核心难点是抹平不同厂商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 输入）。从最小可用开始，再逐步加固。
