多模态输入、能力矩阵与兼容边界

“支持模型 API”不是一个足够具体的结论。应用要知道某个模型、版本、区域和认证入口是否同时支持文本、图片、文件、工具、结构化输出、流式和缓存；还要记录哪些组合没有验证。能力矩阵的作用是让适配器在请求前做选择，而不是在异常发生后猜测。

用显式矩阵拒绝未知组合

CAPABILITIES = {
    ('provider-a', 'model-1'): {
        'text': True, 'image': True, 'file': False,
        'tools': True, 'structured': True, 'stream': True,
    },
    ('provider-b', 'model-2'): {
        'text': True, 'image': False, 'file': False,
        'tools': True, 'structured': False, 'stream': True,
    },
}

def require_capability(provider, model, requested):
    caps = CAPABILITIES.get((provider, model))
    if caps is None:
        raise LookupError('unverified model')
    missing = sorted(name for name in requested if not caps.get(name, False))
    if missing:
        raise ValueError(f'unsupported capabilities: {missing}')
    return caps

assert require_capability('provider-a', 'model-1', {'text', 'image', 'tools'})['image']
try:
    require_capability('provider-b', 'model-2', {'text', 'image'})
except ValueError as error:
    assert 'image' in str(error)
else:
    raise AssertionError('unsupported image accepted')

矩阵中的 True 只表示在指定版本和测试条件下通过了协议验证，不表示模型质量、延迟或内容安全已经达标。缓存命中、区域路由、批处理和推理预算也可能改变结论，应把它们作为额外维度，而不是在一个“支持”字段里合并。

多模态的输入和证据责任

图片或文件至少需要 MIME、大小、来源 ID 和保留策略。扩展名不能证明文件内容，base64 也不等于授权；服务端仍需检查租户、内容类型、大小和恶意载荷。把图片说明复制进文本会丢失原始媒体与模型对齐关系，除非降级路径明确声明只保留抽取后的文本。

变化实验：能力变化后的降级

当 image 不受支持时，应用可以拒绝并说明原因、调用视觉模型后端，或先用受控 OCR/解析器生成带来源的文本。不能静默把图片忽略后继续回答，因为用户会误以为模型看到了图片。降级结果必须携带 degraded=True 和来源版本，交给业务决定是否允许提交。

练习

1. 给矩阵增加 region、api_version 和 auth_mode 三个维度，未知组合必须拒绝。
2. 编写 choose_fallback，在图片不支持时返回“拒绝/视觉后端/OCR”三种显式结果，禁止返回普通文本回答。
3. 设计一次能力重验记录：保存测试输入、响应状态、SDK 版本和时间；说明模型退役或 SDK 升级时为什么必须重新运行。

本章完成后继续流式、结构化输出与工具执行。