多模态输入怎样把图片与文本绑定同一请求

多模态请求里，图片和文字“都传上去了”并不代表它们还保持对应关系。更稳的做法是把一条用户消息建模成有序的 content 内容块列表：图片是 type=image，说明是 type=text，业务侧再用稳定的媒体 ID 维护每张图片的身份，最后按照目标模型的模板转换成真正可处理的消息。

官方文档：https://huggingface.co/docs/transformers/chat_templating_multimodal

先把“业务引用”和“模型输入”分成两层：业务层用 img_001 这类 ID 绑定图片与说明，模型层只接收它支持的 image/text 内容结构；不要直接依赖图片在数组里的临时下标。

先把一条请求拆成内容块

Hugging Face Transformers 的多模态文档把消息写成 role 加 content。与纯文本消息不同，多模态的 content 可以是多个不同类型的字典，例如一个图片块后面紧跟一段说明文字。这样做的价值不是让模型“自动猜编号”，而是让应用明确表达同一请求里有哪些媒体和文本。

下面的结构把两张图片和各自的说明放在同一个用户消息中。示例只展示输入形状，图片地址和模型名称应替换成你的实际资源与目标模型。

messages = [
    {
        "role": "user",
        "content": [
            # 图片块和说明文字保持相邻，表达同一请求中的观察对象与问题。
            {"type": "image", "url": "https://example.invalid/photo-a.jpg"},
            {"type": "text", "text": "请说明图片 A 中的主要对象。"},
            {"type": "image", "url": "https://example.invalid/photo-b.jpg"},
            {"type": "text", "text": "再比较图片 B 与图片 A 的差异。"},
        ],
    }
]

这里的 url 只是 Hugging Face 文档示例支持的一种图片来源写法；具体模型也可能使用本地路径、base64 或内存中的图片对象。真正的边界是：内容块的 type 和资源字段必须符合目标 Processor，而不是照抄一个与模型无关的 JSON。

为什么只保存数组下标容易错位

“第一张图片”“第二张图片”这种说法只在当前数组没有重排时成立。业务代码一旦做了去重、过滤、重试或异步上传，图片列表的下标就可能变化；文字仍然引用旧下标，模型收到的就会是图片 A 配图片 B 的说明。

更稳的方式是先建立应用层媒体表。每个媒体对象拥有稳定的 media_id，说明文字引用这个 ID；生成模型消息时，再把媒体对象解析为目标模型支持的 image 块，并把说明文字放到预期位置。这个 ID 是你自己的数据契约，不要把它误写成 Hugging Face 的通用协议字段。

from dataclasses import dataclass

@dataclass(frozen=True)
class Media:
    media_id: str
    source: str
    note: str


def build_content(media_items: list[Media]) -> list[dict]:
    content = []
    for item in media_items:
        # 先校验稳定 ID，避免上传重排后仍用旧数组下标关联说明。
        if not item.media_id or not item.source:
            raise ValueError("媒体必须包含 media_id 和 source")

        # ref 是应用层的追踪字段；提交给模型前应按目标模板转换或移除。
        content.append({"type": "image", "url": item.source, "ref": item.media_id})
        content.append({"type": "text", "text": f"[{item.media_id}] {item.note}"})
    return content


media_items = [
    Media("img_001", "https://example.invalid/photo-a.jpg", "描述图片 A"),
    Media("img_002", "https://example.invalid/photo-b.jpg", "描述图片 B"),
]
messages = [{"role": "user", "content": build_content(media_items)}]

注意，示例中的 ref 方便日志和业务追踪，但不保证被目标模型接受。实际发送前可以保留一份带 ID 的内部结构，再生成一份干净的模型 payload：

def to_model_content(content: list[dict]) -> list[dict]:
    model_content = []
    for block in content:
        # 只把目标 Processor 认识的字段交给模型，ref 留在应用日志中。
        if block["type"] == "image":
            model_content.append({"type": "image", "url": block["url"]})
        elif block["type"] == "text":
            model_content.append({"type": "text", "text": block["text"]})
        else:
            # 未知类型不能静默丢弃，否则引用表与真实请求会失去一致性。
            raise ValueError(f"不支持的内容类型：{block['type']}")
    return model_content

送入 Processor 前要检查什么

第一步检查引用完整性：每个媒体 ID 只能对应一份可解析的来源，说明文字不能引用不存在的 ID。第二步检查块顺序：如果产品约定“图片后紧跟说明”，就把这个约定写成组装函数，而不是在调用方手工拼列表。第三步检查模型边界：Hugging Face 文档说明，多模态 chat template 属于 Processor，模板会把图片块转换成模型所需的占位符和预处理输入。

模板差异不能靠猜

多模态 Processor 通常负责模板化、分词和图片预处理。官方写模板文档还特别提醒：有的模板会把图片占位符插入文字流，有的模型可能把图片统一放到用户消息末尾。因此，业务层可以固定自己的 media_id 和内容组装规则，但模型层必须加载目标 Processor 的实际模板。

如果使用 ImageTextToTextPipeline，可以直接传入符合模型要求的消息；如果使用 apply_chat_template() 和 generate()，则要把处理后的字典交给模型。不要因为某个模型示例使用了 url，就假定所有检查点、服务端适配器和自定义模板都接受完全相同的字段。

常见问题

把图片和文本放在同一个 content 列表就一定能绑定吗？

它能清楚表达一条消息中的内容关系，但最终排列仍由目标模型的 chat template 决定。要稳定绑定，还需要应用层 ID、组装规则和发送前检查。

可以直接给每个图片块增加 ref 字段吗？

可以在内部结构中保留，但不要把它当成通用模型协议。发送前应按目标 Processor 支持的字段转换，ID 留在日志、数据库或请求追踪信息中。

为什么不能只依赖图片列表的顺序？

过滤、去重、异步上传和重试都可能改变数组下标。稳定媒体 ID 让业务对象的身份不随列表重排而改变。

Processor 和 tokenizer 有什么区别？

纯文本聊天通常由 tokenizer 处理模板和文本；多模态输入还要处理图片等媒体，所以相关 chat template 通常配置在 Processor 上，并由它准备媒体输入。

小结：把多模态请求拆成明确的 image/text 内容块，用应用层稳定 ID 保持图片和说明的绑定，再在 Processor 边界按目标模型模板转换。这样排查时可以分别定位“引用错了”“列表拼错了”还是“模型模板不匹配”，而不是把所有问题都归结为模型看不懂图片。