API参考
数据对象定义
查看 Message、Choice、Usage、Tool 与 Tool Call 的字段结构。
查看 Message、Choice、Usage、Tool 与 Tool Call 的字段结构。
本页集中说明 Chat Completions 中最常用的对象。未使用的可选字段可能缺失或为 null。
Message
| 字段 | 类型 | 说明 |
|---|---|---|
role | string | 消息作者角色。 |
content | string、array 或 null | 消息内容；工具调用场景可能为空。 |
name | string | 可选的参与者名称；是否支持取决于模型。 |
tool_calls | array | 助手生成的工具调用列表。 |
tool_call_id | string | 工具结果消息关联的调用 ID。 |
Choice
| 字段 | 类型 | 说明 |
|---|---|---|
index | integer | 候选项在数组中的索引。 |
message | object | 非流式响应中的完整助手消息。 |
delta | object | 流式响应中的增量内容。 |
finish_reason | string 或 null | 生成停止原因。 |
常见 finish_reason
| 值 | 含义 | 建议处理 |
|---|---|---|
stop | 正常完成或命中停止条件。 | 展示结果。 |
length | 达到输出或上下文限制。 | 提示内容可能被截断，必要时缩短输入或继续生成。 |
tool_calls | 模型希望调用工具。 | 检查 message.tool_calls 并进入工具执行流程。 |
content_filter | 输出因安全策略停止。 | 向用户提供安全且不泄露内部策略的提示。 |
null | 流式生成尚未结束。 | 继续读取后续数据块。 |
Usage
| 字段 | 类型 | 说明 |
|---|---|---|
prompt_tokens | integer | 本次请求输入使用的 Token。 |
completion_tokens | integer | 模型输出使用的 Token。 |
total_tokens | integer | 输入与输出用量合计。 |
Function Tool
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "获取指定城市的当前天气",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["city"],
"additionalProperties": false
}
}
}Tool Call
{
"id": "call_weather_01",
"type": "function",
"function": {
"name": "get_current_weather",
"arguments": "{\"city\":\"北京\",\"unit\":\"celsius\"}"
}
}arguments 是 JSON 字符串而不是已解析对象。应用需要解析、验证，并确认函数名称位于允许列表。