API 部署清单 | OpenAI API

内容目录	预期影响
使用 Responses API	质量、成本、延迟、可靠性
设置 `reasoning.effort`	质量、成本、延迟
设置 `text.verbosity`	质量、成本、延迟
设置助手 `phase` 参数	质量、成本
使用 `tool_search`	成本、延迟
利用内置工具	质量
利用压缩机制	成本
使用 `prompt_cache_key`	延迟、成本
使用 `reasoning.encrypted_content`	质量、延迟
使用 `background=True`	可恢复性
使用 WebSocket 模式	延迟

使用 Responses API

务必从 Responses API 开始。它是 OpenAI 的旗舰 API，也是访问最新模型行为、内置工具、有状态工作流和智能体功能的最佳途径。

设置 `reasoning.effort`

使用 reasoning.effort 来决定模型在回答前需要进行多深入的思考。

对于 gpt-5.5，支持的值包括 none、low、medium、high 和 xhigh。默认值为 medium。较低的投入程度速度更快，使用的推理 Token 更少。较高的投入程度给予模型更多时间进行规划、调试、合成和多步权衡。选择正确的值取决于任务本身，而非仅取决于模型。

当任务主要是提取、路由、分类或简单的重写时，使用 low。当模型需要诊断问题、比较选项、撰写计划或分析代码时，使用 medium 或 high。仅在评估结果显示额外延迟确实值得时，才考虑使用 xhigh。

针对具体任务调整推理投入

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import OpenAI from "openai";

const openai = new OpenAI();

const 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.",
].join("\n");

const response = await openai.responses.create({
  model: "gpt-5.5",
  reasoning: { effort: "high" },
  input: prompt,
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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-5.5",
    reasoning={"effort": "high"},
    input=prompt,
)

print(response.output_text)

设置 `text.verbosity`

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

在编码方面，medium 和 high 倾向于产生更长、更有组织且结构更清晰的输出。low 则使回答更精简。

设置较低的详细程度以获取紧凑输出

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import OpenAI from "openai";

const openai = new OpenAI();

const incident = [
  "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",
].join("\n");

const response = await openai.responses.create({
  model: "gpt-5.5",
  text: { verbosity: "low" },
  input: incident,
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    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 是对话历史中助手消息的标签。它向模型指示先前的助手消息是中间工作记录还是最终答案。使用 phase: "commentary" 表示进度更新、工具调用前的笔记以及其他中间消息。使用 phase: "final_answer" 表示已完成的响应。

助手可能会说

助手评论消息

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

这不是答案，而是进度提示。随后，助手可能会说

助手最终答案消息

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

这在长流程或工具密集型工作流中非常有用，因为助手在完成任务前会产生可见的进度更新。当你将历史记录传回模型时，请保留助手消息上的 phase 标签，以便模型能够区分哪些是进度更新，哪条是最终结果。

在后续请求中保留并回传 gpt-5.3-codex 及之后模型助手消息的 phase 标签。这有助于解决提前停止的问题，确保智能体持续运行直到得出最终答案。

使用 `tool_search`

无需将整个工具目录加载到每个请求中，添加 {"type": "tool_search"} 并将昂贵的工具定义标记为 defer_loading: true。模型可以在运行时加载其所需的子集。在请求开始时，模型仅看到搜索工具的名称和描述。如果模型决定需要某个延迟加载的工具，它会运行工具搜索，此时才会将该工具定义加载到上下文中，随后模型才会调用它。这不仅节省了 Token，还保留了缓存性能。

有两种模式：

托管工具搜索 (Hosted tool search) 是更简单的选项。当你已知哪些工具可能适用于请求时，请使用此模式。
客户端执行工具搜索 (Client-executed tool search) 适用于你的应用必须根据用户租户、项目、权限或内部注册表来决定可用工具的情况。

除非你的应用确实需要自行控制发现过程，否则请从托管工具搜索开始。

根据用户意图对工具进行分组。尽可能使用命名空间或 MCP 服务器。模型在几个清晰的组别中进行选择，远比从长长的函数列表中选择更容易。我们建议保持每个命名空间包含约 10 个函数，以获得最佳的 Token 效率和模型性能。

保持命名空间描述简短且具有区分度。将详细说明放在延迟加载的工具定义内部。避免创建一个包含所有东西的超大命名空间。

将托管工具搜索与延迟加载工具结合使用

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
import OpenAI from "openai";

const openai = new OpenAI();

const billingLookupInvoice = {
  type: "function",
  name: "billing.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,
};

const crmGetAccount = {
  type: "function",
  name: "crm.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,
};

const response = await openai.responses.create({
  model: "gpt-5.5",
  input:
    "Find the right billing tool and explain why invoice INV-1043 still " +
    "shows overdue after a payment yesterday.",
  tools: [
    { type: "tool_search" },
    billingLookupInvoice,
    crmGetAccount,
  ],
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
from openai import OpenAI

client = OpenAI()

billing_lookup_invoice = {
    "type": "function",
    "name": "billing.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_get_account = {
    "type": "function",
    "name": "crm.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-5.5",
    input=(
        "Find the right billing tool and explain why invoice INV-1043 still "
        "shows overdue after a payment yesterday."
    ),
    tools=[
        {"type": "tool_search"},
        billing_lookup_invoice,
        crm_get_account,
    ],
)

print(response.output_text)

利用内置工具

内置工具是 API 的原生功能。无需自行构建每个工具，你可以让模型直接使用已在 Responses API 中集成的工具。模型随后会自行决定何时使用它们。

OpenAI 不断增加原生工具，因此请优先选用符合你工作流的内置工具。仅在原生选项无法涵盖任务需求时，再构建自定义工具。当前内置工具及其相关选项包括：

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

优先选择内置工具还有一个关于模型质量的原因。内置工具属于我们后训练过程的“内分布”内容，这意味着模型是围绕这些工具的形态、行为和输出进行训练和评估的。使用内置工具，OpenAI 模型能够提供更好的工具选择、更简洁的执行，并比新工具减少出错概率。

利用压缩机制

压缩 (Compaction) 是一种上下文工程工具：它决定了模型在多轮对话中需要保留哪些信息。在长时间运行的智能体中，问题不仅仅是“我会触及上下文限制吗？”，而是旧消息、工具日志、重试记录和过时的细节会挤占模型所需的当前状态。

压缩为你提供了一种受控方式来减少上下文大小，同时保留后续回合所需的状态。在完成一个重要的里程碑（如调试阶段结束或缩小根本原因范围）后，你可以压缩之前的窗口并从压缩后的输出继续。这保持了模型的敏锐度，因为下一轮是围绕重要状态构建的，而不是围绕所有中间推理、失败的命令和过时的分支。

有两种利用压缩的方法：

让服务器处理：如果你使用 previous_response_id，请开启 context_management 并设置 compact_threshold。服务器将在对话过大时自动压缩它。你只需持续发送最新的用户消息。
自行处理：如果你自己管理完整的输入数组，调用 client.responses.compact()。它会返回一个较小的上下文窗口，直接在下一次 responses.create() 调用中使用该输出即可。

请勿编辑压缩后的输出。 这不是人类总结，而是帮助模型继续工作的机器状态。将其原样传递，然后添加下一条用户消息。

从压缩的响应状态继续

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import OpenAI from "openai";

const openai = new OpenAI();

// Full window collected from a long debugging session:
// user messages, assistant outputs, tool calls, and tool outputs.
const longWindow = sessionItems;

const compacted = await openai.responses.compact({
  model: "gpt-5.5",
  input: longWindow,
});

const nextResponse = await openai.responses.create({
  model: "gpt-5.5",
  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.",
    },
  ],
});

console.log(nextResponse.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
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-5.5",
    input=long_window,
)

next_response = client.responses.create(
    model="gpt-5.5",
    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)

使用 `prompt_cache_key`

提示词缓存 (Prompt caching) 可在请求重用相同的长前缀时自动降低延迟和成本。对于高容量工作流，请为共享相同稳定前缀的请求设置一致的 prompt_cache_key。

缓存键会与提示前缀哈希结合，有助于将相似请求路由到同一缓存，而无需更改模型输入。对于真正共享的前缀，请保持键的稳定性，并选择一个粒度，避免向单个前缀键对发送过多流量。如果单个前缀和 prompt_cache_key 组合每分钟超过 15 个请求，请求可能会溢出到其他机器，从而降低缓存效率。

将相关请求路由到同一提示词缓存

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import OpenAI from "openai";

const openai = new OpenAI();

const 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.",
].join("\n");

const response = await openai.responses.create({
  model: "gpt-5.5",
  prompt_cache_key: "tenant-acme-support-agent",
  instructions,
  input: "Summarize the current escalation for the on-call lead.",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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-5.5",
    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`

务必轮转推理项目（reasoning items）。这允许模型基于其先前的推理进行工作，从而帮助模型。如果你的零数据保留 (ZDR) 要求不允许存储响应数据，此时 reasoning.encrypted_content 就至关重要。reasoning.encrypted_content 为你提供了一种无状态切换方式。

将 reasoning.encrypted_content 添加到 include 中，响应输出中的推理项目将包含加密的推理内容，这些内容可以传回下一次请求。你的应用无需理解该值，只需将推理项目按原样保留并发送回下一轮，以便模型能使用它继续工作流。

在无状态轮次间传递加密推理

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import OpenAI from "openai";

const openai = new OpenAI();

const first = await openai.responses.create({
  model: "gpt-5.5",
  store: false,
  reasoning: { effort: "medium" },
  include: ["reasoning.encrypted_content"],
  input: "Investigate why invoice INV-1043 has mismatched tax totals.",
});

const second = await openai.responses.create({
  model: "gpt-5.5",
  store: false,
  reasoning: { effort: "medium" },
  include: ["reasoning.encrypted_content"],
  input: [
    ...first.output,
    {
      role: "user",
      content: "Now write the customer-facing explanation in plain English.",
    },
  ],
});

console.log(second.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
from openai import OpenAI

client = OpenAI()

first = client.responses.create(
    model="gpt-5.5",
    store=False,
    reasoning={"effort": "medium"},
    include=["reasoning.encrypted_content"],
    input="Investigate why invoice INV-1043 has mismatched tax totals.",
)

second = client.responses.create(
    model="gpt-5.5",
    store=False,
    reasoning={"effort": "medium"},
    include=["reasoning.encrypted_content"],
    input=[
        *first.output,
        {
            "role": "user",
            "content": "Now write the customer-facing explanation in plain English.",
        },
    ],
)

print(second.output_text)

使用 `background=True`

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

background=True 要求开启 store=True。

运行并轮询后台响应

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import OpenAI from "openai";

const openai = new OpenAI();

let job = await openai.responses.create({
  model: "gpt-5.5",
  background: true,
  store: true,
  input: "Analyze this large log bundle and cluster the primary failure modes.",
  tools: [
    {
      type: "code_interpreter",
      container: {
        type: "auto",
        file_ids: [logBundleFileId],
      },
    },
  ],
});

while (["queued", "in_progress"].includes(job.status)) {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  job = await openai.responses.retrieve(job.id);
}

console.log(job.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
from openai import OpenAI
import time

client = OpenAI()

job = client.responses.create(
    model="gpt-5.5",
    background=True,
    store=True,
    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 结合使用以获取进度事件，但第一个事件可能比普通请求花费更长时间。

从 UI 角度来看，后台模式表示：“这正在运行；这是状态；准备好后结果将在此显示。”

注意：background=True 与零数据保留不兼容。

使用 WebSocket 模式

WebSocket 模式专为长时间运行、工具调用密集的工作流而设计，你可以在该模式下保持持久连接，并通过仅发送新输入项加上 previous_response_id 来继续执行。对于包含 20 次或更多工具调用的任务，此方法端到端速度快约 40%。

工作原理：第一条消息看起来像正常的 Responses 请求：模型、指令、工具和用户输入。服务器会流式传输事件。如果模型请求工具，你的应用运行该工具。然后，无需发送新的 HTTP 请求，你在同一套接字上发送另一个 response.create 事件，并带上之前的 previous_response_id 和新项目。这就是延迟优化的来源。在普通 HTTP 中，每次后续操作都是新请求。在 WebSocket 模式下，连接保持打开，且最近的响应状态会在该连接的内存中保持“温热”。当下一轮从该响应继续时，后端需要做的设置工作更少。

如果你的工作流是一问一答，请保持使用 HTTP。如果你的工作流表现得像长时间运行的智能体，请尝试 WebSocket 模式。

单个 WebSocket 连接一次处理一个进行中的响应，因此并行工作需要多个连接。连接目前上限为 60 分钟。延续过程使用与 HTTP 模式相同的 previous_response_id 语义，并为最近的响应提供连接本地缓存。

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

默认的 Python 示例使用 websocket-client (pip install websocket-client)。JavaScript 示例使用 ws (npm install ws)。

启动 Responses API WebSocket 会话

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
import OpenAI from "openai";
import WebSocket from "ws";

const openai = new OpenAI();

const ws = new WebSocket("wss://api.openai.com/v1/responses", {
  headers: {
    Authorization: "Bearer " + openai.apiKey,
  },
});

ws.on("open", () => {
  ws.send(
    JSON.stringify({
      type: "response.create",
      model: "gpt-5.5",
      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: [testLogTool, codeSearchTool],
    })
  );
});

ws.on("message", (data) => {
  const firstEvent = JSON.parse(data.toString());
  console.log(firstEvent.type);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
from openai import OpenAI
from websocket import create_connection
import json

client = OpenAI()

ws = create_connection(
    "wss://api.openai.com/v1/responses",
    header=[f"Authorization: Bearer {client.api_key}"],
)

# Same request body you would send to client.responses.create(...).
ws.send(
    json.dumps(
        {
            "type": "response.create",
            "model": "gpt-5.5",
            "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 = json.loads(ws.recv())
print(first_event["type"])

最终总结

Responses API 是构建更智能、功能更强大的 OpenAI 应用程序的基石。其真正的优势在于，它使开发者能够从一次性提示词转向持久的、可使用工具的、感知上下文的工作流，从而适应任务的复杂性。遵循本指南，你将在实际部署中获得更高的性能。

推荐

开始使用

核心概念

Agents SDK

工具

运行与扩展

评估

实时与音频

模型优化

专用模型

上线

遗留 API

资源

开始使用

使用 Codex

配置

管理

自动化

学习

发布版本

核心概念

规划

构建

部署

转化类应用

指南

资源

指南

文件上传

API

衡量

广告主 API

API 参考

最近

主题

主题

贡献

分类

主题

项目

活动

使用 Responses API

设置 reasoning.effort

设置 text.verbosity

设置助手 phase 参数

使用 tool_search

利用内置工具

利用压缩机制

使用 prompt_cache_key

使用 reasoning.encrypted_content

使用 background=True

使用 WebSocket 模式

最终总结

设置 `reasoning.effort`

设置 `text.verbosity`

设置助手 `phase` 参数

使用 `tool_search`

使用 `prompt_cache_key`

使用 `reasoning.encrypted_content`

使用 `background=True`