model card 怎样读取输入约束

model card 更适合当作“输入契约的索引”，而不是可以直接提交给接口的 schema。读取时先找输入模态、字段形态、编码与容量、禁止项和已知局限，再回到对应模型的官方 API 文档确认字段名与实际支持范围。这样既能避免把图片当成文本字段，也不会把卡片里的概括性说明误当成永远有效的上限。

官方地址：https://platform.openai.com/docs

先把 model card 当作输入契约的索引

很多人打开 model card 后只看模型名称和一句能力概述，然后直接拼请求。问题在于“能处理文本”并不等于“任何文本字段都能传”，“支持图像”也不等于所有尺寸、编码和容器都被接受。model card 的价值是帮助你定位约束，真正的请求 schema 仍要由模型所属平台的 API 文档确认。

可以先按下面四组信息阅读：输入模态回答能传文字、图片、音频还是组合内容；字段形态回答每种输入在请求中是字符串、对象还是内容块；编码与容量回答编码、长度、尺寸或数量限制；禁止项和局限回答哪些内容不支持、哪些能力不应当承诺。不要把卡片里的自然语言段落直接复制成接口字段。

按四组信息读取输入约束

第一组是模态。先判断当前模型的输入是文本，还是还包含图片、音频等内容块；如果卡片只列出一种模态，就不要从“模型很强”推导出其它模态也可用。第二组是字段形态：同一段文字可能是顶层字符串，也可能位于消息的 content 数组中，字段形态不同，服务端解析结果也不同。

第三组是编码与容量。这里不只看字符数，还要关注字节编码、图片尺寸、音频格式、内容块数量和上下文窗口。若卡片没有给出具体数值，应把它记成“待官方文档确认”，不要用经验值填空。第四组是禁止项与局限，例如不支持的输入类型、只能在特定模型或端点使用的字段，以及结果不保证的场景。

下面是一个本地阅读模板，不是任何厂商规定的固定 model card 格式。它的作用是把散落在说明文字里的条件先整理成待确认清单：

# 这是阅读记录模板，不代表统一的 model card schema
model:
  name: "待确认的模型名"
  version: "待确认的版本或快照"
input:
  modalities: [text]
  item_shape: "待确认：字符串、消息还是内容块"
  encoding: "待确认"
  limits:
    text: "待官方文档确认"
    image: "不适用或待确认"
constraints:
  unsupported: []
  known_limitations: []

这个模板有意保留“待确认”状态：它提醒读者 model card 的描述和接口文档之间存在一层映射，不能把空白当成无限制。

用官方 API 文档确认最终请求字段

确认阶段至少做三次对照。先对照模型列表或模型详情，确认模型标识和可用能力；再对照对应输入指南，确认文本、图片或音频内容块的字段形态；最后对照 API reference，确认字段是必填、可选还是只在特定资源中出现。当前官方文档中的输入对象示例可以包含文本、图片和音频等不同类型，但具体资源支持哪些类型仍由该资源的说明决定。

建议把“卡片结论”和“接口结论”分开记录。例如卡片写“支持图像”，接口侧还要落到 input_image、图片 URL 或数据格式、detail 等实际字段；卡片写“支持文本”，接口侧仍要确认它应该出现在字符串、消息内容还是评测输入数组中。字段名不一致时，以当前官方 API reference 为准。

// 发送前只做契约整理，字段名仍需以当前官方 API 文档为准。
function readInputContract(card, apiReference) {
  // 把描述性信息和接口字段分开，避免把卡片当成可直接提交的 JSON。
  return {
    modalities: card.input?.modalities ?? [],
    declaredLimits: card.input?.limits ?? {},
    unsupported: card.constraints?.unsupported ?? [],
    requestFields: apiReference.inputFields ?? [],
  };
}

这段代码只是整理数据，不会替你判断“当前模型一定支持某种输入”。真正的支持性判断要在读取官方文档后填入 apiReference，并把未知值保留为未知。

请求前检查：把文字描述变成可执行判断

写请求前，可以把检查顺序固定成三层：先判断模态是否在允许集合内，再判断字段结构是否符合端点 schema，最后判断长度、尺寸、格式和数量是否在当前文档给出的范围内。任何一层无法确认，都应该停止发送或走明确的降级分支，而不是悄悄删字段。

例如，输入同时包含文本和图片时，检查结果应该能回答：文本是否放在正确的内容块中，图片引用是否符合当前接口接受的形式，图片的格式和尺寸是否满足要求，模型是否真的提供视觉输入能力。检查通过只表示请求契约基本成立，不代表模型输出一定正确。

基线、改动与边界：别把“可读”误写成“可用”

按实战拆解的方式，可以把一次接入分成三份记录。基线记录只写当前已经确认的输入字段；改动点是补齐模态、结构和容量信息；结果记录是“请求前检查能够指出哪一类不匹配”，而不是编造延迟、准确率或成功率。这样文章和工程日志都不会把说明文档误包装成性能测试。

最容易忽略的边界有三个：model card 可能滞后于接口版本，模型名称相同也可能对应不同快照；自然语言里的“支持”通常没有包含完整的格式、尺寸和数量条件；请求契约通过后，仍然要单独处理输出质量、内容安全和业务兜底。输入约束检查解决的是“能否按正确形态送进去”，不是“送进去后一定得到想要的答案”。

常见问题

model card 能直接生成请求 JSON 吗？

通常不能。它适合提供能力、输入模态和限制的索引；请求 JSON 的字段名、嵌套结构和必填关系仍要以当前官方 API 文档为准。

卡片没有写最大长度时怎么办？

把该字段标成待确认，去看对应模型和端点的官方输入说明。不要把旧模型的上限、经验值或一次成功请求当成当前模型的保证。

输入契约检查通过，是否代表模型一定能正确理解内容？

不是。检查只覆盖模态、结构、格式和容量等输入边界；输出质量、事实性、安全策略和业务结果仍然需要单独设计。