大模型API文档对比：先比这几类信息，再决定接入哪家
文档对比到底在比什么
大模型API文档对比的核心不是比谁的页面好看，而是比照着文档能不能一次接对、出错能不能自己查明白。
同一个功能，有的文档给出完整请求示例和字段默认值，有的只给一句描述，接入成本差好几倍。
判断标准可以落到六个方面：鉴权方式是否写清、请求参数是否有默认值和取值范围、错误码是否覆盖常见失败、流式返回格式是否明确、限流和配额是否有说明、版本变更是否有记录。
这六项直接决定你调试时是查文档还是猜。
六项对比清单
鉴权与请求入口
先看鉴权头怎么写、Key 放在哪个位置、Base URL 是否区分区域。
文档如果只写“使用 API Key 鉴权”而不给完整请求头示例，接入时很容易在 401 上耗时间。
对比时记录：鉴权头名称、Key 前缀格式、是否有临时凭证或多区域入口。
请求参数与默认值
重点看 temperature、max_tokens、top_p 这类采样参数是否标注默认值和取值范围，以及超长输入怎么处理。
文档给了默认值，你才能判断“输出被截断”是参数问题还是模型行为。
缺少默认值说明的文档，排错成本会明显上升。
错误码与失败语义
好的文档会列出 400、401、429、500 各自对应什么原因，以及 error 字段的结构。
对比时留意：限流返回的是 429 还是别的状态码、响应体里有没有 retry_after 之类的重试提示。
这决定你的重试逻辑能不能写对。
流式返回格式
流式接口要看清分块格式，比如是否使用 data: 前缀、结束标记是什么、最后一个块是否包含用量统计。
文档只写“支持流式输出”而不给分块示例，客户端解析很容易在结尾卡住。
限流与配额说明
文档应说明限流维度是每分钟请求数还是 token 数、超限后的行为、配额周期。
没有这些说明，压测和容量规划只能靠试。
版本与变更记录
看是否有 changelog 或版本号，参数废弃是否提前公告。
文档长期不更新，意味着你按它写的代码可能随时对不上线上行为。
用最小请求做交叉验证
文档写得再好也要验证。
准备一个最小请求，逐项核对文档描述与实际返回是否一致：
curl -s https://api.example-provider.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"your-model","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'把 example-provider.com 换成实际服务商域名即可。
验证时重点看三处：返回的字段名和文档是否一致、错误时 error 结构是否和文档示例相同、流式模式下结束块是否符合描述。
发现不一致就以实际返回为准，并在代码里做好兼容。
容易踩的坑
- 只对比“能不能调通”，忽略错误码和限流说明，上线后遇到 429 才发现没有重试依据。
- 把文档里的示例参数直接当生产配置，没注意
max_tokens默认值导致输出被截断。 - 流式解析只按文档示例写死结束标记，服务端格式微调后客户端卡住。
- 忽略版本变更记录，参数废弃后接口报错才回头查文档。
怎么下结论
如果只是做原型验证，优先选请求示例完整、错误码清晰的文档；
如果要长期运行，限流说明和变更记录权重更高。
文档对比的结论应写成一张对照表，把六项逐条打分，再结合自己的调用量和排错能力决定，而不是只看哪家接口看起来更简单。
常见疑问
文档详细就一定好用吗？ 不一定。
有些文档篇幅长但关键默认值和错误码缺失，对比时要看信息是否完整，而不是看页数。
没有 changelog 的服务商能选吗？ 可以选，但要接受参数变更时排查成本更高，建议在代码里对关键字段做兼容处理。
对比时要不要实际压测？ 文档对比阶段用最小请求验证即可，压测属于性能评估，应在确定候选后再做。
