如何第一次上手NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-Base-BF16?下载、环境搭建与快速体验完整指南
如何第一次上手NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-Base-BF16?下载、环境搭建与快速体验完整指南
NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-Base-BF16 是 NVIDIA Nemotron 3.5 Super 系列的基座视觉-语言(Vision-Language)大模型:120B 总参数、12B 激活参数(MoE 混合专家)、Mamba-2 与 Transformer 混合架构,支持最长 1M token 上下文,BF16 精度,并内置 Multi-Token Prediction(MTP)用于原生投机解码。本文面向新手,带你完成从模型下载到环境搭建再到第一次跑通的完整流程,帮你避开上手过程中的常见坑。
一、动手前:用一张表看懂这个模型
在配置环境之前,先确认硬件是否够用。这个模型的“总参数 120B / 激活参数 12B”意味着:推理时每次前向只激活约 12B 参数(速度快),但完整权重(约 232 GiB,见 model.safetensors.index.json 中 total_size: 248906833944 字节)必须全部加载到显存/内存中(占地方)。
| 关键指标 | 数值 | 说明 |
|---|---|---|
| 总参数 / 激活参数 | 120B / 12B | MoE 稀疏激活,512 个路由专家(每层) |
| 精度 | BF16 | 权重约 232 GiB |
| 上下文长度 | 最高 1M tokens | 实际可用长度取决于显存 |
| 输入类型 | 文本、图片(JPEG/PNG)、视频(MP4,≤2 分钟) | 输出为纯文本 |
| 架构 | Mamba-2 + Attention + MoE 混合,C-RADIO 视觉编码器 | 详见 config.json |
| 推理框架 | PyTorch / Megatron-LM / NeMo / vLLM | 官方在 H100/H200/B200/B300/GB200/GB300 上测试过 |
| 授权协议 | OpenMDW-1.1 | 可用于商业与非商业用途 |
⚠️ 重要提示:这是 Base(基座)版本,适合继续预训练、SFT 微调、蒸馏等研发场景。如果你想直接做聊天、推理或工具调用,README 建议改用后训练版(BF16 或 NVFP4 发布)及其部署说明。
二、仓库文件清单:下载前先看目录里有什么
这个仓库就是一个标准的 Hugging Face 模型仓库,目录结构非常“规整”,新手只要认识这几类文件就够了:
| 文件 | 作用 |
|---|---|
| README.md | 模型总览、基准成绩、训练方法、下载方式(第一优先阅读) |
| config.json | 模型核心配置:层类型、专家数、视觉编码器参数等 |
| model-00001-of-00063.safetensors … model-00063-of-00063.safetensors | 模型权重,分 63 个 shard 存储 |
| model.safetensors.index.json | 权重分片索引(43078 个张量),加载器靠它拼回完整模型 |
| tokenizer.json / tokenizer_config.json | 分词器(vocab 131072)及其配置 |
| preprocessor_config.json | 图像/视频预处理器参数(patch_size=16、下采样等) |
| processor_config.json | 多模态 Processor 配置 |
| generation_config.json | 默认生成参数:do_sample=true、temperature=1.0、top_p=0.95 |
| chat_template.jinja | 对话模板,支持 enable_thinking 思考开关 |
| modeling_nemotron_h_omni.py | 模型实现(核心类 NemotronH_Omni_Reasoning_V3) |
| configuration_nemotron_h_omni.py | 配置类 NemotronH_Omni_Reasoning_V3_Config |
| processing_nemotron_h_omni.py | 多模态处理器 NemotronH_Omni_Reasoning_V3Processor |
| image_processing_nemotron_h_omni.py | 图像预处理(切 patch、归一化) |
| ultra_v3_reasoning_parser.py | vLLM 推理内容解析器(拆分思考与正文,注册名 ultra_v3) |
| safety.md / explainability.md / bias.md / privacy.md | 安全、可解释性、偏差与隐私子卡片 |
| Nemotron_3.5_Super_VL_EU_Training_Content_Summary.pdf | 欧盟合规要求的训练内容公开摘要 |
💡 小技巧:config.json 里的 auto_map 字段把 AutoModel、AutoProcessor 等都指向了上述本地 Python 文件,这就是为什么加载时通常需要 trust_remote_code=True(模型自带代码,官方在 config.json 中声明了映射关系)。
三、下载模型权重:最快方法
1. 使用 Hugging Face CLI(推荐)
README 中给出的官方下载命令如下,一条命令即可把 63 个权重分片全部拉下来:
hf download nvidia/NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-Base-BF16 \
--local-dir ./models/super-vl-base-bf16
下载后本地目录 ./models/super-vl-base-bf16/ 的内容与本仓库一致。注意预留 约 250 GB 磁盘空间。
2. 使用 git 方式获取仓库文件
如果只需要配置、代码和文档(不要权重),也可以直接克隆本镜像仓库:
git clone https://gitcode.com/hf_mirrors/nvidia/NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-Base-BF16
由于权重体积巨大,生产环境建议优先用
hf download并开启断点续传,而不是完整 clone。
3. 下载完成后的校验
- 权重应为
model-00001-of-00063.safetensors到model-00063-of-00063.safetensors共 63 个文件; - 每个分片大小可对照 model.safetensors.index.json 中的张量映射核对;
- 配置文件、分词器、processor 配置缺一不可,加载时才会正常工作。
四、环境搭建:硬件与软件准备
硬件要求
该模型专为 NVIDIA GPU 加速系统设计(Linux 环境),官方测试硬件覆盖 NVIDIA Hopper(H100、H200)与 Blackwell(B200、B300、GB200、GB300)。
一个实用的估算方式:BF16 权重约 232 GiB 必须装得下,加上 KV cache 与激活值,多卡集群是主流选择。单张 H100-80G 无法容纳完整权重。如果显存紧张,官方也提到部署方案可以通过缩短上下文窗口来适配可用 GPU 显存。
软件栈
| 组件 | 版本/说明 |
|---|---|
| 操作系统 | Linux |
| PyTorch | 官方 Runtime 引擎,需 CUDA 版本与 GPU 匹配 |
| transformers | 模型以 transformers_version: 5.8.1 发布(见 config.json) |
| 训练/微调框架 | Megatron-LM、NeMo |
| 推理服务 | vLLM(可配合 ultra_v3_reasoning_parser.py 解析思考内容) |
建议步骤:
- 创建独立 Python 环境(推荐 conda/venv);
- 安装匹配 GPU 的 PyTorch + CUDA;
- 升级 transformers 至 5.8.1 或更高;
- 把模型目录放进
HF_HOME缓存或显式指定--local-dir路径,避免重复下载。
五、快速体验:第一次跑通模型
由于模型使用了自带的 auto_map 代码,加载时需要 trust_remote_code=True。下面是最小的加载流程(新手只需理解四步:加载配置 → 加载分词器/处理器 → 加载模型 → 生成):
from transformers import AutoProcessor, AutoModelForImageTextToText
model_path = "./models/super-vl-base-bf16"
processor = AutoProcessor.from_pretrained(model_path, trust_remote_code=True)
model = AutoModelForImageTextToText.from_pretrained(
model_path,
torch_dtype="bfloat16",
device_map="auto",
trust_remote_code=True,
)
# 实际推理时,用 processor 把"文本+图片"编码后传给 model.generate()
几点说明:
- 输入形式:文本直接传字符串;图片支持 JPEG/PNG(RGB);视频支持 mp4 且不超过 2 分钟,按采样帧输入(见 README.md 的 Input 一节);
- 生成参数:仓库自带的 generation_config.json 默认
do_sample=true、temperature=1.0、top_p=0.95,直接复用即可; - 思考开关:chat_template.jinja 支持
enable_thinking参数,false时模型不产生思考过程; - 图像细节:preprocessor_config.json 中
patch_size=16、min_num_patches=1024、max_num_patches=13312,决定了图片被切成多少视觉 token,直接影响显存占用。
🧭 由于这是 Base 模型,第一次生成的文本质量可能不如后训练版,属于正常现象——它的价值在于作为继续训练与领域适配的起点。
六、新手必读:5 个常见坑与注意事项
- Base ≠ Instruct:这是基座检查点,官方明确建议聊天/推理/工具调用场景使用后训练版(BF16 或 NVFP4 发布),本模型面向继续预训练、SFT、RL 与蒸馏(见 README.md 的 Inference 一节)。
- 显存规划:完整权重约 232 GiB,
device_map="auto"可以自动切分到多卡,但上下文越长 KV cache 越吃显存,生产部署建议主动压缩上下文窗口。 - 授权协议:模型受 OpenMDW-1.1 协议约束,商用前请阅读协议条款(README.md 的 License 一节)。
- 安全护栏:作为经过指令相关训练的模型,它可能受不可信输入影响,官方在 safety.md 与 explainability.md 中提示需搭配防护栏与数据过滤;bias.md 和 privacy.md 分别说明偏差与隐私注意事项。
- 推理加速:模型内置 MTP 头(
num_nextn_predict_layers: 1,见 config.json),可原生做投机解码;在 vLLM 中配合 ultra_v3_reasoning_parser.py 的ultra_v3解析器,可以正确拆分"思考内容"和"最终回答"。
七、常见问题(FAQ)
Q1:为什么叫 A12B?120B 和 12B 是什么关系?
MoE 架构下,每个 MoE 层有 512 个路由专家(config.json 中 n_routed_experts: 512),每次只激活其中一部分,因此总参数 120B、每 token 实际激活约 12B——"A12B"即 Active 12B。
Q2:支持多长上下文?能一次读一整本书吗? 架构支持最高 1M token 上下文,训练阶段包含 35B token 的 1M 长上下文扩展 + 9B token 长上下文恢复。但实际可用长度受显存限制,可按部署需求调小窗口。
Q3:能输入视频吗?
可以。支持 mp4 视频(≤2 分钟),按帧采样处理;processor_config.json 中 video_maintain_aspect_ratio 等参数控制视频预处理行为。
Q4:微调用什么框架? 官方 Runtime 引擎包括 PyTorch、Megatron-LM、NeMo,可基于此 Base 检查点做继续预训练或领域适配。
总结
上手 NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-Base-BF16 的路径非常清晰:
- 看 README.md 与 config.json,确认硬件与用途;
- 下载 约 250 GB 权重(
hf download,63 个分片); - 搭环境:Linux + CUDA + PyTorch + transformers 5.8.1+;
- 跑通:
trust_remote_code=True加载模型与 Processor,用processor编码输入后generate; - 注意:它是面向继续训练的 Base 模型,交互类应用请选择后训练发布版。
按照这份指南,你应该已经完成了第一次下载、加载与生成。祝你的视觉-语言模型之旅顺利!🚀