Skip to content
项目
群组
代码片段
帮助
当前项目
正在载入...
登录 / 注册
切换导航面板
S
studyweb
项目
项目
详情
活动
周期分析
仓库
仓库
文件
提交
分支
标签
贡献者
图表
比较
统计图
议题
0
议题
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
CI / CD
CI / CD
流水线
作业
日程
统计图
Wiki
Wiki
代码片段
代码片段
成员
成员
折叠边栏
关闭边栏
活动
图像
聊天
创建新问题
作业
提交
问题看板
Open sidebar
project
studyweb
Commits
2f1dd3a9
提交
2f1dd3a9
authored
7月 08, 2026
作者:
zhangqianwei
浏览文件
操作
浏览文件
下载
电子邮件补丁
差异文件
ljy_完成模块五-LLM-API调用(第二版)
上级
39c76d6d
隐藏空白字符变更
内嵌
并排
正在显示
1 个修改的文件
包含
1769 行增加
和
370 行删除
+1769
-370
模块五-LLM-API调用.md
docs/LLM-API调用/模块五-LLM-API调用.md
+1769
-370
没有找到文件。
docs/LLM-API调用/模块五-LLM-API调用.md
浏览文件 @
2f1dd3a9
...
@@ -4,106 +4,81 @@
...
@@ -4,106 +4,81 @@
>
>
> **章节列表**:
> **章节列表**:
> - 5.1 Prompt Engineering
> - 5.1 Prompt Engineering
> -
**5.2 OpenAI API 调用** ← 本文档当前章节(★5 重点)
> -
5.2 OpenAI API 调用
> - 5.3 流式输出
> - 5.3 流式输出
> - 5.4 Function Calling
> - 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.
1.1 | 零样本提示(Zero-shot) | ★★☆☆☆ | 先看模型在没有示例时怎么回答
|
| 5.
2.2 | 基本调用(Chat Completions) | ★★★★☆ | 先跑通一轮最小请求
|
| 5.
1.2 | 少样本提示(Few-shot) | ★★★★☆ | 通过给示例约束模型输出风格
|
| 5.
2.3 |
`messages`
格式 | ★★★★☆ | 上下文是怎么组织起来的
|
| 5.
1.3 | Chain-of-Thought(CoT) | ★★★★☆ | 让模型按步骤展开复杂推理
|
| 5.
2.4 | Token 计算 | ★★★★☆ | 为什么一次请求会产生成本
|
| 5.
1.4 | 角色提示 | ★★★☆☆ | 先设定身份,再提任务
|
| 5.
2.5 | 错误处理 | ★★★★★ | 让调用代码在真实环境里能稳定工作
|
| 5.
1.5 | 结构化输出 | ★★★★☆ | 让模型输出更适合程序处理的结果
|
| 5.
2.6 | 多轮对话 | ★★★★★ | 模型为什么“记得住上文”
|
| 5.
1.6 | 温度与 Top-p | ★★★★☆ | 控制输出稳定性和发散度
|
| 5.
2.7 | 成本优化 | ★★★★☆ | 让功能能上线,而不是账单先炸掉
|
| 5.
1.7 | Prompt 迭代优化 | ★★★★★ | 从“能用”走到“稳定可用”
|
---
---
### 5.
2.0 章节导读:先跑通一次“最小可用调用”
### 5.
1.0 章节导读:Prompt 不是“随便问一句”,而是在设计输入
> 如果
你是第一次接 OpenAI API,先不要急着理解所有参数。先把“环境变量配置 -> 创建客户端 -> 发请求 -> 读取返回内容”这条链跑通
。
> 如果
把模型看成一个能力很强但也很“较真”的执行者,那么 Prompt 就不是普通聊天,而是你给它下达任务说明书
。
#### 这章最重要的 4 件事
#### 这章最重要的 4 件事
```
text
```
text
1. 知道
API Key 放在哪里
1. 知道
什么情况下 Zero-shot 就够用
2. 知道
最小调用代码怎么写
2. 知道
什么时候要补 Few-shot 示例
3. 知道
messages 是怎么组织上下文的
3. 知道
复杂任务为什么经常要用 CoT
4. 知道
常见报错该怎么处理
4. 知道
Prompt 不理想时该怎么迭代,而不是盲猜
```
```
#### 一张图看懂
一次 API 调用
#### 一张图看懂
Prompt 优化主线
```
text
```
text
┌─────────────────────────────┐
任务目标不清
│ 本地 Python 代码 │
->
│ 负责组织请求和处理返回结果 │
先写最小 Prompt(Zero-shot)
└──────────────┬──────────────┘
->
│
观察回答哪里不稳定
v
->
┌─────────────────────────────┐
补示例(Few-shot)或补步骤(CoT)
│ 读取 OPENAI_API_KEY │
->
│ 提供调用模型所需的身份凭证 │
加入角色、输出格式、参数约束
└──────────────┬──────────────┘
->
│
多轮迭代,得到更稳定的可用 Prompt
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`,也知道真实项目里怎么补错误处理。
> 🎯 **目标**:读完这章后,你应该能根据任务类型,判断该用零样本、少样本还是 CoT,也知道 Prompt 写差时该怎么改。
> **说明**:本章以教学示例为主,重点是帮助你理解 API 调用链路、参数组织方式和返回结果读取方式。实际运行这些示例时,需要先在本机配置有效的 `OPENAI_API_KEY`。
---
---
### 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 @@
...
@@ -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 就像公司门禁卡。没有卡进不去,乱丢卡则可能被别人
...
@@ -127,40 +102,32 @@ API Key 就像公司门禁卡。没有卡进不去,乱丢卡则可能被别人
### 输入是什么
### 输入是什么
在终端里配置环境变量
。
一个直接描述任务的提示词
。
### 输出是什么
### 输出是什么
Python 程序能够读取到
`OPENAI_API_KEY`
。
模型基于任务描述直接回答
。
### 代码演示
### 代码演示
```
bash
# macOS / Linux
export
OPENAI_API_KEY
=
"sk-xxxxxxxxxxxxxxxx"
# 查看是否设置成功
echo
"
$OPENAI_API_KEY
"
```
```
python
```
python
import
os
messages
=
[
{
"role"
:
"system"
,
"content"
:
"你是一名严谨的文本分类助手。"
},
api_key
=
os
.
getenv
(
"OPENAI_API_KEY"
)
{
"role"
:
"user"
,
"content"
:
"请判断这句话属于积极、消极还是中性:'这个接口延迟太高了。'"
},
print
(
bool
(
api_key
))
# True 表示读取成功
]
```
```
#### 正解 vs 错误
#### 正解 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 表示读取成功
...
@@ -168,15 +135,15 @@ print(bool(api_key)) # True 表示读取成功
### 一句话定义
### 一句话定义
基本调用就是通过 SDK 向模型发送一个请求,并从返回结果里取出模型生成的内容
。
Few-shot 提示是通过给模型少量输入输出示例,帮助它理解你期待的回答模式
。
### 为什么重要
### 为什么重要
如果单轮调用都没跑通,后面的多轮对话、流式输出、工具调用都无从谈起
。
当任务有固定口径、固定风格或固定输出结构时,仅靠一句描述往往不够稳,Few-shot 能显著降低随机性
。
### 生活类比
### 生活类比
这就像第一次给客服打电话,先确认“电话能打通、对方会回话”,然后才谈复杂业务流程
。
像带新人写日报,光说“照着格式写”不够,最好给他看两篇合格样例
。
---
---
...
@@ -184,51 +151,46 @@ print(bool(api_key)) # True 表示读取成功
...
@@ -184,51 +151,46 @@ print(bool(api_key)) # True 表示读取成功
### 输入是什么
### 输入是什么
-
环境变量中的
`OPENAI_API_KEY`
带有两个样例的提示词。
-
模型名,例如
`gpt-4.1-mini`
-
一组
`messages`
### 输出是什么
### 输出是什么
模型返回的一段文本,例如:
模型会更倾向模仿你给出的标签风格和表达方式。
```
text
张量可以理解为多维数组,是 PyTorch 里最基础的数据结构。
```
### 代码演示
### 代码演示
```
python
```
python
import
os
messages
=
[
from
openai
import
OpenAI
{
"role"
:
"system"
,
"content"
:
"你是一名文本情绪分类助手,只能输出:积极、消极、中性。"
,
client
=
OpenAI
(
api_key
=
os
.
getenv
(
"OPENAI_API_KEY"
))
},
{
response
=
client
.
chat
.
completions
.
create
(
"role"
:
"user"
,
model
=
"gpt-4.1-mini"
,
"content"
:
"示例1:'这次响应速度很快,体验不错。' -> 积极"
,
messages
=
[
},
{
"role"
:
"system"
,
"content"
:
"你是一名耐心的 AI 助教。"
},
{
{
"role"
:
"user"
,
"content"
:
"请用一句话解释什么是张量。"
},
"role"
:
"user"
,
],
"content"
:
"示例2:'页面一直报错,根本没法提交。' -> 消极"
,
)
},
{
print
(
response
.
choices
[
0
]
.
message
.
content
)
"role"
:
"user"
,
"content"
:
"现在请判断:'文档写得比较完整,但排版有点乱。'"
,
},
]
```
```
#### 正解 vs 错误
#### 正解 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)
...
@@ -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)
...
@@ -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
```
python
messages
=
[
messages
=
[
{
"role"
:
"system"
,
"content"
:
"你是一名耐心的 AI 助教。"
},
{
"role"
:
"system"
,
"content"
:
"你是一名耐心的 AI 助教。"
},
{
"role"
:
"user"
,
"content"
:
"什么是损失函数?"
},
{
{
"role"
:
"assistant"
,
"content"
:
"损失函数用来衡量模型预测值和真实值之间的差距。"
},
"role"
:
"user"
,
{
"role"
:
"user"
,
"content"
:
"那它和准确率有什么区别?"
},
"content"
:
(
"请一步一步分析下面的问题,再给出最终结论:"
"为什么训练循环里通常要先 zero_grad,再 backward,最后 step?"
),
},
]
]
```
```
#### 正解 vs 错误
#### 正解 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 = [
...
@@ -304,15 +253,15 @@ messages = [
### 一句话定义
### 一句话定义
token 可以理解为模型处理文本时使用的基本计量单位,API 返回里通常也会带 usage 信息
。
角色提示是先通过
`system`
消息或任务说明,定义模型在当前对话中的身份和行为边界
。
### 为什么重要
### 为什么重要
如果你完全不关注 token,最常见的后果不是“代码报错”,而是“功能跑起来了,但成本不可控”
。
同一个问题,让“面向实习生的助教”和“严格的代码审查员”来回答,输出风格会明显不同
。
### 生活类比
### 生活类比
像
打出租车时按里程计费。走得越远,费用越高;上下文越长,token 通常越多
。
像
同一句“帮我看看这段内容”,交给老师、产品经理和测试同学,视角会完全不一样
。
---
---
...
@@ -320,45 +269,32 @@ token 可以理解为模型处理文本时使用的基本计量单位,API 返
...
@@ -320,45 +269,32 @@ token 可以理解为模型处理文本时使用的基本计量单位,API 返
### 输入是什么
### 输入是什么
一
次普通 API 请求
。
一
个明确身份的系统提示词
。
### 输出是什么
### 输出是什么
返回结果中常见会带 usage 信息,例如:
模型会更稳定地沿着指定身份回答。
```
text
prompt_tokens=32
completion_tokens=18
total_tokens=50
```
### 代码演示
### 代码演示
```
python
```
python
response
=
client
.
chat
.
completions
.
create
(
messages
=
[
model
=
"gpt-4.1-mini"
,
{
"role"
:
"system"
,
"content"
:
"你是一名面向实习生授课的 PyTorch 助教,回答要通俗、分步骤。"
},
messages
=
[
{
"role"
:
"user"
,
"content"
:
"请解释一下什么是自动求导。"
},
{
"role"
:
"system"
,
"content"
:
"你是一名耐心的 AI 助教。"
},
]
{
"role"
:
"user"
,
"content"
:
"请解释一下什么是反向传播。"
},
],
)
print
(
response
.
usage
.
prompt_tokens
)
print
(
response
.
usage
.
completion_tokens
)
print
(
response
.
usage
.
total_tokens
)
```
```
#### 正解 vs 错误
#### 正解 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)
...
@@ -366,15 +302,15 @@ print(response.usage.total_tokens)
### 一句话定义
### 一句话定义
错误处理就是在请求失败、认证失败、限流、参数错误等情况下,给出可诊断、可恢复或可追踪的处理逻辑
。
结构化输出是通过明确字段、格式或约束,让模型按照稳定结构返回结果
。
### 为什么重要
### 为什么重要
没有错误处理的 API 代码,通常只能在“本地理想环境”里跑;一旦遇到网络波动、Key 配错、限流,就直接崩
。
如果结果最终要被前端展示、写入数据库、做自动流转,结构混乱会比内容略有偏差更麻烦
。
### 生活类比
### 生活类比
就像出差前不仅要买票,还得准备“晚点怎么办、身份证忘带怎么办、酒店满房怎么办”的备用方案
。
像报销单不是随便写一段话,而是必须按“金额、日期、用途”这些字段填
。
---
---
...
@@ -382,58 +318,39 @@ print(response.usage.total_tokens)
...
@@ -382,58 +318,39 @@ print(response.usage.total_tokens)
### 输入是什么
### 输入是什么
-
没配置 API Key
一个要求固定字段输出的提示词。
-
请求参数错误
-
网络连接失败
### 输出是什么
### 输出是什么
程序不会直接一脸空白地崩掉,而是输出更可理解的错误信息
。
模型按字段要求返回更结构化的结果
。
### 代码演示
### 代码演示
```
python
```
python
import
os
messages
=
[
from
openai
import
OpenAI
,
APIConnectionError
,
AuthenticationError
,
BadRequestError
,
RateLimitError
{
"role"
:
"system"
,
"content"
:
"你是一名信息抽取助手。"
},
{
"role"
:
"user"
,
def
ask_once
(
question
:
str
)
->
None
:
"content"
:
(
api_key
=
os
.
getenv
(
"OPENAI_API_KEY"
)
"请从下面这句话中抽取字段,并严格按 JSON 返回:"
if
not
api_key
:
"{
\"
name
\"
:
\"\"
,
\"
deadline
\"
:
\"\"
,
\"
priority
\"
:
\"\"
}。"
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
(
"网络连接失败:请检查网络或稍后重试。"
)
```
```
#### 正解 vs 错误
#### 正解 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:
...
@@ -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:
...
@@ -457,61 +374,1313 @@ def ask_once(question: str) -> None:
### 输入是什么
### 输入是什么
一段逐轮累积的
`messages`
:
同一个问题,不同的采样参数设置。
```
python
messages
=
[
{
"role"
:
"system"
,
"content"
:
"你是一名耐心的 AI 助教。"
},
{
"role"
:
"user"
,
"content"
:
"什么是训练循环?"
},
]
```
### 输出是什么
### 输出是什么
模型在第二轮、第三轮还能接着前面的上下文继续回答
。
低温度通常更稳,高温度通常更发散
。
### 代码演示
### 代码演示
```
python
```
python
import
os
response
=
client
.
chat
.
completions
.
create
(
from
openai
import
OpenAI
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
(
### 5.1.7 Prompt 迭代优化
model
=
"gpt-4.1-mini"
,
messages
=
messages
,
> 用 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
})
for
chunk
in
stream
:
messages
.
append
({
"role"
:
"user"
,
"content"
:
"那为什么每个 batch 都要 zero_grad?"
})
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
(
Function Calling 是一种让模型根据用户问题选择工具、生成工具参数,并把工具结果重新纳入对话的机制。
model
=
"gpt-4.1-mini"
,
messages
=
messages
,
### 为什么重要
)
print
(
"assistant:"
,
response
.
choices
[
0
]
.
message
.
content
)
很多业务问题不是靠模型自己编就能答好,而是必须接真实数据、数据库、搜索、天气、工单、订单等外部工具。
### 生活类比
像前台接待不会直接修空调,但她能判断“这问题该找维修师傅”,然后把工单信息传给对的人。
---
## 举个例子
### 输入是什么
用户提问:“帮我查一下北京今天的天气。”
### 输出是什么
模型不一定直接编答案,而是先提出一个类似
`get_weather(city="北京")`
的工具调用请求。
### 代码演示
```
python
tools
=
[
{
"type"
:
"function"
,
"function"
:
{
"name"
:
"get_weather"
,
"description"
:
"查询指定城市的天气信息"
,
"parameters"
:
{
"type"
:
"object"
,
"properties"
:
{
"city"
:
{
"type"
:
"string"
,
"description"
:
"城市名称"
},
},
"required"
:
[
"city"
],
},
},
}
]
```
```
#### 正解 vs 错误
#### 正解 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)
...
@@ -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)
...
@@ -535,196 +1704,426 @@ print("assistant:", response.choices[0].message.content)
### 输入是什么
### 输入是什么
一
个不断追加历史消息的聊天程序
。
一
份工具定义
。
### 输出是什么
### 输出是什么
通过裁剪历史记录、选择合适模型、压缩系统提示词,让单次请求 token 更低
。
模型能根据定义产出更符合约束的参数
。
### 代码演示
### 代码演示
```
python
```
python
def
keep_recent_messages
(
messages
:
list
[
dict
],
max_rounds
:
int
=
3
)
->
list
[
dict
]:
tools
=
[
system_message
=
messages
[:
1
]
{
recent_history
=
messages
[
1
:][
-
2
*
max_rounds
:]
"type"
:
"function"
,
return
system_message
+
recent_history
"function"
:
{
"name"
:
"get_weather"
,
"description"
:
"查询指定城市天气,并返回温度与天气描述"
,
"parameters"
:
{
"type"
:
"object"
,
"properties"
:
{
"city"
:
{
"type"
:
"string"
,
"description"
:
"需要查询的城市,例如北京、上海"
,
},
"unit"
:
{
"type"
:
"string"
,
"enum"
:
[
"celsius"
,
"fahrenheit"
],
"description"
:
"温度单位"
,
},
},
"required"
:
[
"city"
],
},
},
}
]
```
```
#### 正解 vs 错误
#### 正解 vs 错误
-
正解:
保留系统消息,再按轮数裁剪最近历史,控制上下文长度
。
-
正解:
把字段名、字段含义、可选值和必填项写清楚
。
-
错误:
无上限地把所有历史消息一直往后堆
。
-
错误:
只有函数名,没有参数描述
。
-
错误表现:
单次请求越来越重,响应变慢,token 和成本越来越难控制
。
-
错误表现:
模型要么不给参数,要么传一堆你程序根本接不住的字段
。
#### 3 条最常用的成本优化建议
---
1.
不要无上限保留全部历史消息,定期裁剪上下文。
### 5.4.3 调用流程
2.
在满足效果的前提下,优先选择更轻量的模型。
3.
系统提示词写清楚即可,不要堆很多重复约束
。
> 用 1-2 句话说清:Function Calling 真正重要的不是一个 `tools` 参数,而是完整调用流程。模型负责提议,程序负责执行,执行结果再回给模型
。
---
---
##
正解 vs 错误
##
什么是这个知识点?
| 场景 | 正解 ✅ | 错误 ❌ | 错误表现 |
### 一句话定义
| --- | --- | --- | --- |
| Key 管理 | 用环境变量保存 API Key | 把 Key 直接硬编码进仓库 | 泄露凭证,存在安全风险 |
| 基础调用 | 明确模型名、messages、结果读取路径 | 只复制一段代码,不知道返回结构 | 一换接口或字段就不会改 |
| 多轮对话 | 把历史消息一并带回 | 每次只发最后一句用户输入 | 模型像“失忆”一样接不上话 |
| 错误处理 | 捕获认证、限流、网络异常 | 默认所有请求都会成功 | 程序在真实环境里容易直接崩掉 |
| 成本控制 | 关注 usage、裁剪上下文 | 上下文无限堆积 | token 飙升,成本不可控 |
**错误示例 1:把 API Key 写死在代码里**
调用流程通常包括:发送请求、模型返回 tool call、程序解析参数并执行函数、把结果回填给模型、模型生成最终回答。
### 为什么重要
如果你只会“让模型返回 tool_calls”,却不会把工具结果再送回模型,那么整个链路只做了一半。
### 生活类比
像客服把问题派给后端系统查数据,查完结果还得回到客服,再由客服整理成用户能理解的话。
---
## 举个例子
### 输入是什么
一个带工具定义的用户问题。
### 输出是什么
模型先给出工具调用,再由程序执行工具,最后模型产出自然语言回答。
### 代码演示
```
python
```
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
```
python
response
=
client
.
chat
.
completions
.
create
(
messages
.
append
({
"role"
:
"user"
,
"content"
:
"那上海呢?顺便和北京做个简单比较。"
})
model
=
"gpt-4.1-mini"
,
messages
=
[
follow_up
=
client
.
chat
.
completions
.
create
(
{
"role"
:
"user"
,
"content"
:
"那为什么它会这样?"
},
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
```
text
1. 准备凭证
用户提问
2. 组织请求体
->
3. 发送请求
模型判断是否要调用工具
4. 读取结果并处理异常
->
返回工具名 + 参数
->
程序执行真实函数/API
->
把结果回给模型
->
模型整理成自然语言回复
```
```
###
为什么 `messages` 能实现上下文
###
# 正解 vs 错误
因为服务端不会神奇地“自动记住你上一轮在说什么”,真正起作用的是你把上下文重新放进了这次请求中。换句话说,
**多轮对话的本质是“上下文重放”**
。
-
正解:把 Function Calling 用在“必须接真实数据”的问题上。
-
错误:什么都交给工具,或者什么都不交给工具。
-
错误表现:要么工具层被滥用,要么模型开始一本正经地编假数据。
### 一个最小心智模型
---
## 原理深入
Function Calling 的完整闭环可以概括成下面这张图:
```
text
```
text
system: 你是谁,要遵守什么规则
用户问题
user: 我现在问了什么
->
assistant: 你上一轮怎么回答的
模型判断:是否需要调用工具?
--------------------------------
->
把这些一起发给模型
若需要:返回工具名 + JSON 参数
--------------------------------
->
模型基于完整上下文继续回答
程序解析参数并执行本地函数 / 外部 API
->
把工具结果作为 tool 消息回填
->
模型基于工具结果生成最终回答
```
```
---
这里最关键的不是“会不会写 schema”,而是明确三层分工:
-
模型层:负责判断要不要调用、调用哪个工具、参数怎么填
-
程序层:负责真正执行函数、连外部服务、做权限和异常控制
-
对话层:负责把工具结果重新带回模型,形成最终面向用户的回答
## 实战代码
## 实战代码
下面这段
示例把环境变量、单轮调用、usage 读取和多轮对话都串起来了。你可以先把它当成完整模板来理解调用流程;如果后续需要真实运行,再补上官方 SDK 和有效的
`OPENAI_API_KEY`
即可
。
下面这段
代码是一个完整的最小 Function Calling 示例,包含函数定义、工具调用、工具执行和最终回复
。
```
python
```
python
import
json
import
os
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
=
[
messages
=
[
{
"role"
:
"system"
,
"content"
:
"你是一名
耐心的 AI 助教
。"
},
{
"role"
:
"system"
,
"content"
:
"你是一名
天气助理
。"
},
{
"role"
:
"user"
,
"content"
:
"
请用两句话解释什么是训练循环
。"
},
{
"role"
:
"user"
,
"content"
:
"
帮我查一下北京今天的天气,并给我一句穿衣建议
。"
},
]
]
try
:
first_response
=
client
.
chat
.
completions
.
create
(
response
=
client
.
chat
.
completions
.
create
(
model
=
"gpt-5.5"
,
model
=
"gpt-4.1-mini"
,
messages
=
messages
,
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
(
final_response
=
client
.
chat
.
completions
.
create
(
model
=
"gpt-4.1-mini"
,
model
=
"gpt-5.5"
,
messages
=
messages
,
messages
=
messages
,
)
tools
=
tools
,
print
(
"assistant:"
,
follow_up
.
choices
[
0
]
.
message
.
content
)
)
except
AuthenticationError
:
print
(
final_response
.
choices
[
0
]
.
message
.
content
)
print
(
"认证失败:请检查 API Key。"
)
except
RateLimitError
:
print
(
"请求过快:请稍后重试。"
)
except
BadRequestError
as
exc
:
print
(
f
"请求参数错误:{exc}"
)
except
APIConnectionError
:
print
(
"网络连接失败:请检查网络连接。"
)
if
__name__
==
"__main__"
:
if
__name__
==
"__main__"
:
main
()
run_weather_assistant
()
```
```
---
## 常见问题
## 常见问题
**Q:为什么一定要用环境变量保存 API Key?**
**Q:Function Calling 是不是模型自己真的执行了 Python 函数?**
A:因为这是最常见、也最安全的基础做法。把 Key 写进代码或提交到仓库,会带来非常现实的泄露风险。
**Q:为什么我第二轮提问时,模型像没看过上一轮内容?**
A:因为你没有把上一轮的
`assistant`
回复和之前的
`user`
消息一起放回
`messages`
。模型不是自动记忆,而是依赖你重传上下文。
**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
```
text
☐ 能正确配置 OPENAI_API_KEY 环境变量
☐ 能解释 Function Calling 的基本概念
☐ 能写出一次最小 Chat Completions 调用
☐ 能写出一个带 JSON Schema 的工具定义
☐ 能解释 messages 中 system / user / assistant 的作用
☐ 能解释从 tool_calls 到最终回答的完整流程
☐ 能通过 response.usage 查看 token 消耗
☐ 能写出一个最小多轮 Function Calling 示例
☐ 能写出带基础错误处理的 API 调用代码
☐ 能给出一个真实可落地的工具调用场景
☐ 能实现最小多轮对话
```
```
## 官方来源
## 官方来源
-
OpenAI API Quickstart:
[
https://developers.openai.com/api/docs/quickstart
](
https://developers.openai.com/api/docs/quickstart
)
-
OpenAI Function Calling Guide:
[
https://developers.openai.com/api/docs/guides/function-calling
](
https://developers.openai.com/api/docs/guides/function-calling
)
-
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
)
-
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
人
到此讨论。请谨慎行事。
请先完成此评论的编辑!
取消
请
注册
或者
登录
后发表评论