第 2 课

按官方建议选 Astra 或 Sol,设置推理力度并传入示例图

> 本课对照官方文档「Using GPT-6.2」「模型选择」「推理模型」「开发者快速入门」编写。推理示例代码、usage 对照 JSON 来自「推理模型」页;看图请求采用官方 curl 示例。2026-11-19 核对。

图文22 分钟ChatGPT 官方文档 ↗

课程目录第 2 / 3 课

学习位置仅保存在当前浏览器,有效期 180 天。

01 / 图文教材

图文教材

本课对照官方文档「Using GPT-6.2」「模型选择」「推理模型」「开发者快速入门」编写。推理示例代码、usage 对照 JSON 来自「推理模型」页;看图请求采用官方 curl 示例。2026-11-19 核对。

本课目标

  • 按官方建议,在 Astra 与 Sol 之间选择型号
  • 设置 reasoning.effort,避免传入会被拒绝的 none
  • 跑通官方推理示例,并对照 usage 里的 reasoning_tokens
  • 给输出留出足够空间,避免请求在可见文字出现前就因限额中断
  • 用官方 curl 示例传入一张示例图

前置条件

  • 已完成第 1 课,当前终端里仍有有效的 OPENAI_API_KEY
  • 已安装 openai 包
  • 能访问公网图片地址

第 1 步:按官方建议选 Astra 或 Sol

官方「模型选择」把选型写得很直接:

  • 大多数 API 工作流,先用 GPT-6.2 Sol,推理力度设为 medium
  • 吃力的工程或分析任务,再选 GPT-6.2 Astra
  • 小而重复的任务可以考虑 GPT-6 Luna;读图表、截图可考虑 GPT-6.1 Terra。后两者不是本课的练习对象

同一页还按任务给出更细的起点,例如:

  • GPT-6.2 Sol · Medium:在现有代码库里修缺陷、加功能,或起草待审阅的文档
  • GPT-6.2 Sol · Extra high:需要边做边测、边改的多步任务
  • GPT-6.2 Astra · Low:把一份清楚的简报做成可直接交付的成品
  • GPT-6.2 Astra · Medium:规划并执行复杂项目,随着新信息调整方法
  • GPT-6.2 Astra · Extra high:要权衡取舍、检验假设的开放问题

页面卡片上的官方说明是:Astra 偏向复杂专业工作,例如按你的模板做幻灯片和表格、分析科学数据、设计复杂的 3D 零件;Sol 偏向高效的日常工作,例如写代码和测试、起草清楚的文档、完成跨应用的多步流程。

把代码里的 model 换成对应 ID 即可,不必改请求结构。下面先用 Sol 做日常联调,再用 Astra 跑官方推理示例。

官方「模型选择」页首屏

2026-11-19 实拍。

https://developers.openai.com/api/docs/guides/model-selection

第 2 步:设置推理力度,不要传 none

推理模型会先在内部生成推理 tokens,再写出可见回答。官方「推理模型」建议:这类工作更适合 Responses API;Chat Completions 仍可用,但 Responses 能更好发挥模型能力。

在 Responses API 里,推理力度写在 reasoning.effort。官方列出的取值包括 none、minimal、low、medium、high、xhigh 和 max,但具体型号支持的集合不同。对 GPT-6.2 Astra 和 GPT-6.2 Sol,官方模型页和推理文档都写明:把 reasoning.effort(Responses)或 reasoning_effort(Chat Completions)设为 none 会被拒绝。

「Using GPT-6.2」的迁移说明给出了实用起点:新集成先用 medium;如果你现在用的是 none 或 minimal,改成 low。力度越低,通常越快、tokens 越少;越高则想得更完整。模型也会按任务难度自适应,简单题少想、难题多想。

官方对几个常用档的概括如下(完整表见推理文档,部分说明同时面向更早的型号):

  • low:要工具、规划、搜索或多步决策,但又希望控制速度和成本
  • medium:质量与可靠性更重要,适合智能体编程、研究、处理表格和幻灯片、委派长程任务,是大多数工作的均衡点
  • high:难推理、复杂调试、深度规划,质量优先于延迟
  • xhigh 与 max:只在评估证明额外延迟和成本确实有收益时再使用

不要根据猜测给 GPT-6.2 传入文档没有为它单独保证的取值。先用官方建议的 medium 或迁移时的 low,再按效果调整。

官方「Using GPT-6.2」页首屏

2026-11-19 实拍。

https://developers.openai.com/api/docs/guides/latest-model

第 3 步:跑官方推理示例,并看 usage

新建 reason_transpose.py。下面就是官方「推理模型」页的 Python 示例,型号是 gpt-6.2-astra,力度是 low:

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)
python reason_transpose.py

官方这一页没有给出这段脚本的固定样例输出,所以本课不编造运行结果。你应看到一段 bash 脚本;具体写法会随推理过程变化。真正可以对照的,是官方给出的 usage 结构。推理文档用下面这个 JSON 说明:推理 tokens 的数量写在 output_tokens_details 里。

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

这段示例来自:

https://developers.openai.com/api/docs/guides/reasoning

请对照你这次响应里的 usage。数字不会相同,但应能看到 output_tokens_details.reasoning_tokens。官方写明:推理 tokens 不通过 API 以明文展示思考过程,但它们占用上下文窗口,并且按输出 tokens 计费。

官方「推理模型」页首屏

2026-11-19 实拍。页中示例代码与本课第 3 步一致。

https://developers.openai.com/api/docs/guides/reasoning

官方文档中的推理 tokens 与上下文示意图

官方原图,来源:

https://cdn.openai.com/API/docs/images/context-window.png

第 4 步:给输出留出足够空间

官方建议用 max_output_tokens 限制一次响应生成的总 tokens,范围包括推理 tokens、可见输出,以及不可见的格式 tokens。如果生成量碰到上下文上限或你设的 max_output_tokens,响应的 status 会是 incomplete,incomplete_details.reason 为 max_output_tokens。这可能发生在任何可见文字出现之前。也就是说,你可能已经为输入和推理付了费,却看不到回答。

官方建议:刚开始试用这类模型时,至少为推理和输出预留 25,000 tokens。等你熟悉自己的提示会消耗多少推理 tokens,再调整这个缓冲。

把第 3 步的创建调用改成带上限的写法时,只要增加一个参数即可,例如:

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

25000 来自官方「至少预留 25,000 tokens」的建议,不是另一个隐藏默认值。

第 5 步:用官方 curl 传入一张示例图

两个 GPT-6.2 型号都接受图片输入。官方「开发者快速入门」的 curl 与 TypeScript 示例使用同一张示意图,提问是 “What is in this image?”。先在浏览器或本地下载这张图,确认能打开:

https://openai-documentation.vercel.app/images/cat_and_otter.png

官方快速入门示例图:猫与水獭

官方示例图原文件,源地址同上。

然后发出官方 curl。完整图片地址单独占一行,避免代码块横向溢出:

curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6.2-astra",
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "What is in this image?"
                    },
                    {
                        "type": "input_image",
                        "image_url":
"https://openai-documentation.vercel.app/images/cat_and_otter.png"
                    }
                ]
            }
        ]
}'

官方这一页没有给出看图结果的固定样例句,本课也不编造。成功时,output_text 应描述这张图里的内容;失败时先检查 Key、额度,以及图片 URL 是否能在你的网络环境访问。

说明:同一节的官方 Python 标签用的是另一张图(美国国家美术馆的馆藏图)和另一句提问 “What teams are playing in this image?”。本课跟做以 curl / TypeScript 这一组为准,因为图片和提问一致。不要把两组示例混在一次请求里。

第 6 步:可选,了解 pro 推理模式

官方写明:GPT-5.6 和 GPT-6 系列在 Responses API 中支持 standard 和 pro 两种推理模式,默认是 standard。reasoning.mode 与 reasoning.effort 是两件独立的事:模式决定按 standard 还是 pro 执行,力度决定在该模式里想多少。把模式设为 pro,会做更多模型工作,tokens 和费用也会增加;这些 tokens 仍按所选型号的标准 token 费率计费。

官方给出的 curl 如下。这是可选步骤,日常入门不必默认打开 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."
  }'

官方没有给出这段请求的固定样例回复。若你要比较 standard 与 pro,请用同一条输入各跑一次,只对照自己的结果,不要把未核实的二手结论写进系统提示。

常见坑

  • 给 GPT-6.2 传入 reasoning.effort: "none",请求会失败。
  • 把 max_output_tokens 设得太小。可能只产生推理 tokens,看不到可见回答,但费用已经发生。
  • 把官方 Python 标签的馆藏图,和 curl 标签的猫与水獭图拼成一次请求。
  • 看到 Astra 在「推理模型」页被写为大多数推理工作的起点,就忽略「模型选择」里「大多数 API 工作流先用 Sol」的建议。两句话针对的场景不同:前者强调推理质量,后者强调日常成本和适用面。按任务选,不要只记一个口号。

小结

这一课你已经能按官方建议选择型号和推理力度,读懂 usage 里的推理 tokens,并完成一次官方看图请求。下一课会处理 GPT-6.2 在提示缓存上的变化,并跟做一次必须走 Responses API 的工具调用。