NVIDIA Nemotron 完整教學

一句話定位：NVIDIA 官方為 Nemotron 模型家族（Nano / Super / Ultra 三層 + Nano Omni 多模態變體）建的 Developer Asset Hub — 一站式包含 (1) 可重現的訓練 recipes（pretrain → SFT → RL）、(2) 部署 cookbook、(3) RAG / Agent / SQL LoRA / Voice 等完整 use-case、(4) nemotron-customize Claude Code 插件讓自然語言組合 pipeline，整合 NVIDIA AI 全家桶（NeMo-Curator / NeMo-RL / Megatron-Bridge / Automodel / Evaluator / DataDesigner）。

適合：要訓練 / 微調 production LLM、要在 NVIDIA 平台跑大規模分散式訓練、要復現 SOTA 訓練配方、想用 Claude Code 加速 pipeline 配置、做 multimodal agent / RAG / tool calling production 應用的工程師與研究員。

不適合：完全沒 GPU 的人（部分 step 可純 CPU 跑，但整套 recipes 需要 8-1024 GPU）；只想 inference 不想訓練的人（改看 HuggingFace 的 Nemotron 模型卡或 vLLM / SGLang 文件）。

⚠️ 重要法律提醒：repo 本身 LICENSE 為 Apache-2.0，但 模型權重大多是 NVIDIA Open Model License（NOML），與 Apache-2.0 不同。商用前須個別檢查每個模型權重的授權條款。

目錄

  1. 專案定位
  2. 安裝指南
  3. 核心架構解析
  4. Helper Scripts 詳細用法
  5. 應用場景：5 條 recipe + 9 個 cookbook + 7 個 use-case
  6. 資安掃描報告
  7. FAQ
  8. 進階技巧
  9. 整合進其他工作流
  10. 重點摘要 Checklist
  11. 進一步閱讀

1. 專案定位

1.1 這是什麼

NVIDIA-NeMo/Nemotron 是 NVIDIA 對外打包的 Nemotron 模型家族開發資源中樞。它不是「一個模型」也不是「一個訓練框架」，而是：

 1┌─────────────────────────────────────────────────────────────┐
 2│ Nemotron Developer Asset Hub                                │
 3├─────────────────────────────────────────────────────────────┤
 4│ (1) Training Recipes  →  完整可重現訓練流程（open data 子集）   │
 5│ (2) Steps             →  15 個 modular building block        │
 6│ (3) Usage Cookbooks   →  9 個模型 ×部署 / inference 指南      │
 7│ (4) Use-Case Examples →  7 個 end-to-end 應用範例             │
 8│ (5) Claude Skills     →  7 個 Claude Code skill              │
 9│ (6) Open Datasets     →  指向 HF 上 30+ Nemotron 開放 dataset │
10└─────────────────────────────────────────────────────────────┘

它把 NVIDIA NeMo 全棧（NeMo-Curator 資料處理、NeMo-RL 強化學習、Megatron-Bridge Megatron 訓練、Automodel HF 模型訓練、Evaluator 評估、DataDesigner 合成資料）串成可運行的端到端流程，並提供 CLI（nemotron）統一介面。

1.2 Nemotron 模型家族總覽

三層 + 多模態變體

層級代表模型參數量（active / total）主要用途
NanoNemotron 3 Nano3.6B / 31.6B（MoE）Edge / PC 部署
SuperNemotron 3 Super12B / 120B（MoE）單 GPU 高吞吐
UltraNemotron 3 Ultra未公開多 GPU 資料中心
Omni（多模態變體）Nemotron 3 Nano Omni3B / 30B（MoE）文字 + 圖像 + 影片 + 音訊 agentic perception

架構共同點

所有 Nemotron 3 系列都是 Hybrid Mamba-Transformer Mixture-of-Experts (MoE)：

  • Mamba layers：負責序列 / 記憶效率（長 context）
  • Transformer layers：負責 reasoning
  • MoE：active 參數 « total 參數，推論時只啟動部分 expert
  • Latent MoE（Super 系列）：在低維 latent space 做 expert routing，記憶體更省

關鍵差異：

模型架構特色
Nemotron 3 SuperHybrid Mamba Latent MoE Transformer，120B 總參數 / 12B active；21 個 reward env 多領域 RL
Nemotron 3 Nano標準 hybrid Mamba-MoE；25T pretraining tokens；context 1M；MMLU / agentic benchmark 強
Nemotron 3 Nano Omni30B-A3B；加上 C-RADIOv4-H 視覺 encoder + Parakeet 音訊 encoder + EVS（Efficient Video Sampling）影片管線；context progressive scaling 16K → 49K → 262K

1.3 在 LLM 訓練教材生態系的位置

教材類型代表風格Nemotron 對比
NVIDIA 官方訓練 hub本 repo完整可重現、整合 NeMo 全棧、reference impl—
HuggingFace TRL / Transformers examplestrl-examples / transformers/examples入門優先、單 stageNemotron 涵蓋 pretrain + SFT + RL，TRL 主要 RL
EleutherAI gpt-neox / Megatron-DeepSpeed純訓練框架框架優先、recipe 較少Nemotron 是 recipe 優先、框架是上游
llama-recipes（Meta）meta-llama/llama-recipesLlama 系列 fine-tune cookbookNemotron 同質但完整度 + 規模更大
Mistral fine-tuning examplesmistralai/mistral-finetuneLoRA SFT 為主Nemotron 額外有 RL + multimodal

Nemotron 的賣點：production-grade、跟著官方 tech report 走、有 multi-environment RLVR / SWE-RL / GenRM-RLHF 等業界最前沿配方。

1.4 統計資料快照（2026-06-02）

指標數值
Stars1,200
Forks264
Default branchmain
Created2025-10-03
Last commit2026-06-01
Latest releasev0.1.0（2026-03-24）
Open issues30
Python 檔案594
Markdown 文件372（含每章 README）
YAML config157
Jupyter notebook36
Repo 大小56 MB
主要語言Jupyter Notebook
License（repo）Apache-2.0（但 pyproject 寫 MIT — §6.2.1）
模型權重 License多為 NVIDIA Open Model License (NOML)
維護者NVIDIA Nemotron Team

2. 安裝指南

2.1 環境需求

  • Python：3.10 - 3.13（pyproject 限制 >=3.10,<3.14）
  • 包管理器：uv（強烈推薦；專案 uv.lock 完整鎖定 1.1 MB 依賴）
  • GPU：根據用途差異很大
    • 跑 nemotron-customize skill：CPU 即可
    • inference 小模型：1×24 GB GPU（4090 / A6000）
    • 復現 Nano3 完整 recipe：8-64 GPU（A100 / H100）
    • 復現 Super3 完整 recipe：512-1024 GPU（asynchronous GRPO at 1K GPU scale）
  • CUDA：依 Docker image 而定（CUDA 12.x / 13.x 都有 issue 紀錄）

2.2 三種使用模式

模式 A：作為 Claude Code 插件（最輕量）

1# 在 Claude Code 內
2/plugin marketplace add NVIDIA/Nemotron
3/plugin install nemotron-customize@nvidia-nemotron

接著在 repo 根目錄啟動 Claude Code：

1cd /path/to/Nemotron        # 必須含 pyproject.toml 與 src/nemotron/steps/
2claude

然後在 Claude 內：

1/nemotron-customize

Skill 會解析 step DAG、驗證 artifact wiring、產生 YAML config。

重要：marketplace 只安裝 nemotron-customize；其他 6 個 skill（model knowledge bases + contributor add-* skills）留在 disk 但不會被當 plugin 載入。

模式 B：用 nemotron CLI 跑單一 step

 1git clone https://github.com/NVIDIA-NeMo/Nemotron.git
 2cd Nemotron
 3uv sync                            # 還原 uv.lock
 4
 5# 跑單一 step（範例：跑一個 SFT data packing）
 6uv run nemotron steps data_prep sft_packing --config <yaml>
 7
 8# 跑整個 recipe（範例：Nano3 pretrain）
 9uv run nemotron nano3 pretrain -c test
10uv run nemotron nano3 pretrain --config test --run dlw    # nemo-run 走 SLURM / k8s
11uv run nemotron nano3 pretrain -c test -r dlw train.train_iters=5000   # 覆蓋參數
12uv run nemotron nano3 pretrain -c test --dry-run          # 只 preview，不執行

模式 C：作為 Python library 整合進自己 codebase

 1pip install nemotron      # 從 PyPI（如有發布）
 2# 或從 source
 3cd Nemotron && pip install -e .
 4
 5# 視場景安裝 extras
 6pip install -e ".[wandb]"        # W&B 追蹤
 7pip install -e ".[s3]"           # S3 fsspec
 8pip install -e ".[sentencepiece]"
 9pip install -e ".[audio]"        # omni3 Valor32k SFT 音訊資料
10pip install -e ".[data-sdg]"     # 合成資料 pipeline（DataDesigner）
11pip install -e ".[byob]"         # Build Your Own Benchmark

2.3 安裝流程圖


flowchart TD
    A[需求是什麼?] --> B{用途}
    B -->|想自然語言
組 pipeline| C[模式 A
Claude Code 插件]
    B -->|跑 single step
或單一 recipe| D[模式 B
uv sync + nemotron CLI]
    B -->|整合進自家 codebase| E[模式 C
pip install -e .]
    C --> F[/plugin marketplace add
NVIDIA/Nemotron]
    D --> G[git clone + uv sync]
    E --> H[pip install + extras]
    F --> I[/nemotron-customize
啟動 skill]
    G --> J[uv run nemotron
選 recipe / step]
    H --> K[Python import]
    I --> L[YAML config 生成]
    J --> M[訓練 / eval 開跑]
    K --> M
    L --> M

2.4 NVIDIA AI 全家桶安裝（recipes 內會自動拉）

Nemotron recipes 透過 pyproject.toml 從 main branch 拉以下：

1"nemo-run @ git+https://github.com/NVIDIA-NeMo/Run.git@main"
2"nemo-curator[translation_all] @ git+https://github.com/NVIDIA-NeMo/Curator.git@main"

Megatron-Bridge / NeMo-RL / Automodel / Evaluator 由各 recipe 的 README 指引另外裝（部分要從 source 才能拿到 nemotron_3_omni 或 nano-v3-omni 分支）。

2.5 常見安裝問題

問題處理
nemo-run git+ 拉不到確認網路、用 SSH 鑰匙；或 fork 後改成自己的 mirror
data-designer Python 3.10 不支援extras data-sdg 與 byob 要 Python 3.11-3.13
nemo-curator 依賴龐大（含 PyTorch / spacy / fasttext）用獨立 venv 或 Docker
CUDA 13 nightly 找不到 libcudart.so.12issue #150；用 CUDA 12 stable image
cosmos-xenna 0.2.x / 0.3.x 衝突用 byob extras 鎖定的版本
pre-commit hooks 壞掉issue #213；可暫時 skip：SKIP=...

2.6 Docker / Airgap 部署

deploy/nemotron-customizer/airgap/ 提供完整 airgap 部署 Dockerfile：

1deploy/nemotron-customizer/airgap/
2├── Dockerfile.launcher           # launcher container（控制平面）
3├── Dockerfile.launcher.dockerignore
4├── Dockerfile.execution          # execution container（worker）
5└── Dockerfile.execution.dockerignore

omni3 recipe 各 stage 也有自己的 Dockerfile：

1src/nemotron/recipes/omni3/
2├── stage0_sft/Dockerfile
3└── stage1_rl/Dockerfile

3. 核心架構解析

3.1 Repo 三大區塊


flowchart TB
    subgraph Steps["src/nemotron/steps/
15 個 modular building block"]
        S1[curate]
        S2[translate]
        S3[sdg
合成資料]
        S4[data_prep
pretrain/SFT/RL]
        S5[pretrain]
        S6[sft]
        S7[peft
LoRA/QLoRA]
        S8[rl
DPO/GRPO/RLHF]
        S9[convert
HF↔Megatron]
        S10[optimize
distill/prune/quant]
        S11[eval]
        S12[byob
Build Your Own Benchmark]
        S13[env
環境 profile]
        S14[patterns
共用 DAG 樣板]
    end
    subgraph Recipes["src/nemotron/recipes/
完整訓練 pipeline"]
        R1[super3
120B/12B]
        R2[nano3
31.6B/3.6B]
        R3[omni3
30B/3B multimodal]
        R4[rerank
cross-encoder]
        R5[embed
雙塔]
    end
    subgraph Apps["usage-cookbook/ + use-case-examples/
部署 + 應用範例"]
        A1[Doc Intel RAG]
        A2[SQL LoRA]
        A3[Voice RAG Agent]
        A4[Data Science Agent]
        A5[9 個 cookbook]
    end
    Steps -.組合.-> Recipes
    Recipes -.輸出 ckpt.-> Apps

3.2 Nemotron Steps — 15 個 modular building block

src/nemotron/steps/ 的子目錄：

Step功能上游工具
curate/資料清洗 / 過濾 / 去重 / 品質強化NeMo-Curator
translate/跨語言翻譯（dataset 擴增）NeMo-Curator translation
sdg/Synthetic Data Generation 合成資料生成DataDesigner
data_prep/訓練資料準備（pretrain_prep / sft_packing / rl_prep）內建
pretrain/預訓練Megatron-Bridge
sft/Supervised Fine-Tuning（automodel / megatron_bridge 兩條路）Automodel / Megatron-Bridge
peft/Parameter-Efficient FT（LoRA / QLoRA）同上
rl/RL（DPO / RLVR / GRPO / RLHF / MPO）NeMo-RL
convert/checkpoint 轉換（hf_to_megatron / megatron_to_hf / merge_lora）Megatron-Bridge
optimize/模型優化（distill / prune / quantize）ModelOpt
eval/評估 (model_eval)Evaluator
byob/Build Your Own Benchmark（自建 benchmark + MCQ）內建
env/環境 profile（local / SLURM / k8s）NeMo-Run
patterns/共用 DAG 樣板內建
_runners/ + _bootstrap/step 執行核心內部

Step 的 invocation 模式

1uv run nemotron steps <step_name> [subcommand] --config <yaml>
2
3# 範例
4uv run nemotron steps curate nemo_curator --config conf/clean_cc.yaml
5uv run nemotron steps sft megatron_bridge --config conf/sft.yaml
6uv run nemotron steps convert hf_to_megatron --config conf/conv.yaml

每個 step 內部用 Pydantic 定義 config schema → CLI 自動展開 --help。

Artifact 系統

src/nemotron/kit/ 實作 Artifact 系統：每個 step 輸出 metadata + 資料路徑 + lineage 連結。下個 step 可吃前一步的 artifact 當輸入。


flowchart LR
    A[curate step] -->|Artifact: cleaned_corpus.parquet
+ metadata.json| B[data_prep step]
    B -->|Artifact: packed_dataset.bin
+ lineage to A| C[pretrain step]
    C -->|Artifact: ckpt/
+ training log| D[convert step]
    D -->|Artifact: hf_format/| E[eval step]

支援 Unix piping 在 step 之間傳 artifact：

1uv run nemotron steps curate ... | uv run nemotron steps data_prep ... | uv run nemotron steps pretrain ...

3.3 Training Recipes — 5 條完整 pipeline

3.3.1 Nemotron 3 Super（120B / 12B active）

架構：Hybrid Mamba Latent MoE Transformer Pipeline：Pretrain → SFT → RL（3× RLVR + 2× SWE-RL + RLHF across 21 reward environments） 特殊技法：

  • 大規模 pretraining + data curriculum
  • 多領域 SFT pipeline
  • Multi-environment RLVR with 21 simultaneous reward environments
  • SWE-RL with container-isolated sandbox execution
  • GenRM-based RLHF with principle-following rewards
  • Asynchronous GRPO at 1K GPU scale

Training Guide / Tech Report PDF

3.3.2 Nemotron 3 Nano（31.6B / 3.6B active）

架構：MoE Hybrid Mamba-Transformer Pipeline：Pretrain → SFT → RL Spec：25 trillion pretraining tokens / context up to 1M / 3.3× higher throughput vs similar size 特殊技法：

  • Curriculum-based pretraining with two-phase data mixture
  • Long-context extension via CPT (continued pretraining)
  • Multi-domain SFT with 12+ data sources
  • InfinityByte cross-domain code synthesis
  • Tool-calling fine-tuning and budget-controlled reasoning
  • Multi-environment RLVR with GRPO
  • GenRM reward modeling with circular comparison
  • DPO for tool hallucination reduction

Training Guide / Tech Report PDF

3.3.3 Nemotron 3 Nano Omni（30B / 3B active，多模態）

架構：Hybrid Mamba-Transformer MoE + 多模態 encoder 群 Pipeline：SFT → RL（MPO / text GRPO / vision GRPO）→ Eval


flowchart LR
    subgraph Encoders["多模態 encoder"]
        E1[Audio: Parakeet]
        E2[Vision: C-RADIOv4-H
+ 3D conv
+ EVS]
        E3[Text: tokenizer]
    end
    subgraph Adaptors["modality adaptor"]
        A1[adaptor]
        A2[adaptor]
        A3[adaptor]
    end
    LLM[30B-A3B 統一 LLM decoder
Hybrid Mamba-Transformer MoE]
    E1 --> A1
    E2 --> A2
    E3 --> A3
    A1 --> LLM
    A2 --> LLM
    A3 --> LLM
    LLM --> O[文字輸出
含 reasoning]

Spec：context 16K → 49K → 262K（progressive scaling）；MMlongbench-Doc / OCRBenchV2 / WorldSense / DailyOmni / VoiceBench 上 leading 或 best-in-class

特殊技法：

  • Multimodal SFT pipeline using Megatron-Bridge with the Valor32k recipe family（open: CORD-v2 + Valor32k 變體）
  • Progressive context scaling：16K → 49K → 262K
  • Multimodal Preference Optimization (MPO) on public MMPR dataset
  • Text-only GRPO continuation via NeMo-RL
  • Vision GRPO on MMPR-Tiny
  • 上游分支：Megatron-Bridge nemotron_3_omni + NeMo-RL nano-v3-omni（含 omni vllm fork）

3.3.4 Rerank（cross-encoder）

src/nemotron/recipes/rerank/，三 stage：data prep → train → eval（含 evaluation suite）。 2026-05-28 新加，PR #139。

3.3.5 Embed（雙塔 embedding）

src/nemotron/recipes/embed/，用於 retrieval / RAG 場景。配合 rerank 形成完整 retrieval pipeline。

3.4 Usage Cookbooks 全覽（9 個模型）

每個 cookbook 在 usage-cookbook/<model_name>/ 下，含 README + 多個 notebook：

Cookbook內容
Nemotron-3-Ultra-BaseUltra base model 使用 / 部署
Nemotron-3-SuperLoRA Text2SQL / GRPO-DAPO / OpenScaffolding / Spark Deployment Guide
Nemotron-3-NanoBase 使用、基本 inference 範例
Nemotron-3-Nano-OmniGRPO（nemo gym + 標準） / Doc Intelligence with Parse / Megatron-bridge / automodel SFT
Nemotron-Nano2-VLVL（vision-language）使用
Nemotron-Nano-9B-v2中型 9B 變體
Llama-3.1-Nemotron-Safety-Guard-V3安全護欄 / content moderation
Llama-Nemotron-Super-49B-v1.5Llama-base Nemotron 變體
Nemotron-Parse-v1.1Document parsing 專用模型

3.5 Use Case Examples（7 個）

Use Case用途
Intelligent Document Processing with Nemotron RAGPDF / Office → 結構化資料 + RAG 問答
sql-lora-finetuning-and-deploymentBIRD-SQL fine-tune + 部署完整流程
nemotron-voice-rag-agent-example多模態 RAG agent（語音 + 文字 + 影片）
RAG Agent with Nemotron RAG Models通用 RAG agent
build-your-own-benchmark自建 benchmark + 評估
Nemotron-3-Super-Getting-Started-GuideSuper 系列入門
Simple Nemotron-3-Nano Usage ExampleNano 最簡單範例
Data Science ML Agent自動化 ML / 資料科學 agent

3.6 完整目錄樹

 1Nemotron/
 2├── .claude-plugin/
 3│   └── marketplace.json              # Claude Code 插件市集元資料（nemotron-customize 出口）
 4├── .github/                          # CI / 模板
 5├── deploy/
 6│   └── nemotron-customizer/airgap/   # Airgap 部署 Dockerfile
 7├── docs/                             # 文件原始檔
 8│   ├── nemotron/{super3, nano3, omni3, rerank}/   # 各模型訓練 guide
 9│   ├── train-models/, model-eval/, sdg/, curate/, runspec/, ...
10│   └── _ext/, _static/, _snippets/   # Sphinx 配置
11├── research/                         # 研究實驗（少量）
12├── scripts/                          # Repo 維護腳本
13├── skills/                           # Claude Code skills
14│   ├── nemotron-customize/           # 主 plugin（marketplace 唯一上架）
15│   │   └── SKILL.md
16│   ├── nemotron-super3/              # Super3 模型知識庫
17│   ├── nemotron-nano3/               # Nano3 模型知識庫
18│   ├── nemotron-retrieval-recipes/   # Retrieval (embed + rerank) skill
19│   ├── nemotron-add-pattern/         # Contributor: 新增共用 pattern
20│   ├── nemotron-add-step/            # Contributor: 新增 step
21│   ├── nemotron-add-model/           # Contributor: 新增 model recipe
22│   └── INDEX.md
23├── src/
24│   ├── nemo_runspec/                 # NeMo-Run spec layer（執行抽象）
25│   │   ├── config/, packaging/, templates/, execution.py
26│   └── nemotron/
27│       ├── cli/                      # nemotron CLI 主框架
28│       │   ├── bin/nemotron.py
29│       │   ├── commands/{super3, nano3, omni3, rerank, ...}/
30│       │   └── kit/
31│       ├── data_prep/                # 共用資料處理
32│       ├── kit/                      # Artifact / Pipeline 核心
33│       ├── steps/                    # 15 個 modular step（§3.2）
34│       │   ├── curate/, translate/, sdg/, data_prep/, pretrain/,
35│       │   ├── sft/, peft/, rl/, convert/, optimize/, eval/,
36│       │   ├── byob/, env/, patterns/, _runners/, _bootstrap/
37│       └── recipes/                  # 5 條完整 recipe
38│           ├── super3/, nano3/, omni3/, rerank/, embed/
39│           └── data/                 # 共用 data recipe
40├── tests/                            # pytest 單元測試
41├── tools/
42│   └── budget/                       # Thinking budget custom logit processors
43├── usage-cookbook/                   # 9 個模型部署 cookbook（§3.4）
44├── use-case-examples/                # 7 個 end-to-end 應用範例（§3.5）
45├── LICENSE                           # Apache-2.0
46├── pyproject.toml                    # 12 KB，多個 extras
47├── uv.lock                           # 1.1 MB
48├── README.md                         # 35 KB 主 README
49└── SECURITY.md                       # NVIDIA PSIRT 通報流程

3.7 Hybrid Mamba-Transformer 為什麼贏


flowchart LR
    A[輸入長 context] --> B{每層怎麼選?}
    B -->|Mamba layer| C[線性記憶 hidden state
O(n) 記憶體]
    B -->|Transformer attention| D[O(n²) 記憶體
但 reasoning 強]
    C --> E[長序列效率高]
    D --> F[推理任務強]
    E --> G[Hybrid: 兩者 staking
長 context + 強 reasoning]
    F --> G
    G --> H{MoE 加成}
    H --> I[低 active 參數
= 推論便宜]
    H --> J[Total 容量大
= 知識多]
    I --> K[Nemotron 3 系列
= 全部加總]
    J --> K

這個組合（Mamba 線性 cost + Transformer reasoning + MoE 路由）是 2024-2026 LLM 架構演化的主流方向，Nemotron 3 是把這套組合工程化最成熟的開源系列之一。

4. Helper Scripts 詳細用法

4.1 nemotron CLI

主要入口在 src/nemotron/cli/bin/nemotron.py：

1Usage:
2    nemotron <recipe> <stage> [-c CONFIG] [-r RUN_PROFILE] [DOTLIST...]
3
4範例：
5    nemotron nano3 pretrain -c test                       # 本地執行
6    nemotron nano3 pretrain --config test --run dlw       # nemo-run 接 SLURM/k8s
7    nemotron nano3 pretrain -c test -r dlw train.train_iters=5000   # OmegaConf override
8    nemotron nano3 pretrain -c test --dry-run             # 只 preview config

nemo-run 是 NVIDIA NeMo 子專案，把實驗 spec 抽象成可在 local / SLURM / k8s / DLW（NVIDIA’s Deep Learning Workbench）執行的單一表達。

4.2 nemotron steps

跑單一 modular step：

 1uv run nemotron steps <step_name> [subcommand] [-c CONFIG] [DOTLIST...]
 2
 3# 範例
 4uv run nemotron steps curate nemo_curator -c conf/clean.yaml
 5uv run nemotron steps sdg data_designer -c conf/sdg.yaml
 6uv run nemotron steps data_prep sft_packing -c conf/pack.yaml
 7uv run nemotron steps sft megatron_bridge -c conf/sft.yaml
 8uv run nemotron steps sft automodel -c conf/sft_auto.yaml
 9uv run nemotron steps peft megatron_bridge -c conf/peft.yaml
10uv run nemotron steps rl nemo_rl -c conf/rl.yaml
11uv run nemotron steps convert hf_to_megatron -c conf/conv.yaml
12uv run nemotron steps optimize modelopt distill -c conf/distill.yaml
13uv run nemotron steps eval model_eval -c conf/eval.yaml

Step 的子目錄（從探索看到的對應）

 1steps/sft/        # automodel/  megatron_bridge/
 2steps/peft/       # automodel/  megatron_bridge/
 3steps/rl/         # nemo_rl/
 4steps/convert/    # hf_to_megatron/  megatron_to_hf/  merge_lora/
 5steps/optimize/   # modelopt/{distill, prune, quantize}/
 6steps/data_prep/  # pretrain_prep/  rl_prep/  sft_packing/
 7steps/eval/       # model_eval/
 8steps/byob/       # data/  mcq/  patterns/  references/  runtime/  scripts/
 9steps/curate/     # nemo_curator/
10steps/translate/  # nemo_curator/
11steps/sdg/        # data_designer/

4.3 nemotron-customize Claude Code Skill

skills/nemotron-customize/SKILL.md 完整定義了這個 skill 的 contract：

觸發情境（節錄）：

  • 任何「customize / fine-tune / train / SFT / RL / evaluate」+ Nemotron 相關名稱
  • 「組 pipeline / chain steps / 從 raw data 跑到 trained model」
  • evaluate / benchmark / smoke test / score 既有 / 託管 endpoint

不觸發：frontend / dashboard / visualization / 通用 ML 建議 / billing / 非 Nemotron coding。

前提：

  • src/nemotron/steps/ 存在的 Nemotron repo checkout（從 repo root 啟動）
  • 安裝 uv（用 uv run nemotron steps ...）
  • 遠端執行需要 env profile TOML（NEMOTRON_ENV_FILE 或 env*.toml）
  • 託管服務（translation / hosted eval）需要對應 env var（如 NVIDIA_API_KEY）— 絕不 inline 或 commit

skill 做什麼：

  1. 解析需求 → 規劃 step DAG
  2. 驗證 artifact wiring
  3. 只建立必要 YAML / config，不改既有檔案
  4. 提供 dry-run preview

4.4 7 個 skill 完整對照

Skill角色對使用者
nemotron-customize主要 plugin、組 pipeline、跑 steps✅ Marketplace 上架
nemotron-super3Super3 模型知識庫（架構 / paper / recipe 細節）❌ 不上架
nemotron-nano3Nano3 模型知識庫❌ 不上架
nemotron-retrieval-recipesembed + rerank skill（檢索專用）❌ 不上架
nemotron-add-patternContributor：新增共用 pattern❌ 內部用
nemotron-add-stepContributor：新增 step❌ 內部用
nemotron-add-modelContributor：新增 model recipe❌ 內部用

4.5 tools/budget/ — Thinking budget logit processors

tools/budget/custom_logit_processors/v1/nano_v3_logit_processors.py：實作 thinking budget（推理時限制 <think> token 數量），用法：

 1from vllm import SamplingParams
 2params = SamplingParams(
 3    temperature=0.6,
 4    max_tokens=1220,
 5    extra_args={
 6        "thinking_budget": 150,           # 最多 150 個 thinking token
 7        "thinking_budget_grace_period": 30,
 8        "end_token_ids": [1871, 5565, 11483, 6139, 1046, 2259, 74045, 1062],
 9    },
10)

這是 budget-controlled reasoning 功能（Nano3 tech report 一個重點）。

4.6 nemo_runspec — 執行抽象層

src/nemo_runspec/ 是新建的抽象層：

  • config/ — 執行 spec 的 dataclass
  • packaging/ — 把 step 打包成可送到 cluster 的 artifact
  • templates/ — SLURM / k8s job 模板
  • execution.py — 實際 dispatch（含 subprocess.run(cmd, shell=True, executable="/bin/bash")，見 §6 資安）

跟 nemo-run 的關係：nemo-run 是上游通用框架，nemo_runspec 是 Nemotron-specific 包裝。

4.7 justfile — make 替代

repo 根目錄有個 justfile（287 B），提供 just <target> 快捷指令（如 just test / just lint）。just 是 make 的現代替代，習慣 Makefile 的可以 cat justfile 找對應 target。

5. 應用場景：5 條 recipe + 9 個 cookbook + 7 個 use-case

5.1 Recipe A：Nemotron 3 Super（120B / 12B active）

對象：要復現頂級模型 / 學最前沿 RL 配方的研究員。

完整 pipeline（從 docs/nemotron/super3/README.md）：


flowchart TD
    A[raw data] --> B[nemotron steps curate]
    B --> C[nemotron steps data_prep pretrain_prep]
    C --> D[nemotron super3 pretrain
Megatron-Bridge]
    D --> E[Base ckpt]
    E --> F[nemotron steps data_prep sft_packing]
    F --> G[nemotron super3 sft]
    G --> H[SFT ckpt]
    H --> I[3× RLVR + 2× SWE-RL + RLHF
21 reward env]
    I --> J[Instruct ckpt]
    J --> K[nemotron steps eval]
    K --> L[Benchmark report]

亮點配方：

  • Multi-environment RLVR：21 個 reward env 同時跑（math / code / reasoning / tool calling / …）
  • SWE-RL：container-isolated sandbox 跑 SWE-bench 任務、評估補丁正確性
  • GenRM-based RLHF：reward model 從 generative 走，比 classifier RM 細膩
  • Async GRPO：rollout / training decouple，1K GPU scale

硬體：~1024 H100，預訓 weeks 級

復現難度：⭐⭐⭐⭐⭐（需大規模 GPU + 對應 dataset 子集）

5.2 Recipe B：Nemotron 3 Nano（31.6B / 3.6B active）

對象：想做中型 production model、要學 long-context CPT 的工程師。

亮點配方：

  • Two-phase data mixture pretraining：phase 1 廣度、phase 2 深度
  • Long-context CPT：從 standard context → 1M context
  • 12+ data sources SFT：math / code / science / general / agentic / tool / multi-turn
  • InfinityByte code synthesis：跨領域合成程式碼資料
  • Tool-calling fine-tuning + budget-controlled reasoning
  • GenRM circular comparison：reward model 用 round-robin pairwise 評估
  • DPO for tool hallucination reduction：專攻幻覺工具調用

硬體：~64-256 A100/H100

復現難度：⭐⭐⭐⭐

5.3 Recipe C：Nemotron 3 Nano Omni（30B / 3B 多模態）

對象：multimodal agent、document intelligence、voice / video understanding 應用。

Pipeline：


flowchart LR
    subgraph "Stage 0: SFT"
        S0[Valor32k recipe family
CORD-v2 + 變體
16K context]
    end
    subgraph "Stage 1: RL"
        S1A[MPO
multimodal preference]
        S1B[text GRPO
via NeMo-RL]
        S1C[vision GRPO
on MMPR-Tiny]
    end
    subgraph "Context scaling"
        CS[16K → 49K → 262K]
    end
    S0 --> CS --> S1A
    S0 --> CS --> S1B
    S0 --> CS --> S1C
    S1A --> R[Reasoning ckpt]
    S1B --> R
    S1C --> R
    R --> E[Eval
MMlongbench-Doc
OCRBenchV2
WorldSense
DailyOmni
VoiceBench]

亮點：

  • 一個 unified decoder + 3 個 modality-specific encoder + adaptor
  • Mamba 層讓長 context（262K）可承受
  • 9.2× video reasoning capacity / 7.4× multi-document workload vs 同尺寸 open omni model
  • License: NVIDIA Open Model License (NOML)（enterprise-friendly, on-prem）

硬體：~128-512 H100

復現難度：⭐⭐⭐⭐⭐（需處理多模態資料）

5.4 Recipe D：Rerank（cross-encoder）

src/nemotron/recipes/rerank/，3 stage：

Stage內容
Stage 1SDG（合成 query-doc pairs）
Stage 2Train cross-encoder
Stage 3Eval on BEIR-style retrieval benchmark（用 EvaluateRetrieval from beir）

對象：要做高品質 RAG retrieval 的開發者。 對應 skill：nemotron-retrieval-recipes

5.5 Recipe E：Embed（雙塔 embedding）

src/nemotron/recipes/embed/，與 rerank 互補：embed 做第一階段粗檢，rerank 做第二階段精排。

5.6 9 個 Usage Cookbook 速覽

5.6.1 Nemotron-3-Super

  • lora-text2sql：把 Super 用 LoRA 微調成 Text2SQL specialist
    • 兩個變體：nemo-automodel（HF native）/ nemo-megatron-bridge（Megatron native）
  • grpo-dapo：GRPO with DAPO（Decoupled Advantage Policy Optimization）— RL 進階
  • OpenScaffoldingResources：open scaffolding for agentic tasks
  • SparkDeploymentGuide：用 Apache Spark 跑 Super 大規模 inference

5.6.2 Nemotron-3-Nano

  • 基本 inference 範例

5.6.3 Nemotron-3-Nano-Omni

  • grpo_nemo_gym：用 NeMo Gym 做 GRPO RL
  • grpo：標準 GRPO
  • doc-intelligence-with-parse：document parsing 整合
  • Megatron-bridge：用 Megatron-Bridge SFT
  • automodel：用 Automodel SFT

5.6.4 Nemotron-3-Ultra-Base

  • Ultra base model 部署 / 使用（2026 GTC 發布）

5.6.5 Nemotron-Nano2-VL

  • 2nd gen VL（vision-language）模型使用

5.6.6 Nemotron-Nano-9B-v2

  • 9B 中型變體（適合 LoRA / 量化部署）

5.6.7 Llama-3.1-Nemotron-Safety-Guard-V3

  • Llama-base 的 safety guard 模型，content moderation

5.6.8 Llama-Nemotron-Super-49B-v1.5

  • Llama-base Nemotron Super 變體

5.6.9 Nemotron-Parse-v1.1

  • Document parsing 專用模型（PDF / OCR）

5.7 7 個 Use Case Examples 速覽

5.7.1 Intelligent Document Processing with Nemotron RAG（3.3 KB README）

  • 解析 PDF / Word → 結構化資料 → RAG 問答
  • 用 Nemotron Parse + Nemotron Nano / Super

5.7.2 sql-lora-finetuning-and-deployment

  • BIRD-SQL dataset 做 LoRA fine-tune
  • bird_sql/ + launchable_scripts/
  • 包含 NIM 部署 launch script

5.7.3 nemotron-voice-rag-agent-example（8.1 KB README）

  • nemotron_family_multimodal_rag_agent/
  • 多模態 RAG agent：語音輸入 → ASR → retrieval → Nemotron Omni 回答

5.7.4 RAG Agent with Nemotron RAG Models

  • 通用 RAG agent 範例

5.7.5 build-your-own-benchmark

  • 教使用者自建 benchmark（MCQ / open-ended）

5.7.6 Nemotron-3-Super-Getting-Started-Guide

  • Super 系列 inference 入門

5.7.7 Simple Nemotron-3-Nano Usage Example

  • 最簡單 Python inference 範例

5.7.8 Data Science ML Agent（2.7 KB README）

  • 自動化 ML agent，含 src/、tools/、runs/、data/
  • 把 Nemotron 當 AutoML 後端

5.8 跨場景 routing 圖


flowchart TD
    A[手上有什麼?] --> B{需求類型}
    B -->|要訓模型| C{資源規模}
    C -->|512+ GPU| D[Recipe: Super3]
    C -->|64+ GPU| E[Recipe: Nano3]
    C -->|多模態 128+ GPU| F[Recipe: Omni3]
    C -->|單機 RAG retrieval| G[Recipe: embed + rerank]
    B -->|要 inference / 部署| H{模型大小}
    H -->|2B-9B 單卡| I[Cookbook: Nano / Nano2-VL / Nano-9B]
    H -->|30-49B 中卡| J[Cookbook: Super / Llama-Super]
    H -->|Ultra| K[Cookbook: Ultra-Base]
    H -->|多模態| L[Cookbook: Nano Omni]
    H -->|文件解析| M[Cookbook: Parse v1.1]
    H -->|安全護欄| N[Cookbook: Safety-Guard-V3]
    B -->|要做應用| O{應用類型}
    O -->|RAG 文件問答| P[Use case: Doc IPI RAG]
    O -->|SQL agent| Q[Use case: SQL LoRA]
    O -->|語音 agent| R[Use case: Voice RAG]
    O -->|資料科學 agent| S[Use case: DS ML Agent]
    O -->|建 benchmark| T[Use case: Build Own Benchmark]
    B -->|想用 Claude 組 pipeline| U[Skill: nemotron-customize]

6. 資安掃描報告

掃描時間：2026-06-02 / 掃描範圍：*.py *.sh *.yaml *.yml + LICENSE / pyproject

6.1 🟢 低風險項目（NVIDIA 工程品質高）

  • LICENSE：Apache-2.0（頂層 LICENSE 檔正確）
  • SECURITY.md：完整、明確（NVIDIA PSIRT、PGP key、不要在 GitHub issue 報資安）
  • 無硬編碼 secret：唯一命中 tools/budget/client.py:6:api_key="EMPTY" 是 vLLM 對 OpenAI client 的 dummy；tests/recipes/rerank/test_sdg.py 內 "secret-one" / "secret-two" 是 redaction 行為的測試 fixture
  • 無 pickle.load / joblib.load 載入不信任資料
  • ast.literal_eval（不是 eval）：step_1-download_extract.py 用 ast.literal_eval 解析欄位，正確的安全做法
  • api_key 在 test 內標記 <redacted>：證明 CLI 有 secret redaction 機制
  • 完整 CI / pre-commit：.pre-commit-config.yaml + tests/ 完整
  • 環境變數驅動 auth：SKILL.md 明確要求 NVIDIA_API_KEY 從環境變數讀，「絕不 inline 或 commit」

6.2 🟡 中度風險項目

6.2.1 LICENSE 與 pyproject 衝突

  • 頂層 LICENSE 檔：Apache-2.0
  • pyproject.toml：license = {text = "MIT"}

兩者不一致。實務上 LICENSE 檔優先，但 PyPI metadata 會以 pyproject 為準。

建議：

  • 商用 / 內訓前先以 LICENSE 檔（Apache-2.0）為準
  • 在 GitHub 開 issue 通知 Nemotron team 修正

6.2.2 模型權重 License 與 repo 不同

  • 多數 Nemotron 模型權重採 NVIDIA Open Model License (NOML)，不是 Apache-2.0 / MIT
  • NOML 在「enterprise-friendly, on-prem」場景比 Llama license 寬，但仍有：
    • 禁止用於訓練其他「competing models」
    • 須遵守 NVIDIA 的 acceptable use policy
    • 部分模型禁止某些高風險用途
  • 部分資料集是 NVIDIA Data Agreement 而非 CC-BY-4.0

建議：每個要用的模型 / dataset 個別讀 HuggingFace 模型卡的 license section；商用前由法務確認。

6.2.3 subprocess.run(shell=True, executable="/bin/bash")

src/nemo_runspec/execution.py:120：

1result = subprocess.run(cmd, shell=True, executable="/bin/bash")
  • 用於 dispatch step 的 shell command（如 sbatch / docker run）
  • 本身屬於 execution layer 必要設計
  • 風險：若 cmd 來自不信任輸入會有 shell injection
  • 緩解：上游 caller（CLI / config）必須自己保證 cmd 內容可信

建議：在 multi-user 環境（給外部使用者跑 step）必須在 cmd 構造前做 sanitization；singletenant trusted env 風險可接受。

6.2.4 測試內

tests/kit/test_self_contained_packager.py 三處：

1subprocess.check_call(cmd, shell=True)

僅限測試環境、command 為固定字串、不會在 production 觸發。🟢 低風險。

6.2.5 exec(compile(out, "", "exec"), ns)

tests/kit/test_ast_inliner.py:67：

這是測試 AST inliner 功能（packaging 工具要把多個 .py 拼成 self-contained 檔案）必須的。生產 code path 不用 exec。

6.2.6 大量 git+ 直接依賴

1"nemo-run @ git+https://github.com/NVIDIA-NeMo/Run.git@main"
2"nemo-curator[translation_all] @ git+https://github.com/NVIDIA-NeMo/Curator.git@main"
  • 直接從 main 拉，沒 pin commit hash
  • 風險：上游 force-push / 砍 branch 會破壞重現性
  • 影響：版本漂移可能
  • 但這些都是 NVIDIA 自家 repo，內部 governance 應該到位

建議：production 鎖定具體 commit；fork 後改成自己 mirror。

6.2.7 Container-isolated sandbox 在 SWE-RL

Super3 RL 用 container-isolated sandbox 跑 SWE-bench task。這是 sandbox 設計目的，不是 finding；但 deployer 要注意：

  • sandbox 用什麼基底（Docker / podman / firejail）
  • escape 風險評估
  • 資源限制（CPU / memory / network）

具體在 src/nemotron/recipes/super3/ 與 src/nemotron/steps/rl/nemo_rl/ 中。

6.2.8 CUDA 版本相容性

issue #150 顯示 CUDA 13 nightly image 對某些 NVFP4 部署不相容。建議：production 用 CUDA 12 stable。

6.2.9 uv.lock 1.1 MB

依賴樹龐大；單一 transitive 套件被劫持有供應鏈風險。建議：

  • Mirror 到內部 PyPI
  • 用 pip-audit / safety 定期掃 CVE

6.3 🔴 高風險項目

無高風險 finding。NVIDIA 工程衛生狀況良好。

6.4 結論

項目等級建議
程式碼資安🟢通過
訓練 sandbox（SWE-RL）🟢設計合理；deployer 自負配置
Repo LICENSE🟡Apache-2.0 vs MIT 不一致；以 LICENSE 檔為準
模型權重 License🟡NOML，跟 repo 不同；商用前個別確認
Shell execution layer🟡trusted env 可接受
依賴鎖定🟡git+ main 直接拉，production 要 pin
高風險 finding🟢無

整體判定：🟢 工程上安全可用；🟡 license 與權重授權須法務逐一確認。

7. FAQ

Q1: Nemotron 跟 Llama / Mistral / Qwen 比有什麼不同？

答：

  • 架構：Nemotron 3 是 hybrid Mamba-Transformer MoE；Llama 3 / Qwen 2 / Mistral 主要是純 Transformer dense（Mistral 有 8×7B MoE）
  • 訓練 pipeline 公開度：Nemotron 把 pretrain → SFT → RL 三段完整 reference code 都開源，Llama / Mistral 只開權重
  • 多模態完整度：Nemotron 3 Nano Omni 在「文字 + 圖像 + 影片 + 音訊」單一 decoder 上的整合度業界領先
  • 授權：Nemotron 多數模型 NOML（enterprise-friendly）；Llama 是 Llama license（有 700M MAU 條款）；Mistral / Qwen 多 Apache-2.0
  • 生態：Nemotron 緊密綁 NVIDIA AI stack；Llama 較跨平台

Q2: 我沒 1000 GPU，這個 repo 還對我有用嗎？

答：非常有用。除了 Super3 / Omni3 完整復現需要超算外：

  • 單 GPU：跑所有 cookbook 範例、跑 Nano 3.6B active inference、跑 LoRA fine-tune
  • 8 GPU：跑 Nano3 部分階段、跑 rerank / embed recipe
  • 64 GPU：跑 Nano3 完整 SFT
  • 15 個 step 都可獨立跑：例如只跑 curate 處理自己資料、只跑 eval 評估自己模型、只跑 optimize modelopt prune 做剪枝

Q3: nemotron-customize Claude 插件實際怎麼用？

答：

  1. 從 Claude Code 安裝：/plugin marketplace add NVIDIA/Nemotron + /plugin install nemotron-customize@nvidia-nemotron
  2. 在 repo 根目錄啟動 Claude Code（注意：必須在 repo root，否則 file resolve 失敗）
  3. 對 Claude 說：「我要對自己的中文 dataset 做 Nano3 LoRA SFT」
  4. Skill 會：
    • 探索 src/nemotron/steps/ 找到合適 step
    • 規劃 DAG（curate → data_prep/sft_packing → sft/megatron_bridge → eval/model_eval）
    • 寫 YAML config 草稿給你（不執行）
    • 顯示需要的環境變數（NVIDIA_API_KEY 等）
  5. 你 review YAML 後跑 uv run nemotron steps ...

Q4: 為什麼是 uv 不是 pip？

答：

  • 速度：uv 比 pip 快 10-100×
  • deterministic：uv.lock 完整鎖定所有 transitive
  • PEP 723 支援：recipe 腳本可 inline 寫依賴
  • modern：NVIDIA 內部標準化

如果你必須用 pip：pip install -e . 可以裝，但別期待跟 uv.lock 100% 一致。

Q5: Megatron-Bridge / Automodel / NeMo-RL 三個 SFT/RL 框架怎麼選？

答：

用途框架原因
Megatron 格式 checkpoint、要 tensor / pipeline parallelMegatron-Bridge跟 Megatron-LM 原生整合
HuggingFace 格式、單機 / 簡單Automodel與 transformers 無縫
RL（DPO / GRPO / RLVR / RLHF）NeMo-RLNeMo-RL 是專門 RL 框架
多模態（omni3 RL）NeMo-RL nano-v3-omni 分支含 omni vllm fork

Q6: 21 個 RLVR reward env 是什麼？

答：Super3 tech report 揭露的多領域 RL — 同時跑 21 個獨立 reward environment：

  • math（多個 dataset）
  • code（多語言 + competitive programming）
  • reasoning（chain-of-thought）
  • tool calling
  • instruction following
  • safety
  • …

每個 env 提供 reward 信號，GRPO 訓練時融合。具體列表在 tech report。

Q7: GRPO / DAPO 是什麼？

答：

  • GRPO（Group Relative Policy Optimization）：DeepSeek 提出的 PPO 變體，不用 critic 模型，靠 group sampling 計算 advantage。Nemotron 廣泛採用
  • DAPO（Decoupled Advantage Policy Optimization）：在 GRPO 基礎上把 advantage 計算 decouple，讓 rollout 與 training 異步、scale 更大
  • Nemotron 3 Super 用 asynchronous GRPO at 1K GPU scale

Q8: Open data 只佔訓練資料一部分，私有資料拿不到怎麼辦？

答：

  • README 與每個 recipe 都明示「Open-Source Data Only」— open subset 跑得到的 benchmark 會比 tech report 低
  • 把這些 recipe 當作 methodology reference：學配方 + 用自己資料跑
  • NVIDIA 透過 DataDesigner SDG 步驟給工具生合成資料補洞

Q9: 怎麼在 SLURM cluster 跑？

答：用 nemo-run 的 dlw 或 slurm profile：

1# 假設你有 env profile 在 ./env_slurm.toml
2NEMOTRON_ENV_FILE=./env_slurm.toml \
3uv run nemotron nano3 pretrain -c default --run slurm

env profile 內定義：

  • partition
  • nodes / GPUs per node
  • container image
  • mount paths
  • account / qos

範本見 src/nemotron/steps/env/。

Q10: Nemotron 3 Ultra 哪裡找得到細節？

答：2026-03 GTC San Jose 發布，但目前 repo 只有 usage-cookbook/Nemotron-3-Ultra-Base/（部署）。完整訓練 recipe 預計 0.2.0 / 1.0.0 release 加入。

Q11: budget-controlled reasoning 是什麼？

答：Nano3 tech report 一個重點。模型內訓練時學會「在限定 token 數內完成 reasoning」；inference 時用 tools/budget/custom_logit_processors/v1/nano_v3_logit_processors.py 強制執行，例如 thinking_budget: 150 表示 <think> 段最多 150 個 token。

對 production latency 控制有用：reasoning 模型不會「無限思考」。

Q12: voice RAG agent use case 用什麼模型？

答：use-case-examples/nemotron-voice-rag-agent-example/ 用：

  • ASR：Parakeet（Nemotron Omni 的音訊 encoder）
  • 主 LLM：Nemotron 3 Nano Omni（多模態）
  • TTS：可選（範例可能用 Parakeet 反向 / 或外部 TTS）

Q13: Spark Deployment Guide 是部署什麼？

答：usage-cookbook/Nemotron-3-Super/SparkDeploymentGuide/：用 Apache Spark 跑 batch inference，適合 ETL 場景「百萬筆資料 × LLM 標註 / 改寫 / 分類」。比單機 GPU 跑得快很多。

Q14: Tests are broken（issue #213）— 我用本 repo 安全嗎？

答：

  • issue 提到 tests 與 pre-commit hooks 有些壞，但不影響核心功能
  • 真正核心 path（CLI / steps / recipes）有自己的測試覆蓋
  • 開發階段建議先跑 tests/ 子集，發現問題報 issue

Q15: 怎麼貢獻？

答：

  • 讀 CONTRIBUTING.md
  • 用 nemotron-add-step / nemotron-add-pattern / nemotron-add-model 三個 contributor skill（在 skills/ 下）
  • 開 PR 走標準 GitHub flow

8. 進階技巧

8.1 把 nemotron steps 串成自家 pipeline

1# 範例：用 Unix pipe 串 curate → data_prep → sft
2uv run nemotron steps curate nemo_curator -c c.yaml \
3  | uv run nemotron steps data_prep sft_packing -c p.yaml \
4  | uv run nemotron steps sft megatron_bridge -c s.yaml

每個 step 輸出 artifact metadata + 路徑到 stdout，下個 step 從 stdin 讀。配合 --dry-run 可先驗證 DAG。

8.2 用 Claude nemotron-customize 加速 config 撰寫

對 Claude 說：「我要做一個 dataset 從 raw HF → curate → SFT pack → train Nano3 LoRA → eval on MMLU」，skill 會：

  1. 列出 step DAG
  2. 對每個 step 寫 YAML 草稿（含合理預設）
  3. 顯示需要設的環境變數
  4. 提供 dry-run command 讓你先驗證

省下「翻 docs 找哪個 step / 哪個 config schema」的時間。

8.3 Budget-controlled reasoning 範本

 1from vllm import LLM, SamplingParams
 2import json
 3
 4LLM_PATH = "nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16"
 5llm = LLM(model=LLM_PATH, dtype="bfloat16")
 6
 7# 限制 thinking 在 150 token 內
 8params = SamplingParams(
 9    temperature=0.6,
10    max_tokens=1220,
11    extra_args={
12        "thinking_budget": 150,
13        "thinking_budget_grace_period": 30,
14        "end_token_ids": [1871, 5565, 11483, 6139, 1046, 2259, 74045, 1062],
15    },
16)
17outputs = llm.generate(["Solve: ..."], params)

對 latency-sensitive production（即時對話）特別有用：保證 reasoning 不爆衝。

8.4 LoRA + SFT 三步驟（Nano3 範本）

 1# 1. Pack training data
 2uv run nemotron steps data_prep sft_packing \
 3    -c conf/pack.yaml \
 4    data.path=./my_data.jsonl
 5
 6# 2. LoRA SFT
 7uv run nemotron steps peft megatron_bridge \
 8    -c conf/lora.yaml \
 9    model.pretrained=nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16 \
10    peft.r=32 \
11    peft.alpha=32 \
12    train.train_iters=2000
13
14# 3. Convert LoRA back to HF 並 merge
15uv run nemotron steps convert merge_lora -c conf/merge.yaml

8.5 Optimize：量化部署

 1# Pre-trained model → FP8 量化
 2uv run nemotron steps optimize modelopt quantize \
 3    -c conf/quant.yaml \
 4    quant.scheme=fp8
 5
 6# Pruning（降參數）
 7uv run nemotron steps optimize modelopt prune \
 8    -c conf/prune.yaml
 9
10# Knowledge distillation（小模型學大模型）
11uv run nemotron steps optimize modelopt distill \
12    -c conf/distill.yaml

NVIDIA ModelOpt 已內建這三個動作，配 NIM / TensorRT-LLM 部署效益最大。

8.6 Build Your Own Benchmark

src/nemotron/steps/byob/ 完整 BYOB framework：

1# 從你的領域知識生 MCQ
2uv run nemotron steps byob mcq \
3    -c conf/mcq.yaml \
4    seed_docs=./my_docs/
5
6# 跑 evaluation
7uv run nemotron steps eval model_eval \
8    -c conf/byob_eval.yaml \
9    benchmark=./my_byob/

對「我要評估自家模型在 specialized domain 上的表現」這類需求是黃金工具。

8.7 用 NIM 微服務部署

NVIDIA NIM（NVIDIA Inference Microservices）是商業化 inference 服務：

  • 從 HF 下載 Nemotron 權重
  • 用 NIM 容器啟動：docker run nvcr.io/nim/nvidia/<model>:<tag>
  • 自動暴露 OpenAI-compatible REST API

use-case-examples/sql-lora-finetuning-and-deployment/launchable_scripts/ 有 NIM 部署範例。

8.8 跨模型遷移：學會了 SFT 步驟可套到其他模型

step 系統是 model-agnostic 的：學 Nemotron 3 Nano SFT 後，把 model.pretrained 換成 Llama / Mistral / Qwen，相同 step 也能跑。對「我想用 NVIDIA 工程實踐去訓 X 模型」是好起點。

8.9 Artifact lineage 追蹤

1from nemotron.kit import load_artifact
2a = load_artifact("./outputs/sft_run/artifact.json")
3print(a.metadata)        # 訓練超參數、commit hash、輸入 artifact 來源
4print(a.lineage)         # 上游 artifact 鏈

Reproducibility 必備工具。

8.10 W&B / TensorBoard 整合

1# .env 或 export
2export WANDB_API_KEY=...
3uv run nemotron nano3 pretrain -c default \
4    tracker.wandb.enabled=true \
5    tracker.wandb.project=my-nano3

CHANGELOG 提到內建 WandbTracker。

9. 整合進其他工作流

9.1 整合進 AI knowledge template

Layer用途
ai-gh-save已產生 inbox/2026-06-02-github-NVIDIA-NeMo-Nemotron.md
gh-tutorial-qd已產生本詳細教學 md + qd + plain HTML（本流程）
paper-search找 Nemotron 3 tech reports（已連結 in §11）；找 GRPO / DAPO / MPO / Mamba 原始 paper
paper-qa-liteSuper3 / Nano3 tech reports + Mamba paper 餵成 corpus，問「Hybrid Mamba MoE 在 long context 上的記憶體 footprint 怎麼算？」
graphify對 src/nemotron/ 跑 graphify，看 steps ↔ recipes ↔ kit 的依賴關係
kami把 §5 的 5 條 recipe 抽成單頁 cheat sheet
research-pipeline-v2用 Nemotron training recipe 設計研究 pipeline，套 9-stage research workflow

9.2 內部 LLM 訓練團隊 onboarding

新人 onboarding 建議：

  • Week 1：讀 README + 跑 Simple Nano Usage Example + Doc Intelligence RAG
  • Week 2：跑 nemotron-customize skill 設計第一個 SFT pipeline；訓 Nano LoRA on small dataset
  • Week 3：讀 Super3 / Nano3 tech reports；理解 21-env RLVR 框架
  • Week 4：依團隊方向選方向：(a) 自家領域 SFT、(b) RAG 應用、(c) multimodal、(d) RL 配方

9.3 與 Claude Code / Codex / Gemini CLI 整合

nemotron-customize 目前只支援 Claude Code（marketplace.json 設計）；但 SKILL.md 本身是純 markdown 規範，可轉到其他平台：

  • Cursor / Cline 可直接讀 SKILL.md 模擬
  • 自家 internal agent 可把 SKILL.md 內容當 prompt template

9.4 production LLMOps 平台

把 Nemotron steps 包進 LLMOps 平台：

  • Step 用 Argo Workflows / Airflow / Kubeflow 編排
  • Artifact 寫入 MLflow / Weights & Biases
  • 模型 registry 用 Hugging Face / MLflow
  • 部署用 NVIDIA NIM / vLLM / TensorRT-LLM
  • 監控用 Prometheus + Grafana

10. 重點摘要 Checklist

10.1 概念與架構

  • 能解釋 Hybrid Mamba-Transformer MoE 為什麼贏（線性 cost + reasoning + 低 active 參數）
  • 能說出 Nemotron 3 Nano / Super / Ultra / Nano Omni 的差異
  • 能解釋 latent MoE 與一般 MoE 的差異
  • 能列出 RLVR / GRPO / DAPO / MPO / RLHF 在 Nemotron 中的角色
  • 能說明 budget-controlled reasoning 是什麼、為什麼有用

10.2 工程與工具鏈

  • 能用 uv 還原環境
  • 會用 nemotron CLI 跑單一 recipe / step
  • 知道 15 個 step 各自負責什麼
  • 能寫 YAML config + 用 dotlist override（train.train_iters=5000）
  • 知道 NVIDIA NeMo 全家桶（Curator / RL / Megatron-Bridge / Automodel / Evaluator / DataDesigner）哪個做什麼

10.3 Claude Code 整合

  • 能安裝 nemotron-customize plugin
  • 能正確從 repo root 啟動 Claude Code
  • 知道 skill 的觸發 / 不觸發場景

10.4 Recipes 與 Cookbooks

  • 能找到對應 model 的 cookbook
  • 能找到對應應用的 use-case example
  • 知道 Super3 / Nano3 / Omni3 各自的硬體需求等級

10.5 部署與生產

  • 會用 LoRA fine-tune 然後 merge 回 HF
  • 知道 ModelOpt 怎麼做 quantize / prune / distill
  • 知道 NIM 部署流程
  • 知道 vLLM 配合 thinking budget 怎麼用

10.6 倫理與合規

  • 知道 repo LICENSE (Apache-2.0) ≠ 模型權重 LICENSE (NOML)
  • 知道 NVIDIA Data Agreement 與 CC-BY-4.0 的差異
  • 商用 / 內訓前先過法務

11. 進一步閱讀

11.1 官方資源

11.2 Tech Reports（必讀）

11.3 NVIDIA NeMo 子專案（上游）

11.4 模型權重（HuggingFace）

11.5 重要參考 paper（書中重點觀念）

  • Mamba：Gu & Dao (2023) “Mamba: Linear-Time Sequence Modeling with Selective State Spaces”
  • GRPO：DeepSeek (2024) “DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models”
  • DAPO：ByteDance (2025) “DAPO: An Open-Source LLM Reinforcement Learning System at Scale”
  • MoE：Fedus et al. “Switch Transformers”; Du et al. “GLaM”
  • MPO：Wang et al. (2024) “Enhancing the Reasoning Ability of Multimodal Large Language Models via Mixed Preference Optimization”
  • C-RADIO：NVIDIA (2024-2025) 視覺 encoder
  • Parakeet：NVIDIA NeMo ASR 模型

11.6 競品 / 比較

11.7 Dataset 探索

完整 Nemotron 開源 dataset 索引在 README 的「Nemotron Data Catalogue」（折疊區塊），分類：

  • Code：Nemotron-CC-Code-v1 / Nemotron-Pretraining-Code-v1/v2 / Nemotron-Cascade-RL-SWE / Nemotron-Competitive-Programming-v1 / OpenCodeReasoning / OpenCodeReasoning-2 / Scoring-Verifiers
  • Math：Nemotron-CC-Math-v1 / Nemotron-Math-Proofs-v1 / Nemotron-Math-v2 / Nemotron-CrossThink / OpenMathReasoning（AIMO-2 winner）
  • Science / STEM：Nemotron-Science-v1
  • General / Web：（折疊區塊內更多）

11.8 商業 / 法務參考

📅 教學文件版本：2026-06-02 / 對應 repo commit ≤ 2026-06-01 / 對應 release v0.1.0 / 由 AI Knowledge Template Layer 12（gh-tutorial-qd）自動產生

🔐 重要法律提醒：

  • Repo LICENSE 為 Apache-2.0，但 pyproject.toml 寫 MIT — 以 LICENSE 檔為準
  • 模型權重大多為 NVIDIA Open Model License (NOML)，與 repo LICENSE 不同
  • 部分 dataset 為 NVIDIA Data Agreement 而非 CC-BY-4.0
  • 商用 / 內訓 / 再散佈前必須由法務逐一確認每個模型 / 資料集授權