#203·waoowaoo

建议为 OpenAI Compatible 媒体模板支持显式省略空请求字段

Author: HuuuhuuhuCreated Jul 15, 2026Updated Jul 15, 2026

问题背景

目前 OpenAI Compatible 的媒体模板会把占位符渲染进最终请求体。缺少可选媒体输入时,{{images}} / {{image}} 可能分别渲染为空数组或空字符串。

部分兼容服务商会拒绝“存在但为空”的可选字段。例如纯文生图场景中,如果请求仍携带:

json
{
  "extra_body": {
    "image": []
  }
}

服务端会返回 400;但在图生图场景中,同一个字段又必须存在。当前模板协议无法表达“仅当渲染结果为空时省略该字段”,因此一个模板难以同时兼容有、无参考图两种请求。

建议方案

为具有请求体的模板 endpoint 增加一个可选的显式配置:

typescript
omitEmptyBodyFields?: string[]

数组元素是相对于 bodyTemplate 的点分路径。例如:

json
{
  "bodyTemplate": {
    "model": "{{model}}",
    "prompt": "{{prompt}}",
    "extra_body": {
      "image": "{{images}}"
    }
  },
  "omitEmptyBodyFields": ["extra_body.image"]
}

模板完成正常渲染后,只对配置中列出的路径执行处理,并且仅当最终值严格等于空字符串 "" 或空数组 [] 时,从请求体中删除该字段。

兼容性约束

  • 未配置 omitEmptyBodyFields 时,现有模板行为完全不变。
  • 只处理显式列出的路径,不做全局递归清理。
  • 不删除 null、数字、布尔值、对象、非空值或未列出的空值。
  • schema 校验路径必须真实存在于对象类型的 bodyTemplate 中。
  • 没有请求体的 endpoint 不允许配置该选项。
  • 配置助手仅在服务商文档或实际探测明确证明“空值会被拒绝”时生成该字段,避免猜测。

本地验证

我已按上述方式完成本地实现和回归验证:

  • 覆盖旧模板行为保持不变。
  • 覆盖嵌套空数组和空字符串的定向省略。
  • 覆盖未列出的空字段仍然保留。
  • 覆盖 schema 对不存在路径、无请求体 endpoint 的拒绝。
  • 覆盖 API 配置保存后该字段仍被保留。
  • 9 个相关测试文件,共 69 项测试通过。
  • TypeScript --noEmit、改动文件 ESLint 与生产容器构建验证通过。

如果维护者认可这个方向,我可以再按项目当前代码基线整理最小补丁或补充更详细的测试用例。