OpenAI Responses API 中的 developer 角色与推理模型

最近翻了一遍 OpenAI 的文档，发现 API 有不少变化。最显著的是推出了新的 Responses API，以及针对推理模型（reasoning models）的新机制。这篇记录一下关键点。

Responses API：新项目的推荐选择

OpenAI 现在推荐新项目使用 Responses API，而不是之前的 Chat Completions API。新 API 的端点是 /v1/responses，请求结构也有变化：

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    reasoning={"effort": "medium"},
    input=[
        {
            "role": "developer",
            "content": "你是一个代码审查助手。检查安全漏洞和性能问题。"
        },
        {
            "role": "user",
            "content": "请审查这段代码..."
        }
    ]
)

几个变化：

• 用 input 替代了 messages
• 新增 reasoning 参数控制推理行为
• 新增 instructions 参数作为设定指令的另一种方式

消息角色：developer 和 user

在 Responses API 中，消息角色分为：

文档原话是：

developer messages are instructions provided by the application developer, prioritized ahead of user messages.

翻译：developer 消息是应用开发者提供的指令，优先级高于 user 消息。

可以这样理解这两个角色的关系：

• developer 相当于函数定义，提供系统规则和业务逻辑
• user 相当于函数参数，提供具体输入

instructions 参数

除了用 developer 角色的消息，还可以用 instructions 参数来设定高级指令：

response = client.responses.create(
    model="gpt-5",
    reasoning={"effort": "low"},
    instructions="Talk like a pirate.",
    input="Are semicolons optional in JavaScript?"
)

instructions 参数的优先级高于 input 中的提示。这两种方式效果基本等价：

# 方式一：使用 instructions 参数
instructions="Talk like a pirate."

# 方式二：使用 developer 消息
input=[
    {"role": "developer", "content": "Talk like a pirate."},
    {"role": "user", "content": "Are semicolons optional in JavaScript?"}
]

推理模型

GPT-5 和 o 系列模型（o3、o4-mini）是推理模型。它们在生成回答前会进行内部推理（Chain of Thought），产生 reasoning tokens。这些 token 不会在 API 响应中显示，但会占用上下文窗口并计费。

通过 reasoning.effort 参数控制推理程度：

response = client.responses.create(
    model="gpt-5",
    reasoning={"effort": "medium"},  # low / medium / high
    input=[{"role": "user", "content": "..."}]
)

• low：速度快，token 消耗少
• medium：默认值，平衡速度和推理深度
• high：更完整的推理

推理模型的 token 使用情况可以在响应的 usage 对象中查看：

{
    "usage": {
        "input_tokens": 75,
        "output_tokens": 1186,
        "output_tokens_details": {
            "reasoning_tokens": 1024
        }
    }
}

推理模型的提示技巧

文档提到推理模型和传统模型在提示方式上有区别：

A reasoning model is like a senior co-worker—you can give them a goal to achieve and trust them to work out the details.

推理模型像资深同事——你只需给出目标，相信它能自己搞定细节。

A GPT model is like a junior coworker—they’ll perform best with explicit instructions to create a specific output.

传统 GPT 模型像初级同事——需要明确的指令才能产出符合预期的结果。

当前的模型

根据文档，推理模型包括：

文档特别提到：

Reasoning models work better with the Responses API. While the Chat Completions API is still supported, you’ll get improved model intelligence and performance by using Responses.

推理模型在 Responses API 下表现更好。虽然 Chat Completions API 仍然支持，但使用 Responses API 能获得更好的模型智能和性能。

小结

1. 新项目推荐用 Responses API
2. 用 developer 角色或 instructions 参数设定系统指令
3. 推理模型用 reasoning.effort 控制推理深度
4. 给推理模型高级目标，不用写太细的步骤

参考资料

• OpenAI Text Generation Guide
• OpenAI Reasoning Guide
• Chat Completions API Reference