多模态一起调，真正麻烦的不是某个模态不能用，而是报错之后无法归因：不知道是文本侧、图像侧、音频侧的问题，还是请求体的层级结构写错了。可行的做法是反过来——先把一个模态跑到可重复，再在同一个请求体里逐项叠加，每次只引入一个变化量，并把可观察的通过标准写下来。下面的顺序按「单模态基线 → 加第二个模态 → 核对层级 → 单模态输入自检 → 回退规则」推进，可以在请求构造页上做，也可以在本地请求脚本里做。字段名、模态类型标识、体积和时长上限需要以你实际接入的端点为准，这里给的是可替换的骨架和判断方法。

多模态调试的核心是控制变量：先让一个模态在同一请求体里连续三次返回结构一致的结果，再新增第二个模态，且本次只改模态相关字段。报错时先用请求构造页逐层核对嵌套位置，再回到单模态输入自检，分清是输入本身被拒还是组合方式有误。若最小文本态也无法通过，应停止在模态层面继续尝试，转去核对鉴权、端点与模型标识——这条边界能挡住大部分无效重试。

固定一个模态作为基线并跑三次

先只发一个模态，通常选文本，因为它的输入最容易控制。基线请求要记录：模型标识、端点、messages 的角色顺序、单条 content 数组里元素的数量与类型、采样参数（温度、最大输出长度）、是否要求返回音频或其他模态。把这些存成一个文件，例如 baseline.json，后续每次加模态都以它为底本复制。

三次返回不要求文字完全一样——采样本身会带来差异——但要检查结构是否一致：返回的消息角色序列是否相同、content 里元素类型是否符合预期、结束原因和错误字段是否稳定。通过标准可以定为：三次都不报错，且返回结构与预期模态一致。

如果三次里有一次报错或结构不同，说明基线本身不稳定。此时先记录报错原文、请求 ID 和三次响应，不要急着换模态或改参数，把不一致当成线索而不是绕过去的障碍。回退动作是回到最小文本态重发一次，确认问题是否只存在于基线。

在同一请求体里增加第二个模态，其他字段一律不动

新增模态时，复制 baseline.json 为 step2.json，只改与第二个模态直接相关的部分：通常是在同一条 message 的 content 数组里追加一个元素，包含该模态的类型标识和载荷（本地数据或可访问地址）。模型标识、角色顺序、采样参数、输出要求一律不动。

改完做一次逐字段对照，确认本次唯一改动项只有一处：

diff <(python -m json.tool baseline.json) <(python -m json.tool step2.json)

预期输出只包含新增的 content 元素，以及为它补上的逗号或括号。如果 diff 里出现了别的东西——模型标识变了、消息条数变了、参数被顺带调整——先撤回这些改动再发请求，否则报错无法归因。把这次唯一改动项写在请求文件旁边或提交说明里，后面回退时才有依据。

用请求构造页面逐层展开嵌套结构，核对层级

层级错误在多模态请求里很常见。典型结构是分层的：顶层放模型与参数，messages 是数组，每条 message 有 role 和 content，content 本身又是数组，每个元素带类型标识和该模态的载荷。

{
  "model": "<模型标识>",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "<文本类型>", "text": "..." },
        { "type": "<第二个模态类型>", "<载荷字段>": "..." }
      ]
    }
  ]
}

容易放错位置的地方有几个：一是把模态载荷写在 message 顶层、和 role 平级，而不是放进 content 数组；二是把两个模态拼成一段字符串塞进同一个 content 元素；三是类型标识的大小写或命名与端点要求不一致，或者把类型写在数组元素外面。在请求构造页上逐层展开时，先看 content 是不是数组、再看每个元素有没有类型字段、最后看载荷字段是否挂在正确的元素上。

层级错误的报错通常集中在结构和类型上：提示某字段应为数组却收到字符串、content 元素缺少必需字段、类型值不在允许集合内、role 缺失或 messages 不是数组。看到这类信息时优先核对层级，而不是急着调整输入内容。

给每个模态单独准备一条能过的输入

组合失败和输入本身被拒是两回事，最好分开验证。做法是给每个模态准备一条最小可用输入，单独发一次，确认它能通过，再回到组合请求。

• 文本：一句短句，不含特殊控制字符。
• 图片：小尺寸、常见格式（如 JPEG/PNG），本地能正常打开。
• 音频：短时长、单声道、常见编码，本地播放器能播。
• 视频（如有）：短片段、低码率，先确认容器与编码被端点接受。

输入被拒时，保留报错原文再替换，而不是凭感觉换文件：提示体积或时长超限，就压缩或截断；提示格式或编码不支持，就用常规工具转码；提示资源不可达，就换成可访问地址或先下载再上传；提示内容为空或损坏，就换一个能正常打开的样本重试。每次替换只改一个条件，替换后重新记录这条输入的通过状态。

写回退规则：失败时退回上一步而不是重试整段

把回退写进流程，能减少反复整段重试。可以先按下面的顺序定，实际阈值结合你的环境再调。

停止继续尝试的边界建议写清楚：同一个报错在两步之内没有变化，就不要再改输入了；每次回退只改一个变量，回退后重新记录请求体与报错原文。这样即使问题最终出在环境或权限上，也能从记录里看出是何时从模态问题变成了非模态问题。