OpenAI 兼容性 API chat completion 报文结构 • AiLinkLab Blog

开篇闲聊

不要把大模型的 API 理解成一个黑盒，而是要理解它的内部结构，这样才能更好地使用它。这里我们就把大模型的 API 当做一个一般性的 API来理解。了解 API 的参数的含义，对 AI 模型的能力就有了一个更好的理解。

如果想了解更多关于 OpenAI API 的信息，可以参考以下链接： OpenAI的完整接口标准定义文档

为什么要了解 OpenAI 的接口？原因很简单：

OpenAI 是行业的先行者，他们的接口设计已经成为了一种标准
现在市面上很多大模型都在兼容 OpenAI 的接口，了解这个就等于掌握了一把万能钥匙
理解接口的每个参数，就能更好地控制 AI 模型的行为

Chat Completion 接口：最常用的对话接口

OpenAI 的完整报文 Schema 定义参见链接，内容太多，重点聊下几个重要的部分。

以下是 /chat/completions 接口的 Body 报文结构说明：

字段名	类型	必填	默认值	描述
`model`	string	是	-	模型名称，可选值具体模型文档
`messages`	object[]	是	-	对话消息列表，包含 `role`（`user`/`assistant`/`system`/`tools`）和 `content`（消息内容）。
`stream`	boolean	否	`false`	是否启用流式返回，启用时 tokens 以 Server-Sent Events 形式返回。
`max_tokens`	integer	否	`512`	生成的最大 token 数，范围：`1 < x < 8192`。
`stop`	string[]/null	否	`["null"]`	终止生成的序列（最多 4 个），返回文本不包含该序列。
`temperature`	number	否	`0.7`	控制输出随机性，值越高随机性越强（范围通常为 0-2）。
`top_p`	number	否	`0.7`	核采样参数，动态调整预测 token 的选择范围。
`top_k`	number	否	`50`	采样时考虑的 top-k 个 token。
`frequency_penalty`	number	否	`0.5`	频率惩罚，抑制重复 token 的生成。
`n`	integer	否	`1`	生成结果的数量。
`response_format`	object	否	`{"type": "text"}`	输出格式对象。
`tools`	object[]	否	-	工具调用列表（函数调用），包含 `type: "function"` 和函数元数据。

示例请求 Body

{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "2025年将会迎来哪些机遇和挑战？"
    }
  ],
  "stream": false,
  "max_tokens": 512,
  "temperature": 0.7,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "analyze_industry_trend",
        "description": "分析大模型行业趋势",
        "parameters": {
          "year": 2025,
          "region": "中国"
        }
      }
    }
  ]
}

核心参数解析

选择你的 AI 搭档（model）

"model": "gpt-3.5-turbo"

这就像是在选择不同级别的老师，有的擅长创意写作，有的擅长代码分析。不同模型的能力和价格都不一样，你可以根据需求选择。

对话历史（messages）

这就是你和 AI 的聊天记录，包含几种角色：

user（你）：发问的人
assistant（AI）：回答的助手
system（系统）：像是在给 AI 定规矩
tools（工具）：AI 使用工具后返回的结果

控制 AI 的发挥程度

temperature （温度）：范围 0-2
- 设为 0：AI 变得严谨保守，回答很确定
- 设为 1：AI 会适当发挥，回答更有创意
- 设为 2：AI 天马行空，回答很有想象力
max_tokens （字数限制）：
- 想象成给 AI 限定写作的字数
- 一个汉字大约等于 2 个 tokens
- 设置合理的值可以避免浪费和超支

让对话更流畅（stream）

"stream": true

开启这个选项，AI 的回答会像人类打字一样一个字一个字地显示，而不是一次性蹦出来，体验更好。

避免重复（frequency_penalty 和 presence_penalty）

frequency_penalty （词频惩罚）：
- 正值（0.1 到 2.0）：让 AI 少用重复的词
- 负值（-2.0 到 -0.1）：鼓励 AI 重复使用词语
- 0：保持中立，不干预
presence_penalty （主题惩罚）：
- 正值：鼓励 AI 聊新话题
- 负值：让 AI 继续深入当前话题
- 0：自然过渡

采样控制（top_p 和 top_k）

top_p （核采样）：
- 范围 0-1，默认 0.7
- 值越小，AI 回答越保守
- 值越大，AI 回答越多样
- 建议不要和 temperature 一起调整
top_k （Top-K 采样）：
- 默认值 50
- 控制 AI 每次选词时考虑的候选词数量
- 数值越小，回答越保守

多样性输出（n）

"n": 3

让 AI 一次给出多个不同的回答
默认值是 1
数值越大，API 费用越高
建议配合高 temperature 使用

格式控制（response_format）

"response_format": {"type": "json_object"}

控制 AI 回答的格式
text ：普通文本（默认）
json_object ：JSON 格式

终止序列（stop）

"stop": ["结束", "完毕"]

设置特定的词语作为回答的终止标记
最多可以设置 4 个终止序列
AI 遇到这些词就会停止生成

工具调用（tools） tools 参数让 AI 能够调用外部工具来完成特定任务。这就像给 AI 配备了一个工具箱，需要时可以拿出合适的工具来用。

"tools": [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的天气信息
            ",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称
                        "
                    },
                    "date": {
                        "type": "string",
                        "description": "查询日
                        期，格式：YYYY-MM-DD"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

工具参数说明

type ：工具类型
- 目前主要支持 “function”（函数调用）
- 未来可能会支持更多类型
function ：函数定义
- name ：函数名称，要简单明确
- description ：函数功能描述
- parameters ：函数参数定义
  - 使用 JSON Schema 格式
  - 可以定义必填和选填参数
  - 支持各种数据类型

实用小技巧

创意性任务（如写故事）：
- 调高 temperature（0.8-1.0）
- 适当提高 top_p（0.9）
- 可以设置多个候选答案（n > 1）
严谨性任务（如代码生成）：
- 调低 temperature（0.2-0.4）
- 降低 top_p（0.5）
- 使用 system 角色设定严格的规则
长对话场景：
- 合理设置 max_tokens
- 使用 presence_penalty（0.3-0.5）避免话题重复
- 可以考虑开启 stream 提升体验
控制成本：
- 设置合适的 max_tokens
- 避免过高的 n 值
- 必要时才开启 stream