Step 5 Preview 这类预览版接口，最容易踩的坑不是模型输出质量，而是链路没通就先动参数。一上来改 temperature、top_p、max_tokens，返回值不对时你分不清是鉴权没生效、模型名写错、请求体结构不对，还是参数本身导致的。建议把顺序反过来：先用一个不带业务参数的最小请求确认链路能通，再逐项加参数，每加一项记一次结果。这样任何一次异常都能定位到唯一一个变化点上。
适用场景：首次接入某个预览版接口，或换环境、换账号、换模型名之后。操作动作：只保留鉴权信息和模型名发一次请求，确认能拿到正常响应。验证方式：看 HTTP 状态码、单次响应耗时和错误报文是否完整可读。风险边界：最小请求通了只说明网络、鉴权、模型名这三项没问题，不代表业务参数组合可用；预览版行为可能随版本调整，稳定组合需要在目标环境再确认一次。
清空调参项只保留鉴权和模型名
先构造一个不携带任何业务参数的最小请求体。通用骨架如下，不同接入方式的字段名会有差异，需要以实际接口文档或报错信息为准：
{
"model": "<模型名>",
"messages": [
{ "role": "user", "content": "ping" }
]
}这个骨架里通常只需要两个必填项：model 和 messages。鉴权信息不放在请求体里，而是放在请求头，例如 Authorization: Bearer <KEY>。暂时不要带上 temperature、top_p、max_tokens、system 消息、工具定义、流式开关等任何可选字段。如果接口强制要求某些字段（比如 stream 必须显式给 false），第一次请求报错后按报错提示补上即可，补完就停，不要顺手把其他参数一起加。
建议先在命令行或页面调试框里发这一次请求，不要直接写进业务代码。写进代码会引入超时、重试、序列化等额外变量，反而不容易判断问题出在哪一层。
发送并记录HTTP状态码与响应耗时
这一次请求的重点不是内容好不好，而是把状态码、耗时和错误信息原样记下来。可以用 curl 的 -w 参数把这两项输出到终端：
curl -s -o resp.json \
-w "http_code=%{http_code} time_total=%{time_total}\n" \
-X POST "$BASE_URL" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d @min.json状态码基本能划出排查范围：401 / 403 通常是鉴权头缺失或密钥无效；404 常见于路径写错或模型名不存在；400 一般是请求体字段缺失、类型不对；429 是触发限流；5xx 属于服务端侧。耗时用于后面加参数时做对比，比如某个参数加上之后耗时明显变长，就要先怀疑是不是触发了重试或超时，而不是先怀疑模型。响应体里的错误信息建议完整保存，不要只抄一句“request failed”，多数接口的报错里会写明是哪个字段有问题。
逐步加入 system、temperature 等参数
最小请求稳定返回之后，按“一次只加一项”的方式往上叠。可以参考下面这个顺序：
- 加
system消息：观察点是返回内容是否开始遵守角色设定，同时确认消息顺序和 role 名拼写正确。 - 加
max_tokens：先给一个偏小的值，观察截断行为是否符合预期，以及返回结构里有没有finish_reason之类的字段。 - 加
temperature：同一个 prompt 连发两三次，观察结果是否出现波动；如果完全没变化，先确认这个参数是否真的被接口接受。 - 加
top_p或同类采样参数：注意它和 temperature 一般建议只重点调一个，同时调容易说不清是谁在起作用。 - 加
stream：观察分片返回格式、结束标记以及超时表现是否和一次性返回不同。 - 最后加业务字段：工具定义、结构化输出格式、多轮历史等，这些字段最容易因为拼写或嵌套层级写错导致 400。
每一步都记录三件事：状态码是否仍是 2xx、耗时是否明显偏离上一档、返回结构和内容有没有变化。如果某一步出错，回退到上一步的请求体重新发一次，确认是这一步引入的，再逐字段核对，而不是同时改两处去试。
把稳定组合写进配置模板
确认哪些参数组合能稳定返回后，把它们固化成配置文件，而不是散落在调用代码里。一个可替换的骨架示例：
endpoint: "<接口地址>"
auth:
type: bearer
header: Authorization
key_env: STEP5_KEY
model: "<模型名>"
request:
timeout_s: 60
retries: 0
params:
max_tokens: 512
temperature: 0.2
stream: false
system_prompt_file: "./prompts/system.txt"字段含义按需替换：endpoint 是实际请求地址；auth.key_env 表示密钥从环境变量读取，避免写进仓库；model 必须显式指定，不要依赖服务端默认值；timeout_s 和 retries 建议显式写出来，默认值在排查时反而是干扰项；采样类参数如果不需要就走服务端默认，不必为了“写全”而硬填。哪些必须显式指定，判断标准很简单：换环境时如果它变了会导致请求失败或结果不可复现，就写进模板。
在日志里固定请求ID方便回溯
接入完成后，业务请求能不能复现，取决于日志里有没有一个稳定的关联标识。推荐做法是调用方自己生成一个请求 ID，随请求头发出去，同时在本地日志里记一份：
X-Request-Id: 8f3c1a2e-<随机串>生成方式用 UUID 或“时间戳 + 随机后缀”都可以，关键是同一条业务调用在请求日志、响应日志、业务日志里用同一个值。如果服务端响应里也返回了自己的 request id，两个都记下来，出问题时服务端侧字段能帮对方定位。日志建议按行记录这些字段：
ts=... req_id=... model=... http_code=... time_total=...
params=max_tokens=512,temperature=0.2,stream=false把参数也写进同一行，是为了回溯时能直接看到当时用的是哪一档配置。验证方式：从日志里挑一条有问题的记录，用同一个 req_id 对应的参数重发一次，只改其中一个字段，看返回是否发生对应变化。如果重发结果和日志对不上，说明日志里漏记了某个参数，或者有代码路径绕过了配置模板，这两处都要补回去。