[AI智能体与提效-116] - OpenAI API用法：Completions创建聊天对话

使用 OpenAI API 的Chat Completions(/v1/chat/completions) 接口是构建聊天对话最核心、最常用的方式。

与旧的completions接口不同，Chat Completions专为多轮对话设计，它接受一个包含角色（system,user,assistant）的消息列表，并返回模型生成的回复。

以下是基于 Python SDK (openai >= 1.0) 的完整用法指南，涵盖基础对话、多轮上下文、流式输出和结构化数据。

1. 前置准备

安装官方 SDK：

bash

pip install openai

初始化客户端：

python

from openai import OpenAI import os # 推荐将 API Key 放在环境变量中，避免硬编码 client = OpenAI( api_key=os.environ.get("OPENAI_API_KEY"), # base_url="https://your-proxy.com/v1" # 如果有代理可配置 )

2. 基础用法：单次问答

最简单的对话模式：发送一条消息，接收一条回复。

python

response = client.chat.completions.create( model="gpt-4o", # 或 gpt-4o-mini, o1-preview 等 messages=[ {"role": "system", "content": "你是一个乐于助人的中文助手。"}, {"role": "user", "content": "量子纠缠是什么？用一句话解释。"} ], temperature=0.7, # 创造性 (0-2) max_tokens=500 # 最大生成长度 ) # 提取回复内容 reply = response.choices[0].message.content print(f"AI: {reply}")

关键点解析：

• messages列表：
  • system: 设定人设、规则（可选，但强烈建议）。
  • user: 用户输入。
  • assistant: 模型之前的回复（用于多轮对话）。
• model: 指定使用的模型版本。
• choices[0].message.content: 模型生成的文本内容。

3. 进阶用法：多轮对话 (保持上下文)

Chat Completions本身是无状态的。要实现“记住”之前的对话，你必须手动将历史对话记录拼接到messages列表中，每次请求都发送给云端。

python

# 模拟一个对话历史列表 conversation_history = [ {"role": "system", "content": "你是一个专业的 Python 程序员。"} ] def chat(user_input): # 1. 将用户新输入加入历史 conversation_history.append({"role": "user", "content": user_input}) # 2. 发送包含完整历史的请求 response = client.chat.completions.create( model="gpt-4o", messages=conversation_history # 关键：带上所有历史 ) # 3. 获取并保存 AI 的回复到历史 ai_reply = response.choices[0].message.content conversation_history.append({"role": "assistant", "content": ai_reply}) return ai_reply # --- 测试多轮对话 --- print("User: 什么是列表推导式？") ans1 = chat("什么是列表推导式？") print(f"AI: {ans1}") print("\nUser: 能给我举个刚才那个语法的例子吗？") # 注意：这里没有显式传递“刚才那个语法”，但 AI 知道指的是列表推导式，因为历史记录里包含了上一轮对话 ans2 = chat("能给我举个刚才那个语法的例子吗？") print(f"AI: {ans2}")

注意：随着对话变长，messages列表会越来越大，消耗的 Token 也会越来越多。当超过模型的上下文窗口（如 128k）时，你需要自行实现策略（如滑动窗口、摘要总结）来截断历史记录。

4. 高级用法：流式输出 (Streaming)

为了让用户体验更好（像打字机一样逐字显示），可以开启stream=True。这会返回一个生成器，而不是等待全部完成后一次性返回。

python

stream = client.chat.completions.create( model="gpt-4o", messages=[ {"role": "system", "content": "你是一个诗人。"}, {"role": "user", "content": "写一首关于春天的短诗。"} ], stream=True # 开启流式 ) print("AI: ", end="", flush=True) for chunk in stream: # chunk 是一个小片段，可能包含 content，也可能为 None (结束标志) if chunk.choices[0].delta.content is not None: content = chunk.choices[0].delta.content print(content, end="", flush=True) # 逐字打印 print() # 换行

适用场景：聊天机器人界面、实时语音对话后端。

5. 实用技巧：强制 JSON 输出

如果你需要程序化处理结果（例如提取实体、生成配置），可以使用response_format={"type": "json_object"}强制模型输出合法的 JSON。

python

response = client.chat.completions.create( model="gpt-4o", messages=[ {"role": "system", "content": "你是一个数据提取器。请只输出 JSON 格式，不要包含 markdown 标记。"}, {"role": "user", "content": "从这句话提取姓名和年龄：'张三今年 25 岁，是个工程师'"} ], response_format={"type": "json_object"} # 关键参数 ) import json data = json.loads(response.choices[0].message.content) print(f"姓名: {data['name']}, 年龄: {data['age']}")

6. 常见参数详解表

表格

7. 错误处理最佳实践

网络波动或速率限制（Rate Limit）是常态，务必加上重试机制。

python

from openai import OpenAI, RateLimitError, APIConnectionError import time def create_chat_with_retry(messages, retries=3): for attempt in range(retries): try: return client.chat.completions.create( model="gpt-4o", messages=messages ) except RateLimitError as e: wait_time = 2 ** attempt # 指数退避：2s, 4s, 8s... print(f"触发限流，等待 {wait_time} 秒后重试...") time.sleep(wait_time) except APIConnectionError as e: print(f"网络连接错误: {e}") if attempt == retries - 1: raise time.sleep(1) except Exception as e: print(f"未知错误: {e}") raise # 使用 response = create_chat_with_retry([{"role": "user", "content": "Hello"}]) print(response.choices[0].message.content)

总结

使用chat.completions的核心在于维护好messages列表。

• 单次问答：直接发system+user。
• 多轮对话：不断append新的user和assistant消息到列表中，全量发送。
• 体验优化：使用stream=True实现打字机效果。
• 程序集成：使用response_format={"type": "json_object"}获取结构化数据。