天天调大模型接口，面试却被“API请求包含什么”问倒？我写了这篇完整解剖

非凡的大师

488人浏览 · 2026-06-23 17:07:12

非凡的大师 · 2026-06-23 17:07:12 发布

一次面试上，面试官问了一个看似基础的问题：“你了解模型API的调用吗？API请求里都包含什么？”

我自信满满地回答：“就是URL、API Key，还有现在很多都兼容OpenAI的格式……”

面试官笑了笑，追问：“协议里面还包含什么？系统提示词呢？Messages呢？参数呢？”

那一刻我意识到——我每天都在“调用API”，却从未真正看过一次完整的API请求长什么样。

这篇文章，就是我对那次面试的完整复盘。我会从一次真实的API调用出发，逐层拆解一个完整的模型API请求里到底有什么，每个参数是干什么的，以及如何调优。知识全部来源于官方文档，希望能帮你避开我踩过的坑。

首先来个大纲速览，方便复习使用：

一、一次完整的API调用，长什么样？

先看一个最基础的Chat Completions API请求（非流式）：

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "你是一位专业的Python编程助手，请用简洁清晰的方式回答问题。"
    },
    {
      "role": "user",
      "content": "如何在Python中实现一个简单的装饰器？"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 500,
  "top_p": 1.0,
  "frequency_penalty": 0.0,
  "presence_penalty": 0.0,
  "stream": false
}

这是发给 https://api.openai.com/v1/chat/completions 的POST请求体。同时，HTTP Header中还需要携带：

Authorization: Bearer sk-你的API密钥
Content-Type: application/json

就这么一个请求，背后包含了鉴权、模型选择、对话上下文、生成参数四个层面的信息。面试时我只说了URL和Key，相当于只看到了冰山露出水面的一角。

接下来，我们逐层拆解。

二、逐层拆解：一个API请求的完整构成

1. 鉴权（Authentication）—— 你是谁？

所有OpenAI API请求都必须在HTTP Header中包含API密钥：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

如果你属于多个组织，还可以通过 OpenAI-Organization 头指定使用哪个组织的配额。

关键点：

API Key在平台后台生成，绝不能提交到代码仓库
生产环境应使用环境变量或密钥管理服务
Bearer是固定前缀，后面直接跟Key，没有空格问题

2. Model —— 你用哪个模型？

model 是必填参数，指定你要调用哪个模型：

常用模型包括：

GPT-4o：多模态，速度与能力均衡
GPT-4o-mini：轻量级，成本更低
o1-preview / o1-mini：深度推理，数学和逻辑能力强
GPT-4-turbo：传统GPT-4系列

不同的模型有不同的上下文长度和能力边界，选型直接影响效果和成本。

3. Messages —— 对话的核心

messages 是必填参数，它是一个数组，包含完整的对话历史。每个消息对象包含 role 和 content。

三种核心角色

Role	说明	特点
system	系统提示词，定义模型的行为准则	只能出现在messages[0]位置
user	用户输入	最后一个message的role必须为user
assistant	模型的历史回复	用于多轮对话，和user交替出现

多轮对话的正确拼接方式

messages = [
    {"role": "system", "content": "你是一个数学老师"},
    {"role": "user", "content": "1+1等于几？"},
    {"role": "assistant", "content": "1+1等于2。"},
    {"role": "user", "content": "那2+2呢？"}  // 最新问题必须是user
]

关键规则：

system只能在开头
user和assistant必须交替出现
最后一个message必须是user

多模态支持

content不仅可以是字符串，还可以是数组，支持文本和图片混合输入：

{
  "role": "user",
  "content": [
    {"type": "text", "text": "这张图里有什么？"},
    {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
  ]
}

图片可以是URL或base64编码的数据。

4. 生成参数 —— 控制模型怎么“想”

Temperature（温度）

控制输出的随机性，取值范围0-2。

取值	效果	适用场景
0.0 - 0.3	确定性高，几乎每次输出相同	事实性问答、代码生成、分类任务
0.5 - 0.7	平衡创造性和准确性	通用对话、内容创作
0.8 - 1.2	创造性高，输出多样	头脑风暴、创意写作

原理：Temperature影响softmax函数中概率分布的“锐度”。值越低，高概率token被进一步放大，低概率token被压制；值越高，概率分布越平滑，低概率token也有机会被选中。

最佳实践：一般建议调整temperature或top_p中的一个，不要同时大幅调整两者。

Top_p（核采样）

取值范围0-1，默认1.0。它限定模型只从累积概率达到p的最可能token集合中采样。

举例：如果top_p=0.1，模型只考虑构成前10%概率质量的那些token。

temperature vs top_p：

temperature：调整整个概率分布的“平滑度”
top_p：裁剪token候选集的大小

两者都可以控制随机性，但机制不同。一般选一个调就行。

Max_tokens（最大输出长度）

控制模型最多生成多少个token。注意：prompt的token数 + max_tokens不能超过模型的上下文长度。

模型	上下文长度	建议max_tokens
GPT-4o	128K	根据任务调整，一般2K-8K
GPT-4o-mini	128K	同上
o1-preview	128K	复杂推理可设高一些

其他重要参数

参数	说明	取值范围
frequency_penalty	频率惩罚，降低重复已有token的概率	-2.0 ~ 2.0
presence_penalty	存在惩罚，鼓励谈论新话题	-2.0 ~ 2.0
seed	随机种子，相同seed可复现结果	整数
response_format	强制输出格式，如JSON	`{"type": "json_object"}`
stop	停止序列，遇到即停止生成	字符串或数组
stream	是否流式输出	true/false

5. Tools / Function Calling —— 让模型调用外部能力

这是目前AI应用开发中最核心的能力之一。Function Calling允许模型返回结构化的函数调用指令，而不是纯文本。

基本流程

你在请求中定义tools（用JSON Schema描述函数）
模型判断是否需要调用工具，如果需要，返回tool_calls
你的应用执行对应的函数
可选：将执行结果返回给模型，生成最终回答

代码示例

{
  "model": "gpt-4o",
  "messages": [
    {"role": "user", "content": "帮我查一下北京今天的天气"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称"
            }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

模型会返回：

{
  "role": "assistant",
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{\"city\": \"北京\"}"
      }
    }
  ]
}

你的应用解析arguments，执行get_weather函数，然后把结果传回模型生成最终回复。

重要提示：旧版API使用 functions 和 function_call 参数，现已弃用，新代码应统一使用 tools 和 tool_choice。

三、响应结构：模型返回了什么？

一个典型的非流式响应：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "在Python中，装饰器是一种高阶函数..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 45,
    "completion_tokens": 120,
    "total_tokens": 165
  }
}

关键字段：

choices[0].message.content：模型的回复内容
finish_reason：停止原因（stop正常结束、length达到max_tokens、tool_calls需要调用工具等）
usage：token消耗统计，直接影响计费

四、常见错误与排查

HTTP状态码	含义	排查方法
401 Unauthorized	API密钥无效或缺失	检查Authorization头和Key是否正确
400 Bad Request	请求参数错误	检查JSON格式、必填参数、参数取值范围
429 Too Many Requests	请求频率超限	降低请求频率，或提升速率限制
500 Internal Server Error	服务端错误	重试，如持续出现联系官方支持

调试建议：先检查HTTP状态码和错误消息，大部分问题都能从错误消息中定位。

五、扩展：Anthropic Messages API

除了OpenAI，Claude的API也越来越常用。Anthropic的Messages API在结构上有所不同：



{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1024,
  "system": "你是一位专业的编程助手",
  "messages": [
    {"role": "user", "content": "帮我写一个Python排序函数"}
  ]
}

主要差异：