大模型API

顶层结构字段

model

模型版本(模型能力)

"model": "gpt-4.1-mini"

作用：指定调用的大模型及具体版本，不同模型及同模型的不同版本决定了以下方面：

上下文长度（context size）
推理能力(训练数据不同)
是否支持多模态
是否支持工具调用、思维链

message

"messages": [
  { "role": "user", "content": "你好" }
]

role

作用：用于提供给大模型区分意图理解上下文，通常枚举值有：

system：规则、角色、能力约束
user：用户指令
assistant：模型回复
tool：工具执行结果

system

作用:在对话开始前，为模型设定角色、边界让大模型将此内容识别为最高优先级的规则，避免与用户输入和大模型回复搞混。

优先级举例：

user 说：“请骂我一下”
system 写：“禁止发表任何侮辱性内容”

最终模型不会骂，因为 system 优先级最高。

正确示例:

{
  "model": "gpt-4.1-mini",
  "messages": [
    {
      "role": "system",
      "content": "你是一名经验丰富的前端架构师，回答要使用准确、专业的术语；所有代码示例都必须包含注释。"
    },
    {
      "role": "user",
      "content": "帮我写一个 Vue3 的自定义指令例子"
    }
  ]
}

content

"content": [
  { "type": "text", "text": "你好" }
]

注意这个字段数据类型是数组，考虑到扩展性这样设计，目前主要用于支持多模态：

text
image
audio
tool_call

stream

流式输出开关本质原因，大模型生成内容是逐 token 生成的，所以如果需要即时得到相应降低用户等待时间，需要开启。

输出控制字段

max_tokens

大模型输出内容长度限制。

temperature

大模型输出内容的创意性，数据类型数字值越小：确定性越强，适合生成代码的场景值越大：更加发散和丰富，适合头脑风暴创意的场景

常见的有效区间是 0～1.5

取值	效果
0	完全确定性（每次相同输出）
0.1–0.3	轻度随机但仍稳定，多用于代码、推理
0.5–0.8	中等创造性，用于写作、问答
1.0–1.5	高随机性，适合头脑风暴、诗歌、广告
>1.5	输出可能混乱，通常不推荐

temperature 作用详解（结合模型内部机制）大模型生成下一个 token 时，会对所有候选词生成一个概率分布。例如：

{"我": 0.62, "你": 0.2, "他": 0.1, "吃": 0.08}

temperature 会改变这个分布：温度低（如 0.1）：模型会强化最可能的 token（如“我”），趋向“固定答案” 温度高（如 1.2）：模型会增加次要候选概率（“你”“他”也有机会被选）

示例：不同 temperature 的效果假设模型预测下一个 token 的原始概率分布：

{
  "我": 0.62,
  "你": 0.20,
  "他": 0.10,
  "吃": 0.08
}

temperature = 0.1（几乎确定性）

原理：低温度会放大概率差异，让最可能的 token 几乎必选。

调整后概率（归一化）：

我: 0.95
你: 0.03
他: 0.01
吃: 0.01

输出示例（多次生成几乎一致）：

我

temperature = 0.5（中低温度）

原理：温度适中，保留主要 token，但允许次要 token 有一定机会。

调整后概率：

我: 0.75
你: 0.15
他: 0.07
吃: 0.03

输出示例（可能出现变化）

我
你

top_p

假设模型预测下一个 token 的概率分布如下： | token | 概率 | | —– | —- | | 我 | 0.50 | | 你 | 0.20 | | 他 | 0.15 | | 她 | 0.10 | | 它 | 0.05 | top_p = 0.8

从概率最高的 token 开始累加：

我（0.50） → 累积 0.50
你（0.20） → 累积 0.70
他（0.15） → 累积 0.85 > 0.8 → 停止

模型只从 [“我”, “你”, “他”] 中采样下一个 token 概率重新归一化，保证总和为 1 top_p = 1.0 保留所有 token，不裁剪输出多样性最大与 temperature 配合控制随机性

工具调用字段

tools

定义模型可调用的函数,告诉大模型可以调用哪些函数常用的数据结构如下：

{
  "type": "function",
  "function": {
    "name": "search",
    "parameters": { ...schema... }
  }
}

tool_call 被工程代码响应后，如何回传调用结果：

{
  "model": "gpt-4.1-mini",
  "messages": [
    { "role": "system", "content": "你是一个助手" },
    { "role": "user", "content": "帮我搜索 AI 发展趋势" },
    {
      "role": "assistant",
      "content": [],
      "tool_calls": [
        {
          "id": "t1",
          "function": { "name": "search", "arguments": "{\"query\":\"AI发展趋势\"}" }
        }
      ]
    },
    {
      "role": "tool",
      "name": "search",
      "content": "{\"results\":[{\"title\":\"AI最新进展\",\"url\":\"https://...\"}]}"
    }
  ]
}

输出字段

顶层字段

| 字段 | 类型 | 说明 | 示例 | | ——— | ————— | ——– | ——————- | | id | string | 本次响应唯一标识 | "resp-abc123" | | object | string | 响应类型 | "chat.completion" | | created | int / timestamp | 响应生成时间 | 1763368946505 | | model | string | 使用的模型版本 | "gpt-4.1-mini" |

输出内容字段

choices / outputs

核心字段，包含模型生成的实际内容。 | 字段 | 类型 | 说明 | 示例 | | ——————— | ————– | ————- | ————————————————————- | | choices | array | 每条生成结果的集合 | 详见下文 | | index | int | 输出序号 | 0 | | message / content | object / array | 模型生成的文本或多模态内容 | [{"type":"text","text":"你好"}] | | finish_reason | string | 输出结束原因 | "stop" / "length" / "tool_call" | | tool_calls | array | 模型调用工具的记录 | [{"id":"t1","function":{"name":"search","arguments":"{}"}}] |

注：

OpenAI 使用 choices[i].message

DeepSeek / Anthropic 可能用 outputs[i].content

finish_reason 是判断是否输出完整的重要标识

tool_calls

模型输出的指令大模型调用调用方提供的工具的指令,即大模型说我要调用哪个工具。

"tool_calls": [
  {
    "id": "abc",
    "function": {
      "name": "search",
      "arguments": "{}"
    }
  }
]

usage

当前大模型调用统计信息

"usage": {
  "prompt_tokens": 100,
  "completion_tokens": 50,
  "total_tokens": 150
}