AI API 开发入门教程:用 Python 调用 ChatGPT、DeepSeek 和 Claude
AI API 开发入门教程:用 Python 调用 ChatGPT、DeepSeek 和 Claude 平时使用 ChatGPT、DeepSeek 或 Claude,我们只需要打开网页,输入问题,就能得到 AI 的回答。 但如果我们想在自己的网站中加入 AI 客服,或者让程序自动生成文章、整理数据、分析用户反馈,总不能每次都打开聊天网页,再手动复制粘贴吧?
AI API 开发入门教程:用 Python 调用 ChatGPT、DeepSeek 和 Claude
平时使用 ChatGPT、DeepSeek 或 Claude,我们只需要打开网页,输入问题,就能得到 AI 的回答。
但如果我们想在自己的网站中加入 AI 客服,或者让程序自动生成文章、整理数据、分析用户反馈,总不能每次都打开聊天网页,再手动复制粘贴吧?
这时候就需要用到
AI API
。
API 可以让我们的程序直接调用大模型,把 AI 能力接入网站、应用和自动化流程。
例如,我们可以通过 API 实现:
电商网站自动生成商品描述。
编程教程网站自动解释代码。
笔记应用自动总结文章。
客服系统自动整理用户咨询。
工作系统自动汇总日志和生成报告。
本章节我们使用 Python,从零开始调用 AI API,并逐步实现多轮对话、流式输出、Token 用量统计和异常处理。
最后,我们将把这些功能组合起来,制作一个能够在终端中运行的
RUNOOB AI 聊天工具
。
整个过程以实际操作为主,不需要提前了解复杂的 AI 模型原理。只要具备一点 Python 基础,就可以跟着完成。
什么是 AI API
API 的全称是 Application Programming Interface,中文叫
应用程序编程接口
。
它可以理解为两个软件之间约定好的通信方式。
例如,我们使用天气应用查看天气,应用程序会向天气服务发送请求,再把返回的数据展示到页面上。
AI API 也是类似的过程。
我们的程序发送一段文字给 AI 服务,AI 模型处理后,再把生成的内容返回给程序。
AI API 的基本工作流程
我们的程序 → 发送 API 请求 → AI 模型处理 → 返回响应 → 程序展示结果。
例如,我们发送:
实例:发送给 AI 的问题
请用一句话介绍 Python。
AI 服务可能返回:
示例响应
Python 是一种语法简洁、应用广泛的高级编程语言。
我们可以把这个结果显示在网页上,也可以继续交给程序处理。
API 和普通网页聊天有什么区别
需要注意,
ChatGPT 等聊天产品的订阅与开发者 API 计费通常是独立的
。订阅了聊天产品,并不意味着自动获得相同额度的 API 调用权限。
了解 HTTP 请求与 JSON
调用 AI API 之前,我们先认识两个基础概念:HTTP 和 JSON。
HTTP 请求
HTTP 是客户端和服务器之间常用的通信协议。
我们访问网站、提交表单、调用接口,都经常使用 HTTP。
常见的请求方法有:
大多数文本生成请求会使用 POST 方法,因为我们需要将问题和相关参数发送给服务器。
JSON 数据格式
JSON 是 API 通信中经常使用的数据格式。
它通过键值对组织数据,能够表达字符串、数字、数组和对象等内容。
例如,下面是一个简化的聊天请求结构:
实例:AI 请求中的 JSON
{
"model": "deepseek-flash",
"messages": [
{
"role": "user",
"content": "请介绍一下 RUNOOB 菜鸟教程"
}
]
}
这里包含两个主要字段:
model
:指定我们希望使用的模型。
messages
:提供对话内容。
其中
role
表示消息角色,
content
表示消息内容。
常见消息角色
不同厂商的接口结构并不完全一样。我们先理解这些基本概念,后面直接使用官方 SDK 操作即可。
准备 Python 开发环境
本章节使用 Python 编写示例。
Python 语法相对简单,拥有丰富的 HTTP 和 AI 开发库,很适合用来学习 API 调用。
安装 Python
首先打开 Python 官方下载页面:
https://www.python.org/downloads/
下载安装适合自己系统的版本。
建议使用 Python 3.10 或更高版本,以便满足本章节所使用的 SDK 要求。
安装完成后,打开终端检查版本。
实例:检查 Python 版本
python
--version
如果使用 macOS 或 Linux,也可以尝试:
实例:检查 Python 3
python3
--version
只要能够看到已安装的 Python 版本,就可以继续。
创建项目目录
我们为本章节创建一个独立的项目文件夹。
实例:创建项目
mkdir
runoob-ai-api
cd
runoob-ai-api
创建虚拟环境
Python 虚拟环境可以把当前项目使用的第三方库与其他项目隔离开。
实例:创建虚拟环境
python
-m
venv .venv
macOS 或 Linux 激活虚拟环境:
实例:激活虚拟环境
source
.venv
/
bin
/
activate
Windows PowerShell 使用:
实例:Windows 激活虚拟环境
.venv\Scripts\Activate.ps1
如果使用 Windows CMD,可以运行
.venv\Scripts\activate.bat
。
如果 PowerShell 提示执行策略限制,应检查当前环境的脚本权限,不要直接通过关闭安全机制来解决。
安装 AI SDK
接下来安装 OpenAI 和 Anthropic 的 Python SDK。
实例:安装 SDK
python
-m
pip
install
--upgrade
pip
python
-m
pip
install
openai anthropic
本章节主要使用这两个 SDK:
代码编辑器可以使用 VS Code、Cursor、PyCharm,或者自己习惯的其他编辑器。
API Key 是什么,如何安全使用
调用 AI API 一般需要 API Key。
API Key 可以理解为应用访问 AI 服务的凭证。平台通过它识别请求属于哪个账号或项目,并记录用量。
我们通常可以在各家模型平台的开发者控制台创建 API Key。
不同服务可能有独立的充值、预算和使用限制,创建 Key 前应查看当前计费规则。
不要把 API Key 直接写进代码
例如,下面这种写法不适合真实项目:
不推荐的写法
api_key
=
"sk-这里直接填写真实密钥"
如果不小心把这个文件提交到 GitHub,API Key 就可能泄露。
我们可以将它保存在环境变量中,由 Python 在运行时读取。
macOS 和 Linux 设置环境变量
实例:配置环境变量
export
OPENAI_API_KEY
=
"这里填写你的 OpenAI API Key"
export
DEEPSEEK_API_KEY
=
"这里填写你的 DeepSeek API Key"
export
ANTHROPIC_API_KEY
=
"这里填写你的 Anthropic API Key"
这些命令用于设置当前终端会话的环境变量。示例中的值需要替换为自己的凭证,不要将包含真实密钥的命令保存到公开脚本或共享终端历史中。
Windows PowerShell 设置环境变量
实例:PowerShell 设置 API Key
$env
:OPENAI_API_KEY
=
"这里填写你的 OpenAI API Key"
$env
:DEEPSEEK_API_KEY
=
"这里填写你的 DeepSeek API Key"
$env
:ANTHROPIC_API_KEY
=
"这里填写你的 Anthropic API Key"
正式项目可以使用安全的环境配置或密钥管理服务。为了避免在终端历史中留下凭证,也可以采用受保护的交互式密钥输入方式。
不要把 API Key 放进网页前端 JavaScript、小程序客户端、公开代码仓库或聊天记录中。
如果我们准备开发对外提供服务的网站,应由自己的服务器安全地持有 Key,再通过后端请求 AI 服务。
OpenAI API 入门
我们先通过 OpenAI 官方 SDK 完成第一个 API 调用。
目前 OpenAI 为新项目提供了 Responses API,可以用于文本生成、多模态输入和工具调用等任务。
本章节先学习最简单的文字输入和输出。
第一个 API 调用
在项目中创建
openai_first.py
文件,输入以下代码。
实例:使用 OpenAI Responses API
from
openai
import
OpenAI
自动读取 OPENAI_API_KEY 环境变量
client
=
OpenAI
(
)
response
=
client.
responses
.
create
(
model
=
"gpt-6-astra"
,
input
=
"请用一句话介绍 RUNOOB 菜鸟教程。"
)
(
"AI 回复:"
)
(
response.
output_text
)
这个例子使用官方文档中的
gpt-6-astra
模型标识。实际运行时需要账号具有相应模型访问权限;如果模型不可用,应在模型列表中选择自己已开通的模型。
运行:
实例:运行 Python 文件
python openai_first.py
如果 API Key、网络和模型权限正常,就能够获得 AI 的文字回复。
代码是怎样工作的
到这里,我们已经完成了最基本的 AI API 调用。
需要注意,模型每次生成的具体句子可能不同,不能把某一次示例输出当成固定结果。
使用 DeepSeek API
如果我们希望使用国内模型服务,也可以通过 DeepSeek API 完成类似的任务。
DeepSeek 提供与 OpenAI Chat Completions 兼容的接口,因此可以继续使用已经安装的
openai
Python SDK。
需要修改的主要是:
API Key。
API 服务地址。
模型名称。
DeepSeek 模型选择
根据当前 DeepSeek 官方模型文档,可使用的主要标识包括:
模型版本及定价会更新,我们应该以
DeepSeek 官方模型与计费页面
为准。
第一个 DeepSeek API 调用
创建
deepseek_first.py
文件。
实例:使用 OpenAI SDK 调用 DeepSeek
import
os
from
openai
import
OpenAI
client
=
OpenAI
(
api_key
=
os
.
environ
[
"DEEPSEEK_API_KEY"
]
,
base_url
=
"https://api.deepseek.com"
)
response
=
client.
chat
.
completions
.
create
(
model
=
"deepseek-flash"
,
messages
=
[
{
"role"
:
"user"
,
"content"
:
"请用一句话介绍 RUNOOB 菜鸟教程。"
}
]
,
thinking
=
{
"type"
:
"disabled"
}
)
(
"AI 回复:"
)
(
response.
choices
[
0
]
.
message
.
content
)
if
response.
usage
:
(
"输入 Token:"
,
response.
usage
.
prompt_tokens
)
(
"输出 Token:"
,
response.
usage
.
completion_tokens
)
(
"总 Token:"
,
response.
usage
.
total_tokens
)
这里使用
thinking
参数关闭思考模式,是为了让我们的第一个演示更容易理解。
DeepSeek 当前部分模型默认启用思考模式。如果需要处理复杂任务,也可以按照官方文档启用对应的推理功能。
运行:
实例:运行 DeepSeek 示例
python deepseek_first.py
这个示例展示了一个很实用的技巧:
对于提供兼容接口的模型服务,我们通常不需要重新学习一整套 SDK。
不过,"兼容 OpenAI 格式"并不代表所有参数和功能都完全一样。尤其是思考模式、工具调用、结构化输出和多模态功能,应以对应厂商的文档为准。
使用 Claude API
接下来我们看看 Anthropic 的 Claude API。
Claude 使用 Messages API,官方提供独立的 Python SDK。
虽然它与 OpenAI API 的基本思路类似,但请求参数和返回结构有一些区别。
调用 Claude Messages API
创建
claude_first.py
文件。
实例:第一个 Claude API 调用
from
anthropic
import
Anthropic
自动读取 ANTHROPIC_API_KEY
client
=
Anthropic
(
)
response
=
client.
messages
.
create
(
model
=
"claude-sonnet-5-5"
,
max_tokens
=
512
,
messages
=
[
{
"role"
:
"user"
,
"content"
:
"请用三句话介绍 Python。"
}
]
)
for
block
in
response.
content
:
if
block.
type
==
"text"
:
(
block.
text
)
这里使用 Claude 官方文档中的模型标识。不同账号可能具有不同的模型访问权限,运行时应以控制台中实际可用的模型为准。
Claude 如何设置 System Prompt
在 Claude Messages API 中,系统提示词使用独立的
system
参数,而不是放进普通的
messages
数组。
实例:Claude System Prompt
from
anthropic
import
Anthropic
client
=
Anthropic
(
)
response
=
client.
messages
.
create
(
model
=
"claude-sonnet-5-5"
,
max_tokens
=
512
,
system
=
(
"你是一个 Python 入门教学助手。"
"使用自然、简洁的中文回答。"
"尽量通过简单示例解释概念。"
)
,
messages
=
[
{
"role"
:
"user"
,
"content"
:
"Python 函数是什么?"
}
]
)
for
block
in
response.
content
:
if
block.
type
==
"text"
:
(
block.
text
)
三种 API 的主要区别
DeepSeek 也提供 Anthropic 兼容接口
如果我们使用的是 Anthropic SDK,而服务端支持相应的兼容接口,也可以通过修改访问地址、凭证和模型进行调用。
例如,DeepSeek 官方当前提供 Anthropic 兼容接口:
实例:通过 Anthropic SDK 调用 DeepSeek
import
os
from
anthropic
import
Anthropic
client
=
Anthropic
(
api_key
=
os
.
environ
[
"DEEPSEEK_API_KEY"
]
,
base_url
=
"https://api.deepseek.com/anthropic"
)
response
=
client.
messages
.
create
(
model
=
"deepseek-flash"
,
max_tokens
=
512
,
messages
=
[
{
"role"
:
"user"
,
"content"
:
"请用一句话介绍 Python。"
}
]
)
for
block
in
response.
content
:
if
block.
type
==
"text"
:
(
block.
text
)
这里我们读取的是返回消息中的文本块,而不是将推理内容直接当作最终回答。
接口兼容性可能随模型和 SDK 更新而变化。如果某项参数不能使用,应查看 DeepSeek 对应的兼容接口说明。
AI API 的常见请求参数
完成基本调用后,我们再了解一些常见参数。
不同 API 的参数名称和支持范围可能不同,下面以概念说明为主。
temperature 应该怎么使用
有些模型支持通过 temperature 调整输出随机性。
一般来说,较低的温度会让输出更集中,较高的温度可能增加表达变化。
但这不代表 temperature 设置为 0 就一定得到完全相同的结果,也不能靠降低温度保证事实正确。
另外,一些推理模型会忽略或者限制 temperature 参数。
因此,我们应该先确认所选模型是否支持,再根据实际效果进行调整。
控制输出长度
如果只是让 AI 生成一句商品介绍,就没有必要设置很大的输出上限。
但如果要生成完整文章或复杂代码,输出上限太小又可能导致内容被截断。
这里还需要注意,
Token 不等于中文字数
。不同模型的分词方式不同,不能简单地用固定比例换算。
多轮对话:让程序记住之前聊了什么
前面的例子都是单轮对话。
但真实的聊天应用通常需要支持连续交流。
例如,我们先问:
第一轮
什么是 Python?
然后继续问:
第二轮
它适合开发哪些项目?
第二轮中的"它"指的是 Python。
如果我们的程序没有保存上一轮的对话,模型就可能无法确定"它"指什么。
多轮对话是如何实现的
一种常见做法是:
在应用中保存对话历史,并在下一次请求中提供需要保留的上下文。
下面我们使用 DeepSeek 演示。
实例:多轮对话
import
os
from
openai
import
OpenAI
client
=
OpenAI
(
api_key
=
os
.
environ
[
"DEEPSEEK_API_KEY"
]
,
base_url
=
"https://api.deepseek.com"
)
messages
=
[
{
"role"
:
"system"
,
"content"
:
"你是一个 Python 入门教学助手。"
}
]
def
chat
(
question
)
:
messages.
append
(
{
"role"
:
"user"
,
"content"
: question
}
)
response
=
client.
chat
.
completions
.
create
(
model
=
"deepseek-flash"
,
messages
=
messages
,
thinking
=
{
"type"
:
"disabled"
}
)
answer
=
response.
choices
[
0
]
.
message
.
content
or
""
messages.
append
(
{
"role"
:
"assistant"
,
"content"
: answer
}
)
return
answer
(
"第一轮:"
)
(
chat
(
"什么是 Python?"
)
)
(
"
\n
第二轮:"
)
(
chat
(
"它适合开发哪些项目?"
)
)
我们使用
messages
列表保存了历史消息。
每次发送请求时,都把当前需要的上下文交给模型。
模型回复后,再把这条回复添加进历史列表。
这样,第二轮就能够参考第一轮的内容。
多轮对话需要注意什么
对话历史并不是越长越好。
如果把几百轮对话全部发送给模型,会增加输入 Token 用量,还可能超出上下文窗口。
我们可以根据项目需要保留最近几轮对话,或者把较早的内容整理成摘要。
需要特别注意,如果对话中包含工具调用,还要正确保留相关的工具调用与返回消息,不能随意删掉其中一半。
本章节的命令行工具暂时只处理普通文字对话,因此可以采用更简单的历史记录方案。
流式输出:实现 AI 打字机效果
在聊天网页中,我们经常会看到 AI 的回答逐渐出现在屏幕上。
这就是流式输出(Streaming)。
普通请求通常在响应完成后再返回结果,而流式输出允许我们在内容生成过程中接收多个数据片段。
这种方式很适合聊天界面,因为我们可以更早看到返回内容。
普通响应与流式响应
DeepSeek 流式输出实例
创建
streaming_demo.py
。
实例:流式输出 AI 回复
import
os
from
openai
import
OpenAI
client
=
OpenAI
(
api_key
=
os
.
environ
[
"DEEPSEEK_API_KEY"
]
,
base_url
=
"https://api.deepseek.com"
)
stream
=
client.
chat
.
completions
.
create
(
model
=
"deepseek-flash"
,
messages
=
[
{
"role"
:
"user"
,
"content"
:
"请介绍一下 Python 的主要特点。"
}
]
,
thinking
=
{
"type"
:
"disabled"
}
,
stream
=
True
)
(
"AI:"
,
end
=
""
,
flush
=
True
)
parts
=
[
]
for
chunk
in
stream:
if
not
chunk
.
choices
:
continue
content
=
chunk
.
choices
[
0
]
.
delta
.
content
if
content:
(
content
,
end
=
""
,
flush
=
True
)
parts.
append
(
content
)
(
"
\n
"
)
full_answer
=
""
.
join
(
parts
)
(
"本次回复字符数:"
,
len
(
full_answer
)
)
这里的关键参数是
stream=True
。
程序收到一段文本,就立即打印出来,而不必等整个响应结束。
需要注意,流式输出返回的是数据片段,不保证每个片段刚好是一个汉字或一个完整单词。
OpenAI Responses API 流式输出
OpenAI 的 Responses API 也支持流式响应。
实例:OpenAI 流式响应
from
openai
import
OpenAI
client
=
OpenAI
(
)
stream
=
client.
responses
.
create
(
model
=
"gpt-6-astra"
,
input
=
"请介绍一下 Python 的主要用途。"
,
stream
=
True
)
for
event
in
stream:
if
event.
type
==
"response.output_text.delta"
:
(
event.
delta
,
end
=
""
,
flush
=
True
)
(
)
这里我们只处理文字增量事件。
如果开发正式应用,还应该处理响应完成、错误及其他事件类型。
Token 是什么,AI API 如何计算费用
AI API 的费用通常与模型、输入量、输出量以及具体功能有关。
对于普通文本模型,最常见的计量单位是
Token
。
Token 可以理解为模型处理文本的基本单位。
它可能是一个完整单词、单词的一部分、一个汉字或某个标点符号。
不同模型使用的分词方式不完全相同,因此不能把 Token 简单理解成字符数。
输入 Token 和输出 Token
不同服务可能将部分推理 Token 计入输出 Token,具体以厂商的计费和用量字段说明为准。
API 费用计算方法
如果模型分别对输入和输出 Token 收费,我们可以使用下面的公式估算:
总费用 = 输入 Token 数 / 1,000,000 × 输入单价
+ 输出 Token 数 / 1,000,000 × 输出单价
例如,假设某个模型采用以下
虚构的演示价格
:
则本次费用为:
实例:费用计算
输入费用:
2000 / 1000000 × 1 = 0.002 元
输出费用:
500 / 1000000 × 4 = 0.002 元
合计:
0.004 元
这只是演示计算方式,并不是任何厂商的实际报价。
真实计费还需要考虑缓存、模型版本、特殊功能及套餐规则。
用 Python 统计真实 Token 用量
我们可以在 API 响应中读取用量信息,而不是用中文字数随意估算。
实例:读取 DeepSeek Token 用量
import
os
from
openai
import
OpenAI
client
=
OpenAI
(
api_key
=
os
.
environ
[
"DEEPSEEK_API_KEY"
]
,
base_url
=
"https://api.deepseek.com"
)
response
=
client.
chat
.
completions
.
create
(
model
=
"deepseek-flash"
,
messages
=
[
{
"role"
:
"user"
,
"content"
:
"请解释什么是 Python 列表。"
}
]
,
thinking
=
{
"type"
:
"disabled"
}
)
(
response.
choices
[
0
]
.
message
.
content
)
usage
=
response.
usage
if
usage:
(
"输入 Token:"
,
usage.
prompt_tokens
)
(
"输出 Token:"
,
usage.
completion_tokens
)
(
"总 Token:"
,
usage.
total_tokens
)
这里获取的是平台返回的用量信息。
如果要计算金额,应再根据当前模型的官方价格表进行换算,而不是把某个旧价格永久写进程序。
如何优化 API 调用成本
如果只是偶尔调用一次,费用可能不明显。
但如果我们的网站每天处理大量请求,成本就需要认真考虑。
API 优化不只是减少 Token,也包括减少无效调用、错误重试和重复处理。
常见的成本优化方式
缓存适合哪些场景
如果我们的网站有一个 AI 工具,每次都需要解释相同的固定术语,就可以考虑缓存。
例如,用户反复查询"什么是 JSON",如果系统采用相同模型、相同提示词和相同配置,且任务不需要实时数据,就可能复用之前的结果。
但对于新闻、汇率、账户信息等变化较快的内容,就不应该长期复用过时的缓存。
一个简单的本地缓存示例
下面使用 Python 字典保存当前程序运行期间的响应。
实例:缓存重复问题
import
os
from
openai
import
OpenAI
client
=
OpenAI
(
api_key
=
os
.
environ
[
"DEEPSEEK_API_KEY"
]
,
base_url
=
"https://api.deepseek.com"
)
cache
=
{
}
def
ask_ai
(
question
)
:
if
question
in
cache:
(
"命中本地缓存"
)
return
cache
[
question
]
response
=
client.
chat
.
completions
.
create
(
model
=
"deepseek-flash"
,
messages
=
[
{
"role"
:
"user"
,
"content"
: question
}
]
,
thinking
=
{
"type"
:
"disabled"
}
)
answer
=
response.
choices
[
0
]
.
message
.
content
or
""
cache
[
question
]
=
answer
return
answer
question
=
"请解释什么是 JSON。"
(
"第一次请求:"
)
(
ask_ai
(
question
)
)
(
"
\n
第二次请求:"
)
(
ask_ai
(
question
)
)
第一次调用会向 API 发送请求。
第二次问题完全相同时,程序直接返回内存中保存的结果。
这个例子仅用于说明缓存原理。
正式应用还需要考虑模型版本、系统提示词、缓存有效期、用户隔离和敏感数据处理,不能只根据用户问题字符串判断是否可以共享缓存。
API 错误处理与重试机制
调用 API 不一定每次都成功。
例如,网络连接失败、API Key 无效、模型没有权限、请求太频繁,都可能导致错误。
如果我们准备让 AI 功能长期运行,就需要处理这些情况。
常见 HTTP 错误
不同平台可能使用其他状态码表达余额、额度或业务限制,因此需要结合服务返回的错误信息判断。
为什么不能一直重试
假设我们向模型提交请求,但网络在返回响应时断开。
此时我们无法仅凭客户端超时就断定服务端一定没有处理这次请求。
如果立即反复发送相同请求,可能产生额外的调用成本。
因此,重试应该具备明确的次数上限,并尽量利用 SDK 已经提供的重试能力。
使用 SDK 内置重试
OpenAI Python SDK 对部分临时性错误提供了内置重试机制。
我们可以通过
max_retries
设置最大重试次数。
实例:API 错误处理
import
os
from
openai
import
(
OpenAI
,
AuthenticationError
,
PermissionDeniedError
,
RateLimitError
,
APIConnectionError
,
APIStatusError
)
client
=
OpenAI
(
api_key
=
os
.
environ
[
"DEEPSEEK_API_KEY"
]
,
base_url
=
"https://api.deepseek.com"
,
max_retries
=
2
,
timeout
=
60.0
)
try
:
response
=
client.
chat
.
completions
.
create
(
model
=
"deepseek-flash"
,
messages
=
[
{
"role"
:
"user"
,
"content"
:
"请介绍一下 Python。"
}
]
,
thinking
=
{
"type"
:
"disabled"
}
)
(
response.
choices
[
0
]
.
message
.
content
)
except
AuthenticationError:
(
"认证失败,请检查 API Key。"
)
except
PermissionDeniedError:
(
"当前账号没有相应权限。"
)
except
RateLimitError:
(
"触发限速或配额限制,请查看服务提示。"
)
except
APIConnectionError:
(
"网络连接失败,请检查网络。"
)
except
APIStatusError
as
error:
(
"API 请求失败。"
)
(
"HTTP 状态码:"
,
error.
status_code
)
except
Exception
as
error:
(
"程序发生错误:"
,
type
(
error
)
.__name__
)
这里我们把重试控制交给 SDK,而不是自己不断循环调用接口。
对于创建视频、支付或其他可能产生不可重复操作的 API,还需要根据服务是否支持任务查询和幂等机制来设计重试流程。
实战项目:制作 RUNOOB AI 命令行聊天工具
前面我们已经掌握了 API 调用、多轮对话、Token 统计和异常处理。
接下来把这些内容组合起来,制作一个可以在终端中直接使用的聊天程序。
本次项目使用 DeepSeek API,主要实现以下功能:
在终端中与 AI 对话。
支持连续多轮提问。
使用固定的教学助手系统提示词。
查看当前会话的 Token 用量。
保存聊天记录。
清空当前会话。
处理常见 API 异常。
项目文件
我们只需要创建一个 Python 文件:
实例:项目结构
runoob-ai-api/
└── runoob_chatbot.py
完整 Python 代码
创建
runoob_chatbot.py
,输入下面的代码。
实例:RUNOOB AI 命令行聊天工具
import
os
import
json
from
pathlib
import
Path
from
datetime
import
datetime
from
getpass
import
getpass
from
openai
import
OpenAI
,
OpenAIError
MODEL
=
"deepseek-flash"
SYSTEM_PROMPT
=
(
"你是一个面向编程初学者的 AI 教学助手。"
"使用自然、准确的中文回答问题。"
"解释技术概念时尽量提供简单示例。"
"不编造不存在的技术信息。"
)
class
RunoobChatBot:
def
__init__
(
self
)
:
api_key
=
os
.
getenv
(
"DEEPSEEK_API_KEY"
)
if
not
api_key:
api_key
=
getpass
(
"请输入 DeepSeek API Key:"
)
.
strip
(
)
if
not
api_key:
raise
ValueError
(
"没有提供 API Key"
)
self
.
client
=
OpenAI
(
api_key
=
api_key
,
base_url
=
"https://api.deepseek.com"
,
max_retries
=
2
,
timeout
=
60.0
)
self
.
messages
=
[
]
self
.
input_tokens
=
0
self
.
output_tokens
=
0
def
chat
(
self
,
question
)
:
保留最近 6 轮完整对话
recent_history
=
self
.
messages
[
-
12
:
]
request_messages
=
[
{
"role"
:
"system"
,
"content"
: SYSTEM_PROMPT
}
]
+ recent_history +
[
{
"role"
:
"user"
,
"content"
: question
}
]
response
=
self
.
client
.
chat
.
completions
.
create
(
model
=
MODEL
,
messages
=
request_messages
,
thinking
=
{
"type"
:
"disabled"
}
)
answer
=
response.
choices
[
0
]
.
message
.
content
or
""
成功后才保存本轮对话
self
.
messages
.
append
(
{
"role"
:
"user"
,
"content"
: question
}
)
self
.
messages
.
append
(
{
"role"
:
"assistant"
,
"content"
: answer
}
)
if
response.
usage
:
self
.
input_tokens
+
=
response.
usage
.
prompt_tokens
self
.
output_tokens
+
=
response.
usage
.
completion_tokens
return
answer
def
show_stats
(
self
)
:
(
"
\n
=== 当前会话统计 ==="
)
(
"模型:"
,
MODEL
)
(
"对话轮数:"
,
len
(
self
.
messages
)
//
2
)
(
"输入 Token:"
,
self
.
input_tokens
)
(
"输出 Token:"
,
self
.
output_tokens
)
(
"总 Token:"
,
self
.
input_tokens
+
self
.
output_tokens
)
(
"费用请以平台实际账单为准。
\n
"
)
def
save_history
(
self
)
:
output_dir
=
Path
(
"conversations"
)
output_dir.
mkdir
(
exist_ok
=
True
)
filename
=
(
"chat-"
+
datetime
.
now
(
)
.
strftime
(
"%Y%m%d-%H%M%S-%f"
)
+
".json"
)
filepath
=
output_dir / filename
data
=
{
"model"
: MODEL
,
"saved_at"
:
datetime
.
now
(
)
.
isoformat
(
)
,
"input_tokens"
:
self
.
input_tokens
,
"output_tokens"
:
self
.
output_tokens
,
"messages"
:
self
.
messages
}
filepath.
write_text
(
json.
dumps
(
data
,
ensure_ascii
=
False
,
indent
=
2
)
,
encoding
=
"utf-8"
)
(
"已保存到:"
,
filepath
)
def
clear
(
self
)
:
self
.
messages
.
clear
(
)
self
.
input_tokens
=
0
self
.
output_tokens
=
0
(
"当前会话已清空。"
)
def
print_help
(
)
:
(
"""
可用命令:
/help 查看帮助
/stats 查看 Token 用量
/save 保存当前聊天记录
/clear 清空当前会话
/quit 退出程序
直接输入文字即可与 AI 对话。
"""
)
def
main
(
)
:
(
"RUNOOB AI 命令行聊天工具"
)
bot
=
RunoobChatBot
(
)
print_help
(
)
while
True
:
try
:
question
=
input
(
"我们:"
)
.
strip
(
)
if
not
question:
continue
if
question
==
"/quit"
:
(
"再见!"
)
break
if
question
==
"/help"
:
print_help
(
)
continue
if
question
==
"/stats"
:
bot.
show_stats
(
)
continue
if
question
==
"/save"
:
bot.
save_history
(
)
continue
if
question
==
"/clear"
:
bot.
clear
(
)
continue
(
"AI:"
,
end
=
""
,
flush
=
True
)
answer
=
bot.
chat
(
question
)
(
answer
)
(
)
except
(
KeyboardInterrupt
,
EOFError
)
:
(
"
\n
程序已退出。"
)
break
except
OpenAIError
as
error:
(
"
\n
API 调用失败:"
,
type
(
error
)
.__name__
)
except
Exception
as
error:
(
"
\n
发生错误:"
,
type
(
error
)
.__name__
)
if
__name__
==
"__main__"
:
main
(
)
运行聊天工具
确认已经安装
openai
SDK,并准备好 DeepSeek API Key。
然后运行:
实例:启动聊天程序
python runoob_chatbot.py
如果没有设置
DEEPSEEK_API_KEY
环境变量,程序会通过隐藏输入方式请求 API Key,不会把密钥直接显示在终端上。
运行后,我们就可以输入自然语言进行对话。
使用效果
下面是一个示意性的交互过程,实际回答内容会由模型生成。
实例:命令行聊天示例
RUNOOB AI 命令行聊天工具
我们:什么是 Python?
AI:Python 是一种语法简洁、应用广泛的编程语言。
我们:它适合开发哪些项目?
AI:Python 可以用于网站开发、自动化脚本、
数据分析和人工智能等领域。
我们:/stats
=== 当前会话统计 ===
模型:deepseek-flash
对话轮数:2
输入 Token:...
输出 Token:...
总 Token:...
费用请以平台实际账单为准。
我们:/save
已保存到:conversations/chat-....json
我们:/quit
再见!
如何保存聊天记录
输入
/save
后,程序会将当前会话保存为 JSON 文件。
生成的目录类似:
实例:保存后的文件结构
runoob-ai-api/
├── runoob_chatbot.py
└── conversations/
└── chat-20261109-120000-123456.json
这里保存的是完整聊天记录和 Token 用量,不包含 API Key。
聊天记录本身仍可能包含敏感信息。因此,正式项目需要进一步考虑文件权限、数据保留时间和用户隐私。
后续还可以添加哪些功能
在这个基础版本之上,我们还可以继续扩展:
需要注意,本章节这个示例只是本地运行的学习项目。
如果准备将它部署为公开网站,还需要加入用户身份认证、请求限速、使用额度、日志管理、输入校验和服务器端密钥管理等功能。
常见问题与解决方法
排查 API 失败的推荐顺序
如果我们的程序无法成功调用模型,可以先检查 API Key 是否存在,再确认服务地址和模型标识,之后查看 HTTP 错误与平台的额度限制。
不需要一开始就更换整个 SDK 或重写全部代码。
很多时候,只是凭证、模型名称或者请求参数不正确。
动手练习
练习:调用不同模型
先完成 DeepSeek API 的基础调用,再尝试使用自己有权限访问的其他模型。
比较同一问题在不同模型中的输出内容与 Token 用量。
练习:修改系统提示词
将命令行聊天工具的系统提示词改成 Python 教学助手。
要求它解释概念时先提供定义,再给出简单代码示例。
练习:实现流式聊天
参考前面的流式输出示例,将命令行工具中的普通响应改成流式响应。
让 AI 的回复逐渐显示在终端中。
练习:加入模型配置
将模型名称从代码中的固定常量改为可以通过环境变量配置。
尝试在不修改源代码的情况下切换模型。
练习:统计 API 用量
让程序在每次调用后记录输入和输出 Token。
最后汇总当前会话的使用量,并尝试结合官方价格表估算费用。
练习:开发简单网页聊天工具
使用 FastAPI 作为后端,创建一个接收用户输入的接口。
前端通过 HTML 和 JavaScript 提交问题,后端调用 AI API,再将回复返回网页。
在设计时,我们要确保 API Key 只保存在服务器端,不直接暴露给浏览器。
官方文档与学习资源
AI API 的模型名称、参数、价格和功能都会持续更新。
实际开发中,建议优先参考官方文档,不要只依赖旧教程中的固定配置。
我们可以先把命令行聊天工具运行起来,熟悉从发送请求到读取响应的完整过程。
后面开发网站 AI 功能、自动化脚本或者 Agent 应用时,仍然会用到这里介绍的请求、上下文、流式输出、错误处理和用量管理等基本知识。
CSS独立储备