OpenAI API 部署清单涵盖模型选择与关键配置

始终从\nResponses API 开始。它是 OpenAI 的旗舰\nAPI，也是使用最新模型行为、内置工具、\n有状态工作流和智能体功能的最佳途径。

针对你的工作负载评估 GPT-6 模型系列。使用 gpt-6-astra 获得\n最高能力，使用 gpt-6.1-sol 以低于 Astra 的成本完成复杂\n编码和专业工作，并使用 gpt-6-luna 处理\n高效、可重复的工作。选择在代表性任务上表现良好的模型，\n而不是将每个请求都路由到能力最强的模型。

迁移到 GPT-6 时，在支持的情况下，保留当前模型的工作负载角色和\n有效推理力度。使用 Responses API 进行工具推理。GPT-6 Astra 和 GPT-6.1 Sol\n需要通过 Responses 进行工具调用；GPT-6 Sol 和 GPT-6 Luna 仅在使用 reasoning_effort: "none" 时支持 Chat Completions 中的函数调用。\n当推理力度不是 none 时，请移除 temperature、top_p 和\ntop_logprobs；同时从 Chat Completions 请求中移除 logprobs，并从 Responses 的 include 数组中移除 message.output_text.logprobs。在选择模型或处理层级之前，请确认\n数据驻留资格。如需进行其他兼容性检查，请参阅\n模型迁移指南。更改提示或添加新功能之前，请运行有代表性的评测。比较任务成功率、延迟、输入、输出、推理和\n缓存写入 token，以及每个成功任务的成本。

使用 reasoning.effort 来决定模型在回答前应进行多少思考。

GPT-6 Astra、GPT-6.1 Sol、GPT-6 Sol 和 GPT-6 Luna 支持 low、medium、\nhigh、xhigh 和 max。GPT-6 Sol 和 GPT-6 Luna 还支持 none；GPT-6\nAstra 和 GPT-6.1 Sol 则不支持。较低的推理力度响应更快，使用的\n推理 token 更少。较高的推理力度会让模型有更多时间进行规划、\n调试、综合分析和多步骤权衡。

当任务主要涉及提取、路由、分类或常规改写时，使用 low。当模型需要诊断问题、比较选项、制定计划或推理分析代码时，使用 medium 或 high。只有当具有代表性的评估表明质量提升值得付出额外的延迟和成本时，才使用 xhigh 或 max。从 minimal 迁移，或从 none 迁移到 GPT-6 Astra 或 GPT-6.1 Sol 时，先从 low 开始并比较结果。其他情况下，保留当前实际生效的推理投入级别，并根据质量、延迟和成本目标测试调整效果。

对于最具挑战性且质量优先的工作负载，还应在相同的推理投入级别下，将 reasoning.mode: "pro" 与标准模式进行比较。推理模式与推理投入级别相互独立。Pro 模式可以在返回单个最终答案前投入更多模型计算来提高可靠性，但会增加延迟和 token 用量。

from openai import OpenAI

client = OpenAI()

prompt = """
Our CI job started failing after a dependency bump.

Error:
TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'

Identify the likeliest root cause and the smallest safe fix.
"""

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "xhigh", "mode": "pro"},
    input=prompt,
)

print(response.output_text)

对于处于标准单智能体模式的 GPT-6 模型，在下一条用户消息之前添加一个 configuration_update 输入项，即可在两次响应之间更改推理投入级别。保持请求级的 reasoning.effort 不变，以便原始提示词前缀仍可用于缓存。该更新对下一次响应生效，并持续生效，直到被另一项更新覆盖。配置更新不能与自动压缩或截断结合使用，且 /responses/compact 会拒绝包含此类更新的历史记录。要压缩历史记录，请包含一个 compaction_trigger 项，并在其后添加一项新的更新。

设置 text.verbosity

text.verbosity 是平衡简洁性与完整性的主要调节手段。当产品需要快速、精简的答案时，使用较低的详细程度；当响应需要更丰富的解释、更清晰的结构或完整的上下文时，使用较高的详细程度。较低的详细程度意味着更少的输出 token，因此模型生成的内容更少，返回输出也更快。

对于编程任务，medium 和 high 往往会生成更长、更有条理且结构更清晰的输出。low 则使答案更紧凑、更精简。

迁移时，检查“保持简洁”之类的宽泛指令是否仍然有帮助。优先使用 text.verbosity 控制默认的详细程度，再通过提示词指定所需的内容、结构和长度。

提示词也会影响质量、token 用量、成本和延迟。在设置详细程度时，也请查阅最新模型的提示词最佳实践，包括其中针对编程智能体的测试与验证指导。

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    text={"verbosity": "low"},
    input="""
    Summarize this incident for the next on-call engineer.
    - checkout latency spiked from 220 ms to 4.8 s
    - only us-east-1 was affected
    - rollback is complete
    - likely trigger: cache stampede after deploy
    """,
)

print(response.output_text)

phase 是对话历史中助手消息上的一个标签。它向模型表明，先前的助手消息是中间过程说明，还是最终答案。对于进度更新、工具调用前的说明及其他中间消息，使用 phase: "commentary"。对于已完成的响应，使用 phase: "final_answer"。

助手可能会这样说：

{
  "role": "assistant",
  "phase": "commentary",
  "content": "I'm checking the logs and comparing them to the last successful deploy."
}

这不是答案，而是一条进度说明。之后，助手可能会说：

{
  "role": "assistant",
  "phase": "final_answer",
  "content": "The deploy failed because the migration referenced a column that does not exist in production."
}

这对于运行时间较长或大量使用工具的工作流很有用，因为助手可能会在完成之前提供可见的进度更新。当你在针对 gpt-5.3-codex 及后续模型的后续请求中回传这些历史记录时，请在助手消息上保留并重新发送 phase，以便模型区分进度更新与最终结果。这有助于减少过早停止的情况，使智能体更有可能持续执行，直到得出最终答案。

不要在每次请求中加载完整的工具目录，而应使用 工具搜索：添加 {"type": "tool_search"}，并用 defer_loading: true 标记开销较大的工具定义。这样，模型就能在运行时加载所需的工具子集。 请求开始时，模型只能看到搜索工具的名称和描述。如果 模型判断需要某个延迟加载的工具，就会执行工具搜索，只有此时 这些延迟加载的工具定义才会被载入上下文。之后，模型才会 调用它们。这既能节省 token，又能保持缓存性能。

工具搜索有两种模式：

• 托管式工具搜索是更简单的选项。当你已经知道 本次请求可能有哪些工具可用时，就使用它。
• 客户端执行的工具搜索适用于需要由应用决定 哪些工具可用的情况，例如根据用户所属的租户、项目、权限或 内部注册表来决定。

优先使用托管式工具搜索，除非你的应用确实需要自行控制 工具发现过程。

按用户意图对工具进行分组。尽可能使用命名空间或 MCP 服务器。 与冗长的扁平函数列表相比，模型更容易在几个清晰的分组之间做出选择。 我们建议将每个命名空间中的函数数量控制在约 10 个以内， 以获得最佳的 token 使用效率和模型性能。

命名空间描述应简短且具有区分度。将详细 说明放在延迟加载的工具定义中。避免用一个庞大的 命名空间容纳所有工具。

from openai import OpenAI

client = OpenAI()

billing_namespace = {
    "type": "namespace",
    "name": "billing",
    "description": "Billing tools for invoices, payments, taxes, and credits.",
    "tools": [
        {
            "type": "function",
            "name": "lookup_invoice",
            "description": "Look up invoice state, taxes, credits, and payment attempts.",
            "parameters": {
                "type": "object",
                "properties": {
                    "invoice_id": {"type": "string"},
                },
                "required": ["invoice_id"],
                "additionalProperties": False,
            },
            "strict": True,
            "defer_loading": True,
        }
    ],
}

crm_namespace = {
    "type": "namespace",
    "name": "crm",
    "description": "CRM tools for account ownership, plans, health, and payment history.",
    "tools": [
        {
            "type": "function",
            "name": "get_account",
            "description": "Fetch account owner, plan, health, and payment history.",
            "parameters": {
                "type": "object",
                "properties": {
                    "account_id": {"type": "string"},
                },
                "required": ["account_id"],
                "additionalProperties": False,
            },
            "strict": True,
            "defer_loading": True,
        }
    ],
}

response = client.responses.create(
    model="gpt-6-astra",
    input=(
        "Find the right billing tool and explain why invoice INV-1043 still "
        "shows overdue after a payment yesterday."
    ),
    tools=[billing_namespace, crm_namespace, {"type": "tool_search"}],
)

print(response.output)

程序化工具调用 允许受支持的模型编写 JavaScript，在托管运行时中调用符合条件的工具，并精简 这些工具的中间结果。它适用于范围明确的处理阶段： 代码可以对大量工具结果进行筛选、连接、排序、去重、合并或检查， 然后向模型返回更精简的结构化结果。

添加 programmatic_tool_calling 工具，并逐一启用符合条件的工具。 对于仅通过程序调用的工具，使用 allowed_callers: ["programmatic"]；如果模型也可以直接调用 该工具，则使用 allowed_callers: ["direct", "programmatic"]。 当每次返回的结果都可能改变模型的下一步决策、某项操作需要批准，或最终答案必须保留 引用或原生制品时，应继续使用直接调用。请记录工具返回字段和错误处理行为， 以便模型无需先查看返回结果就能编写正确的程序。

你的工具循环必须处理 program 和 program_output 项，以及 由程序发出的 function_call 项及其对应的 function_call_output 项。 保留每个 call_id，并将函数调用的 caller 复制到其输出中，以便 服务恢复执行正确的程序。

同时测试 program_output 和助手的最终消息。即使程序 结果正确，最终答案仍可能不完整。请与使用直接工具调用的相同工作流比较， 评估任务成功率、所需证据、token 总量、延迟和成本。

多智能体允许受支持的模型（ 包括 GPT-6 模型）将独立的工作分支委派给子智能体，并 综合它们的结果。当你能将研究、分析或实现工作 拆分为具体、范围明确、使用独立上下文且可并行运行的任务时，就可以使用它。

在请求中将 multi_agent.enabled 设置为 true。对于 HTTP，使用测试版 Responses SDK，并使用 client.beta.responses，同时在 betas 中传入 responses_multi_agent=v1。 对于原始 HTTP 或 WebSocket 连接，发送 OpenAI-Beta: responses_multi_agent=v1。在多智能体功能处于测试阶段期间， 各项的数据结构可能会发生变化。

对于简短任务、每一步都依赖上一步的有序链，或会写入同一可变资源的工作，优先使用一个智能体。子智能体可能会增加 token 用量，因此请从 3 的默认 max_concurrent_subagents 值开始，并衡量端到端的质量、延迟和成本。对于工具密集型或长时间运行的多智能体工作流，WebSocket 模式可以减少继续执行的开销。

启用多智能体之前，请考虑其当前的限制：/responses/compact、reasoning.summary 和 max_tool_calls 不受支持。服务器会自动压缩根上下文和每个子智能体的上下文。

对于 GPT-6 模型，如果模型可以在应用程序执行工具时继续工作，请在函数或自定义工具上设置 async: true。尽早启动耗时较长的工具调用，让模型处理彼此独立的工作。应用程序仍会执行并跟踪调用，然后在后续的 Responses 请求中，使用原始的 call_id 返回结果。异步执行不适用于内置工具或程序化工具调用。在多智能体模式下，不要将异步工具与并行工具调用结合使用。完整流程请参阅 异步工具调用。

内置工具 是 API 的原生功能。与其自行构建每一种工具，不如让模型使用已能在 Responses API 中运行的工具。这样，模型便可以自行决定何时使用这些工具。

OpenAI 持续添加更多原生工具，因此如果内置工具适合你的工作流，请优先使用。原生选项无法满足任务需求时，再构建自定义工具。目前的内置工具及相关工具选项包括：

• 网页搜索：搜索网络以获取最新信息
• 文件搜索：搜索上传的文件或向量存储
• 代码解释器：运行 Python 进行分析、数学计算、绘图和文件处理
• Shell：在托管容器或你自己的运行环境中运行 Shell 命令
• 计算机使用：通过截图、点击、输入和滚动操作界面
• 图像生成：生成或编辑图像
• MCP/连接器：将模型连接到外部服务和工具
• 技能：附加可复用的指令包和工作流文件
• 应用补丁：进行结构化代码编辑

模型质量也是优先使用它们的另一个原因。内置工具属于我们后训练的分布内内容，这意味着模型的训练和评估都围绕这些工具的形态、行为和输出进行。使用内置工具时，OpenAI 模型在工具选择上更准确、执行更顺畅，失败也更少。

上下文压缩是一种上下文工程工具：它决定模型在多轮交互中保留哪些信息。在长时间运行的智能体中，问题不只是“我会不会达到上下文限制？”，旧消息、工具日志、重试和过时细节还会挤占模型所需的状态信息。

上下文压缩让你可以有控制地缩小上下文，同时保留后续轮次所需的状态。在完成一个重要阶段后，比如结束调试阶段或缩小根因范围，你可以压缩之前的上下文窗口，并从压缩后的输出继续。这能让模型保持敏锐，因为下一轮会围绕重要状态展开，而不是包含每一步的中间推理、失败的命令和过时的推理分支。

你可以通过两种方式使用上下文压缩：

• 交给服务器处理：如果你使用 previous_response_id，请通过 compact_threshold 启用 context_management。当对话过长时，服务器会自动压缩对话。你只需持续发送最新的用户消息。
• 自行处理：如果你自行管理完整的输入数组，请调用 client.responses.compact()。它会返回一个更小的上下文窗口。在下一次 responses.create() 调用中直接使用返回的输出。

不要编辑压缩后的输出。它不是供人阅读的摘要，而是帮助模型继续运行的机器状态。请将其原样传递下去，然后添加下一条用户消息。

from openai import OpenAI

client = OpenAI()

# Full window collected from a long debugging session:
# user messages, assistant outputs, tool calls, and tool outputs.
long_window = session_items

compacted = client.responses.compact(
    model="gpt-6-astra",
    input=long_window,
)

next_response = client.responses.create(
    model="gpt-6-astra",
    store=False,
    input=[
        *compacted.output,  # Use compact output as-is.
        {
            "type": "message",
            "role": "user",
            "content": (
                "We found the bad cache invalidation path. Write the fix plan "
                "and the verification checklist."
            ),
        },
    ],
)

print(next_response.output_text)

当请求重复使用相同的长前缀时，提示词缓存会自动降低延迟和成本。将稳定的指令、示例和参考资料放在前面，再接上动态的用户特定内容。保持工具定义及其顺序稳定，并在不改写先前上下文的情况下追加新的对话轮次。

GPT-5.6 引入了显式提示词缓存。隐式缓存仍是默认方式，但 GPT-5.6 模型及后续模型系列也支持显式缓存断点和请求级缓存策略。如果稳定前缀之后有变化的后缀，请在可复用内容的边界处添加显式 prompt_cache_breakpoint。只有在请求应仅使用你提供的断点、不使用任何隐式断点时，才将 prompt_cache_options.mode 设置为 explicit。更早的模型仍仅使用自动提示词缓存。

从 GPT-5.5 或更早版本迁移时，请将 prompt_cache_retention 替换为 prompt_cache_options.ttl: "30m"。更改缓存设置前，请参阅提示词缓存的模型差异。

在 GPT-5.6 模型及后续模型系列上，缓存写入的费用为未缓存输入 token 费率的 1.25×。记录 cached_tokens 和 cache_write_tokens，然后将写入量与后续缓存读取量进行比较，以衡量净成本并调整断点位置。

对于共享可复用前缀的请求，请使用稳定的 prompt_cache_key，以帮助将相关请求路由到同一缓存，并优化 GPT-5.6 之前模型的缓存命中率。对于请求繁忙的分组，请遵循将流量分散到更多键的指南。

在 GPT-5.6 及后续模型上，prompt_cache_key 是可选的：即使不使用它，也能获得最佳缓存命中率。你可以用它为不同客户、用户或工作空间分别进行缓存核算。这可以让每个分组的缓存 token 用量和计费更易于解释。为每个客户分配一个不同的键，并在该客户的相关请求中保持该键稳定。使用不同的键还有助于防止跨客户的缓存命中探测。请参阅使用键进行独立缓存核算。

from openai import OpenAI

client = OpenAI()

instructions = """
You are the support agent for Acme.
Follow the Acme support policy and escalation rubric.
Use the same tone, safety rules, and tool plan for each ticket.
"""

response = client.responses.create(
    model="gpt-6-astra",
    prompt_cache_key="tenant-acme-support-agent",
    instructions=instructions,
    input="Summarize the current escalation for the on-call lead.",
)

print(response.output_text)

使用 reasoning.encrypted_content

受支持的模型（包括 GPT-6 模型）可以跨调用保留推理。当任务的目标、假设和优先级保持稳定时，请使用 reasoning.context: "all_turns"。当先前的推理不再相关，并且可能使模型固守过时的方法时，请使用 current_turn。如果省略 reasoning.context 或将其设置为 auto，请检查响应中的 reasoning.context 字段，以确认实际生效的模式。

持久化推理仅在先前的推理项可用时才有效。对于已存储的响应，请使用 previous_response_id。如果你的零数据保留（ZDR）要求不允许存储响应数据，加密的推理内容可以实现无状态衔接。

响应输出中的推理项默认包含加密的推理内容。你可以通过每个推理项的 encrypted_content 属性访问加密的推理内容。你的应用无需理解该值。只需按原样保留每个推理项，并在下一轮发送回去，以便模型继续工作流。

from openai import OpenAI

client = OpenAI()

history = [
    {
        "role": "user",
        "content": "Investigate why invoice INV-1043 has mismatched tax totals.",
    }
]

first = client.responses.create(
    model="gpt-6-astra",
    store=False,
    reasoning={"effort": "medium", "context": "current_turn"},
    input=history,
)

history.extend(item.model_dump(exclude={"status"}) for item in first.output)
history.append(
    {
        "role": "user",
        "content": "Now write the customer-facing explanation in plain English.",
    }
)

second = client.responses.create(
    model="gpt-6-astra",
    store=False,
    reasoning={"effort": "medium", "context": "all_turns"},
    input=history,
)

print(second.output_text)

图像 detail 默认设置为 auto，其尺寸处理方式取决于模型。较大的图像可能会消耗更多输入 token 并增加延迟。请查看所列模型的尺寸表，并在部署前使用你选择的模型测量图像 token 用量和限制。

根据任务选择detail。调整图像尺寸；如果不需要精细的视觉细节，请使用 low；如果需要标准的高保真图像理解，请使用 high。对于支持的任务，如果额外细节有助于提升质量，可在大型、密集、对坐标敏感、OCR、定位或视觉检查任务中使用 original。部署前请测量最坏情况下的图像 token 数量和延迟。

如果你的应用面向个人终端用户，请在每个请求中发送稳定且保护隐私的safety_identifier。这有助于 OpenAI 检测滥用行为，并为你的团队提供稳定的方式来追踪违反政策的行为。它还能降低某位用户的滥用行为影响整个组织访问权限的可能性。

对用户的用户名或电子邮件地址进行哈希处理，而不是发送可识别个人身份的信息。对于未登录的使用场景，请使用稳定的会话 ID。

对于 GPT-6 Astra 代理工作流，请规划目标偏离监测。如果请求返回 403 和 misalignment_policy_violation，请停止为该对话分派操作，不要自动重试被阻止的工作流。还要处理流式传输期间发生的错误，并检查可能已经执行的操作。如果团队需要项目提醒，请订阅 safety.alert.created；webhook 不能替代请求错误处理。请查看指南，了解哪些 Responses 请求可以自动停止。

在选择恢复操作之前，请检查 HTTP 状态和 error.code。429 搭配 slow_down 表示请求速率增长过快：如果存在 Retry-After，请遵循该值，降低流量，然后逐步提高。503 搭配 server_is_overloaded 表示请求的模型暂时过载：如果存在 Retry-After，请遵循该值，然后重试。如果缺少该标头，请使用带随机抖动的指数退避来延长重试间隔，并限制重试次数。计费、支出和配额错误需要先采取措施再重试；不要将每个 429 都视为临时速率限制。请参阅速率限制和错误代码。

对于可能需要较长时间的请求，请使用background=True。API 不会让客户端连接一直保持打开状态，而是启动一个作业并返回一个 ID。你的应用可以轮询该作业，直到它完成、失败或被取消。大型分析、长时间运行的工具调用，或需要状态和重试行为的工作都适合使用它。

# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI
import time

client = OpenAI()
log_bundle_file_id = "file_123"

job = client.responses.create(
    model="gpt-6-astra",
    background=True,
    store=False,
    input="Analyze this large log bundle and cluster the primary failure modes.",
    tools=[
        {
            "type": "code_interpreter",
            "container": {
                "type": "auto",
                "file_ids": [log_bundle_file_id],
            },
        }
    ],
)

while job.status in {"queued", "in_progress"}:
    time.sleep(2)
    job = client.responses.retrieve(job.id)

print(job.output_text)

你可以将其与 stream=True 结合使用来接收进度事件，但第一个事件可能比普通请求耗时更长。

从界面角度来看，后台模式表示：“正在运行；这是当前状态；结果准备好后会显示在这里。”

WebSocket 模式适用于长时间运行、工具调用密集的工作流：你可以保持持久连接打开，并通过仅发送新的输入项以及 previous_response_id 来继续操作。对于包含 20 次或更多工具调用的工作流，我们观察到端到端执行速度最高可提升约 40%。

工作原理：第一条消息看起来像普通的 Responses 请求：包含 model、instructions、tools 和用户输入。服务器会流式返回事件。如果模型请求调用工具，应用就运行该工具。然后，无需发送新的 response.create 事件，而是在同一个 socket 上发送另一个事件，并附上之前的 previous_response_id 和新条目。延迟优势就来自这里。在普通 HTTP 中，每次后续操作都是一个全新的请求。在 WebSocket 模式下，连接会保持打开，最近一次响应的状态也会保留在该连接的内存中。当下一轮从该响应继续时，服务就无需进行那么多准备工作。

如果你的工作流是一个请求、一个回答，那么继续使用 HTTP。如果你的工作流像一个长期运行的智能体，不妨试试 WebSocket 模式。

在同一个连接上并行处理多个对话时，请使用不同的 stream_id 值；通过 stream_id 路由交错事件。一个连接最多支持 16 个活动响应，而同一数据流上的请求会按顺序运行。连接最长可持续 60 分钟。继续操作使用与 HTTP 模式相同的 previous_response_id 语义，并在连接本地缓存每个数据流的最新响应。

注意：WebSocket 模式兼容 ZDR，因为你的数据不会存储到磁盘，只会存储在内存中。

Python 示例使用 pip install "openai[realtime]>=3.8.0"。\nJavaScript 示例使用 npm install openai@^7.10.0 ws。\nRuby 示例使用 gem install openai async-websocket。

对于 Go，请运行 go get github.com/openai/openai-go/v3@v3.73.0。\n对于 Java，请添加 Maven 依赖 com.openai:openai-java:4.79.0。\n这些 Go 和 Java SDK 版本原生支持 Responses WebSocket。

from openai import OpenAI

client = OpenAI()

with client.responses.connect() as connection:
    # Use the same typed parameters as client.responses.create(...).
    connection.response.create(
        model="gpt-6-astra",
        store=False,
        input=[
            {
                "type": "message",
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Find the flaky test in this run, call the tools "
                            "you need, and keep going until you can explain "
                            "the root cause."
                        ),
                    }
                ],
            }
        ],
        tools=[test_log_tool, code_search_tool],
    )
    first_event = connection.recv()
    print(first_event.type)

如果用户可能会在 GPT-6 模型工作期间添加要求，请使用 WebSocket 连接到 Responses API。发送 response.steer，在 previous_response_id 中包含活动响应 ID，并附上新的用户输入。继续读取事件以获取后续响应；response.steer.accepted 表示更新已排队。\n引导不会更改已发送到应用的输出，也不会撤销已经启动的工具。请参阅回合中途引导，了解事件流和工具结果处理。

Responses API 是构建更智能、更强大的 OpenAI 应用的基础。它的真正优势在于，开发者可以从一次性提示转向持久化、可使用工具且能感知上下文的工作流，并根据任务的复杂程度进行调整。请参阅本指南，了解如何在真实部署中实现更高性能。