一、什么是大模型 API 的请求与响应机制?
大模型 API 的请求与响应机制,是指客户端按照约定的协议和数据结构提交模型输入,服务端完成认证、参数校验、模型调度与推理,再将生成结果按照约定格式返回客户端的完整过程。
从工程角度看,它并不是简单的函数调用,而是一次跨越网络、服务端应用、模型推理引擎和数据传输层的远程过程调用(RPC)。
一次典型调用包含以下环节:
flowchart TD
A["客户端构造请求"]
B["HTTP 请求发送"]
C["API 网关接收"]
D["认证与参数校验"]
E["模型服务调度"]
F["模型执行推理"]
G["封装响应数据"]
H["HTTP 响应返回"]
I["客户端解析结果"]
A --> B
B --> C
C --> D
D --> E
E --> F
F --> G
G --> H
H --> I
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#EAF3EC,stroke:#83A995,color:#315D49
style C fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style D fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style E fill:#EAF3EC,stroke:#83A995,color:#315D49
style F fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style G fill:#EAF3EC,stroke:#83A995,color:#315D49
style H fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style I fill:#DCEFE5,stroke:#4F8B70,color:#24563F
理解这套机制,需要区分三个层次:
| 层次 | 主要职责 | 关注内容 |
|---|---|---|
| HTTP 传输层 | 负责请求与响应的数据传输 | Method、Headers、Body、Status Code |
| API 应用层 | 负责认证、参数解析、调度和结果封装 | API Schema、Messages、Model、Usage |
| 模型推理层 | 负责实际的模型计算 | Tokenizer、Prefill、Decode、Sampling |
这三个层次相互协作,但职责并不相同。
例如,HTTP 200 代表 HTTP 请求成功处理,不代表模型答案一定正确;API 返回 JSON,也不意味着模型内部直接生成了 JSON 对象。
二、HTTP 请求的底层结构
大模型 API 通常通过 HTTPS 提供服务。
一次 HTTP 请求由请求行、请求头和请求体等部分组成。
2.1 请求行
请求行用于描述请求方法、目标路径和 HTTP 协议版本。
例如:
POST /v1/chat/completions HTTP/1.1
其中:
| 部分 | 含义 |
|---|---|
| POST | HTTP 请求方法 |
| /v1/chat/completions | 请求资源路径 |
| HTTP/1.1 | HTTP 协议版本 |
常见方法包括:
- GET:读取资源。
- POST:提交数据或创建资源。
- PUT:整体更新资源。
- PATCH:部分更新资源。
- DELETE:删除资源。
大模型推理接口通常使用 POST,因为需要提交 Prompt、模型参数和其他输入数据。
2.2 请求头 Headers
Headers 用于传递请求的元信息。
例如:
POST /v1/chat/completions HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
常见请求头:
| Header | 作用 |
|---|---|
| Host | 目标服务主机 |
| Authorization | 身份认证 |
| Content-Type | 请求体的数据类型 |
| Accept | 客户端期望接收的数据类型 |
| User-Agent | 客户端标识 |
| X-Request-ID | 请求追踪标识,若服务支持 |
其中最重要的是:
Content-Type
Content-Type: application/json
表示请求体使用 JSON 格式。
Authorization
Authorization: Bearer YOUR_API_KEY
表示使用 Bearer Token 进行身份认证。
API Key 不应该暴露在浏览器前端或移动端的公开代码中。生产环境应由后端负责密钥管理和模型服务调用。
2.3 请求体 Body
请求体承载模型调用所需的业务数据。
一个常见的 Chat Completions 风格请求:
{
"model": "example-model",
"messages": [
{
"role": "system",
"content": "你是一名专业的技术助手。"
},
{
"role": "user",
"content": "解释一下 Transformer 的工作原理。"
}
],
"temperature": 0.7,
"max_tokens": 1000,
"stream": false
}
请求体包含两类信息:
- 任务输入:模型名称、消息内容、上下文。
- 推理控制参数:温度、输出长度、流式开关等。
需要注意,这里采用的是一种常见的 OpenAI Chat Completions 兼容风格。不同服务商可能使用不同字段、接口路径和参数定义。
例如,输出长度字段可能使用 max_tokens、max_completion_tokens 或 max_output_tokens,不能假设它们在所有 API 中完全通用。
三、Request Body 的核心字段
请求体是大模型 API 最重要的数据部分。理解字段结构,才能正确控制模型行为。
3.1 Model:模型标识
{
"model": "example-model"
}
model 指定本次请求使用的模型。
它通常决定:
- 模型架构和参数规模。
- 支持的输入模态。
- 上下文窗口大小。
- 最大输出长度。
- 工具调用能力。
- 推理能力与延迟特征。
- 计费规则。
模型标识通常由服务商定义,不同服务商之间的模型名称没有统一标准。
3.2 Messages:对话消息列表
messages 用于描述本次模型调用的上下文。
例如:
{
"messages": [
{
"role": "system",
"content": "你是一名数据库专家。"
},
{
"role": "user",
"content": "什么是数据库索引?"
}
]
}
Messages 通常由多个消息对象组成。
每个消息对象至少需要表达消息来源和内容,具体字段由 API 协议定义。
常见角色包括:
| Role | 含义 |
|---|---|
| system | 系统级指令 |
| developer | 开发者级指令 |
| user | 用户输入 |
| assistant | 模型输出 |
| tool | 外部工具执行结果 |
并非所有服务商都使用完全相同的角色集合或消息结构。
3.3 Content:消息内容
content 表示消息的实际内容。
最简单的情况是字符串:
{
"role": "user",
"content": "什么是 KV Cache?"
}
多模态 API 中,content 也可能是由多个内容块组成的数组:
{
"role": "user",
"content": [
{
"type": "text",
"text": "请描述这张图片。"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.jpg"
}
}
]
}
这意味着消息内容不一定是普通文本。
对于视觉、音频和视频模型,内容结构可能包含:
- 文本片段。
- 图片 URL 或图片数据。
- 音频数据。
- 视频帧。
- 时间戳。
- 模态任务标记。
具体的数据结构取决于模型和服务商。
3.4 Temperature:生成随机性
Temperature 控制采样阶段的概率分布。
设模型输出的 Logits 为 z_i,Temperature 为 T,则经过温度缩放后的概率为:
一般来说:
- T 较低,概率分布更尖锐。
- T 较高,概率分布更平缓。
需要注意,Temperature 主要影响生成策略,不会改变模型已经训练好的参数,也不能直接提升模型知识准确性。
3.5 输出长度限制
常见字段包括:
{
"max_tokens": 1000
}
它用于限制生成内容的长度。
不同 API 对该字段的具体定义可能不同:
- 有的限制生成 Token 数。
- 有的使用专门的最大输出 Token 参数。
- 有的还支持独立控制推理 Token 和可见输出 Token。
上下文窗口与最大输出长度也不是同一个概念。
上下文窗口通常需要容纳输入内容和输出内容,而最大输出长度只控制生成部分。
3.6 Stream:是否启用流式响应
{
"stream": true
}
stream 用于决定服务端采用哪种响应方式。
false:通常等待完整结果后返回。true:通常持续发送增量事件。
不同 API 可能通过其他参数或不同 Endpoint 实现流式调用。
四、从 JSON 到模型输入:请求数据如何被处理?
客户端发送的是 JSON 数据,但模型并不能直接理解 JSON 对象。
JSON 是 API 层的数据交换格式,模型真正处理的是经过解析、规范化和编码后的输入表示。
4.1 JSON 解析
服务端首先接收 HTTP Body,并将 JSON 数据解析为内部对象。
例如:
{
"model": "example-model",
"messages": [
{
"role": "user",
"content": "什么是 Transformer?"
}
]
}
解析后,服务端可以获得:
request = {
"model": "example-model",
"messages": [
{
"role": "user",
"content": "什么是 Transformer?"
}
]
}
这里的 Python 字典仅用于说明解析后的数据结构。实际服务端可能使用 Go、Java、Rust、C++ 或其他语言实现。
4.2 参数校验
服务端通常需要检查:
- model 是否存在。
- messages 是否符合 Schema。
- role 是否有效。
- content 是否符合要求。
- Token 长度是否超限。
- temperature 是否在允许范围内。
- 是否具有对应模型的访问权限。
- 是否超出账户配额。
例如,缺少模型名称、消息结构不合法或输入超出限制,都可能导致请求在模型推理开始前被拒绝。
4.3 消息规范化
通过校验后,服务端可能将外部 API 格式转换为模型推理引擎内部使用的格式。
不同模型可能采用不同的对话模板。
例如,消息可能被组织为包含角色边界和结束标记的序列:
<|system|>
你是一名专业的技术助手。
<|user|>
什么是 Transformer?
<|assistant|>
这里仅用于说明概念,并非所有模型都使用这些 Token。
模型可能使用:
- Chat Template。
- Role Boundary Token。
- Message Separator。
- End-of-Turn Token。
- Tool Call Token。
消息角色不仅是普通文本标签,还可能通过专门的特殊 Token 表示。
4.4 Tokenizer 编码
消息完成规范化后,文本内容需要通过 Tokenizer 转换为 Token ID 序列。
例如:
输入文本
↓
Tokenizer
↓
Token ID
↓
Embedding
↓
Transformer
其数学表示可以抽象为:
其中:
- M:规范化后的输入消息。
- Tokenizer:分词与编码过程。
- X:Token ID 序列。
随后通过 Embedding 层映射为向量:
需要注意,模型并不直接处理 JSON 的键值结构。API 服务层需要先将请求内容转换为模型能够接受的输入表示。
4.5 请求处理完整流程
flowchart TD
A["接收 HTTP Body"]
B["解析 JSON"]
C["校验请求字段"]
D{"请求是否合法"}
E["返回参数错误"]
F["解析 Messages"]
G["应用 Chat Template"]
H["Tokenizer 编码"]
I["生成模型输入表示"]
J["提交推理引擎"]
A --> B
B --> C
C --> D
D -->|"否"| E
D -->|"是"| F
F --> G
G --> H
H --> I
I --> J
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style C fill:#EAF3EC,stroke:#83A995,color:#315D49
style D fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style E fill:#F7EAE7,stroke:#C98D7C,color:#754438
style F fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style G fill:#EAF3EC,stroke:#83A995,color:#315D49
style H fill:#EAF3EC,stroke:#83A995,color:#315D49
style I fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style J fill:#DCEFE5,stroke:#4F8B70,color:#24563F
五、服务端如何执行模型推理?
请求通过 API 层校验后,才会进入真正的模型推理阶段。
以 Decoder-only 自回归语言模型为例,推理通常包含 Prefill 和 Decode 两个阶段。
5.1 Prefill:处理输入上下文
Prefill 阶段负责处理完整输入序列。
主要工作:
- 将输入 Token 转换为 Embedding。
- 执行 Transformer 各层计算。
- 计算 Attention 所需的 Query、Key、Value。
- 建立历史 Token 对应的 KV Cache。
- 计算最后一个输入位置的输出分布。
对于输入长度为 N 的 Prompt,Prefill 通常可以并行处理多个输入位置。
其主要目标是完成上下文编码,并为后续生成建立必要的缓存状态。
5.2 Decode:逐 Token 生成
Prefill 完成后,模型进入 Decode 阶段。
Decode 通常采用自回归方式:
- 根据当前上下文计算下一个 Token 的概率分布。
- 通过 Greedy、Sampling 或其他解码策略选择 Token。
- 将新 Token 加入生成序列。
- 更新 KV Cache。
- 继续预测下一个 Token。
数学上可以表示为:
模型根据已有 Token 序列预测下一个 Token。
整个过程持续进行,直到达到停止条件。
5.3 Prefill 与 Decode 的关系
flowchart TD
A["请求输入 Token 序列"]
B["Prefill 阶段"]
C["并行处理输入上下文"]
D["建立 KV Cache"]
E["计算首个输出 Token 分布"]
F["选择下一个 Token"]
G["Decode 阶段"]
H["读取历史 KV Cache"]
I["计算当前 Token"]
J["追加新的 KV Cache"]
K{"是否结束生成"}
L["完成模型输出"]
A --> B
B --> C
C --> D
D --> E
E --> F
F --> G
G --> H
H --> I
I --> J
J --> K
K -->|"否"| G
K -->|"是"| L
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#EAF3EC,stroke:#83A995,color:#315D49
style C fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style D fill:#EAF3EC,stroke:#83A995,color:#315D49
style E fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style F fill:#EAF3EC,stroke:#83A995,color:#315D49
style G fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style H fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style I fill:#EAF3EC,stroke:#83A995,color:#315D49
style J fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style K fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style L fill:#DCEFE5,stroke:#4F8B70,color:#24563F
需要注意,Prefill 计算出的最后一个输入位置的输出分布,可以用于选择第一个生成 Token。第一个生成 Token 的 K/V 通常在后续 Decode 将该 Token 作为输入时计算并加入缓存。
5.4 模型推理不等于 HTTP 响应
模型内部生成的内容,通常还需要经过服务端处理才能成为 API 响应。
可能涉及:
- Token ID 解码为文本。
- 特殊 Token 处理。
- 工具调用结构解析。
- 输出格式约束。
- 内容安全检查。
- Token 使用量统计。
- Finish Reason 确定。
模型推理层负责生成模型输出,API 应用层负责将结果组织为客户端能够理解的数据结构。
六、Response:响应数据的结构
模型推理完成后,服务端需要构造响应。
在常见的 Chat Completions 风格 API 中,响应通常包含:
- 响应 ID。
- 对象类型。
- 模型名称。
- 生成结果。
- 结束原因。
- Token 使用统计。
6.1 完整响应示例
{
"id": "chatcmpl-example",
"object": "chat.completion",
"created": 1795090000,
"model": "example-model",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Transformer 是一种基于注意力机制的神经网络架构。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 20,
"completion_tokens": 18,
"total_tokens": 38
}
}
这是一个示意性响应结构,实际字段和可选内容取决于具体 API。
6.2 Response 核心字段
| 字段 | 含义 | 作用 |
|---|---|---|
| id | 响应标识 | 唯一识别一次调用结果 |
| object | 对象类型 | 描述响应类别 |
| created | 创建时间 | 记录响应生成时间 |
| model | 模型名称 | 标识实际使用的模型 |
| choices | 生成结果列表 | 承载模型输出 |
| index | 结果索引 | 标识候选结果 |
| message | 消息对象 | 承载模型消息 |
| finish_reason | 结束原因 | 说明生成结束状态 |
| usage | 用量统计 | 统计 Token 消耗 |
并非每个接口都返回所有字段。
例如,有些 API 使用不同的响应对象,也可能将文本内容放在其他结构中。
6.3 Choices:模型生成结果
choices 通常用于承载模型输出结果。
例如:
{
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "这是模型生成的回答。"
},
"finish_reason": "stop"
}
]
}
为什么使用数组?
部分 API 支持一次请求返回多个候选结果,因此使用数组承载多个生成选项。
但并不是所有模型服务都支持多候选输出,也不是所有接口都使用 choices。
6.4 Finish Reason:生成结束原因
finish_reason 用于描述生成停止的原因。
常见值可能包括:
| 值 | 含义 |
|---|---|
| stop | 正常结束或命中停止条件 |
| length | 达到输出长度限制 |
| tool_calls | 生成了工具调用请求 |
| content_filter | 内容安全策略触发 |
不同 API 的枚举值可能不同。
尤其需要注意:
模型生成了工具调用请求,不代表外部工具已经执行。
工具调用请求仍然需要应用程序解析、校验并执行。
6.5 Usage:Token 使用统计
常见响应可能包含:
{
"usage": {
"prompt_tokens": 20,
"completion_tokens": 18,
"total_tokens": 38
}
}
其中:
prompt_tokens:输入 Token 数量。completion_tokens:输出 Token 数量。total_tokens:总 Token 数量。
部分 API 还可能返回缓存 Token、推理 Token 或多模态 Token 的细分统计。
Usage 不只是计费依据,也可以用于:
- 监控请求成本。
- 估算上下文消耗。
- 优化 Prompt。
- 评估不同模型的使用效率。
- 发现异常调用。
七、响应结束原因与模型停止机制
模型为什么会停止生成?
它并不一定是因为已经完成了一个自然语言句子,而是可能触发了不同的终止条件。
常见停止条件包括:
7.1 EOS Token
EOS(End of Sequence)是用于表示序列结束的特殊 Token。
当模型生成符合当前协议的结束标记时,生成过程可以结束。
但不同模型的结束标记可能不同。
7.2 Stop Sequence
客户端可以向 API 提供停止序列。
例如:
{
"stop": ["<END>"]
}
当生成内容匹配指定停止条件时,服务端可能停止继续生成。
7.3 最大输出长度
当生成 Token 数达到最大限制时,服务端会终止本次生成。
这通常会对应类似 length 的结束原因。
7.4 工具调用结束
当模型决定调用工具时,可能先输出结构化工具调用请求,而不是直接生成最终自然语言回答。
应用执行工具并将结果提交模型后,模型可能继续生成后续内容。
7.5 停止条件流程
flowchart TD
A["开始生成 Token"]
B["生成下一个 Token"]
C{"是否触发 EOS"}
D{"是否命中 Stop Sequence"}
E{"是否达到输出长度限制"}
F{"是否生成工具调用请求"}
G["继续生成"]
H["正常结束"]
I["停止序列结束"]
J["长度限制结束"]
K["返回工具调用请求"]
A --> B
B --> C
C -->|"是"| H
C -->|"否"| D
D -->|"是"| I
D -->|"否"| E
E -->|"是"| J
E -->|"否"| F
F -->|"是"| K
F -->|"否"| G
G --> B
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#EAF3EC,stroke:#83A995,color:#315D49
style C fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style D fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style E fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style F fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style G fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style H fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style I fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style J fill:#F7EAE7,stroke:#C98D7C,color:#754438
style K fill:#EAF3EC,stroke:#83A995,color:#315D49
上图是概念化的停止判断流程。真实服务端可能采用不同的内部调度顺序,工具调用也可能由独立的结构化解码流程处理。
八、非流式响应与流式响应的传输机制
大模型 API 的响应方式主要可以分为非流式和流式。
两者的差异不在于模型是否逐 Token 生成,而在于服务端何时向客户端传输已经生成的结果。
8.1 非流式响应
非流式模式下,客户端发起请求后,通常需要等待模型完成本次生成。
随后服务端一次性返回完整响应。
sequenceDiagram
participant C as 客户端
participant S as API 服务
participant M as 模型推理引擎
C->>S: POST 请求
S->>M: 提交模型输入
M-->>S: 完整生成结果
S-->>C: HTTP 200 + JSON
优点:
- 客户端实现简单。
- 响应结构通常完整。
- 适合短文本和后台任务。
缺点:
- 长文本需要等待较长时间。
- 用户无法提前看到已生成内容。
- 首次展示延迟可能较高。
8.2 流式响应
流式模式下,服务端在模型生成过程中持续发送增量数据。
客户端逐步接收并展示。
sequenceDiagram
participant C as 客户端
participant S as API 服务
participant M as 模型推理引擎
C->>S: POST 请求 stream=true
S->>M: 提交模型输入
M-->>S: 生成第一个 Token
S-->>C: 发送 Chunk 1
M-->>S: 生成后续 Token
S-->>C: 发送 Chunk 2
M-->>S: 继续生成
S-->>C: 发送 Chunk 3
M-->>S: 生成结束
S-->>C: 发送结束事件
这里的 Chunk 不一定与单个 Token 一一对应。
服务端可能将多个 Token 合并后发送,也可能因传输缓冲、编码边界和调度策略形成不同大小的数据块。
8.3 SSE 事件结构
一种常见的 SSE 数据格式如下:
data: {"choices":[{"delta":{"content":"大模型"}}]}
data: {"choices":[{"delta":{"content":" API"}}]}
data: {"choices":[{"delta":{"content":" 的响应机制"}}]}
data: [DONE]
流式响应通常使用 delta 表示本次新增的内容。
与非流式响应相比:
| 非流式 | 流式 |
|---|---|
| message | delta |
| 完整内容 | 增量内容 |
| 一次性响应 | 多次事件 |
| 完整 JSON | 事件流 |
| 等待生成结束 | 可以边生成边展示 |
8.4 SSE、HTTP Chunked 与 WebSocket
这三个概念容易混淆。
| 技术 | 核心作用 | 通信方向 |
|---|---|---|
| SSE | 服务端推送事件 | 服务端到客户端 |
| HTTP Chunked Transfer | HTTP/1.1 分块传输编码 | 取决于 HTTP 请求和响应方向 |
| WebSocket | 建立双向消息通道 | 双向 |
SSE 是事件流机制,HTTP Chunked 是传输编码方式,WebSocket 则是独立的双向通信协议。
HTTP/2 也支持流式传输,不应将 HTTP Chunked Transfer 视为所有 HTTP 流式响应的必要条件。
九、客户端如何解析 API 响应?
服务端返回的数据最终需要由客户端解析。
对于非流式 JSON,解析过程相对简单。
9.1 Python 解析完整响应
import requests
response = requests.post(
url,
headers=headers,
json=payload,
timeout=60
)
response.raise_for_status()
data = response.json()
answer = data["choices"][0]["message"]["content"]
print(answer)
实际生产环境中,建议对字段进行安全检查:
choices = data.get("choices", [])
if not choices:
raise ValueError("模型没有返回候选结果")
message = choices[0].get("message", {})
answer = message.get("content")
if answer is None:
raise ValueError("响应中没有文本内容")
print(answer)