flowchart TB
    subgraph "上游服务层"
        AIO[AI Orchestrator]
        AGE[Agent Engine]
        RAG[RAG Engine]
    end

    subgraph "Model Adapter 服务"
        subgraph "接入层"
            API[FastAPI 路由层]
            Health[健康检查]
        end

        subgraph "服务层"
            AS[AdapterService<br/>统一调度服务]
            Cache[CacheService<br/>请求缓存]
            Registry[AdapterRegistry<br/>适配器注册表]
        end

        subgraph "协议转换层"
            PC[ProtocolConverter<br/>协议转换器]
            CC[CostCalculator<br/>成本计算器]
            TC[TokenCounter<br/>Token计数器]
        end

        subgraph "Provider 适配器层"
            OA[OpenAIAdapter]
            CA[ClaudeAdapter]
            ZA[ZhipuAdapter]
            QA[QwenAdapter]
            BA[BaiduAdapter]
        end
    end

    subgraph "LLM 提供商"
        OpenAI[OpenAI API]
        Claude[Anthropic API]
        Zhipu[智谱 API]
        Qwen[通义 API]
        Baidu[文心 API]
    end

    subgraph "基础设施"
        Redis[(Redis<br/>缓存)]
        Metrics[Prometheus<br/>监控]
    end

    AIO --> API
    AGE --> API
    RAG --> API

    API --> AS
    API --> Health
    AS --> Cache
    AS --> Registry
    AS --> PC
    AS --> CC

    Cache --> Redis

    AS --> OA
    AS --> CA
    AS --> ZA
    AS --> QA
    AS --> BA

    OA --> OpenAI
    CA --> Claude
    ZA --> Zhipu
    QA --> Qwen
    BA --> Baidu

    AS --> Metrics
    Cache --> Metrics

sequenceDiagram
    autonumber
    participant Client as 上游服务<br/>(AI Orchestrator)
    participant Router as FastAPI 路由
    participant Service as AdapterService
    participant Cache as CacheService
    participant Conv as ProtocolConverter
    participant Adapter as Provider Adapter<br/>(OpenAIAdapter)
    participant Provider as LLM Provider<br/>(OpenAI API)
    participant Cost as CostCalculator
    participant Redis as Redis

    Client->>Router: POST /api/v1/chat/completions<br/>{model, messages, temperature...}
    Router->>Router: 请求参数验证（Pydantic）
    Router->>Service: adapter_service.chat(request)

    Service->>Service: _get_provider(model, provider)<br/>根据模型名称识别提供商

    Service->>Cache: get_cached_response(request)
    Cache->>Cache: _generate_cache_key(request)<br/>生成缓存键（SHA256）
    Cache->>Redis: GET cache_key

    alt 缓存命中
        Redis-->>Cache: 缓存数据
        Cache-->>Service: ChatResponse
        Service-->>Router: response
        Router-->>Client: 200 OK + ChatResponse
    else 缓存未命中
        Redis-->>Cache: None
        Cache-->>Service: None

        Service->>Conv: normalize_messages(messages, provider)
        Conv-->>Service: 规范化后的 messages

        Service->>Adapter: chat(request)
        Adapter->>Provider: POST /v1/chat/completions<br/>转换为 Provider 特定格式
        Provider-->>Adapter: Provider 响应
        Adapter->>Adapter: 转换为统一格式 ChatResponse
        Adapter-->>Service: ChatResponse

        Service->>Cost: calculate_cost(model, input_tokens, output_tokens)
        Cost-->>Service: 成本信息

        Service->>Cache: set_cached_response(request, response)
        Cache->>Redis: SETEX cache_key 3600 response_json

        Service-->>Router: ChatResponse
        Router-->>Client: 200 OK + ChatResponse
    end

sequenceDiagram
    autonumber
    participant Client as 上游服务
    participant Router as FastAPI 路由
    participant Service as AdapterService
    participant Adapter as Provider Adapter
    participant Provider as LLM Provider

    Client->>Router: POST /api/v1/chat/completions<br/>{stream: true}
    Router->>Router: 参数验证
    Router->>Service: adapter_service.chat_stream(request)

    Service->>Service: _get_provider(model, provider)
    Service->>Adapter: chat_stream(request)

    Adapter->>Provider: POST /v1/chat/completions<br/>{stream: true}
    Provider-->>Adapter: SSE Stream 开始

    loop 流式传输
        Provider-->>Adapter: data: {delta: {content: "..."}}
        Adapter->>Adapter: 解析 SSE 数据
        Adapter-->>Service: yield chunk
        Service-->>Router: yield chunk
        Router-->>Client: data: {content: "..."}\n\n
    end

    Provider-->>Adapter: data: [DONE]
    Adapter-->>Service: 流结束
    Service-->>Router: 流结束
    Router-->>Client: 连接关闭

class AdapterService:
    """适配器服务"""

    def __init__(self):
        # 初始化各个提供商的适配器
        self.openai_adapter = OpenAIAdapter()
        self.anthropic_adapter = AnthropicAdapter()
        self.zhipu_adapter = ZhipuAdapter()
        self.qwen_adapter = QwenAdapter()
        self.baidu_adapter = BaiduAdapter()

        # 提供商映射
        self.adapters = {
            "openai": self.openai_adapter,
            "azure-openai": self.openai_adapter,
            "anthropic": self.anthropic_adapter,
            "zhipu": self.zhipu_adapter,
            "qwen": self.qwen_adapter,
            "baidu": self.baidu_adapter,
        }

    def _get_provider(self, model: str, provider: str = None) -> tuple:
        """
        根据模型名称或指定的提供商获取适配器

        路由策略：
        1. 优先使用显式指定的 provider 参数
        2. 根据模型名称前缀自动识别（gpt-* -> openai, claude-* -> anthropic）
        3. 默认使用 OpenAI

        Args:
            model: 模型名称
            provider: 指定的提供商

        Returns:
            (provider_name, adapter)
        """
        # 显式指定提供商
        if provider and provider in self.adapters:
            return provider, self.adapters[provider]

        # 自动识别
        if model.startswith("gpt-"):
            return "openai", self.openai_adapter
        elif model.startswith("claude-"):
            return "anthropic", self.anthropic_adapter
        elif model.startswith("glm-"):
            return "zhipu", self.zhipu_adapter
        elif model.startswith("qwen-"):
            return "qwen", self.qwen_adapter
        elif model.startswith("ERNIE-") or model.startswith("ernie-"):
            return "baidu", self.baidu_adapter

        # 默认 OpenAI
        logger.warning(f"Unknown model: {model}, using OpenAI adapter")
        return "openai", self.openai_adapter

    async def chat(self, request: ChatRequest) -> ChatResponse:
        """
        聊天接口

        流程：
        1. 根据模型识别 Provider
        2. 调用对应 Adapter 的 chat 方法
        3. 返回统一格式响应

        Args:
            request: 聊天请求

        Returns:
            聊天响应
        """
        provider_name, adapter = self._get_provider(request.model, request.provider)

        logger.info(f"Routing to {provider_name} for model {request.model}")

        try:
            response = await adapter.chat(request)
            response.provider = provider_name
            return response

        except Exception as e:
            logger.error(f"Chat failed with {provider_name}: {e}", exc_info=True)
            raise

sequenceDiagram
    autonumber
    participant Router as 路由层
    participant Service as AdapterService
    participant Map as 提供商映射表
    participant Adapter as Provider Adapter

    Router->>Service: chat(request)
    Service->>Service: _get_provider(model, provider)

    alt 显式指定 provider
        Service->>Map: 查找 self.adapters[provider]
        Map-->>Service: adapter
    else 模型名称前缀匹配
        Service->>Service: 匹配模型前缀规则<br/>(gpt-/claude-/glm-...)
        Service-->>Service: 确定 provider
        Service->>Map: 查找 self.adapters[provider]
        Map-->>Service: adapter
    else 默认策略
        Service->>Service: 使用默认 provider (openai)
        Service->>Map: 查找 self.adapters["openai"]
        Map-->>Service: openai_adapter
    end

    Service->>Service: 记录路由日志
    Service->>Adapter: adapter.chat(request)
    Adapter-->>Service: ChatResponse
    Service->>Service: response.provider = provider_name
    Service-->>Router: ChatResponse

class RequestCacheService:
    """请求缓存服务"""

    def __init__(self):
        # Redis 连接
        self.redis_client = redis.Redis(
            host=settings.REDIS_HOST,
            port=settings.REDIS_PORT,
            db=settings.REDIS_DB,
            decode_responses=True
        )
        self.key_prefix = "model_adapter:cache"
        self.default_ttl = 3600  # 1 小时

    def _generate_cache_key(self, request: ChatRequest) -> str:
        """
        生成缓存键

        策略：
        1. 序列化请求关键参数（model, messages, temperature, max_tokens, top_p 等）
        2. 排除 stream 参数（流式请求不缓存）
        3. 使用 SHA256 生成哈希，避免缓存键冲突
        4. 添加前缀，便于批量管理

        Args:
            request: 聊天请求

        Returns:
            缓存键: "model_adapter:cache:<sha256_hash>"
        """
        request_dict = {
            "model": request.model,
            "messages": [{"role": m.role, "content": m.content} for m in request.messages],
            "temperature": request.temperature,
            "max_tokens": request.max_tokens,
            "top_p": request.top_p,
            "frequency_penalty": request.frequency_penalty,
            "presence_penalty": request.presence_penalty,
        }

        # 确保顺序一致
        request_str = json.dumps(request_dict, sort_keys=True, ensure_ascii=False)
        hash_value = hashlib.sha256(request_str.encode()).hexdigest()

        return f"{self.key_prefix}:{hash_value}"

    async def get_cached_response(
        self,
        request: ChatRequest
    ) -> Optional[ChatResponse]:
        """
        获取缓存的响应

        流程：
        1. 检查是否为流式请求，是则直接返回 None
        2. 生成缓存键
        3. 从 Redis 查询
        4. 如果命中，解析 JSON 并转换为 ChatResponse 对象
        5. 更新缓存过期时间（续期策略）

        Args:
            request: 聊天请求

        Returns:
            缓存的响应（如果存在）
        """
        if request.stream:
            return None

        try:
            cache_key = self._generate_cache_key(request)
            cached_data = self.redis_client.get(cache_key)

            if cached_data:
                logger.info(f"Cache hit for request: {request.model}")
                response_dict = json.loads(cached_data)
                response = ChatResponse.parse_obj(response_dict)

                # 续期
                self.redis_client.expire(cache_key, self.default_ttl)
                return response

            return None
        except Exception as e:
            logger.error(f"Error getting cached response: {e}")
            return None

    async def set_cached_response(
        self,
        request: ChatRequest,
        response: ChatResponse,
        ttl: Optional[int] = None
    ):
        """
        设置缓存响应

        流程：
        1. 检查是否为流式请求，是则跳过
        2. 生成缓存键
        3. 序列化响应为 JSON
        4. 写入 Redis，设置过期时间

        Args:
            request: 聊天请求
            response: 聊天响应
            ttl: 过期时间（秒），默认 3600
        """
        if request.stream:
            return

        try:
            if ttl is None:
                ttl = self.default_ttl

            cache_key = self._generate_cache_key(request)
            response_dict = response.dict()
            response_json = json.dumps(response_dict, ensure_ascii=False)

            self.redis_client.setex(cache_key, ttl, response_json)
            logger.info(f"Cached response for request: {request.model}")
        except Exception as e:
            logger.error(f"Error setting cached response: {e}")

sequenceDiagram
    autonumber
    participant Service as AdapterService
    participant Cache as CacheService
    participant Redis as Redis

    Service->>Cache: get_cached_response(request)

    Cache->>Cache: 检查 request.stream
    alt 流式请求
        Cache-->>Service: None（不缓存流式）
    else 非流式请求
        Cache->>Cache: _generate_cache_key(request)<br/>序列化参数 + SHA256
        Cache->>Redis: GET model_adapter:cache:<hash>

        alt 缓存命中
            Redis-->>Cache: cached_json
            Cache->>Cache: json.loads(cached_json)
            Cache->>Cache: ChatResponse.parse_obj(data)
            Cache->>Redis: EXPIRE key 3600（续期）
            Cache-->>Service: ChatResponse（from cache）
        else 缓存未命中
            Redis-->>Cache: None
            Cache-->>Service: None

            Note over Service: 调用 Provider API 获取响应

            Service->>Cache: set_cached_response(request, response)
            Cache->>Cache: _generate_cache_key(request)
            Cache->>Cache: response.dict() + json.dumps()
            Cache->>Redis: SETEX key 3600 response_json
            Cache-->>Service: 缓存已设置
        end
    end

class ProtocolConverter:
    """协议转换器"""

    @staticmethod
    def to_openai_format(
        messages: List[Dict[str, Any]],
        parameters: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """
        转换为 OpenAI 格式

        OpenAI 格式与统一格式基本一致，直接映射参数即可

        Args:
            messages: 统一格式的消息列表
            parameters: 参数

        Returns:
            OpenAI API 格式的请求
        """
        request = {"messages": messages}

        if parameters:
            param_mapping = {
                "temperature": "temperature",
                "max_tokens": "max_tokens",
                "top_p": "top_p",
                "frequency_penalty": "frequency_penalty",
                "presence_penalty": "presence_penalty",
                "stop": "stop",
            }

            for unified_key, openai_key in param_mapping.items():
                if unified_key in parameters:
                    request[openai_key] = parameters[unified_key]

        return request

    @staticmethod
    def to_claude_format(
        messages: List[Dict[str, Any]],
        parameters: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """
        转换为 Claude 格式

        关键差异：
        1. Claude 要求 system 消息单独放在 "system" 字段
        2. messages 中只能包含 user 和 assistant 消息
        3. 参数名称部分不同（如 stop -> stop_sequences）

        Args:
            messages: 统一格式的消息列表
            parameters: 参数

        Returns:
            Claude API 格式的请求
        """
        system_prompt = None
        formatted_messages = []

        # 分离 system 消息
        for msg in messages:
            if msg.get("role") == "system":
                if system_prompt is None:
                    system_prompt = msg.get("content", "")
                else:
                    system_prompt += "\n\n" + msg.get("content", "")
            else:
                formatted_messages.append(msg)

        request = {"messages": formatted_messages}

        if system_prompt:
            request["system"] = system_prompt

        if parameters:
            param_mapping = {
                "temperature": "temperature",
                "max_tokens": "max_tokens",
                "top_p": "top_p",
                "top_k": "top_k",
                "stop": "stop_sequences",
            }

            for unified_key, claude_key in param_mapping.items():
                if unified_key in parameters:
                    request[claude_key] = parameters[unified_key]

        return request

    @staticmethod
    def normalize_messages(
        messages: List[Dict[str, Any]],
        provider: str,
    ) -> List[Dict[str, Any]]:
        """
        规范化消息格式

        不同 Provider 对消息格式有不同要求：
        - Claude: 不允许连续相同 role 的消息
        - 智谱: 必须包含至少一条 user 消息

        Args:
            messages: 消息列表
            provider: 目标 Provider

        Returns:
            规范化后的消息列表
        """
        if provider == "claude":
            # Claude 不允许连续的相同 role 消息
            normalized = []
            last_role = None

            for msg in messages:
                role = msg.get("role")
                content = msg.get("content")

                if role == "system":
                    normalized.append(msg)
                elif role == last_role:
                    # 合并连续的相同 role 消息
                    if normalized:
                        normalized[-1]["content"] += "\n\n" + content
                else:
                    normalized.append(msg)
                    last_role = role

            return normalized

        elif provider == "zhipu":
            # 智谱 AI 要求必须有 user 消息
            if not any(msg.get("role") == "user" for msg in messages):
                messages.append({"role": "user", "content": "请继续"})

            return messages

        else:
            # OpenAI 等：不需要特殊处理
            return messages

sequenceDiagram
    autonumber
    participant Adapter as Provider Adapter
    participant Conv as ProtocolConverter
    participant Provider as LLM Provider API

    Adapter->>Conv: normalize_messages(messages, provider)

    alt provider == "claude"
        Conv->>Conv: 检测连续相同 role
        Conv->>Conv: 合并连续消息
        Conv->>Conv: 分离 system 消息
        Conv-->>Adapter: 规范化后的 messages
    else provider == "zhipu"
        Conv->>Conv: 检查是否有 user 消息
        alt 缺少 user 消息
            Conv->>Conv: 添加默认 user 消息
        end
        Conv-->>Adapter: 规范化后的 messages
    else provider == "openai"
        Conv-->>Adapter: messages（无需处理）
    end

    alt provider == "openai"
        Adapter->>Conv: to_openai_format(messages, params)
        Conv-->>Adapter: OpenAI 请求格式
    else provider == "claude"
        Adapter->>Conv: to_claude_format(messages, params)
        Conv->>Conv: 提取并分离 system prompt
        Conv->>Conv: 映射参数名称
        Conv-->>Adapter: Claude 请求格式
    else provider == "zhipu"
        Adapter->>Conv: to_zhipu_format(messages, params)
        Conv-->>Adapter: 智谱 AI 请求格式
    end

    Adapter->>Provider: HTTP POST（Provider 特定格式）
    Provider-->>Adapter: Provider 响应

    Adapter->>Conv: from_<provider>_response(response)
    Conv->>Conv: 提取 content、usage 等字段
    Conv->>Conv: 转换为统一格式
    Conv-->>Adapter: 统一格式响应

# 模型定价表 (USD per 1K tokens)
MODEL_PRICING = {
    # OpenAI
    "gpt-3.5-turbo": {"input": 0.0005, "output": 0.0015},
    "gpt-4": {"input": 0.03, "output": 0.06},
    "gpt-4-turbo": {"input": 0.01, "output": 0.03},

    # Claude
    "claude-3-haiku-20240307": {"input": 0.00025, "output": 0.00125},
    "claude-3-sonnet-20240229": {"input": 0.003, "output": 0.015},
    "claude-3-opus-20240229": {"input": 0.015, "output": 0.075},

    # 智谱 AI
    "glm-4": {"input": 0.001, "output": 0.001},
    "glm-3-turbo": {"input": 0.0005, "output": 0.0005},
}

class CostCalculator:
    """成本计算器"""

    @staticmethod
    def calculate_cost(
        model: str,
        input_tokens: int,
        output_tokens: int,
    ) -> Dict[str, float]:
        """
        计算成本

        计算公式：
        - input_cost = (input_tokens / 1000) * pricing["input"]
        - output_cost = (output_tokens / 1000) * pricing["output"]
        - total_cost = input_cost + output_cost

        Args:
            model: 模型名称
            input_tokens: 输入 token 数
            output_tokens: 输出 token 数

        Returns:
            成本详情字典:
            - input_cost: 输入成本
            - output_cost: 输出成本
            - total_cost: 总成本
            - currency: 货币单位（USD）
        """
        pricing = MODEL_PRICING.get(model)

        if not pricing:
            logger.warning(f"No pricing found for model: {model}, using default")
            pricing = {"input": 0.001, "output": 0.002}

        input_cost = (input_tokens / 1000.0) * pricing["input"]
        output_cost = (output_tokens / 1000.0) * pricing["output"]
        total_cost = input_cost + output_cost

        return {
            "input_cost": round(input_cost, 6),
            "output_cost": round(output_cost, 6),
            "total_cost": round(total_cost, 6),
            "currency": "USD",
        }

    @staticmethod
    def get_cheapest_model(
        models: List[str],
        input_tokens: int,
        output_tokens: int,
    ) -> tuple[str, Dict[str, float]]:
        """
        获取成本最低的模型

        流程：
        1. 计算所有模型的成本
        2. 比较 total_cost
        3. 返回成本最低的模型

        Args:
            models: 模型列表
            input_tokens: 输入 token 数
            output_tokens: 输出 token 数

        Returns:
            (模型名称, 成本详情)
        """
        comparison = CostCalculator.compare_model_costs(
            models, input_tokens, output_tokens
        )

        if not comparison:
            return "", {}

        cheapest = min(comparison.items(), key=lambda x: x[1]["total_cost"])
        return cheapest[0], cheapest[1]

    @staticmethod
    def calculate_savings(
        current_model: str,
        alternative_model: str,
        input_tokens: int,
        output_tokens: int,
    ) -> Dict[str, float]:
        """
        计算切换模型可节省的成本

        Args:
            current_model: 当前模型
            alternative_model: 替代模型
            input_tokens: 输入 token 数
            output_tokens: 输出 token 数

        Returns:
            节省详情:
            - current_cost: 当前成本
            - alternative_cost: 替代方案成本
            - savings: 节省金额
            - savings_percent: 节省百分比
        """
        current_cost = CostCalculator.calculate_cost(
            current_model, input_tokens, output_tokens
        )

        alternative_cost = CostCalculator.calculate_cost(
            alternative_model, input_tokens, output_tokens
        )

        savings = current_cost["total_cost"] - alternative_cost["total_cost"]
        savings_percent = (savings / current_cost["total_cost"]) * 100 if current_cost["total_cost"] > 0 else 0

        return {
            "current_cost": current_cost["total_cost"],
            "alternative_cost": alternative_cost["total_cost"],
            "savings": round(savings, 6),
            "savings_percent": round(savings_percent, 2),
            "currency": "USD",
        }

sequenceDiagram
    autonumber
    participant Client as 调用方
    participant Calc as CostCalculator
    participant Pricing as MODEL_PRICING

    Client->>Calc: calculate_cost(model, input_tokens, output_tokens)
    Calc->>Pricing: 查询 MODEL_PRICING[model]

    alt 模型定价存在
        Pricing-->>Calc: {"input": 0.001, "output": 0.002}
    else 模型定价缺失
        Pricing-->>Calc: None
        Calc->>Calc: 使用默认定价
    end

    Calc->>Calc: input_cost = (input_tokens / 1000) * pricing["input"]
    Calc->>Calc: output_cost = (output_tokens / 1000) * pricing["output"]
    Calc->>Calc: total_cost = input_cost + output_cost
    Calc-->>Client: {input_cost, output_cost, total_cost, currency}

    Note over Client,Calc: 成本对比场景

    Client->>Calc: get_cheapest_model([model1, model2, model3], tokens...)
    loop 遍历模型列表
        Calc->>Calc: calculate_cost(model, input_tokens, output_tokens)
    end
    Calc->>Calc: 比较 total_cost，找到最小值
    Calc-->>Client: (cheapest_model, cost_details)

    Note over Client,Calc: 成本节约分析场景

    Client->>Calc: calculate_savings(current, alternative, tokens...)
    Calc->>Calc: current_cost = calculate_cost(current, ...)
    Calc->>Calc: alternative_cost = calculate_cost(alternative, ...)
    Calc->>Calc: savings = current_cost - alternative_cost
    Calc->>Calc: savings_percent = (savings / current_cost) * 100
    Calc-->>Client: {current_cost, alternative_cost, savings, savings_percent}

class OpenAIAdapter(BaseAdapter):
    """OpenAI 适配器"""

    def __init__(self):
        self.api_key = settings.OPENAI_API_KEY
        self.api_base = settings.OPENAI_API_BASE
        self.timeout = settings.REQUEST_TIMEOUT

    async def chat(self, request: ChatRequest) -> ChatResponse:
        """
        聊天接口

        流程：
        1. 构建 OpenAI API 请求
        2. 发送 HTTP POST 请求
        3. 解析响应
        4. 转换为统一格式

        Args:
            request: 聊天请求

        Returns:
            统一格式的聊天响应
        """
        try:
            async with httpx.AsyncClient(timeout=self.timeout) as client:
                response = await client.post(
                    f"{self.api_base}/chat/completions",
                    headers={
                        "Authorization": f"Bearer {self.api_key}",
                        "Content-Type": "application/json",
                    },
                    json={
                        "model": request.model,
                        "messages": [m.dict() for m in request.messages],
                        "temperature": request.temperature,
                        "max_tokens": request.max_tokens,
                        "top_p": request.top_p,
                        "frequency_penalty": request.frequency_penalty,
                        "presence_penalty": request.presence_penalty,
                    },
                )

                response.raise_for_status()
                data = response.json()

                # 转换为统一格式
                return ChatResponse(
                    id=data.get("id", f"chatcmpl-{uuid.uuid4().hex[:8]}"),
                    model=data.get("model", request.model),
                    provider="openai",
                    choices=[
                        ChatChoice(
                            index=choice["index"],
                            message=choice["message"],
                            finish_reason=choice.get("finish_reason"),
                        )
                        for choice in data.get("choices", [])
                    ],
                    usage=Usage(**data.get("usage", {})),
                    created=data.get("created", int(time.time())),
                )

        except httpx.HTTPError as e:
            logger.error(f"OpenAI API request failed: {e}")
            raise
        except Exception as e:
            logger.error(f"OpenAI adapter error: {e}")
            raise

    async def chat_stream(self, request: ChatRequest) -> AsyncIterator[str]:
        """
        流式聊天接口

        流程：
        1. 构建流式请求（stream: true）
        2. 使用 httpx.stream() 建立流式连接
        3. 逐行读取 SSE 数据
        4. 解析并转发给上游

        Args:
            request: 聊天请求

        Yields:
            SSE 格式的流式数据: "data: {...}\n\n"
        """
        try:
            async with httpx.AsyncClient(timeout=self.timeout) as client:
                async with client.stream(
                    "POST",
                    f"{self.api_base}/chat/completions",
                    headers={
                        "Authorization": f"Bearer {self.api_key}",
                        "Content-Type": "application/json",
                    },
                    json={
                        "model": request.model,
                        "messages": [m.dict() for m in request.messages],
                        "temperature": request.temperature,
                        "max_tokens": request.max_tokens,
                        "stream": True,
                    },
                ) as response:
                    response.raise_for_status()

                    async for line in response.aiter_lines():
                        if line.startswith("data: "):
                            data = line[6:]
                            if data == "[DONE]":
                                break
                            yield f"data: {data}\n\n"

        except Exception as e:
            logger.error(f"OpenAI stream error: {e}")
            raise

sequenceDiagram
    autonumber
    participant Service as AdapterService
    participant Adapter as OpenAIAdapter
    participant HTTP as httpx.AsyncClient
    participant API as OpenAI API

    Service->>Adapter: chat(request)
    Adapter->>Adapter: 准备请求参数
    Adapter->>HTTP: 创建异步 HTTP 客户端
    HTTP-->>Adapter: client

    Adapter->>HTTP: client.post(url, headers, json)
    HTTP->>API: POST /v1/chat/completions
    API-->>HTTP: 200 OK + JSON 响应
    HTTP-->>Adapter: response

    Adapter->>Adapter: response.raise_for_status()
    Adapter->>Adapter: data = response.json()
    Adapter->>Adapter: 转换为 ChatResponse 对象<br/>提取 choices, usage, id 等字段
    Adapter-->>Service: ChatResponse

    Note over Service,API: 流式场景

    Service->>Adapter: chat_stream(request)
    Adapter->>Adapter: 准备请求参数（stream: true）
    Adapter->>HTTP: client.stream(POST, url, ...)
    HTTP->>API: POST /v1/chat/completions (stream)
    API-->>HTTP: 开始 SSE 流

    loop 流式传输
        API-->>HTTP: data: {"choices":[{"delta":{"content":"..."}}]}\n\n
        HTTP-->>Adapter: line: "data: {...}"
        Adapter->>Adapter: 解析 SSE 行
        Adapter-->>Service: yield "data: {...}\n\n"
        Service-->>Service: 转发给上游
    end

    API-->>HTTP: data: [DONE]\n\n
    HTTP-->>Adapter: line: "data: [DONE]"
    Adapter->>Adapter: 检测到 [DONE]，结束流
    Adapter-->>Service: 流结束

Client HTTP Request
  ↓
[1] FastAPI Router (app/routers/chat.py:create_chat_completion)
  ↓ Pydantic 参数验证
  ↓
[2] AdapterService.chat (app/services/adapter_service.py:78-99)
  ↓ _get_provider() 路由选择
  ↓
[3] RequestCacheService.get_cached_response (app/services/cache_service.py:63-103)
  ↓ _generate_cache_key() 生成缓存键
  ↓
[4] Redis GET model_adapter:cache:<hash>
  ↓ 缓存命中
  ↓
[5] JSON.loads() + ChatResponse.parse_obj()
  ↓
[6] Redis EXPIRE（续期）
  ↓
[7] 返回 ChatResponse
  ↓
Client HTTP Response (200 OK + JSON)

@router.post("/completions", response_model=ChatResponse)
async def create_chat_completion(request: ChatRequest):
    """创建聊天补全"""
    try:
        logger.info(f"Chat request: model={request.model}, provider={request.provider}")

        if request.stream:
            # 流式响应（本路径不涉及）
            return StreamingResponse(...)
        else:
            # 普通响应 - 本路径
            response = await adapter_service.chat(request)
            return response
    except Exception as e:
        logger.error(f"Chat completion failed: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=str(e))

async def chat(self, request: ChatRequest) -> ChatResponse:
    """聊天接口"""
    # 步骤 2.1：根据模型选择 Provider
    provider_name, adapter = self._get_provider(request.model, request.provider)

    logger.info(f"Routing to {provider_name} for model {request.model}")

    try:
        # 步骤 2.2：调用适配器（本路径会先查缓存）
        response = await adapter.chat(request)
        response.provider = provider_name
        return response
    except Exception as e:
        logger.error(f"Chat failed with {provider_name}: {e}", exc_info=True)
        raise

def _get_provider(self, model: str, provider: str = None) -> tuple:
    """根据模型名称或指定的提供商获取适配器"""
    # 优先级 1：显式指定 provider
    if provider and provider in self.adapters:
        return provider, self.adapters[provider]

    # 优先级 2：模型名称前缀匹配
    if model.startswith("gpt-"):
        return "openai", self.openai_adapter
    elif model.startswith("claude-"):
        return "anthropic", self.anthropic_adapter
    elif model.startswith("glm-"):
        return "zhipu", self.zhipu_adapter
    elif model.startswith("qwen-"):
        return "qwen", self.qwen_adapter
    elif model.startswith("ERNIE-") or model.startswith("ernie-"):
        return "baidu", self.baidu_adapter

    # 优先级 3：默认策略
    logger.warning(f"Unknown model: {model}, using OpenAI adapter")
    return "openai", self.openai_adapter

async def get_cached_response(self, request: ChatRequest) -> Optional[ChatResponse]:
    """获取缓存的响应"""
    # 步骤 3.1：流式请求直接跳过
    if request.stream:
        return None

    try:
        # 步骤 3.2：生成缓存键
        cache_key = self._generate_cache_key(request)

        # 步骤 3.3：从 Redis 查询
        cached_data = self.redis_client.get(cache_key)

        if cached_data:
            # 步骤 3.4：缓存命中
            logger.info(f"Cache hit for request: {request.model}")

            # 步骤 3.5：反序列化
            response_dict = json.loads(cached_data)
            response = ChatResponse.parse_obj(response_dict)

            # 步骤 3.6：续期 TTL
            self.redis_client.expire(cache_key, self.default_ttl)

            return response

        return None
    except Exception as e:
        logger.error(f"Error getting cached response: {e}")
        return None  # 缓存异常不影响主流程

def _generate_cache_key(self, request: ChatRequest) -> str:
    """生成缓存键"""
    # 步骤 3.2.1：序列化请求参数
    request_dict = {
        "model": request.model,
        "messages": [{"role": m.role, "content": m.content} for m in request.messages],
        "temperature": request.temperature,
        "max_tokens": request.max_tokens,
        "top_p": request.top_p,
        "frequency_penalty": request.frequency_penalty,
        "presence_penalty": request.presence_penalty,
    }

    # 步骤 3.2.2：生成 JSON 字符串（确保顺序一致）
    request_str = json.dumps(request_dict, sort_keys=True, ensure_ascii=False)

    # 步骤 3.2.3：SHA256 哈希
    hash_value = hashlib.sha256(request_str.encode()).hexdigest()

    # 步骤 3.2.4：添加前缀
    return f"{self.key_prefix}:{hash_value}"

sequenceDiagram
    autonumber
    participant Client
    participant Router as FastAPI Router
    participant Service as AdapterService
    participant Cache as RequestCacheService
    participant Redis

    Client->>Router: POST /api/v1/chat/completions<br/>{model, messages, ...}
    Router->>Router: Pydantic 验证参数
    Note over Router: 检查必填项、类型、范围
    Router->>Service: adapter_service.chat(request)

    Service->>Service: _get_provider(model, provider)
    Note over Service: 路由规则匹配<br/>gpt-* → openai

    Service->>Cache: get_cached_response(request)
    Cache->>Cache: 检查 request.stream == False
    Cache->>Cache: _generate_cache_key(request)
    Note over Cache: 序列化参数 → SHA256

    Cache->>Redis: GET model_adapter:cache:<hash>
    Redis-->>Cache: cached_json (命中)

    Cache->>Cache: json.loads(cached_json)
    Cache->>Cache: ChatResponse.parse_obj(data)
    Cache->>Redis: EXPIRE key 3600
    Redis-->>Cache: OK

    Cache-->>Service: ChatResponse (from cache)
    Service->>Service: response.provider = "openai"
    Service-->>Router: ChatResponse

    Router-->>Client: 200 OK + JSON

Client HTTP Request
  ↓
[1] FastAPI Router → AdapterService.chat
  ↓
[2] _get_provider() 路由选择
  ↓
[3] RequestCacheService.get_cached_response → Redis GET（未命中）
  ↓
[4] ProtocolConverter.normalize_messages（可选，若需规范化）
  ↓
[5] Provider Adapter (OpenAIAdapter).chat
  ↓ [5.1] httpx.AsyncClient 创建
  ↓ [5.2] 构建请求 JSON
  ↓ [5.3] POST https://api.openai.com/v1/chat/completions
  ↓ [5.4] 等待响应（300-2000ms）
  ↓ [5.5] 解析 JSON 响应
  ↓ [5.6] 转换为 ChatResponse
  ↓
[6] CostCalculator.calculate_cost（可选）
  ↓
[7] RequestCacheService.set_cached_response → Redis SETEX
  ↓
[8] 返回 ChatResponse
  ↓
Client HTTP Response

@staticmethod
def normalize_messages(
    messages: List[Dict[str, Any]],
    provider: str,
) -> List[Dict[str, Any]]:
    """规范化消息格式"""
    if provider == "claude":
        # Claude 不允许连续的相同 role 消息
        normalized = []
        last_role = None

        for msg in messages:
            role = msg.get("role")
            content = msg.get("content")

            if role == "system":
                normalized.append(msg)
            elif role == last_role:
                # 合并连续的相同 role 消息
                if normalized:
                    normalized[-1]["content"] += "\n\n" + content
            else:
                normalized.append(msg)
                last_role = role

        return normalized

    elif provider == "zhipu":
        # 智谱 AI 要求必须有 user 消息
        if not any(msg.get("role") == "user" for msg in messages):
            messages.append({"role": "user", "content": "请继续"})
        return messages

    else:
        # OpenAI 等：不需要特殊处理
        return messages

async def chat(self, request: ChatRequest) -> ChatResponse:
    """聊天接口"""
    try:
        # 步骤 5.1：创建异步 HTTP 客户端
        async with httpx.AsyncClient(timeout=self.timeout) as client:
            # 步骤 5.2-5.3：构建请求并发送
            response = await client.post(
                f"{self.api_base}/chat/completions",
                headers={
                    "Authorization": f"Bearer {self.api_key}",
                    "Content-Type": "application/json",
                },
                json={
                    "model": request.model,
                    "messages": [m.dict() for m in request.messages],
                    "temperature": request.temperature,
                    "max_tokens": request.max_tokens,
                    "top_p": request.top_p,
                    "frequency_penalty": request.frequency_penalty,
                    "presence_penalty": request.presence_penalty,
                },
            )

            # 步骤 5.4：检查 HTTP 状态码
            response.raise_for_status()

            # 步骤 5.5：解析 JSON
            data = response.json()

            # 步骤 5.6：转换为统一格式
            return ChatResponse(
                id=data.get("id", f"chatcmpl-{uuid.uuid4().hex[:8]}"),
                model=data.get("model", request.model),
                provider="openai",
                choices=[
                    ChatChoice(
                        index=choice["index"],
                        message=choice["message"],
                        finish_reason=choice.get("finish_reason"),
                    )
                    for choice in data.get("choices", [])
                ],
                usage=Usage(**data.get("usage", {})),
                created=data.get("created", int(time.time())),
            )

    except httpx.HTTPError as e:
        logger.error(f"OpenAI API request failed: {e}")
        raise
    except Exception as e:
        logger.error(f"OpenAI adapter error: {e}")
        raise

@staticmethod
def calculate_cost(
    model: str,
    input_tokens: int,
    output_tokens: int,
) -> Dict[str, float]:
    """计算成本"""
    # 获取定价
    pricing = MODEL_PRICING.get(model)

    if not pricing:
        logger.warning(f"No pricing found for model: {model}, using default")
        pricing = {"input": 0.001, "output": 0.002}

    # 计算成本 (per 1K tokens)
    input_cost = (input_tokens / 1000.0) * pricing["input"]
    output_cost = (output_tokens / 1000.0) * pricing["output"]
    total_cost = input_cost + output_cost

    return {
        "input_cost": round(input_cost, 6),
        "output_cost": round(output_cost, 6),
        "total_cost": round(total_cost, 6),
        "currency": "USD",
    }

async def set_cached_response(
    self,
    request: ChatRequest,
    response: ChatResponse,
    ttl: Optional[int] = None
):
    """设置缓存响应"""
    # 流式请求不缓存
    if request.stream:
        return

    try:
        if ttl is None:
            ttl = self.default_ttl

        # 生成缓存键
        cache_key = self._generate_cache_key(request)

        # 序列化响应
        response_dict = response.dict()
        response_json = json.dumps(response_dict, ensure_ascii=False)

        # 保存到 Redis
        self.redis_client.setex(cache_key, ttl, response_json)

        logger.info(f"Cached response for request: {request.model}")
    except Exception as e:
        logger.error(f"Error setting cached response: {e}")
        # 缓存异常不影响主流程，直接返回

sequenceDiagram
    autonumber
    participant Client
    participant Router as FastAPI Router
    participant Service as AdapterService
    participant Cache as RequestCacheService
    participant Redis
    participant Converter as ProtocolConverter
    participant Adapter as OpenAIAdapter
    participant HTTP as httpx.AsyncClient
    participant API as OpenAI API
    participant Cost as CostCalculator

    Client->>Router: POST /api/v1/chat/completions
    Router->>Service: adapter_service.chat(request)
    Service->>Service: _get_provider("gpt-4", None)
    Note over Service: 返回 ("openai", openai_adapter)

    Service->>Cache: get_cached_response(request)
    Cache->>Cache: _generate_cache_key(request)
    Cache->>Redis: GET cache_key
    Redis-->>Cache: None (未命中)
    Cache-->>Service: None

    Service->>Converter: normalize_messages(messages, "openai")
    Converter-->>Service: messages (OpenAI 不需处理)

    Service->>Adapter: adapter.chat(request)
    Adapter->>Adapter: 创建 httpx.AsyncClient
    Adapter->>Adapter: 构建请求 JSON
    Adapter->>HTTP: client.post(url, headers, json)
    HTTP->>API: POST /v1/chat/completions

    Note over API: 模型推理<br/>300-2000ms

    API-->>HTTP: 200 OK + JSON
    HTTP-->>Adapter: response
    Adapter->>Adapter: response.raise_for_status()
    Adapter->>Adapter: data = response.json()
    Adapter->>Adapter: 转换为 ChatResponse
    Adapter-->>Service: ChatResponse

    Service->>Cost: calculate_cost(model, input_tokens, output_tokens)
    Note over Cost: 查询 MODEL_PRICING<br/>计算成本
    Cost-->>Service: cost_info

    Service->>Cache: set_cached_response(request, response)
    Cache->>Cache: _generate_cache_key(request)
    Cache->>Cache: response.dict() + json.dumps()
    Cache->>Redis: SETEX key 3600 response_json
    Redis-->>Cache: OK

    Service-->>Router: ChatResponse
    Router-->>Client: 200 OK + JSON

Client HTTP Request (stream: true)
  ↓
[1] FastAPI Router → 检测 request.stream == True
  ↓
[2] AdapterService.chat_stream（返回 AsyncIterator）
  ↓
[3] _get_provider() 路由选择
  ↓
[4] Provider Adapter.chat_stream
  ↓ [4.1] httpx.AsyncClient.stream() 建立流式连接
  ↓ [4.2] POST with stream: true
  ↓ [4.3] 等待首字节（500-1500ms）
  ↓ [4.4] 循环读取 SSE 数据流
  ↓   [4.4.1] response.aiter_lines()
  ↓   [4.4.2] 解析 "data: {...}" 行
  ↓   [4.4.3] yield 转发给上游
  ↓ [4.5] 检测 "data: [DONE]" 结束
  ↓
[5] FastAPI StreamingResponse 逐块发送
  ↓
Client 实时接收 SSE 数据流

if request.stream:
    # 流式响应
    return StreamingResponse(
        adapter_service.chat_stream(request),
        media_type="text/event-stream",
    )