核心难点是抹平不同厂商API差异，需设计轻量抽象层：统一AIRequest/AIResponse结构，用适配器模式封装各Provider，通过工厂路由自动选择，支持重试、限流、日志、缓存等横切能力。

Python 调用大模型 API 的核心难点，不是写几行代码发请求，而是如何把不同厂商（如 OpenAI、Qwen、GLM、DeepSeek、Moonshot）的接口差异“抹平”，让业务代码不随模型切换而重写。统一封装智能能力，关键在设计一层轻量、可扩展、易维护的抽象层。

统一输入输出结构：定义你的 AIRequest 和 AIResponse

别让每个模型自己解析 prompt、处理流式响应、拼接 content。定义两个基础数据类：

• AIRequest：包含 messages（标准 ChatML 格式列表）、model（字符串标识）、temperature、max_tokens、stream 等通用字段；可选扩展 tools、tool_choice 支持函数调用
• AIResponse：统一返回 content: str、finish_reason: str、usage: dict、raw: dict（原始响应体，供调试或特殊字段提取）

用 pydantic.BaseModel 实现，自动校验 + IDE 友好 + 序列化方便。

适配器模式：为每个厂商写一个 Provider

每个 Provider 是一个独立类，实现统一接口 async def chat(self, req: AIRequest) -> AIResponse。例如：

立即学习“Python免费学习笔记（深入）”；

• OpenAIProvider：用 httpx.AsyncClient 调 /v1/chat/completions，把 req.messages 直接传入，再把 response 映射到 AIResponse
• QwenProvider：适配通义千问的 /api/v1/services/aigc/text-generation/generation，需转换 role（user/system/assistant → user/system/assistant 通常一致，但注意 system 是否支持）和参数名（temperature → top_p？看文档）
• GLMProvider：智谱 API 需 sign 签名，且流式响应格式是 SSE，要单独解析 data: {...} 行

所有适配逻辑收在 provider 内部，上层业务完全无感。

路由与工厂：用模型名自动选择 Provider

不要在业务里写 if model == "qwen": ... elif model == "glm": ...。建一个简单工厂：

class AIProviderFactory:
    _providers = {
        "gpt-4o": OpenAIProvider,
        "qwen-max": QwenProvider,
        "glm-4-flash": GLMProvider,
        "deepseek-chat": DeepSeekProvider,
    }

    @classmethod
    def get(cls, model: str) -> BaseProvider:
        provider_cls = cls._providers.get(model)
        if not provider_cls:
            raise ValueError(f"Unsupported model: {model}")
        return provider_cls()

调用时只需：provider = AIProviderFactory.get(req.model); resp = await provider.chat(req)。新增模型？加一行配置即可。

增强能力：插件化支持重试、限流、日志、缓存

封装层的价值不止于兼容，更在于可叠加横切能力：

• 重试：对网络错误、503、rate limit 响应，自动指数退避重试（用 tenacity）
• 限流：按模型维度配置 QPS，用 aiolimiter 控制并发
• 日志：记录请求 ID、模型名、耗时、token 数、是否流式，便于追踪和计费对账
• 缓存：对确定性请求（非 stream / 不含时间变量），用 aiocache 缓存响应，降低延迟与成本

这些能力以装饰器或中间件方式注入 provider，不影响核心适配逻辑。

不复杂但容易忽略：真正决定封装成败的，不是代码量，而是你是否提前想清楚——哪些字段必须统一（比如 messages 结构）、哪些可以容忍差异（比如 stop 参数行为）、哪些能力暂不支持（比如 vision 输入）。从最小可用开始，再逐步加固。