调 OpenAI 兼容接口时，文档一屏全是参数名，哪些必填、哪些填了也没用、哪些名字像但其实不是一回事，光看文档很难判断。这篇按请求结构从上到下过一遍常见字段的含义和取舍，给你一套读文档的方法和动手核对的动作，遇到没见过的字段也能自己定位。
调 OpenAI 兼容接口，最大的坑不是代码写错，而是文档没读明白。同一份请求体，官方文档、中转站文档、别家教程给的字段名和含义经常对不上，照着抄很可能跑出来结果不对，还不报错。这篇不讲抽象概念，就按请求结构从上到下把常见字段拆一遍，给你一套读文档的顺序和动手核对的动作，下次遇到没见过的字段也能自己定位。
先说清楚适用范围：下面讲的是请求侧的结构解析，不涉及鉴权体系、计费规则和流式响应的实现细节。如果你用的是自建推理服务或某些深度定制的兼容层，有些字段可能压根不生效，这时候以你实际对接那家的文档为准。
读接口文档的顺序：先定端点，再看请求体
很多人拿到文档第一件事就是从第一个参数读到最后一个，这是最费劲的方式。更省事的做法是先判断这一步在干什么：是新建一轮对话、往已有对话里补一条消息，还是单纯让模型接着写。这三类操作挂在不同的端点上，字段集合差别很大。端点定了，再去它的请求体里找必填项，能跑通再回头研究可选项。
- 先确定端点归属看路径里带的是对话、补全还是其他动作，别把 A 端点的参数直接搬到 B 端点，同一个名字在两边可能语义不同。
- 按三层过滤字段必填项先填齐跑通一次最小请求；可选项确认默认值是否够用；厂商扩展项留到最后再动。
- 把文档字段名和实际发出的 JSON 对照打开抓包或打印请求体，逐个比对字段拼写。很多误解不是理解错，而是文档里的叫法和真正传的名字不一致。
- 拿不准兼容层保留了什么就去查对照表兼容层未必完整实现所有字段，判断依据是逐字段对照，不是别家教程，具体到哪一页核对看下面的提示。
这个顺序的好处是：先把能跑通的最小请求立起来，后面每加一个字段你都知道它带来了什么变化。反过来先啃全部参数，很容易在某个冷门字段上耗半天，结果它对当前任务根本没用。
核心字段：消息数组、角色和内容怎么摆
对话类请求最核心的结构就是一个消息数组，数组里的顺序就是模型看到的上下文顺序，角色字段决定这条到底是系统设定、用户输入，还是模型上一轮说过的话。很多人第一次接多轮对话会想着把历史拼成一个大字符串塞进去，但标准做法是往数组里追加条目，拼接字符串容易让角色信息丢失，模型也就分不清谁说了什么。
- 消息数组的顺序即上下文顺序，顺序错了模型的理解就错
- 角色决定这条消息的归属，系统设定、用户输入、模型回复要分清
- 多轮对话靠往数组追加条目实现，不是把历史拼成一段文本
- 是否要对历史去重或裁剪由上层逻辑决定，接口本身不会帮你做
- 内容字段在纯文本和带附件场景下形状可能不同，先看清它接受字符串还是结构
- 模型名只起路由作用，哪个名字对应哪个真实模型，去站内模型库核对
内容字段值得单独说一句：纯文本场景下它通常就是一个字符串，但一旦涉及图片、文件或其他附件，它往往变成一个带类型的结构数组。读文档时要盯住这里写的是字符串还是对象，写错了不会报语法错误，只会得到奇怪的输出或者干脆空回复。
可选字段：取样、长度、格式这三类
可选字段看着杂，其实能归成三类：控制输出随机程度的取样类，控制答案长度的上限类，以及约束输出结构的格式类。把这三类分开理解，比逐个背参数名有用得多。取样类越往保守方向调，输出越稳定但越死板；任务越确定、越要求可复现，就越该往稳的一侧走。
| 字段类别 | 管什么 | 什么时候不适用 |
|---|---|---|
| 取样类 | 输出的随机与发散程度 | 需要创意发散时不宜调得过保守，会显得千篇一律 |
| 长度上限类 | 单次回答的最大长度 | 需要长文输出时设小了会静默截断，看不到报错 |
| 格式约束类 | 输出是否按指定结构返回 | 走自由文本问答时用不上，强行加反而限制表达 |
长度上限是新手最容易踩的坑之一：设小了，回答会在半句话上停住，接口不一定给你明确提示，你只会觉得模型没答完。排查这类问题时先看返回里有没有截断相关的标识，再回头调上限。格式约束字段和提示词里写一句「请返回 JSON」完全是两回事：前者会真的约束解码过程，后者只是建议，模型完全可以不听。
厂商扩展字段与兼容层的坑
兼容层通常只保证最常用的那一批字段能用，冷门字段被静默丢掉或改名是常态，而且丢掉的时候一般不报错，只是行为和你预期的不一样。所以遇到「文档里写了但没生效」的情况，第一反应不该是改代码，而是先确认这个字段在你这层到底被保留没有。
- 兼容层优先保证常见字段，冷门字段被丢弃或改名很常见
- 遇到能生效但文档里没有的字段，先查是不是这家的私有扩展，别当成通用标准
- 不同端点对同一字段的接受程度不同，对话端能用的在补全端可能无效
- 字段无效时往往不报错，只会行为不符预期，靠返回值很难反推
- 想确认某字段是保留还是缺失，去站内逐字段对照页核实，别靠猜
举个例子：一家 5 人小团队把本地调通的请求原样搬到另一家兼容服务上，代码没动，输出风格却完全变了。原因往往是某个取样类字段被忽略，服务用了自己的默认值。这种情况下改参数没用，得先确认字段有没有被接住。各家的默认值和支持情况会变，具体到站内页面核对当时的数字比记住任何结论都可靠。
下一步想确认自己对接的那家到底支持哪些字段、默认值是什么，直接到站内兼容字段对照页逐项核一遍，比在报错里来回猜省事得多。→常见问题
文档里写了但传过去没反应，是什么原因？
多半是兼容层没实现这个字段。兼容接口只保证主流字段能用，冷门字段被静默忽略很常见，不会报错。判断办法是用一个明显会改变行为的值试，输出没变化就说明没生效，换等价的提示词写法替代。
字段名大小写和下划线写错会怎样？
通常直接报参数错误，少数平台会静默忽略当成默认值，结果就是行为诡异但不报错。养成习惯：先用最小请求跑通，再一个一个加字段，加完比对输出，这样出错能立刻定位到是哪个字段。
怎么确认某个字段这家到底支不支持？
先用该字段去模型库或兼容字段对照页查一眼，再发两次请求做对照实验，一次带一次不带，输出行为有差就是支持。都不行就说明得换实现方式，别在字段上继续死磕。
