ChatCompletion（聊天补全）接口是 OpenAI 提供的核心对话 API，支撑着 GPT-3.5-turbo、GPT-4 等系列模型的对话能力调用

ChatCompletion聊天补全接口是 OpenAI 提供的核心对话 API支撑着 GPT-3.5-turbo、GPT-4 等系列模型的对话能力调用。新版 OpenAI Python SDKv1.0.0 及以上中该接口统一使用chat.completions.create()方法进行调用取代了旧版的openai.ChatCompletion.create()调用方式。本报告将围绕 ChatCompletion 接口的技术架构、核心参数、实战代码、响应解析、高级特性及最佳实践展开全面阐述旨在帮助开发者快速掌握该接口的使用方法并理解其背后的设计逻辑。二、技术背景与接口演进2.1 接口演进历史OpenAI Python SDK 在 2023 年 11 月发布了 1.0.0 版本这是一次重大的架构升级旧版接口openai 1.0.0使用openai.ChatCompletion.create()或openai.Completion.create()进行全局调用。新版接口openai ≥ 1.0.0使用client.chat.completions.create()需要先通过OpenAI()类实例化客户端对象。新版接口的设计更加模块化支持完整的类型提示Type Hints、异步调用AsyncOpenAI并且与 OpenAI 最新模型如 gpt-4o完全兼容。2.2 为什么需要迁移旧版接口已不再接收功能更新且在未来版本中可能被彻底移除。新版接口提供了以下优势更好的类型安全支持 IDE 自动补全和类型检查。原生异步支持通过AsyncOpenAI客户端实现非阻塞调用。统一接口设计聊天补全、文本补全、嵌入等接口采用一致的命名规范。更完善的错误处理提供细粒度的异常类如RateLimitError、APIConnectionError。三、接口核心架构3.1 HTTP 协议层ChatCompletion 接口的底层 HTTP 端点为POST https://api.openai.com/v1/chat/completions请求头必须包含Authorization: Bearer {API_KEY}API 密钥认证Content-Type: application/json请求体格式3.2 请求体核心字段chat.completions.create()方法接受以下核心参数参数类型必填说明modelstring是模型标识如gpt-4o、gpt-3.5-turbomessagesarray是对话消息数组按 system → user → assistant 顺序排列temperaturefloat否采样温度范围 [0.0, 2.0]默认 1.0top_pfloat否核采样阈值范围 (0.0, 1.0]默认 1.0max_completion_tokensinteger否最大输出 Token 数新版推荐字段streamboolean否是否启用流式输出默认 falsetoolsarray否工具/函数定义列表tool_choicestring/object否工具调用策略auto/none/requiredresponse_formatobject否响应格式控制如{type: json_object}stopstring/array否停止序列最多 4 个ninteger否候选回复数量默认 1presence_penaltyfloat否存在惩罚范围 [-2.0, 2.0]frequency_penaltyfloat否频率惩罚范围 [-2.0, 2.0]seedinteger否随机种子用于结果复现3.3 消息角色体系messages数组中的每条消息包含role和content两个字段system系统指令设定 AI 的角色、行为边界和回复风格。通常放在数组首位可选。user用户输入可以是字符串纯文本或数组多模态包含文本和图片。assistantAI 的历史回复用于维持多轮对话的上下文。tool工具调用返回的结果需包含tool_call_id和content。关键规则messages数组的最后一条消息的role必须为user或tool。四、实战代码与解析4.1 环境准备首先安装必要的依赖库pipinstallopenai python-dotenv在项目根目录创建.env文件写入 API 密钥OPENAI_API_KEYsk-your-api-key-here安全提示API 密钥仅在创建时显示一次丢失需重新生成。严禁将密钥硬编码到代码中或提交到 Git 仓库。4.2 基础调用示例以下代码演示如何使用新版 SDK 进行最基本的单轮对话调用importosfromdotenvimportload_dotenvfromopenaiimportOpenAI# 加载环境变量load_dotenv()# 初始化客户端clientOpenAI(api_keyos.getenv(OPENAI_API_KEY))defbasic_chat(user_message:str,model:strgpt-4o)-str: 基础聊天补全调用 Args: user_message: 用户输入的消息内容 model: 使用的模型名称默认 gpt-4o Returns: AI 生成的回复文本 responseclient.chat.completions.create(modelmodel,messages[{role:system,content:你是一个专业、友好的 AI 助手。},{role:user,content:user_message}],temperature0.7,max_completion_tokens1000)# 解析响应提取第一条候选回复的内容returnresponse.choices[0].message.content# 测试调用if__name____main__:resultbasic_chat(请用 Python 写一个冒泡排序算法)print(result)代码解析load_dotenv()从.env文件中读取环境变量避免密钥泄露。OpenAI()实例化客户端对象自动从环境变量OPENAI_API_KEY中读取密钥。chat.completions.create()发起 API 请求messages数组包含系统指令和用户输入。响应对象的层级结构为response.choices[0].message.content这是新版 SDK 的标准取值路径。4.3 多轮对话实现多轮对话的核心是维护一个消息历史列表每次将用户的新输入和 AI 的回复依次追加到列表中importosfromdotenvimportload_dotenvfromopenaiimportOpenAI load_dotenv()clientOpenAI(api_keyos.getenv(OPENAI_API_KEY))classChatBot:支持多轮对话的聊天机器人def__init__(self,model:strgpt-4o,system_prompt:strNone):self.modelmodel self.history[]# 如果提供了系统提示将其作为第一条消息ifsystem_prompt:self.history.append({role:system,content:system_prompt})defchat(self,user_message:str,**kwargs)-str: 发送用户消息并获取 AI 回复 Args: user_message: 用户输入 **kwargs: 额外参数如 temperature、max_tokens 等 Returns: AI 回复内容 # 追加用户消息到历史记录self.history.append({role:user,content:user_message})# 发起请求responseclient.chat.completions.create(modelself.model,messagesself.history,**kwargs)# 提取 AI 回复assistant_messageresponse.choices[0].message self.history.append({role:assistant,content:assistant_message.content})returnassistant_message.contentdefclear_history(self):清空对话历史保留 system 消息self.history[msgformsginself.historyifmsg[role]system]# 使用示例if__name____main__:botChatBot(modelgpt-4o,system_prompt你是一个 Python 编程专家擅长解释代码概念和调试问题。)print(bot.chat(Python 中列表和元组有什么区别))print(bot.chat(能举个例子说明什么时候该用元组吗))print(bot.chat(谢谢))代码解析ChatBot类封装了对话历史的管理逻辑self.history列表按顺序存储所有消息。每次调用chat()方法时先将用户消息追加到历史再发起请求最后将 AI 回复也追加到历史中。clear_history()方法允许清空对话历史但保留system消息方便重新开始对话而不丢失角色设定。4.4 流式输出Streaming流式输出基于 SSEServer-Sent Events协议逐块返回生成的内容显著提升用户体验特别适用于生成长文本的场景importosfromdotenvimportload_dotenvfromopenaiimportOpenAI load_dotenv()clientOpenAI(api_keyos.getenv(OPENAI_API_KEY))defstream_chat(user_message:str,model:strgpt-4o)-str: 流式聊天输出 Args: user_message: 用户输入 model: 模型名称 Returns: 完整的 AI 回复文本 full_responsestreamclient.chat.completions.create(modelmodel,messages[{role:user,content:user_message}],streamTrue,# 启用流式输出stream_options{include_usage:True}# 在最后一个 chunk 中包含 usage 信息)forchunkinstream:# 每个 chunk 的 delta 包含增量内容deltachunk.choices[0].deltaifdelta.contentisnotNone:print(delta.content,end,flushTrue)full_responsedelta.content# 最后一个 chunk 包含 usage 统计ifchunk.usage:print(f\n\nToken 消耗:{chunk.usage.total_tokens})returnfull_responseif__name____main__:stream_chat(写一篇关于人工智能发展历史的短文约300字)代码解析streamTrue启用流式输出模式返回一个可迭代的流对象。每个chunk对象的choices[0].delta.content包含本次生成的增量文本片段。delta.content可能为None如第一个 chunk 仅包含角色信息需要做判空处理。stream_options{include_usage: True}确保最后一个 chunk 返回 Token 使用统计。4.5 带重试机制的健壮调用网络波动、速率限制等问题可能导致 API 调用失败。实现指数退避重试机制可以显著提高调用的成功率importosimporttimefromdotenvimportload_dotenvfromopenaiimportOpenAI,RateLimitError,APIConnectionError,APIError load_dotenv()clientOpenAI(api_keyos.getenv(OPENAI_API_KEY))defrobust_chat(messages:list,model:strgpt-4o,max_retries:int3,base_delay:float1.0,**kwargs)-str: 带重试机制的聊天调用 Args: messages: 消息列表 model: 模型名称 max_retries: 最大重试次数 base_delay: 基础等待时间秒 **kwargs: 其他请求参数 Returns: AI 回复内容 Raises: Exception: 重试耗尽后抛出最后一次异常 last_exceptionNoneforattemptinrange(max_retries):try:responseclient.chat.completions.create(modelmodel,messagesmessages,**kwargs)returnresponse.choices[0].message.contentexceptRateLimitErrorase:# 速率限制错误HTTP 429last_exceptione wait_timebase_delay*(2**attempt)print(f速率限制{wait_time}秒后重试... (尝试{attempt1}/{max_retries}))time.sleep(wait_time)exceptAPIConnectionErrorase:# 网络连接错误last_exceptione wait_timebase_delay*(2**attempt)print(f连接错误{wait_time}秒后重试... (尝试{attempt1}/{max_retries}))time.sleep(wait_time)exceptAPIErrorase:# 服务器错误HTTP 5xx可重试客户端错误HTTP 4xx直接抛出ife.status_codeande.status_code500:last_exceptione wait_timebase_delay*(2**attempt)print(f服务器错误{wait_time}秒后重试... (尝试{attempt1}/{max_retries}))time.sleep(wait_time)else:raise# 客户端错误不重试直接抛出raiselast_exception# 使用示例if__name____main__:messages[{role:user,content:解释量子计算的基本原理}]try:resultrobust_chat(messages,max_retries3)print(result)exceptExceptionase:print(f调用失败:{e})代码解析针对RateLimitError速率限制和APIConnectionError连接错误进行捕获并执行重试。采用指数退避策略每次重试的等待时间为base_delay × 2^attempt即 1秒 → 2秒 → 4秒。对于服务器错误HTTP 5xx也进行重试但对于客户端错误如参数错误 HTTP 400直接抛出异常避免无效重试。4.6 函数调用Function Calling函数调用能力允许模型自主决定何时调用外部工具将自然语言转换为结构化的函数调用参数importosimportjsonfromdotenvimportload_dotenvfromopenaiimportOpenAI load_dotenv()clientOpenAI(api_keyos.getenv(OPENAI_API_KEY))# 定义外部函数defget_weather(city:str)-dict:获取指定城市的天气信息模拟函数weather_data{北京:{temperature:25,condition:晴,humidity:40},上海:{temperature:28,condition:多云,humidity:65},广州:{temperature:32,condition:雷阵雨,humidity:80},}returnweather_data.get(city,{error:f未找到{city}的天气信息})# 定义工具描述JSON Schematools[{type:function,function:{name:get_weather,description:获取指定城市的当前天气信息,parameters:{type:object,properties:{city:{type:string,description:城市名称如北京、上海}},required:[city]}}}]defchat_with_tools(user_message:str)-str: 支持函数调用的聊天 Args: user_message: 用户输入 Returns: AI 最终回复 messages[{role:user,content:user_message}]# 第一轮让模型决定是否调用工具responseclient.chat.completions.create(modelgpt-4o,messagesmessages,toolstools,tool_choiceauto# 让模型自主决定是否调用)assistant_messageresponse.choices[0].message messages.append(assistant_message)# 检查是否有工具调用ifassistant_message.tool_calls:fortool_callinassistant_message.tool_calls:function_nametool_call.function.name function_argsjson.loads(tool_call.function.arguments)# 执行对应的函数iffunction_nameget_weather:resultget_weather(**function_args)# 将函数结果返回给模型messages.append({role:tool,tool_call_id:tool_call.id,content:json.dumps(result,ensure_asciiFalse)})# 第二轮让模型根据工具返回结果生成最终回复final_responseclient.chat.completions.create(modelgpt-4o,messagesmessages)returnfinal_response.choices[0].message.contentreturnassistant_message.content# 使用示例if__name____main__:print(chat_with_tools(北京今天的天气怎么样))代码解析tools参数定义了外部函数的 JSON Schema 描述包括函数名、描述和参数结构。当模型判断需要调用工具时会在assistant_message.tool_calls中返回工具调用列表。开发者解析tool_call.function.argumentsJSON 字符串并执行对应的本地函数。将函数执行结果以role: tool的消息格式追加到messages中再次调用 API让模型基于工具返回结果生成自然语言回复。五、响应体结构解析5.1 非流式响应非流式响应返回一个完整的 JSON 对象核心结构如下{id:chatcmpl-abc123,object:chat.completion,created:1677652288,model:gpt-4o,choices:[{index:0,message:{role:assistant,content:你好有什么可以帮助你的,tool_calls:null},finish_reason:stop}],usage:{prompt_tokens:9,completion_tokens:12,total_tokens:21}}关键字段说明id请求的唯一标识符用于问题追踪。object固定为chat.completion。createdUnix 时间戳。model实际使用的模型名称。choices生成的结果列表。n参数大于 1 时会有多个候选。finish_reason结束原因常见值包括stop正常结束length达到 Token 长度限制tool_calls模型发起了工具调用content_filter内容被安全过滤器拦截usageToken 消耗统计包含输入 Tokenprompt_tokens、输出 Tokencompletion_tokens和总 Tokentotal_tokens。5.2 流式响应流式响应基于 SSE 协议每行以data:开头最后一个 chunk 以data: [DONE]结束data: {id:chatcmpl-123,object:chat.completion.chunk,created:1 ---