NVIDIA Llama-Nemotron-Colembed-VL-3B-V2 API完全指南：查询、文档与图像嵌入的最佳实践

【免费下载链接】llama-nemotron-colembed-vl-3b-v2项目地址: https://ai.gitcode.com/hf_mirrors/nvidia/llama-nemotron-colembed-vl-3b-v2

NVIDIA Llama-Nemotron-Colembed-VL-3B-V2是一款强大的多模态嵌入模型，专为查询-文档检索优化，支持文本查询与图像文档的嵌入生成，通过ColBERT风格的多向量数值表示实现高效的跨模态检索。本指南将帮助您快速掌握其API使用方法、核心功能与最佳实践。

🌟 模型核心优势与应用场景

✨ v2版本关键改进

• 高级模型融合：通过训练后模型合并技术，结合多个微调检查点的优势，在不增加推理延迟的情况下实现集成模型的精度稳定性
• 增强合成数据：显著丰富了训练数据中的多语言合成数据，提升跨语言和复杂文档类型的语义对齐能力

🚀 典型应用场景

• 多模态RAG系统：处理文本查询与图像文档（如页面、图表、表格、信息图）的检索
• 多媒体搜索引擎：构建跨文本和图像的内容检索系统
• 对话式AI：增强对富媒体输入的理解能力

📋 模型基础架构与技术规格

🔧 架构组成

Llama-Nemotron-Colembed-VL-3B-V2基于Transformer架构，由以下组件构成：

• 视觉编码器：google/siglip2-giant-opt-patch16-384
• 语言模型：meta-llama/Llama-3.2-3B
• 总参数量：约4.4B

📊 输入输出规格

输入类型与格式：

• 文本：字符串列表（一维）
• 图像：RGB格式的PIL图像列表（二维）

图像处理特性：

• 每张图像切片消耗256 tokens
• 默认配置：max_input_tiles = 8，use_thumbnails = True
• 图像会被分割为最多8个切片+1个缩略图（低分辨率完整图像）

输出规格：

• 输出类型：浮点数数组
• 输出形状：[batchsize x seq length x embedding_dim]
• 嵌入维度：3072维

🛠️ 快速开始：安装与基础使用

🔍 环境准备

首先安装必要的依赖包：

pip install "transformers>=4.45.0" pip install flash-attn==2.6.3 --no-build-isolation

根据环境可能需要升级额外依赖：

pip install -U datasets polars pip install -U pydantic

📥 模型加载

使用transformers库加载模型：

import torch from transformers import AutoModel model = AutoModel.from_pretrained( 'nvidia/llama-nemotron-colembed-vl-3b-v2', device_map='cuda', trust_remote_code=True, torch_dtype=torch.bfloat16, attn_implementation="flash_attention_2" ).eval()

📝 文本查询嵌入

生成文本查询的嵌入向量：

queries = [ 'How is AI improving the intelligence and capabilities of robots?', 'Canary, a multilingual model that transcribes speech in English, Spanish, German, and French with punctuation and capitalization.', 'Generative AI can generate DNA sequences that can be translated into proteins for bioengineering.' ] query_embeddings = model.forward_queries(queries, batch_size=8)

🖼️ 图像文档嵌入

处理图像并生成嵌入向量：

from transformers.image_utils import load_image image_urls = [ "https://developer.download.nvidia.com/images/isaac/nvidia-isaac-lab-1920x1080.jpg", "https://developer-blogs.nvidia.com/wp-content/uploads/2024/03/asr-nemo-canary-featured.jpg", "https://blogs.nvidia.com/wp-content/uploads/2023/02/genome-sequencing-helix.jpg" ] images = [load_image(img_path) for img_path in image_urls] image_embeddings = model.forward_images(images, batch_size=8)

🔗 计算相似度分数

获取查询与图像文档之间的相似度分数：

scores = model.get_scores( query_embeddings, image_embeddings ) print(scores) # tensor([[10.9662, 10.6623, 10.0281], # [17.7323, 18.6031, 17.7613], # [13.2915, 13.6993, 13.7968]], device='cuda:0')

📚 API详细解析

🔤 文本处理方法

forward_queries(queries, batch_size=8)

• 功能：处理文本查询并生成嵌入向量
• 参数：
  • queries：字符串列表或DataLoader
  • batch_size：批处理大小，默认为8
• 返回：形状为(num_queries, max_seq_len, hidden_dim)的张量

🖼️ 图像处理方法

forward_images(images, batch_size=8)

• 功能：处理图像文档并生成嵌入向量
• 参数：
  • images：PIL图像列表
  • batch_size：批处理大小，默认为8
• 返回：形状为(num_images, max_seq_len, hidden_dim)的张量

forward_documents(corpus, batch_size=8)

• 功能：处理包含图像和文本的文档
• 参数：
  • corpus：字典列表，每个字典包含"image"和"text"键
  • batch_size：批处理大小，默认为8
• 返回：文档嵌入张量

🔍 检索评分方法

get_scores(query_embeddings, passage_embeddings, batch_size=128)

• 功能：计算查询与文档嵌入之间的ColBERT MaxSim分数
• 参数：
  • query_embeddings：查询嵌入张量或张量列表
  • passage_embeddings：文档嵌入张量或张量列表
  • batch_size：计算批次大小，默认为128
• 返回：形状为(num_queries, num_passages)的分数矩阵

⚙️ 配置参数详解

模型配置可通过configuration_llama_nemotron_vl.py文件查看和调整，关键参数包括：

📝 文本处理配置

• q_max_length：查询最大长度，默认为512
• p_max_length：文档最大长度，默认为10240
• query_prefix：查询前缀，默认为"query:"
• passage_prefix：文档前缀，默认为"passage:"

🖼️ 图像处理配置

• max_input_tiles：最大图像切片数，默认为2
• use_thumbnail：是否使用缩略图，默认为False
• dynamic_image_size：是否使用动态图像大小，默认为False
• min_dynamic_patch/max_dynamic_patch：动态补丁大小范围

🧠 模型架构配置

• select_layer：选择提取特征的层，默认为-1（最后一层）
• pooling：池化方式，默认为"last"
• bidirectional_attention：是否使用双向注意力，默认为False

📊 评估与性能

📈 基准测试结果

Llama-Nemotron-Colembed-VL-3B-V2在ViDoRe（Visual Document Retrieval）基准测试中表现优异：

注：ViDoRe V1和V2的精度以NDCG@5报告，ViDoRe V3以NDCG@10报告

📉 运行评估脚本

使用MTEB 2库评估模型性能：

pip install "mteb>=2.6.0, <3.0.0" # 评估ViDoRe V1和V2 CUDA_VISIBLE_DEVICES=0; python3 mteb2_eval.py --model_name nvidia/llama-nemotron-colembed-vl-3b-v2 --batch_size 16 --benchmark "VisualDocumentRetrieval" # 评估ViDoRe V3 CUDA_VISIBLE_DEVICES=0; python3 mteb2_eval.py --model_name nvidia/llama-nemotron-colembed-vl-3b-v2 --batch_size 16 --benchmark "ViDoRe(v3)" # 评估ViDoRe V3特定任务 CUDA_VISIBLE_DEVICES=0; python3 mteb2_eval.py --model_name nvidia/llama-nemotron-colembed-vl-3b-v2 --batch_size 16 --benchmark "ViDoRe(v3)" --task-list Vidore3ComputerScienceRetrieval

💡 最佳实践与优化建议

🔧 性能优化

1. 硬件加速：

   • 推荐使用NVIDIA Ampere (A100)或Hopper (H100) GPU
   • 启用Flash Attention 2加速注意力计算

2. 批处理策略：

   • 根据GPU内存调整批处理大小，A100 40GB建议批大小为16-32
   • 对长文档使用动态批处理以提高吞吐量

3. 内存管理：

   • 使用torch.bfloat16dtype减少内存占用
   • 对大型图像集采用渐进式加载策略

📝 使用技巧

1. 文本查询优化：

   • 保持查询简洁，关键信息放在句首
   • 使用领域特定术语提高检索精度

2. 图像处理建议：

   • 确保图像分辨率至少为512x512
   • 对复杂文档（如多图表PDF）先分割为单页图像

3. 检索系统构建：

   • 结合FAISS或Annoy等向量数据库实现高效检索
   • 对嵌入向量进行归一化以提高相似度计算稳定性

📄 许可证与引用

📜 许可证信息

本模型的使用受NVIDIA Non-Commercial License Agreement约束，适用于非商业/研究用途。模型基于Meta Llama 3.2构建，Llama 3.2受Llama 3.2 Community License约束。

📚 引用格式

@misc{moreira2026_nemotron_colembed_v2, title={Nemotron ColEmbed V2: Top-Performing Late Interaction embedding models for Visual Document Retrieval}, author={Gabriel de Souza P. Moreira, Ronay Ak, Mengyao Xu, Oliver Holworthy, Benedikt Schifferer, Zhiding Yu, Yauhen Babakhin, Radek Osmulski, Jiarui Cai, Ryan Chesler, Bo Liu, Even Oldridge}, year={2026}, eprint={2602.03992}, archivePrefix={arXiv}, primaryClass={cs.IR}, url={https://arxiv.org/abs/2602.03992}, }

🔗 相关资源

• 模型文件：

  • modeling_llama_nemotron_vl.py - 模型架构实现
  • config.json - 模型配置参数
  • processor_config.json - 处理器配置

• 评估脚本：

  • mteb2_eval.py - MTEB基准测试脚本
  • vidore_eval.py - ViDoRe基准测试专用脚本

• ** tokenizer文件**：

  • tokenizer.json
  • tokenizer_config.json
  • special_tokens_map.json

【免费下载链接】llama-nemotron-colembed-vl-3b-v2项目地址: https://ai.gitcode.com/hf_mirrors/nvidia/llama-nemotron-colembed-vl-3b-v2