一、💡 一句话理解
核心结论
API 是调用入口，请求参数是你告诉模型“使用什么模型、处理什么内容、遵循什么规则”，响应结构则是模型返回的回答、状态、请求编号和 Token 用量。
可以把一次大模型调用记成：
准备 HTTP 请求
→ 携带身份认证和请求参数
→ 发送给模型服务
→ 接收 JSON 或流式响应
→ 提取回答并返回给业务系统本文以通用 HTTP/JSON 方式讲解，并用 DeepSeek 兼容 OpenAI 格式的 Chat Completions API 作示例。不同厂商的接口名称和字段可能不同，实际开发时应以对应厂商的官方文档为准。
二、🧭 理论：它是什么
2.1 大模型 API 是什么
API 是 Application Programming Interface 的缩写，中文通常叫“应用程序编程接口”。
它可以理解为模型服务提供的一扇标准窗口：应用程序按照约定的地址、请求格式和认证方式发送请求，模型服务再按照约定返回结果。
大模型 API 通常建立在 HTTP 和 JSON 之上，因此 Java、Python、JavaScript 等语言都可以调用。
2.2 一次请求由什么组成
| 请求部分 | 示例 | 作用 |
|---|---|---|
| 请求方法 | POST | 表示提交一次生成请求 |
| URL | /chat/completions | 指定调用哪个接口 |
| 请求头 | Authorization | 进行身份认证 |
| 请求头 | Content-Type: application/json | 说明请求体格式 |
| 请求体 | model、messages | 提供模型、问题和其他配置 |
在大模型调用中，最重要的通常是请求头和 JSON 请求体。
2.3 请求参数和模型参数不是一回事
“请求参数”是本次调用时传入的配置，例如 model、messages 和输出长度限制。
“模型参数”则是模型训练后形成的内部数值，属于模型本身的能力结构。
| 概念 | 发生时间 | 示例 |
|---|---|---|
| 模型参数 | 训练模型时形成 | 模型内部的大量权重数值 |
| 请求参数 | 每次调用时传入 | model、messages、stream |
三、⚙️ 理论：它是怎么工作的
3.1 请求参数的主要类别
| 参数类别 | 常见字段 | 作用 |
|---|---|---|
| 模型选择 | model | 指定使用哪个模型 |
| 输入内容 | messages | 提供问题、上下文和角色信息 |
| 生成控制 | 温度、最大输出长度等 | 控制回答的随机性和长度 |
| 输出格式 | JSON Schema、结构化输出 | 约束模型返回的数据格式 |
| 工具调用 | tools | 允许模型调用外部函数或系统能力 |
| 流式控制 | stream | 决定一次性返回还是边生成边返回 |
不同厂商的字段名称不完全相同。例如，OpenAI Responses API 使用 input，而 DeepSeek 的 Chat Completions API 使用 messages。因此不能只背参数名，要结合实际接口文档理解参数含义。
3.2 响应结构的主要组成
一个完整响应通常包含四类信息：
响应
├── 身份信息：id、model
├── 状态信息：status、finish_reason
├── 内容信息：回答文本、结构化对象或工具调用
└── 用量信息：输入 Token、输出 Token、总 Tokenid：本次请求的唯一标识，排查问题时很有用。status：本次生成是否完成。output或choices：模型真正生成的内容，字段名取决于 API 类型；DeepSeek Chat Completions 使用choices。usage：本次请求消耗的 Token 数量，可用于成本统计和限流分析。
3.3 普通响应和流式响应
普通响应是等待模型生成完成后，一次性返回完整 JSON。
流式响应则是边生成边返回文本片段，最后再返回结束事件。它适合聊天页面，但后端解析方式不同：普通响应通常解析一个 JSON，流式响应通常解析多个 SSE 事件。
四、🚀 实践：可以拿来干什么
理解 API、请求参数和响应结构后，可以完成：
- 在 Java 后端中调用大模型完成问答。
- 根据业务场景控制输出长度、格式和风格。
- 实现普通聊天接口和 SSE 流式聊天接口。
- 统计 Token 用量、调用次数和成本。
- 处理超时、重试、限流、降级和错误响应。
- 为 Tool Calling、RAG 和 Agent 工作流提供模型调用基础。
推荐由后端屏蔽第三方模型的原始响应，返回自己的业务响应结构。这样将来更换模型供应商时，前端接口不需要跟着大幅修改。
五、🔍 最小例子
5.1 用 HTTP 调用模型
下面的示例解决“向 DeepSeek 发送一句话并获得回答”这个最小问题：
export DEEPSEEK_API_KEY="你的 DeepSeek API Key"
curl https://api.deepseek.com/chat/completions \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [
{
"role": "user",
"content": "用一句话解释什么是 API"
}
],
"thinking": {
"type": "disabled"
},
"stream": false
}'这个请求中，Authorization 用于身份认证，model 指定模型，messages 指定对话内容，stream: false 表示一次性返回完整结果。DeepSeek 官方当前提供 deepseek-v4-flash 和 deepseek-v4-pro，并使用 https://api.deepseek.com/chat/completions 调用 Chat API。DeepSeek 官方快速开始
5.2 读取简化后的响应
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"model": "deepseek-v4-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "API 是应用程序之间进行通信的接口。"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 20,
"completion_tokens": 12,
"total_tokens": 32
}
}DeepSeek Chat Completions 的回答通常从 choices[0].message.content 读取，Token 用量从 usage 读取。这是帮助理解的简化示意，不代表所有字段都会在每次响应中出现。业务代码需要根据实际 API 文档定义 DTO，并处理可选字段、错误状态和空内容。
5.3 Java 后端中的调用链
Controller 接收用户问题
→ Service 组装请求参数
→ HTTP Client 调用模型 API
→ 解析响应结构
→ 提取模型文本
→ 转换成业务响应
→ 返回给前端后端可以对外统一返回：
{
"conversationId": "conversation-001",
"answer": "API 是应用程序之间的通信接口。",
"usage": {
"inputTokens": 20,
"outputTokens": 12
}
}这样前端只依赖自己的接口，不需要知道第三方模型响应中 output、content 等内部嵌套结构。
六、⚠️ 边界与常见误区
- 请求头不是请求体参数，
Authorization通常放在 Header 中。 model写错会导致请求失败，模型名称必须以供应商实际提供的名称为准。- 不同厂商的
input、messages、content结构可能不同；DeepSeek 使用messages。 - DeepSeek 的回答通常位于
choices[0].message.content，不能假设所有接口都使用response.content。 - 流式响应和普通响应不能使用同一种解析方式。
- 即使要求模型返回 JSON，后端仍然需要进行 JSON 解析、字段校验和异常处理。
- 模型生成的是概率性结果，不代表事实一定正确。
- API Key 不能写死在 Java 源码、前端代码或 Git 仓库中。
- 重试请求可能重复扣费；如果后续接入工具调用或写操作，还可能造成重复业务执行。
- 生产环境应记录请求 ID、响应状态、耗时和用量，但不要记录 API Key 或不必要的敏感内容。
七、📌 总结
- 快速回顾：API 是应用程序调用大模型的标准入口。
- 快速回顾：请求通常由 URL、请求方法、请求头和 JSON 请求体组成。
- 快速回顾：请求参数负责描述模型、输入内容和生成规则。
- 快速回顾：响应结构通常包含回答内容、状态、请求 ID 和 Token 用量。
- 快速回顾：普通响应一次返回完整结果，流式响应分片返回结果。
- 快速回顾：Java 后端应封装第三方 API，向前端返回稳定的业务结构。
记忆句：请求把问题和规则交给模型，响应把回答和调用结果交还给业务系统。