模型接入与结构化输出生态
比较官方客户端、跨厂商抽象和应用验证的职责与迁移成本。
先决定公共契约覆盖什么
模型客户端处理连接、序列化、流与错误，应用处理用户身份、任务事实和外部效果。统一客户端可以降低切换成本，但模型是否支持 strict schema、工具并行、实时音视频、提示缓存与服务端状态，仍随厂商和模型变化。OpenAI 兼容通常只说明若干 HTTP 请求形状兼容，不能据此认定 Responses、Realtime 或计费字段也相同。
| 路线 | TS／Python 入口 | 能解决的问题 | 需承担的限制 |
|---|---|---|---|
| OpenAI 官方 SDK | openai／openai | Responses、流、文件、实时及相应服务的类型和助手 | 厂商端点能力、大版本迁移及 schema 子集 |
| Claude 官方 SDK | @anthropic-ai/sdk／anthropic | Messages、content blocks、缓存、工具与厂商云接入 | block 和工具结果的语义；beta、GA 与模型支持范围分别核对 |
| Google GenAI | @google/genai／google-genai | Gemini 文本、多模态、实时与云端入口 | 新旧 SDK、generate-content 与较新接口的版本差异 |
| AI SDK | ai、provider 包 | TS 统一生成、输出、工具、嵌入、重排与 UI 传输 | provider 映射面与跟进速度、major 升级 |
| LiteLLM | Python 库或独立 Proxy | 公共调用入口、模型映射及网关治理 | 实际目标能力、依赖与网关运营 |
| instructor | Python 为主，多语言移植 | schema、validator、错误反馈重试及部分对象 | 验证仅覆盖写出的规则；重试成本 |
官方客户端有利于直接使用专属能力；公共抽象有利于维护应用契约。项目可以保留公共入口和少量专属适配器。每个请求记录实际模型、端点、响应身份、终止原因及用量，避免公共接口抹去诊断信息。OpenAI TS SDK、OpenAI Python SDK、Claude SDK、Google GenAI Python、AI SDK、LiteLLM。
结构化输出有三层检查
服务端 schema 约束使生成符合支持的结构，客户端解析核实字段与类型，应用验证核实权限、业务条件和证据。三层的条件不同：拒绝和截断可能走独立事件；部分对象尚未结束；厂商支持的 JSON Schema 子集不包含任意自定义规则。字段描述可以引导生成，无法代替执行验证。
本轮核对的 OpenAI 官方指南用 TS zodTextFormat 和 Python text_format 配合 responses.parse，从 output_parsed 取完整结果，拒绝与未完成状态另行处理。AI SDK 当前官方页用 generateText／streamText 的 output 和 Output.object/array/choice/json；部分对象尚不能按完整 schema 校验，完整元素流具有不同边界。OpenAI 结构化输出、AI SDK 结构化数据。
Zod、Valibot、JSON Schema 可参与 TS 契约；Pydantic 提供 Python schema 与 validator，默认类型转换及 strict 模式需按输入策略选择。instructor 能反馈自定义验证错误并有限重试，也可采用供应商原生模式；它无法自动证明任意语义。模型返回某个来源 ID，还需检查本次资料确实包含该来源、用户可访问它，并且它支持结论。instructor、Pydantic。
供应商特性如何保留
Claude 的文本、工具请求和工具回执使用 content blocks，工具结果需对应原调用身份；提示缓存和思考相关字段在模型及版本间变化。Google 的同步生成、流式、文件和 Live 面向不同生命周期，自动函数调用便利性与宿主授权必须共同考虑。较新 SDK 的 runner 能管理调用循环，应用仍管理允许工具、审批、总预算、取消和幂等。
DeepSeek、百炼 Qwen、Z.AI GLM、Moonshot Kimi 的兼容端点是归档的重要接入路线。百炼的 key、端点和模型受地域影响；兼容接口需逐项核对工具、schema、推理内容、输入缓存与计费字段。Mistral、Cohere 官方客户端适合直接使用本家生成、嵌入或重排；较低星数不能证明客户端能力较差。DeepSeek、百炼兼容说明、Z.AI、Moonshot、Mistral、Cohere。
迁移时检查哪几种版本
归档记录了 AI SDK v5、v6、v7 的接口变化，涉及指令、逐步回调、工具审批、OTel 包和 ESM／Node 要求；也记录 OpenAI Python 3.x HTTP 客户端迁移、Google 新旧 SDK 替换与 Interactions 的演进。这些是历史核查线索，本轮没有复查每个 release 或将其全部作为当前安装指令。采用时阅读所锁定版本的 migration guide，核对 provider、UI 包、schema 库和框架运行时，不能只升级 ai 或厂商主包。AI SDK 迁移指南、OpenAI Python releases、Google GenAI releases。
跨供应商测试至少覆盖拒绝、上限截断、空内容、流中错误、并行工具、部分 JSON、取消和重试。一次重试既增加延迟又可能再次收费，SDK 网络重试、应用格式重试与工具业务重试分别计入总截止时间。
相邻候选的实际定位
LangChain 和 PydanticAI 提供接入加编排，需要按是否使用其运行能力评估依赖；LlamaIndex 的价值主要在资料系统。TS 的 instructor-js、token.js、Python 的 Mirascope、marvin、aisuite 等提供较轻抽象，采用时核对自己需要的接口、社区和迁移成本，归档中的低频发版不能单独作为淘汰理由。
Outlines、Guidance、lm-format-enforcer 等影响本地推理的受限生成，位置接近模型采样；Guardrails 可执行具体验证或防护策略；它们与远程 API 客户端的职责有差异。Ollama 客户端接本地服务，不能因官方云 SDK 已支持结构化输出便认定其失去用途。Outlines、Guidance、Mirascope、Ollama API。
本页比较来源于两种语言的 SDK 方向稿与总稿，版本及覆盖变化按上述限定；没有进行供应商延迟、质量或相同 schema 的成功率实测。
最后更新于