E1 · 如何通过 API 调用 AI 模型？ - Model API

所属知识库：Agent 全栈技术地图
所属领域：01 · AI
所属章节：03 · 如何使用和管理 AI 模型？ - Model Engineering
文档类型：技术原理与工程实践研究
版本：v1.0
更新日期：2026 年 10 月 27 日
核心问题：什么是模型 API？应用程序如何与 AI 模型通信？HTTP、REST、JSON、SDK 和 API Key 分别发挥什么作用？一次模型调用经历哪些步骤？同步调用、流式输出和异步任务有什么区别？如何管理模型参数、错误、超时和重试？如何设计可供 Agent System 复用的模型调用模块？

专题导读

这一篇将从 API 的基本原理开始，系统解释应用程序如何连接模型服务、发送请求、接收结果，以及如何将模型 API 封装为 Agent 和 Agent System 可以复用的基础能力。内容将兼顾技术原理、实际代码和工程设计，不依赖某一家模型服务商的特定实现。

一、研究概述

在前面的 Model Architecture 章节中，我们研究了 AI 模型的内部结构、训练机制和推理过程。

但在实际开发中，应用程序通常不需要直接操作模型的神经网络结构，也不需要自行实现 Transformer 的前向传播。

对于使用托管模型服务的开发者而言，更常见的方式是通过 API 调用模型。

例如，一个研究 Agent 需要分析某家企业的信息。

它可以向模型服务发送一段请求：

text

请根据以下资料，分析这家企业的主要业务和竞争优势。

模型服务完成推理后，将结果返回给 Agent。

Agent 再根据结果继续执行任务。

这一过程看起来只是发送和接收信息，但实际上涉及多个技术层次：

网络通信；
身份认证；
请求数据结构；
模型选择；
推理参数；
响应解析；
流式传输；
错误处理；
调用成本；
服务可靠性。

这些共同构成 Model API 的工程基础。

1.1 本篇研究目标

本篇希望解决四类问题。

第一，理解 API 的基本概念。 明确 API、HTTP、REST、JSON、SDK、Endpoint 和 API Key 的含义及其关系。

第二，理解模型调用机制。 掌握模型请求的构成、响应结构、推理参数和完整执行流程。

第三，掌握模型 API 的主要使用方式。 包括普通调用、流式调用、异步任务和多轮对话。

第四，建立模型 API 的工程设计思路。 理解如何处理超时、重试、限流、错误、密钥和日志，并将模型调用封装为可复用的服务。

1.2 本篇研究边界

本篇主要研究模型 API 的通信机制与工程集成。

以下内容将在后续专题深入研究：

研究内容	对应专题
Prompt 设计	E2 · Prompt Engineering
Context Window 管理	E3 · Context Window
JSON Schema 与结构化输出	E4 · Structured Outputs
Function Calling	E5 · Function Calling
多模型选择与路由	E6 · Model Routing
自托管模型服务	E7 · Model Deployment
推理性能与成本优化	E8 · Inference Optimization

二、什么是 API？

2.1 API 的定义

API 是 Application Programming Interface 的缩写，中文通常称为应用程序编程接口。

它是一组用于定义不同软件组件之间如何交互的接口约定。

API 可以规定：

可以执行哪些操作；
调用时需要提供哪些参数；
返回什么类型的结果；
发生错误时如何表示；
调用者需要满足什么条件。

API 并不一定通过互联网提供。

例如，操作系统接口、编程语言库接口和本地模块接口都可以属于 API。

但在模型应用开发中，我们通常讨论的是通过网络访问的 Web API。

2.2 为什么软件需要 API？

假设一个应用程序需要使用另一个系统的能力。

如果没有明确的接口，应用程序就必须了解对方系统的内部实现。

这会导致两个系统高度耦合。

API 的作用是提供相对稳定的交互边界。

text

Application A
      │
      ▼
     API
      │
      ▼
Application B

应用程序 A 只需要按照 API 约定发送请求，而不必直接控制应用程序 B 的内部逻辑。

2.3 什么是 Model API？

Model API 是用于访问 AI 模型能力的编程接口。

它通常允许开发者：

指定模型；
提供输入；
设置推理参数；
获取生成结果；
查询使用量；
处理工具调用或结构化输出。

例如：

text

Application
     │
     │ Model Request
     ▼
Model API
     │
     ▼
Model Service
     │
     ▼
AI Model
     │
     │ Model Response
     ▼
Application

模型 API 的核心价值在于：

将复杂的模型推理能力封装为应用程序可以调用的接口。

三、API、HTTP、REST、JSON 和 SDK 有什么区别？

这些概念经常同时出现，但它们属于不同层次。

3.1 HTTP

HTTP 是 Hypertext Transfer Protocol 的缩写，即超文本传输协议。

它是 Web 应用中广泛使用的请求—响应通信协议。

例如：

http

POST /v1/responses HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

HTTP 定义了请求方法、请求头、消息体、状态码等通信机制。

3.2 HTTPS

HTTPS 是通过 TLS 提供传输安全保护的 HTTP。

模型 API 通常使用 HTTPS，以保护请求和响应在传输过程中的机密性与完整性。

但 HTTPS 不能替代服务端访问控制、数据治理或密钥管理。

3.3 REST

REST 是 Representational State Transfer 的缩写。

它是一种用于设计网络应用接口的架构风格。

REST 风格的 API 通常使用 HTTP 方法和资源标识组织操作。

例如：

text

GET    /models
POST   /responses
GET    /responses/{id}
DELETE /responses/{id}

但并非所有模型 API 都严格遵循 REST。

一些模型服务采用 RPC 风格的接口设计，或者通过 WebSocket、gRPC 等方式通信。

3.4 JSON

JSON 是 JavaScript Object Notation 的缩写。

它是一种常见的数据交换格式。

例如：

json

{
  "model": "example-model",
  "input": "什么是人工智能？"
}

JSON 可以表示：

字符串；
数字；
布尔值；
null；
数组；
对象。

模型 API 常使用 JSON 组织请求和响应，但图像、音频等数据也可能通过文件上传、URL、二进制数据或其他编码方式传输。

3.5 SDK

SDK 是 Software Development Kit 的缩写。

它通常是一组帮助开发者使用某项服务的软件工具。

模型服务商可能提供：

Python SDK；
JavaScript SDK；
Java SDK；
Go SDK。

SDK 通常会封装：

HTTP 请求；
身份认证；
参数序列化；
响应解析；
部分错误处理。

3.6 Endpoint

Endpoint 是 API 中可以访问的具体接口地址。

例如：

text

https://api.example.com/v1/responses

它指定了请求应该发送到哪里。

3.7 API Key

API Key 是一种用于识别或认证 API 调用者的凭证。

服务端可以根据 API Key 判断：

调用者身份；
可访问的资源；
适用的配额；
费用归属。

API Key 应被视为敏感凭证。

3.8 概念关系

text

Application
     │
     ▼
SDK
封装调用逻辑
     │
     ▼
HTTP / HTTPS
传输请求
     │
     ▼
API Endpoint
接收请求
     │
     ▼
Model Service
执行模型推理

其中，JSON 是请求和响应可能采用的数据格式，API Key 则用于身份认证。

3.9 概念对照

概念	所属层次	主要作用
API	软件接口	定义交互方式
HTTP	通信协议	传输请求与响应
HTTPS	安全通信	保护传输过程
REST	接口设计风格	组织资源与操作
JSON	数据格式	表示结构化数据
SDK	开发工具	简化 API 调用
Endpoint	接口地址	指定请求目标
API Key	访问凭证	认证调用者

四、一个模型 API 请求由什么构成？

模型 API 的具体字段取决于服务商和接口版本，但常见请求通常包含以下部分。

4.1 请求目标

首先需要确定访问哪个 API Endpoint。

例如：

text

POST /v1/responses

这里的 POST 表示向服务端提交数据。

4.2 身份认证

请求通常需要携带认证信息。

例如：

http

Authorization: Bearer YOUR_API_KEY

Bearer 是 HTTP Authorization 头中常见的一种认证方案。

4.3 模型名称

请求需要指定目标模型。

例如：

json

{
  "model": "example-model"
}

模型名称由具体服务商定义。

不同服务商可能采用不同的命名规则。

4.4 输入内容

输入可以是文本，也可以是多模态内容。

例如：

json

{
  "input": "解释一下 Transformer 的工作原理。"
}

部分接口采用消息数组表示输入：

json

{
  "messages": [
    {
      "role": "user",
      "content": "解释一下 Transformer。"
    }
  ]
}

这两种形式代表不同 API 风格，不能假设所有服务都支持相同字段。

4.5 推理参数

部分模型 API 支持：

Temperature；
Top-p；
最大输出 Token；
Stop Sequences；
随机种子；
结构化输出配置。

这些参数的可用性和含义可能因模型而异。

4.6 工具定义

如果模型支持 Function Calling，请求可能包含工具定义。

例如：

json

{
  "tools": [
    {
      "name": "search_web",
      "description": "Search information on the web"
    }
  ]
}

这只是用于说明结构的概念性示例，不是某个具体 API 的完整工具定义格式。

4.7 一个概念性请求结构

json

{
  "model": "example-model",
  "messages": [
    {
      "role": "system",
      "content": "你是一名研究助手。"
    },
    {
      "role": "user",
      "content": "解释什么是 Agent。"
    }
  ],
  "temperature": 0.3,
  "max_tokens": 500
}

需要注意：

这个示例展示的是常见的模型请求设计思想，而不是适用于所有服务商的通用 API Schema。

五、一个模型 API 响应由什么构成？

模型完成推理后，会通过 API 返回响应。

5.1 输出内容

最基本的响应包含模型生成结果。

例如：

json

{
  "output": "Agent 是能够围绕目标执行任务的软件系统。"
}

实际 API 的字段结构可能更加复杂。

5.2 响应标识

部分 API 会为请求或响应分配唯一标识。

例如：

json

{
  "id": "resp_example_123"
}

这个标识可以用于：

请求追踪；
错误诊断；
日志关联；
查询异步任务状态。

5.3 模型信息

响应可能包含实际使用的模型名称或版本。

5.4 使用量

部分模型 API 会返回 Token 使用统计。

例如：

json

{
  "usage": {
    "input_tokens": 120,
    "output_tokens": 80,
    "total_tokens": 200
  }
}

这些数据可以用于估算调用成本。

不同服务商的计费分类可能更复杂，例如区分缓存输入、不同模态或不同计算类别。

5.5 结束原因

一些接口会返回生成结束原因。

例如：

正常完成；
达到输出长度限制；
触发停止条件；
产生工具调用；
内容过滤。

不同接口的字段名称和枚举值可能不同。

5.6 响应不一定只有文本

现代模型 API 可能返回：

文本；
JSON；
工具调用请求；
图片；
音频；
文件引用；
多个内容片段。

因此，应用程序不能简单假设所有响应都只有一个字符串。

六、一次模型 API 调用经历哪些步骤？

6.1 完整调用流程

text

Application
     │
     ▼
1. 构建请求
     │
     ▼
2. 添加认证信息
     │
     ▼
3. 发送 HTTPS 请求
     │
     ▼
4. API Gateway 接收请求
     │
     ▼
5. 身份与配额检查
     │
     ▼
6. 请求验证与路由
     │
     ▼
7. 模型推理
     │
     ▼
8. 生成响应
     │
     ▼
9. 返回 API Response
     │
     ▼
10. 应用解析结果

这是常见托管模型服务的概念性流程。

不同服务商可能具有不同的内部实现。

6.2 客户端构建请求

应用程序首先准备：

输入内容；
模型名称；
推理参数；
认证信息。

6.3 网络传输

客户端通过 HTTPS 将请求发送到服务端。

6.4 API Gateway

API Gateway 是服务端可能采用的请求入口。

它可以负责：

身份认证；
请求路由；
限流；
日志；
访问控制。

但不是所有模型服务都必须使用独立的 API Gateway。

6.5 模型推理

请求被传递到模型推理服务。

推理服务负责：

处理输入；
执行模型计算；
生成输出。

对于自回归语言模型，文本生成通常涉及逐步生成 Token。

6.6 返回结果

服务端将模型输出组织为 API 响应。

6.7 客户端处理结果

客户端解析响应，并根据应用要求执行后续操作。

例如：

展示文本；
保存结果；
验证 JSON；
处理工具调用；
记录使用量。

七、如何使用 HTTP 直接调用模型？

理解原始 HTTP 请求，有助于理解 SDK 背后的工作机制。

以下使用 OpenAI Responses API 的请求形式作为具体示例。

接口路径和字段可能随 API 版本更新，实际使用时应以官方文档为准。

7.1 使用 curl

bash

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "input": "用一句话解释什么是 Agent。"
  }'

这个示例包含四个部分。

第一，Endpoint

text

https://api.openai.com/v1/responses

指定请求目标。

第二，Content-Type

http

Content-Type: application/json

声明请求体使用 JSON 格式。

第三，Authorization

http

Authorization: Bearer $OPENAI_API_KEY

提供认证凭证。

第四，Request Body

json

{
  "model": "gpt-4.1",
  "input": "用一句话解释什么是 Agent。"
}

指定模型与输入。

7.2 为什么需要环境变量？

示例中的：

bash

$OPENAI_API_KEY

表示从环境变量读取密钥。

这样可以避免直接将密钥写入代码。

但环境变量本身不是完整的密钥安全方案，还需要结合运行环境、访问权限和密钥轮换机制。

7.3 如何理解 HTTP 状态码？

HTTP 状态码可以帮助判断请求是否成功。

常见情况包括：

状态码	常见含义
200	请求成功
400	请求格式或参数错误
401	身份认证失败
403	请求被拒绝访问
404	资源不存在
408	请求超时
429	请求受到限流
500	服务端内部错误
502	网关错误
503	服务暂时不可用
504	网关超时

具体错误含义仍需要结合服务商返回的错误类型和消息判断。

八、如何通过 SDK 调用模型？

8.1 SDK 的作用

SDK 可以减少直接处理 HTTP 请求的工作。

例如，开发者不必手动完成：

请求序列化；
认证头构建；
响应反序列化；
常见错误类型映射。

8.2 Python 示例

以 OpenAI Python SDK 为例：

python

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4.1",
    input="用一句话解释什么是 Agent。"
)

print(response.output_text)

这里：

python

client = OpenAI()

创建 API 客户端。

在正确配置环境变量的情况下，SDK 可以读取认证信息。

python

client.responses.create(...)

向模型服务发起请求。

python

response.output_text

获取 SDK 提供的文本输出便利字段。

8.3 JavaScript 示例

javascript

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-4.1",
  input: "用一句话解释什么是 Agent。"
});

console.log(response.output_text);

JavaScript 示例使用异步调用。

await 表示等待 Promise 完成。

8.4 SDK 与 HTTP 的关系

text

Developer Code
      │
      ▼
SDK Method
      │
      ▼
HTTP Request
      │
      ▼
Model API
      │
      ▼
HTTP Response
      │
      ▼
SDK Object
      │
      ▼
Developer Code

SDK 不会改变模型的基本推理原理。

它主要简化应用与模型服务之间的交互。

8.5 什么时候使用 SDK？

一般而言：

快速开发可以优先考虑官方 SDK；
需要跨语言兼容时，可以使用标准 HTTP；
需要高度定制网络行为时，可以直接构建 HTTP 客户端；
需要统一接入多个服务商时，可以设计自己的模型接口适配层。

九、同步调用、流式调用和异步任务有什么区别？

模型 API 可能提供不同的执行方式。

9.1 普通请求—响应调用

最常见的方式是：

text

Client
   │
   │ Request
   ▼
Server
   │
   │ Model Inference
   ▼
Response
   │
   ▼
Client

客户端等待服务端生成结果。

这种方式适合：

短文本分类；
简单问答；
信息提取；
较短的结构化输出。

9.2 流式调用

Streaming 是指服务端在生成过程中持续发送部分结果。

text

Client
   │
   │ Request
   ▼
Server
   │
   ├── Chunk 1 ──► Client
   ├── Chunk 2 ──► Client
   ├── Chunk 3 ──► Client
   └── Complete ─► Client

流式调用能够让用户更早看到部分输出。

但它不一定减少完整生成所需的总时间。

9.3 Server-Sent Events

SSE 是 Server-Sent Events 的缩写。

它是一种允许服务器通过 HTTP 连接持续向客户端发送事件的技术。

部分模型 API 使用 SSE 实现流式输出。

9.4 流式调用示例

python

from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model="gpt-4.1",
    input="解释什么是 Transformer。",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

这段代码展示了如何接收文本增量事件。

实际工程中还需要处理：

完成事件；
错误事件；
连接中断；
非文本内容；
工具调用事件。

9.5 异步任务

异步任务模式允许客户端提交任务后，不必保持连接等待完整结果。

例如：

text

Client
   │
   │ Submit Job
   ▼
Server
   │
   │ Return Job ID
   ▼
Client
   │
   │ Later: Check Status
   ▼
Server
   │
   │ Return Result
   ▼
Client

这种模式适合：

批量任务；
长时间运行的任务；
不要求即时返回的处理流程。

9.6 三种方式比较

方式	核心特征	典型用途
普通调用	等待完整响应	简单任务
流式调用	持续接收增量结果	聊天界面、实时展示
异步任务	提交后稍后获取结果	批处理、长任务

9.7 异步编程与异步任务不是一回事

这里需要区分两个概念。

异步编程

例如 Python async/await，主要用于让程序在等待 I/O 时执行其他工作。

异步任务 API

指服务端接收任务后，通过任务 ID、状态查询或回调等方式交付结果。

二者可以结合使用，但不是同一个概念。

十、什么是模型推理参数？

模型 API 可能允许开发者控制生成行为。

10.1 Temperature

Temperature 通常用于调整生成分布的随机性。

在常见的概率采样实现中：

P_{i} = \frac{\exp (z_{i} / T)}{\sum_{j} \exp (z_{j} / T)}

其中：

$z_{i}$ ：Token 的 Logit；
$T$ ：Temperature；
$P_{i}$ ：调整后的采样概率。

一般而言：

较低 Temperature 使分布更加集中；
较高 Temperature 使分布更加平缓。

但不同模型 API 对 Temperature 的支持范围和实现可能不同。

某些模型不允许开发者调整该参数。

10.2 Top-p

Top-p 是一种基于累计概率选择候选 Token 的采样方法。

例如：

text

Token A  0.50
Token B  0.25
Token C  0.15
Token D  0.10

当 Top-p 为 0.9 时，可以选择累计概率达到阈值的最小候选集合。

随后在该集合内进行采样。

10.3 Maximum Output Tokens

该参数用于限制模型最多生成多少输出 Token。

不同 API 可能采用不同字段名称。

例如：

max_output_tokens；
max_tokens；
max_completion_tokens。

这些字段不能在不同接口之间直接互换。

10.4 Stop Sequences

Stop Sequences 用于指定生成停止条件。

例如，当模型生成某个特定字符串时停止。

并非所有模型都支持自定义 Stop Sequences。

10.5 Seed

部分模型 API 支持随机种子参数。

但设置 Seed 不一定能够保证完全确定性的输出。

结果还可能受到：

服务端实现；
模型版本；
并行计算；
数值计算差异。

等因素影响。

10.6 参数选择原则

推理参数应根据任务和模型支持情况设置。

例如：

任务	参数设计重点
信息提取	输出稳定性
创意写作	适度多样性
JSON 输出	结构约束
长报告	输出长度预算
代码生成	正确性与测试
批量分类	一致性与成本

不能简单认为某个 Temperature 数值适合所有任务。

十一、多轮对话是如何通过 API 实现的？

11.1 模型不一定自动保存对话历史

从模型推理机制看，一次请求通常需要包含模型当前应使用的上下文。

不同 API 可能提供不同的状态管理方式。

例如：

无状态调用

应用程序自行保存历史消息，并在后续请求中重新提供。

服务端状态管理

API 通过会话标识、响应标识或其他机制关联历史上下文。

这两种方式不能混为一谈。

11.2 无状态多轮对话示例

第一次：

json

{
  "messages": [
    {
      "role": "user",
      "content": "什么是 Agent？"
    }
  ]
}

第二次：

json

{
  "messages": [
    {
      "role": "user",
      "content": "什么是 Agent？"
    },
    {
      "role": "assistant",
      "content": "Agent 是能够围绕目标执行任务的系统。"
    },
    {
      "role": "user",
      "content": "它与普通聊天机器人有什么区别？"
    }
  ]
}

第二次请求包含了之前的对话内容。

模型因此能够利用历史上下文理解“它”指代什么。

11.3 多轮对话的工程问题

随着对话增长，需要考虑：

历史消息存储；
Token 消耗；
上下文截断；
消息角色；
工具调用记录；
对话状态恢复。

这些问题将在 E3 · Context Window 中深入研究。

十二、模型 API 如何支持多模态输入？

12.1 文本输入

文本是最常见的输入类型。

例如：

text

解释什么是机器学习。

12.2 图片输入

支持视觉能力的模型可以接收图片。

图片可能通过以下方式提供：

图片 URL；
Base64 编码；
文件标识；
其他服务商定义的内容结构。

12.3 音频输入

支持音频能力的 API 可能接收：

音频文件；
音频字节；
音频流；
编码后的音频数据。

12.4 视频输入

支持视频能力的接口可能使用：

视频文件；
视频帧；
帧时间戳；
视频 URL；
实时媒体流。

具体取决于模型与 API。

12.5 多模态消息结构

多模态请求可能使用内容片段数组。

例如：

json

{
  "content": [
    {
      "type": "text",
      "text": "请描述这张图片。"
    },
    {
      "type": "image",
      "url": "https://example.com/image.png"
    }
  ]
}

这是概念性结构示例。

实际 API 可能使用 input_text、input_image、image_url 等不同字段。

12.6 多模态调用需要考虑什么？

文件格式；
文件大小；
分辨率；
音频时长；
视频帧数；
模态支持范围；
上传方式；
费用与延迟。

这些因素可能直接影响模型服务的可用性。

十三、模型 API 为什么会失败？

模型 API 是网络服务，因此调用可能失败。

13.1 客户端错误

例如：

API Key 错误；
请求格式错误；
参数不支持；
模型名称错误；
输入超出限制。

13.2 服务端错误

例如：

服务暂时不可用；
推理服务故障；
内部异常；
服务过载。

13.3 网络错误

例如：

DNS 解析失败；
连接超时；
TLS 握手失败；
连接中断；
代理配置问题。

13.4 限流

Rate Limiting 是服务端限制请求速率或资源消耗的机制。

限制可能基于：

Requests per Minute；
Tokens per Minute；
并发请求数量；
账户配额。

13.5 超时

Timeout 是指某项操作在规定时间内未完成。

常见超时包括：

连接超时；
读取超时；
整体请求超时。

13.6 响应内容错误

即使 HTTP 请求成功，也可能出现应用层错误。

例如：

JSON 解析失败；
缺少必要字段；
输出被截断；
内容不符合业务约束。

因此：

HTTP 成功不等于模型任务成功。

十四、如何设计模型 API 的重试机制？

14.1 为什么需要重试？

某些 API 失败具有暂时性。

例如：

网络瞬时中断；
临时服务过载；
部分限流情况。

适当重试可能提高请求成功率。

14.2 哪些错误适合重试？

通常可以考虑重试：

部分 429 错误；
部分 500 系列错误；
临时网络异常；
特定超时。

但不能假设所有错误都适合重试。

例如，认证失败或参数错误通常需要先修正请求。

14.3 Exponential Backoff

指数退避是一种常见的重试策略。

例如：

text

第一次失败
    │
    ▼
等待 1 秒
    │
    ▼
第二次失败
    │
    ▼
等待 2 秒
    │
    ▼
第三次失败
    │
    ▼
等待 4 秒

实际工程通常还会加入随机抖动（Jitter），避免大量客户端同时重试。

14.4 重试次数限制

重试不能无限进行。

需要设置：

最大重试次数；
最大等待时间；
总体超时；
可重试错误范围。

14.5 重试与重复执行风险

这是模型 API 工程中一个容易忽略的问题。

假设请求已经到达服务端，但客户端在收到响应前发生超时。

客户端无法确定服务端是否已经完成操作。

如果直接重试，可能产生重复请求和重复计费。

对于涉及创建资源、批量任务或外部副作用的接口，还可能产生重复操作。

因此，需要根据 API 支持情况考虑：

Idempotency Key；
请求唯一标识；
状态查询；
去重机制。

并非所有模型 API 都支持幂等键。

十五、如何管理 API Key 与访问权限？

15.1 API Key 是敏感凭证

API Key 通常可以代表某个账户或项目访问模型服务。

泄漏后可能导致：

未授权调用；
费用损失；
配额耗尽；
数据安全风险。

15.2 不应将密钥写入公开代码

例如：

python

api_key = "sk-xxxxxxxx"

如果代码被上传到公开仓库，密钥可能泄漏。

15.3 使用环境变量

python

import os

api_key = os.environ["OPENAI_API_KEY"]

这是常见的开发方式。

15.4 使用 Secret Manager

在生产环境中，可以使用专门的密钥管理服务。

例如：

云服务密钥管理；
容器平台 Secret；
专门的 Secret Manager。

15.5 前端与后端的区别

对于普通 Web 应用，不应直接将长期有效的服务端 API Key 暴露在浏览器代码中。

更常见的架构是：

text

Browser
   │
   ▼
Application Backend
   │
   │ Server-side API Key
   ▼
Model API

如果服务商提供专门设计的短期客户端凭证或实时会话机制，则应按照其安全要求使用。

15.6 最小权限原则

如果服务商支持项目级凭证、权限范围和配额管理，应尽量采用最小必要权限。

15.7 密钥轮换

当密钥泄漏或需要调整访问权限时，应及时撤销旧密钥并更新凭证。

十六、如何记录和监控模型 API 调用？

16.1 为什么需要日志？

当模型应用出现问题时，开发者需要知道：

哪个请求失败；
使用了什么模型；
失败发生在什么阶段；
请求耗时多久；
消耗多少 Token；
是否触发重试。

16.2 典型日志字段

json

{
  "request_id": "req_123",
  "model": "example-model",
  "latency_ms": 1250,
  "input_tokens": 500,
  "output_tokens": 200,
  "status": "success"
}

这是应用层日志的概念性示例。

16.3 主要监控指标

指标	含义
Request Count	请求数量
Success Rate	请求成功率
Error Rate	错误率
Latency	请求延迟
Time to First Token	首个输出 Token 的等待时间
Tokens per Second	Token 生成速度
Token Usage	Token 消耗
Cost	调用成本
Retry Rate	重试比例

16.4 日志与隐私

模型输入和输出可能包含敏感数据。

因此，日志系统不应默认无限制保存完整 Prompt 和 Response。

需要考虑：

数据脱敏；
日志访问权限；
保留期限；
加密；
合规要求。

16.5 模型调用监控与任务质量监控

需要区分：

调用层监控

关注 API 是否成功、延迟和成本。

任务质量监控

关注模型是否真正完成任务。

例如，一个 API 请求可能返回 HTTP 200，但模型生成了错误答案。

因此，模型应用通常需要同时具备调用监控与质量评估。

十七、如何设计统一的模型 API 接口？

当应用需要调用多个模型服务时，直接在业务代码中使用不同 SDK 可能导致耦合。

17.1 多服务商调用的问题

例如：

text

Application
    │
    ├── Provider A SDK
    │
    ├── Provider B SDK
    │
    └── Local Model API

不同服务商可能具有不同的：

请求结构；
模型参数；
响应格式；
工具调用格式；
错误类型；
Token 统计方式。

17.2 统一接口层

可以设计一个统一模型调用接口。

text

Application
    │
    ▼
Unified Model Interface
    │
    ├── Adapter A
    │       │
    │       ▼
    │    Provider A
    │
    ├── Adapter B
    │       │
    │       ▼
    │    Provider B
    │
    └── Adapter C
            │
            ▼
         Local Model

17.3 Adapter Pattern

Adapter Pattern（适配器模式）是一种常见的软件设计模式。

它允许将不同接口转换为应用期望的统一接口。

例如：

python

class ModelClient:
    def generate(self, messages):
        raise NotImplementedError

不同服务商可以实现各自的适配器。

17.4 一个简化示例

python

class ProviderAClient(ModelClient):
    def generate(self, messages):
        # 调用 Provider A
        return "Provider A result"


class ProviderBClient(ModelClient):
    def generate(self, messages):
        # 调用 Provider B
        return "Provider B result"

应用程序只依赖统一接口：

python

def run_task(client: ModelClient, messages):
    return client.generate(messages)

这是一种概念性设计，实际生产实现需要定义请求类型、响应类型、错误处理和异步接口。

17.5 统一接口的局限

不同模型服务可能提供不同能力。

例如：

某些模型支持图片；
某些模型支持音频；
某些模型支持特定工具调用；
某些模型支持结构化输出；
某些模型不支持自定义 Temperature。

因此，统一接口不能假设所有模型能力完全相同。

实际工程需要建立：

Capability-aware Interface

即能够识别和表达不同模型能力差异的接口设计。

17.6 统一模型接口与 Model Routing

统一模型接口主要解决：

如何使用一致的方式调用不同模型？

Model Routing 则解决：

当前任务应该调用哪个模型？

两者相互配合，但职责不同。

十八、模型 API 在 Agent 中如何使用？

18.1 Agent 需要模型调用能力

Agent 通常需要通过模型完成：

任务理解；
信息分析；
决策建议；
工具选择；
结果生成。

这些能力可以通过模型 API 获得。

18.2 Agent Runtime 与 Model API

text

User
  │
  ▼
Agent Runtime
  │
  ├── 构建 Prompt
  ├── 管理 Context
  ├── 选择 Model
  │
  ▼
Model API
  │
  ▼
AI Model
  │
  ▼
Model Response
  │
  ▼
Agent Runtime
  │
  ├── 输出最终答案
  │
  └── 执行工具调用

18.3 模型与 Agent 的职责区别

模型主要负责根据输入生成输出。

Agent Runtime 则负责：

维护任务状态；
组织执行流程；
调用模型；
执行工具；
管理错误；
判断是否继续任务。

因此，模型 API 是 Agent 的基础接口之一，但不是 Agent 的完整执行机制。

18.4 多 Agent 系统中的模型调用

假设一个研究系统包含：

选题 Agent；
调研 Agent；
分析 Agent；
写作 Agent；
审核 Agent。

它们可能分别调用不同模型。

text

                 Agent System
                      │
                      ▼
                 Model Service
                      │
           ┌──────────┼──────────┐
           │          │          │
           ▼          ▼          ▼
        Model A     Model B     Model C

统一模型服务层可以管理：

模型接入；
请求路由；
调用配额；
成本统计；
错误处理。

但具体的 Agent 协作逻辑仍然由 Agent System 的编排与运行机制负责。

十九、如何从零设计一个模型 API 调用模块？

下面给出一个从简单调用逐步演进的工程方案。

19.1 第一阶段：实现基本调用

目标：

配置 API Key；
选择模型；
发送文本请求；
获取结果。

text

Application
    │
    ▼
Model SDK
    │
    ▼
Model API

19.2 第二阶段：增加错误处理

增加：

超时；
异常捕获；
可重试错误识别；
最大重试次数。

19.3 第三阶段：增加结构化请求与响应

定义统一的数据结构。

例如：

python

from dataclasses import dataclass


@dataclass
class ModelRequest:
    model: str
    prompt: str


@dataclass
class ModelResponse:
    text: str
    model: str

这是一种简化设计。

实际应用可能需要更多字段。

19.4 第四阶段：增加调用日志

记录：

请求 ID；
模型；
时间；
延迟；
Token 使用量；
错误。

19.5 第五阶段：支持流式输出

让调用模块支持：

普通响应；
流式事件。

19.6 第六阶段：支持多个模型服务

增加 Adapter。

例如：

text

ModelClient
    │
    ├── OpenAIAdapter
    ├── OtherProviderAdapter
    └── LocalModelAdapter

19.7 第七阶段：增加模型能力声明

例如：

json

{
  "model": "example-model",
  "capabilities": {
    "text": true,
    "vision": true,
    "audio": false,
    "tools": true,
    "structured_output": true
  }
}

这是应用内部能力描述的示例，并非统一行业标准。

19.8 第八阶段：集成到 Agent Runtime

最终形成：

text

Agent Runtime
     │
     ▼
Model Client
     │
     ▼
Model Adapter
     │
     ▼
Model API
     │
     ▼
Model Service

这样，Agent Runtime 就不需要直接依赖某个模型服务商的 SDK。

二十、模型 API 开发中有哪些常见误区？

20.1 误区一：API 就是一个网址

API 不只是 Endpoint。

它还包括请求方法、参数结构、认证、响应格式和错误约定。

20.2 误区二：SDK 与 API 是同一个概念

SDK 是使用 API 的开发工具。

API 是软件之间的交互接口。

20.3 误区三：所有模型 API 都兼容

不同模型服务可能具有不同的接口规范和能力限制。

即使使用相似字段，也不意味着行为完全一致。

20.4 误区四：HTTP 200 就代表模型回答正确

HTTP 200 只表示请求在协议层面成功。

任务结果仍然需要验证。

20.5 误区五：流式输出一定比普通调用更快

流式输出通常可以改善首个结果的可见时间。

但完整生成时间不一定更短。

20.6 误区六：设置 Temperature 为 0 就能保证完全确定性

模型输出还可能受到服务端实现和其他因素影响。

20.7 误区七：所有错误都可以直接重试

认证错误、参数错误和部分业务错误通常需要先修复请求。

20.8 误区八：API Key 放在前端代码里也没有关系

长期有效的服务端密钥不应暴露给不可信客户端。

20.9 误区九：模型支持 Function Calling 就意味着模型能够直接执行工具

模型通常生成工具调用请求，真正执行工具的是应用程序或 Agent Runtime。

20.10 误区十：统一模型接口意味着所有模型完全可互换

模型能力、参数支持和行为差异仍然存在。

统一接口需要明确这些差异。

二十一、核心结论

Model API 是 AI 模型应用工程的基础。

通过本篇研究，可以建立以下认识。

第一，API 是软件组件之间的交互接口。 Model API 将模型推理能力封装为应用程序可以调用的服务。

第二，HTTP、REST、JSON、SDK、Endpoint 和 API Key 属于不同技术层次。 理解这些概念有助于掌握模型 API 的完整工作机制。

第三，模型 API 请求通常包含模型选择、输入、推理参数和认证信息。 响应可能包含生成内容、使用量、状态和其他结构化信息。

第四，一次模型调用需要经过请求构建、网络传输、服务端处理、模型推理和响应解析等环节。

第五，开发者可以直接使用 HTTP，也可以通过 SDK 简化调用。

第六，普通调用、流式调用和异步任务适用于不同场景。 异步编程与服务端异步任务是不同概念。

第七，模型推理参数会影响输出行为，但不同模型对参数的支持和实现存在差异。

第八，多轮对话需要明确上下文管理方式。 模型 API 不一定自动保存完整历史。

第九，模型 API 可能因为网络、认证、限流、超时和服务端故障而失败。 需要建立适当的错误处理机制。

第十，重试需要考虑错误类型、退避策略和重复执行风险。

第十一，API Key 应当作为敏感凭证管理。 生产环境需要关注密钥保护和权限控制。

第十二，模型调用需要记录延迟、错误、Token 使用量和成本，同时注意日志隐私。

第十三，多模型应用可以建立统一模型接口层。 但必须保留对不同模型能力差异的表达。

第十四，Model API 为 Agent 提供模型调用能力，但 Agent 的任务执行、工具操作和状态管理仍由 Agent Runtime 负责。

从整个 Agent 技术体系看，Model API 是模型与应用之间最基础的工程连接点之一。

理解 Model API，意味着我们开始从“使用一个 AI 聊天产品”转向“在自己的软件系统中调用和组织 AI 能力”。

二十二、参考资料与延伸阅读

22.1 API 与网络通信基础

[1] MDN Web Docs. HTTP Overview.
介绍 HTTP 协议及其基本通信机制。
HTTP Overview

[2] MDN Web Docs. HTTP Request Methods.
介绍 GET、POST、PUT、DELETE 等 HTTP 方法。
HTTP Request Methods

[3] MDN Web Docs. HTTP Response Status Codes.
介绍 HTTP 状态码。
HTTP Response Status Codes

[4] RFC 8259. The JavaScript Object Notation (JSON) Data Interchange Format.
JSON 数据格式标准。
RFC 8259

22.2 模型 API 官方文档

[5] OpenAI. API Reference.
介绍 OpenAI 模型 API 的请求、响应和接口能力。
OpenAI API Reference

[6] OpenAI. Responses API.
介绍 Responses API 的使用方式。
OpenAI Responses API

[7] Anthropic. Messages API.
介绍 Claude Messages API。
Anthropic Messages API

[8] Google AI for Developers. Gemini API.
介绍 Gemini API。
Gemini API Documentation

22.3 模型 API 工程实践

[9] OpenAI. API Error Codes.
介绍常见 API 错误及其处理。
OpenAI API Error Codes

[10] OpenAI. Rate Limits.
介绍模型 API 的速率限制。
OpenAI Rate Limits

[11] OpenAI. Streaming API Responses.
介绍流式模型响应。
Streaming API Responses

[12] OWASP. Secrets Management Cheat Sheet.
介绍软件系统中的密钥与凭证管理。
OWASP Secrets Management Cheat Sheet

二十三、关联研究

关联文档	研究内容
M4 · 大语言模型是如何构建的？	LLM 基础
M7 · AI 模型如何生成输出？	Inference & Decoding
M8 · 如何评估 AI 模型的能力与局限？	Model Evaluation
E2 · 如何设计和管理模型输入？	Prompt Engineering
E3 · 如何管理模型的上下文窗口？	Context Window
E4 · 如何让模型生成结构化结果？	Structured Outputs
E5 · 如何让模型调用外部工具？	Function Calling
E6 · 如何选择和切换不同模型？	Model Routing
E7 · 如何部署和运行开源模型？	Model Deployment
E8 · 如何优化模型推理的性能与成本？	Inference Optimization
A2 · Agent 如何获得认知与推理能力？	Agent Model
A7 · Agent 如何调用工具并执行操作？	Agent Tools
L3 · Agent System 如何接入和管理 AI 模型？	Model Services

E1 · 如何通过 API 调用 AI 模型？ - Model API ​

专题导读 ​

一、研究概述 ​

1.1 本篇研究目标 ​

1.2 本篇研究边界 ​

二、什么是 API？ ​

2.1 API 的定义 ​

2.2 为什么软件需要 API？ ​

2.3 什么是 Model API？ ​

三、API、HTTP、REST、JSON 和 SDK 有什么区别？ ​

3.1 HTTP ​

3.2 HTTPS ​

3.3 REST ​

3.4 JSON ​

3.5 SDK ​

3.6 Endpoint ​

3.7 API Key ​

3.8 概念关系 ​

3.9 概念对照 ​

四、一个模型 API 请求由什么构成？ ​

4.1 请求目标 ​

4.2 身份认证 ​

4.3 模型名称 ​

4.4 输入内容 ​

4.5 推理参数 ​

4.6 工具定义 ​

4.7 一个概念性请求结构 ​

五、一个模型 API 响应由什么构成？ ​

5.1 输出内容 ​

5.2 响应标识 ​

5.3 模型信息 ​

5.4 使用量 ​

5.5 结束原因 ​

5.6 响应不一定只有文本 ​

六、一次模型 API 调用经历哪些步骤？ ​

6.1 完整调用流程 ​

6.2 客户端构建请求 ​

6.3 网络传输 ​

6.4 API Gateway ​

6.5 模型推理 ​

6.6 返回结果 ​

6.7 客户端处理结果 ​

七、如何使用 HTTP 直接调用模型？ ​

7.1 使用 curl ​

7.2 为什么需要环境变量？ ​

7.3 如何理解 HTTP 状态码？ ​

八、如何通过 SDK 调用模型？ ​

8.1 SDK 的作用 ​

8.2 Python 示例 ​

8.3 JavaScript 示例 ​

8.4 SDK 与 HTTP 的关系 ​

8.5 什么时候使用 SDK？ ​

九、同步调用、流式调用和异步任务有什么区别？ ​

9.1 普通请求—响应调用 ​

9.2 流式调用 ​

9.3 Server-Sent Events ​

9.4 流式调用示例 ​

9.5 异步任务 ​

9.6 三种方式比较 ​

9.7 异步编程与异步任务不是一回事 ​

十、什么是模型推理参数？ ​

10.1 Temperature ​

10.2 Top-p ​

10.3 Maximum Output Tokens ​

10.4 Stop Sequences ​

10.5 Seed ​

10.6 参数选择原则 ​

十一、多轮对话是如何通过 API 实现的？ ​

11.1 模型不一定自动保存对话历史 ​

11.2 无状态多轮对话示例 ​

11.3 多轮对话的工程问题 ​

十二、模型 API 如何支持多模态输入？ ​

12.1 文本输入 ​

12.2 图片输入 ​

12.3 音频输入 ​

12.4 视频输入 ​

12.5 多模态消息结构 ​

12.6 多模态调用需要考虑什么？ ​

十三、模型 API 为什么会失败？ ​

13.1 客户端错误 ​

E1 · 如何通过 API 调用 AI 模型？ - Model API

专题导读

一、研究概述

1.1 本篇研究目标

1.2 本篇研究边界

二、什么是 API？

2.1 API 的定义

2.2 为什么软件需要 API？

2.3 什么是 Model API？

三、API、HTTP、REST、JSON 和 SDK 有什么区别？

3.1 HTTP

3.2 HTTPS

3.3 REST

3.4 JSON

3.5 SDK

3.6 Endpoint

3.7 API Key

3.8 概念关系

3.9 概念对照

四、一个模型 API 请求由什么构成？

4.1 请求目标

4.2 身份认证

4.3 模型名称

4.4 输入内容

4.5 推理参数

4.6 工具定义

4.7 一个概念性请求结构

五、一个模型 API 响应由什么构成？

5.1 输出内容

5.2 响应标识

5.3 模型信息

5.4 使用量

5.5 结束原因

5.6 响应不一定只有文本

六、一次模型 API 调用经历哪些步骤？

6.1 完整调用流程

6.2 客户端构建请求

6.3 网络传输

6.4 API Gateway

6.5 模型推理

6.6 返回结果

6.7 客户端处理结果

七、如何使用 HTTP 直接调用模型？

7.1 使用 curl

7.2 为什么需要环境变量？

7.3 如何理解 HTTP 状态码？

八、如何通过 SDK 调用模型？

8.1 SDK 的作用

8.2 Python 示例

8.3 JavaScript 示例

8.4 SDK 与 HTTP 的关系

8.5 什么时候使用 SDK？

九、同步调用、流式调用和异步任务有什么区别？

9.1 普通请求—响应调用

9.2 流式调用

9.3 Server-Sent Events

9.4 流式调用示例

9.5 异步任务

9.6 三种方式比较

9.7 异步编程与异步任务不是一回事

十、什么是模型推理参数？

10.1 Temperature

10.2 Top-p

10.3 Maximum Output Tokens

10.4 Stop Sequences

10.5 Seed

10.6 参数选择原则

十一、多轮对话是如何通过 API 实现的？

11.1 模型不一定自动保存对话历史

11.2 无状态多轮对话示例

11.3 多轮对话的工程问题

十二、模型 API 如何支持多模态输入？

12.1 文本输入

12.2 图片输入

12.3 音频输入

12.4 视频输入

12.5 多模态消息结构

12.6 多模态调用需要考虑什么？

十三、模型 API 为什么会失败？

13.1 客户端错误