AI入门

AI API 开发入门教程:用 Python 调用 ChatGPT、DeepSeek 和 Claude

资料核对与更新:2026-11-18 · 阅读约48分钟

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 菜鸟教程。"

)

print

(

"AI 回复:"

)

print

(

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"

}

)

print

(

"AI 回复:"

)

print

(

response.

choices

[

0

]

.

message

.

content

)

if

response.

usage

:

print

(

"输入 Token:"

,

response.

usage

.

prompt_tokens

)

print

(

"输出 Token:"

,

response.

usage

.

completion_tokens

)

print

(

"总 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"

:

print

(

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"

:

print

(

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"

:

print

(

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

print

(

"第一轮:"

)

print

(

chat

(

"什么是 Python?"

)

)

print

(

"

\n

第二轮:"

)

print

(

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

)

print

(

"AI:"

,

end

=

""

,

flush

=

True

)

parts

=

[

]

for

chunk

in

stream:

if

not

chunk

.

choices

:

continue

content

=

chunk

.

choices

[

0

]

.

delta

.

content

if

content:

print

(

content

,

end

=

""

,

flush

=

True

)

parts.

append

(

content

)

print

(

"

\n

"

)

full_answer

=

""

.

join

(

parts

)

print

(

"本次回复字符数:"

,

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"

:

print

(

event.

delta

,

end

=

""

,

flush

=

True

)

print

(

)

这里我们只处理文字增量事件。

如果开发正式应用,还应该处理响应完成、错误及其他事件类型。

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"

}

)

print

(

response.

choices

[

0

]

.

message

.

content

)

usage

=

response.

usage

if

usage:

print

(

"输入 Token:"

,

usage.

prompt_tokens

)

print

(

"输出 Token:"

,

usage.

completion_tokens

)

print

(

"总 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:

print

(

"命中本地缓存"

)

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。"

print

(

"第一次请求:"

)

print

(

ask_ai

(

question

)

)

print

(

"

\n

第二次请求:"

)

print

(

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"

}

)

print

(

response.

choices

[

0

]

.

message

.

content

)

except

AuthenticationError:

print

(

"认证失败,请检查 API Key。"

)

except

PermissionDeniedError:

print

(

"当前账号没有相应权限。"

)

except

RateLimitError:

print

(

"触发限速或配额限制,请查看服务提示。"

)

except

APIConnectionError:

print

(

"网络连接失败,请检查网络。"

)

except

APIStatusError

as

error:

print

(

"API 请求失败。"

)

print

(

"HTTP 状态码:"

,

error.

status_code

)

except

Exception

as

error:

print

(

"程序发生错误:"

,

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

)

:

print

(

"

\n

=== 当前会话统计 ==="

)

print

(

"模型:"

,

MODEL

)

print

(

"对话轮数:"

,

len

(

self

.

messages

)

//

2

)

print

(

"输入 Token:"

,

self

.

input_tokens

)

print

(

"输出 Token:"

,

self

.

output_tokens

)

print

(

"总 Token:"

,

self

.

input_tokens

+

self

.

output_tokens

)

print

(

"费用请以平台实际账单为准。

\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"

)

print

(

"已保存到:"

,

filepath

)

def

clear

(

self

)

:

self

.

messages

.

clear

(

)

self

.

input_tokens

=

0

self

.

output_tokens

=

0

print

(

"当前会话已清空。"

)

def

print_help

(

)

:

print

(

"""

可用命令:

/help   查看帮助

/stats  查看 Token 用量

/save   保存当前聊天记录

/clear  清空当前会话

/quit   退出程序

直接输入文字即可与 AI 对话。

"""

)

def

main

(

)

:

print

(

"RUNOOB AI 命令行聊天工具"

)

bot

=

RunoobChatBot

(

)

print_help

(

)

while

True

:

try

:

question

=

input

(

"我们:"

)

.

strip

(

)

if

not

question:

continue

if

question

==

"/quit"

:

print

(

"再见!"

)

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

print

(

"AI:"

,

end

=

""

,

flush

=

True

)

answer

=

bot.

chat

(

question

)

print

(

answer

)

print

(

)

except

(

KeyboardInterrupt

,

EOFError

)

:

print

(

"

\n

程序已退出。"

)

break

except

OpenAIError

as

error:

print

(

"

\n

API 调用失败:"

,

type

(

error

)

.__name__

)

except

Exception

as

error:

print

(

"

\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独立储备