responses (Mgarlabx)

OpenAI响应API

本教程说明如何使用API responses OpenAI用于文本生成。虽然这个API是多模式的，也就是说，它也允许操作图像，但本教程仅涉及文本生成。

在编写本教程时，API responses 它是OpenAI最新的文本生成功能。它取代了先前的功能，如 chat.completion e assistant不应再用于新项目。此外，对于vibecoding应该谨慎，因为AI代理通常依赖于旧的文档，并经常建议 chat.completion已经被贬低了。

此外，本教程仅将说明如何在API中进行推断，而不是解释如何创建聊天机器人。要了解如何使用 OpenAI 功能创建聊天机器人，请参阅这里： .

基本调用

此 API 调用的基本语法（使用 OpenAI SDK）是：

response = client.responses.create(
    model="gpt-5-nano",
    input="Quem descobriu a América?",
)
print(response.output_text)

（ver example_01_basic.ipynb)

对象 response

“响应”是一个非常复杂的对象，具有多种属性。以下是一些例子：

print(response.id)
print(response.model)
print(response.temperature)
print(response.top_p)
print(response.status)

属性 output_text 包含推理的最终答案：

print(response.output_text)

然而，值得分析的一个有趣的属性是 output它包含了推理的结果。它是一个事件列表，包含LLM推理的所有阶段。看看如何探索它们：

for output in response.output:
    print(output.type)

以下是输出类型的示例列表：

• reasoning指示模型的推理阶段，始终以此类事件开始。
• file_search_call: 报告搜索调用。 “status”属性告诉您是否成功。
• function_call: 报告函数调用。 “status”属性告诉您是否成功。
• mcp_list_tools返回访问的 mcp 拥有的所有“工具”。
• mcp_call: 报告mcp调用。 “status”属性告诉您是否成功。
• message包含最终消息，总是最后一个事件。

因此，根据应用程序的不同，浏览输出可能会很有趣，而不是直接搜索 output_text.

流媒体

添加参数时 stream=True 在API调用中，响应将以块形式生成（“chunks”）。这在聊天机器人开发中可能很有趣，这样用户就不必等待一次性生成响应。随着它的生成，它可以逐渐阅读，从而改善您的机器人的体验。

（ver example_02_streaming.ipynb)

网页搜索

当使用API进行简单调用时，所有内容都将在LLM本身中搜索。然而，这些模型有时间限制，也就是说，它们的知识是有限的，直到它们被生成的日期。例如，O GPT-5 使用数据进行训练至2024年9月30日。在此日期之后发生的一切都不会在咨询中被告知。因此，当您添加下面的参数时，模板将执行 Web 搜索并扩展查询的上下文：

tools=[{
    "type": "web_search"
}]

（ver example_03_web_search.ipynb)

注意这个参数 tools 介绍API中使用的工具概念。还有其他工具选项，如下所示。请注意，此参数是一个列表，也就是说，可以同时使用多个工具。

文件搜索

您可以将文件作为信息源添加到上下文中。为此，首先需要创建一个“矢量存储”。这可以直接在 API 控制台中完成（参见 这里但也可以按计划进行。

创建矢量存储时，必须附加文件并复制存储 ID。此 ID 将在调用参数中显示 ：

tools=[{
    "type": "file_search",
    "vector_store_ids": []
}]

（ver example_04_file_search.ipynb)

请注意，该参数是一个列表，即通过访问多个存储可以传递多个 ID。此外，在同一个存储中可以有多个文件。

此功能会自动实现一项名为“检索增强生成”（RAG）的功能。

结构化输出

根据使用情况，以格式接收API调用的响应可能会很有趣 json而不是简单的文本。这在调用结果将用于某些工作流（“工作流”）的情况下非常有用，例如在自动化中使用。

为此，有必要在调用中告知输出布局 json有两种方法可以做到这一点：

1. 使用参数报告模式 text.

（ver example_11_struc_output_schema.ipynb)

1. 使用“Pydantic”库，参数 text_format在这种情况下，应使用该方法 parse API。

（ver example_12_struc_output_pydantic.ipynb)

函数调用

API做 responses 通过函数调用，帮助开发工作流程（“workflows”）。

重要函数不是由 LLM 执行的，只有当用户发送的消息符合工作流中预期的任何函数时才会返回。

就是这样运作的LLM 最初会分析用户发送的消息。如果它理解消息属于工作流中预期的某个函数，它会通知已识别的函数，并从查询中提取该函数所需的参数。否则，LLM将作为简单的呼叫进行处理，并返回它认为相关的消息。

但是，为了让 LLM 知道工作流中提供了哪些函数，它需要在 API 调用中传递这些函数的列表，包括所需的参数：

tools = [{
    "type": "function",
    "name": "get_capital",
    "description": "Retorna a capital de um país dado o nome do país.",
    "parameters": {
        "type": "object",
        "properties": {
            "country": {
                "type": "string",
                "description": "O nome do país cuja capital foi solicitada.",
            }
        },
        "required": ["country"],
        "additionalProperties": False,
    },
    "strict": True,
}]

（ver example_13_功能\_ call.ipynb)

请注意，这是一个列表，在这种情况下，只有一个函数被告知，但可能有更多。还要注意的是，“参数”遵循结构化输出的“模式”相同的模式。查看更多 这里.

参数 strict: True 确保模型完全遵循您定义的 JSON 架构。如果是 False模型尝试遵循该方案，但可能会有轻微的变化。

主控程序

MCP（模型上下文协议）是一种协议，允许LLM执行函数。也就是说，与前面提到的“函数调用”不同，其中LLM只识别函数，而不是执行函数，“mcp调用”允许识别和执行函数。

为此，必须传递mcp的参数：

tools=[{
    "type": "mcp",
    "server_label": "aloyoga",
    "server_url": "https://www.aloyoga.com/api/mcp",
    "require_approval": "never"
}]

（ver example_14_mcp.ipynb)

要了解更多关于mcps的用途，请参阅这里： .

.