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

一、OpenAI Responses API 概述

大语言模型（如 gpt-3.5-turbo, gpt-4, gpt-4-turbo），并接收模型生成的、符合上下文和指令的文本响应。

核心优势：

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

二、核心概念与术语

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

<a href="https://www.explinks.com/api/scd20250424805504953e78">gpt-4-turbo</a> / gpt-4-turbo-2024-04-09：当前主力模型，能力强大，支持 128K 上下文，知识更新至 2023年底。
<a href="https://www.explinks.com/api/scd20250424392004953e89">gpt-4</a>：之前的旗舰模型。
<a href="https://www.explinks.com/api/scd20250424168504953ea8">gpt-3.5-turbo</a> / gpt-3.5-turbo-0125：性价比高，速度快，适合大多数通用任务，支持 16K 上下文。
<a href="https://www.explinks.com/api/scd20250424923904953e55">gpt-4o</a>：更新的多模态模型，响应速度更快。

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

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

角色 (Role)：

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

响应 (Completion)： API 返回的输出结果，包含模型生成的文本消息（通常存储在 choices[0].message.content 中）以及其他元数据。
令牌 (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 示例：简单对话

使用示例

user_question = "解释一下量子计算的基本原理。"
answer = get_openai_response(user_question)
print(answer)

# 初始化客户端，传入你的 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](https://www.explinks.com/blog/ua-using-pycharm-to-call-api-guide)时出错: {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](https://prompts.explinks.com/)_tokens-输入, completion_tokens-输出, total_tokens-总计)。计费依据。

四、进阶功能与应用

1. 流式响应 (Streaming)

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

使用

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

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 集成应用的基础。

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

print(response_message.content)

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 消息中重复。

五、最佳实践与注意事项

API 密钥安全：

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

错误处理与重试：

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）。

成本控制：

密切关注 usage.total_tokens。
在平台设置支出限额 (Billing -> Usage limits)。
根据需求选择合适模型 (gpt-3.5-turbo 通常比 gpt-4-turbo 便宜很多)。
优化提示词 ([prompt engineering](https://www.explinks.com/blog/wx-a-comprehensive-guide-to-large-models-prompt-engineering-function-calling-rag-fine-tuning)) 和上下文管理，减少不必要的令牌消耗。
使用 max_tokens 限制输出长度。

内容安全与审核：

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

提示工程 (Prompt Engineering)：

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

理解模型局限：

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

版本控制：

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

六、应用场景示例

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

七、总结

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 仓库)

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

文章目录