tamar-model-client 0.1.19__py3-none-any.whl → 0.1.20__py3-none-any.whl

tamar_model_client/async_client.py

@@ -1,273 +1,180 @@
+"""
+Tamar Model Client 异步客户端实现
+
+本模块实现了异步的 gRPC 客户端，用于与 Model Manager Server 进行通信。
+支持单个请求、批量请求、流式响应等功能，并提供了完整的错误处理和重试机制。
+
+主要功能：
+- 异步 gRPC 通信
+- JWT 认证
+- 自动重试和错误处理
+- 流式响应支持
+- 连接池管理
+- 详细的日志记录
+
+使用示例：
+    async with AsyncTamarModelClient() as client:
+        request = ModelRequest(...)
+        response = await client.invoke(request)
+"""
+
 import asyncio
 import atexit
-import base64
 import json
 import logging
-import os
 import time
-import uuid
-from contextvars import ContextVar
+from typing import Optional, AsyncIterator, Union
 
 import grpc
-from typing import Optional, AsyncIterator, Union, Iterable
-
-from openai import NOT_GIVEN
-from pydantic import BaseModel
-
-from .auth import JWTAuthHandler
+from grpc import RpcError
+
+from .core import (
+    generate_request_id,
+    set_request_id,
+    setup_logger,
+    MAX_MESSAGE_LENGTH
+)
+from .core.base_client import BaseClient
+from .core.request_builder import RequestBuilder
+from .core.response_handler import ResponseHandler
 from .enums import ProviderType, InvokeType
-from .exceptions import ConnectionError
+from .exceptions import ConnectionError, TamarModelException
+from .error_handler import EnhancedRetryHandler
 from .schemas import ModelRequest, ModelResponse, BatchModelRequest, BatchModelResponse
 from .generated import model_service_pb2, model_service_pb2_grpc
-from .schemas.inputs import GoogleGenAiInput, OpenAIResponsesInput, OpenAIChatCompletionsInput, \
-    GoogleVertexAIImagesInput, OpenAIImagesInput, OpenAIImagesEditInput
-from .json_formatter import JSONFormatter
-
-logger = logging.getLogger(__name__)
-
-# 使用 contextvars 管理请求ID
-_request_id: ContextVar[str] = ContextVar('request_id', default='-')
-
-
-class RequestIdFilter(logging.Filter):
-    """自定义日志过滤器，向日志中添加 request_id"""
-
-    def filter(self, record):
-        # 从 ContextVar 中获取当前的 request_id
-        record.request_id = _request_id.get()
-        return True
-
-
-if not logger.hasHandlers():
-    # 创建日志处理器，输出到控制台
-    console_handler = logging.StreamHandler()
-
-    # 使用 JSON 格式化器
-    formatter = JSONFormatter()
-    console_handler.setFormatter(formatter)
-
-    # 为当前记录器添加处理器
-    logger.addHandler(console_handler)
-
-    # 设置日志级别
-    logger.setLevel(logging.INFO)
-
-    # 将自定义的 RequestIdFilter 添加到 logger 中
-    logger.addFilter(RequestIdFilter())
 
-MAX_MESSAGE_LENGTH = 2 ** 31 - 1  # 对于32位系统
+# 配置日志记录器
+logger = setup_logger(__name__)
 
 
-def is_effective_value(value) -> bool:
+class AsyncTamarModelClient(BaseClient):
     """
-    递归判断value是否是有意义的有效值
+    Tamar Model Client 异步客户端
+    
+    提供与 Model Manager Server 的异步通信能力，支持：
+    - 单个和批量模型调用
+    - 流式和非流式响应
+    - 自动重试和错误恢复
+    - JWT 认证
+    - 连接池管理
+    
+    使用示例：
+        # 基本用法
+        client = AsyncTamarModelClient()
+        await client.connect()
+        
+        request = ModelRequest(...)
+        response = await client.invoke(request)
+        
+        # 上下文管理器用法（推荐）
+        async with AsyncTamarModelClient() as client:
+            response = await client.invoke(request)
+    
+    环境变量配置：
+        MODEL_MANAGER_SERVER_ADDRESS: gRPC 服务器地址
+        MODEL_MANAGER_SERVER_JWT_SECRET_KEY: JWT 密钥
+        MODEL_MANAGER_SERVER_GRPC_USE_TLS: 是否使用 TLS
+        MODEL_MANAGER_SERVER_GRPC_MAX_RETRIES: 最大重试次数
+        MODEL_MANAGER_SERVER_GRPC_RETRY_DELAY: 重试延迟
     """
-    if value is None or value is NOT_GIVEN:
-        return False
-
-    if isinstance(value, str):
-        return value.strip() != ""
-
-    if isinstance(value, bytes):
-        return len(value) > 0
-
-    if isinstance(value, dict):
-        for v in value.values():
-            if is_effective_value(v):
-                return True
-        return False
-
-    if isinstance(value, list):
-        for item in value:
-            if is_effective_value(item):
-                return True
-        return False
-
-    return True  # 其他类型（int/float/bool）只要不是None就算有效
 
+    def __init__(self, **kwargs):
+        """
+        初始化异步客户端
+        
+        参数继承自 BaseClient，包括：
+        - server_address: gRPC 服务器地址
+        - jwt_secret_key: JWT 签名密钥
+        - jwt_token: 预生成的 JWT 令牌
+        - default_payload: JWT 令牌的默认载荷
+        - token_expires_in: JWT 令牌过期时间
+        - max_retries: 最大重试次数
+        - retry_delay: 初始重试延迟
+        """
+        super().__init__(logger_name=__name__, **kwargs)
+        
+        # === gRPC 通道和连接管理 ===
+        self.channel: Optional[grpc.aio.Channel] = None
+        self.stub: Optional[model_service_pb2_grpc.ModelServiceStub] = None
+        
+        # === 增强的重试处理器 ===
+        self.retry_handler = EnhancedRetryHandler(
+            max_retries=self.max_retries,
+            base_delay=self.retry_delay
+        )
+        
+        # 注册退出时的清理函数
+        atexit.register(self._cleanup_atexit)
 
-def serialize_value(value):
-    """递归处理单个值，处理BaseModel, dict, list, bytes"""
-    if not is_effective_value(value):
-        return None
-    if isinstance(value, BaseModel):
-        return serialize_value(value.model_dump())
-    if hasattr(value, "dict") and callable(value.dict):
-        return serialize_value(value.dict())
-    if isinstance(value, dict):
-        return {k: serialize_value(v) for k, v in value.items()}
-    if isinstance(value, list) or (isinstance(value, Iterable) and not isinstance(value, (str, bytes))):
-        return [serialize_value(v) for v in value]
-    if isinstance(value, bytes):
-        return f"bytes:{base64.b64encode(value).decode('utf-8')}"
-    return value
+    def _cleanup_atexit(self):
+        """程序退出时的清理函数"""
+        if self.channel and not self._closed:
+            try:
+                asyncio.create_task(self.close())
+            except RuntimeError:
+                # 如果事件循环已经关闭，忽略错误
+                pass
 
+    async def close(self):
+        """
+        关闭客户端连接
+        
+        优雅地关闭 gRPC 通道并清理资源。
+        建议在程序结束前调用此方法，或使用上下文管理器自动管理。
+        """
+        if self.channel and not self._closed:
+            await self.channel.close()
+            self._closed = True
+            logger.info("🔒 gRPC channel closed",
+                        extra={"log_type": "info", "data": {"status": "closed"}})
 
-from typing import Any
+    async def __aenter__(self):
+        """异步上下文管理器入口"""
+        await self.connect()
+        return self
 
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """异步上下文管理器出口"""
+        await self.close()
 
-def remove_none_from_dict(data: Any) -> Any:
-    """
-    遍历 dict/list，递归删除 value 为 None 的字段
-    """
-    if isinstance(data, dict):
-        new_dict = {}
-        for key, value in data.items():
-            if value is None:
-                continue
-            cleaned_value = remove_none_from_dict(value)
-            new_dict[key] = cleaned_value
-        return new_dict
-    elif isinstance(data, list):
-        return [remove_none_from_dict(item) for item in data]
-    else:
-        return data
-
-
-def generate_request_id():
-    """生成一个唯一的request_id"""
-    return str(uuid.uuid4())
-
-
-def set_request_id(request_id: str):
-    """设置当前请求的 request_id"""
-    _request_id.set(request_id)
-
-
-class AsyncTamarModelClient:
-    def __init__(
-            self,
-            server_address: Optional[str] = None,
-            jwt_secret_key: Optional[str] = None,
-            jwt_token: Optional[str] = None,
-            default_payload: Optional[dict] = None,
-            token_expires_in: int = 3600,
-            max_retries: Optional[int] = None,  # 最大重试次数
-            retry_delay: Optional[float] = None,  # 初始重试延迟（秒）
-    ):
-        # 服务端地址
-        self.server_address = server_address or os.getenv("MODEL_MANAGER_SERVER_ADDRESS")
-        if not self.server_address:
-            raise ValueError("Server address must be provided via argument or environment variable.")
-        self.default_invoke_timeout = float(os.getenv("MODEL_MANAGER_SERVER_INVOKE_TIMEOUT", 30.0))
-
-        # JWT 配置
-        self.jwt_secret_key = jwt_secret_key or os.getenv("MODEL_MANAGER_SERVER_JWT_SECRET_KEY")
-        self.jwt_handler = JWTAuthHandler(self.jwt_secret_key)
-        self.jwt_token = jwt_token  # 用户传入的 Token（可选）
-        self.default_payload = default_payload
-        self.token_expires_in = token_expires_in
-
-        # === TLS/Authority 配置 ===
-        self.use_tls = os.getenv("MODEL_MANAGER_SERVER_GRPC_USE_TLS", "true").lower() == "true"
-        self.default_authority = os.getenv("MODEL_MANAGER_SERVER_GRPC_DEFAULT_AUTHORITY")
-
-        # === 重试配置 ===
-        self.max_retries = max_retries if max_retries is not None else int(
-            os.getenv("MODEL_MANAGER_SERVER_GRPC_MAX_RETRIES", 3))
-        self.retry_delay = retry_delay if retry_delay is not None else float(
-            os.getenv("MODEL_MANAGER_SERVER_GRPC_RETRY_DELAY", 1.0))
-
-        # === gRPC 通道相关 ===
-        self.channel: Optional[grpc.aio.Channel] = None
-        self.stub: Optional[model_service_pb2_grpc.ModelServiceStub] = None
-        self._closed = False
-        atexit.register(self._safe_sync_close)  # 注册进程退出自动关闭
+    def __enter__(self):
+        """同步上下文管理器入口（不支持）"""
+        raise TypeError("Use 'async with' for AsyncTamarModelClient")
 
-    async def _retry_request(self, func, *args, **kwargs):
-        retry_count = 0
-        while retry_count < self.max_retries:
-            try:
-                return await func(*args, **kwargs)
-            except (grpc.aio.AioRpcError, grpc.RpcError) as e:
-                # 对于取消的情况进行指数退避重试
-                if isinstance(e, grpc.aio.AioRpcError) and e.code() == grpc.StatusCode.CANCELLED:
-                    retry_count += 1
-                    logger.warning(f"⚠️ RPC cancelled, retrying {retry_count}/{self.max_retries}...",
-                                 extra={"log_type": "info", "data": {"retry_count": retry_count, "max_retries": self.max_retries, "error_code": "CANCELLED"}})
-                    if retry_count < self.max_retries:
-                        delay = self.retry_delay * (2 ** (retry_count - 1))
-                        await asyncio.sleep(delay)
-                    else:
-                        logger.error("❌ Max retry reached for CANCELLED",
-                                   extra={"log_type": "info", "data": {"error_code": "CANCELLED", "max_retries_reached": True}})
-                        raise
-                # 针对其他 RPC 错误类型，如暂时的连接问题、服务器超时等
-                elif isinstance(e, grpc.RpcError) and e.code() in {grpc.StatusCode.UNAVAILABLE,
-                                                                   grpc.StatusCode.DEADLINE_EXCEEDED}:
-                    retry_count += 1
-                    logger.warning(f"⚠️ gRPC error {e.code()}, retrying {retry_count}/{self.max_retries}...",
-                                 extra={"log_type": "info", "data": {"retry_count": retry_count, "max_retries": self.max_retries, "error_code": str(e.code())}})
-                    if retry_count < self.max_retries:
-                        delay = self.retry_delay * (2 ** (retry_count - 1))
-                        await asyncio.sleep(delay)
-                    else:
-                        logger.error(f"❌ Max retry reached for {e.code()}",
-                                   extra={"log_type": "info", "data": {"error_code": str(e.code()), "max_retries_reached": True}})
-                        raise
-                else:
-                    logger.error(f"❌ Non-retryable gRPC error: {e}", exc_info=True,
-                               extra={"log_type": "info", "data": {"error_code": str(e.code()) if hasattr(e, 'code') else None, "retryable": False}})
-                    raise
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """同步上下文管理器出口（不支持）"""
+        pass
 
-    async def _retry_request_stream(self, func, *args, **kwargs):
-        retry_count = 0
-        while retry_count < self.max_retries:
-            try:
-                return func(*args, **kwargs)
-            except (grpc.aio.AioRpcError, grpc.RpcError) as e:
-                # 对于取消的情况进行指数退避重试
-                if isinstance(e, grpc.aio.AioRpcError) and e.code() == grpc.StatusCode.CANCELLED:
-                    retry_count += 1
-                    logger.warning(f"⚠️ RPC cancelled, retrying {retry_count}/{self.max_retries}...",
-                                 extra={"log_type": "info", "data": {"retry_count": retry_count, "max_retries": self.max_retries, "error_code": "CANCELLED"}})
-                    if retry_count < self.max_retries:
-                        delay = self.retry_delay * (2 ** (retry_count - 1))
-                        await asyncio.sleep(delay)
-                    else:
-                        logger.error("❌ Max retry reached for CANCELLED",
-                                   extra={"log_type": "info", "data": {"error_code": "CANCELLED", "max_retries_reached": True}})
-                        raise
-                # 针对其他 RPC 错误类型，如暂时的连接问题、服务器超时等
-                elif isinstance(e, grpc.RpcError) and e.code() in {grpc.StatusCode.UNAVAILABLE,
-                                                                   grpc.StatusCode.DEADLINE_EXCEEDED}:
-                    retry_count += 1
-                    logger.warning(f"⚠️ gRPC error {e.code()}, retrying {retry_count}/{self.max_retries}...",
-                                 extra={"log_type": "info", "data": {"retry_count": retry_count, "max_retries": self.max_retries, "error_code": str(e.code())}})
-                    if retry_count < self.max_retries:
-                        delay = self.retry_delay * (2 ** (retry_count - 1))
-                        await asyncio.sleep(delay)
-                    else:
-                        logger.error(f"❌ Max retry reached for {e.code()}",
-                                   extra={"log_type": "info", "data": {"error_code": str(e.code()), "max_retries_reached": True}})
-                        raise
-                else:
-                    logger.error(f"❌ Non-retryable gRPC error: {e}", exc_info=True,
-                               extra={"log_type": "info", "data": {"error_code": str(e.code()) if hasattr(e, 'code') else None, "retryable": False}})
-                    raise
-
-    def _build_auth_metadata(self, request_id: str) -> list:
-        # if not self.jwt_token and self.jwt_handler:
-        # 更改为每次请求都生成一次token
-        metadata = [("x-request-id", request_id)]  # 将 request_id 添加到 headers
-        if self.jwt_handler:
-            self.jwt_token = self.jwt_handler.encode_token(self.default_payload, expires_in=self.token_expires_in)
-            metadata.append(("authorization", f"Bearer {self.jwt_token}"))
-        return metadata
+    async def connect(self):
+        """
+        显式连接到服务器
+        
+        建立与 gRPC 服务器的连接。通常不需要手动调用，
+        因为 invoke 方法会自动确保连接已建立。
+        """
+        await self._ensure_initialized()
 
     async def _ensure_initialized(self):
-        """初始化 gRPC 通道，支持 TLS 与重试机制"""
+        """
+        初始化gRPC通道
+        
+        确保gRPC通道和存根已正确初始化。如果初始化失败，
+        会进行重试，支持TLS配置和完整的keepalive选项。
+        
+        连接配置包括：
+        - 消息大小限制
+        - Keepalive设置（30秒ping间隔，10秒超时）
+        - 连接生命周期管理（1小时最大连接时间）
+        - 性能优化选项（带宽探测、内置重试）
+        
+        Raises:
+            ConnectionError: 当达到最大重试次数仍无法连接时
+        """
         if self.channel and self.stub:
             return
 
         retry_count = 0
-        options = [
-            ('grpc.max_send_message_length', MAX_MESSAGE_LENGTH),
-            ('grpc.max_receive_message_length', MAX_MESSAGE_LENGTH),
-            ('grpc.keepalive_permit_without_calls', True)  # 即使没有活跃请求也保持连接
-        ]
-        if self.default_authority:
-            options.append(("grpc.default_authority", self.default_authority))
+        options = self.build_channel_options()
 
         while retry_count <= self.max_retries:
             try:
@@ -279,60 +186,152 @@ class AsyncTamarModelClient:
                         options=options
                     )
                     logger.info("🔐 Using secure gRPC channel (TLS enabled)",
-                              extra={"log_type": "info", "data": {"tls_enabled": True, "server_address": self.server_address}})
+                                extra={"log_type": "info",
+                                       "data": {"tls_enabled": True, "server_address": self.server_address}})
                 else:
                     self.channel = grpc.aio.insecure_channel(
                         self.server_address,
                         options=options
                     )
                     logger.info("🔓 Using insecure gRPC channel (TLS disabled)",
-                              extra={"log_type": "info", "data": {"tls_enabled": False, "server_address": self.server_address}})
+                                extra={"log_type": "info",
+                                       "data": {"tls_enabled": False, "server_address": self.server_address}})
+                
                 await self.channel.channel_ready()
                 self.stub = model_service_pb2_grpc.ModelServiceStub(self.channel)
                 logger.info(f"✅ gRPC channel initialized to {self.server_address}",
-                          extra={"log_type": "info", "data": {"status": "success", "server_address": self.server_address}})
+                            extra={"log_type": "info",
+                                   "data": {"status": "success", "server_address": self.server_address}})
                 return
+                
             except grpc.FutureTimeoutError as e:
                 logger.error(f"❌ gRPC channel initialization timed out: {str(e)}", exc_info=True,
-                           extra={"log_type": "info", "data": {"error_type": "timeout", "server_address": self.server_address}})
+                             extra={"log_type": "info",
+                                    "data": {"error_type": "timeout", "server_address": self.server_address}})
             except grpc.RpcError as e:
                 logger.error(f"❌ gRPC channel initialization failed: {str(e)}", exc_info=True,
-                           extra={"log_type": "info", "data": {"error_type": "rpc_error", "server_address": self.server_address}})
+                             extra={"log_type": "info",
+                                    "data": {"error_type": "grpc_error", "server_address": self.server_address}})
             except Exception as e:
-                logger.error(f"❌ Unexpected error during channel initialization: {str(e)}", exc_info=True,
-                           extra={"log_type": "info", "data": {"error_type": "unexpected", "server_address": self.server_address}})
-
+                logger.error(f"❌ Unexpected error during gRPC channel initialization: {str(e)}", exc_info=True,
+                             extra={"log_type": "info",
+                                    "data": {"error_type": "unknown", "server_address": self.server_address}})
+            
             retry_count += 1
-            if retry_count > self.max_retries:
-                logger.error(f"❌ Failed to initialize gRPC channel after {self.max_retries} retries.", exc_info=True,
-                           extra={"log_type": "info", "data": {"max_retries_reached": True, "server_address": self.server_address}})
-                raise ConnectionError(f"❌ Failed to initialize gRPC channel after {self.max_retries} retries.")
+            if retry_count <= self.max_retries:
+                await asyncio.sleep(self.retry_delay * retry_count)
 
-            # 指数退避：延迟时间 = retry_delay * (2 ^ (retry_count - 1))
-            delay = self.retry_delay * (2 ** (retry_count - 1))
-            logger.warning(f"🔄 Retrying connection (attempt {retry_count}/{self.max_retries}) after {delay:.2f}s delay...",
-                      extra={"log_type": "info", "data": {"retry_count": retry_count, "max_retries": self.max_retries, "delay": delay}})
-            await asyncio.sleep(delay)
+        raise ConnectionError(f"Failed to connect to {self.server_address} after {self.max_retries} retries")
+
+    async def _retry_request(self, func, *args, **kwargs):
+        """
+        使用增强的重试处理器执行请求
+        
+        Args:
+            func: 要执行的异步函数
+            *args: 函数参数
+            **kwargs: 函数关键字参数
+            
+        Returns:
+            函数执行结果
+            
+        Raises:
+            TamarModelException: 当所有重试都失败时
+        """
+        return await self.retry_handler.execute_with_retry(func, *args, **kwargs)
+
+    async def _retry_request_stream(self, func, *args, **kwargs):
+        """
+        流式请求的重试逻辑
+        
+        对于流式响应，需要特殊的重试处理，因为流不能简单地重新执行。
+        
+        Args:
+            func: 生成流的异步函数
+            *args: 函数参数
+            **kwargs: 函数关键字参数
+            
+        Returns:
+            AsyncIterator: 流式响应迭代器
+        """
+        last_exception = None
+        
+        for attempt in range(self.max_retries + 1):
+            try:
+                # 尝试创建流
+                async for item in func(*args, **kwargs):
+                    yield item
+                return
+                
+            except RpcError as e:
+                last_exception = e
+                if attempt < self.max_retries:
+                    logger.warning(
+                        f"Stream attempt {attempt + 1}/{self.max_retries + 1} failed: {e.code()}",
+                        extra={"retry_count": attempt, "error_code": str(e.code())}
+                    )
+                    await asyncio.sleep(self.retry_delay * (attempt + 1))
+                else:
+                    break
+            except Exception as e:
+                raise TamarModelException(str(e)) from e
+        
+        if last_exception:
+            raise self.error_handler.handle_error(last_exception, {"retry_count": self.max_retries})
+        else:
+            raise TamarModelException("Unknown streaming error occurred")
 
     async def _stream(self, request, metadata, invoke_timeout) -> AsyncIterator[ModelResponse]:
-        async for response in self.stub.Invoke(request, metadata=metadata, timeout=invoke_timeout):
-            yield ModelResponse(
-                content=response.content,
-                usage=json.loads(response.usage) if response.usage else None,
-                error=response.error or None,
-                raw_response=json.loads(response.raw_response) if response.raw_response else None,
-                request_id=response.request_id if response.request_id else None,
-            )
-    
-    async def _stream_with_logging(self, request, metadata, invoke_timeout, start_time, model_request) -> AsyncIterator[ModelResponse]:
-        """流式响应的包装器，用于记录完整的响应日志"""
+        """
+        处理流式响应
+        
+        包含块级超时保护，防止流式响应挂起。
+        
+        Args:
+            request: gRPC 请求对象
+            metadata: 请求元数据
+            invoke_timeout: 总体超时时间
+            
+        Yields:
+            ModelResponse: 流式响应的每个数据块
+            
+        Raises:
+            TimeoutError: 当等待下一个数据块超时时
+        """
+        stream_iter = self.stub.Invoke(request, metadata=metadata, timeout=invoke_timeout).__aiter__()
+        chunk_timeout = 30.0  # 单个数据块的超时时间
+        
+        try:
+            while True:
+                try:
+                    # 对每个数据块的获取进行超时保护
+                    response = await asyncio.wait_for(
+                        stream_iter.__anext__(), 
+                        timeout=chunk_timeout
+                    )
+                    yield ResponseHandler.build_model_response(response)
+                    
+                except asyncio.TimeoutError:
+                    raise TimeoutError(f"流式响应在等待下一个数据块时超时 ({chunk_timeout}s)")
+                    
+                except StopAsyncIteration:
+                    break  # 正常结束
+        except Exception as e:
+            raise
+
+    async def _stream_with_logging(self, request, metadata, invoke_timeout, start_time, model_request) -> AsyncIterator[
+        ModelResponse]:
+        """流式响应的包装器，用于记录完整的响应日志并处理重试"""
         total_content = ""
         final_usage = None
         error_occurred = None
         chunk_count = 0
-        
+
+        # 使用重试逻辑获取流生成器
+        stream_generator = self._retry_request_stream(self._stream, request, metadata, invoke_timeout)
+
         try:
-            async for response in self._stream(request, metadata, invoke_timeout):
+            async for response in stream_generator:
                 chunk_count += 1
                 if response.content:
                     total_content += response.content
@@ -341,26 +340,46 @@ class AsyncTamarModelClient:
                 if response.error:
                     error_occurred = response.error
                 yield response
-            
-            # 流式响应完成，记录成功日志
+
+            # 流式响应完成，记录日志
             duration = time.time() - start_time
-            logger.info(
-                f"✅ Stream completed successfully | chunks: {chunk_count}",
-                extra={
-                    "log_type": "response",
-                    "uri": f"/invoke/{model_request.provider.value}/{model_request.invoke_type.value}",
-                    "duration": duration,
-                    "data": {
-                        "provider": model_request.provider.value,
-                        "invoke_type": model_request.invoke_type.value,
-                        "model": model_request.model,
-                        "stream": True,
-                        "chunks_count": chunk_count,
-                        "total_length": len(total_content),
-                        "usage": final_usage
+            if error_occurred:
+                # 流式响应中包含错误
+                logger.warning(
+                    f"⚠️ Stream completed with errors | chunks: {chunk_count}",
+                    extra={
+                        "log_type": "response",
+                        "uri": f"/invoke/{model_request.provider.value}/{model_request.invoke_type.value}",
+                        "duration": duration,
+                        "data": ResponseHandler.build_log_data(
+                            model_request,
+                            stream_stats={
+                                "chunks_count": chunk_count,
+                                "total_length": len(total_content),
+                                "usage": final_usage,
+                                "error": error_occurred
+                            }
+                        )
                     }
-                }
-            )
+                )
+            else:
+                # 流式响应成功完成
+                logger.info(
+                    f"✅ Stream completed successfully | chunks: {chunk_count}",
+                    extra={
+                        "log_type": "response",
+                        "uri": f"/invoke/{model_request.provider.value}/{model_request.invoke_type.value}",
+                        "duration": duration,
+                        "data": ResponseHandler.build_log_data(
+                            model_request,
+                            stream_stats={
+                                "chunks_count": chunk_count,
+                                "total_length": len(total_content),
+                                "usage": final_usage
+                            }
+                        )
+                    }
+                )
         except Exception as e:
             # 流式响应出错，记录错误日志
             duration = time.time() - start_time
@@ -371,28 +390,22 @@ class AsyncTamarModelClient:
                     "log_type": "response",
                     "uri": f"/invoke/{model_request.provider.value}/{model_request.invoke_type.value}",
                     "duration": duration,
-                    "data": {
-                        "provider": model_request.provider.value,
-                        "invoke_type": model_request.invoke_type.value,
-                        "model": model_request.model,
-                        "stream": True,
-                        "chunks_count": chunk_count,
-                        "error_type": type(e).__name__,
-                        "partial_content_length": len(total_content)
-                    }
+                    "data": ResponseHandler.build_log_data(
+                        model_request,
+                        error=e,
+                        stream_stats={
+                            "chunks_count": chunk_count,
+                            "partial_content_length": len(total_content)
+                        }
+                    )
                 }
             )
             raise
 
     async def _invoke_request(self, request, metadata, invoke_timeout):
+        """执行单个非流式请求"""
         async for response in self.stub.Invoke(request, metadata=metadata, timeout=invoke_timeout):
-            return ModelResponse(
-                content=response.content,
-                usage=json.loads(response.usage) if response.usage else None,
-                error=response.error or None,
-                raw_response=json.loads(response.raw_response) if response.raw_response else None,
-                request_id=response.request_id if response.request_id else None,
-            )
+            return ResponseHandler.build_model_response(response)
 
     async def invoke(self, model_request: ModelRequest, timeout: Optional[float] = None,
                      request_id: Optional[str] = None) -> Union[
@@ -420,9 +433,9 @@ class AsyncTamarModelClient:
             }
 
         if not request_id:
-            request_id = generate_request_id()  # 生成一个新的 request_id
-        set_request_id(request_id)  # 设置当前请求的 request_id
-        metadata = self._build_auth_metadata(request_id)  # 将 request_id 加入到请求头
+            request_id = generate_request_id()
+        set_request_id(request_id)
+        metadata = self._build_auth_metadata(request_id)
 
         # 记录开始日志
         start_time = time.time()
@@ -431,135 +444,86 @@ class AsyncTamarModelClient:
             extra={
                 "log_type": "request",
                 "uri": f"/invoke/{model_request.provider.value}/{model_request.invoke_type.value}",
-                "data": {
-                    "provider": model_request.provider.value,
-                    "invoke_type": model_request.invoke_type.value,
-                    "model": model_request.model,
-                    "stream": model_request.stream,
-                    "org_id": model_request.user_context.org_id,
-                    "user_id": model_request.user_context.user_id,
-                    "client_type": model_request.user_context.client_type
-                }
+                "data": ResponseHandler.build_log_data(model_request)
             })
 
-        # 动态根据 provider/invoke_type 决定使用哪个 input 字段
         try:
-            # 选择需要校验的字段集合
-            # 动态分支逻辑
-            match (model_request.provider, model_request.invoke_type):
-                case (ProviderType.GOOGLE, InvokeType.GENERATION):
-                    allowed_fields = GoogleGenAiInput.model_fields.keys()
-                case (ProviderType.GOOGLE, InvokeType.IMAGE_GENERATION):
-                    allowed_fields = GoogleVertexAIImagesInput.model_fields.keys()
-                case ((ProviderType.OPENAI | ProviderType.AZURE), InvokeType.RESPONSES | InvokeType.GENERATION):
-                    allowed_fields = OpenAIResponsesInput.model_fields.keys()
-                case ((ProviderType.OPENAI | ProviderType.AZURE), InvokeType.CHAT_COMPLETIONS):
-                    allowed_fields = OpenAIChatCompletionsInput.model_fields.keys()
-                case ((ProviderType.OPENAI | ProviderType.AZURE), InvokeType.IMAGE_GENERATION):
-                    allowed_fields = OpenAIImagesInput.model_fields.keys()
-                case ((ProviderType.OPENAI | ProviderType.AZURE), InvokeType.IMAGE_EDIT_GENERATION):
-                    allowed_fields = OpenAIImagesEditInput.model_fields.keys()
-                case _:
-                    raise ValueError(
-                        f"Unsupported provider/invoke_type combination: {model_request.provider} + {model_request.invoke_type}")
-
-            # 将 ModelRequest 转 dict，过滤只保留 base + allowed 的字段
-            model_request_dict = model_request.model_dump(exclude_unset=True)
-
-            grpc_request_kwargs = {}
-            for field in allowed_fields:
-                if field in model_request_dict:
-                    value = model_request_dict[field]
-
-                    # 跳过无效的值
-                    if not is_effective_value(value):
-                        continue
-
-                    # 序列化grpc不支持的类型
-                    grpc_request_kwargs[field] = serialize_value(value)
-
-                    # 清理 serialize后的 grpc_request_kwargs
-                    grpc_request_kwargs = remove_none_from_dict(grpc_request_kwargs)
-
-            request = model_service_pb2.ModelRequestItem(
-                provider=model_request.provider.value,
-                channel=model_request.channel.value,
-                invoke_type=model_request.invoke_type.value,
-                stream=model_request.stream or False,
-                org_id=model_request.user_context.org_id or "",
-                user_id=model_request.user_context.user_id or "",
-                client_type=model_request.user_context.client_type or "",
-                extra=grpc_request_kwargs
-            )
-
+            # 构建 gRPC 请求
+            request = RequestBuilder.build_single_request(model_request)
+            
         except Exception as e:
+            duration = time.time() - start_time
+            logger.error(
+                f"❌ Request build failed: {str(e)}",
+                exc_info=True,
+                extra={
+                    "log_type": "response",
+                    "uri": f"/invoke/{model_request.provider.value}/{model_request.invoke_type.value}",
+                    "duration": duration,
+                    "data": {
+                        "provider": model_request.provider.value,
+                        "invoke_type": model_request.invoke_type.value,
+                        "model": getattr(model_request, 'model', None),
+                        "error_type": "build_error",
+                        "error_message": str(e)
+                    }
+                }
+            )
             raise ValueError(f"构建请求失败: {str(e)}") from e
 
         try:
             invoke_timeout = timeout or self.default_invoke_timeout
             if model_request.stream:
-                # 对于流式响应，使用带日志记录的包装器
-                stream_generator = await self._retry_request_stream(self._stream, request, metadata, invoke_timeout)
+                # 对于流式响应，直接返回带日志记录的包装器
                 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)
-                
+
                 # 记录非流式响应的成功日志
                 duration = time.time() - start_time
+                content_length = len(result.content) if result.content else 0
                 logger.info(
-                    f"✅ Request completed successfully",
+                    f"✅ Request completed | content_length: {content_length}",
                     extra={
                         "log_type": "response",
                         "uri": f"/invoke/{model_request.provider.value}/{model_request.invoke_type.value}",
                         "duration": duration,
-                        "data": {
-                            "provider": model_request.provider.value,
-                            "invoke_type": model_request.invoke_type.value,
-                            "model": model_request.model,
-                            "stream": False,
-                            "content_length": len(result.content) if result.content else 0,
-                            "usage": result.usage
-                        }
+                        "data": ResponseHandler.build_log_data(model_request, result)
                     }
                 )
                 return result
+                
         except grpc.RpcError as e:
             duration = time.time() - start_time
             error_message = f"❌ Invoke gRPC failed: {str(e)}"
             logger.error(error_message, exc_info=True,
-                       extra={
-                           "log_type": "response",
-                           "uri": f"/invoke/{model_request.provider.value}/{model_request.invoke_type.value}",
-                           "duration": duration,
-                           "data": {
-                               "error_type": "grpc_error",
-                               "error_code": str(e.code()) if hasattr(e, 'code') else None,
-                               "provider": model_request.provider.value,
-                               "invoke_type": model_request.invoke_type.value,
-                               "model": model_request.model
-                           }
-                       })
+                         extra={
+                             "log_type": "response",
+                             "uri": f"/invoke/{model_request.provider.value}/{model_request.invoke_type.value}",
+                             "duration": duration,
+                             "data": ResponseHandler.build_log_data(
+                                 model_request,
+                                 error=e
+                             )
+                         })
             raise e
         except Exception as e:
             duration = time.time() - start_time
             error_message = f"❌ Invoke other error: {str(e)}"
             logger.error(error_message, exc_info=True,
-                       extra={
-                           "log_type": "response",
-                           "uri": f"/invoke/{model_request.provider.value}/{model_request.invoke_type.value}",
-                           "duration": duration,
-                           "data": {
-                               "error_type": "other_error",
-                               "provider": model_request.provider.value,
-                               "invoke_type": model_request.invoke_type.value,
-                               "model": model_request.model
-                           }
-                       })
+                         extra={
+                             "log_type": "response",
+                             "uri": f"/invoke/{model_request.provider.value}/{model_request.invoke_type.value}",
+                             "duration": duration,
+                             "data": ResponseHandler.build_log_data(
+                                 model_request,
+                                 error=e
+                             )
+                         })
             raise e
 
     async def invoke_batch(self, batch_request_model: BatchModelRequest, timeout: Optional[float] = None,
-                           request_id: Optional[str] = None) -> \
-            BatchModelResponse:
+                           request_id: Optional[str] = None) -> BatchModelResponse:
         """
         批量模型调用接口
 
@@ -570,7 +534,6 @@ class AsyncTamarModelClient:
         Returns:
             BatchModelResponse: 批量请求的结果
         """
-
         await self._ensure_initialized()
 
         if not self.default_payload:
@@ -580,9 +543,9 @@ class AsyncTamarModelClient:
             }
 
         if not request_id:
-            request_id = generate_request_id()  # 生成一个新的 request_id
-        set_request_id(request_id)  # 设置当前请求的 request_id
-        metadata = self._build_auth_metadata(request_id)  # 将 request_id 加入到请求头
+            request_id = generate_request_id()
+        set_request_id(request_id)
+        metadata = self._build_auth_metadata(request_id)
 
         # 记录开始日志
         start_time = time.time()
@@ -599,155 +562,83 @@ class AsyncTamarModelClient:
                 }
             })
 
-        # 构造批量请求
-        items = []
-        for model_request_item in batch_request_model.items:
-            # 动态根据 provider/invoke_type 决定使用哪个 input 字段
-            try:
-                match (model_request_item.provider, model_request_item.invoke_type):
-                    case (ProviderType.GOOGLE, InvokeType.GENERATION):
-                        allowed_fields = GoogleGenAiInput.model_fields.keys()
-                    case (ProviderType.GOOGLE, InvokeType.IMAGE_GENERATION):
-                        allowed_fields = GoogleVertexAIImagesInput.model_fields.keys()
-                    case ((ProviderType.OPENAI | ProviderType.AZURE), InvokeType.RESPONSES | InvokeType.GENERATION):
-                        allowed_fields = OpenAIResponsesInput.model_fields.keys()
-                    case ((ProviderType.OPENAI | ProviderType.AZURE), InvokeType.CHAT_COMPLETIONS):
-                        allowed_fields = OpenAIChatCompletionsInput.model_fields.keys()
-                    case ((ProviderType.OPENAI | ProviderType.AZURE), InvokeType.IMAGE_GENERATION):
-                        allowed_fields = OpenAIImagesInput.model_fields.keys()
-                    case ((ProviderType.OPENAI | ProviderType.AZURE), InvokeType.IMAGE_EDIT_GENERATION):
-                        allowed_fields = OpenAIImagesEditInput.model_fields.keys()
-                    case _:
-                        raise ValueError(
-                            f"Unsupported provider/invoke_type combination: {model_request_item.provider} + {model_request_item.invoke_type}")
-
-                # 将 ModelRequest 转 dict，过滤只保留 base + allowed 的字段
-                model_request_dict = model_request_item.model_dump(exclude_unset=True)
-
-                grpc_request_kwargs = {}
-                for field in allowed_fields:
-                    if field in model_request_dict:
-                        value = model_request_dict[field]
-
-                        # 跳过无效的值
-                        if not is_effective_value(value):
-                            continue
-
-                        # 序列化grpc不支持的类型
-                        grpc_request_kwargs[field] = serialize_value(value)
-
-                        # 清理 serialize后的 grpc_request_kwargs
-                        grpc_request_kwargs = remove_none_from_dict(grpc_request_kwargs)
-
-                items.append(model_service_pb2.ModelRequestItem(
-                    provider=model_request_item.provider.value,
-                    channel=model_request_item.channel.value,
-                    invoke_type=model_request_item.invoke_type.value,
-                    stream=model_request_item.stream or False,
-                    custom_id=model_request_item.custom_id or "",
-                    priority=model_request_item.priority or 1,
-                    org_id=batch_request_model.user_context.org_id or "",
-                    user_id=batch_request_model.user_context.user_id or "",
-                    client_type=batch_request_model.user_context.client_type or "",
-                    extra=grpc_request_kwargs,
-                ))
-
-            except Exception as e:
-                raise ValueError(f"构建请求失败: {str(e)}，item={model_request_item.custom_id}") from e
+        try:
+            # 构建批量请求
+            batch_request = RequestBuilder.build_batch_request(batch_request_model)
+            
+        except Exception as e:
+            duration = time.time() - start_time
+            logger.error(
+                f"❌ Batch request build failed: {str(e)}",
+                exc_info=True,
+                extra={
+                    "log_type": "response",
+                    "uri": "/batch_invoke",
+                    "duration": duration,
+                    "data": {
+                        "batch_size": len(batch_request_model.items),
+                        "error_type": "build_error",
+                        "error_message": str(e)
+                    }
+                }
+            )
+            raise ValueError(f"构建批量请求失败: {str(e)}") from e
 
         try:
-            # 超时处理逻辑
             invoke_timeout = timeout or self.default_invoke_timeout
-
-            # 调用 gRPC 接口
-            response = await self._retry_request(self.stub.BatchInvoke, model_service_pb2.ModelRequest(items=items),
-                                                 timeout=invoke_timeout, metadata=metadata)
-
-            result = []
-            for res_item in response.items:
-                result.append(ModelResponse(
-                    content=res_item.content,
-                    usage=json.loads(res_item.usage) if res_item.usage else None,
-                    raw_response=json.loads(res_item.raw_response) if res_item.raw_response else None,
-                    error=res_item.error or None,
-                    custom_id=res_item.custom_id if res_item.custom_id else None
-                ))
-            batch_response = BatchModelResponse(
-                request_id=response.request_id if response.request_id else None,
-                responses=result
+            batch_response = await self._retry_request(
+                self.stub.BatchInvoke,
+                batch_request,
+                metadata=metadata,
+                timeout=invoke_timeout
             )
-            
+
+            # 构建响应对象
+            result = ResponseHandler.build_batch_response(batch_response)
+
             # 记录成功日志
             duration = time.time() - start_time
             logger.info(
-                f"✅ Batch request completed successfully",
+                f"✅ Batch Request completed | batch_size: {len(result.responses)}",
                 extra={
                     "log_type": "response",
                     "uri": "/batch_invoke",
                     "duration": duration,
                     "data": {
-                        "batch_size": len(batch_request_model.items),
-                        "responses_count": len(result)
+                        "batch_size": len(result.responses),
+                        "success_count": sum(1 for item in result.responses if not item.error),
+                        "error_count": sum(1 for item in result.responses if item.error)
                     }
-                }
-            )
-            return batch_response
+                })
+
+            return result
+
         except grpc.RpcError as e:
             duration = time.time() - start_time
-            error_message = f"❌ BatchInvoke gRPC failed: {str(e)}"
+            error_message = f"❌ Batch invoke gRPC failed: {str(e)}"
             logger.error(error_message, exc_info=True,
-                       extra={
-                           "log_type": "response",
-                           "uri": "/batch_invoke",
-                           "duration": duration,
-                           "data": {
-                               "error_type": "grpc_error",
-                               "error_code": str(e.code()) if hasattr(e, 'code') else None,
-                               "batch_size": len(batch_request_model.items)
-                           }
-                       })
+                         extra={
+                             "log_type": "response",
+                             "uri": "/batch_invoke",
+                             "duration": duration,
+                             "data": {
+                                 "error_type": "grpc_error",
+                                 "error_code": str(e.code()) if hasattr(e, 'code') else None,
+                                 "batch_size": len(batch_request_model.items)
+                             }
+                         })
             raise e
         except Exception as e:
             duration = time.time() - start_time
-            error_message = f"❌ BatchInvoke other error: {str(e)}"
+            error_message = f"❌ Batch invoke other error: {str(e)}"
             logger.error(error_message, exc_info=True,
-                       extra={
-                           "log_type": "response",
-                           "uri": "/batch_invoke",
-                           "duration": duration,
-                           "data": {
-                               "error_type": "other_error",
-                               "batch_size": len(batch_request_model.items)
-                           }
-                       })
-            raise e
-
-    async def close(self):
-        """关闭 gRPC 通道"""
-        if self.channel and not self._closed:
-            await self.channel.close()
-            self._closed = True
-            logger.info("✅ gRPC channel closed",
-                      extra={"log_type": "info", "data": {"status": "success"}})
-
-    def _safe_sync_close(self):
-        """进程退出时自动关闭 channel（事件循环处理兼容）"""
-        if self.channel and not self._closed:
-            try:
-                loop = asyncio.get_event_loop()
-                if loop.is_running():
-                    loop.create_task(self.close())
-                else:
-                    loop.run_until_complete(self.close())
-            except Exception as e:
-                logger.warning(f"⚠️ gRPC channel close failed at exit: {e}",
-                             extra={"log_type": "info", "data": {"status": "failed", "error": str(e)}})
-
-    async def __aenter__(self):
-        """支持 async with 自动初始化连接"""
-        await self._ensure_initialized()
-        return self
-
-    async def __aexit__(self, exc_type, exc_val, exc_tb):
-        """支持 async with 自动关闭连接"""
-        await self.close()
+                         extra={
+                             "log_type": "response",
+                             "uri": "/batch_invoke",
+                             "duration": duration,
+                             "data": {
+                                 "error_type": "other_error",
+                                 "batch_size": len(batch_request_model.items)
+                             }
+                         })
+            raise e