OpenAI Chat Completions API 完整参考手册
接口地址:
POST https://api.openai.com/v1/chat/completions
文档版本:2026-04
适用模型:GPT-4o、GPT-4-turbo、GPT-3.5-turbo 及兼容 OpenAI 协议的第三方服务
目录
1. 请求结构总览
{
"model": "gpt-4o",
"messages": [...],
// 生成控制
"temperature": 1,
"top_p": 1,
"max_completion_tokens": 4096,
"n": 1,
"stop": null,
"presence_penalty": 0,
"frequency_penalty": 0,
"logit_bias": {},
"logprobs": false,
"top_logprobs": null,
"seed": null,
// 工具调用
"tools": [...],
"tool_choice": "auto",
"parallel_tool_calls": true,
// 结构化输出
"response_format": {"type": "text"},
// 流式
"stream": false,
"stream_options": null,
// 其他
"user": "",
"store": false,
"metadata": {},
"reasoning_effort": null,
"modalities": ["text"],
"service_tier": "auto"
}
2. 必填参数
| 参数 | 类型 | 说明 |
|---|---|---|
model | string | 模型 ID,如 gpt-4o、gpt-4-turbo、gpt-3.5-turbo |
messages | array | 对话消息列表,至少包含一条消息,详见第 3 节 |
3. messages 消息协议
messages 是一个有序数组,模拟完整的对话历史。每轮请求都需要传入完整的历史消息,模型无状态。
3.1 system 消息
设定模型的角色、行为和约束,通常放在数组首位。
{
"role": "system",
"content": "你是一个专业的天气查询助手,只回答与天气相关的问题。",
"name": "weather_bot" // 可选,用于区分多个 system 消息
}
3.2 user 消息
用户输入,支持纯文本或多模态内容。
// 纯文本
{
"role": "user",
"content": "北京今天天气怎么样?"
}
// 多模态(文本 + 图片)
{
"role": "user",
"content": [
{"type": "text", "text": "这张图片里有什么?"},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.jpg",
"detail": "auto" // auto | low | high
}
}
]
}
3.3 assistant 消息
模型的历史回复,回传时需原样保留。若上一轮模型发起了工具调用,tool_calls 字段必须一并保留。
// 普通回复
{
"role": "assistant",
"content": "北京今天晴,气温 22°C。"
}
// 含工具调用的回复
{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\": \"北京\"}" // JSON 字符串,需 JSON.parse 解析
}
}
]
}
3.4 tool 消息
工具执行结果,用于将调用结果回传给模型。tool_call_id 必须与 assistant 消息中对应的 id 匹配。
{
"role": "tool",
"tool_call_id": "call_abc123",
"content": "{\"temperature\": 22, \"condition\": \"晴转多云\"}"
}
3.5 消息顺序约束
system(可选)→ user → assistant → tool → user → assistant → ...
- 每轮对话必须以
user或tool消息结尾(发起新请求时) tool消息必须紧跟在包含tool_calls的assistant消息之后- 并行工具调用时,所有工具结果必须全部回传后才能继续对话
4. 生成控制参数
4.1 随机性控制
| 参数 | 类型 | 默认值 | 范围 | 说明 |
|---|---|---|---|---|
temperature | number | 1 | 0 ~ 2 | 越高输出越随机,越低越确定性。不建议同时调整 temperature 和 top_p |
top_p | number | 1 | 0 ~ 1 | 核采样,只从累计概率达到该值的 token 中采样。0.1 表示只考虑最可能的前 10% |
seed | integer | — | — | 随机种子,相同 seed 在相同条件下尽量复现相同输出 |
temperature 与 top_p 的决策指南
核心原则:两者只调其一,另一个保持默认值。
temperature 调节逻辑
temperature 通过缩放 softmax 概率分布来控制随机性:
- 值趋近
0:分布极度集中,每次几乎选最高概率 token,输出高度确定、可复现 - 值为
1(默认):保持模型原始概率分布,平衡创意与准确性 - 值趋近
2:分布极度平坦,低概率 token 也有机会被选中,输出随机甚至混乱
| 场景 | 推荐值 | 说明 |
|---|---|---|
| 代码生成、数学计算、数据提取 | 0 ~ 0.2 | 要求准确,不允许随机发挥 |
| 问答、摘要、翻译 | 0.3 ~ 0.7 | 需要准确但允许适当表达变化 |
| 通用对话、客服助手 | 0.7 ~ 1.0 | 平衡自然流畅与准确性 |
| 头脑风暴、创意写作、故事生成 | 1.0 ~ 1.5 | 鼓励多样化和意外创意 |
| 诗歌、高度实验性内容 | 1.5 ~ 2.0 | 极度随机,慎用 |
top_p 调节逻辑
top_p 采用核采样(Nucleus Sampling),动态截断概率分布的尾部:
- 值为
1.0(默认):考虑全部 token,不做截断 - 值为
0.9:只从累计概率前 90% 的 token 中采样,排除低概率的长尾噪声 - 值为
0.1:只考虑最核心的少量 token,极度保守
| 场景 | 推荐值 | 说明 |
|---|---|---|
| 需要消除低概率噪声 | 0.8 ~ 0.95 | 保留主流选择,去除异常 token |
| 通用场景 | 1.0 | 保持默认,不干预分布 |
| 极度保守输出 | 0.1 ~ 0.5 | 输出非常集中,适合格式严格的任务 |
temperature vs top_p 选哪个?
需要控制"输出的随机程度" → 调 temperature(更直观)
需要控制"候选词的范围大小" → 调 top_p(更精细)
两者不要同时偏离默认值 → 否则效果叠加,难以预测
常用组合速查
| 任务类型 | temperature | top_p | 效果 |
|---|---|---|---|
| 代码补全 | 0.0 | 1.0 | 确定性最强,首选方案 |
| 数据抽取 / JSON 输出 | 0.1 | 1.0 | 几乎无随机,结构稳定 |
| 问答 / 摘要 | 0.5 | 1.0 | 略带变化,表达自然 |
| 通用对话 | 1.0 | 1.0 | 模型默认行为 |
| 创意写作 | 1.2 | 1.0 | 增加创意多样性 |
| 头脑风暴 | 1.0 | 0.95 | 过滤极低概率词,保持创意 |
4.2 长度控制
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
max_completion_tokens | integer | 模型上限 | 最大生成 token 数,包含推理模型的思考 token(推荐使用此参数) |
max_tokens | integer | — | 已废弃,功能同上,请改用 max_completion_tokens |
n | integer | 1 | 每次请求返回的候选回复数量,n > 1 时消耗更多 token |
stop | string / array | null | 遇到指定字符串时停止生成,最多指定 4 个停止词 |
4.3 重复惩罚
| 参数 | 类型 | 默认值 | 范围 | 说明 |
|---|---|---|---|---|
presence_penalty | number | 0 | -2.0 ~ 2.0 | 正值惩罚已出现过的 token,鼓励模型引入新话题 |
frequency_penalty | number | 0 | -2.0 ~ 2.0 | 正值惩罚高频 token,减少词汇重复 |
logit_bias | object | null | — | 直接调整指定 token 的概率,格式 {"token_id": bias},bias 范围 -100 ~ 100 |
4.4 概率分析
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
logprobs | boolean | false | 是否在响应中返回每个 token 的对数概率 |
top_logprobs | integer | — | 每个位置返回概率最高的前 N 个 token 及其概率,需先开启 logprobs,最大值 20 |
5. tools 工具调用协议
工具调用(Function Calling)允许模型在生成回复时决定调用外部函数,并将调用参数结构化输出。
5.1 顶层参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
tools | array | — | 工具定义列表,每项描述一个可调用的函数 |
tool_choice | string / object | "auto" | 控制模型是否及如何调用工具,见 5.3 节 |
parallel_tool_calls | boolean | true | 是否允许模型在一次回复中并行调用多个工具 |
5.2 单个工具的完整结构
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的天气预报,支持查询未来多天的天气数据",
"strict": false,
"parameters": {
"type": "object",
"properties": {
// 字符串类型
"city": {
"type": "string",
"description": "城市名称,如北京、上海、广州"
},
// 枚举类型
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "温度单位,默认摄氏度"
},
// 整数类型(含范围约束)
"days": {
"type": "integer",
"minimum": 1,
"maximum": 7,
"description": "查询未来几天的天气,1~7"
},
// 数组类型
"fields": {
"type": "array",
"items": {
"type": "string",
"enum": ["temperature", "humidity", "wind", "uv_index"]
},
"description": "指定返回的数据字段"
},
// 嵌套对象
"location": {
"type": "object",
"properties": {
"lat": {"type": "number", "description": "纬度"},
"lng": {"type": "number", "description": "经度"}
},
"required": ["lat", "lng"]
}
},
"required": ["city"],
"additionalProperties": false
}
}
}
function 字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | ✅ | 函数名,仅允许 a-z A-Z 0-9 _ -,最长 64 字符 |
description | string | 推荐 | 函数用途说明,越详细模型调用越准确 |
parameters | object | — | 参数定义,遵循 JSON Schema Draft 7,无参函数可省略 |
strict | boolean | — | 开启后强制模型严格按 schema 生成参数,默认 false |
parameters 支持的 JSON Schema 关键字
| 关键字 | 适用类型 | 说明 |
|---|---|---|
type | 所有 | string / number / integer / boolean / array / object / null |
description | 所有 | 字段说明,帮助模型理解含义 |
enum | string / number | 枚举可选值列表 |
required | object | 必填字段列表 |
properties | object | 子字段定义 |
additionalProperties | object | false 禁止额外字段 |
items | array | 数组元素的类型定义 |
minimum / maximum | number / integer | 数值范围约束 |
minLength / maxLength | string | 字符串长度约束 |
minItems / maxItems | array | 数组长度约束 |
pattern | string | 正则表达式约束 |
$ref / $defs | 所有 | 引用复用定义(strict 模式支持) |
anyOf | 所有 | strict 模式下表示可选字段(配合 null) |
5.3 tool_choice 详细说明
// 禁止调用任何工具,模型只生成文本
"tool_choice": "none"
// 模型自行判断是否调用工具(默认值)
"tool_choice": "auto"
// 必须调用至少一个工具
"tool_choice": "required"
// 强制调用指定工具
"tool_choice": {
"type": "function",
"function": {"name": "get_weather"}
}
5.4 strict 模式约束
开启 "strict": true 时,parameters schema 必须满足:
- 所有
object层级必须设置"additionalProperties": false - 所有
properties中的字段必须全部列在required中 - 可选字段使用
anyOf: [{"type": "xxx"}, {"type": "null"}]表示 - 支持通过
$defs定义可复用结构
// strict 模式下的可选字段写法
"email": {
"anyOf": [
{"type": "string"},
{"type": "null"}
],
"description": "邮箱地址,无则传 null"
}
6. response_format 结构化输出
控制模型输出的格式,共三种模式。
6.1 三种模式对比
| 模式 | 保证合法 JSON | 保证结构符合 Schema | 实现机制 | 适用场景 |
|---|---|---|---|---|
text | ❌ | ❌ | — | 普通对话 |
json_object | ✅ | ❌ | Prompt 引导 | 简单 JSON 输出 |
json_schema | ✅ | ✅ | 约束解码 | 关键数据提取、程序直接消费 |
6.2 text 模式(默认)
{"type": "text"}
普通文本输出,无任何格式约束。
6.3 json_object 模式
{"type": "json_object"}
保证输出是合法 JSON,但不约束结构。
- 使用前必须在
messages中明确要求模型输出 JSON,否则 API 报错 - 字段名、层级、类型完全依赖 prompt 描述,模型可能随意增减字段
- 适合对结构精确度要求不高的场景
// 可能的输出(结构不可控,有额外字段风险)
{"city": "北京", "temp": 22, "extra": "模型自行添加的字段"}
6.4 json_schema 模式(Structured Outputs)
{
"type": "json_schema",
"json_schema": {
"name": "schema_name",
"description": "可选说明",
"schema": { ... },
"strict": true
}
}
通过约束解码(Constrained Decoding)强制输出严格符合 schema 的 JSON,strict: true 时准确率 100%。
json_schema 字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | ✅ | Schema 名称,仅允许 a-z A-Z 0-9 _ -,最长 64 字符 |
description | string | — | Schema 用途说明,辅助模型理解意图 |
schema | object | ✅ | 标准 JSON Schema(Draft 7),根类型必须是 object |
strict | boolean | 推荐 | true 时开启强约束,保证 100% 符合结构,默认 false |
strict: true 时 schema 要求
- 根类型必须为
object(不能是 array 或 string) - 所有
object层级必须设置"additionalProperties": false - 所有
properties字段必须全部列在required中 - 可选字段使用
anyOf: [{"type": "xxx"}, {"type": "null"}]
完整示例
{
"model": "gpt-4o-2024-08-06",
"messages": [
{"role": "user", "content": "提取人员信息:张三是CEO,李四是CTO,邮箱 li4@corp.com"}
],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "people_extraction",
"description": "从文本中提取人员姓名、职位和邮箱",
"strict": true,
"schema": {
"type": "object",
"properties": {
"people": {
"type": "array",
"description": "人员列表",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "姓名"
},
"title": {
"type": "string",
"description": "职位"
},
"email": {
"anyOf": [
{"type": "string"},
{"type": "null"}
],
"description": "邮箱,没有则为 null"
}
},
"required": ["name", "title", "email"],
"additionalProperties": false
}
}
},
"required": ["people"],
"additionalProperties": false
}
}
}
}
模型严格返回:
{
"people": [
{"name": "张三", "title": "CEO", "email": null},
{"name": "李四", "title": "CTO", "email": "li4@corp.com"}
]
}
6.5 json_object vs json_schema 核心区别
json_object: prompt 描述 → 模型"尽力"输出 JSON → 结构不保证
json_schema: schema 约束 → 约束解码 → 输出 100% 符合结构
| 维度 | json_object | json_schema |
|---|---|---|
| 实现机制 | Prompt 引导(软约束) | 约束解码(硬约束) |
| 结构保证 | ❌ 依赖 prompt 质量 | ✅ strict=true 时 100% 保证 |
| 多余字段 | 可能出现 | 不会出现 |
| 缺失字段 | 可能出现 | 不会出现 |
| 类型错误 | 可能出现 | 不会出现 |
| 模型要求 | 较宽泛 | gpt-4o-2024-08-06 及以上 |
| 适用场景 | 简单/非关键 JSON | 关键数据提取、代码直接消费 |
7. 流式输出
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
stream | boolean | false | 开启后以 SSE(Server-Sent Events)逐 token 流式返回 |
stream_options | object | — | {"include_usage": true} 在最后一帧附带 token 用量统计 |
流式响应格式(每帧):
data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"北"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"京"},"finish_reason":null}]}
...
data: {"id":"chatcmpl-xxx","choices":[{"delta":{},"finish_reason":"stop"}]}
data: [DONE]
8. 其他参数
| 参数 | 类型 | 说明 |
|---|---|---|
user | string | 终端用户唯一标识符,用于平台侧的滥用监控和审计 |
store | boolean | 是否将本次请求存储用于 Dashboard 查看或 Fine-tuning(默认 false) |
metadata | object | 自定义键值对,随请求存储,最多 16 个键,可用于业务标注 |
reasoning_effort | string | 推理模型(o1/o3 系列)的思考强度:"low" / "medium" / "high" |
modalities | array | 指定输出模态:["text"] 或 ["text", "audio"](需模型支持音频) |
audio | object | 音频输出配置:{"voice": "alloy", "format": "mp3"} |
prediction | object | 预测输出(Predicted Outputs),提供预期内容以加速生成 |
service_tier | string | 服务等级:"auto" / "default" / "flex"(影响优先级和限速) |
9. 响应体结构
9.1 普通文本回复
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1712345678,
"model": "gpt-4o-2024-08-06",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "北京今天晴,气温 22°C。",
"tool_calls": null,
"refusal": null
},
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 28,
"completion_tokens": 15,
"total_tokens": 43,
"prompt_tokens_details": {
"cached_tokens": 0,
"audio_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"system_fingerprint": "fp_abc123"
}
9.2 含 tool_calls 的回复
当模型决定调用工具时,finish_reason 为 "tool_calls",content 为 null,tool_calls 数组包含所有调用信息。
{
"id": "chatcmpl-xyz789",
"object": "chat.completion",
"created": 1712345678,
"model": "gpt-4o-2024-08-06",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": null, // 有 tool_calls 时 content 为 null
"refusal": null,
"tool_calls": [
{
"id": "call_abc111", // 唯一调用 ID,回传结果时必须对应
"type": "function", // 目前固定为 "function"
"function": {
"name": "get_weather", // 调用的函数名
"arguments": "{\"city\": \"北京\", \"days\": 3}" // JSON 字符串,需 json.loads() 解析
}
},
{
"id": "call_abc222", // 并行调用第二个工具
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\": \"上海\", \"days\": 3}"
}
}
]
},
"logprobs": null,
"finish_reason": "tool_calls" // 标志:需要执行工具并回传结果
}
],
"usage": {
"prompt_tokens": 85,
"completion_tokens": 42,
"total_tokens": 127,
"prompt_tokens_details": {
"cached_tokens": 0,
"audio_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"system_fingerprint": "fp_abc123"
}
tool_calls 数组中每个元素的字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 本次调用的唯一 ID,格式如 call_xxxxxxxx,回传 tool 消息时必须填入 tool_call_id |
type | string | 固定为 "function" |
function.name | string | 模型决定调用的函数名,与 tools 定义中的 name 对应 |
function.arguments | string | 模型生成的调用参数,是 JSON 字符串,需手动 json.loads() 解析后使用 |
收到 tool_calls 后的处理流程
1. 检查 finish_reason === "tool_calls"
2. 将整个 assistant message(含 tool_calls)原样追加到 messages
3. 遍历 tool_calls 数组,逐个执行对应函数
4. 每个工具结果以 role: "tool" 消息追加,tool_call_id 必须与 id 对应
5. 全部结果追加完成后,发起下一轮请求
// 回传工具结果的消息格式(每个 tool_call 对应一条)
{
"role": "tool",
"tool_call_id": "call_abc111", // 对应 tool_calls[i].id
"content": "{\"city\":\"北京\",\"temperature\":18,\"condition\":\"晴\"}"
},
{
"role": "tool",
"tool_call_id": "call_abc222", // 对应 tool_calls[i].id
"content": "{\"city\":\"上海\",\"temperature\":15,\"condition\":\"小雨\"}"
}
finish_reason 枚举值
| 值 | 含义 |
|---|---|
stop | 模型正常结束生成 |
tool_calls | 模型发起了工具调用,需要执行后回传结果 |
length | 达到 max_completion_tokens 限制被截断 |
content_filter | 内容被安全过滤拦截 |
null | 流式输出中间帧 |
10. 完整请求示例
curl https://api.openai.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-4o",
"messages": [
{"role": "system", "content": "你是一个专业的天气查询助手"},
{"role": "user", "content": "查一下北京未来3天的天气"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市未来若干天的天气预报",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称"
},
"days": {
"type": "integer",
"minimum": 1,
"maximum": 7,
"description": "查询天数"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "温度单位"
}
},
"required": ["city"]
}
}
}
],
"tool_choice": "auto",
"parallel_tool_calls": true,
"temperature": 0.7,
"max_completion_tokens": 1024
}'
11. 多轮工具调用完整流程
Python 完整示例
import json
import openai
client = openai.OpenAI(api_key="YOUR_API_KEY")
# 定义工具
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的天气",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称"},
"days": {"type": "integer", "description": "查询天数"}
},
"required": ["city"]
}
}
}
]
# 模拟工具执行函数
def get_weather(city: str, days: int = 1) -> dict:
return {"city": city, "days": days, "temperature": 22, "condition": "晴"}
# 第一轮:用户提问
messages = [
{"role": "system", "content": "你是天气助手"},
{"role": "user", "content": "北京和上海明天天气怎么样?"}
]
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=tools,
tool_choice="auto",
parallel_tool_calls=True
)
msg = response.choices[0].message
# 处理工具调用(可能并行多个)
if msg.tool_calls:
messages.append(msg) # 追加 assistant 消息(含 tool_calls)
for tool_call in msg.tool_calls:
args = json.loads(tool_call.function.arguments)
# 执行对应工具
if tool_call.function.name == "get_weather":
result = get_weather(**args)
# 追加每个工具的执行结果
messages.append({
"role": "tool",
"tool_call_id": tool_call.id, # 必须与 tool_call.id 对应
"content": json.dumps(result, ensure_ascii=False)
})
# 第二轮:将所有工具结果回传,获取最终回复
final_response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=tools
)
print(final_response.choices[0].message.content)
消息流示意
[user] "北京和上海明天天气怎么样?"
↓ 第一次请求
[assistant] tool_calls: [get_weather(北京), get_weather(上海)]
↓ 执行工具
[tool] {"city":"北京","temperature":22,"condition":"晴"}
[tool] {"city":"上海","temperature":18,"condition":"小雨"}
↓ 第二次请求
[assistant] "北京明天晴,22°C;上海明天小雨,18°C。"
注意事项
- tools 每轮请求都必须传入,模型无状态,不记忆上一轮的工具定义
arguments是 JSON 字符串,需手动调用json.loads()解析,不是对象- 并行工具调用时,
assistant消息中可能包含多个tool_calls,需逐个执行并全部回传结果 tool_call_id必须严格对应,每个 tool 消息的tool_call_id必须匹配对应的tool_calls[i].idjson_schema模式需要gpt-4o-2024-08-06及以上版本,旧模型不支持- 兼容第三方服务(如 Azure OpenAI、各国产模型)可能仅支持参数子集,以各平台文档为准

6218

被折叠的 条评论
为什么被折叠?



