tamar-model-client 0.1.26__py3-none-any.whl → 0.1.28__py3-none-any.whl

tamar_model_client/core/http_fallback.py

@@ -7,7 +7,7 @@ connections fail, supporting both synchronous and asynchronous clients.
 
 import json
 import logging
-from typing import Optional, Iterator, AsyncIterator, Dict, Any
+from typing import Optional, Iterator, AsyncIterator, Dict, Any, List
 
 from . import generate_request_id, get_protected_logger
 from ..schemas import ModelRequest, ModelResponse
@@ -16,7 +16,16 @@ logger = get_protected_logger(__name__)
 
 
 class HttpFallbackMixin:
-    """HTTP fallback functionality for synchronous clients"""
+    """HTTP fallback functionality for synchronous clients
+    
+    This mixin requires the following attributes from the host class:
+    - http_fallback_url: str - The HTTP fallback URL (from BaseClient._init_resilient_features)
+    - jwt_token: Optional[str] - JWT token for authentication (from BaseClient)
+    
+    Usage:
+        This mixin should be used with BaseClient or its subclasses that have
+        initialized the resilient features with _init_resilient_features().
+    """
     
     def _ensure_http_client(self) -> None:
         """Ensure HTTP client is initialized"""
@@ -29,7 +38,6 @@ class HttpFallbackMixin:
             
             # Set default headers
             self._http_client.headers.update({
-                'Content-Type': 'application/json',
                 'User-Agent': 'TamarModelClient/1.0'
             })
     
@@ -92,8 +100,13 @@ class HttpFallbackMixin:
     
     def _invoke_http_fallback(self, model_request: ModelRequest, 
                              timeout: Optional[float] = None,
-                             request_id: Optional[str] = None) -> Any:
+                             request_id: Optional[str] = None,
+                             origin_request_id: Optional[str] = None) -> Any:
         """HTTP fallback implementation"""
+        # Check if http_fallback_url is available
+        if not hasattr(self, 'http_fallback_url') or not self.http_fallback_url:
+            raise RuntimeError("HTTP fallback URL not configured. Please set MODEL_CLIENT_HTTP_FALLBACK_URL environment variable.")
+        
         self._ensure_http_client()
         
         # Generate request ID if not provided
@@ -104,10 +117,14 @@ class HttpFallbackMixin:
         logger.warning(
             f"🔻 Using HTTP fallback for request",
             extra={
+                "log_type": "info",
                 "request_id": request_id,
-                "provider": model_request.provider.value,
-                "model": model_request.model,
-                "fallback_url": self.http_fallback_url
+                "data": {
+                    "origin_request_id": origin_request_id,
+                    "provider": model_request.provider.value,
+                    "model": model_request.model,
+                    "fallback_url": self.http_fallback_url
+                }
             }
         )
         
@@ -117,8 +134,18 @@ class HttpFallbackMixin:
         # Construct URL
         url = f"{self.http_fallback_url}/v1/invoke"
         
-        # Build headers with authentication
-        headers = {'X-Request-ID': request_id}
+        # Build headers with authentication and request tracking
+        headers = {
+            'X-Request-ID': request_id,
+            'Content-Type': 'application/json',
+            'User-Agent': 'TamarModelClient/1.0'
+        }
+        
+        # Add origin request ID if provided
+        if origin_request_id:
+            headers['X-Origin-Request-ID'] = origin_request_id
+        
+        # Add JWT authentication if available
         if hasattr(self, 'jwt_token') and self.jwt_token:
             headers['Authorization'] = f'Bearer {self.jwt_token}'
         
@@ -138,10 +165,101 @@ class HttpFallbackMixin:
             # Parse response
             data = response.json()
             return ModelResponse(**data)
+    
+    def _invoke_batch_http_fallback(self, batch_request: 'BatchModelRequest',
+                                   timeout: Optional[float] = None,
+                                   request_id: Optional[str] = None,
+                                   origin_request_id: Optional[str] = None) -> List['BatchModelResponse']:
+        """HTTP batch fallback implementation"""
+        # Import here to avoid circular import
+        from ..schemas import BatchModelRequest, BatchModelResponse
+        
+        # Check if http_fallback_url is available
+        if not hasattr(self, 'http_fallback_url') or not self.http_fallback_url:
+            raise RuntimeError("HTTP fallback URL not configured. Please set MODEL_CLIENT_HTTP_FALLBACK_URL environment variable.")
+        
+        self._ensure_http_client()
+        
+        # Generate request ID if not provided
+        if not request_id:
+            request_id = generate_request_id()
+        
+        # Log fallback usage
+        logger.warning(
+            f"🔻 Using HTTP fallback for batch request",
+            extra={
+                "log_type": "info",
+                "request_id": request_id,
+                "data": {
+                    "origin_request_id": origin_request_id,
+                    "batch_size": len(batch_request.items),
+                    "fallback_url": self.http_fallback_url
+                }
+            }
+        )
+        
+        # Convert to HTTP format
+        http_payload = {
+            "user_context": batch_request.user_context.model_dump(),
+            "items": []
+        }
+        
+        # Convert each item
+        for item in batch_request.items:
+            item_payload = self._convert_to_http_format(item)
+            if hasattr(item, 'custom_id') and item.custom_id:
+                item_payload['custom_id'] = item.custom_id
+            if hasattr(item, 'priority') and item.priority is not None:
+                item_payload['priority'] = item.priority
+            http_payload['items'].append(item_payload)
+        
+        # Construct URL
+        url = f"{self.http_fallback_url}/v1/batch-invoke"
+        
+        # Build headers with authentication and request tracking
+        headers = {
+            'X-Request-ID': request_id,
+            'Content-Type': 'application/json',
+            'User-Agent': 'TamarModelClient/1.0'
+        }
+        
+        # Add origin request ID if provided
+        if origin_request_id:
+            headers['X-Origin-Request-ID'] = origin_request_id
+        
+        # Add JWT authentication if available
+        if hasattr(self, 'jwt_token') and self.jwt_token:
+            headers['Authorization'] = f'Bearer {self.jwt_token}'
+        
+        # Send batch request
+        response = self._http_client.post(
+            url,
+            json=http_payload,
+            timeout=timeout or 120,  # Longer timeout for batch requests
+            headers=headers
+        )
+        response.raise_for_status()
+        
+        # Parse response
+        data = response.json()
+        results = []
+        for item_data in data.get('results', []):
+            results.append(BatchModelResponse(**item_data))
+        
+        return results
 
 
 class AsyncHttpFallbackMixin:
-    """HTTP fallback functionality for asynchronous clients"""
+    """HTTP fallback functionality for asynchronous clients
+    
+    This mixin requires the following attributes from the host class:
+    - http_fallback_url: str - The HTTP fallback URL (from BaseClient._init_resilient_features)
+    - jwt_token: Optional[str] - JWT token for authentication (from BaseClient)
+    
+    Usage:
+        This mixin should be used with BaseClient or its subclasses that have
+        initialized the resilient features with _init_resilient_features().
+    """
     
     async def _ensure_http_client(self) -> None:
         """Ensure async HTTP client is initialized"""
@@ -149,7 +267,6 @@ class AsyncHttpFallbackMixin:
             import aiohttp
             self._http_session = aiohttp.ClientSession(
                 headers={
-                    'Content-Type': 'application/json',
                     'User-Agent': 'AsyncTamarModelClient/1.0'
                 }
             )
@@ -192,8 +309,13 @@ class AsyncHttpFallbackMixin:
     
     async def _invoke_http_fallback(self, model_request: ModelRequest,
                                    timeout: Optional[float] = None,
-                                   request_id: Optional[str] = None) -> Any:
+                                   request_id: Optional[str] = None,
+                                   origin_request_id: Optional[str] = None) -> Any:
         """Async HTTP fallback implementation"""
+        # Check if http_fallback_url is available
+        if not hasattr(self, 'http_fallback_url') or not self.http_fallback_url:
+            raise RuntimeError("HTTP fallback URL not configured. Please set MODEL_CLIENT_HTTP_FALLBACK_URL environment variable.")
+        
         await self._ensure_http_client()
         
         # Generate request ID if not provided
@@ -204,10 +326,14 @@ class AsyncHttpFallbackMixin:
         logger.warning(
             f"🔻 Using HTTP fallback for request",
             extra={
+                "log_type": "info",
                 "request_id": request_id,
-                "provider": model_request.provider.value,
-                "model": model_request.model,
-                "fallback_url": self.http_fallback_url
+                "data": {
+                    "origin_request_id": origin_request_id,
+                    "provider": model_request.provider.value,
+                    "model": model_request.model,
+                    "fallback_url": self.http_fallback_url
+                }
             }
         )
         
@@ -217,8 +343,18 @@ class AsyncHttpFallbackMixin:
         # Construct URL
         url = f"{self.http_fallback_url}/v1/invoke"
         
-        # Build headers with authentication
-        headers = {'X-Request-ID': request_id}
+        # Build headers with authentication and request tracking
+        headers = {
+            'X-Request-ID': request_id,
+            'Content-Type': 'application/json',
+            'User-Agent': 'AsyncTamarModelClient/1.0'
+        }
+        
+        # Add origin request ID if provided
+        if origin_request_id:
+            headers['X-Origin-Request-ID'] = origin_request_id
+        
+        # Add JWT authentication if available
         if hasattr(self, 'jwt_token') and self.jwt_token:
             headers['Authorization'] = f'Bearer {self.jwt_token}'
         
@@ -242,6 +378,91 @@ class AsyncHttpFallbackMixin:
                 data = await response.json()
                 return ModelResponse(**data)
     
+    async def _invoke_batch_http_fallback(self, batch_request: 'BatchModelRequest',
+                                         timeout: Optional[float] = None,
+                                         request_id: Optional[str] = None,
+                                         origin_request_id: Optional[str] = None) -> List['BatchModelResponse']:
+        """Async HTTP batch fallback implementation"""
+        # Import here to avoid circular import
+        from ..schemas import BatchModelRequest, BatchModelResponse
+        
+        # Check if http_fallback_url is available
+        if not hasattr(self, 'http_fallback_url') or not self.http_fallback_url:
+            raise RuntimeError("HTTP fallback URL not configured. Please set MODEL_CLIENT_HTTP_FALLBACK_URL environment variable.")
+        
+        await self._ensure_http_client()
+        
+        # Generate request ID if not provided
+        if not request_id:
+            request_id = generate_request_id()
+        
+        # Log fallback usage
+        logger.warning(
+            f"🔻 Using HTTP fallback for batch request",
+            extra={
+                "log_type": "info",
+                "request_id": request_id,
+                "data": {
+                    "origin_request_id": origin_request_id,
+                    "batch_size": len(batch_request.items),
+                    "fallback_url": self.http_fallback_url
+                }
+            }
+        )
+        
+        # Convert to HTTP format
+        http_payload = {
+            "user_context": batch_request.user_context.model_dump(),
+            "items": []
+        }
+        
+        # Convert each item
+        for item in batch_request.items:
+            item_payload = self._convert_to_http_format(item)
+            if hasattr(item, 'custom_id') and item.custom_id:
+                item_payload['custom_id'] = item.custom_id
+            if hasattr(item, 'priority') and item.priority is not None:
+                item_payload['priority'] = item.priority
+            http_payload['items'].append(item_payload)
+        
+        # Construct URL
+        url = f"{self.http_fallback_url}/v1/batch-invoke"
+        
+        # Build headers with authentication and request tracking
+        headers = {
+            'X-Request-ID': request_id,
+            'Content-Type': 'application/json',
+            'User-Agent': 'AsyncTamarModelClient/1.0'
+        }
+        
+        # Add origin request ID if provided
+        if origin_request_id:
+            headers['X-Origin-Request-ID'] = origin_request_id
+        
+        # Add JWT authentication if available
+        if hasattr(self, 'jwt_token') and self.jwt_token:
+            headers['Authorization'] = f'Bearer {self.jwt_token}'
+        
+        # Send batch request
+        import aiohttp
+        timeout_obj = aiohttp.ClientTimeout(total=timeout or 120) if timeout else None
+        
+        async with self._http_session.post(
+            url,
+            json=http_payload,
+            timeout=timeout_obj,
+            headers=headers
+        ) as response:
+            response.raise_for_status()
+            
+            # Parse response
+            data = await response.json()
+            results = []
+            for item_data in data.get('results', []):
+                results.append(BatchModelResponse(**item_data))
+            
+            return results
+    
     async def _cleanup_http_session(self) -> None:
         """Clean up HTTP session"""
         if hasattr(self, '_http_session') and self._http_session:

tamar_model_client/core/logging_setup.py

@@ -10,7 +10,7 @@ import threading
 from typing import Optional, Dict
 
 from ..json_formatter import JSONFormatter
-from .utils import get_request_id
+from .utils import get_request_id, get_origin_request_id
 
 # gRPC 消息长度限制（32位系统兼容）
 MAX_MESSAGE_LENGTH = 2 ** 31 - 1
@@ -45,6 +45,20 @@ class RequestIdFilter(logging.Filter):
         """
         # 从 ContextVar 中获取当前的 request_id
         record.request_id = get_request_id()
+        
+        # 添加 origin_request_id 到 data 字段
+        origin_request_id = get_origin_request_id()
+        if origin_request_id:
+            # 确保 data 字段存在且是字典类型
+            if not hasattr(record, 'data'):
+                record.data = {}
+            elif record.data is None:
+                record.data = {}
+            elif isinstance(record.data, dict):
+                # 只有在 data 是字典且没有 origin_request_id 时才添加
+                if 'origin_request_id' not in record.data:
+                    record.data['origin_request_id'] = origin_request_id
+            
         return True
 
 

tamar_model_client/core/request_id_manager.py

@@ -0,0 +1,112 @@
+"""
+Request ID 管理器
+
+管理 request_id 的生成和追踪，支持为同一个原始 request_id 生成带序号的组合 ID。
+"""
+
+import threading
+import time
+from typing import Dict, Tuple, Optional
+
+
+class RequestIdManager:
+    """
+    管理 request_id 的生成和追踪
+    
+    为同一个原始 request_id 生成带序号的组合 ID，如：
+    - 原始 ID: abc-123
+    - 第一次调用: abc-123-1
+    - 第二次调用: abc-123-2
+    
+    包含自动清理机制，避免内存泄漏。
+    """
+    
+    def __init__(self, ttl_seconds: int = 3600):
+        """
+        初始化 RequestIdManager
+        
+        Args:
+            ttl_seconds: 计数器的生存时间（秒），默认 1 小时
+        """
+        self._counters: Dict[str, Dict[str, any]] = {}  # {origin_id: {'count': int, 'last_used': float}}
+        self._lock = threading.Lock()
+        self._ttl = ttl_seconds
+        self._last_cleanup = time.time()
+        self._cleanup_interval = 300  # 每 5 分钟执行一次清理
+        
+    def get_composite_id(self, origin_id: str) -> Tuple[str, str]:
+        """
+        获取组合的 request_id
+        
+        Args:
+            origin_id: 原始的 request_id
+            
+        Returns:
+            tuple: (composite_request_id, origin_request_id)
+                - composite_request_id: 带序号的组合 ID，如 "abc-123-1"
+                - origin_request_id: 原始 ID，如 "abc-123"
+        """
+        with self._lock:
+            current_time = time.time()
+            
+            # 定期清理过期的计数器
+            if current_time - self._last_cleanup > self._cleanup_interval:
+                self._cleanup_expired(current_time)
+                self._last_cleanup = current_time
+            
+            # 获取或初始化计数器
+            if origin_id not in self._counters:
+                self._counters[origin_id] = {
+                    'count': 0,
+                    'last_used': current_time
+                }
+            
+            # 递增计数
+            self._counters[origin_id]['count'] += 1
+            self._counters[origin_id]['last_used'] = current_time
+            
+            composite_id = f"{origin_id}-{self._counters[origin_id]['count']}"
+            return composite_id, origin_id
+    
+    def _cleanup_expired(self, current_time: float):
+        """
+        清理过期的计数器
+        
+        Args:
+            current_time: 当前时间戳
+        """
+        expired_ids = [
+            origin_id for origin_id, info in self._counters.items()
+            if current_time - info['last_used'] > self._ttl
+        ]
+        
+        for origin_id in expired_ids:
+            del self._counters[origin_id]
+            
+        # 如果计数器数量过多，保留最近使用的一半
+        if len(self._counters) > 1000:
+            sorted_items = sorted(
+                self._counters.items(),
+                key=lambda x: x[1]['last_used'],
+                reverse=True
+            )[:500]
+            self._counters = dict(sorted_items)
+    
+    def get_stats(self) -> Dict[str, any]:
+        """
+        获取统计信息
+        
+        Returns:
+            dict: 包含计数器数量等统计信息
+        """
+        with self._lock:
+            return {
+                'total_counters': len(self._counters),
+                'ttl_seconds': self._ttl,
+                'cleanup_interval': self._cleanup_interval
+            }
+    
+    def clear(self):
+        """清空所有计数器"""
+        with self._lock:
+            self._counters.clear()

tamar_model_client/core/utils.py

@@ -15,6 +15,7 @@ from pydantic import BaseModel
 
 # 使用 contextvars 管理请求ID，支持异步和同步上下文中的请求追踪
 _request_id: ContextVar[str] = ContextVar('request_id', default='-')
+_origin_request_id: ContextVar[str] = ContextVar('origin_request_id', default=None)
 
 
 def is_effective_value(value) -> bool:
@@ -168,4 +169,29 @@ def get_request_id() -> str:
     Returns:
         str: 当前的请求ID或默认值
     """
-    return _request_id.get()
+    return _request_id.get()
+
+
+def set_origin_request_id(origin_request_id: str):
+    """
+    设置当前上下文的原始请求ID
+    
+    在 ContextVar 中设置原始请求ID，使得在整个异步调用链中
+    都能访问到同一个原始请求ID，便于追踪请求来源。
+    
+    Args:
+        origin_request_id: 要设置的原始请求ID字符串
+    """
+    _origin_request_id.set(origin_request_id)
+
+
+def get_origin_request_id() -> str:
+    """
+    获取当前上下文的原始请求ID
+    
+    从 ContextVar 中获取当前的原始请求ID，如果没有设置则返回 None
+    
+    Returns:
+        str: 当前的原始请求ID或 None
+    """
+    return _origin_request_id.get()

tamar_model_client/error_handler.py

@@ -230,19 +230,106 @@ class EnhancedRetryHandler:
             except (grpc.RpcError, grpc.aio.AioRpcError) as e:
                 # 创建错误上下文
                 error_context = ErrorContext(e, context)
+                current_duration = time.time() - method_start_time
+                context['duration'] = current_duration
 
                 # 判断是否可以重试
-                if not self._should_retry(e, attempt):
+                should_retry = self._should_retry(e, attempt)
+                
+                # 检查是否应该尝试快速降级（需要从外部注入client引用）
+                should_try_fallback = False
+                if hasattr(self.error_handler, 'client') and hasattr(self.error_handler.client, '_should_try_fallback'):
+                    should_try_fallback = self.error_handler.client._should_try_fallback(e.code(), attempt)
+                
+                if should_try_fallback:
+                    # 尝试快速降级到HTTP
+                    logger.warning(
+                        f"🚀 Fast fallback triggered for {e.code().name} after {attempt + 1} attempts",
+                        extra={
+                            "log_type": "fast_fallback",
+                            "request_id": error_context.request_id,
+                            "data": {
+                                "error_code": e.code().name,
+                                "attempt": attempt,
+                                "fallback_reason": "immediate" if hasattr(self.error_handler.client, 'immediate_fallback_errors') and e.code() in self.error_handler.client.immediate_fallback_errors else "after_retries"
+                            }
+                        }
+                    )
+                    
+                    try:
+                        # 尝试HTTP降级（需要从context获取必要参数）
+                        if hasattr(self.error_handler, 'client'):
+                            # 检查是否是批量请求
+                            if hasattr(self.error_handler.client, '_current_batch_request'):
+                                batch_request = self.error_handler.client._current_batch_request
+                                origin_request_id = getattr(self.error_handler.client, '_current_origin_request_id', None)
+                                timeout = context.get('timeout')
+                                request_id = context.get('request_id')
+                                
+                                # 尝试批量HTTP降级
+                                result = await self.error_handler.client._invoke_batch_http_fallback(batch_request, timeout, request_id, origin_request_id)
+                            elif hasattr(self.error_handler.client, '_current_model_request'):
+                                model_request = self.error_handler.client._current_model_request
+                                origin_request_id = getattr(self.error_handler.client, '_current_origin_request_id', None)
+                                timeout = context.get('timeout')
+                                request_id = context.get('request_id')
+                                
+                                # 尝试HTTP降级
+                                result = await self.error_handler.client._invoke_http_fallback(model_request, timeout, request_id, origin_request_id)
+                            
+                            logger.info(
+                                f"✅ Fast fallback to HTTP succeeded",
+                                extra={
+                                    "log_type": "fast_fallback_success",
+                                    "request_id": request_id,
+                                    "data": {
+                                        "grpc_attempts": attempt + 1,
+                                        "fallback_duration": time.time() - method_start_time
+                                    }
+                                }
+                            )
+                            
+                            return result
+                    except Exception as fallback_error:
+                        # 降级失败，记录日志但继续原有重试逻辑
+                        logger.warning(
+                            f"⚠️ Fast fallback to HTTP failed: {str(fallback_error)}",
+                            extra={
+                                "log_type": "fast_fallback_failed",
+                                "request_id": error_context.request_id,
+                                "data": {
+                                    "fallback_error": str(fallback_error),
+                                    "will_continue_grpc_retry": should_retry and attempt < self.max_retries
+                                }
+                            }
+                        )
+
+                if not should_retry:
                     # 不可重试或已达到最大重试次数
-                    current_duration = time.time() - method_start_time
-                    context['duration'] = current_duration
+                    # 记录最终失败日志
+                    log_data = {
+                        "log_type": "info",
+                        "request_id": error_context.request_id,
+                        "data": {
+                            "error_code": error_context.error_code.name if error_context.error_code else 'UNKNOWN',
+                            "error_message": error_context.error_message,
+                            "retry_count": attempt,
+                            "max_retries": self.max_retries,
+                            "category": error_context._get_error_category(),
+                            "is_retryable": False,
+                            "method": error_context.method,
+                            "final_failure": True
+                        },
+                        "duration": current_duration
+                    }
+                    logger.warning(
+                        f"Final attempt {attempt + 1}/{self.max_retries + 1} failed: {e.code()} (no more retries)",
+                        extra=log_data
+                    )
                     last_exception = self.error_handler.handle_error(e, context)
                     break
 
-                # 计算当前耗时
-                current_duration = time.time() - method_start_time
-
-                # 记录重试日志
+                # 可以重试，记录重试日志
                 log_data = {
                     "log_type": "info",
                     "request_id": error_context.request_id,
@@ -252,13 +339,15 @@ class EnhancedRetryHandler:
                         "retry_count": attempt,
                         "max_retries": self.max_retries,
                         "category": error_context._get_error_category(),
-                        "is_retryable": True,  # 既然在重试，说明是可重试的
-                        "method": error_context.method
+                        "is_retryable": True,
+                        "method": error_context.method,
+                        "will_retry": True,
+                        "fallback_attempted": should_try_fallback
                     },
                     "duration": current_duration
                 }
                 logger.warning(
-                    f"Attempt {attempt + 1}/{self.max_retries + 1} failed: {e.code()}",
+                    f"Attempt {attempt + 1}/{self.max_retries + 1} failed: {e.code()} (will retry)",
                     extra=log_data
                 )
 
@@ -267,8 +356,8 @@ class EnhancedRetryHandler:
                     delay = self._calculate_backoff(attempt)
                     await asyncio.sleep(delay)
 
-                context['duration'] = current_duration
-                last_exception = self.error_handler.handle_error(e, context)
+                # 保存异常，以备后续使用
+                last_exception = e
 
             except Exception as e:
                 # 非 gRPC 错误，直接包装抛出
@@ -280,7 +369,11 @@ class EnhancedRetryHandler:
 
         # 抛出最后的异常
         if last_exception:
-            raise last_exception
+            if isinstance(last_exception, TamarModelException):
+                raise last_exception
+            else:
+                # 对于原始的 gRPC 异常，需要包装
+                raise self.error_handler.handle_error(last_exception, context)
         else:
             raise TamarModelException("Unknown error occurred")