如何快速上手NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-BF16:面向初学者的完整入门指南
如何快速上手NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-BF16:面向初学者的完整入门指南
NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-BF16 是 NVIDIA 开源的 Nemotron 3.5 Super VL 视觉语言大模型(BF16 全精度权重),它支持文本、图片和视频输入,主打推理、编程、工具调用、文档与视频理解,并支持最长 1M tokens 的上下文。本指南面向初学者,用最少的步骤带你完成下载、部署、调用,让你几分钟内理解这个模型能做什么、怎么跑起来。
一、Nemotron 3.5 Super VL 是什么?🤔
简单来说,它是一个"能看图、能看视频、会思考、会写代码"的大模型。BF16 版本是全精度参考权重,适合微调、领域适配和全精度评测;如果你追求推理速度,官方还提供压缩版的 NVFP4 版本(此处仅 BF16 仓库)。
| 项目 | 参数 |
|---|---|
| 总参数量 | 120B(实际激活 12B) |
| 架构 | Mamba-2–Transformer 混合 + MoE 专家混合 + C-RADIO 视觉编码器 |
| 精度 | BF16(全精度参考权重) |
| 上下文长度 | 最高 1M tokens |
| 输入 / 输出 | 文本、图片(jpeg/png)、视频(mp4 ≤2 分钟) / 文本 |
| 部署硬件 | 4× H100 或 2× GB200 |
| 推测解码 | 原生 MTP(Multi-Token Prediction) |
| 推理模式 | 可配置(enable_thinking 开关) |
| 许可证 | OpenMDW-1.1(可商用) |
💡 "120B 总参数 / 12B 激活"意味着:模型知识容量很大,但每次推理只激活一小部分专家,速度和显存开销远低于同规模的稠密模型。
二、仓库文件结构一览 📁
在开始部署前,先认识仓库里的关键文件,知道"谁是谁"能少走很多弯路:
| 文件 | 作用 |
|---|---|
| README.md | 模型卡:介绍、部署命令、基准测试全在这里 |
| config.json | 模型主配置(层结构、MoE、视觉编码器参数) |
| modeling_nemotron_h_omni.py | 语言主干 + 多模态模型的 PyTorch 实现 |
| configuration_nemotron_h_omni.py | 对应的配置文件定义 |
| modeling_radio.py / configuration_radio.py | C-RADIO 视觉编码器实现与配置 |
| processing_nemotron_h_omni.py / image_processing_nemotron_h_omni.py | 多模态处理器与图像预处理 |
| chat_template.jinja | 对话模板(控制思考模式输出格式) |
| tokenizer.json / tokenizer_config.json | 分词器及其配置 |
| generation_config.json | 默认生成参数(temperature 1.0、top_p 0.95) |
| preprocessor_config.json / processor_config.json | 图像预处理器与整体处理器配置 |
| model.safetensors.index.json | 权重分片索引(共 63 个 safetensors 分片) |
| safety.md / bias.md / privacy.md / explainability.md | 安全、偏见、隐私与可解释性说明 |
如果需要把仓库拉到本地:
git clone https://gitcode.com/hf_mirrors/nvidia/NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-BF16
三、3 分钟看懂架构 🏗️
想深入可以看 config.json,这里只讲人话版:
- Mamba-2 层:负责高效地处理长上下文,是"省内存的长记忆担当"。
- Transformer 注意力层:每隔若干层插入,用于精确实时检索信息。
- MoE 专家层:每层有 512 个路由专家,每个 token 只激活 22 个(见
num_experts_per_tok字段),这就是"总参数大、激活参数小"的秘密。 - C-RADIO 视觉编码器:把图片、文档页、视频帧转成语言模型能理解的特征。
- MTP 头:递归预测未来 token,实现原生推测解码,让生成更快,无需额外下载草稿模型。
四、部署前的硬件与软件准备 🖥️
| 硬件 | 运行时 | 说明 |
|---|---|---|
| 4× H100 | vLLM / SGLang | 张量并行 TP4,支持 1M 上下文 |
| 2× GB200 | vLLM / SGLang | 张量并行 TP2,支持 1M 上下文 |
软件要求:Linux 系统 + NVIDIA GPU + Docker。推荐的容器镜像:
- vLLM:
vllm/vllm-openai:nightly-3f1bcfd82bb2e93fcd364fc7a5491718453a77e2或vllm/vllm-openai:v0.32.0 - SGLang:
lmsysorg/sglang:nemotron3-5-super
⚠️ 如果模型下载需要认证,请在启动容器前先设置
HF_TOKEN环境变量。
五、vLLM 快速启动:一条命令跑起来 🚀
以 4× H100 为例(2× GB200 只需把 --tensor-parallel-size 改为 2):
export MODEL=nvidia/NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-BF16
vllm serve $MODEL \
--served-model-name nemotron-3.5-super-vl \
--tensor-parallel-size 4 \
--trust-remote-code \
--async-scheduling \
--allowed-local-media-path=/ \
--max-num-seqs 32 \
--enable-mamba-shared-prefix-checkpoint \
--limit-mm-per-prompt '{"video": 1, "image": 1}' \
--video-pruning-rate 0.5 \
--media-io-kwargs '{"video": {"fps": 2, "num_frames": 256}}' \
--enable-auto-tool-choice \
--tool-call-parser qwen3_coder \
--reasoning-parser nemotron_v3 \
--speculative_config.method mtp \
--speculative_config.num_speculative_tokens 5
等模型加载和内核编译完成后,用下面命令验证服务是否就绪:
curl --fail http://localhost:8000/v1/models
看到返回的模型列表,说明服务已经成功上线 ✅。几个参数的小贴士:
--trust-remote-code:必须加,因为模型带自定义代码文件。--reasoning-parser nemotron_v3:解析思考内容,配合"推理模式"使用。- 视频默认按 2 FPS 采样、最多 256 帧;1080p 视频建议降到 1 FPS / 128 帧。
SGLang 用户可以直接用 README.md 中的 sglang serve 配方,核心差异是它使用 --speculative-algorithm EAGLE 来启用推测解码。
六、API 调用:文本、图片、视频、工具调用 💬
服务启动后,用任意 OpenAI 兼容客户端即可调用:
pip install openai
文本 + 推理模式(开启"思考")
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")
response = client.chat.completions.create(
model="nemotron-3.5-super-vl",
messages=[{"role": "user", "content": "解释为什么二分查找是 O(log n) 的。"}],
temperature=1.0,
top_p=0.95,
max_tokens=16384,
extra_body={"chat_template_kwargs": {"enable_thinking": True}},
)
print(response.choices[0].message.content)
推理强度有三档:关闭 / 中档(medium)/ 全开。中档写法:
extra_body={"chat_template_kwargs": {"enable_thinking": True, "medium_effort": True}}
图片理解:把本地图片读入、转成 base64 数据 URL,放入 image_url 字段即可(参考 README.md 的 Images 小节)。
视频理解:同样用 base64 数据 URL,放入 video_url 字段,模型会按顺序总结视频事件。
工具调用:服务已开启 --enable-auto-tool-choice,请求里带 tools 参数,模型就会发起 tool call,你的程序执行后把结果回传即可。
七、推荐采样参数速查表 ⚙️
| 场景 | temperature | top_p |
|---|---|---|
| 纯文本任务 | 1.0 | 0.95 |
| 视觉任务(图片/视频) | 0.6 | 0.95 |
注意两点:
- 思考 token 和最终答案共享
max_tokens预算,如果返回finish_reason == "length",请调大输出预算。 - 默认生成参数见 generation_config.json:
do_sample: true、temperature: 1.0、top_p: 0.95。
八、性能表现:基准测试亮点 📊
官方用 NeMo Gym 评测,与同级别模型对比相当能打(摘自 README.md):
| 基准 | Nemotron 3.5 Super VL | 说明 |
|---|---|---|
| GPQA-Diamond | 89.52 | 研究生级科学问答 |
| LiveCodeBench v6 | 88.22 | 竞赛级编程 |
| SWE-bench Verified | 71.10 | 真实代码库问题修复 |
| GraphWalks | 89.71 | 长上下文知识图谱推理 |
| OCRBench v2(英文) | 68.12 | 视觉 OCR 能力 |
| Video-MME v2 | 32.85 | 视频理解 |
九、常见问题与注意事项 ❓
- 显存不够? 1M 上下文的完整部署建议 4× H100 起步;日常短上下文场景可适当降低并发与序列数。
- 加载报架构不识别? 确认加了
--trust-remote-code,并使用了支持该模型的 vLLM 镜像版本。 - 响应被截断?
max_tokens太小,思考过程会先消耗预算。 - 商业用途? 可以,模型采用 OpenMDW-1.1 许可,商用与学术均可;使用前建议阅读 safety.md 了解安全边界,模型对指令注入较敏感,生产环境请配合护栏使用。
- 想要更高吞吐? 阅读 README.md 中提到的 NVFP4 量化版本说明,用更低的精度换取更快的推理。
恭喜你,已经完成了 NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-BF16 的完整入门之旅 🎉:认识模型 → 看懂仓库 → 部署服务 → 四类 API 调用 → 调参优化。下一步可以尝试开启推理模式跑一个文档理解任务,或用自己的领域数据做适配微调。