【零基础学AI】第 29 章——第一次调用大模型 API

第 29 章 第一次调用大模型 API

文章目录

• [第 29 章 第一次调用大模型 API](#第 29 章 第一次调用大模型 API)
• • [🌈 关于《AI 零基础 36 讲》](#🌈 关于《AI 零基础 36 讲》)
  • 程序把问题送到哪里
  • 先配置密钥，再运行问答
  • 看一眼请求的内容
  • 从响应里取出回答和用量
  • 本次真实调用的结果
  • 没有密钥，也能先验证程序
  • 超时和限流时怎样处理
  • 本章练习

在终端输入"用一句话解释 API"，让 Python 把问题发给模型，再显示回答。这次练习会把前面学过的字符串、字典、函数和错误处理用到同一个小程序里。

本章采用 DeepSeek 的 Chat Completions 接口，已完成一次真实平台请求和本地错误处理验证。

🌈 关于《AI 零基础 36 讲》

🧠 零基础也能开始学 AI

《AI 零基础 36 讲》是一套面向初学者的 AI 入门教程。课程从认识和使用 AI 开始，逐步学习

Python、数据处理、机器学习与深度学习，再进入大模型应用开发，最后完成个人知识库助手的综合实践。

📖 本篇是正式讲解文章

通过具体例子、原创图示和操作结果讲清概念。涉及编程的章节提供可运行代码，方便你边读边试。

🎯 读完以后，动手检验

建议按专栏顺序学习，并完成对应的课后训练，检查自己能否独立运用本章知识。

博客专栏：《AI 零基础 36 讲》

程序把问题送到哪里

API 是服务提供给程序使用的接口。网页聊天框会帮你完成发送和显示，使用 API 时，这些动作需要自己写进程序。

一次请求通常包含目标地址、认证信息和请求内容。服务收到请求后处理它，再返回响应。HTTP 的 POST 方法适合本章这种向服务提交内容的操作。JSON 则用来表达模型名、消息列表等字段，Python 字典可以转换为 JSON 文本。

程序在你的电脑上运行，模型运行在提供方服务中。本章没有在本机训练模型，也不用下载模型权重。运行所需的网络连接和平台账号，和第 27 章的小型本地模型有所不同。

先配置密钥，再运行问答

API Key 用于认证请求。开发平台的余额支持付费调用，密钥用于让服务识别调用者。本章将密钥放在本机环境变量 DEEPSEEK_API_KEY 中，代码通过变量名读取它。

环境变量能避免把密钥写进文章、源代码和结果文件。本机同一用户运行的程序仍可能读取它，环境变量本身不提供加密保护。不要把真实密钥粘贴到聊天、截图或项目文件里。

详细操作见本机配置步骤。在 DeepSeek 开发平台创建 API Key 后，运行本章的 configure-key.ps1，在隐藏输入中粘贴。脚本只将它保存为当前 Windows 用户的环境变量，不写入项目。当前窗口可以立即使用，已经打开的其他程序可能需要重新启动。

代码默认配置使用 https://api.deepseek.com 和 deepseek-flash。模型名按 2026 年 10 月 4 日核对的官方入门文档填写。运行时也可以通过环境变量改变模型名。若以后平台调整模型，需要重新检查文档及账号可用范围。

从本章目录运行下面的命令。

py -3.12 examples/qa.py "用一句话解释 API"

问答程序只用 Python 标准库。requirements.txt 中没有第三方依赖，画图才需要另一个依赖文件。密钥缺失时，程序会显示缺少哪个环境变量，并以退出码 1 结束，不会发送请求。

看一眼请求的内容

客户端把所有配置集中在api_client.py的 Config 中。问答入口只负责读问题、调用函数和显示结果。

下面的代码只构建请求内容，不会连接服务。占位符不能用于真实平台认证。

from api_client import Config

config = Config(api_key="local-teaching-placeholder")
body = config.payload("用一句话解释 API")
print(body["model"])
print(body["messages"][1])
print(body["stream"], body["max_tokens"])

结果如下。

deepseek-flash
{'role': 'user', 'content': '用一句话解释 API'}
False 256

messages 是消息列表。第一条 system 消息约定"简短、具体地回答"，第二条 user 消息放入读者的问题。这个版本每次只发送一条用户问题，没有保存多轮历史。

stream=False 表示等待本次响应后再读取结果。max_tokens=256 限制本次生成的输出 Token 上限，它不代表总用量一定是 256，也不限制输入 Token 数。服务仍会检查自己的参数和上下文限制。

DeepSeek 的非思考模式设置放在配置类里。本文没有向读者提供一套所有厂商都通用的字段承诺。换服务时，要一起检查接口路径、认证方式、参数和响应格式。仅修改网址可能不够。

客户端将字典转换为 UTF-8 JSON，把认证信息放在 Authorization 请求头中，再发送到 /chat/completions。

从响应里取出回答和用量

收到 JSON 后，程序先转换为 Python 对象。回答位于第一项候选的 message 内容中，用量位于 usage 中。读取多层字典和列表时，每一步都要知道自己取的是哪一层。

用本章的固定教学响应演示一次。

from api_client import parse_response
from local_fixture import FIXTURE_RESPONSE

result = parse_response(FIXTURE_RESPONSE)
print(result["answer"])
print(result["usage"])
print(result["finish_reason"], result["complete"])

实际运行结果如下。

API 让你的程序向另一套服务发送请求，并取得响应。
{'prompt_tokens': 30, 'completion_tokens': 18, 'total_tokens': 48}
stop True

三个计数分别表示输入、输出和总 Token 数。这里的输入 30、输出 18 是人为编制的固定数字，合计为 48。真实调用必须读取服务返回的计数，不能拿中文字数代替。

客户端还检查 finish_reason。stop 表示正常停止，length 表示达到输出或上下文上限，文本可能被截断。即使 HTTP 请求成功，也要继续判断回答是否完整。用量信息也不能直接换成金额，金额还取决于提供方当时的计费规则。

问答入口会保存提问、回答、请求和返回模型名、用量、结束原因以及耗时。它不保存认证头和密钥。记录文件使用独立名称，已有文件拒绝覆盖，便于以后比较两次真实请求。

本次真实调用的结果

2026 年 10 月 4 日，使用本机环境变量中的密钥向 DeepSeek 发送"用一句话解释 API"。请求及返回模型名均为 deepseek-flash，回答如下。

API 是软件之间约定好的接口，让一个程序能向另一个程序请求数据或功能，而不用了解对方内部怎么实现。

服务返回输入21、输出29、合计50个 Token，结束原因为 stop。客户端记录耗时约1.27秒，包含本次网络等待与读取，不代表模型平均延迟。见真实请求记录。

这次调用验证了本机认证、请求与响应处理。

没有密钥，也能先验证程序

本章提供一个仅绑定本机回环地址的教学 HTTP 服务。它返回作者编制的固定 JSON，不运行语言模型，也不接收真实密钥。

py -3.12 examples/run_fixture.py

这条命令会启动本地服务、实际运行问答入口、检查请求路径和中文消息，随后关闭服务。结果保存在本地教学记录，文件中的 kind 明确为 local_fixture。命令行显示"本地教学响应"。

超时和限流时怎样处理

密钥错误、余额不足和参数错误需要不同处理。比如 HTTP 401 对应认证失败，402 对应余额不足，422 对应无效参数。平台错误的分类核对DeepSeek 官方错误码。

对 429 限流，本章提示稍后手动重试，并结束当前调用。反复立刻重试会继续增加请求。本地教学服务可以稳定返回 429，练习时无需故意向真实平台发送大量请求。

下面的示例确实经过本地 HTTP 传输。

from api_client import APIError, Config, ask
from local_fixture import FIXTURE_KEY, fixture_server

with fixture_server(status=429) as (base, received):
    try:
        ask(Config(base_url=base, api_key=FIXTURE_KEY,
                   fixture_http=True), "解释 API")
    except APIError as error:
        print(error)
        print("本地收到的请求数", len(received))

结果如下。

HTTP 429，请求过快，请稍后手动重试
本地收到的请求数 1

超时表示客户端没有在设定时间内完成等待或读取。Python 的 socket 超时不等于覆盖全部步骤的严格总时长；服务是否已经生成内容也可能未知。因此程序不会自动补发一次付费请求。

请求格式或参数有问题时，先改代码或配置。网络连接失败时，检查网络和证书。

本章练习

先运行本地教学入口，再完成【零基础学AI】第 29 章课后练习与答案。准备好本机密钥后，用一个不含私人信息的短问题调用真实服务，确认回答、结束原因和用量均已记录。下一章会在这个入口上增加多轮历史和可检查的结构化结果。