如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

推理模型

了解推理模型的工作原理,以及如何有效使用这类模型。

推理模型在生成响应前会先使用内部推理 Token。这有助于模型制定计划、有效使用工具、比较不同方案,在遇到歧义时继续推进任务,并解决更困难的多步骤问题。推理模型尤其擅长解决复杂问题、编程、科学推理,以及执行多步骤智能体工作流。对于我们的轻量级编程智能体 Codex CLI,推理模型也是最佳选择。

对于大多数推理工作负载,建议先使用 gpt-6.2-astra。如果希望降低成本,可以考虑 gpt-6.1-terra。如果需要最低成本和延迟,可以考虑 gpt-6-luna。如果您使用 GPT-5.6 或 GPT-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.2-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。GPT-6.1 Sol 不支持 none 或 minimal,默认值为 medium。

如果将 reasoning.effort(Responses)或 reasoning_effort(Chat Completions)设为 none,GPT-6.2 Astra 和 GPT-6.2 Sol 都会拒绝该请求。

请使用 Responses API 进行函数调用。对于 GPT-6 Astra 和 GPT-6.1 Sol,Chat Completions 不支持函数调用。

默认值也因模型而异。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 和 GPT-6 模型在 Responses API 中支持 standard 和 pro 两种推理模式。默认模式为 standard。对于需要模型投入更多计算,且能接受更高延迟和 Token 用量的困难任务,可将 reasoning.mode 设为 pro。

推理模式和推理强度彼此独立。模式决定采用标准模式还是 Pro 模式执行任务,reasoning.effort 决定模型在所选模式下的推理强度。如果省略 reasoning.effort,GPT-5.6 在两种模式下都默认使用 medium。GPT-6.1 Sol、GPT-6 Sol 和 GPT-6 Luna 的默认推理强度也都是 medium。

使用 Pro 推理模式
curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6.2-sol",
    "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

推理 Token 在 API 中不可见,仍会占用模型的上下文窗口,并按输出 Token计费。

控制成本

要控制推理模型的使用成本,可以通过 max_output_tokens 参数限制模型生成的 Token 总数,包括推理 Token、可见的输出 Token 和不可见的格式 Token。有关生成的 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 付费。

为避免这种情况,请确保上下文窗口留有足够的空间,或提高 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.2-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。GPT-6.1 Sol 也支持 all_turns。省略 reasoning.context 或将其设为 auto,即可使用所选模型的默认设置。

值 行为
auto 使用所选模型的默认设置。省略 reasoning.context 与将其设为 auto 的效果相同。
current_turn 仅允许模型使用当前轮次的推理。先前轮次的推理不会纳入下一次生成的上下文。
all_turns 将先前轮次中可用且兼容的推理项纳入下一次生成的上下文。GPT-5.6 模型和 GPT-6.1 Sol 支持此值。

响应中的 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-6.1-sol"

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.2-astra",
    "store": false,
    "reasoning": {"effort": "medium"},
    "input": "What is the weather like today?",
    "tools": [ ... function config here ... ]
  }'

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

要在 all_turns 模式下使用 store: false,请保留每个输出项,追加下一条用户消息,然后重新传入完整历史。

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

client = OpenAI()
model = "gpt-6.1-sol"

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.to_dict() 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,请在传回工具输出时,一并传回随函数调用返回的推理项。这样,模型就可以在工具调用后继续推理。

您可以使用 previous_response_id 将推理项传递给后续请求。如果您自行管理对话历史,请将原始输入和每个响应中的所有输出项都纳入下一次请求的输入。请保留这些项的原始顺序,并将新项追加到末尾。

对于较新的前沿模型,如果您修改某个推理项之前的历史记录,API 可能会从上下文中移除该推理项。有关如何更改指令和工具输出,以及如何管理长对话,请参阅保持前缀不变。

在对话过程中调整推理强度

您可以使用 configuration_update 为困难任务提高推理强度,或为常规后续任务降低推理强度。在两次响应之间添加更新,同时保持请求级 reasoning.effort 不变。这样可以保留原始提示词前缀,以便使用提示词缓存。

对于支持配置更新的 GPT-6 及后续模型,在标准模式下使用单个智能体时,您可以更新推理强度和响应格式。

请将以下项插入 input 数组,放在下一条用户消息之前。此做法适用于 HTTP Responses 请求和 WebSocket response.create 请求。

{
  "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 项中同时设置 reasoning.effort 和 text.format。只更新其中一项时,另一项会保留原有设置。

通过 context_management 启用自动压缩时,您可以同时使用配置更新。如果历史记录中已有配置更新,API 会在压缩项之后输出一条新的配置更新,其中包含最新的推理强度和输出格式。自动截断功能和独立的 /responses/compact 端点仍会拒绝包含配置更新的历史记录。有关如何准备独立的压缩请求,请参阅压缩指南。

您仍然可以显式压缩历史记录,做法是将 compaction_trigger 项加入 /responses 请求。压缩完成后,请在下一条用户消息之前添加新的 configuration_update,重新指定之前更改过的每项设置。如果更改过响应格式,也要重新指定该格式。

提示词缓存的常规要求仍然适用。要在响应生成期间发送用户指令,请使用在当前轮次中引导模型的功能。

API 在后续请求中移除推理项的情形

为防范蒸馏,如果您在对话中途切换模型系列、改用能力较弱的模型,或切换组织或用户,API 会移除推理项。从 GPT-6.2 开始,如果 safety_identifier 发生变化,或推理项之前的对话历史(即前缀)被修改,API 也会移除相应的推理项。

如果推理项被意外移除,可以查看响应中的 input_transformations 来排查原因。

原因 API 移除推理项的情形
prefix_mismatch 在 GPT-6.2 及后续模型中,您在推理项之前插入或编辑了内容。例如,改写之前某次工具调用的结果会改变前缀。整项删除并保留其余项的原有内容,或在推理项之后追加新项,这两种操作本身均不会触发此原因。
end_user_mismatch 在 GPT-6.2 及后续模型中,创建该项的请求和复用该项的请求使用了不同的 safety_identifier,或者只有其中一个请求提供了标识符。两个请求使用相同的标识符,或者都省略标识符,即可通过此项检查。
model_mismatch 您切换了模型系列,或改用同一系列中能力较弱的模型。如果改用同一系列中能力更强的模型,并且通过其他检查,则会保留兼容的推理。
organization_mismatch 您复用了来自其他组织的推理项,或复用了其他用户在不同工作空间中的推理项。
turn_boundary 推理项来自先前轮次,而模型只使用当前轮次的推理。GPT-5.6 之前发布的模型默认使用当前轮次的推理。对于支持此设置的模型,reasoning.context 决定是否可以使用先前轮次的推理。

推理摘要

您可以使用 summary 参数查看模型的推理摘要。模型生成的原始推理 Token 不会公开。请查阅模型文档,确认哪些推理模型支持摘要。

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

推理摘要包含在 summary 数组中,该数组属于 reasoning 输出项。只有在您明确启用推理摘要后,响应才会包含这部分输出。

以下示例演示如何发送 API 请求,让响应包含推理摘要。

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

client = OpenAI()

response = client.responses.create(
    model="gpt-6.2-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 编写提示词。

原样传回助手消息的阶段值

原样传回助手消息的阶段值
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6.2-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 用于微调。响应质量不理想时,避免主要依靠这个参数来改善质量。
  • 对于智能体工作流或需要大量研究的工作流,请明确任务的完成标准,以及模型应如何验证工作结果。

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

提示词示例

推理模型可以实现复杂算法,也可以生成代码。下面的提示词要求模型根据给定的标准重构一个 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.2-astra",
  input: [
    {
      role: "user",
      content: prompt,
    },
  ],
});

console.log(response.output_text);

应用场景示例

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

使用推理模型验证数据

检查合成医疗数据集中的不一致之处。

使用推理模型生成操作流程

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