提交 2f1dd3a9 authored 作者: zhangqianwei's avatar zhangqianwei

ljy_完成模块五-LLM-API调用(第二版)

上级 39c76d6d
......@@ -4,106 +4,81 @@
>
> **章节列表**:
> - 5.1 Prompt Engineering
> - **5.2 OpenAI API 调用** ← 本文档当前章节(★5 重点)
> - 5.2 OpenAI API 调用
> - 5.3 流式输出
> - 5.4 Function Calling
>
> **阅读建议**:先把 `5.2` 里的调用链路跑通,再去看 `5.3` 和 `5.4`。基础调用如果没吃透,后面的流式和工具调用会像“会背词但不会说话”。
> **阅读建议**:建议按 `5.1 -> 5.2 -> 5.3 -> 5.4` 的顺序往下看。先学会怎么把问题问清楚,再学会怎么把请求发出去,最后再去处理流式返回和工具调用。
---
## 5.2 OpenAI API 调用
## 本模块学习目标
> OpenAI API 调用这章的目标,不是让你背几个参数名,而是让你清楚“请求是怎么发出去的、上下文是怎么组织的、结果是怎么取回来的、报错时该从哪里查”。真正做业务接入时,这些能力比“会复制一段示例代码”更重要。
完成本模块后,你应当至少具备下面这些能力:
- 能区分 Zero-shot、Few-shot、CoT、角色提示、结构化输出等常见 Prompt 技巧。
- 能写出一次完整的 OpenAI API 调用,并解释 `messages`、`usage`、错误处理和多轮对话。
- 能理解流式输出为什么会分块返回,并写出最小流式调用示例。
- 能写出一个带 JSON Schema 的 Function Calling 案例,并说明模型调用工具的完整流程。
---
## 5.1 Prompt Engineering
> Prompt Engineering 的目标不是“堆更多字”,而是把任务说清楚、说稳定、说得更容易让模型按你预期执行。对于真正做业务接入的人来说,Prompt 写法往往直接决定效果上限。
>
> 📖 预计阅读时长:40 分钟 ⏱️ 实战建议:先完成环境变量配置,再依次跑通单轮调用和多轮对话示例
> 📖 预计阅读时长:35 分钟 ⏱️ 实战建议:同一个问题分别用 Zero-shot、Few-shot、CoT 跑一次,对比输出差异
### 📋 本章知识点速览
| 编号 | 知识点 | 难度 | 一句话概括 |
| --- | --- | --- | --- |
| 5.2.1 | API Key 配置 | ★★☆☆☆ | 先让程序拥有调用模型的权限 |
| 5.2.2 | 基本调用(Chat Completions) | ★★★★☆ | 先跑通一轮最小请求 |
| 5.2.3 | `messages` 格式 | ★★★★☆ | 上下文是怎么组织起来的 |
| 5.2.4 | Token 计算 | ★★★★☆ | 为什么一次请求会产生成本 |
| 5.2.5 | 错误处理 | ★★★★★ | 让调用代码在真实环境里能稳定工作 |
| 5.2.6 | 多轮对话 | ★★★★★ | 模型为什么“记得住上文” |
| 5.2.7 | 成本优化 | ★★★★☆ | 让功能能上线,而不是账单先炸掉 |
| 5.1.1 | 零样本提示(Zero-shot) | ★★☆☆☆ | 先看模型在没有示例时怎么回答 |
| 5.1.2 | 少样本提示(Few-shot) | ★★★★☆ | 通过给示例约束模型输出风格 |
| 5.1.3 | Chain-of-Thought(CoT) | ★★★★☆ | 让模型按步骤展开复杂推理 |
| 5.1.4 | 角色提示 | ★★★☆☆ | 先设定身份,再提任务 |
| 5.1.5 | 结构化输出 | ★★★★☆ | 让模型输出更适合程序处理的结果 |
| 5.1.6 | 温度与 Top-p | ★★★★☆ | 控制输出稳定性和发散度 |
| 5.1.7 | Prompt 迭代优化 | ★★★★★ | 从“能用”走到“稳定可用” |
---
### 5.2.0 章节导读:先跑通一次“最小可用调用”
### 5.1.0 章节导读:Prompt 不是“随便问一句”,而是在设计输入
> 如果你是第一次接 OpenAI API,先不要急着理解所有参数。先把“环境变量配置 -> 创建客户端 -> 发请求 -> 读取返回内容”这条链跑通。
> 如果把模型看成一个能力很强但也很“较真”的执行者,那么 Prompt 就不是普通聊天,而是你给它下达任务说明书。
#### 这章最重要的 4 件事
```text
1. 知道 API Key 放在哪里
2. 知道最小调用代码怎么写
3. 知道 messages 是怎么组织上下文的
4. 知道常见报错该怎么处理
1. 知道什么情况下 Zero-shot 就够用
2. 知道什么时候要补 Few-shot 示例
3. 知道复杂任务为什么经常要用 CoT
4. 知道 Prompt 不理想时该怎么迭代,而不是盲猜
```
#### 一张图看懂一次 API 调用
#### 一张图看懂 Prompt 优化主线
```text
┌─────────────────────────────┐
│ 本地 Python 代码 │
│ 负责组织请求和处理返回结果 │
└──────────────┬──────────────┘
│
v
┌─────────────────────────────┐
│ 读取 OPENAI_API_KEY │
│ 提供调用模型所需的身份凭证 │
└──────────────┬──────────────┘
│
v
┌─────────────────────────────┐
│ 创建 OpenAI 客户端 │
│ client = OpenAI(...) │
└──────────────┬──────────────┘
│
v
┌─────────────────────────────┐
│ 组织请求体 │
│ messages + model + params │
└──────────────┬──────────────┘
│
v
┌─────────────────────────────┐
│ 发送请求到模型服务 │
│ chat.completions.create(...)│
└──────────────┬──────────────┘
│
v
┌─────────────────────────────┐
│ 拿到 response │
│ choices / usage / metadata │
└──────────────┬──────────────┘
│
v
┌─────────────────────────────┐
│ 提取文本 / 记录 usage │
│ 处理异常 / 拼接多轮上下文 │
└─────────────────────────────┘
关键产物:
- `messages`:模型看到的完整上下文
- `response.choices[0].message.content`:最终回答文本
- `response.usage`:本次请求的 token 消耗
任务目标不清
->
先写最小 Prompt(Zero-shot)
->
观察回答哪里不稳定
->
补示例(Few-shot)或补步骤(CoT)
->
加入角色、输出格式、参数约束
->
多轮迭代,得到更稳定的可用 Prompt
```
> 🎯 **目标**:读完这章后,你应该能独立完成一次基础对话调用,能写多轮 `messages`,也知道真实项目里怎么补错误处理。
> **说明**:本章以教学示例为主,重点是帮助你理解 API 调用链路、参数组织方式和返回结果读取方式。实际运行这些示例时,需要先在本机配置有效的 `OPENAI_API_KEY`。
> 🎯 **目标**:读完这章后,你应该能根据任务类型,判断该用零样本、少样本还是 CoT,也知道 Prompt 写差时该怎么改。
---
### 5.2.1 API Key 配置
### 5.1.1 零样本提示(Zero-shot)
> 用 1-2 句话说清:OpenAI API 不是匿名调用的,程序必须先拿到凭证。这个凭证通常就是 `OPENAI_API_KEY` 环境变量。
> 用 1-2 句话说清:Zero-shot 就是不给示例,直接描述任务。它适合简单、目标明确的问题,也是写 Prompt 的起点。
---
......@@ -111,15 +86,15 @@
### 一句话定义
API Key 是调用 OpenAI API 的身份凭证,最常见做法是把它放进环境变量 `OPENAI_API_KEY`。
Zero-shot 提示是指不提供额外样例,只用任务说明直接让模型完成要求。
### 为什么重要
没有 Key,请求发不出去;Key 泄露了,别人可以直接拿你的额度去调用模型。
不是所有任务都需要复杂提示。很多基础分类、解释、改写任务,用清晰的 Zero-shot Prompt 就够了。
### 生活类比
API Key 就像公司门禁卡。没有卡进不去,乱丢卡则可能被别人冒用。
像让一个同事“帮我把这段话压缩成一句总结”,你不一定要先给他三份范例。
---
......@@ -127,40 +102,32 @@ API Key 就像公司门禁卡。没有卡进不去,乱丢卡则可能被别人
### 输入是什么
在终端里配置环境变量。
一个直接描述任务的提示词。
### 输出是什么
Python 程序能够读取到 `OPENAI_API_KEY`。
模型基于任务描述直接回答。
### 代码演示
```bash
# macOS / Linux
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
# 查看是否设置成功
echo "$OPENAI_API_KEY"
```
```python
import os
api_key = os.getenv("OPENAI_API_KEY")
print(bool(api_key)) # True 表示读取成功
messages = [
{"role": "system", "content": "你是一名严谨的文本分类助手。"},
{"role": "user", "content": "请判断这句话属于积极、消极还是中性:'这个接口延迟太高了。'"},
]
```
#### 正解 vs 错误
- 正解:把 API Key 放在环境变量里,由代码在运行时读取。
- 错误:把 Key 直接写死在脚本、笔记或仓库里。
- 错误表现:代码暂时能跑,但一旦泄露就是安全事故,后面也不方便切换不同环境。
- 正解:任务目标明确,输出范围也明确,比如“只能回答积极/消极/中性之一”。
- 错误:只说“你帮我分析一下”,却不说分析维度和输出格式。
- 错误表现:回答看起来很聪明,但结果不稳定,甚至每次输出格式都不一样。
---
### 5.2.2 基本调用(Chat Completions)
### 5.1.2 少样本提示(Few-shot)
> 用 1-2 句话说清:最小 API 调用只需要三件事:客户端、模型名、输入消息。先把这一轮跑通,再去谈多轮对话、流式输出和 Function Calling。
> 用 1-2 句话说清:Few-shot 的核心不是“给很多例子”,而是“给刚好能约束任务风格的例子”。当模型老是答偏时,Few-shot 往往比重复改文字更有效。
---
......@@ -168,15 +135,15 @@ print(bool(api_key)) # True 表示读取成功
### 一句话定义
基本调用就是通过 SDK 向模型发送一个请求,并从返回结果里取出模型生成的内容。
Few-shot 提示是通过给模型少量输入输出示例,帮助它理解你期待的回答模式。
### 为什么重要
如果单轮调用都没跑通,后面的多轮对话、流式输出、工具调用都无从谈起。
当任务有固定口径、固定风格或固定输出结构时,仅靠一句描述往往不够稳,Few-shot 能显著降低随机性。
### 生活类比
这就像第一次给客服打电话,先确认“电话能打通、对方会回话”,然后才谈复杂业务流程。
像带新人写日报,光说“照着格式写”不够,最好给他看两篇合格样例。
---
......@@ -184,51 +151,46 @@ print(bool(api_key)) # True 表示读取成功
### 输入是什么
- 环境变量中的 `OPENAI_API_KEY`
- 模型名,例如 `gpt-4.1-mini`
- 一组 `messages`
带有两个样例的提示词。
### 输出是什么
模型返回的一段文本,例如:
```text
张量可以理解为多维数组,是 PyTorch 里最基础的数据结构。
```
模型会更倾向模仿你给出的标签风格和表达方式。
### 代码演示
```python
import os
from openai import OpenAI
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
response = client.chat.completions.create(
model="gpt-4.1-mini",
messages=[
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "请用一句话解释什么是张量。"},
],
)
print(response.choices[0].message.content)
messages = [
{
"role": "system",
"content": "你是一名文本情绪分类助手,只能输出:积极、消极、中性。",
},
{
"role": "user",
"content": "示例1:'这次响应速度很快,体验不错。' -> 积极",
},
{
"role": "user",
"content": "示例2:'页面一直报错,根本没法提交。' -> 消极",
},
{
"role": "user",
"content": "现在请判断:'文档写得比较完整,但排版有点乱。'",
},
]
```
#### 正解 vs 错误
- 正解:明确客户端、模型名、`messages` 和返回内容读取路径。
- 错误:只会复制示例,不知道结果该从哪里取。
- 错误表现:一旦返回结构稍微变化,或者你要加参数时,就很容易改崩。
> 注意:模型返回内容会因模型版本、提示词、上下文不同而变化。上面的输出只是示例,不会每次完全一样。
- 正解:样例数量不必多,但要和真实任务同类型、同风格。
- 错误:给的示例和正式任务完全不是一类问题。
- 错误表现:看起来写了 Few-shot,其实模型仍然抓不到你真正想要的输出模式。
---
### 5.2.3 `messages` 格式
### 5.1.3 Chain-of-Thought(CoT)
> 用 1-2 句话说清:在 Chat Completions 里,对话上下文不是靠“自动记忆”,而是靠你把历史消息一条一条放进 `messages` 列表里。
> 用 1-2 句话说清:CoT 适合推理链较长、步骤较多的任务。它的核心不是“让模型多说话”,而是“让模型按步骤思考”。
---
......@@ -236,15 +198,15 @@ print(response.choices[0].message.content)
### 一句话定义
`messages` 是一个按时间顺序排列的消息列表,每条消息通常包含 `role` 和 `content`。
CoT(Chain-of-Thought)是一种通过提示模型分步骤展开推理过程的方法。
### 为什么重要
模型能不能“接得上话”,关键不在于它记不记得,而在于你有没有把历史上下文正确地带回去。
在数学题、逻辑题、复杂判断和多条件分析任务里,直接要答案常常不稳定,而分步骤推理更容易得到正确结果。
### 生活类比
你去找一个从没见过聊天记录的人复盘对话,必须把前文一条条给他看;否则他不知道你们刚才聊到了哪里。
像让人算一道稍复杂的题,直接报结果容易错,让他先列步骤再计算通常更稳。
---
......@@ -252,51 +214,38 @@ print(response.choices[0].message.content)
### 输入是什么
一组带角色的消息:
```python
messages = [
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "什么是损失函数?"},
{"role": "assistant", "content": "损失函数用来衡量模型预测值和真实值之间的差距。"},
{"role": "user", "content": "那它和准确率有什么区别?"},
]
```
一个明确要求“分步骤思考”的问题。
### 输出是什么
模型会基于整个上下文回答最后一个问题,而不是只看最后一条 user 消息。
模型会更倾向按步骤拆解,而不是直接跳答案。
### 代码演示
```python
messages = [
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "什么是损失函数?"},
{"role": "assistant", "content": "损失函数用来衡量模型预测值和真实值之间的差距。"},
{"role": "user", "content": "那它和准确率有什么区别?"},
{
"role": "user",
"content": (
"请一步一步分析下面的问题,再给出最终结论:"
"为什么训练循环里通常要先 zero_grad,再 backward,最后 step?"
),
},
]
```
#### 正解 vs 错误
- 正解:把 `system`、`user`、`assistant` 按时间顺序组织进同一个 `messages` 列表。
- 错误:只保留最后一句用户输入,觉得模型会“自动记住”前文。
- 错误表现:模型像失忆一样接不上话,经常出现答非所问。
#### 常见角色说明
| 角色 | 作用 |
| --- | --- |
| `system` | 设定助手身份、风格、边界 |
| `user` | 用户当前提出的问题 |
| `assistant` | 模型上一轮给出的回答 |
- 正解:把需要推理的步骤说清楚,让模型先分析再结论。
- 错误:简单任务也强行要求模型写很长的推理过程。
- 错误表现:输出又长又慢,信息密度反而下降。
---
### 5.2.4 Token 计算
### 5.1.4 角色提示
> 用 1-2 句话说清:一次 API 调用不是按“字数”收费,而通常和输入输出消耗的 token 相关。上下文越长、输出越长,成本一般越高。
> 用 1-2 句话说清:角色提示不是为了“听起来更像聊天”,而是为了约束模型回答的视角、语气和边界。它常常是稳定输出风格的第一层控制。
---
......@@ -304,15 +253,15 @@ messages = [
### 一句话定义
token 可以理解为模型处理文本时使用的基本计量单位,API 返回里通常也会带 usage 信息。
角色提示是先通过 `system` 消息或任务说明,定义模型在当前对话中的身份和行为边界。
### 为什么重要
如果你完全不关注 token,最常见的后果不是“代码报错”,而是“功能跑起来了,但成本不可控”。
同一个问题,让“面向实习生的助教”和“严格的代码审查员”来回答,输出风格会明显不同。
### 生活类比
像打出租车时按里程计费。走得越远,费用越高;上下文越长,token 通常越多。
像同一句“帮我看看这段内容”,交给老师、产品经理和测试同学,视角会完全不一样。
---
......@@ -320,45 +269,32 @@ token 可以理解为模型处理文本时使用的基本计量单位,API 返
### 输入是什么
一次普通 API 请求。
一个明确身份的系统提示词。
### 输出是什么
返回结果中常见会带 usage 信息,例如:
```text
prompt_tokens=32
completion_tokens=18
total_tokens=50
```
模型会更稳定地沿着指定身份回答。
### 代码演示
```python
response = client.chat.completions.create(
model="gpt-4.1-mini",
messages=[
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "请解释一下什么是反向传播。"},
],
)
print(response.usage.prompt_tokens)
print(response.usage.completion_tokens)
print(response.usage.total_tokens)
messages = [
{"role": "system", "content": "你是一名面向实习生授课的 PyTorch 助教,回答要通俗、分步骤。"},
{"role": "user", "content": "请解释一下什么是自动求导。"},
]
```
#### 正解 vs 错误
- 正解:通过 `response.usage` 看输入、输出和总 token 消耗。
- 错误:只看功能有没有跑通,从来不看 usage。
- 错误表现:开发阶段觉得“能用就行”,上线后才发现上下文越堆越长,成本完全失控。
- 正解:角色设定和任务场景一致,比如“面向实习生”“输出简洁”“只给结论”。
- 错误:角色提示堆很多形容词,但和任务本身没有关系。
- 错误表现:Prompt 很长,但模型行为并没有稳定下来。
---
### 5.2.5 错误处理
### 5.1.5 结构化输出
> 用 1-2 句话说清:真实业务里不能假设“每次请求都成功”。错误处理不是锦上添花,而是把示例代码升级成可用代码的关键步骤。
> 用 1-2 句话说清:当结果要给程序继续处理时,最怕的不是模型答错,而是格式乱。结构化输出的重点就是让结果更可解析、可校验、可落库。
---
......@@ -366,15 +302,15 @@ print(response.usage.total_tokens)
### 一句话定义
错误处理就是在请求失败、认证失败、限流、参数错误等情况下,给出可诊断、可恢复或可追踪的处理逻辑。
结构化输出是通过明确字段、格式或约束,让模型按照稳定结构返回结果。
### 为什么重要
没有错误处理的 API 代码,通常只能在“本地理想环境”里跑;一旦遇到网络波动、Key 配错、限流,就直接崩。
如果结果最终要被前端展示、写入数据库、做自动流转,结构混乱会比内容略有偏差更麻烦。
### 生活类比
就像出差前不仅要买票,还得准备“晚点怎么办、身份证忘带怎么办、酒店满房怎么办”的备用方案。
像报销单不是随便写一段话,而是必须按“金额、日期、用途”这些字段填。
---
......@@ -382,58 +318,39 @@ print(response.usage.total_tokens)
### 输入是什么
- 没配置 API Key
- 请求参数错误
- 网络连接失败
一个要求固定字段输出的提示词。
### 输出是什么
程序不会直接一脸空白地崩掉,而是输出更可理解的错误信息。
模型按字段要求返回更结构化的结果。
### 代码演示
```python
import os
from openai import OpenAI, APIConnectionError, AuthenticationError, BadRequestError, RateLimitError
def ask_once(question: str) -> None:
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
raise RuntimeError("未检测到 OPENAI_API_KEY,请先配置环境变量。")
client = OpenAI(api_key=api_key)
try:
response = client.chat.completions.create(
model="gpt-4.1-mini",
messages=[
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": question},
],
)
print(response.choices[0].message.content)
except AuthenticationError:
print("认证失败:请检查 API Key 是否正确。")
except RateLimitError:
print("请求过快:请稍后重试,或降低并发量。")
except BadRequestError as exc:
print(f"请求参数错误:{exc}")
except APIConnectionError:
print("网络连接失败:请检查网络或稍后重试。")
messages = [
{"role": "system", "content": "你是一名信息抽取助手。"},
{
"role": "user",
"content": (
"请从下面这句话中抽取字段,并严格按 JSON 返回:"
"{\"name\": \"\", \"deadline\": \"\", \"priority\": \"\"}。"
"句子:'李佳洋需要在明天下午前提交模块五初版,优先级较高。'"
),
},
]
```
#### 正解 vs 错误
- 正解:至少区分认证失败、限流、参数错误和网络错误这几类常见异常。
- 错误:默认所有请求都会成功,出错时只让程序直接抛 traceback。
- 错误表现:一旦放进真实服务环境,问题很难排查,用户也拿不到可理解的提示。
- 正解:明确字段名、字段含义和输出格式。
- 错误:只说“帮我转成 JSON”,但不说要哪些字段。
- 错误表现:模型确实回了 JSON,但字段名每次都不一样,后续程序无法稳定解析。
---
### 5.2.6 多轮对话
### 5.1.6 温度与 Top-p
> 用 1-2 句话说清:多轮对话的本质不是“模型自己记住了”,而是你把上文一并发回去。上下文管理写得好不好,直接决定聊天产品体验。
> 用 1-2 句话说清:温度和 Top-p 不是“越高级越好”,而是用来控制输出稳定性和发散度。教学、抽取、分类通常更偏低温度;创意写作通常更允许发散。
---
......@@ -441,15 +358,15 @@ def ask_once(question: str) -> None:
### 一句话定义
多轮对话就是在新请求里保留前面几轮 `user` 和 `assistant` 消息,让模型基于完整上下文继续回答。
温度和 Top-p 是控制模型采样行为的参数,会影响输出的稳定性、随机性和多样性。
### 为什么重要
如果你每次只发最后一句问题,模型就会像“失忆”一样答非所问。
相同 Prompt 在不同参数设置下,输出风格可能差很多。参数不合适时,你会误以为是 Prompt 写坏了。
### 生活类比
像接力聊天。你不能只把最后一句“那它为什么会这样?”丢给一个不看前文的人。
像开会发言时,有的人只按提纲说重点,有的人会自由发挥很多细节;温度和 Top-p 就像在调这个“发挥程度”。
---
......@@ -457,61 +374,1313 @@ def ask_once(question: str) -> None:
### 输入是什么
一段逐轮累积的 `messages`:
```python
messages = [
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "什么是训练循环?"},
]
```
同一个问题,不同的采样参数设置。
### 输出是什么
模型在第二轮、第三轮还能接着前面的上下文继续回答。
低温度通常更稳,高温度通常更发散。
### 代码演示
```python
import os
from openai import OpenAI
response = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "system", "content": "你是一名简洁的 AI 助教。"},
{"role": "user", "content": "请用一句话解释什么是提示词工程。"},
],
temperature=0.2,
top_p=1.0,
)
```
#### 正解 vs 错误
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
- 正解:分类、抽取、标准问答等任务优先追求稳定,可以用较低温度。
- 错误:所有任务都盲目把温度调高,觉得这样“更聪明”。
- 错误表现:输出忽左忽右,评估和上线都很难稳定。
messages = [
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "什么是训练循环?"},
]
---
response = client.chat.completions.create(
model="gpt-4.1-mini",
messages=messages,
### 5.1.7 Prompt 迭代优化
> 用 1-2 句话说清:Prompt 很少一次写对。真正的工程实践不是“凭直觉改一句”,而是基于失败案例持续迭代。
---
## 什么是这个知识点?
### 一句话定义
Prompt 迭代优化是通过观察失败样例、收集误差模式、逐步补约束与示例,让输出变得更稳定的过程。
### 为什么重要
真实业务里,模型效果差通常不是“模型不行”,而是 Prompt 目标不清、边界不清、示例不够、格式不稳。
### 生活类比
像带新人做事,不是第一次说完他就能完全按你预期执行,而是要根据出错点不断补充说明。
---
## 举个例子
### 输入是什么
一版初始 Prompt 和它对应的失败现象。
### 输出是什么
基于失败点补充更明确的约束。
### 代码演示
```text
初版 Prompt:
请总结这段会议记录。
问题:
- 有时输出太长
- 有时没有行动项
- 有时语气像口语聊天
优化后 Prompt:
请把下面会议记录总结成 3 个部分:
1. 会议主题
2. 关键结论(不超过 3 条)
3. 后续行动项(按项目符号列出)
要求:语言简洁、正式,不要输出无关寒暄。
```
#### 正解 vs 错误
- 正解:根据真实失败样例补约束、补示例、补输出格式。
- 错误:回答不理想时只会反复改一个形容词。
- 错误表现:看起来改了很多轮,实际问题模式并没有被解决。
---
## 实战代码
下面这段代码把 Zero-shot、Few-shot 和 CoT 三种常见写法放到同一个最小示例里,方便你对比输出差异。
```python
import os
from openai import OpenAI
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
prompt_cases = {
"zero_shot": [
{"role": "system", "content": "你是一名文本分类助手,只能输出:积极、消极、中性。"},
{"role": "user", "content": "请判断:'这个页面太卡了,基本没法用。'"},
],
"few_shot": [
{"role": "system", "content": "你是一名文本分类助手,只能输出:积极、消极、中性。"},
{"role": "user", "content": "示例:'响应速度很快。' -> 积极"},
{"role": "user", "content": "示例:'一直报错。' -> 消极"},
{"role": "user", "content": "请判断:'这个页面太卡了,基本没法用。'"},
],
"cot": [
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{
"role": "user",
"content": "请一步一步分析,为什么训练循环里通常要先 zero_grad,再 backward,最后 step?",
},
],
}
for name, messages in prompt_cases.items():
response = client.chat.completions.create(
model="gpt-5.5",
messages=messages,
temperature=0.2,
)
print(f"=== {name} ===")
print(response.choices[0].message.content)
```
## 常见问题
**Q:是不是 Prompt 越长越好?**
A:不是。关键信息明确最重要,冗长但模糊的 Prompt 往往不如短而清楚的 Prompt。
**Q:Few-shot 一定比 Zero-shot 强吗?**
A:不一定。任务简单时,Zero-shot 已经够用;任务风格要求高或输出不稳定时,Few-shot 会更有价值。
**Q:CoT 是不是所有任务都要用?**
A:不是。它更适合多步推理任务,简单分类或固定抽取任务强行加 CoT 反而可能拖慢输出。
**Q:为什么我明明换了很多句子,效果还是不稳定?**
A:这通常说明问题不在“措辞美化”,而在任务边界、输出格式或示例设计本身,需要回到失败案例做迭代。
## 验收标准
```text
☐ 能解释 Zero-shot、Few-shot、CoT 的区别
☐ 能写出一个 Few-shot 示例
☐ 能写出一个要求分步骤推理的 CoT Prompt
☐ 能通过角色提示稳定输出风格
☐ 能设计一个结构化输出 Prompt
☐ 能根据失败案例优化 Prompt
```
## 官方来源
- OpenAI Prompt Engineering Guide: [https://developers.openai.com/api/docs/guides/prompt-engineering](https://developers.openai.com/api/docs/guides/prompt-engineering)
- OpenAI Developer Docs 首页: [https://developers.openai.com/api](https://developers.openai.com/api)
## 参考文献
[1] OpenAI Developer Documentation, Prompt Engineering Guide, accessed on 2026-07-08.
---
## 5.2 OpenAI API 调用
> OpenAI API 调用这章的目标,不是让你背几个参数名,而是让你清楚“请求是怎么发出去的、上下文是怎么组织的、结果是怎么取回来的、报错时该从哪里查”。真正做业务接入时,这些能力比“会复制一段示例代码”更重要。
>
> 📖 预计阅读时长:40 分钟 ⏱️ 实战建议:先完成环境变量配置,再依次跑通单轮调用和多轮对话示例
### 📋 本章知识点速览
| 编号 | 知识点 | 难度 | 一句话概括 |
| --- | --- | --- | --- |
| 5.2.1 | API Key 配置 | ★★☆☆☆ | 先让程序拥有调用模型的权限 |
| 5.2.2 | 基本调用(Chat Completions) | ★★★★☆ | 先跑通一轮最小请求 |
| 5.2.3 | `messages` 格式 | ★★★★☆ | 上下文是怎么组织起来的 |
| 5.2.4 | Token 计算 | ★★★★☆ | 为什么一次请求会产生成本 |
| 5.2.5 | 错误处理 | ★★★★★ | 让调用代码在真实环境里能稳定工作 |
| 5.2.6 | 多轮对话 | ★★★★★ | 模型为什么“记得住上文” |
| 5.2.7 | 成本优化 | ★★★★☆ | 让功能能上线,而不是账单先炸掉 |
---
### 5.2.0 章节导读:先跑通一次“最小可用调用”
> 如果你是第一次接 OpenAI API,先不要急着理解所有参数。先把“环境变量配置 -> 创建客户端 -> 发请求 -> 读取返回内容”这条链跑通。
#### 这章最重要的 4 件事
```text
1. 知道 API Key 放在哪里
2. 知道最小调用代码怎么写
3. 知道 messages 是怎么组织上下文的
4. 知道常见报错该怎么处理
```
#### 一张图看懂一次 API 调用
```text
┌─────────────────────────────┐
│ 本地 Python 代码 │
│ 负责组织请求和处理返回结果 │
└──────────────┬──────────────┘
│
v
┌─────────────────────────────┐
│ 读取 OPENAI_API_KEY │
│ 提供调用模型所需的身份凭证 │
└──────────────┬──────────────┘
│
v
┌─────────────────────────────┐
│ 创建 OpenAI 客户端 │
│ client = OpenAI(...) │
└──────────────┬──────────────┘
│
v
┌─────────────────────────────┐
│ 组织请求体 │
│ messages + model + params │
└──────────────┬──────────────┘
│
v
┌─────────────────────────────┐
│ 发送请求到模型服务 │
│ chat.completions.create(...)│
└──────────────┬──────────────┘
│
v
┌─────────────────────────────┐
│ 拿到 response │
│ choices / usage / metadata │
└──────────────┬──────────────┘
│
v
┌─────────────────────────────┐
│ 提取文本 / 记录 usage │
│ 处理异常 / 拼接多轮上下文 │
└─────────────────────────────┘
关键产物:
- `messages`:模型看到的完整上下文
- `response.choices[0].message.content`:最终回答文本
- `response.usage`:本次请求的 token 消耗
```
> 🎯 **目标**:读完这章后,你应该能独立完成一次基础对话调用,能写多轮 `messages`,也知道真实项目里怎么补错误处理。
> **说明**:本章以教学示例为主,重点是帮助你理解 API 调用链路、参数组织方式和返回结果读取方式。实际运行这些示例时,需要先在本机配置有效的 `OPENAI_API_KEY`。
---
### 5.2.1 API Key 配置
> 用 1-2 句话说清:OpenAI API 不是匿名调用的,程序必须先拿到凭证。这个凭证通常就是 `OPENAI_API_KEY` 环境变量。
---
## 什么是这个知识点?
### 一句话定义
API Key 是调用 OpenAI API 的身份凭证,最常见做法是把它放进环境变量 `OPENAI_API_KEY`。
### 为什么重要
没有 Key,请求发不出去;Key 泄露了,别人可以直接拿你的额度去调用模型。
### 生活类比
API Key 就像公司门禁卡。没有卡进不去,乱丢卡则可能被别人冒用。
---
## 举个例子
### 输入是什么
在终端里配置环境变量。
### 输出是什么
Python 程序能够读取到 `OPENAI_API_KEY`。
### 代码演示
```bash
# macOS / Linux
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
# 查看是否设置成功
echo "$OPENAI_API_KEY"
```
```python
import os
api_key = os.getenv("OPENAI_API_KEY")
print(bool(api_key)) # True 表示读取成功
```
#### 正解 vs 错误
- 正解:把 API Key 放在环境变量里,由代码在运行时读取。
- 错误:把 Key 直接写死在脚本、笔记或仓库里。
- 错误表现:代码暂时能跑,但一旦泄露就是安全事故,后面也不方便切换不同环境。
---
### 5.2.2 基本调用(Chat Completions)
> 用 1-2 句话说清:最小 API 调用只需要三件事:客户端、模型名、输入消息。先把这一轮跑通,再去谈多轮对话、流式输出和 Function Calling。
---
## 什么是这个知识点?
### 一句话定义
基本调用就是通过 SDK 向模型发送一个请求,并从返回结果里取出模型生成的内容。
### 为什么重要
如果单轮调用都没跑通,后面的多轮对话、流式输出、工具调用都无从谈起。
### 生活类比
这就像第一次给客服打电话,先确认“电话能打通、对方会回话”,然后才谈复杂业务流程。
---
## 举个例子
### 输入是什么
- 环境变量中的 `OPENAI_API_KEY`
- 模型名,例如 `gpt-5.5`
- 一组 `messages`
### 输出是什么
模型返回的一段文本,例如:
```text
张量可以理解为多维数组,是 PyTorch 里最基础的数据结构。
```
### 代码演示
```python
import os
from openai import OpenAI
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
response = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "请用一句话解释什么是张量。"},
],
)
print(response.choices[0].message.content)
```
#### 正解 vs 错误
- 正解:明确客户端、模型名、`messages` 和返回内容读取路径。
- 错误:只会复制示例,不知道结果该从哪里取。
- 错误表现:一旦返回结构稍微变化,或者你要加参数时,就很容易改崩。
> 注意:模型返回内容会因模型版本、提示词、上下文不同而变化。上面的输出只是示例,不会每次完全一样。
---
### 5.2.3 `messages` 格式
> 用 1-2 句话说清:在 Chat Completions 里,对话上下文不是靠“自动记忆”,而是靠你把历史消息一条一条放进 `messages` 列表里。
---
## 什么是这个知识点?
### 一句话定义
`messages` 是一个按时间顺序排列的消息列表,每条消息通常包含 `role` 和 `content`。
### 为什么重要
模型能不能“接得上话”,关键不在于它记不记得,而在于你有没有把历史上下文正确地带回去。
### 生活类比
你去找一个从没见过聊天记录的人复盘对话,必须把前文一条条给他看;否则他不知道你们刚才聊到了哪里。
---
## 举个例子
### 输入是什么
一组带角色的消息:
```python
messages = [
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "什么是损失函数?"},
{"role": "assistant", "content": "损失函数用来衡量模型预测值和真实值之间的差距。"},
{"role": "user", "content": "那它和准确率有什么区别?"},
]
```
### 输出是什么
模型会基于整个上下文回答最后一个问题,而不是只看最后一条 user 消息。
### 代码演示
```python
messages = [
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "什么是损失函数?"},
{"role": "assistant", "content": "损失函数用来衡量模型预测值和真实值之间的差距。"},
{"role": "user", "content": "那它和准确率有什么区别?"},
]
```
#### 正解 vs 错误
- 正解:把 `system`、`user`、`assistant` 按时间顺序组织进同一个 `messages` 列表。
- 错误:只保留最后一句用户输入,觉得模型会“自动记住”前文。
- 错误表现:模型像失忆一样接不上话,经常出现答非所问。
#### 常见角色说明
| 角色 | 作用 |
| --- | --- |
| `system` | 设定助手身份、风格、边界 |
| `user` | 用户当前提出的问题 |
| `assistant` | 模型上一轮给出的回答 |
---
### 5.2.4 Token 计算
> 用 1-2 句话说清:一次 API 调用不是按“字数”收费,而通常和输入输出消耗的 token 相关。上下文越长、输出越长,成本一般越高。
---
## 什么是这个知识点?
### 一句话定义
token 可以理解为模型处理文本时使用的基本计量单位,API 返回里通常也会带 usage 信息。
### 为什么重要
如果你完全不关注 token,最常见的后果不是“代码报错”,而是“功能跑起来了,但成本不可控”。
### 生活类比
像打出租车时按里程计费。走得越远,费用越高;上下文越长,token 通常越多。
---
## 举个例子
### 输入是什么
一次普通 API 请求。
### 输出是什么
返回结果中常见会带 usage 信息,例如:
```text
prompt_tokens=32
completion_tokens=18
total_tokens=50
```
### 代码演示
```python
response = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "请解释一下什么是反向传播。"},
],
)
print(response.usage.prompt_tokens)
print(response.usage.completion_tokens)
print(response.usage.total_tokens)
```
#### 正解 vs 错误
- 正解:通过 `response.usage` 看输入、输出和总 token 消耗。
- 错误:只看功能有没有跑通,从来不看 usage。
- 错误表现:开发阶段觉得“能用就行”,上线后才发现上下文越堆越长,成本完全失控。
---
### 5.2.5 错误处理
> 用 1-2 句话说清:真实业务里不能假设“每次请求都成功”。错误处理不是锦上添花,而是把示例代码升级成可用代码的关键步骤。
---
## 什么是这个知识点?
### 一句话定义
错误处理就是在请求失败、认证失败、限流、参数错误等情况下,给出可诊断、可恢复或可追踪的处理逻辑。
### 为什么重要
没有错误处理的 API 代码,通常只能在“本地理想环境”里跑;一旦遇到网络波动、Key 配错、限流,就直接崩。
### 生活类比
就像出差前不仅要买票,还得准备“晚点怎么办、身份证忘带怎么办、酒店满房怎么办”的备用方案。
---
## 举个例子
### 输入是什么
- 没配置 API Key
- 请求参数错误
- 网络连接失败
### 输出是什么
程序不会直接一脸空白地崩掉,而是输出更可理解的错误信息。
### 代码演示
```python
import os
from openai import OpenAI, APIConnectionError, AuthenticationError, BadRequestError, RateLimitError
def ask_once(question: str) -> None:
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
raise RuntimeError("未检测到 OPENAI_API_KEY,请先配置环境变量。")
client = OpenAI(api_key=api_key)
try:
response = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": question},
],
)
print(response.choices[0].message.content)
except AuthenticationError:
print("认证失败:请检查 API Key 是否正确。")
except RateLimitError:
print("请求过快:请稍后重试,或降低并发量。")
except BadRequestError as exc:
print(f"请求参数错误:{exc}")
except APIConnectionError:
print("网络连接失败:请检查网络或稍后重试。")
```
#### 正解 vs 错误
- 正解:至少区分认证失败、限流、参数错误和网络错误这几类常见异常。
- 错误:默认所有请求都会成功,出错时只让程序直接抛 traceback。
- 错误表现:一旦放进真实服务环境,问题很难排查,用户也拿不到可理解的提示。
---
### 5.2.6 多轮对话
> 用 1-2 句话说清:多轮对话的本质不是“模型自己记住了”,而是你把上文一并发回去。上下文管理写得好不好,直接决定聊天产品体验。
---
## 什么是这个知识点?
### 一句话定义
多轮对话就是在新请求里保留前面几轮 `user` 和 `assistant` 消息,让模型基于完整上下文继续回答。
### 为什么重要
如果你每次只发最后一句问题,模型就会像“失忆”一样答非所问。
### 生活类比
像接力聊天。你不能只把最后一句“那它为什么会这样?”丢给一个不看前文的人。
---
## 举个例子
### 输入是什么
一段逐轮累积的 `messages`:
```python
messages = [
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "什么是训练循环?"},
]
```
### 输出是什么
模型在第二轮、第三轮还能接着前面的上下文继续回答。
### 代码演示
```python
import os
from openai import OpenAI
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
messages = [
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "什么是训练循环?"},
]
response = client.chat.completions.create(
model="gpt-5.5",
messages=messages,
)
assistant_reply = response.choices[0].message.content
print("assistant:", assistant_reply)
messages.append({"role": "assistant", "content": assistant_reply})
messages.append({"role": "user", "content": "那为什么每个 batch 都要 zero_grad?"})
response = client.chat.completions.create(
model="gpt-5.5",
messages=messages,
)
print("assistant:", response.choices[0].message.content)
```
#### 正解 vs 错误
- 正解:每轮都把上一轮的 `assistant` 回复追加回 `messages`,再加上新的用户问题。
- 错误:第二轮只发一句“那为什么会这样?”之类的跟进提问。
- 错误表现:模型不知道“这样”指什么,回答会明显跑偏。
---
### 5.2.7 成本优化
> 用 1-2 句话说清:API 能跑通只是第一步,能不能长期稳定地上线,还取决于成本是否可控。很多项目不是被技术卡住,而是被账单卡住。
---
## 什么是这个知识点?
### 一句话定义
成本优化就是在满足效果要求的前提下,通过控制模型选择、上下文长度和输出长度等手段,降低单次请求和整体调用成本。
### 为什么重要
开发阶段一两次调用看不出问题,但一旦放进循环、批量处理或者真实用户场景里,成本会被迅速放大。
### 生活类比
像点外卖,不是每顿都必须点最贵套餐;适合的份量和配置,长期看最重要。
---
## 举个例子
### 输入是什么
一个不断追加历史消息的聊天程序。
### 输出是什么
通过裁剪历史记录、选择合适模型、压缩系统提示词,让单次请求 token 更低。
### 代码演示
```python
def keep_recent_messages(messages: list[dict], max_rounds: int = 3) -> list[dict]:
system_message = messages[:1]
recent_history = messages[1:][-2 * max_rounds :]
return system_message + recent_history
```
#### 正解 vs 错误
- 正解:保留系统消息,再按轮数裁剪最近历史,控制上下文长度。
- 错误:无上限地把所有历史消息一直往后堆。
- 错误表现:单次请求越来越重,响应变慢,token 和成本越来越难控制。
#### 3 条最常用的成本优化建议
1. 不要无上限保留全部历史消息,定期裁剪上下文。
2. 在满足效果的前提下,优先选择更轻量的模型。
3. 系统提示词写清楚即可,不要堆很多重复约束。
---
## 正解 vs 错误
| 场景 | 正解 ✅ | 错误 ❌ | 错误表现 |
| --- | --- | --- | --- |
| Key 管理 | 用环境变量保存 API Key | 把 Key 直接硬编码进仓库 | 泄露凭证,存在安全风险 |
| 基础调用 | 明确模型名、messages、结果读取路径 | 只复制一段代码,不知道返回结构 | 一换接口或字段就不会改 |
| 多轮对话 | 把历史消息一并带回 | 每次只发最后一句用户输入 | 模型像“失忆”一样接不上话 |
| 错误处理 | 捕获认证、限流、网络异常 | 默认所有请求都会成功 | 程序在真实环境里容易直接崩掉 |
| 成本控制 | 关注 usage、裁剪上下文 | 上下文无限堆积 | token 飙升,成本不可控 |
**错误示例 1:把 API Key 写死在代码里**
```python
client = OpenAI(api_key="sk-1234567890")
```
这种写法最大的问题不是“不优雅”,而是**高风险泄露**。一旦代码被提交到仓库,别人就可能直接使用你的额度。
**错误示例 2:多轮对话不回传历史**
```python
response = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "user", "content": "那为什么它会这样?"},
],
)
```
这种情况下,模型根本不知道“它”指的是什么,很容易答偏。
---
## 原理深入
### 核心逻辑
一次标准调用至少包括四步:
```text
1. 准备凭证
2. 组织请求体
3. 发送请求
4. 读取结果并处理异常
```
### 为什么 `messages` 能实现上下文
因为服务端不会神奇地“自动记住你上一轮在说什么”,真正起作用的是你把上下文重新放进了这次请求中。换句话说,**多轮对话的本质是“上下文重放”**。
### 一个最小心智模型
```text
system: 你是谁,要遵守什么规则
user: 我现在问了什么
assistant: 你上一轮怎么回答的
--------------------------------
把这些一起发给模型
--------------------------------
模型基于完整上下文继续回答
```
---
## 实战代码
下面这段示例把环境变量、单轮调用、usage 读取和多轮对话都串起来了。你可以先把它当成完整模板来理解调用流程;如果后续需要真实运行,再补上官方 SDK 和有效的 `OPENAI_API_KEY` 即可。
```python
import os
from openai import OpenAI, APIConnectionError, AuthenticationError, BadRequestError, RateLimitError
def main() -> None:
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
raise RuntimeError("请先设置 OPENAI_API_KEY 环境变量。")
client = OpenAI(api_key=api_key)
messages = [
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "请用两句话解释什么是训练循环。"},
]
try:
response = client.chat.completions.create(
model="gpt-5.5",
messages=messages,
)
answer = response.choices[0].message.content
print("assistant:", answer)
print("usage:", response.usage)
messages.append({"role": "assistant", "content": answer})
messages.append({"role": "user", "content": "那为什么每个 batch 都要 zero_grad?"})
follow_up = client.chat.completions.create(
model="gpt-5.5",
messages=messages,
)
print("assistant:", follow_up.choices[0].message.content)
except AuthenticationError:
print("认证失败:请检查 API Key。")
except RateLimitError:
print("请求过快:请稍后重试。")
except BadRequestError as exc:
print(f"请求参数错误:{exc}")
except APIConnectionError:
print("网络连接失败:请检查网络连接。")
if __name__ == "__main__":
main()
```
---
## 常见问题
**Q:为什么一定要用环境变量保存 API Key?**
A:因为这是最常见、也最安全的基础做法。把 Key 写进代码或提交到仓库,会带来非常现实的泄露风险。
**Q:为什么我第二轮提问时,模型像没看过上一轮内容?**
A:因为你没有把上一轮的 `assistant` 回复和之前的 `user` 消息一起放回 `messages`。模型不是自动记忆,而是依赖你重传上下文。
**Q:为什么我能拿到回答,却不知道这次花了多少 token?**
A:因为你还没看 `response.usage`。这个字段通常能帮助你快速判断输入、输出和总 token 消耗。
**Q:为什么明明代码没问题,还是请求失败?**
A:真实环境里最常见的是三类问题:Key 没配对、网络不通、请求太快被限流。所以调用代码里一定要有错误处理,而不是默认所有请求都成功。
**Q:为什么这章先讲 Chat Completions,不先讲更复杂的工具调用?**
A:因为工具调用建立在“基础请求已经能稳定跑通”的前提上。`5.4 Function Calling` 会在这章的基础上继续展开。
---
## 验收标准
```text
☐ 能正确配置 OPENAI_API_KEY 环境变量
☐ 能写出一次最小 Chat Completions 调用
☐ 能解释 messages 中 system / user / assistant 的作用
☐ 能通过 response.usage 查看 token 消耗
☐ 能写出带基础错误处理的 API 调用代码
☐ 能实现最小多轮对话
```
## 官方来源
- OpenAI API Quickstart: [https://developers.openai.com/api/docs/quickstart](https://developers.openai.com/api/docs/quickstart)
- OpenAI Text Generation Guide: [https://platform.openai.com/docs/guides/text-generation](https://platform.openai.com/docs/guides/text-generation)
- OpenAI Token Counting Guide: [https://developers.openai.com/api/docs/guides/token-counting](https://developers.openai.com/api/docs/guides/token-counting)
- OpenAI Chat Completions API 参考: [https://platform.openai.com/docs/api-reference/chat](https://platform.openai.com/docs/api-reference/chat)
- OpenAI Developer Docs 首页: [https://developers.openai.com/api](https://developers.openai.com/api)
## 参考文献
[1] OpenAI Developer Documentation, accessed on 2026-07-07.
---
## 5.3 流式输出
> 流式输出的意义,不是“看起来更炫”,而是让用户更早看到模型开始返回内容。对聊天产品、长回答生成、实时交互类应用来说,这通常直接影响体验。
>
> 📖 预计阅读时长:25 分钟 ⏱️ 实战建议:先跑通控制台流式打印,再去理解 chunk 拼接和前端展示
### 📋 本章知识点速览
| 编号 | 知识点 | 难度 | 一句话概括 |
| --- | --- | --- | --- |
| 5.3.1 | Streaming 原理(SSE) | ★★★☆☆ | 为什么结果不是一次性全回来 |
| 5.3.2 | 流式调用 | ★★★★☆ | 怎么边生成边接收模型输出 |
| 5.3.3 | chunk 拼接 | ★★★★☆ | 怎么把碎片结果重新拼成完整文本 |
| 5.3.4 | 前端展示 | ★★★★☆ | 怎么让用户逐字看到输出过程 |
---
### 5.3.1 Streaming 原理(SSE)
> 用 1-2 句话说清:流式输出本质上是“服务端分块推送,客户端逐块接收”。你看到的不是一整段文字一次性返回,而是很多个小片段依次到达。
---
## 什么是这个知识点?
### 一句话定义
Streaming 是指模型把生成结果分成多个小块逐步返回,客户端边收边处理,而不是等整段结果全部生成完再统一拿到。
### 为什么重要
长回答如果必须等整段生成结束再显示,用户会感觉系统“卡住了”;流式返回可以显著降低主观等待感。
### 生活类比
像客服边打字边发消息,你会先看到前几句,而不是等他把整篇写完才一次性发出来。
---
## 举个例子
### 输入是什么
一条需要较长回答的问题。
### 输出是什么
客户端不是一次收到整段文本,而是收到一连串 chunk。
### 代码演示
```text
chunk 1 -> "训练循环"
chunk 2 -> "是模型"
chunk 3 -> "反复执行"
chunk 4 -> "前向传播、损失计算..."
```
#### 正解 vs 错误
- 正解:把流式结果理解成“多个片段依次返回”。
- 错误:以为流式返回的数据结构和普通一次性返回完全一样。
- 错误表现:代码写成只取一次结果,导致边生成边显示根本不生效。
---
### 5.3.2 流式调用
> 用 1-2 句话说清:流式调用和普通调用最大的区别,是你不再等一个完整 `response`,而是迭代读取每个片段事件。
---
## 什么是这个知识点?
### 一句话定义
流式调用就是让客户端在请求模型后,持续监听返回事件,并逐块提取增量文本。
### 为什么重要
如果你不会写这一层迭代逻辑,就算 API 本身支持流式,你的产品也仍然只能表现成“整段等完再显示”。
### 生活类比
像听直播和看录播的区别。直播是边说边听,录播是等全部录完再看。
---
## 举个例子
### 输入是什么
一个开启流式返回的请求。
### 输出是什么
控制台会逐步打印模型返回的片段,而不是最后一次性打印整段结果。
### 代码演示
```python
import os
from openai import OpenAI
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
stream = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "请解释一下什么是 Function Calling。"},
],
stream=True,
)
assistant_reply = response.choices[0].message.content
print("assistant:", assistant_reply)
messages.append({"role": "assistant", "content": assistant_reply})
messages.append({"role": "user", "content": "那为什么每个 batch 都要 zero_grad?"})
for chunk in stream:
delta = chunk.choices[0].delta.content or ""
print(delta, end="", flush=True)
```
#### 正解 vs 错误
- 正解:把 `stream=True` 和事件循环读取搭配起来使用。
- 错误:开了流式模式,却还按普通 `response.choices[0].message.content` 的方式一次性取结果。
- 错误表现:要么直接报错,要么你根本没有真正看到流式效果。
---
### 5.3.3 chunk 拼接
> 用 1-2 句话说清:流式输出真正落地时,不能只“打印一下就完了”,通常还要把多个 chunk 拼回完整内容,方便记录日志、落库或后续继续对话。
---
## 什么是这个知识点?
### 一句话定义
chunk 拼接就是把流式返回的多个文本片段按顺序累计起来,得到完整回答。
### 为什么重要
如果你只在屏幕上边打边看,却不保留最终完整文本,后续日志记录、上下文续接和业务存储都会受影响。
### 生活类比
像别人一句一句发语音转文字,你最后还是得把整段内容拼回一条完整消息。
---
## 举个例子
### 输入是什么
一串逐块返回的流式事件。
### 输出是什么
程序既能边打印,也能最终得到一段完整字符串。
### 代码演示
```python
full_text = ""
for chunk in stream:
delta = chunk.choices[0].delta.content or ""
full_text += delta
print(delta, end="", flush=True)
print("\n--- 完整结果 ---")
print(full_text)
```
#### 正解 vs 错误
- 正解:一边显示 chunk,一边累积完整文本。
- 错误:只顾着实时打印,不保留最终拼接结果。
- 错误表现:用户看得到内容,但程序后面拿不到完整答案做存储或续聊。
---
### 5.3.4 前端展示
> 用 1-2 句话说清:前端展示的核心不是“会不会动”,而是“能不能随着 chunk 到达逐步更新页面”。如果前端最后还是等整段才刷出来,那就没有发挥流式价值。
---
## 什么是这个知识点?
### 一句话定义
前端展示是指把后端接收到的流式片段持续推给页面,并动态更新文本区域。
### 为什么重要
流式调用如果只在后端可见、前端没有逐步刷新,那么用户感受到的仍然是一次性返回。
### 生活类比
像演讲字幕系统,字幕要一句句往上滚,而不是等整场结束才把全文贴出来。
---
## 举个例子
### 输入是什么
后端接口返回的文本流。
### 输出是什么
页面里的文本内容随着 chunk 到达持续增长。
### 代码演示
```javascript
async function renderStream() {
const response = await fetch("/api/chat-stream");
const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");
let fullText = "";
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value, { stream: true });
fullText += chunk;
document.getElementById("output").textContent = fullText;
}
}
```
#### 正解 vs 错误
- 正解:每读到一个 chunk 就更新一次页面内容。
- 错误:把所有 chunk 收集完之后再统一渲染。
- 错误表现:用户还是要等完整结果回来,体验上和非流式几乎没区别。
---
## 原理深入
你可以把流式输出理解成下面这条链:
```text
客户端发请求
->
服务端开始生成回复
->
模型边生成边输出片段
->
SDK/后端逐块接收
->
前端逐块展示
->
同时把片段拼成完整结果
```
所以流式输出不是“多了一个参数”这么简单,它涉及三层配合:
- 模型侧:支持流式返回
- 后端侧:能逐块读取事件
- 前端侧:能逐块刷新展示
三层只要有一层没接住,最终体验就会退回到“一次性返回”。
## 实战代码
```python
import os
from openai import OpenAI
def stream_answer(question: str) -> str:
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
stream = client.chat.completions.create(
model="gpt-5.5",
messages=[
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": question},
],
stream=True,
)
full_text = ""
for chunk in stream:
delta = chunk.choices[0].delta.content or ""
full_text += delta
print(delta, end="", flush=True)
print()
return full_text
if __name__ == "__main__":
answer = stream_answer("请解释一下为什么 Few-shot 能提高输出稳定性。")
print("--- 最终拼接结果 ---")
print(answer)
```
## 常见问题
**Q:为什么流式模式下我拿不到完整 `message.content`?**
A:因为流式返回不是一次给完整消息,而是分很多个 chunk 返回,你需要自己逐块读取和拼接。
**Q:为什么我明明开了 `stream=True`,前端还是一次性显示?**
A:通常是因为前端或后端没有逐块刷新,而是在收完所有内容后才统一渲染。
**Q:流式输出是不是一定更快?**
A:不一定让“总生成时间”变短,但通常能更早让用户看到首批内容,所以主观体验会更好。
## 验收标准
```text
☐ 能解释流式输出为什么是分块返回
☐ 能写出一个最小流式调用示例
☐ 能把 chunk 拼接成完整字符串
☐ 能解释前端为什么需要逐块刷新
```
## 官方来源
- OpenAI Streaming Guide: [https://developers.openai.com/api/docs/guides/streaming-responses](https://developers.openai.com/api/docs/guides/streaming-responses)
- OpenAI Developer Docs 首页: [https://developers.openai.com/api](https://developers.openai.com/api)
## 参考文献
[1] OpenAI Developer Documentation, Streaming Guide, accessed on 2026-07-08.
---
## 5.4 Function Calling
> Function Calling 的重点不是“模型会不会写 JSON”,而是“模型能不能判断什么时候该调用工具、调用哪个工具、该传什么参数,以及拿到工具结果后怎么继续回答”。这是大模型真正接业务系统时非常关键的一步。
>
> 📖 预计阅读时长:40 分钟 ⏱️ 实战建议:先看完整调用流程,再自己改一个函数名和参数试一遍
### 📋 本章知识点速览
| 编号 | 知识点 | 难度 | 一句话概括 |
| --- | --- | --- | --- |
| 5.4.1 | Function Calling 概念 | ★★★★☆ | 让模型知道什么时候该借助工具 |
| 5.4.2 | 函数定义(JSON Schema) | ★★★★★ | 用结构化方式告诉模型函数长什么样 |
| 5.4.3 | 调用流程 | ★★★★★ | 从模型判定到执行函数再到最终回答 |
| 5.4.4 | 多轮 Function Calling | ★★★★★ | 工具调用也需要放进多轮上下文里 |
| 5.4.5 | 实际应用场景 | ★★★★★ | 把 Function Calling 真正落到业务问题上 |
---
### 5.4.1 Function Calling 概念
> 用 1-2 句话说清:Function Calling 不是让模型真的直接执行 Python 函数,而是让模型先“提出调用意图和参数”,再由你的程序决定要不要执行。
---
## 什么是这个知识点?
### 一句话定义
response = client.chat.completions.create(
model="gpt-4.1-mini",
messages=messages,
)
print("assistant:", response.choices[0].message.content)
Function Calling 是一种让模型根据用户问题选择工具、生成工具参数,并把工具结果重新纳入对话的机制。
### 为什么重要
很多业务问题不是靠模型自己编就能答好,而是必须接真实数据、数据库、搜索、天气、工单、订单等外部工具。
### 生活类比
像前台接待不会直接修空调,但她能判断“这问题该找维修师傅”,然后把工单信息传给对的人。
---
## 举个例子
### 输入是什么
用户提问:“帮我查一下北京今天的天气。”
### 输出是什么
模型不一定直接编答案,而是先提出一个类似 `get_weather(city="北京")` 的工具调用请求。
### 代码演示
```python
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的天气信息",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称"},
},
"required": ["city"],
},
},
}
]
```
#### 正解 vs 错误
- 正解:每轮都把上一轮的 `assistant` 回复追加回 `messages`,再加上新的用户问题。
- 错误:第二轮只发一句“那为什么会这样?”之类的跟进提问。
- 错误表现:模型不知道“这样”指什么,回答会明显跑偏。
- 正解:把模型看成“决定是否要用工具、要传什么参数”的一层。
- 错误:以为只要把函数写出来,模型就会自动执行本地代码。
- 错误表现:文档看懂了概念,真写代码时却不知道“谁负责执行函数”。
---
### 5.2.7 成本优化
### 5.4.2 函数定义(JSON Schema)
> 用 1-2 句话说清:API 能跑通只是第一步,能不能长期稳定地上线,还取决于成本是否可控。很多项目不是被技术卡住,而是被账单卡住。
> 用 1-2 句话说清:函数定义写得越清楚,模型越容易正确地产生参数。Function Calling 里最核心的输入之一,就是这份 JSON Schema。
---
......@@ -519,15 +1688,15 @@ print("assistant:", response.choices[0].message.content)
### 一句话定义
成本优化就是在满足效果要求的前提下,通过控制模型选择、上下文长度和输出长度等手段,降低单次请求和整体调用成本。
函数定义就是用结构化 Schema 描述函数名称、用途和参数约束,让模型知道“这个工具能做什么、参数应该怎么填”。
### 为什么重要
开发阶段一两次调用看不出问题,但一旦放进循环、批量处理或者真实用户场景里,成本会被迅速放大。
如果参数定义模糊,模型可能会乱传字段、漏传必填项,或者根本判断不出该用哪个工具。
### 生活类比
像点外卖,不是每顿都必须点最贵套餐;适合的份量和配置,长期看最重要。
像填报销单时,表格没写清“金额必须是数字、日期必须是 YYYY-MM-DD”,填的人就很容易乱填。
---
......@@ -535,196 +1704,426 @@ print("assistant:", response.choices[0].message.content)
### 输入是什么
一个不断追加历史消息的聊天程序。
一份工具定义。
### 输出是什么
通过裁剪历史记录、选择合适模型、压缩系统提示词,让单次请求 token 更低。
模型能根据定义产出更符合约束的参数。
### 代码演示
```python
def keep_recent_messages(messages: list[dict], max_rounds: int = 3) -> list[dict]:
system_message = messages[:1]
recent_history = messages[1:][-2 * max_rounds :]
return system_message + recent_history
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市天气,并返回温度与天气描述",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "需要查询的城市,例如北京、上海",
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "温度单位",
},
},
"required": ["city"],
},
},
}
]
```
#### 正解 vs 错误
- 正解:保留系统消息,再按轮数裁剪最近历史,控制上下文长度。
- 错误:无上限地把所有历史消息一直往后堆。
- 错误表现:单次请求越来越重,响应变慢,token 和成本越来越难控制。
- 正解:把字段名、字段含义、可选值和必填项写清楚。
- 错误:只有函数名,没有参数描述。
- 错误表现:模型要么不给参数,要么传一堆你程序根本接不住的字段。
#### 3 条最常用的成本优化建议
---
1. 不要无上限保留全部历史消息,定期裁剪上下文。
2. 在满足效果的前提下,优先选择更轻量的模型。
3. 系统提示词写清楚即可,不要堆很多重复约束。
### 5.4.3 调用流程
> 用 1-2 句话说清:Function Calling 真正重要的不是一个 `tools` 参数,而是完整调用流程。模型负责提议,程序负责执行,执行结果再回给模型。
---
## 正解 vs 错误
## 什么是这个知识点?
| 场景 | 正解 ✅ | 错误 ❌ | 错误表现 |
| --- | --- | --- | --- |
| Key 管理 | 用环境变量保存 API Key | 把 Key 直接硬编码进仓库 | 泄露凭证,存在安全风险 |
| 基础调用 | 明确模型名、messages、结果读取路径 | 只复制一段代码,不知道返回结构 | 一换接口或字段就不会改 |
| 多轮对话 | 把历史消息一并带回 | 每次只发最后一句用户输入 | 模型像“失忆”一样接不上话 |
| 错误处理 | 捕获认证、限流、网络异常 | 默认所有请求都会成功 | 程序在真实环境里容易直接崩掉 |
| 成本控制 | 关注 usage、裁剪上下文 | 上下文无限堆积 | token 飙升,成本不可控 |
### 一句话定义
**错误示例 1:把 API Key 写死在代码里**
调用流程通常包括:发送请求、模型返回 tool call、程序解析参数并执行函数、把结果回填给模型、模型生成最终回答。
### 为什么重要
如果你只会“让模型返回 tool_calls”,却不会把工具结果再送回模型,那么整个链路只做了一半。
### 生活类比
像客服把问题派给后端系统查数据,查完结果还得回到客服,再由客服整理成用户能理解的话。
---
## 举个例子
### 输入是什么
一个带工具定义的用户问题。
### 输出是什么
模型先给出工具调用,再由程序执行工具,最后模型产出自然语言回答。
### 代码演示
```python
client = OpenAI(api_key="sk-1234567890")
import json
import os
from openai import OpenAI
def get_weather(city: str, unit: str = "celsius") -> dict:
mock_data = {
"北京": {"temperature": 31, "description": "晴"},
"上海": {"temperature": 28, "description": "多云"},
}
result = mock_data.get(city, {"temperature": 25, "description": "未知"})
result["unit"] = unit
return result
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市天气",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名"},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "温度单位",
},
},
"required": ["city"],
},
},
}
]
messages = [
{"role": "system", "content": "你是一名天气助理。"},
{"role": "user", "content": "帮我查一下北京今天的天气,并给我一句穿衣建议。"},
]
first_response = client.chat.completions.create(
model="gpt-5.5",
messages=messages,
tools=tools,
tool_choice="auto",
)
assistant_message = first_response.choices[0].message
tool_calls = assistant_message.tool_calls or []
if tool_calls:
messages.append(assistant_message.model_dump())
for tool_call in tool_calls:
args = json.loads(tool_call.function.arguments)
tool_result = get_weather(
city=args["city"],
unit=args.get("unit", "celsius"),
)
messages.append(
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(tool_result, ensure_ascii=False),
}
)
final_response = client.chat.completions.create(
model="gpt-5.5",
messages=messages,
tools=tools,
)
print(final_response.choices[0].message.content)
```
这种写法最大的问题不是“不优雅”,而是**高风险泄露**。一旦代码被提交到仓库,别人就可能直接使用你的额度。
#### 正解 vs 错误
**错误示例 2:多轮对话不回传历史**
- 正解:模型负责产出 `tool_calls`,程序负责执行函数并回填结果。
- 错误:拿到 `tool_calls` 就结束,不继续第二次请求。
- 错误表现:用户看不到最终自然语言回答,只看到一段工具调用信息。
---
### 5.4.4 多轮 Function Calling
> 用 1-2 句话说清:工具调用不是一次性的黑盒操作。只要对话要继续,你就得把之前的 `assistant`、`tool` 和 `user` 消息一起保留进上下文。
---
## 什么是这个知识点?
### 一句话定义
多轮 Function Calling 是在多轮对话里持续保留工具调用历史,让模型能基于之前的工具结果继续回答新问题。
### 为什么重要
如果你第二轮对话不保留上一轮工具结果,模型就不知道前面查过什么、返回了什么。
### 生活类比
像医生上一轮刚看完化验单,下一轮你问“那要不要吃药”,他必须看得到前面的检查结果。
---
## 举个例子
### 输入是什么
第一轮查北京天气,第二轮继续追问“那上海呢?帮我比较一下”。
### 输出是什么
模型能基于前一轮的工具调用结果继续组织新一轮工具请求和回答。
### 代码演示
```python
response = client.chat.completions.create(
model="gpt-4.1-mini",
messages=[
{"role": "user", "content": "那为什么它会这样?"},
],
messages.append({"role": "user", "content": "那上海呢?顺便和北京做个简单比较。"})
follow_up = client.chat.completions.create(
model="gpt-5.5",
messages=messages,
tools=tools,
tool_choice="auto",
)
```
这种情况下,模型根本不知道“它”指的是什么,很容易答偏。
#### 正解 vs 错误
- 正解:保留前一轮的 `assistant` 消息和 `tool` 结果,再追加新的用户问题。
- 错误:第二轮只发一句“那上海呢?”而不带之前工具调用上下文。
- 错误表现:模型不知道“那”指什么,也不知道你们前面查过哪个城市。
---
## 原理深入
### 5.4.5 实际应用场景
### 核心逻辑
> 用 1-2 句话说清:Function Calling 真正的价值,不在示例里,而在你能不能把它接到真实工具上。凡是“回答必须基于外部真实数据”的场景,它都很有用。
一次标准调用至少包括四步:
---
## 什么是这个知识点?
### 一句话定义
实际应用场景是指把 Function Calling 接到天气查询、订单状态、工单系统、数据库检索、日程管理、RAG 检索等真实业务工具上。
### 为什么重要
很多业务问题不能接受模型自由编造,必须让它先查真实信息,再回答用户。
### 生活类比
像企业里的智能助理,不是光会说话,而是要能查系统、调接口、拿结果。
---
## 举个例子
### 输入是什么
需要依赖外部系统数据的问题,比如:
- “帮我查一下订单 1024 的状态”
- “帮我看看今天北京天气,适不适合出门”
- “帮我查一下这个客户本月有没有未完成工单”
### 输出是什么
模型根据问题选择不同工具,再结合工具结果生成用户可理解的回答。
### 代码演示
```text
1. 准备凭证
2. 组织请求体
3. 发送请求
4. 读取结果并处理异常
用户提问
->
模型判断是否要调用工具
->
返回工具名 + 参数
->
程序执行真实函数/API
->
把结果回给模型
->
模型整理成自然语言回复
```
### 为什么 `messages` 能实现上下文
#### 正解 vs 错误
因为服务端不会神奇地“自动记住你上一轮在说什么”,真正起作用的是你把上下文重新放进了这次请求中。换句话说,**多轮对话的本质是“上下文重放”**。
- 正解:把 Function Calling 用在“必须接真实数据”的问题上。
- 错误:什么都交给工具,或者什么都不交给工具。
- 错误表现:要么工具层被滥用,要么模型开始一本正经地编假数据。
### 一个最小心智模型
---
## 原理深入
Function Calling 的完整闭环可以概括成下面这张图:
```text
system: 你是谁,要遵守什么规则
user: 我现在问了什么
assistant: 你上一轮怎么回答的
--------------------------------
把这些一起发给模型
--------------------------------
模型基于完整上下文继续回答
用户问题
->
模型判断:是否需要调用工具?
->
若需要:返回工具名 + JSON 参数
->
程序解析参数并执行本地函数 / 外部 API
->
把工具结果作为 tool 消息回填
->
模型基于工具结果生成最终回答
```
---
这里最关键的不是“会不会写 schema”,而是明确三层分工:
- 模型层:负责判断要不要调用、调用哪个工具、参数怎么填
- 程序层:负责真正执行函数、连外部服务、做权限和异常控制
- 对话层:负责把工具结果重新带回模型,形成最终面向用户的回答
## 实战代码
下面这段示例把环境变量、单轮调用、usage 读取和多轮对话都串起来了。你可以先把它当成完整模板来理解调用流程;如果后续需要真实运行,再补上官方 SDK 和有效的 `OPENAI_API_KEY` 即可。
下面这段代码是一个完整的最小 Function Calling 示例,包含函数定义、工具调用、工具执行和最终回复。
```python
import json
import os
from openai import OpenAI, APIConnectionError, AuthenticationError, BadRequestError, RateLimitError
from openai import OpenAI
def main() -> None:
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
raise RuntimeError("请先设置 OPENAI_API_KEY 环境变量。")
client = OpenAI(api_key=api_key)
def get_weather(city: str, unit: str = "celsius") -> dict:
weather_map = {
"北京": {"temperature": 31, "description": "晴"},
"上海": {"temperature": 28, "description": "多云"},
}
result = weather_map.get(city, {"temperature": 25, "description": "未知"})
result["unit"] = unit
return result
def run_weather_assistant() -> None:
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市天气",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称"},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "温度单位",
},
},
"required": ["city"],
},
},
}
]
messages = [
{"role": "system", "content": "你是一名耐心的 AI 助教。"},
{"role": "user", "content": "请用两句话解释什么是训练循环。"},
{"role": "system", "content": "你是一名天气助理。"},
{"role": "user", "content": "帮我查一下北京今天的天气,并给我一句穿衣建议。"},
]
try:
response = client.chat.completions.create(
model="gpt-4.1-mini",
messages=messages,
first_response = client.chat.completions.create(
model="gpt-5.5",
messages=messages,
tools=tools,
tool_choice="auto",
)
assistant_message = first_response.choices[0].message
tool_calls = assistant_message.tool_calls or []
messages.append(assistant_message.model_dump())
for tool_call in tool_calls:
args = json.loads(tool_call.function.arguments)
tool_result = get_weather(args["city"], args.get("unit", "celsius"))
messages.append(
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(tool_result, ensure_ascii=False),
}
)
answer = response.choices[0].message.content
print("assistant:", answer)
print("usage:", response.usage)
messages.append({"role": "assistant", "content": answer})
messages.append({"role": "user", "content": "那为什么每个 batch 都要 zero_grad?"})
follow_up = client.chat.completions.create(
model="gpt-4.1-mini",
messages=messages,
)
print("assistant:", follow_up.choices[0].message.content)
except AuthenticationError:
print("认证失败:请检查 API Key。")
except RateLimitError:
print("请求过快:请稍后重试。")
except BadRequestError as exc:
print(f"请求参数错误:{exc}")
except APIConnectionError:
print("网络连接失败:请检查网络连接。")
final_response = client.chat.completions.create(
model="gpt-5.5",
messages=messages,
tools=tools,
)
print(final_response.choices[0].message.content)
if __name__ == "__main__":
main()
run_weather_assistant()
```
---
## 常见问题
**Q:为什么一定要用环境变量保存 API Key?**
A:因为这是最常见、也最安全的基础做法。把 Key 写进代码或提交到仓库,会带来非常现实的泄露风险。
**Q:为什么我第二轮提问时,模型像没看过上一轮内容?**
A:因为你没有把上一轮的 `assistant` 回复和之前的 `user` 消息一起放回 `messages`。模型不是自动记忆,而是依赖你重传上下文。
**Q:Function Calling 是不是模型自己真的执行了 Python 函数?**
**Q:为什么我能拿到回答,却不知道这次花了多少 token?**
A:不是。模型只是返回“应该调用哪个工具、参数是什么”,真正执行本地函数的是你的程序。
A:因为你还没看 `response.usage`。这个字段通常能帮助你快速判断输入、输出和总 token 消耗。
**Q:为什么我拿到了 `tool_calls`,却没有最终回答?**
**Q:为什么明明代码没问题,还是请求失败?**
A:因为你只完成了第一步。还需要执行工具,并把工具结果作为 `tool` 消息再发回模型。
A:真实环境里最常见的是三类问题:Key 没配对、网络不通、请求太快被限流。所以调用代码里一定要有错误处理,而不是默认所有请求都成功。
**Q:JSON Schema 一定要写得很复杂吗?**
**Q:为什么这章先讲 Chat Completions,不先讲更复杂的工具调用?**
A:不一定。最重要的是字段名、字段类型、必填项和含义写清楚,先保证模型能稳定产出正确参数。
A:因为工具调用建立在“基础请求已经能稳定跑通”的前提上。`5.4 Function Calling` 会在这章的基础上继续展开。
**Q:Function Calling 和普通 Prompt 最大区别是什么?**
---
A:普通 Prompt 更像“只靠模型自己回答”,Function Calling 则是“模型先决定要不要借助外部工具,再结合工具结果回答”。
## 验收标准
```text
☐ 能正确配置 OPENAI_API_KEY 环境变量
☐ 能写出一次最小 Chat Completions 调用
☐ 能解释 messages 中 system / user / assistant 的作用
☐ 能通过 response.usage 查看 token 消耗
☐ 能写出带基础错误处理的 API 调用代码
☐ 能实现最小多轮对话
☐ 能解释 Function Calling 的基本概念
☐ 能写出一个带 JSON Schema 的工具定义
☐ 能解释从 tool_calls 到最终回答的完整流程
☐ 能写出一个最小多轮 Function Calling 示例
☐ 能给出一个真实可落地的工具调用场景
```
## 官方来源
- OpenAI API Quickstart: [https://developers.openai.com/api/docs/quickstart](https://developers.openai.com/api/docs/quickstart)
- OpenAI Text Generation Guide: [https://platform.openai.com/docs/guides/text-generation](https://platform.openai.com/docs/guides/text-generation)
- OpenAI Token Counting Guide: [https://developers.openai.com/api/docs/guides/token-counting](https://developers.openai.com/api/docs/guides/token-counting)
- OpenAI Chat Completions API 参考: [https://platform.openai.com/docs/api-reference/chat](https://platform.openai.com/docs/api-reference/chat)
- OpenAI Function Calling Guide: [https://developers.openai.com/api/docs/guides/function-calling](https://developers.openai.com/api/docs/guides/function-calling)
- OpenAI Developer Docs 首页: [https://developers.openai.com/api](https://developers.openai.com/api)
## 参考文献
[1] OpenAI Developer Documentation, accessed on 2026-07-07.
[1] OpenAI Developer Documentation, Function Calling Guide, accessed on 2026-07-08.
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑!
请 注册 或者 后发表评论