query: 与 passage: 前缀的秘密：Nemotron-3.5-Embed-8B-BF16 的 Chat Template 检索提示机制详解

• 人工智能
• 大模型
• 基础模型
• Embedding
• 多模态
• RAG

Nemotron-3.5-Embed-8B-BF16 是 NVIDIA 推出的多模态检索向量（Embedding）模型，支持文本与文档图像输入。它表现出色的关键之一，就藏在query:与passage:这两个简短前缀，以及 Chat Template 如何将它们精准注入模型输入的机制里。本文面向新手，带你快速看懂这套检索提示机制，避开最常见的使用陷阱。

🧭 模型速览：它是什么

Nemotron-3.5-Embed-8B-BF16是一个基于 Transformer 的多模态双编码器（bi-encoder）检索模型，参数规模 8.38B，主要信息可在 README.md 中查到：

向量生成流水线由 modules.json 定义：Transformer → Pooling → Normalize，即先编码、再做 mean pooling（见 1_Pooling/config.json），最后 L2 归一化，这样余弦相似度就等于向量点积。

🔑 为什么必须有 query: 和 passage: 前缀？

双编码器模型在训练时，"查询"和"文档"是用不同的前缀分别学习编码的。模型需要知道：眼前这段文字是"一个问题"还是"一篇待检索的文档"，两者在语义空间里的表示方式并不相同。

官方在前置提示配置 config_sentence_transformers.json 中明确写死了这两个前缀：

"prompts": { "query": "query: ", "document": "passage: " }

对应关系一目了然：

如果漏掉前缀直接编码，向量会偏离训练时的分布，相似度排序的质量可能明显下降——这是新手使用检索向量模型时最容易踩的坑之一。

🧩 Chat Template 检索提示机制：逐段拆解

真正让前缀"注入"到模型输入的，是仓库中的 chat_template.jinja。它名为nemo-mistral-retrieval-v1（chat_template.jinja），由 Mistral Ministral-3 的对话模板改造而来，但专为检索场景做了三处关键设计：

第 1 步：system 消息 = 检索前缀

对话模板把system消息的内容当作检索前缀使用（chat_template.jinja）。模板会去掉前缀尾部多余空格再补一个空格，保证最终输出严格是query:或passage:——无论你是否多打了空格，渲染结果都一致。

调用方只需要构造两条消息：

messages = [ {"role": "system", "content": "query:"}, # 文档则写 "passage:" {"role": "user", "content": "What is NVIDIA NeMo Framework?"}, ] inputs = processor.apply_chat_template(messages, tokenize=True)

第 2 步：user 消息 = 查询或文档正文

user消息承载真正要编码的内容，渲染时有一个巧妙的"安全转义"：mark_user_text宏（chat_template.jinja）会在用户文本中的[和<后面插入一个零宽字符。这样即使文档正文里恰好出现[IMG]、[INST]这类标记，也不会被模型误认为特殊结构，属于防注入的细心思。

第 3 步：图像统一替换为 [IMG] 占位符

对于图文输入，模板会先把所有图像块规范化为[IMG]占位符（图像统一排在文本之前），再由处理器替换为真实视觉 token。图像相关的特殊 token（[IMG]、[IMG_BREAK]、[IMG_END]）定义在 tokenizer_config.json 中，图像处理器配置见 processor_config.json（默认最长边 1,120 像素）。

附加：严格的格式校验

模板只接受「一条 user 消息 + 可选的前置 system 前缀」这一种结构，其他形式会直接抛出异常（chat_template.jinja）：

Retrieval inputs require one user message with an optional leading system prefix

这个校验能帮你在调用阶段就发现消息结构写错的问题，而不是得到莫名其妙的低分结果。

还有一个容易被忽视的细节：与普通对话模型不同，这个模板刻意省略了[INST]/[/INST]等生成式对话包装和 BOS/EOS 特殊 token（chat_template.jinja 的注释说明了这一点），目的是让推理时的 token 序列与训练时逐 token 完全一致。这也是 vLLM 示例中要设置add_special_tokens=False的原因。

🛠️ 三种主流用法的差异对比

同一套前缀机制，在三种运行框架中的暴露方式不同：

Sentence Transformers 的两行调用最能体现"前缀自动化"：

query_embedding = model.encode_query([query]) # 自动加 "query: " doc_embeddings = model.encode_document([documents]) # 自动加 "passage: "

1_Pooling/config.json 中"include_prompt": true表示池化时会把前缀 token 一并纳入，这正是前缀影响最终向量的原因。

⚠️ 新手常见坑：3 个自查问题

1. 相似度整体偏低？先检查查询和文档是否分别使用了query:与passage:前缀，两边前缀不能互换。
2. 结果不如预期？确认没有绕过 Chat Template 直接拼接字符串；模板的转义与规范化（去多余空格、零宽字符插入）都是对齐训练数据的一部分。
3. 图文输入报错或超长？图像 token 也计入 32,768 的上下文上限，图像过大时调低分辨率即可；官方完整示例与示例输出（相关文档相似度约 0.58，无关文档约 0.25）见 README.md。

📂 相关核心文件一览

📌 小结

Nemotron-3.5-Embed-8B-BF16 的检索提示机制可以浓缩成三句话：查询加query:前缀，文档加passage:前缀；前缀由 Chat Template 统一注入并做 token 级对齐；不同框架下只需按各自方式声明输入类型即可。理解这套机制后，无论是搭建语义搜索还是多模态 RAG，你都能把模型的使用方式保持在它"最熟悉"的训练分布之内，从而拿到稳定的检索效果。

• 人工智能
• 大模型
• 基础模型
• Embedding
• 多模态
• RAG