For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

建议

选择模型

文本与代码

提示词

推理

图像与视频

实时交互与音频

专用模型

API Dashboard
试用 ChatGPT

推理模型

了解推理模型的工作原理及其有效用法。

推理模型 在生成响应之前会使用内部推理 Token。这有助于模型制定计划、有效使用工具、考察不同方案、应对含糊不清的信息，并解决更复杂的多步骤任务。推理模型尤其擅长解决复杂问题、编程、科学推理和多步骤智能体工作流。对于我们的轻量级编程智能体 Codex CLI，推理模型也是最佳选择。

对于大多数推理工作负载，请先使用 gpt-6-astra。如需降低成本，可以考虑 gpt-5.6-terra；如需最低的成本和延迟，可以选择 gpt-5.6-luna。如果您使用的是 GPT-5.6 模型，请参阅推理模式，了解其 pro 选项。

推理模型搭配 Responses API 使用时效果更好。虽然仍然支持 Chat Completions API， 但使用 Responses 可以提升模型的智能水平 和性能。

开始使用推理

调用 Responses API，并指定推理模型和推理强度：

在 Responses API 中使用推理模型
from openai import OpenAI

client = OpenAI()

prompt = """
Write a bash script that takes a matrix represented as a string with
format '[1,2],[3,4],[5,6]' and prints the transpose in the same format.
"""

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "low"},
    input=[{"role": "user", "content": prompt}],
)

print(response.output_text)

推理强度

reasoning.effort 参数用于指导模型在执行任务时投入多少思考。

支持的值因模型而异，可能包括 none、minimal、low、medium、high、xhigh 和 max。较低的推理强度更注重速度和减少 Token 用量，而较高的推理强度会让模型思考得更充分，从而提供质量更高的响应。在不同推理强度下，模型也会自适应地进行推理：对于简单任务使用较少的 Token，对于复杂任务则投入更多思考。

GPT-6 Astra 不支持 none 推理强度。 将 reasoning.effort（Responses）或 reasoning_effort（Chat Completions）设为 none 会返回 HTTP 400。

请使用 Responses API 进行函数调用。 Chat Completions 不支持通过 GPT-6 Astra 进行函数调用。

默认值也因模型而异，并非统一设置。gpt-5.5 的默认推理强度为 medium。要让 gpt-5.5 全面兼顾质量、可靠性和性能，这是最合适的起点。

推理强度最适合
none对延迟要求极高，且无法从推理或多步链式工具调用中获益的任务。对于使用 gpt-5.5 的延迟敏感型使用场景，我们建议先尝试 low，再根据需要切换到 none。

常见使用场景包括语音、快速信息检索和分类。
low以小幅增加延迟为代价进行高效推理。非常适合需要使用工具、规划、搜索或多步骤决策，同时注重速度和成本优化的使用场景。

常见使用场景包括数据分析、起草文稿、以执行为主的编程，以及客户支持或聊天助手工作流。
medium适用于重视质量和可靠性，且涉及规划、复杂推理和判断的任务。这是大多数工作负载的默认配置，在延迟、性能和成本的帕累托曲线上处于较为均衡的位置。

常见使用场景包括智能体编程、研究、处理电子表格和幻灯片，以及委派需要长时间持续执行的工作。
high复杂推理、复杂调试、深入规划，以及质量和智能水平比延迟更重要的高价值任务。推荐用于复杂工作流和智能体任务。

常见使用场景包括智能体编程、长期研究和知识工作。请根据任务的复杂程度，同时评估 medium 和 high。
xhigh深度研究、异步工作流和需要长时间运行的智能体任务。仅当您的评测表明其带来的明显收益足以抵偿额外的延迟和成本时，才应使用。

常见使用场景包括安全审查和代码审查、提升企业生产力、更深入的研究任务，以及具有挑战性的编程工作流。
max为您最复杂的任务提供最高强度的推理。如果您目前使用 xhigh，请评估 max 是否能带来更好的表现。

对于延迟敏感型应用，若要缩短首个可见 Token 的等待时间，请要求模型先生成一段简短的开场说明，再继续深入推理。

部分模型仅支持其中一些值，因此在选择设置之前，请先查看相应的模型页面。

推理模式

GPT-5.6 模型在 Responses API 中支持 standard 和 pro 推理模式，默认为 standard。对于需要模型投入更多计算，且能容忍更高延迟和 Token 用量的复杂任务，请将 reasoning.mode 设为 pro。

推理模式和推理强度相互独立。模式用于选择标准执行方式或 pro 执行方式，而 reasoning.effort 控制模型在该模式下投入的推理量。如果省略 reasoning.effort，GPT-5.6 在两种模式下均默认为 medium。

使用 pro 推理模式
curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6",
    "reasoning": {
      "mode": "pro",
      "effort": "medium"
    },
    "input": "Review this database migration plan and identify potential failure modes."
  }'

Pro 模式会汇总模型为生成最终答案所投入的计算，并按照所选模型的标准 Token 费率对相应的 Token 计费。Pro 模式比标准模式投入更多模型计算，因此会增加 Token 用量和成本。现有 Pro 模型 ID 的行为和定价保持不变。

推理的工作原理

推理模型在输入和输出 Token 之外，还引入了 推理 Token 。模型使用这些推理 Token 进行“思考”，拆解提示，并考虑多种生成响应的方法。我们的 gpt-5.5 和 gpt-5.4 等推理模型支持交错思考，即模型可以在思考之前和思考间隙生成可见的输出 Token，也可以在工具调用之间进行思考。

对于 GPT-5.6 之前发布的模型，多步骤对话中的默认行为是沿用每一步的输入和输出 Token，但不将先前轮次的推理纳入下一次采样的上下文。GPT-5.6 模型则默认纳入先前轮次中可用的推理。在支持的模型上，使用 reasoning.context 可以选择这两种行为中的任意一种。

当前轮次上下文中的推理 Token

虽然无法通过 API 查看推理 Token，但它们仍会占用 模型的上下文窗口空间，并按输出 Token计费。

控制成本

为了管理使用推理模型的成本，您可以限制模型生成的 Token 总数， 其中包括推理 Token、可见的输出 Token 和不可见的格式 Token。 要设置这一限制，请使用 max_output_tokens 参数。有关生成的 Token 如何计入用量和输出限制的详细信息，请参阅输出 Token 计数。

管理上下文窗口

创建响应时，务必确保上下文窗口中有足够的空间容纳推理 Token。根据问题的复杂程度，模型可能生成几百到数万个推理 Token。您可以在响应对象的 usage 对象中，通过 output_tokens_details 查看实际使用的推理 Token 数量：

{
  "usage": {
    "input_tokens": 75,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 1186,
    "output_tokens_details": {
      "reasoning_tokens": 1024
    },
    "total_tokens": 1261
  }
}

您可以在模型参考页面上查看上下文窗口长度，不同模型快照的长度会有所不同。

为推理分配空间

如果生成的 Token 达到上下文窗口上限或您设置的 max_output_tokens 值，您会收到一个响应，其中 status 为 incomplete，且 incomplete_details 中的 reason 为 max_output_tokens。这可能发生在任何可见的输出 Token 生成之前，也就是说，您可能需要支付输入 Token 和推理 Token 的费用，却没有收到可见的响应。

要避免这种情况，请确保上下文窗口中有足够的空间，或调高 max_output_tokens 的值。OpenAI 建议，在开始试用这些模型时，至少预留 25,000 个 Token 用于推理和输出。随着您逐渐了解自己的提示所需的推理 Token 数量，可以相应调整这部分预留空间。

处理不完整的响应
from openai import OpenAI

client = OpenAI()

prompt = """
Write a bash script that takes a matrix represented as a string with
format '[1,2],[3,4],[5,6]' and prints the transpose in the same format.
"""

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "medium"},
    input=[{"role": "user", "content": prompt}],
    max_output_tokens=300,
)

if (
    response.status == "incomplete"
    and response.incomplete_details.reason == "max_output_tokens"
):
    print("Ran out of tokens")
    if response.output_text:
        print("Partial output:", response.output_text)
    else:
        print("Ran out of tokens during reasoning")

跨调用保留推理

对话状态和推理状态的用途不同。在调用之间传递消息，可以让模型获得可见的对话历史。在支持的模型上，持久化推理还能让模型将先前轮次中兼容的推理项纳入下一次上下文。

持久化推理能够保持连续性，但不会暴露模型的原始推理。推理项的内容仍不可见，API 也不会返回其中的推理文本。设置 reasoning.context 可以控制模型能够使用哪些可用的推理项：

GPT-5.6 模型系列 支持 all_turns，并将其作为默认值。较早模型的默认值为 current_turn。省略 reasoning.context 或将其设为 auto，即可使用所选模型的默认值。

值行为
auto使用所选模型的默认值。省略 reasoning.context 与将其设为 auto 的效果相同。
current_turn提供当前轮次的推理，但不将先前轮次的推理纳入下一次采样的上下文。
all_turns将先前轮次中可用且兼容的推理项纳入下一次采样的上下文。GPT-5.6 模型支持此值。

响应的 reasoning.context 字段包含实际生效的模式，即 current_turn 或 all_turns。请检查每个响应中的此字段，以确认模型使用了哪种模式。此设置不会创建尚不存在的推理项。

只有当请求能够访问先前的响应项时，all_turns 才会生效。请使用 previous_response_id、将响应关联到一个对话，或手动重放完整的响应历史。在首次请求中，由于不存在先前的推理，current_turn 和 all_turns 的行为相同。

持久化推理只能在同一模型系列内复用。例如，gpt-5.6-sol、gpt-5.6-terra 和 gpt-5.6-luna 可以相互复用推理，但 GPT-5.6 和 GPT-5.5 系列之间无法沿用推理。

当您切换模型系列时，即使 reasoning.context 为 all_turns，API 也会从模型的上下文中排除不兼容的推理。

使用已存储的响应继续推理

使用 previous_response_id 实现最简洁的有状态集成：

通过先前的响应保留推理
from openai import OpenAI

client = OpenAI()
model = "gpt-5.6"

first = client.responses.create(
    model=model,
    input="Inspect this repository and identify the likely bug.",
    reasoning={"context": "current_turn"},
)

second = client.responses.create(
    model=model,
    previous_response_id=first.id,
    input="Now patch the bug and explain the change.",
    reasoning={"context": "all_turns"},
)

print(second.output_text)

重新传入模型已不再需要的旧响应项时，请使用 current_turn。这些推理项可以保留在 API 载荷中以维持连续性，但服务不会将它们纳入新一次采样的上下文。这可以减少长时间运行的工作流实际使用的上下文。

不依赖已存储的响应保留推理

在无状态模式下创建响应时，响应的 output 数组中的推理项默认包含 encrypted_content 属性。当 store 为 false，或您的组织使用零数据保留（ZDR）时，会采用无状态模式。为保持兼容性，API 仍接受在 include 中指定旧版 reasoning.encrypted_content 值，但不要求这样做。

以下请求无需指定 include 即可返回加密的推理内容：

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "store": false,
    "reasoning": {"effort": "medium"},
    "input": "What is the weather like today?",
    "tools": [ ... function config here ... ]
  }'

output 数组中的推理项将包含 encrypted_content 属性，其中存放加密的推理 Token，您可以将其传入后续调用。

要在 store: false 的情况下使用 all_turns，请保留每个输出项，追加下一条用户消息，然后重新传入完整历史记录：

在不存储响应的情况下保留推理
from openai import OpenAI

client = OpenAI()
model = "gpt-5.6"

history = [
    {
        "role": "user",
        "content": "Inspect this repository and identify the likely bug.",
    }
]

first = client.responses.create(
    model=model,
    store=False,
    input=history,
    reasoning={"context": "current_turn"},
)

# Keep every output item, including encrypted reasoning and assistant phase.
history.extend(item.model_dump() for item in first.output)
history.append(
    {
        "role": "user",
        "content": "Now patch the bug and explain the change.",
    }
)

second = client.responses.create(
    model=model,
    store=False,
    input=history,
    reasoning={"context": "all_turns"},
)

print(second.output_text)

在上下文中保留推理项

在 Responses API 中使用推理模型进行函数调用时，我们强烈建议您在回传函数输出的同时，回传上一次函数调用返回的所有推理项。如果模型连续调用多个函数，您应回传自上一条 user 消息以来的所有推理项、函数调用项和函数调用输出项。这样，模型便能继续推理，以最节省 Token 的方式生成更好的结果。

最简单的做法是将上一次响应中的所有推理项传入下一次响应。我们的系统会智能忽略与您的函数无关的推理项，仅在上下文中保留相关项。您可以使用 previous_response_id 参数传入先前响应中的推理项，也可以手动将先前响应中的所有输出项传入新响应的输入。

对于高级使用场景，您可能会先截断和优化上下文窗口中的部分内容，再将其传入下一次响应。此时，只需确保从上一条用户消息到函数调用输出之间的所有项均原样传入下一次响应。这样就能确保模型拥有所需的全部上下文。

请参阅本指南，了解有关手动管理上下文的更多信息。

在对话中途调整推理

使用 configuration_update 可以在处理复杂工作时提高推理强度，或在处理常规后续任务时降低推理强度。在两次响应之间添加更新，同时保持请求级别的 reasoning.effort 不变。这样可以保留原始提示前缀，以便使用提示缓存。

仅 GPT-6 Astra（gpt-6-astra）在 标准单智能体模式下支持配置更新。配置更新只能更改推理强度。

在 HTTP Responses 请求或 WebSocket response.create 请求的 input 数组中，将以下项添加到下一条用户消息之前：

{
  "type": "configuration_update",
  "reasoning": {
    "effort": "high"
  }
}

例如，如果对话开始时请求级别的推理强度为 low，此更新会为下一次及后续响应选择 high，直到另一次更新将其覆盖。

为后续任务提高推理强度
from openai import OpenAI

client = OpenAI()
model = "gpt-6-astra"

response = client.responses.create(
    model=model,
    reasoning={"effort": "low"},
    input="Draft a database migration plan.",
    store=True,
)
print(response.output_text)

response = client.responses.create(
    model=model,
    previous_response_id=response.id,
    reasoning={"effort": "low"},
    input=[
        {
            "type": "configuration_update",
            "reasoning": {"effort": "high"},
        },
        {
            "role": "user",
            "content": "Analyze the failure modes and propose rollback steps.",
        },
    ],
    store=True,
)
print(response.output_text)

使用 previous_response_id 保留更新，或在手动管理对话历史记录时，将这些更新按原来的位置重新传入。响应中的 reasoning.effort 仍会报告请求级别的设置，而非更新所选的推理强度。

不要在对话历史记录中将两个 configuration_update 项紧挨着放置；API 会拒绝相邻的更新。

不要将配置更新与自动压缩或自动截断结合使用。独立的 /responses/compact 端点也会拒绝包含这些更新的历史记录。

您仍可在 /responses 请求中包含 compaction_trigger 项，显式压缩历史记录。压缩后，请在下一条用户消息之前添加新的 configuration_update，并指定所需的推理强度。

常规提示缓存要求仍然适用。要在响应生成期间发送用户指令，请使用轮次中途引导。

推理摘要

我们不公开模型生成的原始推理 Token，但您可以使用 summary 参数查看模型的推理摘要。请参阅模型文档，了解哪些推理模型支持摘要。

不同模型支持不同的推理摘要设置。例如，我们的计算机使用模型支持 concise 摘要生成器，而 o4-mini 支持 detailed。要使用模型所支持的最详细的摘要生成器，请将此参数的值设为 auto。对于目前的大多数推理模型，auto 等同于 detailed，但未来可能会提供更细化的设置。

推理摘要输出位于 reasoning 输出项的 summary 数组中。只有在您明确选择包含推理摘要时，才会包含此输出。

以下示例展示如何发起 API 请求，使响应包含推理摘要。

在 API 响应中包含推理摘要
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="What is the capital of France?",
    reasoning={"effort": "low", "summary": "auto"},
)

print(response.output)

此 API 请求返回的输出数组将同时包含助手消息，以及模型生成该响应时的推理摘要。

[
  {
    "id": "rs_6876cf02e0bc8192b74af0fb64b715ff06fa2fcced15a5ac",
    "type": "reasoning",
    "summary": [
      {
        "type": "summary_text",
        "text": "**Answering a simple question**\n\nI\u2019m looking at a straightforward question: the capital of France is Paris. It\u2019s a well-known fact, and I want to keep it brief and to the point. Paris is known for its history, art, and culture, so it might be nice to add just a hint of that charm. But mostly, I\u2019ll aim to focus on delivering a clear and direct answer, ensuring the user gets what they\u2019re looking for without any extra fluff."
      }
    ]
  },
  {
    "id": "msg_6876cf054f58819284ecc1058131305506fa2fcced15a5ac",
    "type": "message",
    "status": "completed",
    "content": [
      {
        "type": "output_text",
        "annotations": [],
        "logprobs": [],
        "text": "The capital of France is Paris."
      }
    ],
    "role": "assistant"
  }
]

在使用我们最新推理模型的摘要生成器之前，您可能需要 完成组织 验证， 以确保安全部署。请前往平台 设置页面开始验证。

phase 参数

在 Responses API 中使用 GPT-5.5 和 GPT-5.4 处理长时间运行或频繁使用工具的流程时，请使用助手消息的 phase 字段，以避免提前停止等异常行为。 phase 在 API 层面是可选字段，但 OpenAI 建议使用它。对于助手的中间进度更新，例如工具调用前的开场说明，请使用 phase: "commentary"；对于完成后的答案，请使用 phase: "final_answer"。不要为用户消息添加 phase。 使用 previous_response_id 通常是最简单的方法，因为它会保留先前的助手状态。如果您手动重新传入助手历史记录，请保留每个原始 phase 值。 缺少或丢失 phase 可能导致这些工作流将开场说明视为最终答案。有关模型专属的提示词编写指导，请参阅为 GPT-5.5 编写提示词。

原样回传助手的 phase 值

原样回传助手的 phase 值
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input=[
        {
            "role": "assistant",
            "phase": "commentary",
            "content": "I’ll inspect the logs and then summarize root cause and remediation.",
        },
        {
            "role": "assistant",
            "phase": "final_answer",
            "content": "Root cause: cache invalidation race.",
        },
        {
            "role": "user",
            "content": "Great—now give me a rollout-safe fix plan.",
        },
    ],
)

print(response.output_text)

提示词编写建议

为推理模型编写提示词时，请考虑以下差异。对于具备推理能力的 GPT-5 模型，通常只需给出清晰的目标、严格的约束和明确的输出要求，而不必规定每个中间步骤，就能获得最佳效果。

  • 向模型说明任务、约束条件和期望的输出格式。
  • 将 reasoning.effort 作为调优参数，而不要将其作为弥补质量不足的主要手段。
  • 对于智能体工作流或需要大量研究的工作流，请明确定义完成标准，以及模型应如何验证自己的工作。

有关使用推理模型的更多最佳实践，请参阅本指南。

提示示例

OpenAI o 系列模型能够实现复杂算法并生成代码。此提示要求 o1 根据一些特定条件重构一个 React 组件。

重构代码
import OpenAI from "openai";

const openai = new OpenAI();

const prompt = `
Instructions:
- Given the React component below, change it so that nonfiction books have red
  text.
- Return only the code in your reply
- Do not include any additional formatting, such as markdown code blocks
- For formatting, use four space tabs, and do not allow any lines of code to
  exceed 80 columns

const books = [
  { title: 'Dune', category: 'fiction', id: 1 },
  { title: 'Frankenstein', category: 'fiction', id: 2 },
  { title: 'Moneyball', category: 'nonfiction', id: 3 },
];

export default function BookList() {
  const listItems = books.map(book =>
    <li>
      {book.title}
    </li>
  );

  return (
    <ul>{listItems}</ul>
  );
}
`.trim();

const response = await openai.responses.create({
  model: "gpt-6-astra",
  input: [
    {
      role: "user",
      content: prompt,
    },
  ],
});

console.log(response.output_text);

使用场景示例

您可以在 Cookbook 中找到一些将推理模型用于实际场景的示例。

使用推理进行数据验证

检查合成医疗数据集中的不一致之处。
使用推理生成操作流程

根据帮助中心文章生成智能体可执行的操作。