文本对话详细教程¶
适用于所有聊天对话模型，从零开始学会调用大模型 API
实际调用效果展示¶
下面是使用本教程代码实际运行得到的输出示例：
简单对话¶
提问： "用中文介绍一下自己"
AI 回答：
Token 消耗统计： - prompt_tokens: 13 - completion_tokens: 37 - total_tokens: 50
流式输出示例¶
提问： "写一首关于人工智能的小诗"
AI 回答（流式输出）：
目录¶
前置准备¶
在开始之前，请确保你已经准备好了以下内容：
1. 安装 SDK¶
2. 准备 API Key¶
从 API Nexus 控制台获取你的 API Key，格式类似：
3. 环境配置（推荐）¶
为了避免把 API Key 写死在代码里，推荐使用环境变量：
Windows:
Mac/Linux:
Python dotenv (推荐):
安装 python-dotenv：
在项目根目录创建 .env 文件：
在代码中加载：
你的第一次 API 调用¶
复制粘贴这段代码，运行试试看！
from openai import OpenAI
# 1. 初始化客户端
client = OpenAI(
api_key="你的API_KEY", # 如果配置了环境变量，可以不用写这行
base_url="https://apinexus.net/v1"
)
# 2. 调用 API
response = client.chat.completions.create(
model="gpt-4o-mini-2024-07-18", # 选择模型
messages=[
{"role": "user", "content": "用中文介绍一下自己"}
]
)
# 3. 输出结果
print("AI 回答:", response.choices[0].message.content)
如果你能看到 AI 的回复，恭喜你！你的第一次 API 调用成功了！
分步详解¶
让我们把上面的代码拆开来，理解每一行都在做什么：
第 1 步：导入并初始化客户端¶
from openai import OpenAI
client = OpenAI(
api_key="你的API_KEY", # 认证你的身份
base_url="https://apinexus.net/v1" # 指定 API 服务商地址
)
理解： - OpenAI 是 SDK 提供的客户端类 - api_key 相当于你的密码，证明你有权调用 API - base_url 告诉 SDK 去哪里调用 API
第 2 步：发起对话请求¶
response = client.chat.completions.create(
model="gpt-4o-mini-2024-07-18",
messages=[
{"role": "user", "content": "用中文介绍一下自己"}
]
)
理解参数：
| 参数 | 说明 |
|---|---|
model | 用哪个模型回答。不同模型有不同的能力、速度和价格 |
messages | 对话内容。这是一个数组，因为对话可以有多轮 |
role | 消息角色。user 是用户说的话，assistant 是 AI 说的话，system 是系统设置 |
第 3 步：解析返回结果¶
完整的返回数据结构：
{
"id": "chatcmpl-abcdefghijklmnopqrstuvwxyz",
"object": "chat.completion",
"created": 1713792000,
"model": "gpt-4o-mini-2024-07-18",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "你好，我是一名人工智能助手..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 13,
"completion_tokens": 37,
"total_tokens": 50
}
}
小技巧： 每次调用都检查 usage，可以帮助你控制成本！
多轮对话¶
大模型是"失忆"的，每次调用都是独立的。如果你想让模型记住上下文，你需要把整个对话历史都发过去。
from openai import OpenAI
client = OpenAI(base_url="https://apinexus.net/v1")
# 我们用一个列表来保存所有消息历史
messages = []
# ========== 第一轮对话 ==========
user_input1 = "1+1 等于几？"
messages.append({"role": "user", "content": user_input1})
response = client.chat.completions.create(
model="gpt-4o-mini-2024-07-18",
messages=messages
)
answer1 = response.choices[0].message.content
print(f"AI: {answer1}")
messages.append({"role": "assistant", "content": answer1})
# ========== 第二轮对话 ==========
# 现在 AI 知道之前的对话内容了！
user_input2 = "再乘以 5 呢？"
messages.append({"role": "user", "content": user_input2})
response2 = client.chat.completions.create(
model="gpt-4o-mini-2024-07-18",
messages=messages # 把完整的历史消息都发过去
)
print(f"AI: {response2.choices[0].message.content}")
重要提示： - 消息顺序不能乱，必须按时间顺序排列 - 历史越长，花的 Token 越多，费用越高 - 每个模型都有最大上下文长度限制，超长会报错
流式输出¶
对于长文本生成，用流式输出可以让用户体验好 10 倍。不必等全部生成完才能看到内容。
from openai import OpenAI
client = OpenAI(base_url="https://apinexus.net/v1")
# stream=True 开启流式模式
stream = client.chat.completions.create(
model="gpt-4o-mini-2024-07-18",
messages=[{"role": "user", "content": "写一首关于人工智能的小诗"}],
stream=True
)
print("AI: ", end="", flush=True)
for chunk in stream:
# 每次只返回一小段文字
if chunk.choices[0].delta.content:
content = chunk.choices[0].delta.content
print(content, end="", flush=True) # 打字机效果
print() # 最后换行
流式输出的优势： - 首字响应快，用户不用等 - 打字机效果，体验更好 - 太长的内容可以提前中断
系统提示词¶
用系统提示词给 AI 设定"人设"，告诉它该怎么说话。
response = client.chat.completions.create(
model="gpt-4o-mini-2024-07-18",
messages=[
# 这就是系统提示词，通常放在 messages 的最前面
{
"role": "system",
"content": "你是一个专业的 Python 编程老师。你的回答要简洁，多用代码示例，解释要通俗易懂。"
},
# 然后才是用户的问题
{"role": "user", "content": "如何快速合并两个字典？"}
]
)
print(response.choices[0].message.content)
常用的系统提示词模板¶
| 场景 | 提示词示例 |
|---|---|
| 编程助手 | "你是一个资深 Python 开发工程师。回答要准确，提供完整可运行的代码，代码要加注释。" |
| 翻译官 | "你是一个专业翻译。用户说中文你翻译成英文，说英文你翻译成中文。翻译要自然流畅，符合目标语言习惯。" |
| 创意写作 | "你是一个想象力丰富的作家。擅长写故事、诗歌、文案。风格可以多样。" |
| 逻辑推理 | "你是一个逻辑思维严谨的助手。思考问题要分步骤，把你的推理过程说清楚。" |
| 数据分析 | "你是一个数据分析师。回答要结构化，多用列表、表格，给出数据洞察。" |
常用参数详解¶
除了 model 和 messages，还有很多实用参数可以调整。
temperature - 温度参数¶
控制 AI 回答的"创造性"和"随机性"，范围：0 ~ 2
| 值 | 效果 | 适用场景 |
|---|---|---|
| 0 ~ 0.3 | 非常确定，回答一致 | 代码生成、事实问答、分类 |
| 0.4 ~ 0.7 | 平衡，推荐默认值 | 一般对话、翻译、摘要 |
| 0.8 ~ 1.2 | 更有创造性 | 创意写作、头脑风暴 |
| 1.3 ~ 2.0 | 非常随机，可能出奇怪内容 | 纯创意探索 |
# 代码生成：低温度，确保正确性
response = client.chat.completions.create(
model="gpt-4o-mini-2024-07-18",
temperature=0.2, # 低温度
messages=messages
)
max_tokens - 最大输出长度¶
限制 AI 最多输出多少 Token，避免生成太长的回复：
response = client.chat.completions.create(
model="gpt-4o-mini-2024-07-18",
max_tokens=500, # 最多输出 500 Token
messages=messages
)
stream - 流式输出¶
详见 流式输出 章节。
presence_penalty 和 frequency_penalty¶
控制 AI 不要重复说同样的内容：
| 参数 | 范围 | 作用 |
|---|---|---|
presence_penalty | -2 ~ 2 | 话题重复性惩罚 |
frequency_penalty | -2 ~ 2 | 词频惩罚 |
# 写诗歌时，增加词频惩罚，避免重复用词
response = client.chat.completions.create(
model="gpt-4o-mini-2024-07-18",
frequency_penalty=0.5, # 增加词频惩罚
messages=[{"role": "user", "content": "写一首关于春天的诗"}]
)
错误处理最佳实践¶
网络请求总会有失败的时候，做好错误处理才能写出健壮的代码。
常见错误类型¶
| 错误 | 原因 | 处理方式 |
|---|---|---|
RateLimitError | 请求太频繁，限流了 | 等待一段时间重试 |
APIConnectionError | 网络连接失败 | 重试，检查网络 |
AuthenticationError | API Key 不对 | 检查 API Key 是否正确 |
APIError | 服务端错误 | 重试，或者换个模型 |
带有重试机制的完整代码¶
import time
from openai import OpenAI, RateLimitError, APIError, APIConnectionError
client = OpenAI(base_url="https://apinexus.net/v1")
def chat_with_retry(messages, model="gpt-4o-mini-2024-07-18", max_retries=3, **kwargs):
"""带有重试机制的聊天函数"""
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model=model,
messages=messages,
timeout=60, # 设置超时，避免无限等待
**kwargs
)
return response
except RateLimitError:
if attempt < max_retries - 1:
wait_time = (attempt + 1) * 5 # 重试间隔递增：5秒、10秒、15秒
print(f"限流了，等待 {wait_time} 秒后重试...")
time.sleep(wait_time)
continue
raise
except APIConnectionError:
if attempt < max_retries - 1:
print("网络连接失败，重试中...")
time.sleep(2)
continue
raise
except APIError as e:
if "500" in str(e) and attempt < max_retries - 1:
print("服务端错误，重试中...")
time.sleep(2)
continue
raise
# 使用示例
messages = [{"role": "user", "content": "你好"}]
try:
response = chat_with_retry(messages)
print("成功:", response.choices[0].message.content)
except Exception as e:
print(f"调用失败: {e}")
模型选择指南¶
API Nexus 提供多种模型供你选择：
| 模型 | 特点 | 推荐场景 |
|---|---|---|
| gpt-4o-mini-2024-07-18 | 速度快，成本低 | 日常对话、快速响应 |
| deepseek-v3.2 | 中文能力强，性价比高 | 代码、推理、中文场景 |
| claude-sonnet-4-6 | 质量高，适合复杂任务 | 长文本、多模态、复杂推理 |
| qwen-plus | 中文优化 | 中文对话、知识问答 |
选择建议： 1. 先从 gpt-4o-mini-2024-07-18 开始尝试，能满足需求就够用了 2. 中文场景优先试 deepseek-v3.2 或 qwen-plus 3. 复杂推理用 claude-sonnet-4-6 4. 代码任务用 deepseek-v3.2
常见问题 FAQ¶
Q: 1 Token 是多少个字？¶
A: 大约是 0.7 ~ 0.8 个中文字，或者 0.75 个英文单词。 - 1000 Token 约等于 700 个中文字 - 用 response.usage 可以看到精确的 Token 消耗
Q: 为什么 AI 会胡说八道？¶
A: 大模型是"统计型"的，不是数据库。对于它不确定的内容，可能会编造答案。 - 重要事实请自行验证 - 降低 temperature 可以减少胡说八道的概率
Q: 怎么让 AI 输出 JSON 格式？¶
A: 两种方法：
# 方法 1：用 response_format 参数
response = client.chat.completions.create(
model="gpt-4o-mini-2024-07-18",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": "你是一个 JSON 生成器。输出必须是合法 JSON。"},
{"role": "user", "content": "输出 3 个城市和它们的人口"}
]
)
# 方法 2：直接在提示词里要求
messages.append({"role": "user", "content": "请输出 JSON 格式，不要有其他解释文字。"})
Q: 最多能传多少历史消息？¶
A: 取决于模型的上下文窗口，每个模型的限制不同。建议控制在较短范围内以节省 Token 消耗。
Q: 调用超时了怎么办？¶
A: 1. 增加 timeout 参数 2. 缩短输出长度（减小 max_tokens） 3. 用更快的模型 4. 检查网络连接
完整示例代码¶
这里是一个完整的、可以直接运行的聊天程序：
"""
简单的命令行聊天程序
运行方法：python chat_demo.py
输入 'quit' 退出
"""
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
client = OpenAI(base_url="https://apinexus.net/v1")
messages = []
# 可选：设置系统提示词
messages.append({
"role": "system",
"content": "你是一个友好的 AI 助手。回答简洁明了，用中文回答。"
})
print("=" * 50)
print("API Nexus 聊天演示")
print("输入 'quit' 退出")
print("=" * 50)
while True:
user_input = input("\n你: ").strip()
if user_input.lower() in ["quit", "exit", "退出"]:
print("再见！")
break
if not user_input:
continue
messages.append({"role": "user", "content": user_input})
print("AI: ", end="", flush=True)
# 流式输出
stream = client.chat.completions.create(
model="gpt-4o-mini-2024-07-18",
messages=messages,
stream=True,
temperature=0.7
)
full_response = ""
for chunk in stream:
if chunk.choices[0].delta.content:
content = chunk.choices[0].delta.content
print(content, end="", flush=True)
full_response += content
print()
messages.append({"role": "assistant", "content": full_response})
把上面的代码保存为 chat_demo.py，运行试试吧！
下一步¶
最后更新: 2026-06-16