OpenAI API 怎样用 temperature 之外的参数控制采样

OpenAI API 里，temperature 之外真正直接参与采样控制的是 top_p；reasoning.effort、max_output_tokens 和 text.verbosity 更像推理投入、输出预算与表达详略控制。先把这些职责分开，再按一个变量一轮地调整，结果才容易解释。

官方文档：https://developers.openai.com/api/docs/

下面以 Responses API 为范围。不同模型对参数的支持范围可能不同，示例中的模型名需要替换成账户可用的模型，不要把某个模型的默认值当成所有模型都相同。

OpenAI API 的采样控制分成两层

第一层是直接改变候选 token 如何进入采样的参数：temperature 调整分布的随机性尺度，top_p 做 nucleus sampling，只保留累计概率质量达到阈值的候选范围。第二层是生成控制：reasoning.effort 约束推理模型投入多少思考预算，max_output_tokens 限制响应可生成的总 token 上限，text.verbosity 影响文本表达的详略。

因此，“答案太发散”先看采样参数；“回答太短”先看输出预算；“推理任务不够稳”再看模型是否支持以及 reasoning.effort。把三类问题都归结为提高或降低 temperature，通常会得到难以复盘的调参结果。

先选 top_p，再决定是否调整 temperature

top_p 的取值范围是 0 到 1。它不是“保留前几个 token”，而是按概率从高到低累积候选，直到覆盖设定的概率质量。例如较小的 top_p 会缩小候选范围，较大的值会保留更多可能性。官方文档建议通常调整 temperature 或 top_p 其中一个，而不是同时调整。

一个可复用的顺序是：先固定 temperature，只改变 top_p 观察答案的稳定性；如果仍需要更细的随机性变化，再回到 temperature 做小幅调整。每轮至少固定提示词、模型、输入顺序和输出预算，否则你看到的差异不一定来自采样参数。

用 Responses API 把随机性和输出上限分开配置

下面的最小示例只展示参数职责，不代表在本地已经发起请求。示例把 top_p 作为主要采样旋钮，同时保留一个较低的 temperature 作为固定基线；实际项目应通过同一组测试输入比较多次结果。

from openai import OpenAI

# 用环境变量读取密钥，避免把凭据写进源代码。
client = OpenAI()

# 替换为账户可用且支持这些字段的模型。
response = client.responses.create(
    model='your-model-id',
    input='把这段说明改写成三条简短要点。',
    temperature=0.2,          # 固定随机性基线，先不要和 top_p 一起大改。
    top_p=0.9,                # 控制候选 token 覆盖的概率质量范围。
    max_output_tokens=300,    # 限制总输出预算，不负责增加答案的多样性。
)

# SDK 提供文本便捷属性时直接读取；业务代码仍应处理请求异常。
print(response.output_text)

这里的 max_output_tokens 是上限，不是目标长度。推理模型还可能把推理 token 计入这个总预算，所以“提高上限”会改变可用空间，却不会自动让内容更有创意。请求参数的具体兼容性以当前 API Reference 和模型说明为准。

不要把 reasoning.effort 和 max_output_tokens 当成随机开关

reasoning.effort 解决的是推理模型投入多少思考，适合在速度、成本和复杂任务质量之间做取舍；它不是 top_p 的替代品。复杂规划可以尝试更高的 effort，延迟敏感的分类任务则应结合模型支持范围选择较低档位。

max_output_tokens 只解决“最多能生成多少”。如果响应经常在句子中间结束，先增加预算并检查是否包含推理 token；如果答案过于冗长，应收紧任务要求或使用文本配置，而不是把 temperature 调到极低。只有当输出仍然偏离预期时，才回到采样参数。

迁移与排查时看这张参数表

实际调参可以留下四项记录：模型与 endpoint、固定输入、变更的单一参数、结果摘要。这样才能回答“为什么这次更好”，也能区分是采样范围、推理预算还是输出长度造成的变化。

top_p 和 temperature 可以同时调整吗？

技术上是否接受取决于 endpoint 和模型，但官方建议通常只调整其中一个。两者同时变化会让结果归因困难，除非你已经用固定实验设计明确知道自己要比较什么。

max_output_tokens 能让答案更有创意吗？

不能。它提供更多生成空间，不能直接扩大候选分布。创意或随机性应从采样参数和提示词目标入手。

reasoning.effort 越高越好吗？

不一定。它要和任务复杂度、延迟、成本以及模型支持范围一起权衡；简单任务提高 effort 可能只增加开销。

参数说明可从官方 API Reference 继续查阅：https://developers.openai.com/api/reference/resources/responses/methods/create；推理投入说明见 https://developers.openai.com/api/docs/guides/reasoning。