Chat Completions API #
什么是 Chat Completions？ #
Chat Completions API 是 OpenAI 提供的对话式文本生成接口，它接受一系列消息作为输入，然后生成模型回复。这是使用 GPT 模型的主要方式。
text
┌─────────────────────────────────────────────────────────────┐
│ Chat Completions 工作原理 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 输入：消息列表（Messages） │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ [ │ │
│ │ {"role": "system", "content": "你是一个助手"}, │ │
│ │ {"role": "user", "content": "你好"}, │ │
│ │ {"role": "assistant", "content": "你好！"}, │ │
│ │ {"role": "user", "content": "今天天气如何？"} │ │
│ │ ] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ GPT 模型处理 │ │
│ │ 理解上下文 → 生成回复 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 输出：模型回复 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ {"role": "assistant", "content": "抱歉，我无法..."} │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
基本用法 #
最简单的请求 #
python
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "你好，介绍一下 Python"}
]
)
print(response.choices[0].message.content)
完整请求示例 #
python
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "你是一个专业的编程助手。"},
{"role": "user", "content": "如何学习 Python？"}
],
temperature=0.7,
max_tokens=1000,
top_p=1,
frequency_penalty=0,
presence_penalty=0
)
print(response.choices[0].message.content)
print(f"\n使用的 Token: {response.usage.total_tokens}")
消息格式 #
消息结构 #
text
┌─────────────────────────────────────────────────────────────┐
│ 消息结构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 每条消息包含两个字段： │
│ │
│ { │
│ "role": "角色类型", // 必填 │
│ "content": "消息内容" // 必填 │
│ } │
│ │
│ 角色类型： │
│ ───────────────────────────────────────────────────────── │
│ system 系统指令，设定 AI 的行为 │
│ user 用户消息 │
│ assistant AI 助手的回复 │
│ │
└─────────────────────────────────────────────────────────────┘
System 消息 #
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{
"role": "system",
"content": "你是一个专业的 Python 编程助手。回答要简洁、专业，并提供代码示例。"
},
{
"role": "user",
"content": "如何读取文件？"
}
]
)
User 消息 #
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "什么是机器学习？"}
]
)
Assistant 消息 #
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "你好"},
{"role": "assistant", "content": "你好！有什么我可以帮助你的吗？"},
{"role": "user", "content": "请继续我们之前的对话"}
]
)
系统提示（System Prompt） #
什么是系统提示？ #
text
┌─────────────────────────────────────────────────────────────┐
│ 系统提示的作用 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 系统提示用于： │
│ │
│ 1. 设定角色 │
│ "你是一个专业的翻译" │
│ │
│ 2. 定义行为 │
│ "回答要简洁，不超过100字" │
│ │
│ 3. 提供背景 │
│ "用户是初学者，请用简单的语言解释" │
│ │
│ 4. 设置格式 │
│ "请用 JSON 格式返回结果" │
│ │
│ 5. 限制范围 │
│ "只回答编程相关问题" │
│ │
└─────────────────────────────────────────────────────────────┘
系统提示示例 #
角色扮演 #
python
system_prompt = """你是一位资深的软件架构师，拥有 15 年的行业经验。
你的职责是：
1. 帮助用户设计系统架构
2. 提供技术选型建议
3. 指出潜在的技术风险
4. 给出最佳实践建议
回答风格：
- 专业但不晦涩
- 提供具体的理由
- 必要时画图说明
- 给出多个方案供选择"""
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": "如何设计一个高并发的电商系统？"}
]
)
格式控制 #
python
system_prompt = """你是一个数据提取助手。
从用户输入中提取信息，并以 JSON 格式返回。
返回格式：
{
"name": "姓名",
"email": "邮箱",
"phone": "电话",
"company": "公司"
}
如果某项信息缺失，对应值设为 null。"""
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": "我是张三，邮箱是 zhangsan@example.com，电话 13800138000"}
]
)
import json
data = json.loads(response.choices[0].message.content)
print(data)
语言风格 #
python
system_prompt = """你是一个幽默风趣的助手。
- 用轻松愉快的语气回答
- 适当使用表情符号
- 可以开一些无伤大雅的玩笑
- 但要确保回答的准确性"""
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": "什么是递归？"}
]
)
多轮对话 #
对话上下文管理 #
text
┌─────────────────────────────────────────────────────────────┐
│ 多轮对话流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 第 1 轮： │
│ User: "你好" │
│ Assistant: "你好！有什么可以帮助你的？" │
│ │
│ 第 2 轮： │
│ User: "我想学习 Python" │
│ Assistant: "很好！Python 是一门优秀的语言..." │
│ │
│ 第 3 轮： │
│ User: "从哪里开始？" │
│ Assistant: "建议从基础语法开始..." │
│ │
│ 关键：每次请求都要带上之前的对话历史 │
│ │
└─────────────────────────────────────────────────────────────┘
实现多轮对话 #
python
from openai import OpenAI
client = OpenAI()
class ChatSession:
def __init__(self, system_prompt: str = "你是一个友好的助手。"):
self.messages = [
{"role": "system", "content": system_prompt}
]
def chat(self, user_input: str) -> str:
self.messages.append({
"role": "user",
"content": user_input
})
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=self.messages
)
assistant_message = response.choices[0].message.content
self.messages.append({
"role": "assistant",
"content": assistant_message
})
return assistant_message
def get_history(self):
return self.messages
session = ChatSession("你是一个 Python 编程助手。")
print(session.chat("什么是列表？"))
print(session.chat("如何创建一个列表？"))
print(session.chat("能给我一个例子吗？"))
print("\n对话历史：")
for msg in session.get_history():
print(f"{msg['role']}: {msg['content'][:50]}...")
对话历史管理 #
python
from openai import OpenAI
from typing import List, Dict
client = OpenAI()
class ConversationManager:
def __init__(self, max_tokens: int = 4000):
self.max_tokens = max_tokens
self.messages: List[Dict] = []
def add_message(self, role: str, content: str):
self.messages.append({"role": role, "content": content})
self._trim_history()
def _trim_history(self):
while self._estimate_tokens() > self.max_tokens and len(self.messages) > 1:
if self.messages[0]["role"] == "system":
self.messages.pop(1)
else:
self.messages.pop(0)
def _estimate_tokens(self) -> int:
total = 0
for msg in self.messages:
total += len(msg["content"]) // 4
return total
def chat(self, user_input: str) -> str:
self.add_message("user", user_input)
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=self.messages
)
assistant_message = response.choices[0].message.content
self.add_message("assistant", assistant_message)
return assistant_message
manager = ConversationManager(max_tokens=2000)
高级功能 #
JSON 模式 #
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{
"role": "system",
"content": "你是一个数据提取助手。以 JSON 格式返回结果。"
},
{
"role": "user",
"content": "提取以下文本中的实体：苹果公司成立于1976年，总部位于加州库比蒂诺。"
}
],
response_format={"type": "json_object"}
)
import json
data = json.loads(response.choices[0].message.content)
print(json.dumps(data, indent=2, ensure_ascii=False))
视觉能力（GPT-4 Vision） #
python
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "这张图片里有什么？"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.jpg"
}
}
]
}
],
max_tokens=500
)
print(response.choices[0].message.content)
使用 Base64 图片 #
python
import base64
def encode_image(image_path: str) -> str:
with open(image_path, "rb") as image_file:
return base64.b64encode(image_file.read()).decode('utf-8')
base64_image = encode_image("path/to/image.png")
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "描述这张图片"
},
{
"type": "image_url",
"image_url": {
"url": f"data:image/png;base64,{base64_image}"
}
}
]
}
]
)
多图片输入 #
python
response = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "比较这两张图片的区别："},
{
"type": "image_url",
"image_url": {"url": "https://example.com/image1.jpg"}
},
{
"type": "image_url",
"image_url": {"url": "https://example.com/image2.jpg"}
}
]
}
]
)
响应处理 #
完整响应结构 #
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "你好"}
]
)
print(f"请求 ID: {response.id}")
print(f"模型: {response.model}")
print(f"创建时间: {response.created}")
print(f"回复内容: {response.choices[0].message.content}")
print(f"结束原因: {response.choices[0].finish_reason}")
print(f"输入 Token: {response.usage.prompt_tokens}")
print(f"输出 Token: {response.usage.completion_tokens}")
print(f"总 Token: {response.usage.total_tokens}")
finish_reason 说明 #
text
┌─────────────────────────────────────────────────────────────┐
│ finish_reason 类型 │
├─────────────────────────────────────────────────────────────┤
│ │
│ stop │
│ ───────────────────────────────────────────────────────── │
│ 正常完成，模型已生成完整回复 │
│ │
│ length │
│ ───────────────────────────────────────────────────────── │
│ 达到 max_tokens 限制，回复被截断 │
│ 解决：增加 max_tokens 或简化请求 │
│ │
│ content_filter │
│ ───────────────────────────────────────────────────────── │
│ 内容被安全过滤器拦截 │
│ 解决：修改输入内容 │
│ │
│ function_call │
│ ───────────────────────────────────────────────────────── │
│ 模型决定调用函数（已弃用，使用 tool_calls） │
│ │
│ tool_calls │
│ ───────────────────────────────────────────────────────── │
│ 模型决定调用工具 │
│ │
└─────────────────────────────────────────────────────────────┘
最佳实践 #
1. 系统提示设计 #
python
SYSTEM_PROMPT = """你是一个专业的客服助手。
职责：
1. 回答用户关于产品的问题
2. 处理投诉和建议
3. 引导用户完成购买流程
行为准则：
- 礼貌、耐心、专业
- 不确定时承认并寻求帮助
- 不讨论竞争对手产品
- 不承诺无法保证的事情
回复格式：
- 简洁明了，不超过 200 字
- 使用分段和列表提高可读性
- 必要时提供相关链接"""
2. 错误处理 #
python
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
import time
def safe_chat(messages: list, max_retries: int = 3) -> str:
client = OpenAI()
for attempt in range(max_retries):
try:
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages
)
return response.choices[0].message.content
except RateLimitError:
wait = 2 ** attempt
print(f"速率限制，等待 {wait} 秒...")
time.sleep(wait)
except APIConnectionError as e:
print(f"连接错误: {e}")
time.sleep(1)
except APIError as e:
print(f"API 错误: {e}")
if attempt == max_retries - 1:
raise
raise Exception("超过最大重试次数")
3. 内容安全检查 #
python
def is_safe_content(content: str) -> bool:
client = OpenAI()
response = client.moderations.create(
input=content
)
return not response.results[0].flagged
user_input = "用户输入的内容"
if is_safe_content(user_input):
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": user_input}]
)
else:
print("内容包含敏感信息，已拒绝处理")
4. Token 管理 #
python
import tiktoken
def truncate_text(text: str, max_tokens: int, model: str = "gpt-4o-mini") -> str:
encoding = tiktoken.encoding_for_model(model)
tokens = encoding.encode(text)
if len(tokens) <= max_tokens:
return text
truncated_tokens = tokens[:max_tokens]
return encoding.decode(truncated_tokens)
long_text = "很长的文本内容..."
safe_text = truncate_text(long_text, max_tokens=4000)
下一步 #
现在你已经掌握了 Chat Completions API 的核心功能，接下来学习 参数详解，了解如何通过调整参数来优化模型输出！
最后更新：2026-03-29