先拆单路，是判断 Vivix 混合输入问题出在哪一层最省事的做法：把文本、图像、音频（按你实际接入的模态取）分别发成只含一路的请求，确认每一路单独可用；再按两两组合叠加，记录第一次失败出现在哪一组、失败在请求构造、服务端校验还是返回解析。整条请求反复重发只能看到“有时失败”，看不出是哪一路把结构顶坏了。

混合输入报错时，优先做单模态基线，而不是调整参数或重试整条请求。判断依据是：单路全部跑通后，冲突一定来自组合层，可把排查范围压到两两组合。操作上先固定一套单模态请求模板和返回结构记录，再做组合矩阵，把首次失败的原始请求与返回体留档。边界在于：单路跑通不代表组合可用，体积、字段互斥、模态顺序仍需组合测试确认；服务端行为以你的实际返回信息为准。

把混合输入拆成单模态请求逐一跑通

这一节的目标只有一个：拿到每一路单独调用时的请求形状、返回结构和耗时基线。没有基线，后面任何组合失败都说不清是新问题还是老问题。请求模板建议固定字段顺序和最小必填项，只替换内容部分，避免模板本身引入变量。下面是一个通用骨架，字段名按你实际使用的接入协议替换，不要直接照抄当成官方接口。

POST /v1/multimodal   # 路径按你的接入协议替换
Content-Type: application/json

{
  "model": "<model-name>",
  "input": [
    { "type": "text",  "text": "一段固定的短提示词，便于对比" }
  ]
}

图像和音频各跑一遍时，只把 input 数组里的元素换成对应模态，其他字段保持不变。建议每一路至少跑两次：一次用最小内容（短文本、小图、短音频），一次用接近业务实际的大小，用来区分“格式问题”和“体积问题”。记录表按下面的列填，够用就行：

• 模态：text / image / audio，一次只写一路。
• 请求要点：元素类型、编码方式（如 base64 或 URL 引用）、内容大小量级。
• 返回结构：顶层有哪些字段、内容放在哪个路径下、是否有错误字段。
• 端到端耗时：从发出到拿全响应的区间，不要写成精确单值。
• 失败情况：状态码、错误码、错误消息原文。

判断标准很朴素：三路单独都返回结构完整、可被你的解析代码正常取出内容，才算基线成立。任何一路单跑就失败，先解决它，别急着做组合。

两两组合叠加并记录首次失败的位置

基线成立后，不要再直接上三路混合。按两两组合推进，每次只加一路，出问题时变量只有一个。组合矩阵建议固定成下面几行，逐行执行并记录“首次失败位置”——是请求还没发出就构造失败，还是发出后服务端拒绝，还是返回 200 但解析不出来。

每个失败组合都要留下原始请求和原始返回，不要只记一句“报错了”。建议在客户端统一打日志，把请求体（大内容做截断或只记长度与类型）、状态码、响应体原文和请求标识一起落盘，便于回查：

# 通用日志骨架，伪代码，按你的语言替换
log.info("req_id=%s status=%s types=%s sizes=%s body=%s",
         resp.headers.get("x-request-id"),
         resp.status_code,
         [p["type"] for p in payload["input"]],
         [len(str(p)) for p in payload["input"]],
         resp.text[:500])

把失败组合按现象分成三类，比逐条读错误消息快：格式类（字段类型、编码不被接受）、体积类（内容过大、元素过多）、字段缺失类（某模态存在时另一字段变为必填）。多数“混着来就报错”的情况，落在这三类之一。

根据返回信息判断冲突落在哪一层

同样是失败，错误信息的来源决定你该改哪一端。可以先按返回形态分四类，再逐类做初步归因：

1. 本地构造失败：请求还没发出，序列化或必填校验就抛错。归因在你自己的请求组装代码，不属于服务端行为。
2. 4xx 且消息指向字段结构：通常是字段名、类型、层级放错，或某模态要求独立字段而不是混在数组里。归因在请求构造，需要对照单模态基线逐字段比对。
3. 4xx 且消息指向内容或体积：编码方式不对、大小超限、元素条数超限。归因在内容准备环节，优先做压缩、裁剪或分次提交的评估。
4. 5xx 或超时：先不要改请求结构，用同一份请求重放确认是否稳定复现；稳定复现再把该组合标记为待确认，避免误判成格式问题。

还有一类容易漏掉：状态码 200 但你的解析代码取不到内容。这通常不是服务端拒绝，而是返回结构在不同模态组合下发生了变化，比如内容被包在另一层或换成了引用形式。处理方式是保留完整响应体，对比单模态基线的字段路径。

把确认有问题的组合写成调用前校验

定位清楚的组合，不要只写在文档里，落成调用前校验，让同类错误在本地就暴露，省掉一次无效调用。校验只做“确定会失败”的判断，不做模糊猜测，避免误伤正常请求。下面是通用骨架：

# 调用前校验骨架，规则按你确认过的失败组合补充
MAX_ELEMENTS = 8          # 按实际限制调整
MAX_TOTAL_CHARS = 200000  # 占位阈值，用你确认过的上限替换

def validate_input(items):
    types = [i.get("type") for i in items]
    if len(items) > MAX_ELEMENTS:
        raise ValueError("输入元素过多：%d，上限 %d" % (len(items), MAX_ELEMENTS))
    if "image" in types and "text" not in types:
        raise ValueError("image 需要搭配 text 提示词，当前缺失")
    total = sum(len(str(i)) for i in items)
    if total > MAX_TOTAL_CHARS:
        raise ValueError("输入总体积过大：%d，建议裁剪后再提交" % total)
    for i in items:
        if i.get("type") not in ("text", "image", "audio"):
            raise ValueError("未知模态类型：%r" % i.get("type"))

触发校验后的处理要提前定好，不要临时决定。常见做法是：提示里直接写清哪一路、哪条规则、建议动作；同时提供降级路径，比如把混合请求拆成先文本后图像的分步调用，或暂时只保留文本一路返回结果，并在返回体里标出被省略的模态。降级必须是显式标注的，不能让调用方以为拿到了完整结果。

校验规则本身也要跟着实际情况走：每确认一个新的失败组合，就补一条规则，并保留原始错误样例作为回归用例。规则写得越贴近实际报错，本地拦截越准；凭感觉加的规则，反而会把可用请求拦下来。