tamar-model-client 0.1.27__tar.gz → 0.1.28__tar.gz

{tamar_model_client-0.1.27 → tamar_model_client-0.1.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tamar-model-client
-Version: 0.1.27
+Version: 0.1.28
 Summary: A Python SDK for interacting with the Model Manager gRPC service
 Home-page: http://gitlab.tamaredge.top/project-tap/AgentOS/model-manager-client
 Author: Oscar Ou
@@ -18,6 +18,8 @@ Requires-Dist: PyJWT
 Requires-Dist: nest_asyncio
 Requires-Dist: openai
 Requires-Dist: google-genai
+Requires-Dist: requests>=2.25.0
+Requires-Dist: aiohttp>=3.7.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -65,6 +67,8 @@ Dynamic: summary
 - 🔄 **自动重试** 指数退避策略
 
 ### 🛡️ 生产级特性
+- 🛡️ **熔断降级** 服务故障时自动切换到 HTTP
+- 🚀 **快速降级** 失败立即降级，最大化成功率
 - 🔐 **JWT 认证** 安全可靠
 - 📊 **使用量追踪** Token 统计与成本计算
 - 🆔 **请求追踪** 唯一 request_id
@@ -87,7 +91,14 @@ pip install tamar-model-client
 
 - Python ≥ 3.8
 - 支持 Windows / Linux / macOS
-- 依赖项会自动安装（grpcio, pydantic, python-dotenv 等）
+- 依赖项会自动安装（包括以下核心库）：
+  - `grpcio>=1.67.1` - gRPC 通信协议
+  - `pydantic` - 数据验证和序列化
+  - `PyJWT` - JWT 认证
+  - `requests>=2.25.0` - HTTP 降级功能（同步）
+  - `aiohttp>=3.7.0` - HTTP 降级功能（异步）
+  - `openai` - OpenAI 服务商支持
+  - `google-genai` - Google AI 服务商支持
 
 ## 🏗️ 项目架构
 
@@ -339,7 +350,7 @@ async def main():
     )
 
     # 发送请求并获取响应
-    async for r in await client.invoke(model_request):
+    async for r in await client.invoke(request_data):
         if r.error:
             print(f"错误: {r.error}")
         else:
@@ -587,6 +598,62 @@ metrics = client.get_resilient_metrics()
 # }
 ```
 
+### 🚀 快速降级功能（用户体验优化）
+
+在传统的熔断降级基础上，SDK 新增了快速降级功能，进一步提升用户体验：
+
+#### 传统降级 vs 快速降级
+
+**传统模式**：
+```
+gRPC请求 → 失败 → 重试1 → 失败 → 重试2 → 失败 → ... → 重试N → 失败 → HTTP降级
+耗时：(重试次数 × 退避时间) + 降级时间  // 可能需要十几秒
+```
+
+**快速降级模式**：
+```
+gRPC请求 → 失败 → 立即HTTP降级 (或重试1次后降级)
+耗时：降级时间  // 通常1-2秒内完成
+```
+
+#### 降级策略配置
+
+- **立即降级错误**：`UNAVAILABLE`, `DEADLINE_EXCEEDED`, `CANCELLED` (网络问题)
+- **延迟降级错误**：其他错误重试指定次数后降级
+- **永不降级错误**：`UNAUTHENTICATED`, `PERMISSION_DENIED` (客户端问题)
+
+#### 使用示例
+
+```python
+from tamar_model_client import TamarModelClient
+
+# 启用快速降级（通过环境变量）
+# MODEL_CLIENT_FAST_FALLBACK_ENABLED=true
+# MODEL_CLIENT_FALLBACK_AFTER_RETRIES=1
+
+client = TamarModelClient()
+
+# 正常使用，快速降级对用户透明
+response = client.invoke(request)
+# 如果gRPC不可用，会在1-2秒内自动切换到HTTP并返回结果
+```
+
+#### 配置选项详解
+
+```bash
+# 启用快速降级（默认开启）
+MODEL_CLIENT_FAST_FALLBACK_ENABLED=true
+
+# 非立即降级的错误，重试多少次后降级（默认1次）
+MODEL_CLIENT_FALLBACK_AFTER_RETRIES=1
+
+# 网络错误立即降级（默认配置）
+MODEL_CLIENT_IMMEDIATE_FALLBACK_ERRORS=UNAVAILABLE,DEADLINE_EXCEEDED,CANCELLED
+
+# 认证错误永不降级（避免无效降级）
+MODEL_CLIENT_NEVER_FALLBACK_ERRORS=UNAUTHENTICATED,PERMISSION_DENIED,INVALID_ARGUMENT
+```
+
 ### ⚠️ 注意事项
 
 1. **参数说明**
@@ -614,6 +681,11 @@ export MODEL_MANAGER_SERVER_GRPC_USE_TLS="false"
 export MODEL_MANAGER_SERVER_GRPC_DEFAULT_AUTHORITY="localhost"
 export MODEL_MANAGER_SERVER_GRPC_MAX_RETRIES="5"
 export MODEL_MANAGER_SERVER_GRPC_RETRY_DELAY="1.5"
+
+# 快速降级配置（可选，优化用户体验）
+export MODEL_CLIENT_FAST_FALLBACK_ENABLED="true"
+export MODEL_CLIENT_HTTP_FALLBACK_URL="http://localhost:8080"
+export MODEL_CLIENT_FALLBACK_AFTER_RETRIES="1"
 ```
 
 或者本地 `.env` 文件
@@ -667,6 +739,27 @@ MODEL_CLIENT_CIRCUIT_BREAKER_THRESHOLD=5
 
 # 熔断器恢复超时（秒，熔断后多久尝试恢复，默认 60）
 MODEL_CLIENT_CIRCUIT_BREAKER_TIMEOUT=60
+
+
+# ========================
+# 🚀 快速降级配置（可选，优化体验）
+# ========================
+
+# 是否启用快速降级功能（默认 true）
+# 启用后，gRPC 请求失败时会立即尝试 HTTP 降级，而不是等待所有重试完成
+MODEL_CLIENT_FAST_FALLBACK_ENABLED=true
+
+# 降级前的最大 gRPC 重试次数（默认 1）
+# 对于非立即降级的错误，重试指定次数后才尝试降级
+MODEL_CLIENT_FALLBACK_AFTER_RETRIES=1
+
+# 立即降级的错误类型（逗号分隔，默认网络相关错误）
+# 这些错误类型会在第一次失败后立即尝试降级
+MODEL_CLIENT_IMMEDIATE_FALLBACK_ERRORS=UNAVAILABLE,DEADLINE_EXCEEDED,CANCELLED
+
+# 永不降级的错误类型（逗号分隔，默认认证相关错误）
+# 这些错误类型不会触发降级，通常是客户端问题而非服务不可用
+MODEL_CLIENT_NEVER_FALLBACK_ERRORS=UNAUTHENTICATED,PERMISSION_DENIED,INVALID_ARGUMENT
 ```
 
 加载后，初始化时无需传参：

{tamar_model_client-0.1.27 → tamar_model_client-0.1.28}/README.md

@@ -35,6 +35,8 @@
 - 🔄 **自动重试** 指数退避策略
 
 ### 🛡️ 生产级特性
+- 🛡️ **熔断降级** 服务故障时自动切换到 HTTP
+- 🚀 **快速降级** 失败立即降级，最大化成功率
 - 🔐 **JWT 认证** 安全可靠
 - 📊 **使用量追踪** Token 统计与成本计算
 - 🆔 **请求追踪** 唯一 request_id
@@ -57,7 +59,14 @@ pip install tamar-model-client
 
 - Python ≥ 3.8
 - 支持 Windows / Linux / macOS
-- 依赖项会自动安装（grpcio, pydantic, python-dotenv 等）
+- 依赖项会自动安装（包括以下核心库）：
+  - `grpcio>=1.67.1` - gRPC 通信协议
+  - `pydantic` - 数据验证和序列化
+  - `PyJWT` - JWT 认证
+  - `requests>=2.25.0` - HTTP 降级功能（同步）
+  - `aiohttp>=3.7.0` - HTTP 降级功能（异步）
+  - `openai` - OpenAI 服务商支持
+  - `google-genai` - Google AI 服务商支持
 
 ## 🏗️ 项目架构
 
@@ -309,7 +318,7 @@ async def main():
     )
 
     # 发送请求并获取响应
-    async for r in await client.invoke(model_request):
+    async for r in await client.invoke(request_data):
         if r.error:
             print(f"错误: {r.error}")
         else:
@@ -557,6 +566,62 @@ metrics = client.get_resilient_metrics()
 # }
 ```
 
+### 🚀 快速降级功能（用户体验优化）
+
+在传统的熔断降级基础上，SDK 新增了快速降级功能，进一步提升用户体验：
+
+#### 传统降级 vs 快速降级
+
+**传统模式**：
+```
+gRPC请求 → 失败 → 重试1 → 失败 → 重试2 → 失败 → ... → 重试N → 失败 → HTTP降级
+耗时：(重试次数 × 退避时间) + 降级时间  // 可能需要十几秒
+```
+
+**快速降级模式**：
+```
+gRPC请求 → 失败 → 立即HTTP降级 (或重试1次后降级)
+耗时：降级时间  // 通常1-2秒内完成
+```
+
+#### 降级策略配置
+
+- **立即降级错误**：`UNAVAILABLE`, `DEADLINE_EXCEEDED`, `CANCELLED` (网络问题)
+- **延迟降级错误**：其他错误重试指定次数后降级
+- **永不降级错误**：`UNAUTHENTICATED`, `PERMISSION_DENIED` (客户端问题)
+
+#### 使用示例
+
+```python
+from tamar_model_client import TamarModelClient
+
+# 启用快速降级（通过环境变量）
+# MODEL_CLIENT_FAST_FALLBACK_ENABLED=true
+# MODEL_CLIENT_FALLBACK_AFTER_RETRIES=1
+
+client = TamarModelClient()
+
+# 正常使用，快速降级对用户透明
+response = client.invoke(request)
+# 如果gRPC不可用，会在1-2秒内自动切换到HTTP并返回结果
+```
+
+#### 配置选项详解
+
+```bash
+# 启用快速降级（默认开启）
+MODEL_CLIENT_FAST_FALLBACK_ENABLED=true
+
+# 非立即降级的错误，重试多少次后降级（默认1次）
+MODEL_CLIENT_FALLBACK_AFTER_RETRIES=1
+
+# 网络错误立即降级（默认配置）
+MODEL_CLIENT_IMMEDIATE_FALLBACK_ERRORS=UNAVAILABLE,DEADLINE_EXCEEDED,CANCELLED
+
+# 认证错误永不降级（避免无效降级）
+MODEL_CLIENT_NEVER_FALLBACK_ERRORS=UNAUTHENTICATED,PERMISSION_DENIED,INVALID_ARGUMENT
+```
+
 ### ⚠️ 注意事项
 
 1. **参数说明**
@@ -584,6 +649,11 @@ export MODEL_MANAGER_SERVER_GRPC_USE_TLS="false"
 export MODEL_MANAGER_SERVER_GRPC_DEFAULT_AUTHORITY="localhost"
 export MODEL_MANAGER_SERVER_GRPC_MAX_RETRIES="5"
 export MODEL_MANAGER_SERVER_GRPC_RETRY_DELAY="1.5"
+
+# 快速降级配置（可选，优化用户体验）
+export MODEL_CLIENT_FAST_FALLBACK_ENABLED="true"
+export MODEL_CLIENT_HTTP_FALLBACK_URL="http://localhost:8080"
+export MODEL_CLIENT_FALLBACK_AFTER_RETRIES="1"
 ```
 
 或者本地 `.env` 文件
@@ -637,6 +707,27 @@ MODEL_CLIENT_CIRCUIT_BREAKER_THRESHOLD=5
 
 # 熔断器恢复超时（秒，熔断后多久尝试恢复，默认 60）
 MODEL_CLIENT_CIRCUIT_BREAKER_TIMEOUT=60
+
+
+# ========================
+# 🚀 快速降级配置（可选，优化体验）
+# ========================
+
+# 是否启用快速降级功能（默认 true）
+# 启用后，gRPC 请求失败时会立即尝试 HTTP 降级，而不是等待所有重试完成
+MODEL_CLIENT_FAST_FALLBACK_ENABLED=true
+
+# 降级前的最大 gRPC 重试次数（默认 1）
+# 对于非立即降级的错误，重试指定次数后才尝试降级
+MODEL_CLIENT_FALLBACK_AFTER_RETRIES=1
+
+# 立即降级的错误类型（逗号分隔，默认网络相关错误）
+# 这些错误类型会在第一次失败后立即尝试降级
+MODEL_CLIENT_IMMEDIATE_FALLBACK_ERRORS=UNAVAILABLE,DEADLINE_EXCEEDED,CANCELLED
+
+# 永不降级的错误类型（逗号分隔，默认认证相关错误）
+# 这些错误类型不会触发降级，通常是客户端问题而非服务不可用
+MODEL_CLIENT_NEVER_FALLBACK_ERRORS=UNAUTHENTICATED,PERMISSION_DENIED,INVALID_ARGUMENT
 ```
 
 加载后，初始化时无需传参：

{tamar_model_client-0.1.27 → tamar_model_client-0.1.28}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="tamar-model-client",
-    version="0.1.27",
+    version="0.1.28",
     description="A Python SDK for interacting with the Model Manager gRPC service",
     author="Oscar Ou",
     author_email="oscar.ou@tamaredge.ai",
@@ -19,6 +19,8 @@ setup(
         "nest_asyncio",
         "openai",
         "google-genai",
+        "requests>=2.25.0",  # HTTP降级功能（同步）
+        "aiohttp>=3.7.0",    # HTTP降级功能（异步）
     ],
     long_description=open("README.md", encoding="utf-8").read(),
     long_description_content_type="text/markdown",

{tamar_model_client-0.1.27 → tamar_model_client-0.1.28}/tamar_model_client/async_client.py

@@ -32,6 +32,7 @@ from grpc import RpcError
 from .core import (
     generate_request_id,
     set_request_id,
+    set_origin_request_id,
     get_protected_logger,
     MAX_MESSAGE_LENGTH, 
     get_request_id,
@@ -113,6 +114,9 @@ class AsyncTamarModelClient(BaseClient, AsyncHttpFallbackMixin):
             base_delay=self.retry_delay
         )
         
+        # 设置client引用，用于快速降级
+        self.retry_handler.error_handler.client = self
+        
         # 注册退出时的清理函数
         atexit.register(self._cleanup_atexit)
 
@@ -739,7 +743,12 @@ class AsyncTamarModelClient(BaseClient, AsyncHttpFallbackMixin):
         if self.resilient_enabled and self.circuit_breaker and self.circuit_breaker.is_open:
             if self.http_fallback_url:
                 logger.warning("🔻 Circuit breaker is OPEN, using HTTP fallback")
-                return await self._invoke_http_fallback(model_request, timeout, request_id)
+                # 在这里还没有计算origin_request_id，所以先计算
+                temp_origin_request_id = None
+                temp_request_id = request_id
+                if request_id:
+                    temp_request_id, temp_origin_request_id = self._request_id_manager.get_composite_id(request_id)
+                return await self._invoke_http_fallback(model_request, timeout, temp_request_id, temp_origin_request_id)
                 
         await self._ensure_initialized()
 
@@ -759,6 +768,8 @@ class AsyncTamarModelClient(BaseClient, AsyncHttpFallbackMixin):
             request_id = generate_request_id()
             
         set_request_id(request_id)
+        if origin_request_id:
+            set_origin_request_id(origin_request_id)
         metadata = self._build_auth_metadata(request_id, origin_request_id)
 
         # 构建日志数据
@@ -806,7 +817,17 @@ class AsyncTamarModelClient(BaseClient, AsyncHttpFallbackMixin):
                 # 对于流式响应，直接返回带日志记录的包装器
                 return self._stream_with_logging(request, metadata, invoke_timeout, start_time, model_request)
             else:
-                result = await self._retry_request(self._invoke_request, request, metadata, invoke_timeout, request_id=request_id)
+                # 存储model_request和origin_request_id供重试方法使用
+                self._current_model_request = model_request
+                self._current_origin_request_id = origin_request_id
+                try:
+                    result = await self._retry_request(self._invoke_request, request, metadata, invoke_timeout, request_id=request_id)
+                finally:
+                    # 清理临时存储
+                    if hasattr(self, '_current_model_request'):
+                        delattr(self, '_current_model_request')
+                    if hasattr(self, '_current_origin_request_id'):
+                        delattr(self, '_current_origin_request_id')
 
                 # 记录非流式响应的成功日志
                 duration = time.time() - start_time
@@ -854,16 +875,11 @@ class AsyncTamarModelClient(BaseClient, AsyncHttpFallbackMixin):
             if isinstance(e, grpc.RpcError):
                 self._record_channel_error(e)
             
-            # 记录失败并尝试降级（如果启用了熔断）
+            # 记录失败（如果启用了熔断）
             if self.resilient_enabled and self.circuit_breaker:
                 # 将错误码传递给熔断器，用于智能失败统计
                 error_code = e.code() if hasattr(e, 'code') else None
                 self.circuit_breaker.record_failure(error_code)
-                
-                # 如果可以降级，则降级
-                if self.http_fallback_url and self.circuit_breaker.should_fallback():
-                    logger.warning(f"🔻 gRPC failed, falling back to HTTP: {str(e)}")
-                    return await self._invoke_http_fallback(model_request, timeout, request_id)
             
             raise e
         except Exception as e:
@@ -893,6 +909,17 @@ class AsyncTamarModelClient(BaseClient, AsyncHttpFallbackMixin):
         Returns:
             BatchModelResponse: 批量请求的结果
         """
+        # 如果启用了熔断且熔断器打开，直接走 HTTP
+        if self.resilient_enabled and self.circuit_breaker and self.circuit_breaker.is_open:
+            if self.http_fallback_url:
+                logger.warning("🔻 Circuit breaker is OPEN, using HTTP fallback for batch request")
+                # 在这里还没有计算origin_request_id，所以先计算
+                temp_origin_request_id = None
+                temp_request_id = request_id
+                if request_id:
+                    temp_request_id, temp_origin_request_id = self._request_id_manager.get_composite_id(request_id)
+                return await self._invoke_batch_http_fallback(batch_request_model, timeout, temp_request_id, temp_origin_request_id)
+                
         await self._ensure_initialized()
 
         if not self.default_payload:
@@ -911,6 +938,8 @@ class AsyncTamarModelClient(BaseClient, AsyncHttpFallbackMixin):
             request_id = generate_request_id()
             
         set_request_id(request_id)
+        if origin_request_id:
+            set_origin_request_id(origin_request_id)
         metadata = self._build_auth_metadata(request_id, origin_request_id)
 
         # 构建日志数据
@@ -957,6 +986,11 @@ class AsyncTamarModelClient(BaseClient, AsyncHttpFallbackMixin):
 
         try:
             invoke_timeout = timeout or self.default_invoke_timeout
+            
+            # 保存批量请求信息用于降级
+            self._current_batch_request = batch_request_model
+            self._current_origin_request_id = origin_request_id
+            
             batch_response = await self._retry_request(
                 self.stub.BatchInvoke,
                 batch_request,

{tamar_model_client-0.1.27 → tamar_model_client-0.1.28}/tamar_model_client/circuit_breaker.py

@@ -101,9 +101,12 @@ class CircuitBreaker:
                     logger.warning(
                         f"🔻 Circuit breaker OPENED after {self.failure_count} failures",
                         extra={
-                            "failure_count": self.failure_count,
-                            "threshold": self.failure_threshold,
-                            "trigger_error": error_code.name if error_code else "unknown"
+                            "log_type": "info",
+                            "data": {
+                                "failure_count": self.failure_count,
+                                "threshold": self.failure_threshold,
+                                "trigger_error": error_code.name if error_code else "unknown"
+                            }
                         }
                     )
     

{tamar_model_client-0.1.27 → tamar_model_client-0.1.28}/tamar_model_client/core/__init__.py

@@ -10,7 +10,9 @@ from .utils import (
     remove_none_from_dict,
     generate_request_id,
     set_request_id,
-    get_request_id
+    get_request_id,
+    set_origin_request_id,
+    get_origin_request_id
 )
 
 from .logging_setup import (
@@ -32,6 +34,8 @@ __all__ = [
     'generate_request_id',
     'set_request_id',
     'get_request_id',
+    'set_origin_request_id',
+    'get_origin_request_id',
     # Logging
     'setup_logger',
     'RequestIdFilter',