NVIDIA-Nemotron-3.5-Super-VL-120B-A12B第一次上手:从下载到跑通第一个多模态问答的零基础教程
NVIDIA-Nemotron-3.5-Super-VL-120B-A12B第一次上手:从下载到跑通第一个多模态问答的零基础教程
NVIDIA-Nemotron-3.5-Super-VL-120B-A12B 是 NVIDIA 开源的多模态(视觉语言)大模型:吃进文本、图片、视频,输出文字答案。它总参数 120B、每次推理只激活 12B,支持最长 1M token 上下文。本文是一份零基础教程,带你从下载模型、校验文件,到用 transformers 加载并跑通第一个多模态问答,最后附上常见报错避坑指南。
30秒认识:Nemotron 3.5 Super VL 多模态大模型是什么 🧠
Nemotron 3.5 Super VL 主打推理、编程、工具调用、文档与视频理解,核心参数一览:
| 项目 | 说明 |
|---|---|
| 总参数 | 120B(激活 12B) |
| 架构 | Mamba-2 + Transformer 混合 MoE(混合专家) |
| 视觉编码器 | C-RADIO(ViT-Huge,32 层) |
| 上下文长度 | 最长 1M token |
| 输入 / 输出 | 文本 + 图片 + 视频 → 文本 |
| 精度 | BF16(全精度参考权重) |
| 推荐部署 | 4×H100 或 2×GB200 |
| 许可 | OpenMDW-1.1(可商用) |
两个关键数字先记住:
- MoE 让它快:虽然总参数 120B,但每个 token 只激活约 12B 参数,推理速度远好于同等规模的稠密模型。
- 思考可开关:默认会输出"思考过程",可通过聊天模板的
enable_thinking参数开启或关闭,见 chat_template.jinja。
模型的核心信息都写在 config.json 里:model_type 为 nemotron_h_omni,auto_map 字段把配置、模型、多模态处理器都指向了仓库内自带的本地代码,也就是说从本地目录加载时框架会自动使用这些代码,不需要你改任何东西。
第一步:一键下载 Nemotron 多模态模型(git clone)📥
整个仓库约 249 GB(权重索引 model.safetensors.index.json 中 total_size 约 248.9GB),推荐直接克隆:
git clone https://gitcode.com/hf_mirrors/unsloth/NVIDIA-Nemotron-3.5-Super-VL-120B-A12B
下载完成后,建议用仓库自带的 checksums.blake3 校验文件完整性,避免网络中断导致静默损坏:
# 如未安装:pip install blake3,然后进入模型目录执行
blake3 -c checksums.blake3
第二步:读懂模型文件夹:权重、配置与多模态处理器 📂
不用全背,了解每类文件的作用即可:
| 文件 | 作用 |
|---|---|
model-00001-of-00063.safetensors ~ model-00063-of-00063.safetensors |
模型权重,切成 63 片 |
| model.safetensors.index.json | 权重索引:记录每个参数在哪个分片 |
| config.json | 模型结构配置:MoE 层、视觉编码器、1M 上下文等 |
| tokenizer.json / tokenizer_config.json | 词表与编码规则 |
| chat_template.jinja | 聊天模板:把对话消息组织成模型提示词 |
| modeling_nemotron_h_omni.py / modeling_radio.py | 主模型与 C-RADIO 视觉编码器的本地建模代码 |
| processing_nemotron_h_omni.py / image_processing_nemotron_h_omni.py | 多模态处理器:把图/视频/文本统一转成模型输入 |
| generation_config.json | 默认采样参数(temperature=1.0,top_p=0.95) |
| ultra_v3_reasoning_parser.py | vLLM 推理解析器(ultra_v3),自动分离思考过程与答案 |
第三步:安装 transformers,准备运行多模态大模型 🛠️
需要准备 Python 3.10+ 和带 CUDA 的多卡 GPU 环境,然后安装两个核心库:
pip install -U transformers torch
注意:模型声明基于 transformers 5.12.1 生成(见 config.json 的 transformers_version),版本过低会在加载时报错。
⚠️ 硬件实话:本仓库是 BF16 全精度版本(约 249 GB),官方推荐 4×H100 或 2×GB200 部署。如果只有单张消费级显卡(如 4090/5090),直接加载会 OOM,需要改用量化版模型(如 unsloth 提供的 GGUF/FP8 量化),本文的加载流程完全通用。
第四步:跑通第一个 Nemotron 多模态问答(最小代码)🚀
新建一个 run_vl.py,十几行代码就能让模型"看图答题":
from PIL import Image
from transformers import AutoModelForImageTextToText, AutoProcessor
MODEL = "./NVIDIA-Nemotron-3.5-Super-VL-120B-A12B" # 改成你的本地模型目录
processor = AutoProcessor.from_pretrained(MODEL)
model = AutoModelForImageTextToText.from_pretrained(
MODEL,
device_map="auto", # 自动多卡分配
torch_dtype="auto", # BF16
)
# 准备"一张图 + 一个问题"
image = Image.open("chart.png") # 换成你自己的图片(jpg/png)
messages = [{"role": "user", "content": [
{"type": "image", "image": image},
{"type": "text", "text": "请解读这张图表:核心结论是什么?"},
]}]
# 多模态处理器:自动把 <image> 展开成对应数量的视觉 token
inputs = processor.apply_chat_template(
messages, tokenize=True, add_generation_prompt=True,
return_dict=True, return_tensors="pt",
).to(model.device)
output = model.generate(
**inputs,
max_new_tokens=1024,
temperature=0.6, # 官方推荐:视觉任务用 0.6
top_p=0.95,
)
print(processor.decode(output[0], skip_special_tokens=True))
执行 python run_vl.py,第一个多模态问答就跑通了。三个关键点:
<image>占位符:处理器会自动把提示词中的图片标记扩展成视觉 token,数量由 preprocessor_config.json 控制(min_num_patches=1024~max_num_patches=13312,图片会被自动下采样,防止上下文爆炸)。- 采样参数:纯文本对话推荐
temperature=1.0, top_p=0.95(即 generation_config.json 的默认值);视觉任务用temperature=0.6,回答更稳定。 - 视频也能问:处理器同样接受视频输入(mp4、2 分钟以内),用法与图片一致。
附:推理模式一键开关 💭
模型默认带"思考模式",输出会先给思考过程再给答案。需要关掉时,在调用 apply_chat_template 时传 enable_thinking=False 即可;用 vLLM 部署则传 chat_template_kwargs={"enable_thinking": False},输出中的思考内容会由 ultra_v3_reasoning_parser.py 注册的 ultra_v3 解析器自动分离。
常见报错与避坑指南(第一次运行必踩)🕳️
| 现象 | 原因与解决办法 |
|---|---|
加载时抛 OSError 或结构报错 |
transformers 版本太旧,不支持 nemotron_h_omni,升级即可:pip install -U transformers |
out of memory |
BF16 权重约 249 GB,单卡必 OOM:多卡用 device_map="auto",或换量化版模型 |
| 只输出思考过程、没有答案 | 思考模式开启且 max_new_tokens 太小,调大长度或关闭 enable_thinking |
| 回答"发飘" | 按官方推荐调采样:视觉 0.6 / 0.95,文本 1.0 / 0.95 |
| 下载后校验失败 | 断点续传重新拉取分片,再用 blake3 -c checksums.blake3 复查 |
进阶方向:微调、部署与长上下文 📈
- 微调 / 领域适配:这个 BF16 版本正是为自定义准备的基座,可按 README.md 的说明做领域适配与全精度评测;
- 部署提速:生产环境可切换 vLLM / SGLang 引擎,模型内置的 MTP(Multi-Token Prediction)头支持原生投机解码,进一步提速;
- 长上下文:1M token 上下文窗口,适合长文档分析、视频问答等场景。
🎉 恭喜!你已经完成了 Nemotron 3.5 Super VL 从"下载"到"第一个多模态问答"的完整旅程。