Chat Completions 是什么
Chat Completions 是使用最广的对话补全接口：向服务端发一个 JSON，里面写清模型名与消息数组，返回里取第一条候选消息的内容即可。它把多轮对话抽象成消息数组，把工具调用、结构化输出、多模态输入都统一挂在这套结构上，因此成了事实标准，几乎所有厂商都提供兼容端点。新项目也可以选更新的接口，但兼容性最好的仍是它。
基本信息
| 请求路径 | 多数服务为 /v1/chat/completions |
|---|---|
| 方法 | POST，请求体为 JSON |
| 核心字段 | model 与 messages 为必填，其余按需 |
| 返回结构 | 候选数组，每个候选含消息内容与结束原因 |
| 鉴权 | 多数用 Authorization 请求头携带令牌 |
| 扩展能力 | 工具调用、结构化输出、多模态内容块、流式输出 |
核心字段速查
| 字段 | 作用 | 常用取值 |
|---|---|---|
| model | 指定调用的模型 | 固定版本标识，避免滚动别名 |
| messages | 消息数组，承载上下文 | 按系统、用户、助手顺序排列 |
| temperature | 控制随机性 | 事实任务取低值，创意任务取高值 |
| max_tokens | 限制输出长度 | 按任务需要设置并留余量 |
| stream | 是否逐块返回 | 交互场景开启，批处理可关闭 |
| tools | 声明可调用的工具 | 仅在需要函数调用时传入 |
典型使用场景
- 对话机器人：多轮上下文里维持话题连贯
- 内容生成：摘要、改写、翻译、报告草稿
- 信息抽取：把自由文本转成字段化的结构化数据
- 工具编排：由模型决定调用哪个接口并组织结果
- 批量处理：离线任务用同一接口循环调用并记录用量
最小可用请求
最小可用请求
curl -s https://api.openai.com/v1/chat/completions -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-4o","messages":[{"role":"system","content":"你是运维助手"},{"role":"user","content":"nginx 502 怎么排查"}],"temperature":0.2,"max_tokens":512}' # 带上参数便于复现
# 返回里取第一个候选的消息内容作为回答，同时保留结束原因用于判断截断
# 多轮：把这次返回的助手消息追加进 messages 再发下一次请求
# 出错时先看状态码定位大类，再看错误体里的具体原因程序侧的最小封装
程序侧的最小封装
from openai import OpenAI
client = OpenAI() # 密钥从环境变量读取
r = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "总结这段话"}],
)
print(r.choices[0].message.content) # 文本结果
print(r.usage) # 用量，用于成本核算
# 解析时对字段做兜底：不同提供方的返回可能缺字段或附加额外字段返回对象怎么读
| 字段 | 含义 | 注意 |
|---|---|---|
| 候选数组 | 模型给出的回答列表 | 通常取第一条，多候选场景按需遍历 |
| 消息内容 | 正文文本 | 工具调用场景下可能为空 |
| 结束原因 | 为何停止生成 | 长度限制与自然结束要区别处理 |
| 工具调用块 | 模型要求的函数与参数 | 需由你的代码执行后再回填结果 |
| 用量 | 输入与输出的 token 数 | 用于成本核算与限流预估 |
接入与上线检查
- 先用最小请求跑通鉴权与模型名，再叠加工具与结构化输出
- 把超时、重试与退避写进封装层，业务代码只调用封装
- 记录每次请求的用量与结束原因，用于成本核算与截断排查
- 提示词与模型版本纳入版本管理，改动后跑同一套回归用例
上下文长度限制是输入加输出合计：长历史配长回答很容易触顶，多轮应用要主动裁剪或摘要，而不是等报错。
把密钥写进前端代码再直连接口，等于对全网公开：所有模型调用都应经过自有后端或网关转发。