网硕互联帮助中心📚 系列定位：从 Scratch 积木到 Python 代码，双向对照学 AI 编程 ✍️ 作者：梅雅达编程工作室 🎯 本篇难度：⭐⭐⭐⭐⭐（实战高阶）
一、摘要
Scratch 转 Python 系列第 19 天——今天是让你的 Python 真的会说话的一天！过去 18 天我们写的 AI Agent 回复都是"预设话术"，本篇终于要接真实大模型 API：用 requests 库发送 HTTP 请求、组装 JSON Body、带上鉴权 Key、处理响应，让你的 Agent 从"背台词"进化到"真的会思考"。本篇同时讲清楚 API 调用四大关键点——鉴权 / 超时 / 重试 / 错误处理，并给出可直接跑起来的大模型对接 Demo（含 DeepSeek、通义千问、扣子三条备选路径），一次学会通用套路。
二、本节课学习目标
三、专业名词通俗释义
| API | Application Programming Interface，程序对外提供服务的接口 | 别人家的舞台开放了几个"广播消息"通道让你用 |
| HTTP 请求 | 你的程序去网上请别人做事的"标准信封" | 精灵广播消息给远方的舞台，等回应 |
| GET / POST | 常见两种请求方式：GET 拿数据，POST 提交数据 | 广播查询 vs 广播提交表单 |
| Headers（请求头） | 信封上的附加信息，比如"我是谁"“要什么格式” | 广播消息附带的自定义变量 |
| Body（请求体） | 信封里装的具体内容，一般是 JSON | 广播消息带的完整内容包 |
| API Key | 你的专属通行证，证明"我是付费用户可以调" | 舞台入场券，没它不让进 |
| 响应（Response） | 服务器给你的"回信"，一般也是 JSON | 远方舞台广播回来的消息包 |
| 状态码 | 回信开头的"办得成没"标记：200 成功、401 没权限、429 太频繁… | 广播回执上的成功/失败标记 |
四、分模块双向对照知识点
模块 1：requests 基础请求
Scratch 积木逻辑：
Scratch 里"广播消息"是把消息送给舞台上其他精灵；requests 是把消息送到互联网上另一台电脑。核心动作都是"发消息 → 等回复"。 
Python 源码（含 Scratch 积木注释）：
import requests
# 【Scratch积木】广播消息 (GET 请求) 到 (百度)
response = requests.get("https://www.baidu.com")
# 【Scratch积木】读取回执的 (状态码)
print("状态码:", response.status_code)
# 【Scratch积木】读取回执的 (文本内容)
print("前 100 字:", response.text[:100])
运行结果：
状态码: 200
前 100 字: <!DOCTYPE html><!–STATUS OK–><html> <head><meta http-equiv="content-type"…
核心易错说明：
- requests 是第三方库，需要 pip install requests 才能用
- response.text 是字符串，response.json() 才能自动解析 JSON
模块 2：POST + JSON Body + Headers
Scratch 积木逻辑：
Scratch 广播消息可以带一个变量。真实 API 一般要求你把"要问的问题"包装成 JSON 送过去，同时头部要带 API Key 证明身份。 
Python 源码（含 Scratch 积木注释）：
import requests
url = "https://api.example.com/chat"
# 【Scratch积木】新建字典「请求头」→ 装 API Key
headers = {
"Authorization": "Bearer sk-你的APIKey",
"Content-Type": "application/json",
}
# 【Scratch积木】新建字典「请求体」→ 装问题
payload = {
"model": "gpt-3.5-turbo",
"messages": [{"role": "user", "content": "你好呀"}],
}
# 【Scratch积木】广播 POST 请求 (带头 + 带体)
response = requests.post(url, headers=headers, json=payload, timeout=30)
# 【Scratch积木】读取回执的 JSON 结果
data = response.json()
print(data)
运行结果（示例）：
{'id': 'chat-xxx', 'choices': [{'message': {'role': 'assistant', 'content': '你好呀！很高兴见到你～'}}]}
核心易错说明：
- json=payload 参数会自动把字典序列化成 JSON 字符串并加 Content-Type: application/json，别写成 data=payload（那样发的是表单）
- timeout=30 是必须加的！否则接口卡住会让整个程序一直挂着
模块 3：超时与重试
Scratch 积木逻辑：
Scratch 广播如果收不到回复不会自动重发。真实 API 网络抖一下就可能失败，我们要写"最多重试 3 次"的健壮逻辑。 
Python 源码（含 Scratch 积木注释）：
import requests
import time
def call_api_with_retry(url, headers, payload, max_retries=3):
# 【Scratch积木】重复 (max_retries) 次
for attempt in range(1, max_retries + 1):
try:
# 【Scratch积木】发请求
r = requests.post(url, headers=headers, json=payload, timeout=30)
# 【Scratch积木】如果 状态码 = 200 那么返回
if r.status_code == 200:
return r.json()
else:
print(f"第 {attempt} 次失败：状态码 {r.status_code}")
except requests.exceptions.RequestException as e:
# 【Scratch积木】捕获异常，打印后重试
print(f"第 {attempt} 次异常：{e}")
# 【Scratch积木】等待 (2 的 attempt 次方) 秒（指数退避）
time.sleep(2 ** attempt)
return None # 全部重试失败
运行结果（示例）：
第 1 次异常：Connection timed out
第 2 次异常：Connection timed out
{'choices': […]}
核心易错说明：
- 指数退避（2, 4, 8 秒）比"每次都等 1 秒"更友好，能给服务器喘息时间
- 别搞"死循环重试"，一定要有 max_retries 上限
模块 4：响应解析与错误码判断
Scratch 积木逻辑：
API 回执像信封，里面有可能是成功内容，也可能是错误说明。我们要按状态码分不同处理。 
Python 源码（含 Scratch 积木注释）：
r = requests.post(url, headers=headers, json=payload, timeout=30)
# 【Scratch积木】根据 状态码 判断
if r.status_code == 200:
# 【Scratch积木】成功 → 取 JSON 内容
print("回复：", r.json()["choices"][0]["message"]["content"])
elif r.status_code == 401:
print("❌ API Key 无效，请检查")
elif r.status_code == 429:
print("⚠️ 请求太频繁，稍后再试")
elif r.status_code >= 500:
print("⚠️ 服务器出错，稍后重试")
else:
print(f"其他错误：{r.status_code} – {r.text}")
运行结果（示例）：
回复： 你好呀！很高兴见到你～
核心易错说明：
- r.json() 如果响应不是合法 JSON 会抛异常，最好套 try/except
- 大模型 API 返回结构各家不同（OpenAI 是 choices[0].message.content，其他家可能是 output.text），务必看文档
五、综合实战项目：真实大模型 API 对接 Demo
给 Day 17 的 CLI 聊天机器人换一个"真正的大脑"——把 Agent 的 chat() 从"预设话术"换成"调大模型 API"。
Scratch 积木思路
Python 完整可运行代码（片段）
class LLMAgent(AIRole):
"""接入真实大模型 API 的 Agent"""
API_URL = "https://api.deepseek.com/v1/chat/completions" # 可换成通义 / 扣子
MODEL = "deepseek-chat"
def __init__(self, name, role, style, api_key):
super().__init__(name, style)
self.role_name = role
self.api_key = api_key
self.system_prompt = f"你是一个{style}的{role}，名字叫{name}。请用符合人设的方式回答。"
def chat(self, user_input):
headers = {
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json",
}
payload = {
"model": self.MODEL,
"messages": [
{"role": "system", "content": self.system_prompt},
{"role": "user", "content": user_input},
],
}
try:
r = requests.post(self.API_URL, headers=headers, json=payload, timeout=30)
reply = r.json()["choices"][0]["message"]["content"]
except Exception as e:
reply = f"[API 调用失败，回退预设]收到：{user_input}"
self.history.append({"user": user_input, "bot": reply})
print(f"【{self.role_name}·{self.name}】{reply}")
return reply
# 完整代码含 GET/POST 演示、重试封装、多 API 提供商切换
# 见配套源码文件 day19_code.py
运行结果预览：
===== 真实大模型 Agent Demo =====
你 > 请用一句诗形容今天的心情
【AI助手·小凌】清风入怀星未落，代码为伴亦悠然～
你 > /exit
再见👋
💡 提示：Demo 里 api_key 请换成你自己的（DeepSeek、通义千问、扣子都有免费试用额度）。文件里也提供了"离线 mock 模式"，没 Key 也能跑，方便同学们先看流程。
六、高频易错点总结
八、💡 学习提示
为鼓励大家动手练习、吃透编程逻辑，本篇不提供 Scratch 成品源码，请对照截图亲手搭建积木完成复刻！ 配套 Python 代码可直接复制运行学习。
九、往期历史笔记
编程启蒙｜Scratch 转 Python 系列第 1 天：变量、数字运算积木双向对照（AI 基础数值计算实战）
编程启蒙｜Scratch 转 Python 系列第 2 天：分支判断 if 积木双向对照（AI 指令条件过滤实战）
编程启蒙｜Scratch 转 Python 系列第 3 天：循环重复积木双向对照（AI 批量循环处理，已收录 AI Agent 技术社区）
编程启蒙｜Scratch 转 Python 系列第 4 天：字符串文本积木双向对照（AI 提示词拼接、文本清洗实战）
编程启蒙｜Scratch 转 Python 系列第 5 天：自定义积木 / 函数双向对照（AI 工具封装、重复指令简化实战）
编程启蒙｜Scratch 转 Python 系列第 6 天：列表、数组积木双向对照（AI 底层语法 / AI 批量数据处理实战）
编程启蒙｜Scratch 转 Python 系列第 7 天：猜数字大挑战·升级版实战（AI 出题 + 二分查找最优解 + 完整命令行游戏 已被收录在智能体开发者社区）
编程启蒙｜Scratch 转 Python 系列第8天：节奏敲击机游戏实战（AI节奏谱生成实战）
编程启蒙｜Scratch 转 Python 系列第9天：字典/哈希表积木双向对照（AI大模型参数配置表实战）
编程启蒙｜Scratch 转 Python 系列第 10 天：问答闯关游戏实战（AI 题库管理 + 多关卡剧本）
编程启蒙｜Scratch 转 Python 系列第 11 天：文件读写积木双向对照（AI 训练数据存取实战）
编程启蒙｜Scratch 转 Python 系列第 12 天：记忆翻牌游戏实战（AI 图案主题包 + 存档排行榜 已被收录在2048 AI社区）
编程启蒙｜Scratch 转 Python 系列第 13 天：异常处理 try/except 积木双向对照（AI 接口调用容错实战）
编程启蒙｜Scratch 转 Python 系列第 14 天：AI 提示词管理工具实战（增删改查 + 存档导入 + 异常兜底）
编程启蒙｜Scratch 转 Python 系列第 15 天：类与对象积木双向对照（AI 角色类封装实战）已被智能体开发者社区收录
编程启蒙｜Scratch 转 Python 系列第 16 天：继承与多态积木双向对照（AI Agent 角色体系实战）已被智能体开发者社区收录
编程启蒙｜Scratch 转 Python 系列第 17 天：AI 聊天机器人游戏实战（AI 多角色对话 + 人设切换实战）已被DAMO开发者矩阵收录
编程启蒙｜Scratch 转 Python 系列第 18 天：模块导入与常用标准库积木双向对照（AI 工具箱模块化实战）
编程启蒙｜番外篇：AI自己学会了攻击电脑——我们为什么更要让孩子从小理解编程
十、下一章预告
第 20 天：综合大项目 AI Agent 助手（全系列知识串联收官）
本系列收官大项目来了！我们将把 20 天所有知识串起来，做一个真正可用的 AI Agent 助手：
- 多角色人设 + 动态切换（Day 15-17）
- 真实大模型 API 对接（Day 19）
- 多轮上下文记忆 + JSON 存档（Day 6/9/11/18）
- 完整异常兜底 + CLI 交互（Day 13）
- 模块化工程结构（Day 18）
- AI 场景：亲手做一个属于自己的 AI 助手，可以每天用！
系列大结局，一起冲！🚀
十一、原创声明
本文为「梅雅达编程笔记」原创技术教程，未经授权禁止转载、洗稿或用于商业培训。转载合作请联系工作室。系列内容持续更新中，欢迎收藏 CSDN 专栏「编程启蒙–scratch转python」追更 🍃
评论前必须登录！
注册