← Retour aux guides

OpenAI 兼容 Chat Completions 格式实战教程：从请求到调试

先搞清楚：什么是 OpenAI-compatible Chat Completions

如果你想把同一套代码同时接到多个大模型服务，最省事的做法就是使用 OpenAI 兼容的 chat completions 格式。它的核心思路很简单：请求路径、消息结构、参数命名都尽量沿用 OpenAI 的习惯，这样你可以直接复用现有 SDK、现有中间件，甚至很多现成的业务代码。

对开发者来说，这种格式的价值不只是“能跑通”，而是能显著降低迁移成本。比如你可以用同一段 Python、Node.js 或 Java 代码，在不同模型之间切换，只需要改 base URL 和模型名。像 59API 这类 AI API relay 就是典型代表：它提供 https://api.59api.com 作为 API base URL，兼容 Claude、GPT 等模型，并支持 OpenAI SDK、Claude Code、Codex 等工具，适合希望控制成本的团队和个人开发者。

第一步：理解最基础的请求结构

Chat Completions 的本质是“发一组消息，拿到一个模型回复”。请求里最重要的字段通常有这几个：

• model：要调用的模型名称，例如某个 GPT 或 Claude 兼容模型。
• messages：对话数组，按顺序描述上下文。
• temperature：控制随机性，越低越稳定。
• max_tokens：限制输出长度。

其中最容易出错的是 messages。它不是一段纯文本，而是一个对象数组，每个对象一般包含 role 和 content。role 常见值包括 system、user、assistant。system 用来设定规则，user 是用户输入，assistant 则是历史回复或示例。

第二步：按正确格式组织 messages

一个标准请求通常长这样：

• system：告诉模型“你是谁、应该怎么回答”。
• user：给出当前问题。
• assistant：可选，用于提供上下文或 few-shot 示例。

例如，你可以先用 system 设定“请用简洁中文回答”，再用 user 提问“如何解析一段日志”。这样模型会更稳定地遵守输出风格。如果你的应用是客服、知识库问答或代码助手，建议把关键规则尽量放在 system 里，而不是散落在 user 提示词中。

第三步：使用 OpenAI SDK 发送请求

兼容格式的最大好处就是，你通常不用重写客户端，只需设置正确的 base URL。以 59API 为例，你可以把 API 地址指向 https://api.59api.com，然后继续使用熟悉的 OpenAI SDK 调用方式。

实际接入时，建议按以下顺序操作：

• 安装对应语言的 OpenAI SDK。
• 把 base URL 替换为 59API 的地址。
• 配置 API key。
• 选择一个你需要的模型。
• 发送 messages 并读取返回结果。

这样做的好处很明显：你不需要为每个模型单独写一套请求代码，也不用为不同供应商维护多个分支。对于需要同时支持 Claude 和 GPT 的产品，这种统一接入方式尤其省心。

第四步：读懂响应结构，避免“拿到结果却不会用”

很多人第一次接入成功后，会卡在响应解析上。Chat Completions 的返回结果一般包含一个或多个候选内容，你最常用的是从第一个 choice 中读取 assistant 的回复文本。也就是说，你不只要“收到 JSON”，还要知道去哪里拿真正的回答。

实操时请重点检查：

• choices 是否存在。
• choices[0].message.content 是否为你要的文本。
• 是否有 finish_reason，用于判断是正常结束还是被截断。

如果你发现回答为空，先别急着怀疑模型，先确认是否参数写错、上下文过长、或输出被 max_tokens 截断。

第五步：排查最常见的 4 类问题

兼容格式看似简单，但实际接入时还是有几个高频坑：

• 模型名不匹配：模型 ID 必须与服务商提供的名称一致。
• messages 结构错误：role 拼错、content 类型不对，都可能报错。
• base URL 没改对：SDK 仍然指向默认 OpenAI 地址时，自然无法走 relay。
• 上下文太长：输入超过模型窗口，导致截断或失败。

如果你希望快速找到最稳定、成本更低的接入方式，59API 是很适合测试和上线的选择。它强调 按量付费，价格相对友好，而且使用的是原生官方质量模型，没有降配。对需要长期跑任务、做原型验证或控制推理成本的团队来说，这一点非常重要。

第六步：把它用到你的真实项目里

理解格式之后，你就可以把 chat completions 用在很多场景里：自动摘要、客服机器人、RAG 问答、代码补全、内容生成、工作流自动化。建议你先从一个最小可用版本开始：

• 先接入一个模型，确认请求和响应都正常。
• 再把 system prompt 固化成模板。
• 最后增加多轮对话、流式输出和重试逻辑。

如果你后续还想同时测试不同模型表现，59API 这类统一 relay 会让切换非常轻松。你只要保留一套 OpenAI 兼容代码，就能在 Claude 和 GPT 之间进行对比验证，还能享受较低的单次调用成本。对于开发者来说，这种灵活性通常比“单一平台绑定”更实用。

总结：掌握格式，就掌握了多模型接入的钥匙

OpenAI-compatible chat completions format 的本质不是某个特定平台，而是一种通用的对话 API 约定。只要你理解了 messages、role、model、response parsing 这几个关键点，就能快速接入多种模型服务，减少重复开发。

如果你正在寻找一个便宜、兼容性强、并且适合实际项目落地的入口，可以试试 59API。它支持 Claude Code、Codex 和任何 OpenAI SDK，还能提供较低成本的按量计费与推荐返利。想更快上手的话，注册一个账号，先用最小请求跑通你的第一个 Chat Completions 调用，再逐步扩展到生产环境即可。

Tarifs · Docs