OpenAI Responses API 使用指南：构建智能响应的强大引擎

在人工智能驱动的应用开发领域，OpenAI 的 Responses API（通常指其基于 gpt-3.5-turbo, gpt-4 等模型的 Chat Completions API）已成为构建对话式 AI、内容生成工具、智能助手和复杂自动化工作流的核心组件。本文将深入探讨如何高效、安全地利用这一强大工具，涵盖从基础概念到高级应用的全过程。

一、OpenAI Responses API 概述

OpenAI Responses API 的核心是 Chat Completions API。它允许开发者将一段或多段对话消息（包含用户输入和系统指令）发送给 OpenAI 的强大语言模型（如 gpt-3.5-turbo, gpt-4, gpt-4-turbo），并接收模型生成的、符合上下文和指令的文本响应。

核心优势：

1. 对话理解： 天然支持多轮对话上下文跟踪。
2. 指令跟随： 通过 system 角色消息精准控制模型行为。
3. 功能丰富： 支持流式传输、函数调用、JSON 模式、可复现性等。
4. 模型可选： 提供不同能力级别和成本效益的模型。
5. 持续进化： 模型和 API 功能不断更新优化。

二、核心概念与术语

1. 模型 (Model)： 执行任务的基础 AI 引擎。常用模型包括：

• gpt-4-turbo / gpt-4-turbo-2024-04-09： 当前主力模型，能力强大，支持 128K 上下文，知识更新至 2023年底。
• gpt-4： 之前的旗舰模型。
• gpt-3.5-turbo / gpt-3.5-turbo-0125： 性价比高，速度快，适合大多数通用任务，支持 16K 上下文。
• gpt-4o： 更新的多模态模型，响应速度更快。

2. 消息 (Messages)： API 请求的核心输入，是一个消息对象数组 (messages)。每条消息包含：

• role： 发送者角色。必须为 "system", "user" 或 "assistant"。
• content： 消息的实际文本内容。对于 assistant 角色，可以是 null（当使用函数调用时）。

3. 角色 (Role)：

• system： 设定助手的行为、个性或整体目标。通常放在消息列表开头。例如：{"role": "system", "content": "你是一位乐于助人的、专业的、简洁的翻译助手，只将用户输入的中文翻译成英文。"}
• user： 代表应用程序的最终用户或触发 API 调用的指令。例如：{"role": "user", "content": "将'你好，世界！'翻译成英文。"}
• assistant： 代表模型之前的回复。在连续对话中，需要包含这些历史消息以维持上下文。也可用于提供期望回复的示例（少样本学习）。

4. 响应 (Completion)： API 返回的输出结果，包含模型生成的文本消息（通常存储在 choices[0].message.content 中）以及其他元数据。
5. 令牌 (Token)： 文本在模型内部被切分的基本单位。一个英文单词通常对应 1 个或几个令牌，一个中文字符通常对应 1-2 个令牌。API 调用按输入和输出的总令牌数计费。上下文长度也受最大令牌数限制（如 gpt-4-turbo 支持 128, 000 令牌）。

三、API 使用基础：发起你的第一个请求

1. 前提条件

• OpenAI 账户： 访问 https://platform.openai.com/ 注册。
• API 密钥 (API Key)： 登录后，在平台右上角头像菜单 -> “View API Keys” 中创建并安全保管。
• 安装官方库 (推荐)：

pip install openai

2. Python 示例：简单对话

from openai import OpenAI



# 初始化客户端，传入你的 API Key (强烈建议从环境变量读取)

client = OpenAI(api_key='你的API密钥')  # 实际使用中替换为环境变量



def get_openai_response(prompt, model="gpt-3.5-turbo"):

    try:

        # 构建消息列表

        messages = [

            {"role": "system", "content": "你是一位乐于助人的助手。"},

            {"role": "user", "content": prompt}

        ]



        # 调用 Chat Completions API

        response = client.chat.completions.create(

            model=model,

            messages=messages,

            temperature=0.7,  # 控制输出随机性 (0.0-2.0)

            max_tokens=150,    # 限制生成的最大令牌数

        )



        # 提取并返回助手回复内容

        assistant_reply = response.choices[0].message.content

        return assistant_reply.strip()



    except Exception as e:

        print(f"调用API时出错: {e}")

        return None



# 使用示例

user_question = "解释一下量子计算的基本原理。"

answer = get_openai_response(user_question)

print(answer)

3. 关键请求参数详解

• model (必填): 指定使用的模型 ID (如 "gpt-4-turbo")。
• messages (必填): 包含对话历史的 role/content 字典列表。
• temperature (可选, 默认 1.0): 控制输出的随机性。值越低（接近 0），输出越确定、保守、一致；值越高（接近 2.0），输出越随机、有创造性、可能偏离主题。
• max_tokens (可选): 限制模型生成响应的最大令牌数。需小于模型的最大上下文限制（如 128K）。注意：输入令牌 + max_tokens <= 模型上限。设置过低可能导致回复被截断。
• top_p (可选, 默认 1.0): 另一种控制随机性的方法（核心采样）。通常建议只修改 temperature 或 top_p 中的一个。
• n (可选, 默认 1): 为同一输入生成多个回复选项。
• stop (可选): 指定一个字符串列表，当模型生成其中任何一个字符串时停止生成。
• presence_penalty / frequency_penalty (可选, 默认 0.0): 数值在 -2.0 到 2.0 之间。正值降低重复令牌的可能性，负值增加重复可能性。presence_penalty 惩罚新出现的令牌，frequency_penalty 惩罚已出现过的令牌。
• stream (可选, 默认 False): 是否启用流式响应 (下文详述)。
• seed (可选): 设置一个整数种子，配合其他参数（如 temperature=0）可以产生高度可复现的结果。

4. 处理响应

响应对象 (response) 包含丰富信息：

• response.id: 本次请求的唯一标识符。
• response.object: 对象类型 (chat.completion)。
• response.created: 请求创建的时间戳。
• response.model: 使用的模型 ID。
• response.choices: 最重要的部分，是一个列表（即使 n=1）。每个 choice 包含：

• choice.index: 选项索引。
• choice.message: 包含 role (assistant) 和 content (生成的文本) 的对象。
• choice.finish_reason: 停止生成的原因 (stop-正常结束, length-达到 max_tokens, content_filter-内容过滤, function_call-触发了函数调用)。
• response.usage: 本次请求消耗的令牌数 (prompt_tokens-输入, completion_tokens-输出, total_tokens-总计)。计费依据。

四、进阶功能与应用

1. 流式响应 (Streaming)

对于需要低延迟或实时显示的场景（如聊天应用），流式传输至关重要。它允许逐块接收响应，而不是等待整个响应生成完毕。

from openai import OpenAI

client = OpenAI(api_key='你的API密钥')



def stream_openai_response(prompt, model="gpt-3.5-turbo"):

    messages = [{"role": "user", "content": prompt}]



    # 关键：设置 stream=True

    stream = client.chat.completions.create(

        model=model,

        messages=messages,

        stream=True,  # 启用流式

        max_tokens=500,

    )



    collected_chunks = []

    print("助手: ", end="", flush=True)

    for chunk in stream:

        if chunk.choices[0].delta.content is not None:  # 检查是否有新内容

            content_chunk = chunk.choices[0].delta.content

            print(content_chunk, end="", flush=True)  # 实时打印

            collected_chunks.append(content_chunk)



    # 将收集的块合并成完整回复

    full_reply = "".join(collected_chunks)

    return full_reply



# 使用

stream_openai_response("写一个关于太空探索的短篇科幻故事开头。")

优点： 提升用户体验（打字机效果），减少感知延迟，可以在生成过长响应时提前中断。

2. 函数调用 (Function Calling)

让模型智能地决定何时需要调用你提供的函数，并结构化输出调用参数。这是构建复杂 Agent、信息检索、API 集成应用的基础。

from openai import OpenAI

import json



client = OpenAI(api_key='你的API密钥')



# 1. 定义你的函数 (工具)

def get_current_weather(location, unit="celsius"):

    """获取指定地点的当前天气信息。"""

    # 这里应该是调用真实天气API的代码

    # 模拟返回

    return json.dumps({"location": location, "temperature": "22", "unit": unit, "forecast": ["晴朗", "微风"]})



# 2. 描述函数 (工具) 供模型理解

tools = [

    {

        "type": "function",

        "function": {

            "name": "get_current_weather",

            "description": "获取指定地点的当前天气",

            "parameters": {

                "type": "object",

                "properties": {

                    "location": {

                        "type": "string",

                        "description": "城市名称，例如：北京，旧金山",

                    },

                    "unit": {

                        "type": "string",

                        "enum": ["celsius", "fahrenheit"],

                        "description": "温度单位",

                    },

                },

                "required": ["location"],

            },

        },

    }

]



# 3. 用户消息

messages = [{"role": "user", "content": "北京今天的天气怎么样？"}]



# 4. 第一次调用：模型判断是否需要调用函数

response = client.chat.completions.create(

    model="gpt-3.5-turbo-0125",  # 或 gpt-4-turbo

    messages=messages,

    tools=tools,

    tool_choice="auto",  # 让模型决定是否调用

)

response_message = response.choices[0].message

tool_calls = response_message.tool_calls



# 5. 检查是否有函数调用请求

if tool_calls:

    # 6. 遍历所有请求调用的函数 (可能多个)

    for tool_call in tool_calls:

        function_name = tool_call.function.name

        function_args = json.loads(tool_call.function.arguments)



        # 7. 执行实际函数

        if function_name == "get_current_weather":

            location = function_args.get("location")

            unit = function_args.get("unit", "celsius")  # 提供默认值

            weather_data = get_current_weather(location=location, unit=unit)



            # 8. 将函数执行结果作为新消息添加到对话历史

            messages.append(response_message)  # 先添加包含tool_calls的助手消息

            messages.append(

                {

                    "role": "tool",

                    "tool_call_id": tool_call.id,

                    "name": function_name,

                    "content": weather_data,  # 函数执行返回的结果

                }

            )



    # 9. 第二次调用：将函数执行结果发送给模型，让它生成面向用户的回复

    second_response = client.chat.completions.create(

        model="gpt-3.5-turbo-0125",

        messages=messages,

    )

    final_reply = second_response.choices[0].message.content

    print(final_reply)  # 例如: "北京今天的天气是晴朗，微风，气温22摄氏度。"

else:

    # 如果模型没有调用函数，直接使用第一次的回复

    print(response_message.content)

关键点：

• 使用 tools 参数提供函数定义列表。
• 模型在需要时会返回 tool_calls。
• 应用执行函数并将结果作为 role: tool 的消息传回。
• 模型根据函数结果生成最终用户回复。

3. JSON 模式 (JSON Mode)

强制模型以 有效的 JSON 对象 格式输出响应。极大简化了从非结构化文本到结构化数据的解析过程。

response = client.chat.completions.create(

    model="gpt-4-turbo",

    messages=[

        {"role": "system", "content": "你是一个产品信息提取器。用户会描述一个产品，你以JSON格式返回产品名称、品牌、主要特点和价格范围（如果提到）。"},

        {"role": "user", "content": "我刚买了一部新的iPhone 15 Pro，钛金属边框，6.1英寸屏幕，拍照效果太棒了，花了我999美元。"}

    ],

    response_format={"type": "json_object"},  # 关键：启用JSON模式

    temperature=0.0,

)



# 尝试解析JSON

import json

try:

    product_info = json.loads(response.choices[0].message.content)

    print(f"产品名称: {product_info['name']}")

    print(f"品牌: {product_info['brand']}")

    print(f"特点: {', '.join(product_info['features']}")

    print(f"价格范围: {product_info['price_range']}")

except json.JSONDecodeError as e:

    print("解析JSON失败:", e)

    print("原始响应:", response.choices[0].message.content)

重要提示：

• 启用 JSON 模式 (response_format={"type": "json_object"}) 时，系统消息 (system) 中必须明确指示模型输出 JSON。这是模型正常工作所必需的约定。
• 非常适用于数据提取、API 响应生成、配置生成等需要严格结构化的场景。

4. 上下文管理

模型对对话历史 (messages 列表) 有记忆，但受限于最大上下文长度。有效管理上下文是关键：

• 仅传递必要历史： 避免发送无关的早期对话。
• 摘要 (Summarization)： 当对话很长时，可以要求模型对之前的对话进行摘要，然后用摘要替代冗长的历史记录。
• 向量数据库： 对于超长文档或大量历史信息，结合 Embeddings API 和向量数据库进行检索，只将与当前问题最相关的片段放入上下文。
• 利用 system 指令： 在 system 消息中清晰设定长期目标、规则和约束，减少在 user/assistant 消息中重复。

五、最佳实践与注意事项

1. API 密钥安全：

• 永远不要 将 API 密钥硬编码在客户端代码（前端 JavaScript、移动 App）中。
• 将密钥存储在环境变量 (OPENAI_API_KEY) 或安全的服务器端配置管理系统中。
• 在 OpenAI 平台 设置使用额度限制和 IP 白名单。
• 定期轮换密钥。

2. 错误处理与重试：

from openai import OpenAI, APIError, RateLimitError

import time

import backoff  # 推荐使用 backoff 库简化退避逻辑



@backoff.on_exception(backoff.expo, (APIError, RateLimitError), max_tries=5)

def robust_api_call(...):

    ...

• 网络问题、API 限速 (429 Too Many Requests)、服务暂时不可用 (5xx) 是常见的。
• 使用指数退避策略进行重试。
• 捕获并处理特定异常（如 openai.APIError, openai.RateLimitError）。

3. 成本控制：

• 密切关注 usage.total_tokens。
• 在平台设置支出限额 (Billing -> Usage limits)。
• 根据需求选择合适模型 (gpt-3.5-turbo 通常比 gpt-4-turbo 便宜很多)。
• 优化提示词 (prompt engineering) 和上下文管理，减少不必要的令牌消耗。
• 使用 max_tokens 限制输出长度。

4. 内容安全与审核：

• OpenAI 内置内容安全过滤器（响应中的 finish_reason: content_filter 可能表示触发了过滤）。
• 重要： 在将模型输出展示给用户或执行操作前，务必进行你自己的内容安全审核和验证。不要完全信任模型的输出。检查输出是否包含有害、偏见、不准确、敏感信息或不符合你应用政策的内容。
• 考虑集成额外的内容审核 API 或服务。

5. 提示工程 (Prompt Engineering)：

• 清晰明确： system 消息要清晰定义助手的角色、任务范围和限制。
• 提供上下文： 在 user 消息中给出足够背景信息。
• 结构化指令： 使用步骤、示例、特定格式要求（如“用要点列出”、“用 Markdown 表格展示”）。
• 迭代优化： 根据测试结果不断调整提示词。使用 Playground (https://platform.openai.com/playground) 快速实验。
• 少样本学习 (Few-shot Learning)： 在 messages 中提供少量输入输出示例，指导模型学习特定任务格式或风格。

6. 理解模型局限：

• 知识截止： 模型知识可能不是最新的（尽管 gpt-4-turbo 更新到了 2023年底）。
• 幻觉 (Hallucination)： 模型可能生成看似合理但不真实的信息或引用不存在的来源。
• 偏见 (Bias)： 模型训练数据可能包含社会偏见，输出可能反映这些偏见。
• 数学与逻辑： 复杂计算或逻辑推理可能出错。
• 指令遵循： 模型有时会偏离指令或忽略部分约束。

7. 版本控制：

• 指定具体的模型版本（如 gpt-4-turbo-2024-04-09 而不是 gpt-4-turbo），避免因默认模型更新导致行为意外改变。

六、应用场景示例

1. 智能客服聊天机器人： 处理用户咨询、故障排除、提供产品信息。
2. 内容创作助手： 撰写文章、邮件、广告文案、社交媒体帖子、代码片段、诗歌故事。
3. 代码生成与解释： 根据描述生成代码、注释代码、解释代码逻辑、转换编程语言。
4. 语言翻译与润色： 多语言互译、文本风格改写、语法校对。
5. 教育辅导： 解释复杂概念、生成练习题、个性化学习辅导。
6. 数据分析与报告： 总结数据要点、生成报告草稿、解释图表含义（结合代码）。
7. 游戏 NPC 对话： 为游戏角色生成动态、自然的对话内容。
8. 个人智能助理： 集成日程管理、信息检索、邮件处理等功能的智能核心。

七、总结

OpenAI Responses API (Chat Completions API) 为开发者打开了利用尖端大语言模型能力的大门。通过理解其核心概念、掌握基础调用和进阶功能（流式传输、函数调用、JSON 模式），并遵循最佳实践（安全、成本、错误处理、内容审核、提示工程），你可以构建出强大、可靠且用户友好的 AI 驱动应用。持续关注 OpenAI 官方文档 (https://platform.openai.com/docs) 的更新，了解新模型发布、API 功能增强和最佳实践的变化，是保持你的应用处于领先地位的关键。开始探索和实践，释放 AI 的无限潜力吧！

重要资源：

• OpenAI 官方文档: https://platform.openai.com/docs
• OpenAI API 参考: https://platform.openai.com/docs/api-reference
• OpenAI Python 库 GitHub: https://github.com/openai/openai-python
• OpenAI Cookbook (示例): https://cookbook.openai.com/ (或 GitHub 仓库)