OpenAI API(2) OpenAI Responses API使用

发布于：2025-07-23 ⋅ 阅读:(20) ⋅ 点赞:(0)

1. 简介

Responses API 是 OpenAI 为智能代理（Agents）提供的全新 API 基础构件，它结合了 Chat
Completions API 的简洁性 与 Assistants API 的内置工具能力，使得代理能够更智能地执行任务。
📌 核心特点
✅ 简洁易用：继承了 Chat Completions API 的易用性。
✅ 增强功能：支持内置工具（Tools），如函数调用（Function Calling）、Web 搜索、文件搜
索、计算机控制等。
✅ 适用于代理（Agents）：可用于构建智能化任务执行系统。

官网地址 openai官网地址

2.安装和参数

2.1 安装

import openai
from openai import OpenAI

2.2 responses API参数列表

参数名 类型 必填/可选 默认值 说明
model string 必填 无 指定要使用的模型 ID，例如 gpt-4o 或 gpt-4o-mini。
store boolean or null 可选 false 是否存储本次对话的输出，供模型精炼或评估产品使用。
metadata object or null 可选 null 开发者自定义的标签和值，用于过滤仪表盘中的补全结果。
frequency_penalty number or null 可选 0 数值在 -2.0 到 2.0 之间，正值减少重复生成内容的可能性。
logit_bias map 可选 null 调整某些特定 tokens 出现的可能性，值在 -100 到 100 之间。
logprobs boolean or null 可选 false 是否返回生成的每个 token 的对数概率。
top_logprobs integer or null 可选 null 指定返回最有可能出现的前几个 tokens 及其概率，需开启 logprobs。
max_completion_tokens integer or null 可选 null 指定模型生成的最大 token 数，包括可见文本和推理 tokens。
n integer or null 可选 1 每个输入生成的对话补全选项数量，值越大，生成的回复越多。
presence_penalty number or null 可选 0 数值在 -2.0 到 2.0 之间，正值鼓励生成新的主题和内容。
response_format object 可选 null 指定生成结果的格式，可以设置为 json_schema 以确保结构化输出，或 json_object 用于 JSON 格式。
seed integer or null 可选 null 保持生成的一致性，重复相同请求将尽量生成相同的结果。
service_tier string or null 可选 auto 指定服务延迟等级，适用于付费订阅用户，默认为 auto。
stop string / array / null 可选 null 最多指定 4 个序列，API 遇到这些序列时会停止生成进一步的 tokens。
stream boolean or null 可选 false 是否启用流式响应，若启用，生成的 tokens 将逐步返回。
stream_options object or null 可选 null 流式响应的选项，仅当 stream 为 true 时设置。
temperature number or null 可选 1 控制生成输出的随机性，值越高生成的文本越随机。建议调整此值或 top_p，而不是同时调整。
top_p number or null 可选 1 使用核采样方法，选择最有可能的 tokens，总概率达到 top_p 百分比。建议与 temperature 二选一。
tools array 可选 null 模型可以调用的工具列表，目前仅支持函数调用。
user string 可选 null 表示最终用户的唯一标识符，用于监控和检测滥用行为。

2.3 responses API参数解释：

  1. 模型和输出相关参数

    • model 是必填参数，决定使用哪个模型（如 gpt-4o 或 gpt-4o-mini）。
    • store 控制是否存储生成的对话结果，便于后续模型训练或评估。
    • metadata 用于添加开发者自定义的标签，便于在仪表盘中过滤补全结果。
    • max_completion_tokens 和 n 控制生成内容的数量和长度，帮助管理生成成本。

  2. 生成行为控制：

    • frequency_penalty 和 presence_penalty 都用于影响生成结果的内容重复度和新颖性。
    • logit_bias 是用于调整特定 token 出现概率的高级控制工具。
    • temperature 和 top_p 通过不同的方式控制生成结果的随机性，建议选其一进行调整。

  3. 高级功能：

    • logprobs 和 top_logprobs 用于返回每个 token 的概率信息，适合对模型输出进行更细粒度分析。
    • stream 启用后会实时返回生成的结果，适用于需要逐步展示内容的场景。
    • tools 允许模型调用外部工具（如函数），适用于扩展模型的功能。

  4. 服务和用户相关参数：

    • service_tier 控制服务的延迟和稳定性，适合高性能要求的付费用户。
    • user 用于标识最终用户，有助于监控使用行为，防止滥用。

3.使用示例

3.1文本生成

# 实例化客户端
client = OpenAI(api_key=openai_api_key, 
                base_url=base_url)
response = client.responses.create(
    model="gpt-4o",
    input="你好，好久不见，请介绍下你自己！"
)

# 输出结果
response.output_text

相应结构

[
    {
        "id": "msg_67b73f697ba4819183a15cc17d011509",
        "type": "message",
        "role": "assistant",
        "content": [
            {
                "type": "output_text",
                "text": "你好！我是一款先进的人工智能助手，可以帮助回答问题、提供建议和协助你处理各种信息。我很高兴能够与你交流！如果你有什么问题或者需要帮助，随时告诉我哦。",
                "annotations": []
            }
        ]
    }
]

📌 重要说明：

  • output 可能包含多个结果，在多轮对话或批量生成时尤其明显。
  • 一些 SDK 提供 output_text 属性，可以直接获取所有文本输出，方便访问文本数据。
  • 除了纯文本，模型还可以返回 JSON 结构化数据（称为 Structured Outputs）。

3.2 消息角色与指令控制

1.指令

我们可以使用不同的方式给模型提供指令：

  1. 使用 instructions 参数 提供全局行为指令，如语气、目标等。（权重最高）
  2. 使用 input 数组，指定不同角色的消息。
response = client.responses.create(
    model="gpt-4o",
    instructions="用海盗的口吻说话。",
    input="JavaScript 中的分号是可选的吗？",
)

print(response.output_text)
2.多角色设置

此外，也可以使用 input 数组还可以指定多种角色，例如使用developer角色，developer 角色类似于 系统设定，用户输入 user 角色的内容，最终 模型按 developer 设定风格回答。

response = client.responses.create(
    model="gpt-4o",
    input=[
        {
            "role": "developer",
            "content": "用海盗的口吻说话。"
        },
        {
            "role": "user",
            "content": "JavaScript 中的分号是可选的吗？"
        }
    ]
)
3.消息角色的优先级
角色 优先级 说明
developer 最高 由开发者提供的指令，优先级最高，类似 system。
user 次高 由最终用户提供的输入，次于 developer。
assistant 最低 由模型生成的响应。

3.3 Web Search（网页搜索）功能实现

📌 使用 Web搜索：

response = client.responses.create(
    model="gpt-4o",
    tools=[{"type": "web_search_preview"}],  # 启用 Web 搜索工具
    input="今天有什么正面的新闻吗？"
)

print(response.output_text)
  • 该 API 请求会调用 web_search_preview，允许模型在回答前搜索最新的新闻。
  • 但模型可以自行决定是否使用该工具。

📌 强制使用 Web 搜索：
如果希望确保模型一定使用 Web 搜索（避免它仅使用内部知识回答），可以设置 tool_choice 参数：

tool_choice={"type": "web_search_preview"}
  • 让 Web 搜索始终执行，而不是让模型决定是否使用搜索工具。
  • 提升一致性，但可能会增加查询时间。

输出结果

[
  {
    "type": "web_search_call",
    "id": "ws_67c9fa0502748190b7dd390736892e100be649c1a5ff9609",
    "status": "completed"
  },
  {
    "id": "msg_67c9fa077e288190af08fdffda2e34f20be649c1a5ff9609",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "On March 6, 2025, several news...",
        "annotations": [
          {
            "type": "url_citation",
            "start_index": 2606,
            "end_index": 2758,
            "url": "https://...",
            "title": "Title..."
          }
        ]
      }
    ]
  }
]

📌 指定位置搜索:

Web 搜索可以根据用户的位置优化搜索结果。你可以指定：

  • country（国家）：两字母 ISO 代码，如 "US"（美国）、"GB"（英国）。
  • city（城市）：如 "London"（伦敦）。
  • region（地区）：如 "California"（加州）。
  • timezone（时区）：如 "America/Chicago"（芝加哥时间）。
response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "web_search_preview",
        "user_location": {
            "type": "approximate",
            "country": "CN",
            "city": "Beijing",
            "region": "Beijing",
        }
    }],
    input="北京三里屯附近最好吃的餐厅有哪些?",
)

3.4 文件搜索（File Search）

OpenAI Agents SDK 支持文件搜索功能，允许模型在生成回答之前检索用户上传的文件中的相关信息。

1. 文件搜索功能概述

file_search 工具可以让模型在已上传的文件知识库（vector stores）中进行语义搜索和关键词搜索，从而扩展模型的内在知识。

📌 特点：

  • 托管工具（由 OpenAI 负责管理，无需用户自行实现搜索逻辑）。
  • 自动调用：模型决定何时使用该工具进行检索。
  • 向量存储支持：通过创建向量存储并上传文件来增强模型的知识。

📌 相关概念：

  • Vector Store（向量存储）：一个可存储文本向量化数据的数据库，支持语义检索。
  • Semantic Search（语义搜索）：利用向量表示进行相似性匹配，而不仅仅是关键字匹配。

📌 学习更多：可参考 OpenAI Retrieval Guide（检索指南）。

2. 使用文件搜索

在使用文件搜索前，用户需要：

  1. 创建向量存储（Vector Store）。
  2. 上传文件到向量存储。
  3. 在 API 调用中启用 file_search，并指定向量存储 ID。

📌 ⚠️ 限制：

  • 目前 一次搜索仅支持一个向量存储（vector_store_ids 只能包含一个 ID）。
3.启用文件检索
response = client.responses.create(
    model="gpt-4o-mini",
    input="你知道OpenAI的responses API是什么么？",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["vs_67d41ac1c3e08191ad00db04996b631f"]  # 指定要搜索的向量存储
    }]
)

print(response.output_text)
4. API 响应结构

当 file_search 工具被调用后，API 响应将包含两部分：

  1. file_search_call：存储搜索请求的 ID 和查询内容。
  2. message：存储模型的回答，并包含文件引用信息（file citations）。

📌 解析：

  • file_search_call：存储搜索请求的 ID、状态和查询内容。
  • message：
    • output_text：模型生成的文本。
    • annotations：提供引用文件信息，包括 file_id 和 filename，标明信息的来源。
response = client.responses.create(
    model="gpt-4o-mini",
    input="你知道OpenAI的responses API是什么么？",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["vs_67d41ac1c3e08191ad00db04996b631f"]
    }],
    include=["output[*].file_search_call.search_results"]
)

📌 作用：

  • include 参数指定要包含 search_results，以便直接获取搜索的原始数据。

3.5 计算机使用（Computer Use）

OpenAI 的 计算机使用代理（Computer-Using Agent, CUA） 允许模型模拟人在计算机上操作，例如点击、输入、滚动等，从而执行自动化任务。

image-20250312090619991
1. 概述

Computer Use（计算机使用） 是 OpenAI 提供的一种增强版 CUA（计算机使用代理），基于 computer-use-preview 模型，结合：

  • GPT-4o 的视觉能力（识别屏幕截图）
  • 高级推理能力（模拟计算机界面交互）

📌 特点：

  • 允许模型执行计算机操作（如点击、输入文本、滚动页面）。
  • 通过截图感知界面变化，并决定下一步操作。
  • 可用于网页浏览、数据输入、在线购物、表单填写等任务。

📌 当前状态：

  • Beta 版，可能存在漏洞或错误。
  • 不适用于高安全性任务（如银行交易、个人账户管理）。
  • 必须符合 OpenAI 的使用政策。

📌 适用 API：

  • ✅ Responses API
  • ❌ 不适用于 Chat Completions
from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="computer-use-preview",
    tools=[{
        "type": "computer_use_preview",
        "display_width": 1024,
        "display_height": 768,
        "environment": "browser" # other possible values: "mac", "windows", "ubuntu"
    }],
    input=[
        {
            "role": "user",
            "content": "Check the latest OpenAI news on bing.com."
        }
        # Optional: include a screenshot of the initial state of the environment
        # {
        #     type: "input_image",
        #     image_url: f"data:image/png;base64,{screenshot_base64}"
        # }
    ],
    reasoning={
        "generate_summary": "concise",
    },
    truncation="auto"
)

print(response.output)

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布