对话端点的请求结构
对话端点的骨架是一个消息数组：每条消息带角色与内容，角色包括系统、用户、助手与工具。采样参数、流式开关与工具定义都是与消息数组同级的字段。服务端会用模型自带的模板把消息渲染成真正的提示词，因此不要自己在内容里拼接角色标记，否则模板会重复渲染。
最小请求
最小请求
curl http://127.0.0.1:8000/v1/chat/completions -H 'Content-Type: application/json' -d '{
"model": "<模型名>",
"messages": [
{"role": "system", "content": "你是简洁的技术助手"},
{"role": "user", "content": "一句话介绍 KV 缓存"}
],
"temperature": 0.3,
"max_tokens": 128,
"stream": false
}'请求字段
| 字段 | 作用 | 注意 |
|---|---|---|
| model | 指定模型名或别名 | 与网关映射表保持一致 |
| messages | 消息数组，含角色与内容 | 多轮时按时间顺序追加历史 |
| temperature | 采样温度 | 与错误来源定位相关，排查时可归零 |
| max_tokens | 输出长度上限 | 输入加输出不超过上下文窗口 |
| stream | 是否流式返回 | 客户端与网关两处都要支持 |
| 工具相关字段 | 定义可调用工具与选择策略 | 自托管实现的支持程度需实测 |
典型使用场景
- 业务接入：作为主调用入口，业务侧只维护消息数组与参数
- 多轮对话：把历史消息按顺序放回数组，由服务端统一渲染
- 流式前端：开启流式返回，边生成边展示，改善长回答的感知延迟
- 联调排错：先用最小请求打通链路，再逐步加入参数
- 回归测试：固定消息与参数作为冒烟用例，每次发布后执行
多轮对话把历史消息按顺序放回数组即可：服务端会用模型模板重新渲染，自己拼接角色标记会导致模板重复或格式错乱。
消息里塞自定义字段有风险：渲染与网关校验可能出错，扩展信息应通过独立通道传递。