OpenAI Chat Completions API 完整参考手册

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. 请求结构总览
  2. 必填参数
  3. messages 消息协议
  4. 生成控制参数
  5. tools 工具调用协议
  6. response_format 结构化输出
  7. 流式输出
  8. 其他参数
  9. 响应体结构
  10. 完整请求示例
  11. 多轮工具调用完整流程

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. 必填参数

参数类型说明
modelstring模型 ID,如 gpt-4ogpt-4-turbogpt-3.5-turbo
messagesarray对话消息列表,至少包含一条消息,详见第 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 → ...
  • 每轮对话必须以 usertool 消息结尾(发起新请求时)
  • tool 消息必须紧跟在包含 tool_callsassistant 消息之后
  • 并行工具调用时,所有工具结果必须全部回传后才能继续对话

4. 生成控制参数

4.1 随机性控制

参数类型默认值范围说明
temperaturenumber10 ~ 2越高输出越随机,越低越确定性。不建议同时调整 temperaturetop_p
top_pnumber10 ~ 1核采样,只从累计概率达到该值的 token 中采样。0.1 表示只考虑最可能的前 10%
seedinteger随机种子,相同 seed 在相同条件下尽量复现相同输出
temperaturetop_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(更精细)
两者不要同时偏离默认值      → 否则效果叠加,难以预测

常用组合速查

任务类型temperaturetop_p效果
代码补全0.01.0确定性最强,首选方案
数据抽取 / JSON 输出0.11.0几乎无随机,结构稳定
问答 / 摘要0.51.0略带变化,表达自然
通用对话1.01.0模型默认行为
创意写作1.21.0增加创意多样性
头脑风暴1.00.95过滤极低概率词,保持创意

4.2 长度控制

参数类型默认值说明
max_completion_tokensinteger模型上限最大生成 token 数,包含推理模型的思考 token(推荐使用此参数)
max_tokensinteger已废弃,功能同上,请改用 max_completion_tokens
ninteger1每次请求返回的候选回复数量,n > 1 时消耗更多 token
stopstring / arraynull遇到指定字符串时停止生成,最多指定 4 个停止词

4.3 重复惩罚

参数类型默认值范围说明
presence_penaltynumber0-2.0 ~ 2.0正值惩罚已出现过的 token,鼓励模型引入新话题
frequency_penaltynumber0-2.0 ~ 2.0正值惩罚高频 token,减少词汇重复
logit_biasobjectnull直接调整指定 token 的概率,格式 {"token_id": bias},bias 范围 -100 ~ 100

4.4 概率分析

参数类型默认值说明
logprobsbooleanfalse是否在响应中返回每个 token 的对数概率
top_logprobsinteger每个位置返回概率最高的前 N 个 token 及其概率,需先开启 logprobs,最大值 20

5. tools 工具调用协议

工具调用(Function Calling)允许模型在生成回复时决定调用外部函数,并将调用参数结构化输出。

5.1 顶层参数

参数类型默认值说明
toolsarray工具定义列表,每项描述一个可调用的函数
tool_choicestring / object"auto"控制模型是否及如何调用工具,见 5.3 节
parallel_tool_callsbooleantrue是否允许模型在一次回复中并行调用多个工具

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 字段说明
字段类型必填说明
namestring函数名,仅允许 a-z A-Z 0-9 _ -,最长 64 字符
descriptionstring推荐函数用途说明,越详细模型调用越准确
parametersobject参数定义,遵循 JSON Schema Draft 7,无参函数可省略
strictboolean开启后强制模型严格按 schema 生成参数,默认 false
parameters 支持的 JSON Schema 关键字
关键字适用类型说明
type所有string / number / integer / boolean / array / object / null
description所有字段说明,帮助模型理解含义
enumstring / number枚举可选值列表
requiredobject必填字段列表
propertiesobject子字段定义
additionalPropertiesobjectfalse 禁止额外字段
itemsarray数组元素的类型定义
minimum / maximumnumber / integer数值范围约束
minLength / maxLengthstring字符串长度约束
minItems / maxItemsarray数组长度约束
patternstring正则表达式约束
$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_objectPrompt 引导简单 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 字段说明
字段类型必填说明
namestringSchema 名称,仅允许 a-z A-Z 0-9 _ -,最长 64 字符
descriptionstringSchema 用途说明,辅助模型理解意图
schemaobject标准 JSON Schema(Draft 7),根类型必须是 object
strictboolean推荐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_objectjson_schema
实现机制Prompt 引导(软约束)约束解码(硬约束)
结构保证❌ 依赖 prompt 质量✅ strict=true 时 100% 保证
多余字段可能出现不会出现
缺失字段可能出现不会出现
类型错误可能出现不会出现
模型要求较宽泛gpt-4o-2024-08-06 及以上
适用场景简单/非关键 JSON关键数据提取、代码直接消费

7. 流式输出

参数类型默认值说明
streambooleanfalse开启后以 SSE(Server-Sent Events)逐 token 流式返回
stream_optionsobject{"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. 其他参数

参数类型说明
userstring终端用户唯一标识符,用于平台侧的滥用监控和审计
storeboolean是否将本次请求存储用于 Dashboard 查看或 Fine-tuning(默认 false
metadataobject自定义键值对,随请求存储,最多 16 个键,可用于业务标注
reasoning_effortstring推理模型(o1/o3 系列)的思考强度:"low" / "medium" / "high"
modalitiesarray指定输出模态:["text"]["text", "audio"](需模型支持音频)
audioobject音频输出配置:{"voice": "alloy", "format": "mp3"}
predictionobject预测输出(Predicted Outputs),提供预期内容以加速生成
service_tierstring服务等级:"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"contentnulltool_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 数组中每个元素的字段说明
字段类型说明
idstring本次调用的唯一 ID,格式如 call_xxxxxxxx,回传 tool 消息时必须填入 tool_call_id
typestring固定为 "function"
function.namestring模型决定调用的函数名,与 tools 定义中的 name 对应
function.argumentsstring模型生成的调用参数,是 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。"

注意事项

  1. tools 每轮请求都必须传入,模型无状态,不记忆上一轮的工具定义
  2. arguments 是 JSON 字符串,需手动调用 json.loads() 解析,不是对象
  3. 并行工具调用时assistant 消息中可能包含多个 tool_calls,需逐个执行并全部回传结果
  4. tool_call_id 必须严格对应,每个 tool 消息的 tool_call_id 必须匹配对应的 tool_calls[i].id
  5. json_schema 模式需要 gpt-4o-2024-08-06 及以上版本,旧模型不支持
  6. 兼容第三方服务(如 Azure OpenAI、各国产模型)可能仅支持参数子集,以各平台文档为准
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值