diff --git a/.github/workflows/fern-docs-preview-build.yml b/.github/workflows/fern-docs-preview-build.yml new file mode 100644 index 000000000..1bd0f0b03 --- /dev/null +++ b/.github/workflows/fern-docs-preview-build.yml @@ -0,0 +1,31 @@ +# Copyright (c) 2026, NVIDIA CORPORATION. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Build half (collector) of the Fern docs preview pair. +# +# Fork-PR safe: collects fern/ sources and PR metadata into an artifact +# without using any secrets. The companion comment workflow runs in the +# base-repo context via workflow_run and consumes the artifact. +# +name: "Preview Fern Docs: Build" + +on: + pull_request: + paths: + - 'fern/**' + - '.github/workflows/fern-docs-preview-build.yml' + +jobs: + collect: + uses: NVIDIA-NeMo/FW-CI-templates/.github/workflows/_fern_docs_preview_build.yml@mmck-docs-fern diff --git a/.github/workflows/fern-docs-preview-cleanup.yml b/.github/workflows/fern-docs-preview-cleanup.yml new file mode 100644 index 000000000..6fb7b3b61 --- /dev/null +++ b/.github/workflows/fern-docs-preview-cleanup.yml @@ -0,0 +1,33 @@ +# Copyright (c) 2026, NVIDIA CORPORATION. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Cleanup half of the Fern docs preview cleanup pair. +# +# Triggered by workflow_run after "Preview Fern Docs: Close" completes. +# Reads the preview URL artifact and calls fern docs preview delete --url. +# +# Required repo or org secret: DOCS_FERN_TOKEN + +name: "Preview Fern Docs: Cleanup" + +on: + workflow_run: + workflows: ["Preview Fern Docs: Close"] + types: [completed] + +jobs: + cleanup: + uses: NVIDIA-NeMo/FW-CI-templates/.github/workflows/_fern_docs_preview_cleanup.yml@mmck-docs-fern + secrets: + DOCS_FERN_TOKEN: ${{ secrets.DOCS_FERN_TOKEN }} diff --git a/.github/workflows/fern-docs-preview-close.yml b/.github/workflows/fern-docs-preview-close.yml new file mode 100644 index 000000000..ae6a5870a --- /dev/null +++ b/.github/workflows/fern-docs-preview-close.yml @@ -0,0 +1,30 @@ +# Copyright (c) 2026, NVIDIA CORPORATION. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Close half (collector) of the Fern docs preview cleanup pair. +# +# Fork-PR safe: reads the preview URL marker from the PR comment using +# read-only GITHUB_TOKEN access and uploads it as an artifact for the +# cleanup workflow to consume. +# + +name: "Preview Fern Docs: Close" + +on: + pull_request: + types: [closed] + +jobs: + close: + uses: NVIDIA-NeMo/FW-CI-templates/.github/workflows/_fern_docs_preview_close_collect.yml@mmck-docs-fern diff --git a/.github/workflows/fern-docs-preview-comment.yml b/.github/workflows/fern-docs-preview-comment.yml new file mode 100644 index 000000000..81018971f --- /dev/null +++ b/.github/workflows/fern-docs-preview-comment.yml @@ -0,0 +1,34 @@ +# Copyright (c) 2026, NVIDIA CORPORATION. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Comment half of the Fern docs preview pair. +# +# Triggered by workflow_run after "Preview Fern Docs: Build" completes. +# Runs in the base-repo context, so DOCS_FERN_TOKEN is available even when +# the originating PR is from a fork. +# +# Required repo or org secret: DOCS_FERN_TOKEN + +name: "Preview Fern Docs: Comment" + +on: + workflow_run: + workflows: ["Preview Fern Docs: Build"] + types: [completed] + +jobs: + preview: + uses: NVIDIA-NeMo/FW-CI-templates/.github/workflows/_fern_docs_preview_comment.yml@mmck-docs-fern + secrets: + DOCS_FERN_TOKEN: ${{ secrets.DOCS_FERN_TOKEN }} diff --git a/.github/workflows/fern-docs-publish.yml b/.github/workflows/fern-docs-publish.yml new file mode 100644 index 000000000..6d5a491af --- /dev/null +++ b/.github/workflows/fern-docs-publish.yml @@ -0,0 +1,37 @@ +# Copyright (c) 2026, NVIDIA CORPORATION. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Publishes the Fern documentation site on push to main and on manual dispatch. +# +# Required repo or org secret: DOCS_FERN_TOKEN + +name: Publish Fern Docs + +on: + push: + branches: [main] + paths: + - 'fern/**' + - '.github/workflows/fern-docs-publish.yml' + workflow_dispatch: + +concurrency: + group: fern-docs-publish + cancel-in-progress: false + +jobs: + publish: + uses: NVIDIA-NeMo/FW-CI-templates/.github/workflows/_fern_docs_publish.yml@mmck-docs-fern + secrets: + DOCS_FERN_TOKEN: ${{ secrets.DOCS_FERN_TOKEN }} diff --git a/docs/_ext/nemotron_customize.py b/docs/_ext/nemotron_customize.py deleted file mode 100644 index 8dc746733..000000000 --- a/docs/_ext/nemotron_customize.py +++ /dev/null @@ -1,483 +0,0 @@ -from __future__ import annotations - -from pathlib import Path -import re -import tomllib - -from docutils import nodes -from docutils.parsers.rst import Directive -from docutils.statemachine import ViewList -from sphinx.application import Sphinx - - -REPO_ROOT = Path(__file__).resolve().parents[2] -GITHUB_BLOB_BASE = "https://github.com/NVIDIA-NeMo/Nemotron/blob/main" -GITHUB_TREE_BASE = "https://github.com/NVIDIA-NeMo/Nemotron/tree/main" - - -class StepTomlDirective(Directive): - required_arguments = 1 - has_content = False - - def run(self) -> list[nodes.Node]: - path = _resolve_repo_path(self.arguments[0]) - if not path.exists(): - return [_error(self, f"step-toml could not find file: {path}")] - - try: - data = _load_toml(path) - except Exception as exc: # pragma: no cover - surfaced in docs build - return [_error(self, f"step-toml failed to parse {path}: {exc}")] - - step = data.get("step", {}) - container = nodes.container(classes=["nemotron-step-toml"]) - - title = str(step.get("name") or path.parent.name) - container += nodes.rubric(text=title) - - description = step.get("description") or step.get("summary") - if description: - container += nodes.paragraph(text=str(description).strip()) - - metadata = nodes.field_list() - _append_field(metadata, "Category", [str(step.get("category", ""))]) - _append_field(metadata, "Tags", _normalize_sequence(step.get("tags"))) - if metadata.children: - container += metadata - - container.extend(_table_section("Consumes", [ - [ - str(entry.get("type", "")), - str(entry.get("description", "")), - _yes_no(entry.get("required", True)), - ] - for entry in _table_list(data.get("consumes")) - ], ["Type", "Description", "Required"])) - - container.extend(_table_section("Produces", [ - [ - str(entry.get("type", "")), - str(entry.get("description", "")), - ] - for entry in _table_list(data.get("produces")) - ], ["Type", "Description"])) - - container.extend(_table_section("Parameters", [ - [ - str(entry.get("name", "")), - str(entry.get("description", "")), - _format_scalar(entry.get("default")), - _format_sequence(entry.get("choices") or entry.get("values")), - ] - for entry in _table_list(data.get("parameters")) - ], ["Name", "Description", "Default", "Choices"])) - - container.extend(_table_section("Models", [ - [ - str(entry.get("name", "")), - str(entry.get("description") or entry.get("notes") or ""), - _format_scalar(entry.get("default")), - _format_scalar(entry.get("min_gpus")), - ] - for entry in _table_list(data.get("models")) - ], ["Name", "Description", "Default", "Min GPUs"])) - - strategies = _table_list(data.get("strategies")) - if strategies: - container += _list_admonition( - "Strategies", - "step-strategies", - [ - _join_parts( - [ - ("When", entry.get("when")), - ("Then", entry.get("then") or entry.get("recommendation")), - ("Skill", entry.get("skill")), - ] - ) - for entry in strategies - ], - ) - - errors = _table_list(data.get("errors")) - if errors: - container += _list_admonition( - "Errors", - "step-errors", - [ - _join_parts( - [ - ("Name", entry.get("name") or entry.get("symptom")), - ("Cause", entry.get("cause")), - ("Recovery", entry.get("recovery") or entry.get("fix")), - ("Skill", entry.get("skill")), - ] - ) - for entry in errors - ], - ) - - reference = data.get("reference", {}) - if isinstance(reference, dict) and reference: - container += nodes.rubric(text="Reference") - refs = nodes.bullet_list() - for key, value in reference.items(): - values = _normalize_sequence(value) - if not values: - continue - item = nodes.list_item() - item += nodes.paragraph(text=f"{key}:") - nested = nodes.bullet_list() - for raw in values: - nested_item = nodes.list_item() - nested_item += _link_paragraph(raw) - nested += nested_item - item += nested - refs += item - if refs.children: - container += refs - - return [container] - - -class TypesTomlDirective(Directive): - required_arguments = 1 - has_content = False - - def run(self) -> list[nodes.Node]: - path = _resolve_repo_path(self.arguments[0]) - if not path.exists(): - return [_error(self, f"types-toml could not find file: {path}")] - - try: - data = _load_toml(path) - except Exception as exc: # pragma: no cover - surfaced in docs build - return [_error(self, f"types-toml failed to parse {path}: {exc}")] - - type_entries = _extract_types(data) - rows = [] - for name in sorted(type_entries): - entry = type_entries[name] - converts = [] - for target, step in _normalize_mapping(entry.get("convert_to")).items(): - converts.append(f"{target} ({step})" if step else str(target)) - rows.append([ - name, - str(entry.get("description", "")), - _format_sequence(entry.get("is_a")), - ", ".join(converts), - ]) - - container = nodes.container(classes=["nemotron-types-toml"]) - container += _make_table( - ["Type", "Description", "Compatible With (is_a)", "Converts To"], - rows, - ) - - if _mermaid_enabled(self): - mermaid = _build_type_graph(type_entries) - if mermaid: - container += nodes.rubric(text="Type Graph") - mermaid_container = nodes.container(classes=["nemotron-type-graph"]) - view = ViewList() - view.append(".. mermaid::", "nemotron_customize") - view.append("", "nemotron_customize") - for line in mermaid.splitlines(): - view.append(f" {line}", "nemotron_customize") - self.state.nested_parse(view, self.content_offset, mermaid_container) - container += mermaid_container - - return [container] - - -def _resolve_repo_path(argument: str) -> Path: - path = Path(argument.strip()) - return path if path.is_absolute() else (REPO_ROOT / path).resolve() - - -def _load_toml(path: Path) -> dict: - with path.open("rb") as handle: - return tomllib.load(handle) - - -def _extract_types(data: dict) -> dict[str, dict]: - if isinstance(data.get("types"), dict): - types = {str(name): value for name, value in data["types"].items() if isinstance(value, dict)} - global_convert = _normalize_mapping(data.get("convert_to")) - for mapping in global_convert.values(): - if isinstance(mapping, dict): - source = str(mapping.get("from", "")) - target = str(mapping.get("to", "")) - step = str(mapping.get("step", "")) - if source and target and source in types: - convert_map = dict(_normalize_mapping(types[source].get("convert_to"))) - convert_map[target] = step - types[source]["convert_to"] = convert_map - return types - return {str(name): value for name, value in data.items() if isinstance(value, dict)} - - -def _make_table(headers: list[str], rows: list[list[str]]) -> nodes.table: - table = nodes.table() - tgroup = nodes.tgroup(cols=len(headers)) - table += tgroup - - for _ in headers: - tgroup += nodes.colspec(colwidth=1) - - thead = nodes.thead() - tgroup += thead - header_row = nodes.row() - thead += header_row - for header in headers: - entry = nodes.entry() - entry += nodes.paragraph(text=header) - header_row += entry - - tbody = nodes.tbody() - tgroup += tbody - for row_values in rows: - row = nodes.row() - tbody += row - for value in row_values: - entry = nodes.entry() - entry += nodes.paragraph(text=value) - row += entry - - return table - - -def _table_section(title: str, rows: list[list[str]], headers: list[str]) -> list[nodes.Node]: - if not rows: - return [] - return [nodes.rubric(text=title), _make_table(headers, rows)] - - -def _list_admonition(title: str, css_class: str, items: list[str]) -> nodes.admonition: - admonition = nodes.admonition(classes=["admonition", css_class]) - admonition += nodes.title(text=title) - bullet_list = nodes.bullet_list() - for item_text in items: - if not item_text: - continue - item = nodes.list_item() - item += _paragraph_with_links(item_text) - bullet_list += item - admonition += bullet_list - return admonition - - -def _append_field(field_list: nodes.field_list, name: str, values: list[str]) -> None: - cleaned = [value for value in values if value] - if not cleaned: - return - - field = nodes.field() - field += nodes.field_name(text=name) - body = nodes.field_body() - if len(cleaned) == 1: - body += nodes.paragraph(text=cleaned[0]) - else: - bullet_list = nodes.bullet_list() - for value in cleaned: - item = nodes.list_item() - item += nodes.paragraph(text=value) - bullet_list += item - body += bullet_list - field += body - field_list += field - - -def _normalize_sequence(value: object) -> list[str]: - if value is None: - return [] - if isinstance(value, str): - stripped = value.strip() - return [stripped] if stripped else [] - if isinstance(value, (list, tuple, set)): - return [str(item).strip() for item in value if str(item).strip()] - return [str(value).strip()] - - -def _normalize_mapping(value: object) -> dict[str, object]: - if isinstance(value, dict): - return {str(key): item for key, item in value.items()} - return {} - - -def _table_list(value: object) -> list[dict]: - if isinstance(value, list): - return [entry for entry in value if isinstance(entry, dict)] - return [] - - -def _format_scalar(value: object) -> str: - if value is None: - return "" - if isinstance(value, bool): - return "yes" if value else "no" - return str(value) - - -def _format_sequence(value: object) -> str: - return ", ".join(_normalize_sequence(value)) - - -def _yes_no(value: object) -> str: - return "yes" if bool(value) else "no" - - -def _join_parts(parts: list[tuple[str, object]]) -> str: - rendered = [] - for label, value in parts: - if value is None: - continue - text = _format_sequence(value) if isinstance(value, (list, tuple, set)) else str(value).strip() - if text: - rendered.append(f"{label}: {text}") - return "; ".join(rendered) - - -def _paragraph_with_links(text: str) -> nodes.paragraph: - paragraph = nodes.paragraph() - parts = re.split(r"(https?://\S+|(?:[A-Za-z0-9_.-]+/)+[A-Za-z0-9_.-]+/?(?:[A-Za-z0-9_.-]+)?)", text) - for part in parts: - if not part: - continue - if part.startswith("http://") or part.startswith("https://"): - paragraph += nodes.reference(text=part, refuri=part) - elif "/" in part and not part.startswith(" ") and not part.endswith(" "): - paragraph += nodes.reference(text=part, refuri=_repo_link(part)) - else: - paragraph += nodes.Text(part) - return paragraph - - -def _link_paragraph(value: str) -> nodes.paragraph: - paragraph = nodes.paragraph() - paragraph += nodes.reference(text=value, refuri=_repo_link(value)) - return paragraph - - -def _repo_link(value: str) -> str: - if value.startswith("http://") or value.startswith("https://"): - return value - candidate = value.strip() - if not candidate: - return value - if candidate.endswith("/") or Path(candidate).suffix == "": - return f"{GITHUB_TREE_BASE}/{candidate.rstrip('/')}" - return f"{GITHUB_BLOB_BASE}/{candidate}" - - -def _build_type_graph(type_entries: dict[str, dict]) -> str: - lines = ["flowchart LR"] - seen_edges: set[str] = set() - - for name in sorted(type_entries): - entry = type_entries[name] - for parent in _normalize_sequence(entry.get("is_a")): - edge = f' { _node_id(name) }["{name}"] -->|is_a| { _node_id(parent) }["{parent}"]' - if edge not in seen_edges: - lines.append(edge) - seen_edges.add(edge) - - for target, step in _normalize_mapping(entry.get("convert_to")).items(): - label = str(step) if step else "convert" - edge = ( - f' { _node_id(name) }["{name}"] -. "{label}" .-> ' - f'{ _node_id(str(target)) }["{target}"]' - ) - if edge not in seen_edges: - lines.append(edge) - seen_edges.add(edge) - - return "\n".join(lines) if len(lines) > 1 else "" - - -def _node_id(name: str) -> str: - sanitized = re.sub(r"[^A-Za-z0-9_]", "_", name) - return f"type_{sanitized}" - - -def _error(directive: Directive, message: str) -> nodes.error: - error = nodes.error() - error += nodes.paragraph(text=message) - return error - - -def _insert_after_title(doctree: nodes.document, node: nodes.Node) -> None: - if doctree.children and isinstance(doctree.children[0], nodes.section): - section = doctree.children[0] - if section.children and isinstance(section.children[0], nodes.title): - section.insert(1, node) - return - section.insert(0, node) - return - - if doctree.children and isinstance(doctree.children[0], nodes.title): - doctree.insert(1, node) - else: - doctree.insert(0, node) - - -def _frontmatter_admonition(title: str, css_class: str) -> nodes.admonition: - admonition = nodes.admonition(classes=["admonition", css_class]) - admonition += nodes.title(text=title) - return admonition - - -def _inject_frontmatter_admonitions(app: Sphinx, doctree: nodes.document, docname: str) -> None: - metadata = app.env.metadata.get(docname, {}) or {} - - triggers = _normalize_sequence(metadata.get("triggers")) - if triggers: - admonition = _frontmatter_admonition("Pattern Metadata", "pattern-metadata") - fields = nodes.field_list() - _append_field(fields, "Triggers", triggers) - _append_field(fields, "Steps", _normalize_sequence(metadata.get("steps"))) - _append_field(fields, "Confidence", _normalize_sequence(metadata.get("confidence"))) - _append_field(fields, "Tags", _normalize_sequence(metadata.get("tags"))) - admonition += fields - _insert_after_title(doctree, admonition) - - paper = metadata.get("paper") - if paper: - admonition = _frontmatter_admonition("Paper Reference", "paper-reference") - fields = nodes.field_list() - paper_value = str(paper) - if paper_value.startswith("arxiv:"): - paper_id = paper_value.split(":", 1)[1] - field = nodes.field() - field += nodes.field_name(text="Paper") - body = nodes.field_body() - paragraph = nodes.paragraph() - paragraph += nodes.reference(text=paper_value, refuri=f"https://arxiv.org/abs/{paper_id}") - body += paragraph - field += body - fields += field - else: - _append_field(fields, "Paper", [paper_value]) - _append_field(fields, "Section", _normalize_sequence(metadata.get("section"))) - _append_field(fields, "Summary", _normalize_sequence(metadata.get("summary"))) - admonition += fields - _insert_after_title(doctree, admonition) - - -def _mermaid_enabled(directive: Directive) -> bool: - env = getattr(directive.state.document.settings, "env", None) - app = getattr(env, "app", None) - if app is None: - return False - return "sphinxcontrib.mermaid" in app.extensions - - -def setup(app: Sphinx) -> dict[str, bool]: - app.add_directive("step-toml", StepTomlDirective) - app.add_directive("types-toml", TypesTomlDirective) - app.connect("doctree-resolved", _inject_frontmatter_admonitions) - return { - "version": "0.1", - "parallel_read_safe": True, - "parallel_write_safe": True, - } diff --git a/docs/application-examples.md b/docs/application-examples.md deleted file mode 100644 index 73c9f5a89..000000000 --- a/docs/application-examples.md +++ /dev/null @@ -1,92 +0,0 @@ - - - -(application-examples)= -# Application Examples - -End-to-end applications built on Nemotron models, including agentic workflows, RAG systems, and fine-tuning pipelines. Each card links to its directory in the [Nemotron GitHub repository](https://github.com/NVIDIA-NeMo/nemotron). - -::::{grid} 1 2 2 2 -:gutter: 3 - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Nemotron 3 Super Getting Started Guide -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/use-case-examples/Nemotron-3-Super-Getting-Started-Guide -:link-type: url - -Introductory notebook covering Nemotron 3 Super's reasoning features: thinking, reasoning budget, low effort mode, streaming responses, tool-call streaming, and Perplexity Search integration using the OpenAI-compatible API. -+++ -{bdg-success}`Notebook` {bdg-muted-line}`Mar 11, 2026` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` SQL LoRA Fine-tuning and Deployment -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/use-case-examples/sql-lora-finetuning-and-deployment -:link-type: url - -End-to-end LoRA fine-tuning of Nemotron 3 Nano on Text2SQL (BIRD SQL) with deployment via NVIDIA NIM or vLLM using NeMo AutoModel or Megatron Bridge. -+++ -{bdg-secondary}`Local GPU` {bdg-info}`Fine-tuning` {bdg-muted-line}`Mar 11, 2026` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Intelligent Document Processing -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/use-case-examples/Intelligent%20Document%20Processing%20with%20Nemotron%20RAG -:link-type: url - -IDP pipeline that extracts and queries complex enterprise documents — financial reports, charts, and tables — using NeMo Retriever and multimodal Nemotron models. -+++ -{bdg-secondary}`Local GPU` {bdg-muted-line}`Feb 09, 2026` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Voice RAG Agent -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/use-case-examples/nemotron-voice-rag-agent-example -:link-type: url - -End-to-end voice-driven RAG agent combining speech-to-text, multimodal retrieval, 1M-token reasoning, and safety guardrails using open Nemotron models. -+++ -{bdg-secondary}`Local GPU` {bdg-muted-line}`Jan 07, 2026` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Simple Nemotron 3 Nano Usage -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/use-case-examples/Simple%20Nemotron-3-Nano%20Usage%20Example -:link-type: url - -Introductory notebook covering basic inference, reasoning mode toggling, and multi-agent systems using the OpenAI-compatible API via OpenRouter and LangChain. -+++ -{bdg-success}`Notebook` {bdg-muted-line}`Dec 15, 2025` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Data Science ML Agent -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/use-case-examples/Data%20Science%20ML%20Agent -:link-type: url - -Natural language-driven ML agent built on Nemotron Nano 9B with GPU-accelerated data exploration and model training using RAPIDS cuDF and cuML. -+++ -{bdg-secondary}`Local GPU` {bdg-muted-line}`Nov 06, 2025` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` RAG Agent -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/use-case-examples/RAG%20Agent%20with%20Nemotron%20RAG%20Models -:link-type: url - -Production-ready RAG agent using local Hugging Face embedding and reranking models with NVIDIA AI Endpoints for LLM inference, built on LangGraph. -+++ -{bdg-secondary}`Local GPU` {bdg-muted-line}`Oct 28, 2025` -::: - -:::: diff --git a/docs/architecture/README.md b/docs/architecture/README.md deleted file mode 100644 index 07696e891..000000000 --- a/docs/architecture/README.md +++ /dev/null @@ -1,58 +0,0 @@ -# Nemotron Architecture - -This directory contains documentation about Nemotron's architecture and design principles. - -## Overview - -Nemotron is a **cookbook** - a reference implementation showing best practices for training LLMs at scale. It's not a framework you install; it's a codebase you fork and customize. - -## Documents - -- [Runspec Specification](../runspec/v1/spec.md) - The `[tool.runspec]` metadata format for recipe scripts -- [CLI Architecture](cli-architecture.md) - How the CLI layer works and how to fork it -- [Design Philosophy](design-philosophy.md) - What we optimize for and why - -## Quick Start - -```bash -# Run pretraining locally -nemotron nano3 pretrain -c tiny - -# Submit to cluster -nemotron nano3 pretrain -c tiny --run dgx - -# See what's happening (execution logic is visible in the code) -# Open: src/nemotron/cli/commands/nano3/pretrain.py -``` - -## Two-Layer Architecture - -| Layer | What | Where | Fork When | -|-------|------|-------|-----------| -| **Execution** | How to run and track experiments | `cli/commands/` + `nemo_runspec/` | nemo-run/wandb -> SkyPilot/mlflow | -| **Runtime** | Training/data processing | `recipes/` | Algorithm changes | - -``` -Execution Layer Runtime Layer (recipes/) -┌──────────────────────────┐ ┌─────────────────────┐ -│ cli/commands/nano3/ │ │ recipes/nano3/ │ -│ pretrain.py │ │ pretrain/train.py │ -│ │ │ │ -│ nemo_runspec (toolkit) │─────►│ Megatron-Bridge │ -│ config, execution, env │ │ │ -│ artifact registry │ │ │ -└──────────────────────────┘ └─────────────────────┘ -``` - -The runtime layer is typically a **thin script** that delegates to NVIDIA AI stack libraries. The execution layer contains all the job submission logic, which is what you'd change to swap nemo-run for SkyPilot or another backend. - -## Package Responsibilities - -| Package | Scope | -|---------|-------| -| **`nemo_runspec`** | Generic CLI toolkit: PEP 723 runspec parsing, config loading, env.toml profiles, execution helpers, packaging, pipeline orchestration, artifact registry (`art://` resolution, fsspec/wandb backends) | -| **`nemotron.kit`** | Domain-specific: artifact type definitions (pretrain data, SFT data, checkpoints), lineage trackers (W&B, file-based), W&B integration | -| **`nemotron.cli`** | CLI commands: visible execution logic per command, typer-based command tree | -| **`nemotron.recipes`** | Runtime scripts: training, data prep, RL (thin scripts delegating to NVIDIA AI stack) | - -Dependency direction: `nemotron.cli` -> `nemo_runspec` + `nemotron.kit` -> NVIDIA stack. Never the reverse. diff --git a/docs/assets/omni3/omni_loss_curve.png b/docs/assets/omni3/omni_loss_curve.png deleted file mode 100644 index 4cfa8305d..000000000 Binary files a/docs/assets/omni3/omni_loss_curve.png and /dev/null differ diff --git a/docs/assets/super3/latent_moe.png b/docs/assets/super3/latent_moe.png deleted file mode 100644 index 5f178d8fd..000000000 Binary files a/docs/assets/super3/latent_moe.png and /dev/null differ diff --git a/docs/broken_links_false_positives.json b/docs/broken_links_false_positives.json deleted file mode 100644 index bf56cdf87..000000000 --- a/docs/broken_links_false_positives.json +++ /dev/null @@ -1,3 +0,0 @@ -{ "filename": "use-case-examples/nemotron-voice-rag-agent-example/README.md", "lineno": 163, "status": "broken", "code": 0, "uri": "https://www.llama.com/llama3_1/license/", "info": "400 Client Error: Bad Request for url: https://www.llama.com/llama3_1/license/" } -{ "filename": "usage-cookbook/Nemotron-3-Super/grpo-dapo/README.md", "lineno": 9, "status": "broken", "code": 0, "uri": "https://www.reddit.com/r/OpenAI/comments/1i6jsr2/deepseek_discovered_their_new_model_having_an_aha", "info": "403 Client Error: Blocked for url: https://www.reddit.com/r/OpenAI/comments/1i6jsr2/deepseek_discovered_their_new_model_having_an_aha/" } -{ "filename": "nemotron/nano3/rl.md", "lineno": 101, "status": "broken", "code": 0, "uri": "https://docs.nvidia.com/nemo/rl/latest/guides/grpo.html#loss", "info": "RemoteDisconnected: Remote end closed connection without response" } diff --git a/docs/build-benchmarks/explanation/get-right-questions.md b/docs/build-benchmarks/explanation/get-right-questions.md deleted file mode 100644 index e32393876..000000000 --- a/docs/build-benchmarks/explanation/get-right-questions.md +++ /dev/null @@ -1,75 +0,0 @@ - - -# Getting the Right Questions From the Source Benchmark - -Choose the best rows from the Hugging Face source benchmark, such as Massive Multitask Language Understanding (MMLU), to use as few-shot examples for each target, from broad choices down to very specific tags. - -You control which source questions appear as few-shots by configuring coarse filters (`split`, `subset`, `hf_dataset`, `source_subjects`) and fine filters (`target_source_mapping`, and optional `tags` backed by `metadata_file`). -The intent is to show the model exemplars that match the subject you are generating for. - -In `nemotron steps run byob/mcq`, each key in `target_source_mapping` must match a folder of `.txt` files or a `*.parquet` file under `input_dir`, not an abstract label on its own. - -## The Funnel: Coarse to Fine-Grained Control - -Most question-answer benchmark datasets expose many subjects, such as astronomy, econometrics, elementary mathematics, nutrition, and so on. -Coarse filters shrink that universe before you attach sources to each local target. - -You can narrow step by step until each target draws from the pool you intend. - -```{image} ../_images/funnel.png -:class: .sd-p-1 -:width: 640px -:alt: Funnel from coarse to fine filtering: split, subset, source_subjects, then target_source_mapping with optional subjects and tags per target. -``` - -```{rubric} Coarse (top of funnel) -``` - -- `hf_dataset`: which Hugging Face benchmark to load, for example `cais/mmlu`. -- `split`: which split to read first, such as `test` or `train`, applied when the loader pulls the benchmark. -- `subset`: which variant of that benchmark, such as `all` for MMLU or `kn` for MMLU Indic, also applied at load time. -- `source_subjects`: which benchmark taxonomy labels may appear in the pool. - If you leave this list empty, the pipeline expands it to every subject available for the chosen `hf_dataset`, `subset`, and `split`. - Mappings only sample from subjects that remain in this pool. - -```{rubric} Finer (middle of funnel) -``` - -- `target_source_mapping`: for each target key that exists under `input_dir`, you list which source subjects to sample and optionally assign weights. - This ties each corpus folder or Parquet file to the part of the benchmark taxonomy you want the model to imitate. - -```{rubric} Finest (bottom of funnel) -``` - -- `tags`: optional. - When `metadata_file` lists question identifiers with tags, each target can filter few-shots further by tag strings such as `reasoning` or `unambiguous`, or by comma-joined combinations such as `reasoning,unambiguous`, optionally with weights. - Tags are the tightest lever on which rows become few-shots. - -## How It Fits Together - -1. Load: the pipeline loads the benchmark for `hf_dataset`, `split`, and `subset`, then keeps only the subjects in `source_subjects`, or all subjects when that list is empty after expansion. -1. Map: for each target, `target_source_mapping` names source subjects and optional tag sets to sample from. - Source subjects and tags each support explicit weights; otherwise sampling is uniform over the listed entries. -1. Sample: while building the seed dataset, the prepare step samples subject-tag pairs according to those weights and draws few-shot questions from the filtered source tables. - -The coarse settings define the global pool. -`target_source_mapping`, and tags when enabled, narrow which slice of that pool each target should use when it pairs exemplars with your domain chunks. - -## Configuration at a Glance - -| Control | Where | Effect | -| ------- | ----- | ------ | -| `hf_dataset` | Top-level config | Which Hugging Face dataset supplies few-shot rows. | -| `split` | Top-level config | Dataset split, such as `test`, taken from the source benchmark. | -| `subset` | Top-level config | Dataset subset, such as `all` or `kn`, applied before subject filtering. | -| `source_subjects` | Top-level config | Restricts which benchmark subjects remain in the pool; an empty list expands to all subjects for the chosen dataset, split, and subset. | -| `target_source_mapping` | Per target directory or Parquet | For each target under `input_dir`, which source subjects and optional tags to use, with optional weights. | - -## Related documentation - -- For full option details and validation rules, see {doc}`../reference/generate-config`. -- For allowed Hugging Face benchmarks and subsets, see {doc}`../reference/benchmarks`. -- For how the prepare step uses this mapping to build the seed dataset, see {doc}`data-preparation`. diff --git a/docs/build-benchmarks/explanation/index.md b/docs/build-benchmarks/explanation/index.md deleted file mode 100644 index d511b73fc..000000000 --- a/docs/build-benchmarks/explanation/index.md +++ /dev/null @@ -1,110 +0,0 @@ - - -# Concepts - -These pages explain how the `mcq` family inside `src/nemotron/steps/byob` prepares data, runs each generation stage, and optionally translates benchmarks. - -```{toctree} -:maxdepth: 2 -:hidden: - -pipeline-overview -Data Preparation -Get the Right Questions -question-generation -quality-validation -filtering -translation -``` - -## Architecture - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`workflow;1.5em;sd-mr-1` Pipeline overview -:link: pipeline-overview -:link-type: doc -Prepare, generate, translate, and the Parquet stage cache. -+++ -{bdg-secondary}`stages` -::: - -:::: - -## Core processes - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`database;1.5em;sd-mr-1` Data preparation -:link: data-preparation -:link-type: doc -Seeds from Hugging Face plus local corpus chunks. -+++ -{bdg-secondary}`few-shot` -::: - -:::{grid-item-card} {octicon}`cross-reference;1.5em;sd-mr-1` Mapping targets to sources -:link: get-right-questions -:link-type: doc -`source_subjects`, weights, and optional tags. -+++ -{bdg-secondary}`target_source_mapping` -::: - -:::{grid-item-card} {octicon}`sparkle-fill;1.5em;sd-mr-1` Question generation -:link: question-generation -:link-type: doc -Data Designer batched calls from prepared seeds. -+++ -{bdg-secondary}`generation` -::: - -:::: - -## Quality assurance - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`checklist;1.5em;sd-mr-1` Validation stack -:link: quality-validation -:link-type: doc -Judgement, deduplication, distractors, coverage, outliers. -+++ -{bdg-secondary}`validation` -::: - -:::{grid-item-card} {octicon}`filter;1.5em;sd-mr-1` Filtering -:link: filtering -:link-type: doc -Easiness and hallucination scores with removal flags. -+++ -{bdg-secondary}`filtering` -::: - -:::: - -## Translation - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`globe;1.5em;sd-mr-1` Translation -:link: translation -:link-type: doc -Curator translation, backtranslation, metrics, final schema. -+++ -{bdg-secondary}`translate` -::: - -:::: - -## Next steps - -- Hands-on first run: {doc}`../getting-started` -- YAML tables: {doc}`../reference/index` diff --git a/docs/build-benchmarks/getting-started.md b/docs/build-benchmarks/getting-started.md deleted file mode 100644 index 7132ed55f..000000000 --- a/docs/build-benchmarks/getting-started.md +++ /dev/null @@ -1,104 +0,0 @@ - - -(getting-started-byob-mcq)= -# Getting Started with Building MCQ Benchmarks - - - -::::{grid} 2 - -:::{grid-item-card} -:columns: 8 - -**What You'll Build**: A small multiple-choice question (MCQ) benchmark for math questions from the sample `tiny` configuration. -You'll run the `nemotron steps run byob/mcq` command and it will use an NVIDIA-hosted model endpoint for inference. - -^^^ - -**In this tutorial, you will**: - -1. Install Python dependencies. -2. Run the `tiny` configuration from the repository root. -3. Locate outputs and scan the main Parquet artifacts. -4. Confirm `benchmark.parquet` columns against the output reference. - -{octicon}`clock;1.5em;sd-mr-1` This tutorial requires between 10 and 15 minutes to complete. -::: - -:::{grid-item-card} -:columns: 4 - -{octicon}`flame;1.5em;sd-mr-1` **Sample Prompt** - -^^^ - -Help me create an MCQ benchmark using the `tiny` configuration from the Nemotron repository clone, write outputs under `./output`, then show me which Parquet files to open first. - -::: -:::: - -## Start Here - -- Run all commands from the repository root so the `input_dir` path in the procedure resolves. -- The sample configuration uses the `cais/mmlu` dataset from Hugging Face for few-shot examples of multiple-choice questions. -- The sample configuration uses the `src/nemotron/steps/byob/data/tiny_input/maths/tiny.txt` file for input. - - ```{literalinclude} ../../src/nemotron/steps/byob/data/tiny_input/maths/tiny.txt - ``` - -## Prerequisites - -- You have a host with access to https://integrate.api.nvidia.com. -- The `uv` tool available in your shell. -- `NVIDIA_API_KEY` exported in the same shell session before you run the procedure. - The default model for the configuration is `openai/gpt-oss-120b`. - -## Procedure - -1. Clone the repository: - - ```console - git clone https://github.com/NVIDIA-NeMo/Nemotron && cd Nemotron - ``` - -1. From the repository root, add the dependencies for building benchmarks: - - ```console - uv sync --extra byob - ``` - -1. Run generation with host paths. - The `tiny` configuration sets `stage: all`. - This stage setting chains the data preparation and then generation for MCQ. - - ```console - uv run nemotron steps run byob/mcq \ - -c tiny \ - family=mcq \ - stage=all \ - input_dir="./src/nemotron/steps/byob/data/tiny_input" \ - output_dir=./byob-output - ``` - - When the `-c` / `--config` argument is not a path, the command resolves the config file name in the `src/nemotron/steps/byob/mcq/config/` directory. - - When the command finishes, list the `./byob-output/byob_mcq_tiny/` directory. - The `expt_name` field in the `src/nemotron/steps/byob/mcq/config/tiny.yaml` file specifies that directory. - Look for the following files: - - - `stage_cache/*.parquet`, one file per intermediate stage, described in {doc}`reference/output-files` - - `benchmark_raw.parquet`, the full row set before optional removals - - `benchmark.parquet`, the final `mcq` schema for downstream use - -1. Open `benchmark.parquet` with Pandas, Polars, or another Parquet-aware tool and confirm columns match {doc}`reference/output-files`. - -## Next Steps - -For background on how stages connect, read {doc}`explanation/pipeline-overview`. -For task-focused changes, continue with: - -- Swap in your own corpus and mapping: {doc}`how-to/prepare-data`. -- Tune endpoints and keys: {doc}`how-to/custom-model-endpoints`. diff --git a/docs/build-benchmarks/how-to/index.md b/docs/build-benchmarks/how-to/index.md deleted file mode 100644 index 7b6c1694e..000000000 --- a/docs/build-benchmarks/how-to/index.md +++ /dev/null @@ -1,94 +0,0 @@ - - -# How-To Guides - -Task-focused guides for `nemotron steps run byob/mcq` with the `mcq` family. - -Start with {doc}`../getting-started` if you have not produced `benchmark.parquet` yet. - -```{toctree} -:maxdepth: 1 -:hidden: - -Prepare Data -Use Your Domain Data -Model Endpoints -Tune Prompts -Skip Stages -``` - -## Setup and configuration - -::::{grid} 1 1 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`file-directory;1.5em;sd-mr-1` Prepare your data -:link: prepare-data -:link-type: doc -Lay out `input_dir`, text or Parquet inputs, and `target_source_mapping`. -+++ -{bdg-secondary}`input_dir` -::: - -:::{grid-item-card} {octicon}`database;1.5em;sd-mr-1` Domain corpus files -:link: domain-data -:link-type: doc -Create per-target directories of `.txt` files and match them to YAML. -+++ -{bdg-secondary}`corpus` -::: - -:::{grid-item-card} {octicon}`gear;1.5em;sd-mr-1` Model endpoints -:link: custom-model-endpoints -:link-type: doc -Configure OpenAI-compatible providers for generation, judgement, expansion, validity, and filters. -+++ -{bdg-secondary}`yaml` -::: - -:::: - -## Advanced workflows - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`comment;1.5em;sd-mr-1` Prompt tuning -:link: prompt-tuning -:link-type: doc -Point `prompt_config` at a YAML file that defines stage templates. -+++ -{bdg-secondary}`prompt` -::: - -:::{grid-item-card} {octicon}`sync;1.5em;sd-mr-1` Skip stages -:link: skip-stages -:link-type: doc -Resume with `skip_until` and cached Parquet files. -+++ -{bdg-secondary}`iteration` -::: - -:::: - -## Workflow overview - -```{mermaid} -flowchart LR - A[Prepare data layout] --> B[Edit YAML] - B --> C[uv run nemotron steps run byob/mcq] - C --> D{Need translation?} - D -->|yes| E[translate config + passthrough] - D -->|no| F[Done] - E --> F - C -.->|iterate| G[skip_until] - G --> C -``` - -## Related documentation - -- {doc}`../explanation/index` — how each stage behaves. -- {doc}`../reference/index` — full field lists and allowed datasets. diff --git a/docs/build-benchmarks/index.md b/docs/build-benchmarks/index.md deleted file mode 100644 index 6c7aa6356..000000000 --- a/docs/build-benchmarks/index.md +++ /dev/null @@ -1,147 +0,0 @@ - - -(build-benchmarks-index)= -# About Building Multiple-Choice Question Benchmarks - - - -This section describes how to build a custom multiple-choice question (MCQ) benchmark as Apache Parquet files with the `nemotron steps run byob/mcq` command. -You supply domain text files under `input_dir`, and the pipeline samples few-shot exemplars from a Hugging Face benchmark named in your configuration, such as `cais/mmlu`. -The configuration specifies subject filters such as `high_school_mathematics`. - -The benchmark step prepares seed rows, generates and judges questions, runs optional deduplication and distractor stages, and writes `benchmark.parquet`. -An optional translation stage reads an existing benchmark and writes another `benchmark.parquet` with the same column layout. - -:::{tip} -New to this flow? Follow {doc}`getting-started` once, then use the grids and tables below to jump to how-to guides, concepts, or reference pages. -::: - -## When to Use - -The `nemotron steps run byob/mcq` command enables the following outcomes. - -- Questions grounded in your own documents, paired with few-shot items from a public benchmark subject you declare in configuration. -- A repeatable Parquet artifact, one experiment folder under your configured `output_dir`, plus intermediate caches when you iterate. -- Optional translation with forward passes, backtranslation, and metric thresholds before you export another Parquet benchmark. - -## Pipeline Summary - -At a high level, the benchmark step performs the following work. - -1. Prepare: sample few-shot examples and align them with chunks from your corpus into a seed dataset. -2. Generate: run the staged MCQ pipeline from generation through filtering into `benchmark_raw.parquet` and `benchmark.parquet`. -3. Translate, optional: translate questions and options, score backtranslation quality, and export a new `benchmark.parquet`. - -## Documentation Series - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`book;1.5em;sd-mr-1` Tutorial -:link: getting-started -:link-type: doc -Install the `byob` extra, run the sample `tiny` configuration with local paths, and inspect Parquet outputs. -The `tiny` fixture pairs `cais/mmlu` high school mathematics few-shots with a one-line input file related to algebra. -+++ -{bdg-secondary}`hands-on` -::: - -:::{grid-item-card} {octicon}`tools;1.5em;sd-mr-1` How-To Guides -:link: how-to/index -:link-type: doc -Prepare data, tune models in YAML, customize prompts, and resume with `skip_until`. -+++ -{bdg-secondary}`task-based` -::: - -:::{grid-item-card} {octicon}`light-bulb;1.5em;sd-mr-1` Concepts -:link: explanation/index -:link-type: doc -How prepare, generate, and translate stages fit together and what each configuration block does. -+++ -{bdg-secondary}`concept-focused` -::: - -:::{grid-item-card} {octicon}`list-unordered;1.5em;sd-mr-1` Reference -:link: reference/index -:link-type: doc -Supported Hugging Face datasets, Parquet outputs, and YAML fields. -+++ -{bdg-secondary}`specification` -::: - -:::: - -## All Documentation - -````{tab-set} - -```{tab-item} Tutorial - -| Guide | What you will do | -| --- | --- | -| {doc}`./getting-started` | Run `nemotron steps run byob/mcq` with `tiny` and inspect outputs | - -``` - -```{tab-item} How-To Guides - -| Guide | What you will do | -| --- | --- | -| {doc}`how-to/prepare-data` | Lay out `input_dir` and `target_source_mapping` | -| {doc}`how-to/domain-data` | Lay out per-target `.txt` corpora under `input_dir` | -| {doc}`how-to/custom-model-endpoints` | Point generation, judgement, and filter models at your endpoints | -| {doc}`how-to/prompt-tuning` | Override prompts with a YAML file | -| {doc}`how-to/skip-stages` | Resume after intermediate Parquet caches | - -``` - -```{tab-item} Concepts - -| Guide | What you will learn | -| --- | --- | -| {doc}`explanation/pipeline-overview` | Stage order for prepare, generate, and translate | -| {doc}`explanation/data-preparation` | Seeds, chunking, and the prepare step | -| {doc}`explanation/get-right-questions` | `source_subjects` and `target_source_mapping` | -| {doc}`explanation/question-generation` | Data Designer batched generation | -| {doc}`explanation/quality-validation` | Judgement, deduplication, distractors, coverage, outliers | -| {doc}`explanation/filtering` | Easiness and hallucination filters | -| {doc}`explanation/translation` | Curator translation and backtranslation metrics | - -``` - -```{tab-item} Reference - -| Guide | What you will find | -| --- | --- | -| {doc}`reference/output-files` | Paths under `output_dir` / `expt_name` | -| {doc}`reference/troubleshooting` | Symptom-to-fix index for BYOB runs | -| {doc}`reference/benchmarks` | Allowed `hf_dataset` values and default subsets | -| {doc}`reference/generate-config` | Generation YAML keys | -| {doc}`reference/translation-config` | Translation YAML keys | - -``` - -```` - -## What You Need - -- A Nemotron clone with dependencies installed, including the `byob` extra from `uv sync --extra byob`. -- Model credentials and endpoints that match the `generation_model_config`, `judge_model_config`, and related blocks in your YAML, as described in {doc}`how-to/custom-model-endpoints`. -- Network access to download the configured Hugging Face benchmark split unless it is already cached on disk. - -## Quick Start - -1. Follow {doc}`getting-started` if you have not run the step yet. -2. Read {doc}`how-to/prepare-data` when you are ready to point the pipeline at your own corpus and mapping. -3. Open {doc}`reference/generate-config` or {doc}`reference/translation-config` when you need field-level YAML detail. - -## Limitations and Considerations - -- Cost: generation, judgement, expansion, validity checks, and filters call remote models whenever you configure them to do so. -- Time: full runs depend on corpus size, model latency, and which optional stages stay enabled. -- Rate limits: hosted APIs may throttle parallel requests that you set under `inference_parameters`. -- Curator mount: checked-in configurations mount NeMo Curator from Git for translation and deduplication-related paths, so remote profiles must expose that tree the same way your environment expects. diff --git a/docs/build-benchmarks/reference/benchmarks.md b/docs/build-benchmarks/reference/benchmarks.md deleted file mode 100644 index 5b1099dc0..000000000 --- a/docs/build-benchmarks/reference/benchmarks.md +++ /dev/null @@ -1,24 +0,0 @@ - - -# Supported Hugging Face Benchmarks - -`hf_dataset` in your generation YAML must be one of the strings in `ALLOWED_HF_DATASETS` inside `src/nemotron/steps/byob/runtime/constants.py`. - -If you omit `subset` in YAML, `ByobConfig.from_yaml` substitutes the default from `HF_DATASET_TO_SUBSET`. - -| `hf_dataset` | Default `subset` when omitted | -| --- | --- | -| `cais/mmlu` | `all` | -| `TIGER-Lab/MMLU-Pro` | `default` | -| `ai4bharat/MILU` | `English` | -| `CohereLabs/Global-MMLU` | `en` | -| `CohereLabs/Global-MMLU-Lite` | `en` | -| `LinguaLift/IndicMMLU-Pro` | `hindi` | -| `openai/MMMLU` | `default` | -| `sarvamai/mmlu-indic` | `en` | -| `Idavidrein/gpqa` | `gpqa_main` | - -Each identifier maps to the shared MCQ dataset implementation through `HF_DATASET_TO_MODULE`, which currently resolves every row to `nemotron.steps.byob.runtime.benchmark_families.mcq`. diff --git a/docs/build-benchmarks/reference/generate-config.md b/docs/build-benchmarks/reference/generate-config.md deleted file mode 100644 index d911da5df..000000000 --- a/docs/build-benchmarks/reference/generate-config.md +++ /dev/null @@ -1,75 +0,0 @@ - - -# Generation Configuration Reference - -This page lists the YAML keys validated inside `ByobConfig.from_yaml` in `runtime/config.py`. -Optional keys show their defaults in the dataclass or in the `get` calls inside `from_yaml`. - -## Experiment layout - -| Key | Notes | -| --- | --- | -| `expt_name` | Required string; builds `output_dir/expt_name/`. | -| `output_dir` | Required writable directory. | -| `input_dir` | Required path containing each `target_source_mapping` corpus. | -| `random_seed` | Optional; seeds Python and NumPy when present. | -| `ndd_batch_size` | Optional positive int; defaults to `1000` in the dataclass but sample configs use smaller values. | - -## Dataset selection - -| Key | Notes | -| --- | --- | -| `hf_dataset` | Must appear in `ALLOWED_HF_DATASETS`. | -| `subset` | Optional; defaults per {doc}`benchmarks`. | -| `split` | Optional; defaults to `"test"`. | -| `language` | Required string (for example `en-US`). | -| `metadata_file` | Optional CSV path enabling tag-aware sampling. | - -## Subjects and sampling - -| Key | Notes | -| --- | --- | -| `source_subjects` | Required non-empty list of benchmark subject strings. | -| `target_source_mapping` | Required mapping; see {doc}`../how-to/prepare-data`. | -| `few_shot_samples_per_query` | Required positive int. | -| `queries_per_target_subject_document` | Required positive int. | -| `num_questions_per_query` | Required positive int. | - -## Prompts and models - -| Key | Notes | -| --- | --- | -| `prompt_config` | `null` loads packaged defaults; a string path loads YAML with all required stages. | -| `generation_model_config` | Required mapping for Data Designer calls. | -| `judge_model_config` | Required mapping. | -| `do_distractor_expansion` | Required bool. | -| `distractor_expansion_model_config` | Required when expansion is true. | -| `distractor_validity_model_config` | Required mapping. | -| `filtering_model_configs` | Required dict with `hallucination` and `easiness` lists. | -| `easiness_threshold` | Required float in `[0, 1]`. | -| `hallucination_threshold` | Required float in `[0, 1]`. | -| `remove_hallucinated` | Optional bool; defaults to `True`. | -| `remove_easy` | Optional bool; defaults to `False`. | - -## Optional quality stages - -| Key | Notes | -| --- | --- | -| `semantic_deduplication_config` | Dict with `enabled`, embedding model id, clustering parameters, and `remove_duplicates`. | -| `semantic_outlier_detection_config` | Dict with `enabled`, embedding model id, and neighbour thresholds. | -| `chunking_config` | Dict; supports `window_size` (`null` keeps whole documents). | -| `do_coverage_check` | Bool; defaults to `False` when omitted. | -| `coverage_check_config` | Dict with `window_size` and `model_identifier`. | - -## Curator mount - -Sample configs include a `run.env.mounts` entry that uses `${auto_mount:...}` to place NeMo Curator on `/opt/Curator`. -Remote profiles must preserve the same mount contract your environment expects. - -## Stage dispatch for `nemotron steps run` - -The generic steps CLI accepts `family`, `stage`, and `skip_until` as dotlist overrides, and you can also place those keys directly in YAML. -`family` defaults to `mcq` when omitted. diff --git a/docs/build-benchmarks/reference/index.md b/docs/build-benchmarks/reference/index.md deleted file mode 100644 index b9f0e2ddf..000000000 --- a/docs/build-benchmarks/reference/index.md +++ /dev/null @@ -1,85 +0,0 @@ - - -# Reference - -Specifications grounded in `src/nemotron/steps/byob`. - -```{toctree} -:maxdepth: 1 -:hidden: - -benchmarks -output-files -generate-config -translation-config -troubleshooting -``` - -## Outputs - -::::{grid} 1 1 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`file-code;1.5em;sd-mr-1` Output files -:link: output-files -:link-type: doc -Seed, stage cache, raw and final Parquet paths. -+++ -{bdg-secondary}`parquet` -::: - -:::{grid-item-card} {octicon}`alert;1.5em;sd-mr-1` Troubleshooting -:link: troubleshooting -:link-type: doc -Common configuration errors, missing caches, filtering, and endpoint issues. -+++ -{bdg-secondary}`faq` -::: - -:::: - -## Configuration - -::::{grid} 1 1 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`gear;1.5em;sd-mr-1` Generation YAML -:link: generate-config -:link-type: doc -Required keys for `ByobConfig.from_yaml`. -+++ -{bdg-secondary}`yaml` -::: - -:::{grid-item-card} {octicon}`globe;1.5em;sd-mr-1` Translation YAML -:link: translation-config -:link-type: doc -`ByobTranslationConfig.from_yaml` requirements. -+++ -{bdg-secondary}`yaml` -::: - -:::: - -## Source benchmarks - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`database;1.5em;sd-mr-1` Allowed Hugging Face datasets -:link: benchmarks -:link-type: doc -Identifiers and default subsets from `runtime/constants.py`. -+++ -{bdg-secondary}`hf_dataset` -::: - -:::: - -## Related documentation - -- Tutorial: {doc}`../getting-started` -- Concepts: {doc}`../explanation/index` diff --git a/docs/build-benchmarks/reference/output-files.md b/docs/build-benchmarks/reference/output-files.md deleted file mode 100644 index 951a992e3..000000000 --- a/docs/build-benchmarks/reference/output-files.md +++ /dev/null @@ -1,88 +0,0 @@ - - -# Output Files - -All paths below are relative to `output_dir` from your YAML and the string `expt_name`. - -## Prepare - -| File | Description | -| --- | --- | -| `seed.parquet` | Few-shot rows plus domain chunks. | - -## Generate - -The final generation creates these files: - -| File | Description | -| --- | --- | -| `benchmark_raw.parquet` | Snapshot immediately before column renaming for the final schema. | -| `benchmark.parquet` | Final MCQ schema; column meanings and a sample row are in the next section. | - -The following intermediate files that are created in the `stage_cache` directory: - -| File | Stage | -| --- | --- | -| `generated_questions.parquet` | GENERATION | -| `judged_questions.parquet` | JUDGEMENT | -| `semantic_deduplicated_questions.parquet` | SEMANTIC_DEDUPLICATION | -| `expanded_distractors.parquet` | DISTRACTOR_EXPANSION (only when `do_distractor_expansion` is true) | -| `coverage_check.parquet` | COVERAGE_CHECK (only when `do_coverage_check` is true) | -| `valid_distractors.parquet` | DISTRACTOR_VALIDITY_CHECK | -| `semantic_outlier_detection.parquet` | SEMANTIC_OUTLIER_DETECTION | -| `filtered_questions.parquet` | HALLUCINATION_EASINESS_DETECTION | - -(final-mcq-columns)= -## Final MCQ Columns - -Generation and translation both export the same eight columns on the final `benchmark.parquet` file. - -| Column | Meaning | -| --- | --- | -| `question_id` | Stable identifier for the row, taken from the internal `id_question` field before export. | -| `question` | Stem text for the multiple-choice item. After translation this is the target-language text. | -| `options` | Ordered list of choice strings. The list order matches the letter labels implied by `answer_index`. | -| `answer_index` | Zero-based index into `options` for the correct choice. | -| `answer` | Letter label for the correct choice, derived from `answer_index` (`0` → `A`, `1` → `B`, and so on). | -| `cot_content` | Reserved for chain-of-thought text. The current pipeline sets this column to the literal `-` for every row on export. | -| `src` | Reserved for a source document marker. The current pipeline sets this column to the literal `-` for every row on export. | -| `category` | Target key from `target_source_mapping` in your generation configuration, in other words the domain bucket name for the row, not the Hugging Face few-shot subject name. | - -### Sample Row - -Values below are illustrative; your identifiers and wording will differ. - -```json -{ - "question_id": "mcq-00042", - "question": "If x^2 = 9, which value can x take?", - "options": ["-3 only", "-3 or 3", "3 only", "9"], - "answer_index": 1, - "answer": "B", - "cot_content": "-", - "src": "-", - "category": "maths" -} -``` - -## Translate - -The translate stage creates the following final output files: - -| File | Description | -| --- | --- | -| `benchmark_raw.parquet` | Intermediate snapshot prior to optional quality filtering. | -| `benchmark.parquet` | Final translated MCQ after fields are renamed back to `question`, `options`, `answer_index`, and `answer`. Column semantics match generation; see {ref}`final-mcq-columns`. | - -The following intermediate files are created in the `staged_cache` directory. - -| File | Stage | -| --- | --- | -| `translated_questions.parquet` | TRANSLATION | -| `backtranslated_questions.parquet` | BACKTRANSLATION | -| `quality_metrics.parquet` | QUALITY_METRICS | - -Intermediate translation Parquet files can include additional columns such as `question_translated`, `options_translated`, backtranslation fields, and metric scores. diff --git a/docs/build-benchmarks/reference/translation-config.md b/docs/build-benchmarks/reference/translation-config.md deleted file mode 100644 index ee77f4241..000000000 --- a/docs/build-benchmarks/reference/translation-config.md +++ /dev/null @@ -1,51 +0,0 @@ - - - - -# Translation Configuration Reference - -This page describes the YAML configuration file that you provide for the translate stage: the keys you set or override, how backtranslation quality scores show up in Parquet output columns, and which rows are omitted from the final `benchmark.parquet` when quality filtering is enabled. - -## Required Keys - -| Key | Notes | -| --- | --- | -| `expt_name` | Directory name under `output_dir` for caches and final artifacts. | -| `dataset_path` | Existing `benchmark.parquet` from a generation run. | -| `output_dir` | Parent directory for `expt_name`. | -| `source_language` | BCP-47 style tag (for example `en-US`). | -| `target_language` | Target locale tag (for example `hi-IN`). | -| `translation_model_config` | Dictionary with `backend_type`, `params`, and optional `stage` and `segment_stage`. | -| `backtranslation_quality_metrics` | Non-empty list; each element is a dictionary with `type` and `threshold`. | - -## Quality Metrics - -Each `type` must be `sacrebleu`, `chrf`, or `ter`. -Each `threshold` must be nonnegative. - -NeMo Curator writes one numeric score column and one boolean pass column per configured metric, for example `score_chrf` and `score_chrf_passed`. -The column `is_quality_metric_passed` is true on a row when every per-metric pass column is true for that row. - -Each score compares the original benchmark text with the round-trip backtranslation from the target locale, using sentence-level APIs from the *sacrebleu* library. - -| `type` | Measures | Scale and direction | How to interpret scores | Row passes when | -| --- | --- | --- | --- | --- | -| `sacrebleu` | Sentence bilingual evaluation understudy (BLEU) | 0 through 100 after *sacrebleu* tokenization; higher values track closer matches to the reference. | High scores mean the backtranslation preserved wording and order; scores near zero mean little *n*-gram overlap. | `score_sacrebleu` ≥ `threshold` | -| `chrf` | Sentence character n-gram F-score (chrF) | 0 through 100 in typical sentence outputs; higher values mean closer character-level match. | High scores track spelling and phrasing fidelity; low scores mean the backtranslation diverged on the surface string. | `score_chrf` ≥ `threshold` | -| `ter` | Sentence translation error rate (TER) | Zero means no edits; larger values report more insertions, deletions, or substitutions relative to the reference. | Values close to zero mean the backtranslation needed minimal editing to match the original; large values signal heavy rewrites or mismatch. | `score_ter` ≤ `threshold` | - -Inspect `stage_cache/quality_metrics.parquet` under your experiment directory to pick thresholds from the score spread you see in data. - -## Optional Keys - -| Key | Default | Notes | -| --- | --- | --- | -| `remove_low_quality` | `True` unless YAML overrides it | When true, the pipeline omits rows where `is_quality_metric_passed` is false before export. | - -## FAITH evaluation - -`translation_model_config.stage.enable_faith_eval` must not be true. -The benchmark translation relies on backtranslation metrics instead of FAITH filtering diff --git a/docs/build-benchmarks/reference/troubleshooting.md b/docs/build-benchmarks/reference/troubleshooting.md deleted file mode 100644 index cd676939d..000000000 --- a/docs/build-benchmarks/reference/troubleshooting.md +++ /dev/null @@ -1,57 +0,0 @@ - - - - -# Troubleshooting - -This page lists common symptoms when you run `nemotron steps run byob/mcq` with the bring your own benchmark (BYOB) multiple choice question (MCQ) family and when you tune BYOB translation settings. -Each table row pairs a symptom with the files, fields, or flags you should inspect first. -For stage flow and design rationale, see the explanation pages linked from {doc}`../explanation/index`. - -## Configuration Rejected Before the Pipeline Runs - -| Symptom | What to do | -| --- | --- | -| Assertion that `tags` should not be specified when `metadata_file` is absent | Remove `tags` from every `target_source_mapping` entry, or set top-level `metadata_file` to the comma-separated values (CSV) file that supplies tag metadata. See {doc}`../how-to/prepare-data`. | -| Assertion that BYOB translation does not support FAITH evaluation | Under `translation_model_config.stage`, set `enable_faith_eval` to false or omit the field. BYOB translation expects `backtranslation_quality_metrics` instead of FAITH. See {doc}`translation-config` and {doc}`../explanation/translation`. | -| Message that a prompt override key is missing or is not a string, or validation fails on `prompt_config` | Open your `prompt_config` YAML and match the structure in {doc}`../how-to/prompt-tuning`. Easiness and hallucination overrides must include the expected blocks. | -| Schema validation reports that `distractor_validity_model_config` is missing | The current generation schema requires this block even when distractor expansion is off. Add the block as described in {doc}`../how-to/custom-model-endpoints`. | - -## Skipped Stages and Missing Parquet Inputs - -| Symptom | What to do | -| --- | --- | -| A stage fails because an expected Parquet file is missing under `output_dir//stage_cache/` | When you use `skip_until`, every stage before the resume point must have written its output file to disk. Rerun from an earlier stage without skipping, or copy valid caches from a prior run. See {doc}`../how-to/skip-stages`. | - -## Generation Ends With No Final Benchmark Rows - -| Symptom | What to do | -| --- | --- | -| Log line `No questions left after filtering`, or `benchmark.parquet` is missing after a run that exited early | Open `stage_cache/filtered_questions.parquet` and inspect `is_easy`, `is_hallucination`, and score columns. Loosen `easiness_threshold` or `hallucination_threshold`, set `remove_easy` and `remove_hallucinated` to false for a diagnostic run, or adjust upstream judgement and deduplication settings. See {doc}`../explanation/filtering`. | - -## Translation Export Drops Every Row - -| Symptom | What to do | -| --- | --- | -| `benchmark.parquet` exists but has zero rows after translation | When `remove_low_quality` is true, only rows with `is_quality_metric_passed` are exported. Inspect `stage_cache/quality_metrics.parquet`, relax metric thresholds in `backtranslation_quality_metrics`, or set `remove_low_quality` to false while you tune. See {doc}`../explanation/translation`. | - -## Few-Shot Sampling Finds No Rows - -| Symptom | What to do | -| --- | --- | -| Runtime error stating there are no samples for a given source subject and tag combination | Tag filters must match comma-separated tag strings that appear in the metadata CSV for that Hugging Face subject. Widen `tags`, correct the CSV, or confirm `source_subjects` and `target_source_mapping` names align with {doc}`../how-to/prepare-data` and {doc}`../explanation/get-right-questions`. | - -## Hosted Models Throttle or Stall - -| Symptom | What to do | -| --- | --- | -| Timeouts, HTTP responses in the 429 range, or bursty failures when calling remote endpoints | Reduce `max_parallel_requests` and related batch settings in your YAML, rerun on a smaller slice of data, and confirm API keys and quotas. See {doc}`../explanation/question-generation` and {doc}`../how-to/custom-model-endpoints`. | - -## Related Reference - -- Parquet layout and final column list: {doc}`output-files` -- Generation YAML fields: {doc}`generate-config` -- Translation YAML fields: {doc}`translation-config` diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 451e1c63b..000000000 --- a/docs/conf.py +++ /dev/null @@ -1,150 +0,0 @@ -# Copyright (c) 2025, NVIDIA CORPORATION. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -import os -import shutil -import sys -from pathlib import Path - -sys.path.insert(0, os.path.abspath("_ext")) - -project = "Nemotron" -copyright = "2026, NVIDIA Corporation" -author = "NVIDIA Corporation" - -# Version is set by CI via DOCS_VERSION env var (dev or stable) -# Defaults to "dev" for local builds -release = os.environ.get("DOCS_VERSION", "nightly") - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = [ - "myst_parser", # For our markdown docs - "sphinx.ext.viewcode", # For adding a link to view source code in docs - "sphinx.ext.napoleon", # For google style docstrings - "sphinx_copybutton", # For copy button in code blocks - "sphinx_design", # For grid cards and other design elements - "sphinxcontrib.mermaid", # For mermaid diagrams - "nemotron_customize", - "sphinx_reredirects", -] - -templates_path = ["_templates"] -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "customize"] - -# -- Options for MyST Parser (Markdown) -------------------------------------- -# MyST Parser settings -myst_enable_extensions = [ - "dollarmath", # Enables dollar math for inline math - "amsmath", # Enables LaTeX math for display mode - "colon_fence", # Enables code blocks using ::: delimiters instead of ``` - "deflist", # Supports definition lists with term: definition format - "fieldlist", # Enables field lists for metadata like :author: Name - "tasklist", # Adds support for GitHub-style task lists with [ ] and [x] - "attrs_block", # Enables setting attributes on block elements using {#id .class key=val} -] -myst_heading_anchors = 5 # Generates anchor links for headings up to level 5 - -# Configure MyST to handle mermaid code blocks -myst_fence_as_directive = ["mermaid"] - -# -- Options for Mermaid ----------------------------------------------------- -# Configure mermaid diagrams -mermaid_version = "latest" # Use the latest version of mermaid - -copybutton_prompt_text = ">>> |$ |# " -copybutton_exclude = ".linenos, .gp, .go" - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -# -- Custom static files for Termynal terminal animations ------------------- -html_static_path = ["_static"] -html_css_files = [ - "css/termynal.css", - "customize.css", -] -html_js_files = [ - "js/termynal.js", - "js/termynal-init.js", -] - -html_theme = "nvidia_sphinx_theme" -html_theme_options = { - "switcher": { - "json_url": "../versions1.json", - "version_match": release, - }, - "icon_links": [ - { - "name": "GitHub", - "url": "https://github.com/NVIDIA-NeMo/Nemotron", - "icon": "fa-brands fa-github", - } - ], - "extra_head": { - """ - - """ - }, - "extra_footer": { - """ - - """ - }, -} -html_extra_path = ["project.json", "versions1.json"] - -# Github links are now getting rate limited from the Github Actions -if os.environ.get("CI", False): - linkcheck_ignore = [ - ".*github\\.com.*", - ".*githubusercontent\\.com.*", - ] - -redirects = { - # Usage cookbook → deployment guides summary - "usage-cookbook/README": "../deployment-guides.html", - "usage-cookbook/Nemotron-Nano2-VL/README": "../../deployment-guides.html", - "usage-cookbook/Nemotron-Parse-v1.1/README": "../../deployment-guides.html", - "usage-cookbook/Nemotron-3-Nano-Omni/Megatron-bridge/README": "../../../deployment-guides.html", - "usage-cookbook/Nemotron-3-Nano-Omni/automodel/automodel_training_cookbook": "../../../deployment-guides.html", - "usage-cookbook/Nemotron-3-Nano-Omni/doc-intelligence-with-parse/README": "../../../deployment-guides.html", - "usage-cookbook/Nemotron-3-Super/README": "../../deployment-guides.html", - "usage-cookbook/Nemotron-3-Super/grpo-dapo/README": "../../../deployment-guides.html", - "usage-cookbook/Nemotron-3-Super/lora-text2sql/README": "../../../deployment-guides.html", - "usage-cookbook/Nemotron-3-Super/lora-text2sql/nemo-automodel/README": "../../../../deployment-guides.html", - "usage-cookbook/Nemotron-3-Super/lora-text2sql/nemo-megatron-bridge/README": "../../../../deployment-guides.html", - "usage-cookbook/Nemotron-3-Super/SparkDeploymentGuide/README": "../../../deployment-guides.html", - "usage-cookbook/Nemotron-3-Super/OpenScaffoldingResources/README": "../../../deployment-guides.html", - "usage-cookbook/Nemotron-3-Super/grpo-dapo/grpo_training_cookbook": "../../../deployment-guides.html", - "usage-cookbook/Nemotron-3-Ultra-Base/README": "../../deployment-guides.html", - # Use case examples → application examples summary - "use-case-examples/README": "../application-examples.html", - "use-case-examples/Simple Nemotron-3-Nano Usage Example/README": "../../application-examples.html", - "use-case-examples/Data Science ML Agent/README": "../../application-examples.html", - "use-case-examples/RAG Agent with Nemotron RAG Models/README": "../../application-examples.html", - "use-case-examples/Intelligent Document Processing with Nemotron RAG/README": "../../application-examples.html", - "use-case-examples/nemotron-voice-rag-agent-example/README": "../../application-examples.html", - "use-case-examples/sql-lora-finetuning-and-deployment/README": "../../application-examples.html", -} diff --git a/docs/curate/how-to/index.md b/docs/curate/how-to/index.md deleted file mode 100644 index 3ce06c0f3..000000000 --- a/docs/curate/how-to/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Task-focused guides for curate/nemo_curator." -topics: ["Curation", "How-To"] -tags: ["How-To", "Curation", "NeMo Curator"] -content: - type: "How-To" - difficulty: "Intermediate" - audience: ["ML Engineer", "Data Scientist"] ---- - -# Curation How-To Guides - -Use these guides after the local initial validation in {doc}`../getting-started`. - -```{toctree} -:maxdepth: 1 - -run-local-jsonl -use-huggingface-snapshot -enable-filters -``` diff --git a/docs/curate/reference/index.md b/docs/curate/reference/index.md deleted file mode 100644 index fdd990b2b..000000000 --- a/docs/curate/reference/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Reference pages for curate/nemo_curator." -topics: ["Curation", "Reference"] -tags: ["Reference", "Curation", "NeMo Curator"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Data Scientist"] ---- - -# Curation Reference - -Use these pages to look up CLI syntax, configuration fields, input/output format, and common failures. - -```{toctree} -:maxdepth: 1 - -cli-curate -curate-config -io-format -troubleshooting -``` diff --git a/docs/curate/reference/troubleshooting.md b/docs/curate/reference/troubleshooting.md deleted file mode 100644 index 2aef640a8..000000000 --- a/docs/curate/reference/troubleshooting.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Troubleshooting reference for curate/nemo_curator." -topics: ["Curation", "Reference", "Troubleshooting"] -tags: ["Troubleshooting", "Curation", "NeMo Curator"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Data Scientist"] ---- - -# Curation Troubleshooting - -| Symptom | Likely Cause | Fix | -| --- | --- | --- | -| `input_glob` matches no files | Path does not exist in the current host, container, or shared mount | Use an absolute path or verify the mount. For local tiny runs, override the packaged `/nemo_run/code/...` path with `${PWD}/src/nemotron/steps/curate/nemo_curator/data/tiny.jsonl`. | -| Missing FastText model | `language_codes` is non-empty but `models.fasttext_langid` is missing or invalid | Set `language_codes=[]` to disable language filtering, or provide the FastText `lid.176.bin` path. | -| `quality_filters` error about `min_words` and `max_words` | Only one word-count bound was set | Set both `quality_filters.min_words` and `quality_filters.max_words`, or set `quality_filters={}`. | -| Output is empty or much smaller than expected | Filters are too strict or applied before corpus shape is understood | Re-run with `language_codes=[]`, `domains=[]`, and `quality_filters={}`. Add filters back one at a time. | -| Ray worker starts a new `.venv` or cannot import dependencies | Local `uv run` and the Ray runtime environment are both attempting to manage dependency setup | Export `RAY_ENABLE_UV_RUN_RUNTIME_ENV=0` and run with `uv run --no-sync` after `uv sync --extra curate`. | -| Large local file causes memory pressure | Input shard is too large for the available Ray worker memory | Split large JSONL files into smaller shards before running Curator. | -| Domain classifier downloads repeatedly | Hugging Face cache path is not persistent | Set `models.hf_cache_dir` to a persistent cache location and mount it in remote profiles. | - -## Debug Checklist - -1. Run the local tiny command with filters disabled. -2. Confirm `uv sync --extra curate` completed in the same repository clone. -3. Confirm the input path exists where the command runs. -4. Confirm `output_dir` is writable. -5. Add language, word-count, and domain filters one at a time. diff --git a/docs/deployment-guides.md b/docs/deployment-guides.md deleted file mode 100644 index 6ae3b765d..000000000 --- a/docs/deployment-guides.md +++ /dev/null @@ -1,104 +0,0 @@ - - - -(deployment-guides)= -# Deployment Guides - -Deployment guides, fine-tuning recipes, and agentic usage examples for Nemotron models. Each card links to its directory in the [Nemotron GitHub repository](https://github.com/NVIDIA-NeMo/nemotron). - -::::{grid} 1 2 2 2 -:gutter: 3 - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Nemotron 3 Super -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/usage-cookbook/Nemotron-3-Super -:link-type: url - -Notebooks for deploying the 120B/12B-active hybrid Mamba-Transformer MoE model with vLLM, SGLang, and TensorRT-LLM. -+++ -{bdg-success}`Notebook` {bdg-secondary}`Local GPU` {bdg-muted-line}`Apr 28, 2026` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Nemotron 3 Super — LoRA Text2SQL -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/usage-cookbook/Nemotron-3-Super/lora-text2sql -:link-type: url - -Supervised fine-tuning with LoRA for Text2SQL using the BIRD SQL benchmark. Includes recipes for both NeMo AutoModel and Megatron Bridge. -+++ -{bdg-secondary}`Local GPU` {bdg-info}`Fine-tuning` {bdg-muted-line}`Apr 28, 2026` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Nemotron 3 Super on DGX Spark -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/usage-cookbook/Nemotron-3-Super/SparkDeploymentGuide -:link-type: url - -Deploy on a single DGX Spark with 128 GB unified memory using vLLM (nightly) and TensorRT-LLM, including NVFP4 quantization and MTP speculative decoding. -+++ -{bdg-secondary}`Local GPU` {bdg-muted-line}`Apr 10, 2026` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Nemotron 3 Ultra Base -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/usage-cookbook/Nemotron-3-Ultra-Base -:link-type: url - -550B total / 55B active parameter base model checkpoint announced at GTC 2026. A starting point for custom fine-tuning and RL post-training pipelines — not yet instruction-tuned. -+++ -{bdg-secondary}`Local GPU` {bdg-info}`Fine-tuning` {bdg-muted-line}`Mar 23, 2026` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Nemotron 3 Super on GRPO/DAPO RL Training -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/usage-cookbook/Nemotron-3-Super/grpo-dapo -:link-type: url - -Full-weight RL training from a base model using the GRPO/DAPO algorithm to reproduce emergent math reasoning. Requires 5× GB200 or 3× B200 nodes. -+++ -{bdg-secondary}`Local GPU` {bdg-info}`Fine-tuning` {bdg-muted-line}`Mar 11, 2026` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Nemotron 3 Super on Agentic Coding -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/usage-cookbook/Nemotron-3-Super/OpenScaffoldingResources -:link-type: url - -Use Nemotron 3 Super with OpenCode, OpenClaw, Kilo Code CLI, and OpenHands via OpenRouter and build.nvidia.com. -+++ -{bdg-success}`Beginner` {bdg-muted-line}`Mar 11, 2026` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Nemotron Nano 2 VL -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/usage-cookbook/Nemotron-Nano2-VL -:link-type: url - -Notebooks for the 12B multimodal model that unifies visual and textual understanding. Covers NIM inference via build.nvidia.com and local Hugging Face deployment. -+++ -{bdg-success}`Notebook` {bdg-secondary}`Local GPU` {bdg-muted-line}`Oct 28, 2025` -::: - -:::{grid-item-card} {octicon}`mark-github;1.5em;sd-mr-1` Nemotron Parse v1.1 -:link: https://github.com/NVIDIA-NeMo/nemotron/tree/main/usage-cookbook/Nemotron-Parse-v1.1 -:link-type: url - -Notebook for the document-parsing VLM that converts PDFs and unstructured documents into structured JSON, LaTeX, and Markdown. Available via NIM at build.nvidia.com. -+++ -{bdg-success}`Beginner` {bdg-success}`Notebook` {bdg-muted-line}`Oct 28, 2025` -::: - -:::: diff --git a/docs/assets/super3/avg_benchmark.png b/docs/fern/_images/avg_benchmark.png similarity index 100% rename from docs/assets/super3/avg_benchmark.png rename to docs/fern/_images/avg_benchmark.png diff --git a/docs/assets/expert-parallelism.png b/docs/fern/_images/expert-parallelism.png similarity index 100% rename from docs/assets/expert-parallelism.png rename to docs/fern/_images/expert-parallelism.png diff --git a/docs/build-benchmarks/_images/funnel.png b/docs/fern/_images/funnel.png similarity index 100% rename from docs/build-benchmarks/_images/funnel.png rename to docs/fern/_images/funnel.png diff --git a/docs/assets/nemo-framework-overview.png b/docs/fern/_images/nemo-framework-overview.png similarity index 100% rename from docs/assets/nemo-framework-overview.png rename to docs/fern/_images/nemo-framework-overview.png diff --git a/docs/assets/nemo-rl-actors.png b/docs/fern/_images/nemo-rl-actors.png similarity index 100% rename from docs/assets/nemo-rl-actors.png rename to docs/fern/_images/nemo-rl-actors.png diff --git a/docs/assets/omni-3.png b/docs/fern/_images/omni-3.png similarity index 100% rename from docs/assets/omni-3.png rename to docs/fern/_images/omni-3.png diff --git a/docs/assets/sequence-parallelism.png b/docs/fern/_images/sequence-parallelism.png similarity index 100% rename from docs/assets/sequence-parallelism.png rename to docs/fern/_images/sequence-parallelism.png diff --git a/docs/assets/super3/super-pattern.png b/docs/fern/_images/super-pattern.png similarity index 100% rename from docs/assets/super3/super-pattern.png rename to docs/fern/_images/super-pattern.png diff --git a/docs/assets/super3/super-phase1.png b/docs/fern/_images/super-phase1.png similarity index 100% rename from docs/assets/super3/super-phase1.png rename to docs/fern/_images/super-phase1.png diff --git a/docs/assets/super3/super-phase2.png b/docs/fern/_images/super-phase2.png similarity index 100% rename from docs/assets/super3/super-phase2.png rename to docs/fern/_images/super-phase2.png diff --git a/docs/assets/super3/super_sft_blend.png b/docs/fern/_images/super_sft_blend.png similarity index 100% rename from docs/assets/super3/super_sft_blend.png rename to docs/fern/_images/super_sft_blend.png diff --git a/docs/assets/tensor-parallelism.png b/docs/fern/_images/tensor-parallelism.png similarity index 100% rename from docs/assets/tensor-parallelism.png rename to docs/fern/_images/tensor-parallelism.png diff --git a/docs/fern/_sphinx_design_static/design-tabs.js b/docs/fern/_sphinx_design_static/design-tabs.js new file mode 100644 index 000000000..b25bd6a4f --- /dev/null +++ b/docs/fern/_sphinx_design_static/design-tabs.js @@ -0,0 +1,101 @@ +// @ts-check + +// Extra JS capability for selected tabs to be synced +// The selection is stored in local storage so that it persists across page loads. + +/** + * @type {Record} + */ +let sd_id_to_elements = {}; +const storageKeyPrefix = "sphinx-design-tab-id-"; + +/** + * Create a key for a tab element. + * @param {HTMLElement} el - The tab element. + * @returns {[string, string, string] | null} - The key. + * + */ +function create_key(el) { + let syncId = el.getAttribute("data-sync-id"); + let syncGroup = el.getAttribute("data-sync-group"); + if (!syncId || !syncGroup) return null; + return [syncGroup, syncId, syncGroup + "--" + syncId]; +} + +/** + * Initialize the tab selection. + * + */ +function ready() { + // Find all tabs with sync data + + /** @type {string[]} */ + let groups = []; + + document.querySelectorAll(".sd-tab-label").forEach((label) => { + if (label instanceof HTMLElement) { + let data = create_key(label); + if (data) { + let [group, id, key] = data; + + // add click event listener + // @ts-ignore + label.onclick = onSDLabelClick; + + // store map of key to elements + if (!sd_id_to_elements[key]) { + sd_id_to_elements[key] = []; + } + sd_id_to_elements[key].push(label); + + if (groups.indexOf(group) === -1) { + groups.push(group); + // Check if a specific tab has been selected via URL parameter + const tabParam = new URLSearchParams(window.location.search).get( + group + ); + if (tabParam) { + console.log( + "sphinx-design: Selecting tab id for group '" + + group + + "' from URL parameter: " + + tabParam + ); + window.sessionStorage.setItem(storageKeyPrefix + group, tabParam); + } + } + + // Check is a specific tab has been selected previously + let previousId = window.sessionStorage.getItem( + storageKeyPrefix + group + ); + if (previousId === id) { + // console.log( + // "sphinx-design: Selecting tab from session storage: " + id + // ); + // @ts-ignore + label.previousElementSibling.checked = true; + } + } + } + }); +} + +/** + * Activate other tabs with the same sync id. + * + * @this {HTMLElement} - The element that was clicked. + */ +function onSDLabelClick() { + let data = create_key(this); + if (!data) return; + let [group, id, key] = data; + for (const label of sd_id_to_elements[key]) { + if (label === this) continue; + // @ts-ignore + label.previousElementSibling.checked = true; + } + window.sessionStorage.setItem(storageKeyPrefix + group, id); +} + +document.addEventListener("DOMContentLoaded", ready, false); diff --git a/docs/fern/_sphinx_design_static/sphinx-design.min.css b/docs/fern/_sphinx_design_static/sphinx-design.min.css new file mode 100644 index 000000000..860c36da0 --- /dev/null +++ b/docs/fern/_sphinx_design_static/sphinx-design.min.css @@ -0,0 +1 @@ +.sd-bg-primary{background-color:var(--sd-color-primary) !important}.sd-bg-text-primary{color:var(--sd-color-primary-text) !important}button.sd-bg-primary:focus,button.sd-bg-primary:hover{background-color:var(--sd-color-primary-highlight) !important}a.sd-bg-primary:focus,a.sd-bg-primary:hover{background-color:var(--sd-color-primary-highlight) !important}.sd-bg-secondary{background-color:var(--sd-color-secondary) !important}.sd-bg-text-secondary{color:var(--sd-color-secondary-text) !important}button.sd-bg-secondary:focus,button.sd-bg-secondary:hover{background-color:var(--sd-color-secondary-highlight) !important}a.sd-bg-secondary:focus,a.sd-bg-secondary:hover{background-color:var(--sd-color-secondary-highlight) !important}.sd-bg-success{background-color:var(--sd-color-success) !important}.sd-bg-text-success{color:var(--sd-color-success-text) !important}button.sd-bg-success:focus,button.sd-bg-success:hover{background-color:var(--sd-color-success-highlight) !important}a.sd-bg-success:focus,a.sd-bg-success:hover{background-color:var(--sd-color-success-highlight) !important}.sd-bg-info{background-color:var(--sd-color-info) !important}.sd-bg-text-info{color:var(--sd-color-info-text) !important}button.sd-bg-info:focus,button.sd-bg-info:hover{background-color:var(--sd-color-info-highlight) !important}a.sd-bg-info:focus,a.sd-bg-info:hover{background-color:var(--sd-color-info-highlight) !important}.sd-bg-warning{background-color:var(--sd-color-warning) !important}.sd-bg-text-warning{color:var(--sd-color-warning-text) !important}button.sd-bg-warning:focus,button.sd-bg-warning:hover{background-color:var(--sd-color-warning-highlight) !important}a.sd-bg-warning:focus,a.sd-bg-warning:hover{background-color:var(--sd-color-warning-highlight) !important}.sd-bg-danger{background-color:var(--sd-color-danger) !important}.sd-bg-text-danger{color:var(--sd-color-danger-text) !important}button.sd-bg-danger:focus,button.sd-bg-danger:hover{background-color:var(--sd-color-danger-highlight) !important}a.sd-bg-danger:focus,a.sd-bg-danger:hover{background-color:var(--sd-color-danger-highlight) !important}.sd-bg-light{background-color:var(--sd-color-light) !important}.sd-bg-text-light{color:var(--sd-color-light-text) !important}button.sd-bg-light:focus,button.sd-bg-light:hover{background-color:var(--sd-color-light-highlight) !important}a.sd-bg-light:focus,a.sd-bg-light:hover{background-color:var(--sd-color-light-highlight) !important}.sd-bg-muted{background-color:var(--sd-color-muted) !important}.sd-bg-text-muted{color:var(--sd-color-muted-text) !important}button.sd-bg-muted:focus,button.sd-bg-muted:hover{background-color:var(--sd-color-muted-highlight) !important}a.sd-bg-muted:focus,a.sd-bg-muted:hover{background-color:var(--sd-color-muted-highlight) !important}.sd-bg-dark{background-color:var(--sd-color-dark) !important}.sd-bg-text-dark{color:var(--sd-color-dark-text) !important}button.sd-bg-dark:focus,button.sd-bg-dark:hover{background-color:var(--sd-color-dark-highlight) !important}a.sd-bg-dark:focus,a.sd-bg-dark:hover{background-color:var(--sd-color-dark-highlight) !important}.sd-bg-black{background-color:var(--sd-color-black) !important}.sd-bg-text-black{color:var(--sd-color-black-text) !important}button.sd-bg-black:focus,button.sd-bg-black:hover{background-color:var(--sd-color-black-highlight) !important}a.sd-bg-black:focus,a.sd-bg-black:hover{background-color:var(--sd-color-black-highlight) !important}.sd-bg-white{background-color:var(--sd-color-white) !important}.sd-bg-text-white{color:var(--sd-color-white-text) !important}button.sd-bg-white:focus,button.sd-bg-white:hover{background-color:var(--sd-color-white-highlight) !important}a.sd-bg-white:focus,a.sd-bg-white:hover{background-color:var(--sd-color-white-highlight) !important}.sd-text-primary,.sd-text-primary>p{color:var(--sd-color-primary) !important}a.sd-text-primary:focus,a.sd-text-primary:hover{color:var(--sd-color-primary-highlight) !important}.sd-text-secondary,.sd-text-secondary>p{color:var(--sd-color-secondary) !important}a.sd-text-secondary:focus,a.sd-text-secondary:hover{color:var(--sd-color-secondary-highlight) !important}.sd-text-success,.sd-text-success>p{color:var(--sd-color-success) !important}a.sd-text-success:focus,a.sd-text-success:hover{color:var(--sd-color-success-highlight) !important}.sd-text-info,.sd-text-info>p{color:var(--sd-color-info) !important}a.sd-text-info:focus,a.sd-text-info:hover{color:var(--sd-color-info-highlight) !important}.sd-text-warning,.sd-text-warning>p{color:var(--sd-color-warning) !important}a.sd-text-warning:focus,a.sd-text-warning:hover{color:var(--sd-color-warning-highlight) !important}.sd-text-danger,.sd-text-danger>p{color:var(--sd-color-danger) !important}a.sd-text-danger:focus,a.sd-text-danger:hover{color:var(--sd-color-danger-highlight) !important}.sd-text-light,.sd-text-light>p{color:var(--sd-color-light) !important}a.sd-text-light:focus,a.sd-text-light:hover{color:var(--sd-color-light-highlight) !important}.sd-text-muted,.sd-text-muted>p{color:var(--sd-color-muted) !important}a.sd-text-muted:focus,a.sd-text-muted:hover{color:var(--sd-color-muted-highlight) !important}.sd-text-dark,.sd-text-dark>p{color:var(--sd-color-dark) !important}a.sd-text-dark:focus,a.sd-text-dark:hover{color:var(--sd-color-dark-highlight) !important}.sd-text-black,.sd-text-black>p{color:var(--sd-color-black) !important}a.sd-text-black:focus,a.sd-text-black:hover{color:var(--sd-color-black-highlight) !important}.sd-text-white,.sd-text-white>p{color:var(--sd-color-white) !important}a.sd-text-white:focus,a.sd-text-white:hover{color:var(--sd-color-white-highlight) !important}.sd-outline-primary{border-color:var(--sd-color-primary) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-primary:focus,a.sd-outline-primary:hover{border-color:var(--sd-color-primary-highlight) !important}.sd-outline-secondary{border-color:var(--sd-color-secondary) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-secondary:focus,a.sd-outline-secondary:hover{border-color:var(--sd-color-secondary-highlight) !important}.sd-outline-success{border-color:var(--sd-color-success) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-success:focus,a.sd-outline-success:hover{border-color:var(--sd-color-success-highlight) !important}.sd-outline-info{border-color:var(--sd-color-info) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-info:focus,a.sd-outline-info:hover{border-color:var(--sd-color-info-highlight) !important}.sd-outline-warning{border-color:var(--sd-color-warning) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-warning:focus,a.sd-outline-warning:hover{border-color:var(--sd-color-warning-highlight) !important}.sd-outline-danger{border-color:var(--sd-color-danger) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-danger:focus,a.sd-outline-danger:hover{border-color:var(--sd-color-danger-highlight) !important}.sd-outline-light{border-color:var(--sd-color-light) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-light:focus,a.sd-outline-light:hover{border-color:var(--sd-color-light-highlight) !important}.sd-outline-muted{border-color:var(--sd-color-muted) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-muted:focus,a.sd-outline-muted:hover{border-color:var(--sd-color-muted-highlight) !important}.sd-outline-dark{border-color:var(--sd-color-dark) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-dark:focus,a.sd-outline-dark:hover{border-color:var(--sd-color-dark-highlight) !important}.sd-outline-black{border-color:var(--sd-color-black) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-black:focus,a.sd-outline-black:hover{border-color:var(--sd-color-black-highlight) !important}.sd-outline-white{border-color:var(--sd-color-white) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-white:focus,a.sd-outline-white:hover{border-color:var(--sd-color-white-highlight) !important}.sd-bg-transparent{background-color:transparent !important}.sd-outline-transparent{border-color:transparent !important}.sd-text-transparent{color:transparent !important}.sd-p-0{padding:0 !important}.sd-pt-0,.sd-py-0{padding-top:0 !important}.sd-pr-0,.sd-px-0{padding-right:0 !important}.sd-pb-0,.sd-py-0{padding-bottom:0 !important}.sd-pl-0,.sd-px-0{padding-left:0 !important}.sd-p-1{padding:.25rem !important}.sd-pt-1,.sd-py-1{padding-top:.25rem !important}.sd-pr-1,.sd-px-1{padding-right:.25rem !important}.sd-pb-1,.sd-py-1{padding-bottom:.25rem !important}.sd-pl-1,.sd-px-1{padding-left:.25rem !important}.sd-p-2{padding:.5rem !important}.sd-pt-2,.sd-py-2{padding-top:.5rem !important}.sd-pr-2,.sd-px-2{padding-right:.5rem !important}.sd-pb-2,.sd-py-2{padding-bottom:.5rem !important}.sd-pl-2,.sd-px-2{padding-left:.5rem !important}.sd-p-3{padding:1rem !important}.sd-pt-3,.sd-py-3{padding-top:1rem !important}.sd-pr-3,.sd-px-3{padding-right:1rem !important}.sd-pb-3,.sd-py-3{padding-bottom:1rem !important}.sd-pl-3,.sd-px-3{padding-left:1rem !important}.sd-p-4{padding:1.5rem !important}.sd-pt-4,.sd-py-4{padding-top:1.5rem !important}.sd-pr-4,.sd-px-4{padding-right:1.5rem !important}.sd-pb-4,.sd-py-4{padding-bottom:1.5rem !important}.sd-pl-4,.sd-px-4{padding-left:1.5rem !important}.sd-p-5{padding:3rem !important}.sd-pt-5,.sd-py-5{padding-top:3rem !important}.sd-pr-5,.sd-px-5{padding-right:3rem !important}.sd-pb-5,.sd-py-5{padding-bottom:3rem !important}.sd-pl-5,.sd-px-5{padding-left:3rem !important}.sd-m-auto{margin:auto !important}.sd-mt-auto,.sd-my-auto{margin-top:auto !important}.sd-mr-auto,.sd-mx-auto{margin-right:auto !important}.sd-mb-auto,.sd-my-auto{margin-bottom:auto !important}.sd-ml-auto,.sd-mx-auto{margin-left:auto !important}.sd-m-0{margin:0 !important}.sd-mt-0,.sd-my-0{margin-top:0 !important}.sd-mr-0,.sd-mx-0{margin-right:0 !important}.sd-mb-0,.sd-my-0{margin-bottom:0 !important}.sd-ml-0,.sd-mx-0{margin-left:0 !important}.sd-m-1{margin:.25rem !important}.sd-mt-1,.sd-my-1{margin-top:.25rem !important}.sd-mr-1,.sd-mx-1{margin-right:.25rem !important}.sd-mb-1,.sd-my-1{margin-bottom:.25rem !important}.sd-ml-1,.sd-mx-1{margin-left:.25rem !important}.sd-m-2{margin:.5rem !important}.sd-mt-2,.sd-my-2{margin-top:.5rem !important}.sd-mr-2,.sd-mx-2{margin-right:.5rem !important}.sd-mb-2,.sd-my-2{margin-bottom:.5rem !important}.sd-ml-2,.sd-mx-2{margin-left:.5rem !important}.sd-m-3{margin:1rem !important}.sd-mt-3,.sd-my-3{margin-top:1rem !important}.sd-mr-3,.sd-mx-3{margin-right:1rem !important}.sd-mb-3,.sd-my-3{margin-bottom:1rem !important}.sd-ml-3,.sd-mx-3{margin-left:1rem !important}.sd-m-4{margin:1.5rem !important}.sd-mt-4,.sd-my-4{margin-top:1.5rem !important}.sd-mr-4,.sd-mx-4{margin-right:1.5rem !important}.sd-mb-4,.sd-my-4{margin-bottom:1.5rem !important}.sd-ml-4,.sd-mx-4{margin-left:1.5rem !important}.sd-m-5{margin:3rem !important}.sd-mt-5,.sd-my-5{margin-top:3rem !important}.sd-mr-5,.sd-mx-5{margin-right:3rem !important}.sd-mb-5,.sd-my-5{margin-bottom:3rem !important}.sd-ml-5,.sd-mx-5{margin-left:3rem !important}.sd-w-25{width:25% !important}.sd-w-50{width:50% !important}.sd-w-75{width:75% !important}.sd-w-100{width:100% !important}.sd-w-auto{width:auto !important}.sd-h-25{height:25% !important}.sd-h-50{height:50% !important}.sd-h-75{height:75% !important}.sd-h-100{height:100% !important}.sd-h-auto{height:auto !important}.sd-d-none{display:none !important}.sd-d-inline{display:inline !important}.sd-d-inline-block{display:inline-block !important}.sd-d-block{display:block !important}.sd-d-grid{display:grid !important}.sd-d-flex-row{display:-ms-flexbox !important;display:flex !important;flex-direction:row !important}.sd-d-flex-column{display:-ms-flexbox !important;display:flex !important;flex-direction:column !important}.sd-d-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}@media(min-width: 576px){.sd-d-sm-none{display:none !important}.sd-d-sm-inline{display:inline !important}.sd-d-sm-inline-block{display:inline-block !important}.sd-d-sm-block{display:block !important}.sd-d-sm-grid{display:grid !important}.sd-d-sm-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-sm-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}@media(min-width: 768px){.sd-d-md-none{display:none !important}.sd-d-md-inline{display:inline !important}.sd-d-md-inline-block{display:inline-block !important}.sd-d-md-block{display:block !important}.sd-d-md-grid{display:grid !important}.sd-d-md-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-md-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}@media(min-width: 992px){.sd-d-lg-none{display:none !important}.sd-d-lg-inline{display:inline !important}.sd-d-lg-inline-block{display:inline-block !important}.sd-d-lg-block{display:block !important}.sd-d-lg-grid{display:grid !important}.sd-d-lg-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-lg-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}@media(min-width: 1200px){.sd-d-xl-none{display:none !important}.sd-d-xl-inline{display:inline !important}.sd-d-xl-inline-block{display:inline-block !important}.sd-d-xl-block{display:block !important}.sd-d-xl-grid{display:grid !important}.sd-d-xl-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-xl-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}.sd-align-major-start{justify-content:flex-start !important}.sd-align-major-end{justify-content:flex-end !important}.sd-align-major-center{justify-content:center !important}.sd-align-major-justify{justify-content:space-between !important}.sd-align-major-spaced{justify-content:space-evenly !important}.sd-align-minor-start{align-items:flex-start !important}.sd-align-minor-end{align-items:flex-end !important}.sd-align-minor-center{align-items:center !important}.sd-align-minor-stretch{align-items:stretch !important}.sd-text-justify{text-align:justify !important}.sd-text-left{text-align:left !important}.sd-text-right{text-align:right !important}.sd-text-center{text-align:center !important}.sd-font-weight-light{font-weight:300 !important}.sd-font-weight-lighter{font-weight:lighter !important}.sd-font-weight-normal{font-weight:400 !important}.sd-font-weight-bold{font-weight:700 !important}.sd-font-weight-bolder{font-weight:bolder !important}.sd-font-italic{font-style:italic !important}.sd-text-decoration-none{text-decoration:none !important}.sd-text-lowercase{text-transform:lowercase !important}.sd-text-uppercase{text-transform:uppercase !important}.sd-text-capitalize{text-transform:capitalize !important}.sd-text-wrap{white-space:normal !important}.sd-text-nowrap{white-space:nowrap !important}.sd-text-truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.sd-fs-1,.sd-fs-1>p{font-size:calc(1.375rem + 1.5vw) !important;line-height:unset !important}.sd-fs-2,.sd-fs-2>p{font-size:calc(1.325rem + 0.9vw) !important;line-height:unset !important}.sd-fs-3,.sd-fs-3>p{font-size:calc(1.3rem + 0.6vw) !important;line-height:unset !important}.sd-fs-4,.sd-fs-4>p{font-size:calc(1.275rem + 0.3vw) !important;line-height:unset !important}.sd-fs-5,.sd-fs-5>p{font-size:1.25rem !important;line-height:unset !important}.sd-fs-6,.sd-fs-6>p{font-size:1rem !important;line-height:unset !important}.sd-border-0{border:0 solid !important}.sd-border-top-0{border-top:0 solid !important}.sd-border-bottom-0{border-bottom:0 solid !important}.sd-border-right-0{border-right:0 solid !important}.sd-border-left-0{border-left:0 solid !important}.sd-border-1{border:1px solid !important}.sd-border-top-1{border-top:1px solid !important}.sd-border-bottom-1{border-bottom:1px solid !important}.sd-border-right-1{border-right:1px solid !important}.sd-border-left-1{border-left:1px solid !important}.sd-border-2{border:2px solid !important}.sd-border-top-2{border-top:2px solid !important}.sd-border-bottom-2{border-bottom:2px solid !important}.sd-border-right-2{border-right:2px solid !important}.sd-border-left-2{border-left:2px solid !important}.sd-border-3{border:3px solid !important}.sd-border-top-3{border-top:3px solid !important}.sd-border-bottom-3{border-bottom:3px solid !important}.sd-border-right-3{border-right:3px solid !important}.sd-border-left-3{border-left:3px solid !important}.sd-border-4{border:4px solid !important}.sd-border-top-4{border-top:4px solid !important}.sd-border-bottom-4{border-bottom:4px solid !important}.sd-border-right-4{border-right:4px solid !important}.sd-border-left-4{border-left:4px solid !important}.sd-border-5{border:5px solid !important}.sd-border-top-5{border-top:5px solid !important}.sd-border-bottom-5{border-bottom:5px solid !important}.sd-border-right-5{border-right:5px solid !important}.sd-border-left-5{border-left:5px solid !important}.sd-rounded-0{border-radius:0 !important}.sd-rounded-1{border-radius:.2rem !important}.sd-rounded-2{border-radius:.3rem !important}.sd-rounded-3{border-radius:.5rem !important}.sd-rounded-pill{border-radius:50rem !important}.sd-rounded-circle{border-radius:50% !important}.shadow-none{box-shadow:none !important}.sd-shadow-sm{box-shadow:0 .125rem .25rem var(--sd-color-shadow) !important}.sd-shadow-md{box-shadow:0 .5rem 1rem var(--sd-color-shadow) !important}.sd-shadow-lg{box-shadow:0 1rem 3rem var(--sd-color-shadow) !important}@keyframes sd-slide-from-left{0%{transform:translateX(-100%)}100%{transform:translateX(0)}}@keyframes sd-slide-from-right{0%{transform:translateX(200%)}100%{transform:translateX(0)}}@keyframes sd-grow100{0%{transform:scale(0);opacity:.5}100%{transform:scale(1);opacity:1}}@keyframes sd-grow50{0%{transform:scale(0.5);opacity:.5}100%{transform:scale(1);opacity:1}}@keyframes sd-grow50-rot20{0%{transform:scale(0.5) rotateZ(-20deg);opacity:.5}75%{transform:scale(1) rotateZ(5deg);opacity:1}95%{transform:scale(1) rotateZ(-1deg);opacity:1}100%{transform:scale(1) rotateZ(0);opacity:1}}.sd-animate-slide-from-left{animation:1s ease-out 0s 1 normal none running sd-slide-from-left}.sd-animate-slide-from-right{animation:1s ease-out 0s 1 normal none running sd-slide-from-right}.sd-animate-grow100{animation:1s ease-out 0s 1 normal none running sd-grow100}.sd-animate-grow50{animation:1s ease-out 0s 1 normal none running sd-grow50}.sd-animate-grow50-rot20{animation:1s ease-out 0s 1 normal none running sd-grow50-rot20}.sd-badge{display:inline-block;padding:.35em .65em;font-size:.75em;font-weight:700;line-height:1;text-align:center;white-space:nowrap;vertical-align:baseline;border-radius:.25rem}.sd-badge:empty{display:none}a.sd-badge{text-decoration:none}.sd-btn .sd-badge{position:relative;top:-1px}.sd-btn{background-color:transparent;border:1px solid transparent;border-radius:.25rem;cursor:pointer;display:inline-block;font-weight:400;font-size:1rem;line-height:1.5;padding:.375rem .75rem;text-align:center;text-decoration:none;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out;vertical-align:middle;user-select:none;-moz-user-select:none;-ms-user-select:none;-webkit-user-select:none}.sd-btn:hover{text-decoration:none}@media(prefers-reduced-motion: reduce){.sd-btn{transition:none}}.sd-btn-primary,.sd-btn-outline-primary:hover,.sd-btn-outline-primary:focus{color:var(--sd-color-primary-text) !important;background-color:var(--sd-color-primary) !important;border-color:var(--sd-color-primary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-primary:hover,.sd-btn-primary:focus{color:var(--sd-color-primary-text) !important;background-color:var(--sd-color-primary-highlight) !important;border-color:var(--sd-color-primary-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-primary{color:var(--sd-color-primary) !important;border-color:var(--sd-color-primary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-secondary,.sd-btn-outline-secondary:hover,.sd-btn-outline-secondary:focus{color:var(--sd-color-secondary-text) !important;background-color:var(--sd-color-secondary) !important;border-color:var(--sd-color-secondary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-secondary:hover,.sd-btn-secondary:focus{color:var(--sd-color-secondary-text) !important;background-color:var(--sd-color-secondary-highlight) !important;border-color:var(--sd-color-secondary-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-secondary{color:var(--sd-color-secondary) !important;border-color:var(--sd-color-secondary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-success,.sd-btn-outline-success:hover,.sd-btn-outline-success:focus{color:var(--sd-color-success-text) !important;background-color:var(--sd-color-success) !important;border-color:var(--sd-color-success) !important;border-width:1px !important;border-style:solid !important}.sd-btn-success:hover,.sd-btn-success:focus{color:var(--sd-color-success-text) !important;background-color:var(--sd-color-success-highlight) !important;border-color:var(--sd-color-success-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-success{color:var(--sd-color-success) !important;border-color:var(--sd-color-success) !important;border-width:1px !important;border-style:solid !important}.sd-btn-info,.sd-btn-outline-info:hover,.sd-btn-outline-info:focus{color:var(--sd-color-info-text) !important;background-color:var(--sd-color-info) !important;border-color:var(--sd-color-info) !important;border-width:1px !important;border-style:solid !important}.sd-btn-info:hover,.sd-btn-info:focus{color:var(--sd-color-info-text) !important;background-color:var(--sd-color-info-highlight) !important;border-color:var(--sd-color-info-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-info{color:var(--sd-color-info) !important;border-color:var(--sd-color-info) !important;border-width:1px !important;border-style:solid !important}.sd-btn-warning,.sd-btn-outline-warning:hover,.sd-btn-outline-warning:focus{color:var(--sd-color-warning-text) !important;background-color:var(--sd-color-warning) !important;border-color:var(--sd-color-warning) !important;border-width:1px !important;border-style:solid !important}.sd-btn-warning:hover,.sd-btn-warning:focus{color:var(--sd-color-warning-text) !important;background-color:var(--sd-color-warning-highlight) !important;border-color:var(--sd-color-warning-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-warning{color:var(--sd-color-warning) !important;border-color:var(--sd-color-warning) !important;border-width:1px !important;border-style:solid !important}.sd-btn-danger,.sd-btn-outline-danger:hover,.sd-btn-outline-danger:focus{color:var(--sd-color-danger-text) !important;background-color:var(--sd-color-danger) !important;border-color:var(--sd-color-danger) !important;border-width:1px !important;border-style:solid !important}.sd-btn-danger:hover,.sd-btn-danger:focus{color:var(--sd-color-danger-text) !important;background-color:var(--sd-color-danger-highlight) !important;border-color:var(--sd-color-danger-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-danger{color:var(--sd-color-danger) !important;border-color:var(--sd-color-danger) !important;border-width:1px !important;border-style:solid !important}.sd-btn-light,.sd-btn-outline-light:hover,.sd-btn-outline-light:focus{color:var(--sd-color-light-text) !important;background-color:var(--sd-color-light) !important;border-color:var(--sd-color-light) !important;border-width:1px !important;border-style:solid !important}.sd-btn-light:hover,.sd-btn-light:focus{color:var(--sd-color-light-text) !important;background-color:var(--sd-color-light-highlight) !important;border-color:var(--sd-color-light-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-light{color:var(--sd-color-light) !important;border-color:var(--sd-color-light) !important;border-width:1px !important;border-style:solid !important}.sd-btn-muted,.sd-btn-outline-muted:hover,.sd-btn-outline-muted:focus{color:var(--sd-color-muted-text) !important;background-color:var(--sd-color-muted) !important;border-color:var(--sd-color-muted) !important;border-width:1px !important;border-style:solid !important}.sd-btn-muted:hover,.sd-btn-muted:focus{color:var(--sd-color-muted-text) !important;background-color:var(--sd-color-muted-highlight) !important;border-color:var(--sd-color-muted-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-muted{color:var(--sd-color-muted) !important;border-color:var(--sd-color-muted) !important;border-width:1px !important;border-style:solid !important}.sd-btn-dark,.sd-btn-outline-dark:hover,.sd-btn-outline-dark:focus{color:var(--sd-color-dark-text) !important;background-color:var(--sd-color-dark) !important;border-color:var(--sd-color-dark) !important;border-width:1px !important;border-style:solid !important}.sd-btn-dark:hover,.sd-btn-dark:focus{color:var(--sd-color-dark-text) !important;background-color:var(--sd-color-dark-highlight) !important;border-color:var(--sd-color-dark-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-dark{color:var(--sd-color-dark) !important;border-color:var(--sd-color-dark) !important;border-width:1px !important;border-style:solid !important}.sd-btn-black,.sd-btn-outline-black:hover,.sd-btn-outline-black:focus{color:var(--sd-color-black-text) !important;background-color:var(--sd-color-black) !important;border-color:var(--sd-color-black) !important;border-width:1px !important;border-style:solid !important}.sd-btn-black:hover,.sd-btn-black:focus{color:var(--sd-color-black-text) !important;background-color:var(--sd-color-black-highlight) !important;border-color:var(--sd-color-black-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-black{color:var(--sd-color-black) !important;border-color:var(--sd-color-black) !important;border-width:1px !important;border-style:solid !important}.sd-btn-white,.sd-btn-outline-white:hover,.sd-btn-outline-white:focus{color:var(--sd-color-white-text) !important;background-color:var(--sd-color-white) !important;border-color:var(--sd-color-white) !important;border-width:1px !important;border-style:solid !important}.sd-btn-white:hover,.sd-btn-white:focus{color:var(--sd-color-white-text) !important;background-color:var(--sd-color-white-highlight) !important;border-color:var(--sd-color-white-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-white{color:var(--sd-color-white) !important;border-color:var(--sd-color-white) !important;border-width:1px !important;border-style:solid !important}.sd-stretched-link::after{position:absolute;top:0;right:0;bottom:0;left:0;z-index:1;content:""}.sd-hide-link-text{font-size:0}.sd-octicon,.sd-material-icon{display:inline-block;fill:currentColor;vertical-align:middle}.sd-avatar-xs{border-radius:50%;object-fit:cover;object-position:center;width:1rem;height:1rem}.sd-avatar-sm{border-radius:50%;object-fit:cover;object-position:center;width:3rem;height:3rem}.sd-avatar-md{border-radius:50%;object-fit:cover;object-position:center;width:5rem;height:5rem}.sd-avatar-lg{border-radius:50%;object-fit:cover;object-position:center;width:7rem;height:7rem}.sd-avatar-xl{border-radius:50%;object-fit:cover;object-position:center;width:10rem;height:10rem}.sd-avatar-inherit{border-radius:50%;object-fit:cover;object-position:center;width:inherit;height:inherit}.sd-avatar-initial{border-radius:50%;object-fit:cover;object-position:center;width:initial;height:initial}.sd-card{background-clip:border-box;background-color:var(--sd-color-card-background);border:1px solid var(--sd-color-card-border);border-radius:.25rem;color:var(--sd-color-card-text);display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;min-width:0;position:relative;word-wrap:break-word}.sd-card>hr{margin-left:0;margin-right:0}.sd-card-hover:hover{border-color:var(--sd-color-card-border-hover);transform:scale(1.01)}.sd-card-body{-ms-flex:1 1 auto;flex:1 1 auto;padding:1rem 1rem}.sd-card-title{margin-bottom:.5rem}.sd-card-subtitle{margin-top:-0.25rem;margin-bottom:0}.sd-card-text:last-child{margin-bottom:0}.sd-card-link:hover{text-decoration:none}.sd-card-link+.card-link{margin-left:1rem}.sd-card-header{padding:.5rem 1rem;margin-bottom:0;background-color:var(--sd-color-card-header);border-bottom:1px solid var(--sd-color-card-border)}.sd-card-header:first-child{border-radius:calc(0.25rem - 1px) calc(0.25rem - 1px) 0 0}.sd-card-footer{padding:.5rem 1rem;background-color:var(--sd-color-card-footer);border-top:1px solid var(--sd-color-card-border)}.sd-card-footer:last-child{border-radius:0 0 calc(0.25rem - 1px) calc(0.25rem - 1px)}.sd-card-header-tabs{margin-right:-0.5rem;margin-bottom:-0.5rem;margin-left:-0.5rem;border-bottom:0}.sd-card-header-pills{margin-right:-0.5rem;margin-left:-0.5rem}.sd-card-img-overlay{position:absolute;top:0;right:0;bottom:0;left:0;padding:1rem;border-radius:calc(0.25rem - 1px)}.sd-card-img,.sd-card-img-bottom,.sd-card-img-top{width:100%}.sd-card-img,.sd-card-img-top{border-top-left-radius:calc(0.25rem - 1px);border-top-right-radius:calc(0.25rem - 1px)}.sd-card-img,.sd-card-img-bottom{border-bottom-left-radius:calc(0.25rem - 1px);border-bottom-right-radius:calc(0.25rem - 1px)}.sd-cards-carousel{width:100%;display:flex;flex-wrap:nowrap;-ms-flex-direction:row;flex-direction:row;overflow-x:hidden;scroll-snap-type:x mandatory}.sd-cards-carousel.sd-show-scrollbar{overflow-x:auto}.sd-cards-carousel:hover,.sd-cards-carousel:focus{overflow-x:auto}.sd-cards-carousel>.sd-card{flex-shrink:0;scroll-snap-align:start}.sd-cards-carousel>.sd-card:not(:last-child){margin-right:3px}.sd-card-cols-1>.sd-card{width:90%}.sd-card-cols-2>.sd-card{width:45%}.sd-card-cols-3>.sd-card{width:30%}.sd-card-cols-4>.sd-card{width:22.5%}.sd-card-cols-5>.sd-card{width:18%}.sd-card-cols-6>.sd-card{width:15%}.sd-card-cols-7>.sd-card{width:12.8571428571%}.sd-card-cols-8>.sd-card{width:11.25%}.sd-card-cols-9>.sd-card{width:10%}.sd-card-cols-10>.sd-card{width:9%}.sd-card-cols-11>.sd-card{width:8.1818181818%}.sd-card-cols-12>.sd-card{width:7.5%}.sd-container,.sd-container-fluid,.sd-container-lg,.sd-container-md,.sd-container-sm,.sd-container-xl{margin-left:auto;margin-right:auto;padding-left:var(--sd-gutter-x, 0.75rem);padding-right:var(--sd-gutter-x, 0.75rem);width:100%}@media(min-width: 576px){.sd-container-sm,.sd-container{max-width:540px}}@media(min-width: 768px){.sd-container-md,.sd-container-sm,.sd-container{max-width:720px}}@media(min-width: 992px){.sd-container-lg,.sd-container-md,.sd-container-sm,.sd-container{max-width:960px}}@media(min-width: 1200px){.sd-container-xl,.sd-container-lg,.sd-container-md,.sd-container-sm,.sd-container{max-width:1140px}}.sd-row{--sd-gutter-x: 1.5rem;--sd-gutter-y: 0;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;margin-top:calc(var(--sd-gutter-y) * -1);margin-right:calc(var(--sd-gutter-x) * -0.5);margin-left:calc(var(--sd-gutter-x) * -0.5)}.sd-row>*{box-sizing:border-box;flex-shrink:0;width:100%;max-width:100%;padding-right:calc(var(--sd-gutter-x) * 0.5);padding-left:calc(var(--sd-gutter-x) * 0.5);margin-top:var(--sd-gutter-y)}.sd-col{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-auto>*{flex:0 0 auto;width:auto}.sd-row-cols-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}@media(min-width: 576px){.sd-col-sm{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-sm-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-sm-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-sm-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-sm-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-sm-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-sm-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-sm-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-sm-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-sm-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-sm-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-sm-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-sm-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-sm-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}@media(min-width: 768px){.sd-col-md{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-md-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-md-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-md-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-md-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-md-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-md-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-md-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-md-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-md-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-md-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-md-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-md-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-md-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}@media(min-width: 992px){.sd-col-lg{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-lg-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-lg-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-lg-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-lg-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-lg-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-lg-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-lg-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-lg-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-lg-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-lg-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-lg-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-lg-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-lg-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}@media(min-width: 1200px){.sd-col-xl{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-xl-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-xl-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-xl-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-xl-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-xl-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-xl-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-xl-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-xl-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-xl-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-xl-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-xl-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-xl-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-xl-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}.sd-col-auto{flex:0 0 auto;-ms-flex:0 0 auto;width:auto}.sd-col-1{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}.sd-col-2{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-col-3{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-col-4{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-col-5{flex:0 0 auto;-ms-flex:0 0 auto;width:41.6666666667%}.sd-col-6{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-col-7{flex:0 0 auto;-ms-flex:0 0 auto;width:58.3333333333%}.sd-col-8{flex:0 0 auto;-ms-flex:0 0 auto;width:66.6666666667%}.sd-col-9{flex:0 0 auto;-ms-flex:0 0 auto;width:75%}.sd-col-10{flex:0 0 auto;-ms-flex:0 0 auto;width:83.3333333333%}.sd-col-11{flex:0 0 auto;-ms-flex:0 0 auto;width:91.6666666667%}.sd-col-12{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-g-0,.sd-gy-0{--sd-gutter-y: 0}.sd-g-0,.sd-gx-0{--sd-gutter-x: 0}.sd-g-1,.sd-gy-1{--sd-gutter-y: 0.25rem}.sd-g-1,.sd-gx-1{--sd-gutter-x: 0.25rem}.sd-g-2,.sd-gy-2{--sd-gutter-y: 0.5rem}.sd-g-2,.sd-gx-2{--sd-gutter-x: 0.5rem}.sd-g-3,.sd-gy-3{--sd-gutter-y: 1rem}.sd-g-3,.sd-gx-3{--sd-gutter-x: 1rem}.sd-g-4,.sd-gy-4{--sd-gutter-y: 1.5rem}.sd-g-4,.sd-gx-4{--sd-gutter-x: 1.5rem}.sd-g-5,.sd-gy-5{--sd-gutter-y: 3rem}.sd-g-5,.sd-gx-5{--sd-gutter-x: 3rem}@media(min-width: 576px){.sd-col-sm-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-sm-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-sm-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-sm-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-sm-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-sm-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-sm-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-sm-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-sm-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-sm-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-sm-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-sm-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-sm-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-sm-0,.sd-gy-sm-0{--sd-gutter-y: 0}.sd-g-sm-0,.sd-gx-sm-0{--sd-gutter-x: 0}.sd-g-sm-1,.sd-gy-sm-1{--sd-gutter-y: 0.25rem}.sd-g-sm-1,.sd-gx-sm-1{--sd-gutter-x: 0.25rem}.sd-g-sm-2,.sd-gy-sm-2{--sd-gutter-y: 0.5rem}.sd-g-sm-2,.sd-gx-sm-2{--sd-gutter-x: 0.5rem}.sd-g-sm-3,.sd-gy-sm-3{--sd-gutter-y: 1rem}.sd-g-sm-3,.sd-gx-sm-3{--sd-gutter-x: 1rem}.sd-g-sm-4,.sd-gy-sm-4{--sd-gutter-y: 1.5rem}.sd-g-sm-4,.sd-gx-sm-4{--sd-gutter-x: 1.5rem}.sd-g-sm-5,.sd-gy-sm-5{--sd-gutter-y: 3rem}.sd-g-sm-5,.sd-gx-sm-5{--sd-gutter-x: 3rem}}@media(min-width: 768px){.sd-col-md-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-md-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-md-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-md-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-md-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-md-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-md-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-md-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-md-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-md-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-md-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-md-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-md-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-md-0,.sd-gy-md-0{--sd-gutter-y: 0}.sd-g-md-0,.sd-gx-md-0{--sd-gutter-x: 0}.sd-g-md-1,.sd-gy-md-1{--sd-gutter-y: 0.25rem}.sd-g-md-1,.sd-gx-md-1{--sd-gutter-x: 0.25rem}.sd-g-md-2,.sd-gy-md-2{--sd-gutter-y: 0.5rem}.sd-g-md-2,.sd-gx-md-2{--sd-gutter-x: 0.5rem}.sd-g-md-3,.sd-gy-md-3{--sd-gutter-y: 1rem}.sd-g-md-3,.sd-gx-md-3{--sd-gutter-x: 1rem}.sd-g-md-4,.sd-gy-md-4{--sd-gutter-y: 1.5rem}.sd-g-md-4,.sd-gx-md-4{--sd-gutter-x: 1.5rem}.sd-g-md-5,.sd-gy-md-5{--sd-gutter-y: 3rem}.sd-g-md-5,.sd-gx-md-5{--sd-gutter-x: 3rem}}@media(min-width: 992px){.sd-col-lg-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-lg-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-lg-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-lg-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-lg-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-lg-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-lg-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-lg-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-lg-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-lg-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-lg-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-lg-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-lg-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-lg-0,.sd-gy-lg-0{--sd-gutter-y: 0}.sd-g-lg-0,.sd-gx-lg-0{--sd-gutter-x: 0}.sd-g-lg-1,.sd-gy-lg-1{--sd-gutter-y: 0.25rem}.sd-g-lg-1,.sd-gx-lg-1{--sd-gutter-x: 0.25rem}.sd-g-lg-2,.sd-gy-lg-2{--sd-gutter-y: 0.5rem}.sd-g-lg-2,.sd-gx-lg-2{--sd-gutter-x: 0.5rem}.sd-g-lg-3,.sd-gy-lg-3{--sd-gutter-y: 1rem}.sd-g-lg-3,.sd-gx-lg-3{--sd-gutter-x: 1rem}.sd-g-lg-4,.sd-gy-lg-4{--sd-gutter-y: 1.5rem}.sd-g-lg-4,.sd-gx-lg-4{--sd-gutter-x: 1.5rem}.sd-g-lg-5,.sd-gy-lg-5{--sd-gutter-y: 3rem}.sd-g-lg-5,.sd-gx-lg-5{--sd-gutter-x: 3rem}}@media(min-width: 1200px){.sd-col-xl-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-xl-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-xl-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-xl-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-xl-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-xl-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-xl-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-xl-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-xl-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-xl-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-xl-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-xl-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-xl-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-xl-0,.sd-gy-xl-0{--sd-gutter-y: 0}.sd-g-xl-0,.sd-gx-xl-0{--sd-gutter-x: 0}.sd-g-xl-1,.sd-gy-xl-1{--sd-gutter-y: 0.25rem}.sd-g-xl-1,.sd-gx-xl-1{--sd-gutter-x: 0.25rem}.sd-g-xl-2,.sd-gy-xl-2{--sd-gutter-y: 0.5rem}.sd-g-xl-2,.sd-gx-xl-2{--sd-gutter-x: 0.5rem}.sd-g-xl-3,.sd-gy-xl-3{--sd-gutter-y: 1rem}.sd-g-xl-3,.sd-gx-xl-3{--sd-gutter-x: 1rem}.sd-g-xl-4,.sd-gy-xl-4{--sd-gutter-y: 1.5rem}.sd-g-xl-4,.sd-gx-xl-4{--sd-gutter-x: 1.5rem}.sd-g-xl-5,.sd-gy-xl-5{--sd-gutter-y: 3rem}.sd-g-xl-5,.sd-gx-xl-5{--sd-gutter-x: 3rem}}.sd-flex-row-reverse{flex-direction:row-reverse !important}details.sd-dropdown{position:relative;font-size:var(--sd-fontsize-dropdown)}details.sd-dropdown:hover{cursor:pointer}details.sd-dropdown .sd-summary-content{cursor:default}details.sd-dropdown summary.sd-summary-title{padding:.5em .6em .5em 1em;font-size:var(--sd-fontsize-dropdown-title);font-weight:var(--sd-fontweight-dropdown-title);user-select:none;-moz-user-select:none;-ms-user-select:none;-webkit-user-select:none;list-style:none;display:inline-flex;justify-content:space-between}details.sd-dropdown summary.sd-summary-title::-webkit-details-marker{display:none}details.sd-dropdown summary.sd-summary-title:focus{outline:none}details.sd-dropdown summary.sd-summary-title .sd-summary-icon{margin-right:.6em;display:inline-flex;align-items:center}details.sd-dropdown summary.sd-summary-title .sd-summary-icon svg{opacity:.8}details.sd-dropdown summary.sd-summary-title .sd-summary-text{flex-grow:1;line-height:1.5;padding-right:.5rem}details.sd-dropdown summary.sd-summary-title .sd-summary-state-marker{pointer-events:none;display:inline-flex;align-items:center}details.sd-dropdown summary.sd-summary-title .sd-summary-state-marker svg{opacity:.6}details.sd-dropdown summary.sd-summary-title:hover .sd-summary-state-marker svg{opacity:1;transform:scale(1.1)}details.sd-dropdown[open] summary .sd-octicon.no-title{visibility:hidden}details.sd-dropdown .sd-summary-chevron-right{transition:.25s}details.sd-dropdown[open]>.sd-summary-title .sd-summary-chevron-right{transform:rotate(90deg)}details.sd-dropdown[open]>.sd-summary-title .sd-summary-chevron-down{transform:rotate(180deg)}details.sd-dropdown:not([open]).sd-card{border:none}details.sd-dropdown:not([open])>.sd-card-header{border:1px solid var(--sd-color-card-border);border-radius:.25rem}details.sd-dropdown.sd-fade-in[open] summary~*{-moz-animation:sd-fade-in .5s ease-in-out;-webkit-animation:sd-fade-in .5s ease-in-out;animation:sd-fade-in .5s ease-in-out}details.sd-dropdown.sd-fade-in-slide-down[open] summary~*{-moz-animation:sd-fade-in .5s ease-in-out,sd-slide-down .5s ease-in-out;-webkit-animation:sd-fade-in .5s ease-in-out,sd-slide-down .5s ease-in-out;animation:sd-fade-in .5s ease-in-out,sd-slide-down .5s ease-in-out}.sd-col>.sd-dropdown{width:100%}.sd-summary-content>.sd-tab-set:first-child{margin-top:0}@keyframes sd-fade-in{0%{opacity:0}100%{opacity:1}}@keyframes sd-slide-down{0%{transform:translate(0, -10px)}100%{transform:translate(0, 0)}}.sd-tab-set{border-radius:.125rem;display:flex;flex-wrap:wrap;margin:1em 0;position:relative}.sd-tab-set>input{opacity:0;position:absolute}.sd-tab-set>input:checked+label{border-color:var(--sd-color-tabs-underline-active);color:var(--sd-color-tabs-label-active)}.sd-tab-set>input:checked+label+.sd-tab-content{display:block}.sd-tab-set>input:not(:checked)+label:hover{color:var(--sd-color-tabs-label-hover);border-color:var(--sd-color-tabs-underline-hover)}.sd-tab-set>input:focus+label{outline-style:auto}.sd-tab-set>input:not(.focus-visible)+label{outline:none;-webkit-tap-highlight-color:transparent}.sd-tab-set>label{border-bottom:.125rem solid transparent;margin-bottom:0;color:var(--sd-color-tabs-label-inactive);border-color:var(--sd-color-tabs-underline-inactive);cursor:pointer;font-size:var(--sd-fontsize-tabs-label);font-weight:700;padding:1em 1.25em .5em;transition:color 250ms;width:auto;z-index:1}html .sd-tab-set>label:hover{color:var(--sd-color-tabs-label-active)}.sd-col>.sd-tab-set{width:100%}.sd-tab-content{box-shadow:0 -0.0625rem var(--sd-color-tabs-overline),0 .0625rem var(--sd-color-tabs-underline);display:none;order:99;padding-bottom:.75rem;padding-top:.75rem;width:100%}.sd-tab-content>:first-child{margin-top:0 !important}.sd-tab-content>:last-child{margin-bottom:0 !important}.sd-tab-content>.sd-tab-set{margin:0}.sd-sphinx-override,.sd-sphinx-override *{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}.sd-sphinx-override p{margin-top:0}:root{--sd-color-primary: #0071bc;--sd-color-secondary: #6c757d;--sd-color-success: #28a745;--sd-color-info: #17a2b8;--sd-color-warning: #f0b37e;--sd-color-danger: #dc3545;--sd-color-light: #f8f9fa;--sd-color-muted: #6c757d;--sd-color-dark: #212529;--sd-color-black: black;--sd-color-white: white;--sd-color-primary-highlight: #0060a0;--sd-color-secondary-highlight: #5c636a;--sd-color-success-highlight: #228e3b;--sd-color-info-highlight: #148a9c;--sd-color-warning-highlight: #cc986b;--sd-color-danger-highlight: #bb2d3b;--sd-color-light-highlight: #d3d4d5;--sd-color-muted-highlight: #5c636a;--sd-color-dark-highlight: #1c1f23;--sd-color-black-highlight: black;--sd-color-white-highlight: #d9d9d9;--sd-color-primary-bg: rgba(0, 113, 188, 0.2);--sd-color-secondary-bg: rgba(108, 117, 125, 0.2);--sd-color-success-bg: rgba(40, 167, 69, 0.2);--sd-color-info-bg: rgba(23, 162, 184, 0.2);--sd-color-warning-bg: rgba(240, 179, 126, 0.2);--sd-color-danger-bg: rgba(220, 53, 69, 0.2);--sd-color-light-bg: rgba(248, 249, 250, 0.2);--sd-color-muted-bg: rgba(108, 117, 125, 0.2);--sd-color-dark-bg: rgba(33, 37, 41, 0.2);--sd-color-black-bg: rgba(0, 0, 0, 0.2);--sd-color-white-bg: rgba(255, 255, 255, 0.2);--sd-color-primary-text: #fff;--sd-color-secondary-text: #fff;--sd-color-success-text: #fff;--sd-color-info-text: #fff;--sd-color-warning-text: #212529;--sd-color-danger-text: #fff;--sd-color-light-text: #212529;--sd-color-muted-text: #fff;--sd-color-dark-text: #fff;--sd-color-black-text: #fff;--sd-color-white-text: #212529;--sd-color-shadow: rgba(0, 0, 0, 0.15);--sd-color-card-border: rgba(0, 0, 0, 0.125);--sd-color-card-border-hover: hsla(231, 99%, 66%, 1);--sd-color-card-background: transparent;--sd-color-card-text: inherit;--sd-color-card-header: transparent;--sd-color-card-footer: transparent;--sd-color-tabs-label-active: hsla(231, 99%, 66%, 1);--sd-color-tabs-label-hover: hsla(231, 99%, 66%, 1);--sd-color-tabs-label-inactive: hsl(0, 0%, 66%);--sd-color-tabs-underline-active: hsla(231, 99%, 66%, 1);--sd-color-tabs-underline-hover: rgba(178, 206, 245, 0.62);--sd-color-tabs-underline-inactive: transparent;--sd-color-tabs-overline: rgb(222, 222, 222);--sd-color-tabs-underline: rgb(222, 222, 222);--sd-fontsize-tabs-label: 1rem;--sd-fontsize-dropdown: inherit;--sd-fontsize-dropdown-title: 1rem;--sd-fontweight-dropdown-title: 700} diff --git a/docs/fern/_static/check-solid.svg b/docs/fern/_static/check-solid.svg new file mode 100644 index 000000000..92fad4b5c --- /dev/null +++ b/docs/fern/_static/check-solid.svg @@ -0,0 +1,4 @@ + + + + diff --git a/docs/fern/_static/clipboard.min.js b/docs/fern/_static/clipboard.min.js new file mode 100644 index 000000000..54b3c4638 --- /dev/null +++ b/docs/fern/_static/clipboard.min.js @@ -0,0 +1,7 @@ +/*! + * clipboard.js v2.0.8 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */ +!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return n={686:function(t,e,n){"use strict";n.d(e,{default:function(){return o}});var e=n(279),i=n.n(e),e=n(370),u=n.n(e),e=n(817),c=n.n(e);function a(t){try{return document.execCommand(t)}catch(t){return}}var f=function(t){t=c()(t);return a("cut"),t};var l=function(t){var e,n,o,r=1 + + + + diff --git a/docs/fern/_static/copybutton.css b/docs/fern/_static/copybutton.css new file mode 100644 index 000000000..f1916ec7d --- /dev/null +++ b/docs/fern/_static/copybutton.css @@ -0,0 +1,94 @@ +/* Copy buttons */ +button.copybtn { + position: absolute; + display: flex; + top: .3em; + right: .3em; + width: 1.7em; + height: 1.7em; + opacity: 0; + transition: opacity 0.3s, border .3s, background-color .3s; + user-select: none; + padding: 0; + border: none; + outline: none; + border-radius: 0.4em; + /* The colors that GitHub uses */ + border: #1b1f2426 1px solid; + background-color: #f6f8fa; + color: #57606a; +} + +button.copybtn.success { + border-color: #22863a; + color: #22863a; +} + +button.copybtn svg { + stroke: currentColor; + width: 1.5em; + height: 1.5em; + padding: 0.1em; +} + +div.highlight { + position: relative; +} + +/* Show the copybutton */ +.highlight:hover button.copybtn, button.copybtn.success { + opacity: 1; +} + +.highlight button.copybtn:hover { + background-color: rgb(235, 235, 235); +} + +.highlight button.copybtn:active { + background-color: rgb(187, 187, 187); +} + +/** + * A minimal CSS-only tooltip copied from: + * https://codepen.io/mildrenben/pen/rVBrpK + * + * To use, write HTML like the following: + * + *

Short

+ */ + .o-tooltip--left { + position: relative; + } + + .o-tooltip--left:after { + opacity: 0; + visibility: hidden; + position: absolute; + content: attr(data-tooltip); + padding: .2em; + font-size: .8em; + left: -.2em; + background: grey; + color: white; + white-space: nowrap; + z-index: 2; + border-radius: 2px; + transform: translateX(-102%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); +} + +.o-tooltip--left:hover:after { + display: block; + opacity: 1; + visibility: visible; + transform: translateX(-100%) translateY(0); + transition: opacity 0.2s cubic-bezier(0.64, 0.09, 0.08, 1), transform 0.2s cubic-bezier(0.64, 0.09, 0.08, 1); + transition-delay: .5s; +} + +/* By default the copy button shouldn't show up when printing a page */ +@media print { + button.copybtn { + display: none; + } +} diff --git a/docs/fern/_static/copybutton.js_t b/docs/fern/_static/copybutton.js_t new file mode 100644 index 000000000..ec91f2096 --- /dev/null +++ b/docs/fern/_static/copybutton.js_t @@ -0,0 +1,175 @@ +// Localization support +const messages = { + 'en': { + 'copy': 'Copy', + 'copy_to_clipboard': 'Copy to clipboard', + 'copy_success': 'Copied!', + 'copy_failure': 'Failed to copy', + }, + 'es' : { + 'copy': 'Copiar', + 'copy_to_clipboard': 'Copiar al portapapeles', + 'copy_success': '¡Copiado!', + 'copy_failure': 'Error al copiar', + }, + 'de' : { + 'copy': 'Kopieren', + 'copy_to_clipboard': 'In die Zwischenablage kopieren', + 'copy_success': 'Kopiert!', + 'copy_failure': 'Fehler beim Kopieren', + }, + 'fr' : { + 'copy': 'Copier', + 'copy_to_clipboard': 'Copier dans le presse-papier', + 'copy_success': 'Copié !', + 'copy_failure': 'Échec de la copie', + }, + 'ru': { + 'copy': 'Скопировать', + 'copy_to_clipboard': 'Скопировать в буфер', + 'copy_success': 'Скопировано!', + 'copy_failure': 'Не удалось скопировать', + }, + 'zh-CN': { + 'copy': '复制', + 'copy_to_clipboard': '复制到剪贴板', + 'copy_success': '复制成功!', + 'copy_failure': '复制失败', + }, + 'it' : { + 'copy': 'Copiare', + 'copy_to_clipboard': 'Copiato negli appunti', + 'copy_success': 'Copiato!', + 'copy_failure': 'Errore durante la copia', + } +} + +let locale = 'en' +if( document.documentElement.lang !== undefined + && messages[document.documentElement.lang] !== undefined ) { + locale = document.documentElement.lang +} + +let doc_url_root = DOCUMENTATION_OPTIONS.URL_ROOT; +if (doc_url_root == '#') { + doc_url_root = ''; +} + +/** + * SVG files for our copy buttons + */ +let iconCheck = ` + ${messages[locale]['copy_success']} + + +` + +// If the user specified their own SVG use that, otherwise use the default +let iconCopy = `{{ copybutton_image_svg }}`; +if (!iconCopy) { + iconCopy = ` + ${messages[locale]['copy_to_clipboard']} + + + +` +} + +/** + * Set up copy/paste for code blocks + */ + +const runWhenDOMLoaded = cb => { + if (document.readyState != 'loading') { + cb() + } else if (document.addEventListener) { + document.addEventListener('DOMContentLoaded', cb) + } else { + document.attachEvent('onreadystatechange', function() { + if (document.readyState == 'complete') cb() + }) + } +} + +const codeCellId = index => `codecell${index}` + +// Clears selected text since ClipboardJS will select the text when copying +const clearSelection = () => { + if (window.getSelection) { + window.getSelection().removeAllRanges() + } else if (document.selection) { + document.selection.empty() + } +} + +// Changes tooltip text for a moment, then changes it back +// We want the timeout of our `success` class to be a bit shorter than the +// tooltip and icon change, so that we can hide the icon before changing back. +var timeoutIcon = 2000; +var timeoutSuccessClass = 1500; + +const temporarilyChangeTooltip = (el, oldText, newText) => { + el.setAttribute('data-tooltip', newText) + el.classList.add('success') + // Remove success a little bit sooner than we change the tooltip + // So that we can use CSS to hide the copybutton first + setTimeout(() => el.classList.remove('success'), timeoutSuccessClass) + setTimeout(() => el.setAttribute('data-tooltip', oldText), timeoutIcon) +} + +// Changes the copy button icon for two seconds, then changes it back +const temporarilyChangeIcon = (el) => { + el.innerHTML = iconCheck; + setTimeout(() => {el.innerHTML = iconCopy}, timeoutIcon) +} + +const addCopyButtonToCodeCells = () => { + // If ClipboardJS hasn't loaded, wait a bit and try again. This + // happens because we load ClipboardJS asynchronously. + if (window.ClipboardJS === undefined) { + setTimeout(addCopyButtonToCodeCells, 250) + return + } + + // Add copybuttons to all of our code cells + const COPYBUTTON_SELECTOR = '{{ copybutton_selector }}'; + const codeCells = document.querySelectorAll(COPYBUTTON_SELECTOR) + codeCells.forEach((codeCell, index) => { + const id = codeCellId(index) + codeCell.setAttribute('id', id) + + const clipboardButton = id => + `` + codeCell.insertAdjacentHTML('afterend', clipboardButton(id)) + }) + +{{ copybutton_format_func }} + +var copyTargetText = (trigger) => { + var target = document.querySelector(trigger.attributes['data-clipboard-target'].value); + + // get filtered text + let exclude = '{{ copybutton_exclude }}'; + + let text = filterText(target, exclude); + return formatCopyText(text, {{ "{!r}".format(copybutton_prompt_text) }}, {{ copybutton_prompt_is_regexp | lower }}, {{ copybutton_only_copy_prompt_lines | lower }}, {{ copybutton_remove_prompts | lower }}, {{ copybutton_copy_empty_lines | lower }}, {{ "{!r}".format(copybutton_line_continuation_character) }}, {{ "{!r}".format(copybutton_here_doc_delimiter) }}) +} + + // Initialize with a callback so we can modify the text before copy + const clipboard = new ClipboardJS('.copybtn', {text: copyTargetText}) + + // Update UI with error/success messages + clipboard.on('success', event => { + clearSelection() + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_success']) + temporarilyChangeIcon(event.trigger) + }) + + clipboard.on('error', event => { + temporarilyChangeTooltip(event.trigger, messages[locale]['copy'], messages[locale]['copy_failure']) + }) +} + +runWhenDOMLoaded(addCopyButtonToCodeCells) diff --git a/docs/fern/_static/copybutton_funcs.js b/docs/fern/_static/copybutton_funcs.js new file mode 100644 index 000000000..dbe1aaad7 --- /dev/null +++ b/docs/fern/_static/copybutton_funcs.js @@ -0,0 +1,73 @@ +function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string +} + +/** + * Removes excluded text from a Node. + * + * @param {Node} target Node to filter. + * @param {string} exclude CSS selector of nodes to exclude. + * @returns {DOMString} Text from `target` with text removed. + */ +export function filterText(target, exclude) { + const clone = target.cloneNode(true); // clone as to not modify the live DOM + if (exclude) { + // remove excluded nodes + clone.querySelectorAll(exclude).forEach(node => node.remove()); + } + return clone.innerText; +} + +// Callback when a copy button is clicked. Will be passed the node that was clicked +// should then grab the text and replace pieces of text that shouldn't be used in output +export function formatCopyText(textContent, copybuttonPromptText, isRegexp = false, onlyCopyPromptLines = true, removePrompts = true, copyEmptyLines = true, lineContinuationChar = "", hereDocDelim = "") { + var regexp; + var match; + + // Do we check for line continuation characters and "HERE-documents"? + var useLineCont = !!lineContinuationChar + var useHereDoc = !!hereDocDelim + + // create regexp to capture prompt and remaining line + if (isRegexp) { + regexp = new RegExp('^(' + copybuttonPromptText + ')(.*)') + } else { + regexp = new RegExp('^(' + escapeRegExp(copybuttonPromptText) + ')(.*)') + } + + const outputLines = []; + var promptFound = false; + var gotLineCont = false; + var gotHereDoc = false; + const lineGotPrompt = []; + for (const line of textContent.split('\n')) { + match = line.match(regexp) + if (match || gotLineCont || gotHereDoc) { + promptFound = regexp.test(line) + lineGotPrompt.push(promptFound) + if (removePrompts && promptFound) { + outputLines.push(match[2]) + } else { + outputLines.push(line) + } + gotLineCont = line.endsWith(lineContinuationChar) & useLineCont + if (line.includes(hereDocDelim) & useHereDoc) + gotHereDoc = !gotHereDoc + } else if (!onlyCopyPromptLines) { + outputLines.push(line) + } else if (copyEmptyLines && line.trim() === '') { + outputLines.push(line) + } + } + + // If no lines with the prompt were found then just use original lines + if (lineGotPrompt.some(v => v === true)) { + textContent = outputLines.join('\n'); + } + + // Remove a trailing newline to avoid auto-running when pasting + if (textContent.endsWith("\n")) { + textContent = textContent.slice(0, -1) + } + return textContent +} diff --git a/docs/_static/css/termynal.css b/docs/fern/_static/css/termynal.css similarity index 100% rename from docs/_static/css/termynal.css rename to docs/fern/_static/css/termynal.css diff --git a/docs/_static/customize.css b/docs/fern/_static/customize.css similarity index 100% rename from docs/_static/customize.css rename to docs/fern/_static/customize.css diff --git a/docs/fern/_static/design-tabs.js b/docs/fern/_static/design-tabs.js new file mode 100644 index 000000000..b25bd6a4f --- /dev/null +++ b/docs/fern/_static/design-tabs.js @@ -0,0 +1,101 @@ +// @ts-check + +// Extra JS capability for selected tabs to be synced +// The selection is stored in local storage so that it persists across page loads. + +/** + * @type {Record} + */ +let sd_id_to_elements = {}; +const storageKeyPrefix = "sphinx-design-tab-id-"; + +/** + * Create a key for a tab element. + * @param {HTMLElement} el - The tab element. + * @returns {[string, string, string] | null} - The key. + * + */ +function create_key(el) { + let syncId = el.getAttribute("data-sync-id"); + let syncGroup = el.getAttribute("data-sync-group"); + if (!syncId || !syncGroup) return null; + return [syncGroup, syncId, syncGroup + "--" + syncId]; +} + +/** + * Initialize the tab selection. + * + */ +function ready() { + // Find all tabs with sync data + + /** @type {string[]} */ + let groups = []; + + document.querySelectorAll(".sd-tab-label").forEach((label) => { + if (label instanceof HTMLElement) { + let data = create_key(label); + if (data) { + let [group, id, key] = data; + + // add click event listener + // @ts-ignore + label.onclick = onSDLabelClick; + + // store map of key to elements + if (!sd_id_to_elements[key]) { + sd_id_to_elements[key] = []; + } + sd_id_to_elements[key].push(label); + + if (groups.indexOf(group) === -1) { + groups.push(group); + // Check if a specific tab has been selected via URL parameter + const tabParam = new URLSearchParams(window.location.search).get( + group + ); + if (tabParam) { + console.log( + "sphinx-design: Selecting tab id for group '" + + group + + "' from URL parameter: " + + tabParam + ); + window.sessionStorage.setItem(storageKeyPrefix + group, tabParam); + } + } + + // Check is a specific tab has been selected previously + let previousId = window.sessionStorage.getItem( + storageKeyPrefix + group + ); + if (previousId === id) { + // console.log( + // "sphinx-design: Selecting tab from session storage: " + id + // ); + // @ts-ignore + label.previousElementSibling.checked = true; + } + } + } + }); +} + +/** + * Activate other tabs with the same sync id. + * + * @this {HTMLElement} - The element that was clicked. + */ +function onSDLabelClick() { + let data = create_key(this); + if (!data) return; + let [group, id, key] = data; + for (const label of sd_id_to_elements[key]) { + if (label === this) continue; + // @ts-ignore + label.previousElementSibling.checked = true; + } + window.sessionStorage.setItem(storageKeyPrefix + group, id); +} + +document.addEventListener("DOMContentLoaded", ready, false); diff --git a/docs/_static/js/termynal-init.js b/docs/fern/_static/js/termynal-init.js similarity index 100% rename from docs/_static/js/termynal-init.js rename to docs/fern/_static/js/termynal-init.js diff --git a/docs/_static/js/termynal.js b/docs/fern/_static/js/termynal.js similarity index 100% rename from docs/_static/js/termynal.js rename to docs/fern/_static/js/termynal.js diff --git a/docs/fern/_static/sphinx-design.min.css b/docs/fern/_static/sphinx-design.min.css new file mode 100644 index 000000000..860c36da0 --- /dev/null +++ b/docs/fern/_static/sphinx-design.min.css @@ -0,0 +1 @@ +.sd-bg-primary{background-color:var(--sd-color-primary) !important}.sd-bg-text-primary{color:var(--sd-color-primary-text) !important}button.sd-bg-primary:focus,button.sd-bg-primary:hover{background-color:var(--sd-color-primary-highlight) !important}a.sd-bg-primary:focus,a.sd-bg-primary:hover{background-color:var(--sd-color-primary-highlight) !important}.sd-bg-secondary{background-color:var(--sd-color-secondary) !important}.sd-bg-text-secondary{color:var(--sd-color-secondary-text) !important}button.sd-bg-secondary:focus,button.sd-bg-secondary:hover{background-color:var(--sd-color-secondary-highlight) !important}a.sd-bg-secondary:focus,a.sd-bg-secondary:hover{background-color:var(--sd-color-secondary-highlight) !important}.sd-bg-success{background-color:var(--sd-color-success) !important}.sd-bg-text-success{color:var(--sd-color-success-text) !important}button.sd-bg-success:focus,button.sd-bg-success:hover{background-color:var(--sd-color-success-highlight) !important}a.sd-bg-success:focus,a.sd-bg-success:hover{background-color:var(--sd-color-success-highlight) !important}.sd-bg-info{background-color:var(--sd-color-info) !important}.sd-bg-text-info{color:var(--sd-color-info-text) !important}button.sd-bg-info:focus,button.sd-bg-info:hover{background-color:var(--sd-color-info-highlight) !important}a.sd-bg-info:focus,a.sd-bg-info:hover{background-color:var(--sd-color-info-highlight) !important}.sd-bg-warning{background-color:var(--sd-color-warning) !important}.sd-bg-text-warning{color:var(--sd-color-warning-text) !important}button.sd-bg-warning:focus,button.sd-bg-warning:hover{background-color:var(--sd-color-warning-highlight) !important}a.sd-bg-warning:focus,a.sd-bg-warning:hover{background-color:var(--sd-color-warning-highlight) !important}.sd-bg-danger{background-color:var(--sd-color-danger) !important}.sd-bg-text-danger{color:var(--sd-color-danger-text) !important}button.sd-bg-danger:focus,button.sd-bg-danger:hover{background-color:var(--sd-color-danger-highlight) !important}a.sd-bg-danger:focus,a.sd-bg-danger:hover{background-color:var(--sd-color-danger-highlight) !important}.sd-bg-light{background-color:var(--sd-color-light) !important}.sd-bg-text-light{color:var(--sd-color-light-text) !important}button.sd-bg-light:focus,button.sd-bg-light:hover{background-color:var(--sd-color-light-highlight) !important}a.sd-bg-light:focus,a.sd-bg-light:hover{background-color:var(--sd-color-light-highlight) !important}.sd-bg-muted{background-color:var(--sd-color-muted) !important}.sd-bg-text-muted{color:var(--sd-color-muted-text) !important}button.sd-bg-muted:focus,button.sd-bg-muted:hover{background-color:var(--sd-color-muted-highlight) !important}a.sd-bg-muted:focus,a.sd-bg-muted:hover{background-color:var(--sd-color-muted-highlight) !important}.sd-bg-dark{background-color:var(--sd-color-dark) !important}.sd-bg-text-dark{color:var(--sd-color-dark-text) !important}button.sd-bg-dark:focus,button.sd-bg-dark:hover{background-color:var(--sd-color-dark-highlight) !important}a.sd-bg-dark:focus,a.sd-bg-dark:hover{background-color:var(--sd-color-dark-highlight) !important}.sd-bg-black{background-color:var(--sd-color-black) !important}.sd-bg-text-black{color:var(--sd-color-black-text) !important}button.sd-bg-black:focus,button.sd-bg-black:hover{background-color:var(--sd-color-black-highlight) !important}a.sd-bg-black:focus,a.sd-bg-black:hover{background-color:var(--sd-color-black-highlight) !important}.sd-bg-white{background-color:var(--sd-color-white) !important}.sd-bg-text-white{color:var(--sd-color-white-text) !important}button.sd-bg-white:focus,button.sd-bg-white:hover{background-color:var(--sd-color-white-highlight) !important}a.sd-bg-white:focus,a.sd-bg-white:hover{background-color:var(--sd-color-white-highlight) !important}.sd-text-primary,.sd-text-primary>p{color:var(--sd-color-primary) !important}a.sd-text-primary:focus,a.sd-text-primary:hover{color:var(--sd-color-primary-highlight) !important}.sd-text-secondary,.sd-text-secondary>p{color:var(--sd-color-secondary) !important}a.sd-text-secondary:focus,a.sd-text-secondary:hover{color:var(--sd-color-secondary-highlight) !important}.sd-text-success,.sd-text-success>p{color:var(--sd-color-success) !important}a.sd-text-success:focus,a.sd-text-success:hover{color:var(--sd-color-success-highlight) !important}.sd-text-info,.sd-text-info>p{color:var(--sd-color-info) !important}a.sd-text-info:focus,a.sd-text-info:hover{color:var(--sd-color-info-highlight) !important}.sd-text-warning,.sd-text-warning>p{color:var(--sd-color-warning) !important}a.sd-text-warning:focus,a.sd-text-warning:hover{color:var(--sd-color-warning-highlight) !important}.sd-text-danger,.sd-text-danger>p{color:var(--sd-color-danger) !important}a.sd-text-danger:focus,a.sd-text-danger:hover{color:var(--sd-color-danger-highlight) !important}.sd-text-light,.sd-text-light>p{color:var(--sd-color-light) !important}a.sd-text-light:focus,a.sd-text-light:hover{color:var(--sd-color-light-highlight) !important}.sd-text-muted,.sd-text-muted>p{color:var(--sd-color-muted) !important}a.sd-text-muted:focus,a.sd-text-muted:hover{color:var(--sd-color-muted-highlight) !important}.sd-text-dark,.sd-text-dark>p{color:var(--sd-color-dark) !important}a.sd-text-dark:focus,a.sd-text-dark:hover{color:var(--sd-color-dark-highlight) !important}.sd-text-black,.sd-text-black>p{color:var(--sd-color-black) !important}a.sd-text-black:focus,a.sd-text-black:hover{color:var(--sd-color-black-highlight) !important}.sd-text-white,.sd-text-white>p{color:var(--sd-color-white) !important}a.sd-text-white:focus,a.sd-text-white:hover{color:var(--sd-color-white-highlight) !important}.sd-outline-primary{border-color:var(--sd-color-primary) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-primary:focus,a.sd-outline-primary:hover{border-color:var(--sd-color-primary-highlight) !important}.sd-outline-secondary{border-color:var(--sd-color-secondary) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-secondary:focus,a.sd-outline-secondary:hover{border-color:var(--sd-color-secondary-highlight) !important}.sd-outline-success{border-color:var(--sd-color-success) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-success:focus,a.sd-outline-success:hover{border-color:var(--sd-color-success-highlight) !important}.sd-outline-info{border-color:var(--sd-color-info) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-info:focus,a.sd-outline-info:hover{border-color:var(--sd-color-info-highlight) !important}.sd-outline-warning{border-color:var(--sd-color-warning) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-warning:focus,a.sd-outline-warning:hover{border-color:var(--sd-color-warning-highlight) !important}.sd-outline-danger{border-color:var(--sd-color-danger) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-danger:focus,a.sd-outline-danger:hover{border-color:var(--sd-color-danger-highlight) !important}.sd-outline-light{border-color:var(--sd-color-light) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-light:focus,a.sd-outline-light:hover{border-color:var(--sd-color-light-highlight) !important}.sd-outline-muted{border-color:var(--sd-color-muted) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-muted:focus,a.sd-outline-muted:hover{border-color:var(--sd-color-muted-highlight) !important}.sd-outline-dark{border-color:var(--sd-color-dark) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-dark:focus,a.sd-outline-dark:hover{border-color:var(--sd-color-dark-highlight) !important}.sd-outline-black{border-color:var(--sd-color-black) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-black:focus,a.sd-outline-black:hover{border-color:var(--sd-color-black-highlight) !important}.sd-outline-white{border-color:var(--sd-color-white) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-white:focus,a.sd-outline-white:hover{border-color:var(--sd-color-white-highlight) !important}.sd-bg-transparent{background-color:transparent !important}.sd-outline-transparent{border-color:transparent !important}.sd-text-transparent{color:transparent !important}.sd-p-0{padding:0 !important}.sd-pt-0,.sd-py-0{padding-top:0 !important}.sd-pr-0,.sd-px-0{padding-right:0 !important}.sd-pb-0,.sd-py-0{padding-bottom:0 !important}.sd-pl-0,.sd-px-0{padding-left:0 !important}.sd-p-1{padding:.25rem !important}.sd-pt-1,.sd-py-1{padding-top:.25rem !important}.sd-pr-1,.sd-px-1{padding-right:.25rem !important}.sd-pb-1,.sd-py-1{padding-bottom:.25rem !important}.sd-pl-1,.sd-px-1{padding-left:.25rem !important}.sd-p-2{padding:.5rem !important}.sd-pt-2,.sd-py-2{padding-top:.5rem !important}.sd-pr-2,.sd-px-2{padding-right:.5rem !important}.sd-pb-2,.sd-py-2{padding-bottom:.5rem !important}.sd-pl-2,.sd-px-2{padding-left:.5rem !important}.sd-p-3{padding:1rem !important}.sd-pt-3,.sd-py-3{padding-top:1rem !important}.sd-pr-3,.sd-px-3{padding-right:1rem !important}.sd-pb-3,.sd-py-3{padding-bottom:1rem !important}.sd-pl-3,.sd-px-3{padding-left:1rem !important}.sd-p-4{padding:1.5rem !important}.sd-pt-4,.sd-py-4{padding-top:1.5rem !important}.sd-pr-4,.sd-px-4{padding-right:1.5rem !important}.sd-pb-4,.sd-py-4{padding-bottom:1.5rem !important}.sd-pl-4,.sd-px-4{padding-left:1.5rem !important}.sd-p-5{padding:3rem !important}.sd-pt-5,.sd-py-5{padding-top:3rem !important}.sd-pr-5,.sd-px-5{padding-right:3rem !important}.sd-pb-5,.sd-py-5{padding-bottom:3rem !important}.sd-pl-5,.sd-px-5{padding-left:3rem !important}.sd-m-auto{margin:auto !important}.sd-mt-auto,.sd-my-auto{margin-top:auto !important}.sd-mr-auto,.sd-mx-auto{margin-right:auto !important}.sd-mb-auto,.sd-my-auto{margin-bottom:auto !important}.sd-ml-auto,.sd-mx-auto{margin-left:auto !important}.sd-m-0{margin:0 !important}.sd-mt-0,.sd-my-0{margin-top:0 !important}.sd-mr-0,.sd-mx-0{margin-right:0 !important}.sd-mb-0,.sd-my-0{margin-bottom:0 !important}.sd-ml-0,.sd-mx-0{margin-left:0 !important}.sd-m-1{margin:.25rem !important}.sd-mt-1,.sd-my-1{margin-top:.25rem !important}.sd-mr-1,.sd-mx-1{margin-right:.25rem !important}.sd-mb-1,.sd-my-1{margin-bottom:.25rem !important}.sd-ml-1,.sd-mx-1{margin-left:.25rem !important}.sd-m-2{margin:.5rem !important}.sd-mt-2,.sd-my-2{margin-top:.5rem !important}.sd-mr-2,.sd-mx-2{margin-right:.5rem !important}.sd-mb-2,.sd-my-2{margin-bottom:.5rem !important}.sd-ml-2,.sd-mx-2{margin-left:.5rem !important}.sd-m-3{margin:1rem !important}.sd-mt-3,.sd-my-3{margin-top:1rem !important}.sd-mr-3,.sd-mx-3{margin-right:1rem !important}.sd-mb-3,.sd-my-3{margin-bottom:1rem !important}.sd-ml-3,.sd-mx-3{margin-left:1rem !important}.sd-m-4{margin:1.5rem !important}.sd-mt-4,.sd-my-4{margin-top:1.5rem !important}.sd-mr-4,.sd-mx-4{margin-right:1.5rem !important}.sd-mb-4,.sd-my-4{margin-bottom:1.5rem !important}.sd-ml-4,.sd-mx-4{margin-left:1.5rem !important}.sd-m-5{margin:3rem !important}.sd-mt-5,.sd-my-5{margin-top:3rem !important}.sd-mr-5,.sd-mx-5{margin-right:3rem !important}.sd-mb-5,.sd-my-5{margin-bottom:3rem !important}.sd-ml-5,.sd-mx-5{margin-left:3rem !important}.sd-w-25{width:25% !important}.sd-w-50{width:50% !important}.sd-w-75{width:75% !important}.sd-w-100{width:100% !important}.sd-w-auto{width:auto !important}.sd-h-25{height:25% !important}.sd-h-50{height:50% !important}.sd-h-75{height:75% !important}.sd-h-100{height:100% !important}.sd-h-auto{height:auto !important}.sd-d-none{display:none !important}.sd-d-inline{display:inline !important}.sd-d-inline-block{display:inline-block !important}.sd-d-block{display:block !important}.sd-d-grid{display:grid !important}.sd-d-flex-row{display:-ms-flexbox !important;display:flex !important;flex-direction:row !important}.sd-d-flex-column{display:-ms-flexbox !important;display:flex !important;flex-direction:column !important}.sd-d-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}@media(min-width: 576px){.sd-d-sm-none{display:none !important}.sd-d-sm-inline{display:inline !important}.sd-d-sm-inline-block{display:inline-block !important}.sd-d-sm-block{display:block !important}.sd-d-sm-grid{display:grid !important}.sd-d-sm-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-sm-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}@media(min-width: 768px){.sd-d-md-none{display:none !important}.sd-d-md-inline{display:inline !important}.sd-d-md-inline-block{display:inline-block !important}.sd-d-md-block{display:block !important}.sd-d-md-grid{display:grid !important}.sd-d-md-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-md-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}@media(min-width: 992px){.sd-d-lg-none{display:none !important}.sd-d-lg-inline{display:inline !important}.sd-d-lg-inline-block{display:inline-block !important}.sd-d-lg-block{display:block !important}.sd-d-lg-grid{display:grid !important}.sd-d-lg-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-lg-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}@media(min-width: 1200px){.sd-d-xl-none{display:none !important}.sd-d-xl-inline{display:inline !important}.sd-d-xl-inline-block{display:inline-block !important}.sd-d-xl-block{display:block !important}.sd-d-xl-grid{display:grid !important}.sd-d-xl-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-xl-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}.sd-align-major-start{justify-content:flex-start !important}.sd-align-major-end{justify-content:flex-end !important}.sd-align-major-center{justify-content:center !important}.sd-align-major-justify{justify-content:space-between !important}.sd-align-major-spaced{justify-content:space-evenly !important}.sd-align-minor-start{align-items:flex-start !important}.sd-align-minor-end{align-items:flex-end !important}.sd-align-minor-center{align-items:center !important}.sd-align-minor-stretch{align-items:stretch !important}.sd-text-justify{text-align:justify !important}.sd-text-left{text-align:left !important}.sd-text-right{text-align:right !important}.sd-text-center{text-align:center !important}.sd-font-weight-light{font-weight:300 !important}.sd-font-weight-lighter{font-weight:lighter !important}.sd-font-weight-normal{font-weight:400 !important}.sd-font-weight-bold{font-weight:700 !important}.sd-font-weight-bolder{font-weight:bolder !important}.sd-font-italic{font-style:italic !important}.sd-text-decoration-none{text-decoration:none !important}.sd-text-lowercase{text-transform:lowercase !important}.sd-text-uppercase{text-transform:uppercase !important}.sd-text-capitalize{text-transform:capitalize !important}.sd-text-wrap{white-space:normal !important}.sd-text-nowrap{white-space:nowrap !important}.sd-text-truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.sd-fs-1,.sd-fs-1>p{font-size:calc(1.375rem + 1.5vw) !important;line-height:unset !important}.sd-fs-2,.sd-fs-2>p{font-size:calc(1.325rem + 0.9vw) !important;line-height:unset !important}.sd-fs-3,.sd-fs-3>p{font-size:calc(1.3rem + 0.6vw) !important;line-height:unset !important}.sd-fs-4,.sd-fs-4>p{font-size:calc(1.275rem + 0.3vw) !important;line-height:unset !important}.sd-fs-5,.sd-fs-5>p{font-size:1.25rem !important;line-height:unset !important}.sd-fs-6,.sd-fs-6>p{font-size:1rem !important;line-height:unset !important}.sd-border-0{border:0 solid !important}.sd-border-top-0{border-top:0 solid !important}.sd-border-bottom-0{border-bottom:0 solid !important}.sd-border-right-0{border-right:0 solid !important}.sd-border-left-0{border-left:0 solid !important}.sd-border-1{border:1px solid !important}.sd-border-top-1{border-top:1px solid !important}.sd-border-bottom-1{border-bottom:1px solid !important}.sd-border-right-1{border-right:1px solid !important}.sd-border-left-1{border-left:1px solid !important}.sd-border-2{border:2px solid !important}.sd-border-top-2{border-top:2px solid !important}.sd-border-bottom-2{border-bottom:2px solid !important}.sd-border-right-2{border-right:2px solid !important}.sd-border-left-2{border-left:2px solid !important}.sd-border-3{border:3px solid !important}.sd-border-top-3{border-top:3px solid !important}.sd-border-bottom-3{border-bottom:3px solid !important}.sd-border-right-3{border-right:3px solid !important}.sd-border-left-3{border-left:3px solid !important}.sd-border-4{border:4px solid !important}.sd-border-top-4{border-top:4px solid !important}.sd-border-bottom-4{border-bottom:4px solid !important}.sd-border-right-4{border-right:4px solid !important}.sd-border-left-4{border-left:4px solid !important}.sd-border-5{border:5px solid !important}.sd-border-top-5{border-top:5px solid !important}.sd-border-bottom-5{border-bottom:5px solid !important}.sd-border-right-5{border-right:5px solid !important}.sd-border-left-5{border-left:5px solid !important}.sd-rounded-0{border-radius:0 !important}.sd-rounded-1{border-radius:.2rem !important}.sd-rounded-2{border-radius:.3rem !important}.sd-rounded-3{border-radius:.5rem !important}.sd-rounded-pill{border-radius:50rem !important}.sd-rounded-circle{border-radius:50% !important}.shadow-none{box-shadow:none !important}.sd-shadow-sm{box-shadow:0 .125rem .25rem var(--sd-color-shadow) !important}.sd-shadow-md{box-shadow:0 .5rem 1rem var(--sd-color-shadow) !important}.sd-shadow-lg{box-shadow:0 1rem 3rem var(--sd-color-shadow) !important}@keyframes sd-slide-from-left{0%{transform:translateX(-100%)}100%{transform:translateX(0)}}@keyframes sd-slide-from-right{0%{transform:translateX(200%)}100%{transform:translateX(0)}}@keyframes sd-grow100{0%{transform:scale(0);opacity:.5}100%{transform:scale(1);opacity:1}}@keyframes sd-grow50{0%{transform:scale(0.5);opacity:.5}100%{transform:scale(1);opacity:1}}@keyframes sd-grow50-rot20{0%{transform:scale(0.5) rotateZ(-20deg);opacity:.5}75%{transform:scale(1) rotateZ(5deg);opacity:1}95%{transform:scale(1) rotateZ(-1deg);opacity:1}100%{transform:scale(1) rotateZ(0);opacity:1}}.sd-animate-slide-from-left{animation:1s ease-out 0s 1 normal none running sd-slide-from-left}.sd-animate-slide-from-right{animation:1s ease-out 0s 1 normal none running sd-slide-from-right}.sd-animate-grow100{animation:1s ease-out 0s 1 normal none running sd-grow100}.sd-animate-grow50{animation:1s ease-out 0s 1 normal none running sd-grow50}.sd-animate-grow50-rot20{animation:1s ease-out 0s 1 normal none running sd-grow50-rot20}.sd-badge{display:inline-block;padding:.35em .65em;font-size:.75em;font-weight:700;line-height:1;text-align:center;white-space:nowrap;vertical-align:baseline;border-radius:.25rem}.sd-badge:empty{display:none}a.sd-badge{text-decoration:none}.sd-btn .sd-badge{position:relative;top:-1px}.sd-btn{background-color:transparent;border:1px solid transparent;border-radius:.25rem;cursor:pointer;display:inline-block;font-weight:400;font-size:1rem;line-height:1.5;padding:.375rem .75rem;text-align:center;text-decoration:none;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out;vertical-align:middle;user-select:none;-moz-user-select:none;-ms-user-select:none;-webkit-user-select:none}.sd-btn:hover{text-decoration:none}@media(prefers-reduced-motion: reduce){.sd-btn{transition:none}}.sd-btn-primary,.sd-btn-outline-primary:hover,.sd-btn-outline-primary:focus{color:var(--sd-color-primary-text) !important;background-color:var(--sd-color-primary) !important;border-color:var(--sd-color-primary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-primary:hover,.sd-btn-primary:focus{color:var(--sd-color-primary-text) !important;background-color:var(--sd-color-primary-highlight) !important;border-color:var(--sd-color-primary-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-primary{color:var(--sd-color-primary) !important;border-color:var(--sd-color-primary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-secondary,.sd-btn-outline-secondary:hover,.sd-btn-outline-secondary:focus{color:var(--sd-color-secondary-text) !important;background-color:var(--sd-color-secondary) !important;border-color:var(--sd-color-secondary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-secondary:hover,.sd-btn-secondary:focus{color:var(--sd-color-secondary-text) !important;background-color:var(--sd-color-secondary-highlight) !important;border-color:var(--sd-color-secondary-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-secondary{color:var(--sd-color-secondary) !important;border-color:var(--sd-color-secondary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-success,.sd-btn-outline-success:hover,.sd-btn-outline-success:focus{color:var(--sd-color-success-text) !important;background-color:var(--sd-color-success) !important;border-color:var(--sd-color-success) !important;border-width:1px !important;border-style:solid !important}.sd-btn-success:hover,.sd-btn-success:focus{color:var(--sd-color-success-text) !important;background-color:var(--sd-color-success-highlight) !important;border-color:var(--sd-color-success-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-success{color:var(--sd-color-success) !important;border-color:var(--sd-color-success) !important;border-width:1px !important;border-style:solid !important}.sd-btn-info,.sd-btn-outline-info:hover,.sd-btn-outline-info:focus{color:var(--sd-color-info-text) !important;background-color:var(--sd-color-info) !important;border-color:var(--sd-color-info) !important;border-width:1px !important;border-style:solid !important}.sd-btn-info:hover,.sd-btn-info:focus{color:var(--sd-color-info-text) !important;background-color:var(--sd-color-info-highlight) !important;border-color:var(--sd-color-info-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-info{color:var(--sd-color-info) !important;border-color:var(--sd-color-info) !important;border-width:1px !important;border-style:solid !important}.sd-btn-warning,.sd-btn-outline-warning:hover,.sd-btn-outline-warning:focus{color:var(--sd-color-warning-text) !important;background-color:var(--sd-color-warning) !important;border-color:var(--sd-color-warning) !important;border-width:1px !important;border-style:solid !important}.sd-btn-warning:hover,.sd-btn-warning:focus{color:var(--sd-color-warning-text) !important;background-color:var(--sd-color-warning-highlight) !important;border-color:var(--sd-color-warning-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-warning{color:var(--sd-color-warning) !important;border-color:var(--sd-color-warning) !important;border-width:1px !important;border-style:solid !important}.sd-btn-danger,.sd-btn-outline-danger:hover,.sd-btn-outline-danger:focus{color:var(--sd-color-danger-text) !important;background-color:var(--sd-color-danger) !important;border-color:var(--sd-color-danger) !important;border-width:1px !important;border-style:solid !important}.sd-btn-danger:hover,.sd-btn-danger:focus{color:var(--sd-color-danger-text) !important;background-color:var(--sd-color-danger-highlight) !important;border-color:var(--sd-color-danger-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-danger{color:var(--sd-color-danger) !important;border-color:var(--sd-color-danger) !important;border-width:1px !important;border-style:solid !important}.sd-btn-light,.sd-btn-outline-light:hover,.sd-btn-outline-light:focus{color:var(--sd-color-light-text) !important;background-color:var(--sd-color-light) !important;border-color:var(--sd-color-light) !important;border-width:1px !important;border-style:solid !important}.sd-btn-light:hover,.sd-btn-light:focus{color:var(--sd-color-light-text) !important;background-color:var(--sd-color-light-highlight) !important;border-color:var(--sd-color-light-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-light{color:var(--sd-color-light) !important;border-color:var(--sd-color-light) !important;border-width:1px !important;border-style:solid !important}.sd-btn-muted,.sd-btn-outline-muted:hover,.sd-btn-outline-muted:focus{color:var(--sd-color-muted-text) !important;background-color:var(--sd-color-muted) !important;border-color:var(--sd-color-muted) !important;border-width:1px !important;border-style:solid !important}.sd-btn-muted:hover,.sd-btn-muted:focus{color:var(--sd-color-muted-text) !important;background-color:var(--sd-color-muted-highlight) !important;border-color:var(--sd-color-muted-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-muted{color:var(--sd-color-muted) !important;border-color:var(--sd-color-muted) !important;border-width:1px !important;border-style:solid !important}.sd-btn-dark,.sd-btn-outline-dark:hover,.sd-btn-outline-dark:focus{color:var(--sd-color-dark-text) !important;background-color:var(--sd-color-dark) !important;border-color:var(--sd-color-dark) !important;border-width:1px !important;border-style:solid !important}.sd-btn-dark:hover,.sd-btn-dark:focus{color:var(--sd-color-dark-text) !important;background-color:var(--sd-color-dark-highlight) !important;border-color:var(--sd-color-dark-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-dark{color:var(--sd-color-dark) !important;border-color:var(--sd-color-dark) !important;border-width:1px !important;border-style:solid !important}.sd-btn-black,.sd-btn-outline-black:hover,.sd-btn-outline-black:focus{color:var(--sd-color-black-text) !important;background-color:var(--sd-color-black) !important;border-color:var(--sd-color-black) !important;border-width:1px !important;border-style:solid !important}.sd-btn-black:hover,.sd-btn-black:focus{color:var(--sd-color-black-text) !important;background-color:var(--sd-color-black-highlight) !important;border-color:var(--sd-color-black-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-black{color:var(--sd-color-black) !important;border-color:var(--sd-color-black) !important;border-width:1px !important;border-style:solid !important}.sd-btn-white,.sd-btn-outline-white:hover,.sd-btn-outline-white:focus{color:var(--sd-color-white-text) !important;background-color:var(--sd-color-white) !important;border-color:var(--sd-color-white) !important;border-width:1px !important;border-style:solid !important}.sd-btn-white:hover,.sd-btn-white:focus{color:var(--sd-color-white-text) !important;background-color:var(--sd-color-white-highlight) !important;border-color:var(--sd-color-white-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-white{color:var(--sd-color-white) !important;border-color:var(--sd-color-white) !important;border-width:1px !important;border-style:solid !important}.sd-stretched-link::after{position:absolute;top:0;right:0;bottom:0;left:0;z-index:1;content:""}.sd-hide-link-text{font-size:0}.sd-octicon,.sd-material-icon{display:inline-block;fill:currentColor;vertical-align:middle}.sd-avatar-xs{border-radius:50%;object-fit:cover;object-position:center;width:1rem;height:1rem}.sd-avatar-sm{border-radius:50%;object-fit:cover;object-position:center;width:3rem;height:3rem}.sd-avatar-md{border-radius:50%;object-fit:cover;object-position:center;width:5rem;height:5rem}.sd-avatar-lg{border-radius:50%;object-fit:cover;object-position:center;width:7rem;height:7rem}.sd-avatar-xl{border-radius:50%;object-fit:cover;object-position:center;width:10rem;height:10rem}.sd-avatar-inherit{border-radius:50%;object-fit:cover;object-position:center;width:inherit;height:inherit}.sd-avatar-initial{border-radius:50%;object-fit:cover;object-position:center;width:initial;height:initial}.sd-card{background-clip:border-box;background-color:var(--sd-color-card-background);border:1px solid var(--sd-color-card-border);border-radius:.25rem;color:var(--sd-color-card-text);display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;min-width:0;position:relative;word-wrap:break-word}.sd-card>hr{margin-left:0;margin-right:0}.sd-card-hover:hover{border-color:var(--sd-color-card-border-hover);transform:scale(1.01)}.sd-card-body{-ms-flex:1 1 auto;flex:1 1 auto;padding:1rem 1rem}.sd-card-title{margin-bottom:.5rem}.sd-card-subtitle{margin-top:-0.25rem;margin-bottom:0}.sd-card-text:last-child{margin-bottom:0}.sd-card-link:hover{text-decoration:none}.sd-card-link+.card-link{margin-left:1rem}.sd-card-header{padding:.5rem 1rem;margin-bottom:0;background-color:var(--sd-color-card-header);border-bottom:1px solid var(--sd-color-card-border)}.sd-card-header:first-child{border-radius:calc(0.25rem - 1px) calc(0.25rem - 1px) 0 0}.sd-card-footer{padding:.5rem 1rem;background-color:var(--sd-color-card-footer);border-top:1px solid var(--sd-color-card-border)}.sd-card-footer:last-child{border-radius:0 0 calc(0.25rem - 1px) calc(0.25rem - 1px)}.sd-card-header-tabs{margin-right:-0.5rem;margin-bottom:-0.5rem;margin-left:-0.5rem;border-bottom:0}.sd-card-header-pills{margin-right:-0.5rem;margin-left:-0.5rem}.sd-card-img-overlay{position:absolute;top:0;right:0;bottom:0;left:0;padding:1rem;border-radius:calc(0.25rem - 1px)}.sd-card-img,.sd-card-img-bottom,.sd-card-img-top{width:100%}.sd-card-img,.sd-card-img-top{border-top-left-radius:calc(0.25rem - 1px);border-top-right-radius:calc(0.25rem - 1px)}.sd-card-img,.sd-card-img-bottom{border-bottom-left-radius:calc(0.25rem - 1px);border-bottom-right-radius:calc(0.25rem - 1px)}.sd-cards-carousel{width:100%;display:flex;flex-wrap:nowrap;-ms-flex-direction:row;flex-direction:row;overflow-x:hidden;scroll-snap-type:x mandatory}.sd-cards-carousel.sd-show-scrollbar{overflow-x:auto}.sd-cards-carousel:hover,.sd-cards-carousel:focus{overflow-x:auto}.sd-cards-carousel>.sd-card{flex-shrink:0;scroll-snap-align:start}.sd-cards-carousel>.sd-card:not(:last-child){margin-right:3px}.sd-card-cols-1>.sd-card{width:90%}.sd-card-cols-2>.sd-card{width:45%}.sd-card-cols-3>.sd-card{width:30%}.sd-card-cols-4>.sd-card{width:22.5%}.sd-card-cols-5>.sd-card{width:18%}.sd-card-cols-6>.sd-card{width:15%}.sd-card-cols-7>.sd-card{width:12.8571428571%}.sd-card-cols-8>.sd-card{width:11.25%}.sd-card-cols-9>.sd-card{width:10%}.sd-card-cols-10>.sd-card{width:9%}.sd-card-cols-11>.sd-card{width:8.1818181818%}.sd-card-cols-12>.sd-card{width:7.5%}.sd-container,.sd-container-fluid,.sd-container-lg,.sd-container-md,.sd-container-sm,.sd-container-xl{margin-left:auto;margin-right:auto;padding-left:var(--sd-gutter-x, 0.75rem);padding-right:var(--sd-gutter-x, 0.75rem);width:100%}@media(min-width: 576px){.sd-container-sm,.sd-container{max-width:540px}}@media(min-width: 768px){.sd-container-md,.sd-container-sm,.sd-container{max-width:720px}}@media(min-width: 992px){.sd-container-lg,.sd-container-md,.sd-container-sm,.sd-container{max-width:960px}}@media(min-width: 1200px){.sd-container-xl,.sd-container-lg,.sd-container-md,.sd-container-sm,.sd-container{max-width:1140px}}.sd-row{--sd-gutter-x: 1.5rem;--sd-gutter-y: 0;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;margin-top:calc(var(--sd-gutter-y) * -1);margin-right:calc(var(--sd-gutter-x) * -0.5);margin-left:calc(var(--sd-gutter-x) * -0.5)}.sd-row>*{box-sizing:border-box;flex-shrink:0;width:100%;max-width:100%;padding-right:calc(var(--sd-gutter-x) * 0.5);padding-left:calc(var(--sd-gutter-x) * 0.5);margin-top:var(--sd-gutter-y)}.sd-col{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-auto>*{flex:0 0 auto;width:auto}.sd-row-cols-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}@media(min-width: 576px){.sd-col-sm{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-sm-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-sm-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-sm-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-sm-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-sm-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-sm-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-sm-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-sm-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-sm-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-sm-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-sm-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-sm-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-sm-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}@media(min-width: 768px){.sd-col-md{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-md-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-md-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-md-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-md-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-md-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-md-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-md-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-md-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-md-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-md-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-md-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-md-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-md-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}@media(min-width: 992px){.sd-col-lg{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-lg-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-lg-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-lg-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-lg-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-lg-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-lg-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-lg-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-lg-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-lg-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-lg-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-lg-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-lg-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-lg-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}@media(min-width: 1200px){.sd-col-xl{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-xl-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-xl-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-xl-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-xl-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-xl-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-xl-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-xl-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-xl-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-xl-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-xl-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-xl-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-xl-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-xl-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}.sd-col-auto{flex:0 0 auto;-ms-flex:0 0 auto;width:auto}.sd-col-1{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}.sd-col-2{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-col-3{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-col-4{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-col-5{flex:0 0 auto;-ms-flex:0 0 auto;width:41.6666666667%}.sd-col-6{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-col-7{flex:0 0 auto;-ms-flex:0 0 auto;width:58.3333333333%}.sd-col-8{flex:0 0 auto;-ms-flex:0 0 auto;width:66.6666666667%}.sd-col-9{flex:0 0 auto;-ms-flex:0 0 auto;width:75%}.sd-col-10{flex:0 0 auto;-ms-flex:0 0 auto;width:83.3333333333%}.sd-col-11{flex:0 0 auto;-ms-flex:0 0 auto;width:91.6666666667%}.sd-col-12{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-g-0,.sd-gy-0{--sd-gutter-y: 0}.sd-g-0,.sd-gx-0{--sd-gutter-x: 0}.sd-g-1,.sd-gy-1{--sd-gutter-y: 0.25rem}.sd-g-1,.sd-gx-1{--sd-gutter-x: 0.25rem}.sd-g-2,.sd-gy-2{--sd-gutter-y: 0.5rem}.sd-g-2,.sd-gx-2{--sd-gutter-x: 0.5rem}.sd-g-3,.sd-gy-3{--sd-gutter-y: 1rem}.sd-g-3,.sd-gx-3{--sd-gutter-x: 1rem}.sd-g-4,.sd-gy-4{--sd-gutter-y: 1.5rem}.sd-g-4,.sd-gx-4{--sd-gutter-x: 1.5rem}.sd-g-5,.sd-gy-5{--sd-gutter-y: 3rem}.sd-g-5,.sd-gx-5{--sd-gutter-x: 3rem}@media(min-width: 576px){.sd-col-sm-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-sm-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-sm-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-sm-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-sm-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-sm-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-sm-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-sm-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-sm-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-sm-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-sm-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-sm-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-sm-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-sm-0,.sd-gy-sm-0{--sd-gutter-y: 0}.sd-g-sm-0,.sd-gx-sm-0{--sd-gutter-x: 0}.sd-g-sm-1,.sd-gy-sm-1{--sd-gutter-y: 0.25rem}.sd-g-sm-1,.sd-gx-sm-1{--sd-gutter-x: 0.25rem}.sd-g-sm-2,.sd-gy-sm-2{--sd-gutter-y: 0.5rem}.sd-g-sm-2,.sd-gx-sm-2{--sd-gutter-x: 0.5rem}.sd-g-sm-3,.sd-gy-sm-3{--sd-gutter-y: 1rem}.sd-g-sm-3,.sd-gx-sm-3{--sd-gutter-x: 1rem}.sd-g-sm-4,.sd-gy-sm-4{--sd-gutter-y: 1.5rem}.sd-g-sm-4,.sd-gx-sm-4{--sd-gutter-x: 1.5rem}.sd-g-sm-5,.sd-gy-sm-5{--sd-gutter-y: 3rem}.sd-g-sm-5,.sd-gx-sm-5{--sd-gutter-x: 3rem}}@media(min-width: 768px){.sd-col-md-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-md-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-md-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-md-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-md-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-md-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-md-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-md-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-md-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-md-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-md-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-md-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-md-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-md-0,.sd-gy-md-0{--sd-gutter-y: 0}.sd-g-md-0,.sd-gx-md-0{--sd-gutter-x: 0}.sd-g-md-1,.sd-gy-md-1{--sd-gutter-y: 0.25rem}.sd-g-md-1,.sd-gx-md-1{--sd-gutter-x: 0.25rem}.sd-g-md-2,.sd-gy-md-2{--sd-gutter-y: 0.5rem}.sd-g-md-2,.sd-gx-md-2{--sd-gutter-x: 0.5rem}.sd-g-md-3,.sd-gy-md-3{--sd-gutter-y: 1rem}.sd-g-md-3,.sd-gx-md-3{--sd-gutter-x: 1rem}.sd-g-md-4,.sd-gy-md-4{--sd-gutter-y: 1.5rem}.sd-g-md-4,.sd-gx-md-4{--sd-gutter-x: 1.5rem}.sd-g-md-5,.sd-gy-md-5{--sd-gutter-y: 3rem}.sd-g-md-5,.sd-gx-md-5{--sd-gutter-x: 3rem}}@media(min-width: 992px){.sd-col-lg-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-lg-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-lg-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-lg-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-lg-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-lg-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-lg-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-lg-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-lg-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-lg-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-lg-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-lg-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-lg-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-lg-0,.sd-gy-lg-0{--sd-gutter-y: 0}.sd-g-lg-0,.sd-gx-lg-0{--sd-gutter-x: 0}.sd-g-lg-1,.sd-gy-lg-1{--sd-gutter-y: 0.25rem}.sd-g-lg-1,.sd-gx-lg-1{--sd-gutter-x: 0.25rem}.sd-g-lg-2,.sd-gy-lg-2{--sd-gutter-y: 0.5rem}.sd-g-lg-2,.sd-gx-lg-2{--sd-gutter-x: 0.5rem}.sd-g-lg-3,.sd-gy-lg-3{--sd-gutter-y: 1rem}.sd-g-lg-3,.sd-gx-lg-3{--sd-gutter-x: 1rem}.sd-g-lg-4,.sd-gy-lg-4{--sd-gutter-y: 1.5rem}.sd-g-lg-4,.sd-gx-lg-4{--sd-gutter-x: 1.5rem}.sd-g-lg-5,.sd-gy-lg-5{--sd-gutter-y: 3rem}.sd-g-lg-5,.sd-gx-lg-5{--sd-gutter-x: 3rem}}@media(min-width: 1200px){.sd-col-xl-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-xl-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-xl-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-xl-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-xl-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-xl-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-xl-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-xl-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-xl-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-xl-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-xl-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-xl-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-xl-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-xl-0,.sd-gy-xl-0{--sd-gutter-y: 0}.sd-g-xl-0,.sd-gx-xl-0{--sd-gutter-x: 0}.sd-g-xl-1,.sd-gy-xl-1{--sd-gutter-y: 0.25rem}.sd-g-xl-1,.sd-gx-xl-1{--sd-gutter-x: 0.25rem}.sd-g-xl-2,.sd-gy-xl-2{--sd-gutter-y: 0.5rem}.sd-g-xl-2,.sd-gx-xl-2{--sd-gutter-x: 0.5rem}.sd-g-xl-3,.sd-gy-xl-3{--sd-gutter-y: 1rem}.sd-g-xl-3,.sd-gx-xl-3{--sd-gutter-x: 1rem}.sd-g-xl-4,.sd-gy-xl-4{--sd-gutter-y: 1.5rem}.sd-g-xl-4,.sd-gx-xl-4{--sd-gutter-x: 1.5rem}.sd-g-xl-5,.sd-gy-xl-5{--sd-gutter-y: 3rem}.sd-g-xl-5,.sd-gx-xl-5{--sd-gutter-x: 3rem}}.sd-flex-row-reverse{flex-direction:row-reverse !important}details.sd-dropdown{position:relative;font-size:var(--sd-fontsize-dropdown)}details.sd-dropdown:hover{cursor:pointer}details.sd-dropdown .sd-summary-content{cursor:default}details.sd-dropdown summary.sd-summary-title{padding:.5em .6em .5em 1em;font-size:var(--sd-fontsize-dropdown-title);font-weight:var(--sd-fontweight-dropdown-title);user-select:none;-moz-user-select:none;-ms-user-select:none;-webkit-user-select:none;list-style:none;display:inline-flex;justify-content:space-between}details.sd-dropdown summary.sd-summary-title::-webkit-details-marker{display:none}details.sd-dropdown summary.sd-summary-title:focus{outline:none}details.sd-dropdown summary.sd-summary-title .sd-summary-icon{margin-right:.6em;display:inline-flex;align-items:center}details.sd-dropdown summary.sd-summary-title .sd-summary-icon svg{opacity:.8}details.sd-dropdown summary.sd-summary-title .sd-summary-text{flex-grow:1;line-height:1.5;padding-right:.5rem}details.sd-dropdown summary.sd-summary-title .sd-summary-state-marker{pointer-events:none;display:inline-flex;align-items:center}details.sd-dropdown summary.sd-summary-title .sd-summary-state-marker svg{opacity:.6}details.sd-dropdown summary.sd-summary-title:hover .sd-summary-state-marker svg{opacity:1;transform:scale(1.1)}details.sd-dropdown[open] summary .sd-octicon.no-title{visibility:hidden}details.sd-dropdown .sd-summary-chevron-right{transition:.25s}details.sd-dropdown[open]>.sd-summary-title .sd-summary-chevron-right{transform:rotate(90deg)}details.sd-dropdown[open]>.sd-summary-title .sd-summary-chevron-down{transform:rotate(180deg)}details.sd-dropdown:not([open]).sd-card{border:none}details.sd-dropdown:not([open])>.sd-card-header{border:1px solid var(--sd-color-card-border);border-radius:.25rem}details.sd-dropdown.sd-fade-in[open] summary~*{-moz-animation:sd-fade-in .5s ease-in-out;-webkit-animation:sd-fade-in .5s ease-in-out;animation:sd-fade-in .5s ease-in-out}details.sd-dropdown.sd-fade-in-slide-down[open] summary~*{-moz-animation:sd-fade-in .5s ease-in-out,sd-slide-down .5s ease-in-out;-webkit-animation:sd-fade-in .5s ease-in-out,sd-slide-down .5s ease-in-out;animation:sd-fade-in .5s ease-in-out,sd-slide-down .5s ease-in-out}.sd-col>.sd-dropdown{width:100%}.sd-summary-content>.sd-tab-set:first-child{margin-top:0}@keyframes sd-fade-in{0%{opacity:0}100%{opacity:1}}@keyframes sd-slide-down{0%{transform:translate(0, -10px)}100%{transform:translate(0, 0)}}.sd-tab-set{border-radius:.125rem;display:flex;flex-wrap:wrap;margin:1em 0;position:relative}.sd-tab-set>input{opacity:0;position:absolute}.sd-tab-set>input:checked+label{border-color:var(--sd-color-tabs-underline-active);color:var(--sd-color-tabs-label-active)}.sd-tab-set>input:checked+label+.sd-tab-content{display:block}.sd-tab-set>input:not(:checked)+label:hover{color:var(--sd-color-tabs-label-hover);border-color:var(--sd-color-tabs-underline-hover)}.sd-tab-set>input:focus+label{outline-style:auto}.sd-tab-set>input:not(.focus-visible)+label{outline:none;-webkit-tap-highlight-color:transparent}.sd-tab-set>label{border-bottom:.125rem solid transparent;margin-bottom:0;color:var(--sd-color-tabs-label-inactive);border-color:var(--sd-color-tabs-underline-inactive);cursor:pointer;font-size:var(--sd-fontsize-tabs-label);font-weight:700;padding:1em 1.25em .5em;transition:color 250ms;width:auto;z-index:1}html .sd-tab-set>label:hover{color:var(--sd-color-tabs-label-active)}.sd-col>.sd-tab-set{width:100%}.sd-tab-content{box-shadow:0 -0.0625rem var(--sd-color-tabs-overline),0 .0625rem var(--sd-color-tabs-underline);display:none;order:99;padding-bottom:.75rem;padding-top:.75rem;width:100%}.sd-tab-content>:first-child{margin-top:0 !important}.sd-tab-content>:last-child{margin-bottom:0 !important}.sd-tab-content>.sd-tab-set{margin:0}.sd-sphinx-override,.sd-sphinx-override *{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}.sd-sphinx-override p{margin-top:0}:root{--sd-color-primary: #0071bc;--sd-color-secondary: #6c757d;--sd-color-success: #28a745;--sd-color-info: #17a2b8;--sd-color-warning: #f0b37e;--sd-color-danger: #dc3545;--sd-color-light: #f8f9fa;--sd-color-muted: #6c757d;--sd-color-dark: #212529;--sd-color-black: black;--sd-color-white: white;--sd-color-primary-highlight: #0060a0;--sd-color-secondary-highlight: #5c636a;--sd-color-success-highlight: #228e3b;--sd-color-info-highlight: #148a9c;--sd-color-warning-highlight: #cc986b;--sd-color-danger-highlight: #bb2d3b;--sd-color-light-highlight: #d3d4d5;--sd-color-muted-highlight: #5c636a;--sd-color-dark-highlight: #1c1f23;--sd-color-black-highlight: black;--sd-color-white-highlight: #d9d9d9;--sd-color-primary-bg: rgba(0, 113, 188, 0.2);--sd-color-secondary-bg: rgba(108, 117, 125, 0.2);--sd-color-success-bg: rgba(40, 167, 69, 0.2);--sd-color-info-bg: rgba(23, 162, 184, 0.2);--sd-color-warning-bg: rgba(240, 179, 126, 0.2);--sd-color-danger-bg: rgba(220, 53, 69, 0.2);--sd-color-light-bg: rgba(248, 249, 250, 0.2);--sd-color-muted-bg: rgba(108, 117, 125, 0.2);--sd-color-dark-bg: rgba(33, 37, 41, 0.2);--sd-color-black-bg: rgba(0, 0, 0, 0.2);--sd-color-white-bg: rgba(255, 255, 255, 0.2);--sd-color-primary-text: #fff;--sd-color-secondary-text: #fff;--sd-color-success-text: #fff;--sd-color-info-text: #fff;--sd-color-warning-text: #212529;--sd-color-danger-text: #fff;--sd-color-light-text: #212529;--sd-color-muted-text: #fff;--sd-color-dark-text: #fff;--sd-color-black-text: #fff;--sd-color-white-text: #212529;--sd-color-shadow: rgba(0, 0, 0, 0.15);--sd-color-card-border: rgba(0, 0, 0, 0.125);--sd-color-card-border-hover: hsla(231, 99%, 66%, 1);--sd-color-card-background: transparent;--sd-color-card-text: inherit;--sd-color-card-header: transparent;--sd-color-card-footer: transparent;--sd-color-tabs-label-active: hsla(231, 99%, 66%, 1);--sd-color-tabs-label-hover: hsla(231, 99%, 66%, 1);--sd-color-tabs-label-inactive: hsl(0, 0%, 66%);--sd-color-tabs-underline-active: hsla(231, 99%, 66%, 1);--sd-color-tabs-underline-hover: rgba(178, 206, 245, 0.62);--sd-color-tabs-underline-inactive: transparent;--sd-color-tabs-overline: rgb(222, 222, 222);--sd-color-tabs-underline: rgb(222, 222, 222);--sd-fontsize-tabs-label: 1rem;--sd-fontsize-dropdown: inherit;--sd-fontsize-dropdown-title: 1rem;--sd-fontweight-dropdown-title: 700} diff --git a/docs/fern/docs.yml b/docs/fern/docs.yml new file mode 100644 index 000000000..3eb699e7f --- /dev/null +++ b/docs/fern/docs.yml @@ -0,0 +1,7 @@ +# Generated by sphinx-fern-builder. Customize as needed. +instances: + - url: your-org.docs.buildwithfern.com/your-project +title: "Nemotron" +versions: + - display-name: vnightly + path: ./versions/vnightly.yml diff --git a/docs/fern/fern.config.json b/docs/fern/fern.config.json new file mode 100644 index 000000000..44aa75f72 --- /dev/null +++ b/docs/fern/fern.config.json @@ -0,0 +1,4 @@ +{ + "organization": "NVIDIA Corporation", + "version": "4.34.1" +} diff --git a/docs/nemotron/rerank/README.md b/docs/fern/pages-nightly/nemotron/rerank/README.mdx similarity index 92% rename from docs/nemotron/rerank/README.md rename to docs/fern/pages-nightly/nemotron/rerank/README.mdx index b3a31cd1f..77f2e9aee 100644 --- a/docs/nemotron/rerank/README.md +++ b/docs/fern/pages-nightly/nemotron/rerank/README.mdx @@ -1,23 +1,29 @@ -# Reranking Model Fine-Tuning Recipe +--- +title: "Reranking Model Fine-Tuning Recipe" +slug: "nemotron/rerank/README.html" +description: "A complete 6-stage pipeline for fine-tuning and deploying cross-encoder reranking models on domain-specific data using synthetic data generation." +--- A complete 6-stage pipeline for fine-tuning and deploying cross-encoder reranking models on domain-specific data using synthetic data generation. ## Overview -This recipe fine-tunes NVIDIA's [Llama-Nemotron-Rerank-1B-v2](https://huggingface.co/nvidia/llama-nemotron-rerank-1b-v2) cross-encoder reranking model on your own domain data. By the end of this pipeline, you'll have a domain-adapted reranker that improves retrieval precision by re-scoring candidate documents returned by a first-stage retriever. +This recipe fine-tunes NVIDIA’s [Llama-Nemotron-Rerank-1B-v2](https://huggingface.co/nvidia/llama-nemotron-rerank-1b-v2) cross-encoder reranking model on your own domain data. By the end of this pipeline, you’ll have a domain-adapted reranker that improves retrieval precision by re-scoring candidate documents returned by a first-stage retriever. ### Why Fine-Tune Reranking Models? In a typical retrieval pipeline, a fast embedding model retrieves a broad set of candidate documents, then a cross-encoder reranker re-scores each query–document pair to improve ranking quality. Fine-tuning the reranker adapts it to: - Understand domain-specific relevance signals and terminology + - Better discriminate between subtly relevant and irrelevant documents + - Improve precision at the top of the ranked list (nDCG@k) on your specific corpus ### Embedding vs. Reranking | Aspect | Embedding Model | Reranking Model | -|--------|----------------|-----------------| +| --- | --- | --- | | **Architecture** | Bi-encoder (encodes query and document separately) | Cross-encoder (encodes query and document together) | | **Speed** | Fast (single encoding per document, offline indexable) | Slower (joint encoding per query–document pair) | | **Accuracy** | Good for broad recall | Higher precision at top ranks | @@ -27,7 +33,7 @@ The two models are complementary — use the embedding model to cast a wide net, ## Training Pipeline -``` +```default ┌─────────────────────────────────────────────────────────────────────────────┐ │ YOUR DOCUMENT CORPUS │ │ (Text files: .txt, .md, etc.) │ @@ -85,13 +91,13 @@ The two models are complementary — use the embedding model to cast a wide net, ``` | Stage | Command | Description | Output | -|-------|---------|-------------|--------| -| Stage 0: SDG | `nemotron rerank sdg` | Validate corpus, generate synthetic Q&A pairs from documents | Q&A pairs with quality scores | -| Stage 1: Data Prep | `nemotron rerank prep` | Convert, mine hard negatives, unroll | Training-ready data | -| Stage 2: Finetune | `nemotron rerank finetune` | Fine-tune cross-encoder reranking model | Model checkpoint | -| Stage 3: Eval | `nemotron rerank eval` | Evaluate reranking improvement over first-stage retrieval | Metrics comparison | -| Stage 4: Export | `nemotron rerank export` | Export to ONNX/TensorRT | Optimized inference models | -| Stage 5: Deploy | `nemotron rerank deploy` | Deploy NIM ranking service | Running inference service | +| --- | --- | --- | --- | +| Stage 0: SDG | nemotron rerank sdg | Validate corpus, generate synthetic Q&A pairs from documents | Q&A pairs with quality scores | +| Stage 1: Data Prep | nemotron rerank prep | Convert, mine hard negatives, unroll | Training-ready data | +| Stage 2: Finetune | nemotron rerank finetune | Fine-tune cross-encoder reranking model | Model checkpoint | +| Stage 3: Eval | nemotron rerank eval | Evaluate reranking improvement over first-stage retrieval | Metrics comparison | +| Stage 4: Export | nemotron rerank export | Export to ONNX/TensorRT | Optimized inference models | +| Stage 5: Deploy | nemotron rerank deploy | Deploy NIM ranking service | Running inference service | ## Installation @@ -116,10 +122,12 @@ uv sync --all-extras ### 3. Get Your NVIDIA API Key -The SDG stage (Stage 0) uses NVIDIA's hosted LLM APIs for synthetic data generation. +The SDG stage (Stage 0) uses NVIDIA’s hosted LLM APIs for synthetic data generation. 1. Sign up at [build.nvidia.com](https://build.nvidia.com) + 2. Create an API key + 3. Set the environment variable: ```bash @@ -131,6 +139,7 @@ export NVIDIA_API_KEY=nvapi-your_key_here For Docker or Slurm execution, create `env.toml` in the **repository root directory**. **Minimal configuration (local execution only):** + ```toml [wandb] project = "my-reranking-project" @@ -145,13 +154,15 @@ See the [Execution Profiles](#execution-profiles) section below. ### Supported Formats - Any text files, default: .txt, .md, .text, and files with no extension + - Documents should be UTF-8 encoded + - Files are processed recursively from the corpus directory ### Corpus Size Recommendations | Corpus Size | Documents | Expected Results | -|-------------|-----------|------------------| +| --- | --- | --- | | **Minimum** | 50-100 docs (~50K tokens) | Basic domain adaptation | | **Recommended** | 500+ docs | Good domain coverage | | **Optimal** | 1000+ docs | Best performance | @@ -175,26 +186,37 @@ All files matching the `file_extensions` config (default: `.txt,.md,.text,` plus ### Hardware Requirements - **GPU**: NVIDIA GPU with at least 80GB VRAM (e.g., A100, H100) - - Stage 0 uses NVIDIA API (no GPU required) - - Stages 1-5: Require GPU for model inference and training + + - Stage 0 uses NVIDIA API (no GPU required) + + - Stages 1-5: Require GPU for model inference and training + - **CPU**: Modern multi-core processor (16+ cores recommended) + - **Memory**: 128GB+ RAM recommended + - **Storage**: ~50GB free disk space for outputs, models, and containers ### Software Requirements - **Python**: 3.12 or later + - **UV**: Package manager (installation instructions above) + - **NVIDIA API Key**: Required for synthetic data generation + - **NGC API Key**: Required for authenticated NIM deployment + - **NVIDIA GPU Drivers**: Latest drivers for your GPU + - **Docker** (optional): For containerized execution or NIM deployment + - **Slurm** (optional): For cluster execution ### Expected Runtime & Resources | Stage | GPU VRAM | CPU | Notes | -|-------|----------|-----|-------| +| --- | --- | --- | --- | | Stage 0 (SDG) | N/A | 8+ cores | Uses API (no local GPU); runtime varies by dataset size | | Stage 1 (Data Prep) | 40GB | 16+ cores | Hard negative mining on GPU; runtime varies by dataset size | | Stage 2 (Finetune) | 80GB | 16+ cores | Runtime varies by dataset size and epochs | @@ -204,11 +226,14 @@ All files matching the `file_extensions` config (default: `.txt,.md,.text,` plus ### LLM API Usage (Stage 0) -Stage 0 uses LLM APIs for synthetic data generation. By default, it uses NVIDIA's hosted LLMs: +Stage 0 uses LLM APIs for synthetic data generation. By default, it uses NVIDIA’s hosted LLMs: - **Default provider**: NVIDIA API (free tier available at [build.nvidia.com](https://build.nvidia.com)) + - **Default model**: `nvidia/nemotron-3-nano-30b-a3b` (fast, reliable for structured generation) + - **Usage**: ~4 API calls per document (artifact extraction, QA generation, dedup, quality eval) + - **Cost**: Free tier has rate limits; contact NVIDIA for production usage ## Quick Start @@ -257,9 +282,9 @@ nemotron rerank finetune -c default --dry-run Stages are designed to run sequentially, but you can start from any stage if you have the required inputs: | Start From | Requirement | Use Case | -|------------|-------------|----------| +| --- | --- | --- | | **Stage 0** | Document corpus | Full pipeline from scratch | -| **Stage 1** | Q&A pairs (JSON) | Skip SDG if you have labeled data or use [NVIDIA's pre-generated dataset](#using-nvidias-pre-generated-dataset) | +| **Stage 1** | Q&A pairs (JSON) | Skip SDG if you have labeled data or use [NVIDIA’s pre-generated dataset](#using-nvidia-s-pre-generated-dataset) | | **Stage 2** | Training data (Automodel format) | Skip data prep if data is ready | | **Stage 3** | Model checkpoint | Evaluate existing checkpoint | | **Stage 4** | Model checkpoint | Export existing model | @@ -267,9 +292,9 @@ Stages are designed to run sequentially, but you can start from any stage if you See individual stage configs for input format requirements. -### Using NVIDIA's Pre-Generated Dataset +### Using NVIDIA’s Pre-Generated Dataset -NVIDIA provides a ready-to-use synthetic retrieval dataset on Hugging Face: [Retrieval-Synthetic-NVDocs-v1](https://huggingface.co/datasets/nvidia/Retrieval-Synthetic-NVDocs-v1). This dataset was generated from NVIDIA's publicly available content using the same SDG pipeline (Stage 0) in this recipe, and contains ~15K documents with 105K+ question-answer pairs across multiple reasoning types. +NVIDIA provides a ready-to-use synthetic retrieval dataset on Hugging Face: [Retrieval-Synthetic-NVDocs-v1](https://huggingface.co/datasets/nvidia/Retrieval-Synthetic-NVDocs-v1). This dataset was generated from NVIDIA’s publicly available content using the same SDG pipeline (Stage 0) in this recipe, and contains ~15K documents with 105K+ question-answer pairs across multiple reasoning types. If you want to fine-tune a reranking model on NVIDIA-related content, you can **skip Stage 0 entirely** and start directly from Stage 1: @@ -409,14 +434,15 @@ Rerank cluster execution requires a profile with `remote_job_dir` or `env_vars.N Each stage has a `config/` directory with YAML configuration files. | File | Purpose | -|------|---------| -| `default.yaml` | Production-ready configuration | +| --- | --- | +| default.yaml | Production-ready configuration | ### Key Configuration Options The default config points at a small pinned sample corpus. For your own corpus, override the Stage 0 paths: **Stage 0: SDG** + ```yaml corpus_id: my_corpus # Identifier for your corpus corpus_dir: ./data/corpus # Path to your documents @@ -428,6 +454,7 @@ quality_judge_model: nvidia/nemotron-3-nano-30b-a3b # LLM for QA quality ``` **Stage 1: Data Prep** + ```yaml base_model: nvidia/llama-nemotron-embed-1b-v2 # Embedding model for hard negative mining quality_threshold: 7.0 # Minimum Q&A quality score (0-10) @@ -440,6 +467,7 @@ test_ratio: 0.2 # Test split (20%) ``` **Stage 2: Finetune** + ```yaml base_model: nvidia/llama-nemotron-rerank-1b-v2 num_epochs: 3 @@ -451,7 +479,7 @@ weight_decay: 0.01 optimizer_backend: auto # FusedAdam in the container, FlashAdamW locally without TE flash_adamw_master_weight_bits: 32 # Effective master-weight precision for FlashAdamW rerank_max_length: 512 # Max tokens for concatenated query+passage -prompt_template: "question:{query} \n \n passage:{passage}" +prompt_template: "question:\{query\} \n \n passage:\{passage\}" train_n_passages: 5 # 1 positive + 4 hard negatives num_labels: 1 temperature: 1.0 @@ -460,6 +488,7 @@ temperature: 1.0 > **Warning — Overfitting risk**: The default `num_epochs: 3` is set for the small example dataset shipped with this recipe, where fewer epochs may not produce a visible training signal. For most real-world datasets, **1–2 epochs is sufficient** and 3 epochs carries a high risk of overfitting. Lower this value when working with your own data (e.g., `nemotron rerank finetune -c default num_epochs=1`). **Stage 3: Eval** + ```yaml base_model: nvidia/llama-nemotron-rerank-1b-v2 # Base reranker for comparison retrieval_model: nvidia/llama-nemotron-embed-1b-v2 # First-stage retriever @@ -472,17 +501,19 @@ eval_nim: false # Evaluate NIM endpoint ``` **Stage 4: Export** + ```yaml model_path: ./output/rerank/stage2_finetune/checkpoints/LATEST/model/consolidated export_to_trt: false # Export to TensorRT (requires nemo:25.07+ container) quant_cfg: null # Quantization: null, "fp8", "int8_sq" calibration_query: what information is relevant to this query? -prompt_template: "question:{query} \n \n passage:{passage}" +prompt_template: "question:\{query\} \n \n passage:\{passage\}" trt_opt_batch: 16 # Optimal batch size for TRT trt_opt_seq_len: 256 # Optimal sequence length for TRT ``` **Stage 5: Deploy** + ```yaml nim_image: nvcr.io/nim/nvidia/llama-nemotron-rerank-1b-v2:1.10.0 model_dir: ./output/rerank/stage4_export/onnx # ONNX or TensorRT export directory @@ -607,7 +638,7 @@ curl -X POST http://localhost:8000/v1/ranking \ After running the full pipeline: -``` +```default output/rerank/ ├── stage0_sdg/ # Synthetic Q&A pairs │ └── generated_batch*.json @@ -634,7 +665,7 @@ output/rerank/ The evaluation stage measures reranking quality using a two-stage approach: first-stage dense retrieval followed by cross-encoder re-ranking. This mirrors how rerankers are used in production. | Metric | Description | Range | -|--------|-------------|-------| +| --- | --- | --- | | **nDCG@k** | Normalized Discounted Cumulative Gain (ranking quality) | 0.0-1.0 | | **Recall@k** | Fraction of relevant documents in top-k results | 0.0-1.0 | | **Precision@k** | Fraction of retrieved documents that are relevant | 0.0-1.0 | @@ -642,11 +673,10 @@ The evaluation stage measures reranking quality using a two-stage approach: firs Higher scores indicate better re-ranking performance. The key metric to watch is **nDCG@10**, which captures how well the reranker promotes relevant documents to the top of the list. - ## Key Components | Component | Purpose | Repository | -|-----------|---------|------------| +| --- | --- | --- | | retriever-sdg | Synthetic data generation using NeMo Data Designer | [GitHub](https://github.com/NVIDIA-NeMo/DataDesigner) | | Automodel | Cross-encoder model training framework | [GitHub](https://github.com/NVIDIA-NeMo/Automodel) | | BEIR | Evaluation framework for information retrieval | [GitHub](https://github.com/beir-cellar/beir) | @@ -656,7 +686,7 @@ Higher scores indicate better re-ranking performance. The key metric to watch is ## Base Model | Property | Value | -|----------|-------| +| --- | --- | | Model | nvidia/llama-nemotron-rerank-1b-v2 | | Parameters | ~1B | | Architecture | Cross-encoder (sequence classification) | @@ -667,15 +697,23 @@ Higher scores indicate better re-ranking performance. The key metric to watch is ## Further Reading - [NeMo Data Designer Documentation](https://github.com/NVIDIA-NeMo/DataDesigner) - Synthetic data generation framework + - [Automodel Documentation](https://github.com/NVIDIA-NeMo/Automodel) - Model training framework + - [BEIR Benchmark](https://github.com/beir-cellar/beir) - Information retrieval evaluation + - [NVIDIA NIM Documentation](https://developer.nvidia.com/nim) - Production inference microservices + - [Llama-Nemotron-Rerank-1B-v2 Model Card](https://huggingface.co/nvidia/llama-nemotron-rerank-1b-v2) - Base model details + - [Retrieval-Synthetic-NVDocs-v1 Dataset](https://huggingface.co/datasets/nvidia/Retrieval-Synthetic-NVDocs-v1) - Pre-generated synthetic retrieval dataset ## Support For issues, questions, or contributions: + - **Issues**: [GitHub Issues](https://github.com/NVIDIA-NeMo/Nemotron/issues) + - **Discussions**: [GitHub Discussions](https://github.com/NVIDIA-NeMo/Nemotron/discussions) + - **Documentation**: [Nemotron Documentation](https://github.com/NVIDIA-NeMo/Nemotron) diff --git a/docs/fern/pages-v0.1.0/index.mdx b/docs/fern/pages-v0.1.0/index.mdx new file mode 100644 index 000000000..d7d9ebb1e --- /dev/null +++ b/docs/fern/pages-v0.1.0/index.mdx @@ -0,0 +1,98 @@ +--- +title: "Nemotron Training Recipes" +slug: "index.html" +description: "Open and efficient models for agentic AI. Reproducible training pipelines with transparent data, techniques, and weights." +--- + +**Open and efficient models for agentic AI.** Reproducible training pipelines with transparent data, techniques, and weights. + +
+ +
+## Quick Start + +
+```console +// Install the Nemotron training recipes +$ git clone https://github.com/NVIDIA/nemotron +$ cd nemotron && uv sync + +// Run the Nano3 pipeline stage by stage +$ uv run nemotron nano3 data prep pretrain --run YOUR-CLUSTER +$ uv run nemotron nano3 pretrain --run YOUR-CLUSTER +$ uv run nemotron nano3 data prep sft --run YOUR-CLUSTER +$ uv run nemotron nano3 sft --run YOUR-CLUSTER +$ uv run nemotron nano3 data prep rl --run YOUR-CLUSTER +$ uv run nemotron nano3 rl --run YOUR-CLUSTER +``` + +
+> **Note**: The `--run YOUR-CLUSTER` flag submits jobs to your configured Slurm cluster via [NeMo-Run](/nemo_runspec/nemo-run). See [Execution through NeMo-Run](/nemo_runspec/nemo-run) for setup instructions. + +## Usage Cookbook & Examples + + + +Deployment guides for Nemotron models: TensorRT-LLM, vLLM, SGLang, NIM, and Hugging Face. + + + + +End-to-end applications: RAG agents, ML agents, and multi-agent systems. + + + + + +## Available Training Recipes + + + +31.6B total / 3.6B active parameters, 25T tokens, up to 1M context. Hybrid Mamba-Transformer with sparse MoE. + +**Stages:** Pretraining → SFT → RL + + + + + +## Training Pipeline + +The Nemotron training pipeline has three stages, each tracked through [artifact lineage](/nemotron/artifacts): + +| Stage | Name | Description | +| --- | --- | --- | +| 0 | [Pretraining](/nemotron/nano3/pretrain) | Base model training on large text corpus | +| 1 | [SFT](/nemotron/nano3/sft) | Supervised fine-tuning for instruction following | +| 2 | [RL](/nemotron/nano3/rl) | Reinforcement learning for alignment | + +## Why Nemotron? + +| | | +| --- | --- | +| **Open Models** | Transparent training data, techniques, and weights for community innovation | +| **Compute Efficiency** | Model pruning enabling higher throughput via TensorRT-LLM | +| **High Accuracy** | Built on frontier open models with human-aligned reasoning | +| **Flexible Deployment** | Deploy anywhere: edge, single GPU, or data center with NIM | + +## Features + +- **End-to-end pipelines** from raw data to deployment-ready models + +- **[Artifact lineage](/nemotron/artifacts)** via [W&B](/nemotron/wandb) from data to model + +- **Built on [NVIDIA’s NeMo stack](/nemotron/nvidia-stack)** (Megatron-Bridge, NeMo-RL) + +- **Reproducible** with versioned configs, data blends, and checkpoints + +## Resources + +- [Tech Report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf) – Nemotron 3 Nano methodology + +- [Model Weights](https://huggingface.co/collections/nvidia/nvidia-nemotron-v3) – pre-trained checkpoints on HuggingFace + +- [Pre-training Datasets](https://huggingface.co/collections/nvidia/nemotron-pre-training-datasets) – open pre-training data + +- [Post-training Datasets](https://huggingface.co/collections/nvidia/nemotron-post-training-v3) – SFT and RL data + +- [Artifact Lineage](/nemotron/artifacts) – W&B integration guide diff --git a/docs/fern/pages-v0.1.0/usage-cookbook/Nemotron-3-Super/AdvancedDeploymentGuide/README.mdx b/docs/fern/pages-v0.1.0/usage-cookbook/Nemotron-3-Super/AdvancedDeploymentGuide/README.mdx new file mode 100644 index 000000000..44df40ea2 --- /dev/null +++ b/docs/fern/pages-v0.1.0/usage-cookbook/Nemotron-3-Super/AdvancedDeploymentGuide/README.mdx @@ -0,0 +1,273 @@ +--- +title: "Nemotron 3 Super — Advanced Deployment Guide" +slug: "usage-cookbook/Nemotron-3-Super/AdvancedDeploymentGuide/README.html" +description: "Three properties of Nemotron 3 Super that directly affect inference configuration:" +--- + +## Architecture Considerations + +Three properties of Nemotron 3 Super that directly affect inference configuration: + +**LatentMoE** — Expert computation happens in a compressed latent dimension (`d=4096 → ℓ=1024`). All-to-all routing traffic is reduced ~4× vs a standard MoE, which matters significantly for EP across NVLinks. Expert parallelism (`--enable-expert-parallel` / `--ep`) is strongly preferred over pure TP for this architecture. + +**MTP (Multi-Token Prediction)** — One MTP layer is baked into the checkpoint. This layer functions as a tail augmented draft model (similar to Eagle or other MTP heads) for speculative decoding. Unlike external draft models, additional KV cache and latency overhead is minimal as there is only a single layer called per predicted token. + +**Mamba-2 Hybrid** — SSM state cache (`mamba_ssm_cache`) is distinct from the KV cache. Use `float32` for all checkpoint precisions. + +## Pinned Versions + +| Framework | Pinned Version / Image | +| --- | --- | +| vLLM | 0.17.1 | +| SGLang | lmsysorg/sglang:v0.5.9 | +| TRT-LLM | nvcr.io/nvidia/tensorrt-llm/release:1.3.0rc5 | + +## vLLM + +### Install + +```bash +pip install vllm==0.17.1 +``` + +### Baseline Serve Command (4× GB200, 8k/64k) + +```bash +VLLM_FLASHINFER_MOE_BACKEND=latency \ +VLLM_USE_FLASHINFER_MOE_FP4=1 \ +VLLM_USE_FLASHINFER_MOE_FP8=1 \ +vllm serve $MODEL_CKPT \ + --tensor-parallel-size 4 \ + --trust-remote-code \ + --gpu-memory-utilization 0.9 \ + --enable-expert-parallel \ + --max-cudagraph-capture-size 512 \ + --reasoning-parser-plugin super_v3_reasoning_parser.py \ + --reasoning-parser super_v3 +``` + +### Env Vars + +| Variable | Value | Effect | +| --- | --- | --- | +| VLLM_FLASHINFER_MOE_BACKEND | latency | TRT-LLM Gen kernels — optimal for online/latency-bound serving. Use throughput (CUTLASS) for offline batch jobs. | +| VLLM_USE_FLASHINFER_MOE_FP4 | 1 | Enables NVFP4 MoE kernels. Blackwell only. | +| VLLM_USE_FLASHINFER_MOE_FP8 | 1 | Enables FP8 MoE kernels. | +| VLLM_FLASHINFER_ALLREDUCE_BACKEND | trtllm | Fixes allreduce on certain topologies. Fixed upstream in [#35793](https://github.com/vllm-project/vllm/pull/35793). | + +### MTP (Speculative Decoding) + +Add to the base command: + +```bash + --speculative-config '{"method": "nemotron_h_mtp", "num_speculative_tokens": 5}' +``` + +### Optional Flags Reference + +```bash +# Triton attention backend — required on some configurations. Fixed upstream in vllm#35219. +--attention-backend TRITON_ATTN + +# Reduce CUDA graph memory if headroom is tight (default 512) +--max-cudagraph-capture-size 256 + +# For unconstrained memory: prefer chunked prefill off +--no-enable-chunked-prefill # required for vLLM \<= 0.15.0 due to accuracy bug + +# SSM cache precision — float32 for all checkpoint precisions +--mamba-ssm-cache-dtype float32 + +# Cap context length for fair benchmarking or memory control +--max-model-len 65536 +``` + +## SGLang + +### Docker Pull + +```bash +docker pull lmsysorg/sglang:v0.5.9 +``` + +### Baseline Serve Command (4× GB200, 8k/64k) + +```bash +python3 -m sglang.launch_server \ + --model nvidia/NVIDIA-Nemotron-3-Super \ + --trust-remote-code \ + --tp 4 \ + --ep 4 \ + --tool-call-parser qwen3_coder \ + --reasoning-parser nano_v3 \ + --chunked-prefill-size 8192 +``` + +### MTP (Speculative Decoding) + +```bash + --speculative-algorithm EAGLE \ + --speculative-num-steps 5 \ + --speculative-eagle-topk 1 \ + --speculative-num-draft-tokens 5 +``` + +> **NVFP4/FP8 + MTP on v0.5.9**: MTP does not work with NVFP4/FP8 on the `v0.5.9` image. The fix is merged into SGLang main. Use the nightly image `nightly-dev-20260310-0fd9a57d` and add `--disable-radix-cache`. + +### SSM Cache + +```bash +--mamba-ssm-dtype float32 # use for all checkpoint precisions +``` + +Not required if baked into the checkpoint (which it is for released Nemotron 3 Super checkpoints). + +--- + +## TensorRT-LLM + +### Docker Pull + +> **Requires branch build**: These configs depend on changes not yet merged into the `1.3.0rc7` release [image](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/tensorrt-llm/containers/release?version=1.3.0rc7). Build TRT-LLM from `main` [branch](https://github.com/NVIDIA/TensorRT-LLM) before using these configs. + +TRT-LLM requires an `extra_llm_api_options` YAML for MoE backend, KV cache, and CUDA graph settings that can’t be passed as CLI flags. + +### Config A — NVFP4, 2× B200 (TEP2, Latency-Optimized) + +Optimal for a 2-GPU B200 node running NVFP4 with MTP enabled. + +**`y.yaml`** + +```yaml +trust_remote_code: true +kv_cache_config: + enable_block_reuse: false + free_gpu_memory_fraction: 0.8 + mamba_ssm_cache_dtype: float32 +speculative_config: + decoding_type: MTP + num_nextn_predict_layers: 3 + allow_advanced_sampling: true +cuda_graph_config: + max_batch_size: 16 + enable_padding: true +moe_config: + backend: TRTLLM +stream_interval: 1 +enable_chunked_prefill: true +``` + +**Serve command** + +```bash +mpirun -n 1 --allow-run-as-root --oversubscribe \ + trtllm-serve /data/super_fp4/ \ + --host 0.0.0.0 \ + --port 8000 \ + --max_batch_size 16 \ + --tp_size 2 \ + --ep_size 2 \ + --max_num_tokens 8192 \ + --max_seq_len 262144 \ + --extra_llm_api_options y.yaml +``` + +**Config rationale** + +- `max_batch_size: 16` — Conservative for 2 GPUs. Balances MTP draft acceptance overhead vs. throughput. + +- `tp_size 2 / ep_size 2` — Full EP across both GPUs. On LatentMoE, EP reduces all-to-all by ~4× vs TP at the same GPU count. + +- `mamba_ssm_cache_dtype: float32` — Use float32 for all checkpoint precisions. + +- `enable_block_reuse: false` — Mamba recurrent state is not prefix-cacheable; block reuse has no benefit here. + +- `num_nextn_predict_layers: 3` — Drives MTP with 3 speculative draft steps. Average acceptance length is 3.45 on SPEED-Bench at draft length 7. + +- `allow_advanced_sampling: true` — Required for MTP sampler compatibility. + +- `enable_chunked_prefill: true` — Reduces inter-token latency on long prompts by interleaving prefill and decode steps. + +### Config B — NVFP4, 8× B200 (DEP8, Throughput-Optimized) + +Optimal for a full 8-GPU B200 node (DGX B200) serving NVFP4. + +**`y.yaml`** + +```yaml +kv_cache_config: + enable_block_reuse: false + free_gpu_memory_fraction: 0.8 +moe_config: + backend: TRTLLM +cuda_graph_config: + enable_padding: true + max_batch_size: 256 +enable_attention_dp: true +num_postprocess_workers: 4 +enable_chunked_prefill: true +stream_interval: 10 +``` + +Additionally, TRT-LLM supports using a quantized mamba cache with stochastic rounding to improve throughput. Extend the `kv_cache_config` with the following info. + +```default +kv_cache_config: + mamba_ssm_cache_dtype: float16 + mamba_ssm_stochastic_rounding: true + mamba_ssm_philox_rounds: 5 +``` + +**Serve command** + +```bash +mpirun -n 1 --allow-run-as-root --oversubscribe \ + trtllm-serve /data/super_fp4/ \ + --host 0.0.0.0 \ + --port 8000 \ + --max_batch_size 256 \ + --tp_size 8 --ep_size 8 \ + --max_num_tokens 8192 \ + --trust_remote_code \ + --reasoning_parser nano-v3 \ + --tool_parser qwen3_coder \ + --extra_llm_api_options y.yaml +``` + +### Config C — NVFP4, DGX Spark + +Config to deploy the model on 1x DGX Spark. + +```default +kv_cache_config: + enable_block_reuse: false +cuda_graph_config: + max_batch_size: 32 + enable_padding: true +moe_config: + backend: CUTLASS +EOF +``` + +**Serve command** + +```bash +trtllm-serve /data/super_fp4/ \ + --host 0.0.0.0 \ + --port 8000 \ + --max_batch_size 4 \ + --trust_remote_code \ + --reasoning_parser nano-v3 \ + --tool_parser qwen3_coder \ + --extra_llm_api_options y.yaml +``` + +### Updated reasoning parser + +To use the `force_nonempty_content` kwarg in the chat template, build TRT-LLM from `main`. Alternatively, the changes from [PR-12061](https://github.com/NVIDIA/TensorRT-LLM/pull/12061) can be manually cherry-picked into the release container to enable it. + +### Contributors: + +The configurations in this document were created by: + +Izzy Putterman, Nave Assaf, Joyjit Daw, and many other talented NVIDIA engineers. diff --git a/docs/fern/pages-v0.1.0/use-case-examples/nemotron-voice-rag-agent-example/README.mdx b/docs/fern/pages-v0.1.0/use-case-examples/nemotron-voice-rag-agent-example/README.mdx new file mode 100644 index 000000000..05ce69f24 --- /dev/null +++ b/docs/fern/pages-v0.1.0/use-case-examples/nemotron-voice-rag-agent-example/README.mdx @@ -0,0 +1,205 @@ +--- +title: "🎙️ Voice-Powered RAG Agent with NVIDIA Nemotron Models" +slug: "use-case-examples/nemotron-voice-rag-agent-example/README.html" +description: "Build a complete end-to-end AI agent that accepts voice input, retrieves multimodal context, reasons with long-context models, and enforces safety guardrails—all using the latest NVIDIA Nemotron open " +--- + +Build a complete end-to-end AI agent that accepts voice input, retrieves multimodal context, reasons with long-context models, and enforces safety guardrails—all using the latest NVIDIA Nemotron open models. + +## 🌟 Features + +- **Voice Input**: Nemotron Speech ASR for real-time speech-to-text + +- **LangChain 1.0 Agent**: Uses `langgraph.prebuilt.create_react_agent` with automatic looping + +- **RAG as a Tool**: On-demand retrieval - agent decides when to search knowledge base + +- **Automatic Agent Loop**: Can call tools multiple times until it has enough information + +- **Multimodal RAG**: Embed and retrieve both text and document images + +- **Smart Reranking**: Improve retrieval accuracy by 6-7% with cross-encoder reranking + +- **Image Understanding**: Describe visual content in context using vision-language models + +- **Long-Context Reasoning**: Generate responses with 1M token context window + +- **Safety Guardrails (Always On)**: PII detection and content moderation enforced on all inputs/outputs + +## 📦 Models Used + +| Component | Model | Parameters | Deployment | +| --- | --- | --- | --- | +| **Speech-to-Text** | nvidia/nemotron-speech-streaming-en-0.6b | 600M | Self-hosted (NeMo) | +| **Embeddings** | nvidia/llama-nemotron-embed-vl-1b-v2 | 1.7B | Self-hosted (Transformers) | +| **Reranking** | nvidia/llama-nemotron-rerank-vl-1b-v2 | 1.7B | Self-hosted (Transformers) | +| **Vision-Language** | nvidia/nemotron-nano-12b-v2-vl | 12B | NVIDIA API | +| **Reasoning** | nvidia/nemotron-3-nano-30b-a3b | 30B | NVIDIA API | +| **Safety** | nvidia/Llama-3.1-Nemotron-Safety-Guard-8B-v3 | 8B | Self-hosted (Transformers) | + +## 🔧 Requirements + +### Hardware + +- **GPU**: NVIDIA GPU with at least 24GB VRAM recommended (for self-hosted models) + +- **CUDA**: 11.8 or later + +### Software + +- Python 3.10+ + +- PyTorch 2.0+ + +- NVIDIA API Key (for cloud-hosted models) + +## 🚀 Quick Start + +### 1. Clone the Repository + +```bash +git clone https://github.com/NVIDIA-NeMo/Nemotron.git +cd Nemotron/use-case-examples/nemotron-voice-rag-agent-example +``` + +### 2. Set Up Environment + +**Option A: Standard CUDA (RTX, A100, etc.):** + +```bash +uv sync --extra cuda --index-url https://download.pytorch.org/whl/cu124 +``` + +**Option B: DGX Spark (GB10):** + +```bash +uv sync --extra cuda --index-url https://download.pytorch.org/whl/cu130 +``` + +**Note:** Since `nemo_toolkit[asr]` may have specific PyTorch requirements, if you encounter dependency conflicts, install PyTorch first: + +```bash +# For Spark/GB10 systems +uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130 +uv sync + +# For standard CUDA systems +uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124 +uv sync +``` + +### 3. Configure API Key + +```bash +export NVIDIA_API_KEY="your-nvidia-api-key" +``` + +Get your API key from [NVIDIA NGC](https://ngc.nvidia.com/). + +### 4. Run the Tutorial + +```bash +jupyter notebook voice_rag_agent_tutorial.ipynb +``` + +## 📁 Project Structure + +```default +nemotron-voice-rag-agent-example/ +├── voice_rag_agent_tutorial.ipynb # Main tutorial notebook +├── README.md # This file +├── requirements.txt # Python dependencies +└── BlogSkeleton/ # Blog content and model docs + ├── BLOG.md + ├── BLOG_UPDATED.md + ├── Code Snippets/ + └── Model Information/ +``` + +## 🏗️ Architecture + +```default +┌─────────────────────────────────────────────────────────────────────┐ +│ Voice-Powered LangChain 1.0 Agent with RAG Tool │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ 🎤 Voice Input → Nemotron Speech ASR → Text Query │ +│ ↓ │ +│ 🛡️ Input Safety Check (ALWAYS ENFORCED) │ +│ ↓ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ LangGraph ReAct Agent Loop │ │ +│ │ (langgraph.prebuilt.create_react_agent) │ │ +│ │ │ │ +│ │ Agent (nemotron-3-nano-30b-a3b) │ │ +│ │ │ │ │ +│ │ ├─> Decide: Need more info? │ │ +│ │ │ │ │ +│ │ ├─> YES: Call RAG Tool ──┐ │ │ +│ │ │ ├── Embed │ │ │ +│ │ │ ├── Vector Search │ │ │ +│ │ │ ├── Rerank │ LOOP │ │ +│ │ │ └── Describe Images │ UNTIL │ │ +│ │ │ │ SATISFIED │ │ +│ │ └─\< Tool Result ─────────┘ │ │ +│ │ │ │ │ +│ │ └─> NO: Generate final answer │ │ +│ │ │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ ↓ │ +│ 🛡️ Output Safety Check (ALWAYS ENFORCED) │ +│ ↓ │ +│ 📝 Safe Text Output │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +## 📖 Tutorial Steps + +1. **Environment Setup**: Install dependencies and configure API keys + +2. **Multimodal RAG**: Build embeddings and vector store for text + images + +3. **Speech Input**: Add real-time speech transcription with Nemotron ASR + +4. **Safety Guardrails**: Implement PII detection and content moderation + +5. **Reasoning LLM**: Configure Nemotron for agent decision-making + +6. **LangChain 1.0 Agent**: Create ReAct agent with automatic looping + + - Define RAG as a tool (not a fixed workflow step) + + - Use `langgraph.prebuilt.create_react_agent` + + - Agent automatically loops until it can answer + + - Safety enforced on all inputs and outputs + +## 🎯 Use Cases + +- **Enterprise Q&A**: Answer questions over documents with charts, tables, and images + +- **Voice Assistants**: Build conversational AI with voice input + +- **Compliance**: Detect PII and enforce content policies + +- **Research**: Query scientific papers with visual content + +## 📄 License + +This project uses NVIDIA open models. Each model is governed by its respective license: + +- [NVIDIA Open Model License](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license/) + +- [Llama 3.1 Community License](https://www.llama.com/llama3_1/license/) + +## 🤝 Contributing + +Contributions are welcome! Please read our contributing guidelines before submitting PRs. + +## 📬 Support + +- [NVIDIA Developer Forums](https://forums.developer.nvidia.com/) + +- [GitHub Issues](https://github.com/NVIDIA-NeMo/Nemotron/issues) diff --git a/docs/fern/pages-vnightly/application-examples.mdx b/docs/fern/pages-vnightly/application-examples.mdx new file mode 100644 index 000000000..606ed3c2f --- /dev/null +++ b/docs/fern/pages-vnightly/application-examples.mdx @@ -0,0 +1,92 @@ +--- +title: "Application Examples" +slug: "application-examples.html" +description: "End-to-end applications built on Nemotron models, including agentic workflows, RAG systems, and fine-tuning pipelines. Each card links to its directory in the Nemotron GitHub repository." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +{/* Card footer badges +================== +Add a badge only when the attribute applies. Omit it (and do not substitute its opposite) when it does not. +Absence is the signal for the simpler case. + +{bdg-success\}`Notebook` — self-contained notebook; no environment beyond pip install. + Omit for multi-file projects and anything that isn't a notebook. + +{bdg-secondary\}`Local GPU` — requires a local GPU or hardware beyond a laptop or desktop. + Omit for API/cloud-only examples. Do not add an "API" badge. + +{bdg-info\}`Fine-tuning` — example includes a training/fine-tuning step. + Omit for inference-only examples. Do not add an "Inference" badge. */} + + + +End-to-end applications built on Nemotron models, including agentic workflows, RAG systems, and fine-tuning pipelines. Each card links to its directory in the [Nemotron GitHub repository](https://github.com/NVIDIA-NeMo/nemotron). + + + +Introductory notebook covering Nemotron 3 Super’s reasoning features: thinking, reasoning budget, low effort mode, streaming responses, tool-call streaming, and Perplexity Search integration using the OpenAI-compatible API. + +--- + +Notebook Mar 11, 2026 + + + + +End-to-end LoRA fine-tuning of Nemotron 3 Nano on Text2SQL (BIRD SQL) with deployment via NVIDIA NIM or vLLM using NeMo AutoModel or Megatron Bridge. + +--- + +Local GPU Fine-tuning Mar 11, 2026 + + + + +IDP pipeline that extracts and queries complex enterprise documents — financial reports, charts, and tables — using NeMo Retriever and multimodal Nemotron models. + +--- + +Local GPU Feb 09, 2026 + + + + +End-to-end voice-driven RAG agent combining speech-to-text, multimodal retrieval, 1M-token reasoning, and safety guardrails using open Nemotron models. + +--- + +Local GPU Jan 07, 2026 + + + + +Introductory notebook covering basic inference, reasoning mode toggling, and multi-agent systems using the OpenAI-compatible API via OpenRouter and LangChain. + +--- + +Notebook Dec 15, 2025 + + + + +Natural language-driven ML agent built on Nemotron Nano 9B with GPU-accelerated data exploration and model training using RAPIDS cuDF and cuML. + +--- + +Local GPU Nov 06, 2025 + + + + +Production-ready RAG agent using local Hugging Face embedding and reranking models with NVIDIA AI Endpoints for LLM inference, built on LangGraph. + +--- + +Local GPU Oct 28, 2025 + + + + diff --git a/docs/fern/pages-vnightly/architecture/README.mdx b/docs/fern/pages-vnightly/architecture/README.mdx new file mode 100644 index 000000000..45999b0e3 --- /dev/null +++ b/docs/fern/pages-vnightly/architecture/README.mdx @@ -0,0 +1,64 @@ +--- +title: "Nemotron Architecture" +slug: "architecture/README.html" +description: "This directory contains documentation about Nemotron’s architecture and design principles." +--- + +This directory contains documentation about Nemotron’s architecture and design principles. + +## Overview + +Nemotron is a **cookbook** - a reference implementation showing best practices for training LLMs at scale. It’s not a framework you install; it’s a codebase you fork and customize. + +## Documents + +- [Runspec Specification](/../runspec/v1/spec) - The `[tool.runspec]` metadata format for recipe scripts + +- [CLI Architecture](/cli-architecture) - How the CLI layer works and how to fork it + +- [Design Philosophy](/design-philosophy) - What we optimize for and why + +## Quick Start + +```bash +# Run pretraining locally +nemotron nano3 pretrain -c tiny + +# Submit to cluster +nemotron nano3 pretrain -c tiny --run dgx + +# See what's happening (execution logic is visible in the code) +# Open: src/nemotron/cli/commands/nano3/pretrain.py +``` + +## Two-Layer Architecture + +| Layer | What | Where | Fork When | +| --- | --- | --- | --- | +| **Execution** | How to run and track experiments | cli/commands/ + nemo_runspec/ | nemo-run/wandb -> SkyPilot/mlflow | +| **Runtime** | Training/data processing | recipes/ | Algorithm changes | + +```default +Execution Layer Runtime Layer (recipes/) +┌──────────────────────────┐ ┌─────────────────────┐ +│ cli/commands/nano3/ │ │ recipes/nano3/ │ +│ pretrain.py │ │ pretrain/train.py │ +│ │ │ │ +│ nemo_runspec (toolkit) │─────►│ Megatron-Bridge │ +│ config, execution, env │ │ │ +│ artifact registry │ │ │ +└──────────────────────────┘ └─────────────────────┘ +``` + +The runtime layer is typically a **thin script** that delegates to NVIDIA AI stack libraries. The execution layer contains all the job submission logic, which is what you’d change to swap nemo-run for SkyPilot or another backend. + +## Package Responsibilities + +| Package | Scope | +| --- | --- | +| **nemo_runspec** | Generic CLI toolkit: PEP 723 runspec parsing, config loading, env.toml profiles, execution helpers, packaging, pipeline orchestration, artifact registry (art:// resolution, fsspec/wandb backends) | +| **nemotron.kit** | Domain-specific: artifact type definitions (pretrain data, SFT data, checkpoints), lineage trackers (W&B, file-based), W&B integration | +| **nemotron.cli** | CLI commands: visible execution logic per command, typer-based command tree | +| **nemotron.recipes** | Runtime scripts: training, data prep, RL (thin scripts delegating to NVIDIA AI stack) | + +Dependency direction: `nemotron.cli` -> `nemo_runspec` + `nemotron.kit` -> NVIDIA stack. Never the reverse. diff --git a/docs/architecture/cli-architecture.md b/docs/fern/pages-vnightly/architecture/cli-architecture.mdx similarity index 81% rename from docs/architecture/cli-architecture.md rename to docs/fern/pages-vnightly/architecture/cli-architecture.mdx index 4c049bcd5..efdfcd05f 100644 --- a/docs/architecture/cli-architecture.md +++ b/docs/fern/pages-vnightly/architecture/cli-architecture.mdx @@ -1,16 +1,20 @@ -# CLI Architecture +--- +title: "CLI Architecture" +slug: "architecture/cli-architecture.html" +description: "This document explains how Nemotron’s CLI layer works and how to modify it for your needs." +--- -This document explains how Nemotron's CLI layer works and how to modify it for your needs. +This document explains how Nemotron’s CLI layer works and how to modify it for your needs. ## Overview -The CLI layer (`src/nemotron/cli/`) handles **execution** -- how jobs are submitted and tracked. Each command file contains visible execution logic, making it easy to understand and modify. +The CLI layer (`src/nemotron/cli/`) handles **execution** – how jobs are submitted and tracked. Each command file contains visible execution logic, making it easy to understand and modify. The shared toolkit lives in the `nemo_runspec` package: config loading, env.toml profiles, execution helpers, packaging, and display utilities. CLI commands import from `nemo_runspec` and wire things together explicitly. ## Design Principle: Visible Execution -Nemotron makes execution **explicit** -- all nemo-run setup lives directly in each command function: +Nemotron makes execution **explicit** – all nemo-run setup lives directly in each command function: ```python # src/nemotron/cli/commands/nano3/pretrain.py @@ -59,7 +63,7 @@ Recipe scripts are self-describing. Each script declares its identity, container # /// ``` -The CLI reads this via `nemo_runspec.parse()`, returning a frozen `Runspec` dataclass. See [nemo_runspec package](../nemo_runspec/package-readme) for the full schema. +The CLI reads this via `nemo_runspec.parse()`, returning a frozen `Runspec` dataclass. See [nemo_runspec package](/../nemo_runspec/package-readme) for the full schema. ### RecipeConfig @@ -115,7 +119,7 @@ job_path, train_path = save_configs(job_config, train_config_for_script, job_dir ## Directory Structure -``` +```default src/nemotron/ ├── cli/ # EXECUTION LAYER │ ├── bin/ @@ -209,6 +213,7 @@ src/nemo_runspec/ # SHARED TOOLKIT ## Execution Patterns ### Training (Slurm + torchrun) + Pretrain and SFT use Slurm with torchrun launcher: ```python @@ -222,6 +227,7 @@ with run.Experiment(recipe_name) as exp: ``` ### RL (Ray) + RL uses Ray for distributed execution: ```python @@ -239,6 +245,7 @@ ray_job.start( ``` ### Data Prep (Ray + Code Packager) + Data prep uses Ray with full codebase rsync. The `[tool.runspec]` in the data prep script declares `launch = "ray"`: ```python @@ -251,6 +258,7 @@ SPEC = parse_runspec(SCRIPT_PATH) # launch=ray, cmd template from [tool.runspec ### Example: Replace nemo-run with SkyPilot 1. **Read the current execution logic** in `cli/commands/nano3/pretrain.py` + 2. **Replace `_execute_remote()`** with SkyPilot equivalents: ```python @@ -278,33 +286,34 @@ def _execute_skypilot(cfg: RecipeConfig): sky.launch(task, cluster_name="nano3-pretrain") ``` -3. **Keep config loading** -- `nemo_runspec.config` works with any backend -4. **Keep the `[tool.runspec]` block** -- metadata stays with the script +3. **Keep config loading** – `nemo_runspec.config` works with any backend + +4. **Keep the `[tool.runspec]` block** – metadata stays with the script ## Shared Utilities Low-level helpers in `nemo_runspec.execution` are shared across commands but keep orchestration visible: | Function | Module | Description | -|----------|--------|-------------| -| `create_executor()` | `nemo_runspec.execution` | Build nemo-run executor from env config | -| `build_env_vars()` | `nemo_runspec.execution` | Build environment variables (HF, W&B tokens) | -| `execute_local()` | `nemo_runspec.execution` | Local subprocess execution via torchrun | -| `get_startup_commands()` | `nemo_runspec.execution` | Extract startup commands from env config | -| `ensure_squashed_image()` | `nemo_runspec.squash` | Container squashing for cluster | -| `clone_git_repos_via_tunnel()` | `nemo_runspec.execution` | Git repo cloning via SSH tunnel | +| --- | --- | --- | +| create_executor() | nemo_runspec.execution | Build nemo-run executor from env config | +| build_env_vars() | nemo_runspec.execution | Build environment variables (HF, W&B tokens) | +| execute_local() | nemo_runspec.execution | Local subprocess execution via torchrun | +| get_startup_commands() | nemo_runspec.execution | Extract startup commands from env config | +| ensure_squashed_image() | nemo_runspec.squash | Container squashing for cluster | +| clone_git_repos_via_tunnel() | nemo_runspec.execution | Git repo cloning via SSH tunnel | -These are utilities, not abstractions. The calling code shows exactly how they're used. +These are utilities, not abstractions. The calling code shows exactly how they’re used. ## CLI Behavior Reference | Feature | How It Works | -|---------|--------------| -| Late globals | `split_unknown_args()` in `parse_recipe_config()` | -| Dotlist overrides | Applied during `parse_config()` via OmegaConf | -| Packager selection | `SelfContainedPackager` or `CodePackager` from `nemo_runspec.packaging` | -| Ray execution | Visible in `_execute_remote()` functions in RL/data prep commands | -| Build verb | Family-specific `build.py` dispatchers submit stage-local container builds explicitly | -| Omni3 family layout | Top-level `omni3/` mixes build/eval commands with nested `data/`, `model/`, and `rl/` groups | -| Rich help panels | `RecipeTyper` + `RecipeMeta` from `nemo_runspec.recipe_typer` | -| env.toml profiles | Loaded via `nemo_runspec.env.parse_env()` with inheritance | +| --- | --- | +| Late globals | split_unknown_args() in parse_recipe_config() | +| Dotlist overrides | Applied during parse_config() via OmegaConf | +| Packager selection | SelfContainedPackager or CodePackager from nemo_runspec.packaging | +| Ray execution | Visible in _execute_remote() functions in RL/data prep commands | +| Build verb | Family-specific build.py dispatchers submit stage-local container builds explicitly | +| Omni3 family layout | Top-level omni3/ mixes build/eval commands with nested data/, model/, and rl/ groups | +| Rich help panels | RecipeTyper + RecipeMeta from nemo_runspec.recipe_typer | +| env.toml profiles | Loaded via nemo_runspec.env.parse_env() with inheritance | diff --git a/docs/architecture/design-philosophy.md b/docs/fern/pages-vnightly/architecture/design-philosophy.mdx similarity index 65% rename from docs/architecture/design-philosophy.md rename to docs/fern/pages-vnightly/architecture/design-philosophy.mdx index 75e4186c4..aaf8bc1a2 100644 --- a/docs/architecture/design-philosophy.md +++ b/docs/fern/pages-vnightly/architecture/design-philosophy.mdx @@ -1,10 +1,14 @@ -# Design Philosophy +--- +title: "Design Philosophy" +slug: "architecture/design-philosophy.html" +description: "Nemotron is a cookbook, not a framework. Each recipe is a working example of a real training workflow, from data preparation through pretraining, fine-tuning, and reinforcement learning. Everything in" +--- Nemotron is a **cookbook**, not a framework. Each recipe is a working example of a real training workflow, from data preparation through pretraining, fine-tuning, and reinforcement learning. Everything in this document follows from that choice. -A framework gives you building blocks and asks you to assemble them. A cookbook shows you the finished dish: here's how we actually trained this model, start to finish. The code is fully runnable, but it's not meant to be your team's production codebase. It's a reference implementation. You read it, understand the approach, and adapt the parts you need into your own setup. +A framework gives you building blocks and asks you to assemble them. A cookbook shows you the finished dish: here’s how we actually trained this model, start to finish. The code is fully runnable, but it’s not meant to be your team’s production codebase. It’s a reference implementation. You read it, understand the approach, and adapt the parts you need into your own setup. -This is a subtle but important distinction. A team's codebase evolves around their specific infrastructure, scale, and constraints. A cookbook is optimized for something different: **teaching by showing working examples**. Because it's a cookbook, we expect every team to customize it — different clusters, different data pipelines, different tracking tools. Customization isn't an edge case, it's the whole point. +This is a subtle but important distinction. A team’s codebase evolves around their specific infrastructure, scale, and constraints. A cookbook is optimized for something different: **teaching by showing working examples**. Because it’s a cookbook, we expect every team to customize it — different clusters, different data pipelines, different tracking tools. Customization isn’t an edge case, it’s the whole point. That expectation shapes everything about how we write code. We favor clarity over abstraction, self-contained examples over reusable components, and making every step visible over hiding complexity behind convenience wrappers. When the code is explicit, a human can read a recipe and understand what to change. And just as importantly, an LLM or AI agent can too — which means customization can be assisted or fully driven by AI. @@ -14,16 +18,19 @@ That expectation shapes everything about how we write code. We favor clarity ove We expect users to show up with prompts like: -> "Fork nemotron's CLI and replace nemo-run with SkyPilot" -> "Add a new data preprocessing stage to nano3" -> "Customize the SFT recipe to use my dataset format" +> “Fork nemotron’s CLI and replace nemo-run with SkyPilot” +“Add a new data preprocessing stage to nano3” +“Customize the SFT recipe to use my dataset format” For an LLM to do this well, the codebase must be: + 1. **Readable**: An LLM (or a human new to the project) can understand what the code does by reading it + 2. **Self-contained**: Related logic lives together, not scattered across files + 3. **Forkable**: Easy to copy a module and modify it for your needs -This is why we optimize for explicitness. When a user says "swap nemo-run for SkyPilot", an LLM should be able to read the relevant recipe and make the changes without getting lost in abstractions. This works because recipes are complete, end-to-end examples — not thin wrappers around hidden framework machinery. +This is why we optimize for explicitness. When a user says “swap nemo-run for SkyPilot”, an LLM should be able to read the relevant recipe and make the changes without getting lost in abstractions. This works because recipes are complete, end-to-end examples — not thin wrappers around hidden framework machinery. ## Design Principles @@ -39,7 +46,7 @@ def _execute_pretrain(cfg: RecipeConfig): # ALL execution logic visible here train_config = parse_config(cfg.ctx, SPEC.config_dir, SPEC.config.default) job_config = build_job_config(train_config, ...) - executor = create_executor(env=env, ...) # <- Can see exactly what's happening + executor = create_executor(env=env, ...) # \<- Can see exactly what's happening with run.Experiment(name) as exp: exp.add(script_task, executor=executor) exp.run() @@ -66,25 +73,34 @@ Recipe scripts declare their own identity and requirements via PEP 723 inline me # /// ``` -The CLI layer reads this metadata via `nemo_runspec.parse()` instead of duplicating it. This keeps recipes portable -- any tool can read the same metadata. +The CLI layer reads this metadata via `nemo_runspec.parse()` instead of duplicating it. This keeps recipes portable – any tool can read the same metadata. ### 3. Locality Over DRY Keep related code together, even if it means some duplication. **Why duplication is sometimes better:** + - Each command file is self-contained and readable -- Changes to one command don't accidentally affect others + +- Changes to one command don’t accidentally affect others + - LLMs can understand one file without tracing through abstractions + - Forking is easy: copy the file, modify what you need -**What we don't share:** +**What we don’t share:** + - High-level orchestration (executor building, experiment running) + - Command-specific logic **What we do share (via `nemo_runspec`):** + - Low-level utilities (env var building, packager construction) + - Config loading and merging + - Help formatting and display ### 4. Fork Over Extend @@ -92,6 +108,7 @@ Keep related code together, even if it means some duplication. This is the cookbook principle in action: design for copying and modifying, not subclassing. **Instead of inheritance hierarchies:** + ```python # cli/commands/nano3/pretrain.py - just copy and modify this file @@ -107,9 +124,13 @@ def _execute_skypilot(cfg: RecipeConfig): ``` This is simpler because: + - No inheritance hierarchy to understand + - No hook points to find + - No registration system to configure + - Just code you can read and change ## Two-Layer Architecture @@ -117,33 +138,36 @@ This is simpler because: We separate execution (how to run) from runtime (what to run): | Layer | Purpose | Change Frequency | -|-------|---------|-----------------| -| **Execution** (`cli/commands/` + `nemo_runspec/`) | Job submission, tracking, orchestration | When changing backends | -| **Runtime** (`recipes/`) | Training algorithms, data processing | When changing algorithms | +| --- | --- | --- | +| **Execution** (cli/commands/ + nemo_runspec/) | Job submission, tracking, orchestration | When changing backends | +| **Runtime** (recipes/) | Training algorithms, data processing | When changing algorithms | The runtime layer is typically a **thin script** that delegates to NVIDIA AI stack libraries: | Stage | Script | Library | -|-------|--------|---------| -| Pretrain | `train.py` | Megatron-Bridge | -| SFT | `train.py` | Megatron-Bridge | -| RL | `train.py` | NeMo-RL | -| Data prep | `data_prep.py` | Nemotron data_prep + Ray | +| --- | --- | --- | +| Pretrain | train.py | Megatron-Bridge | +| SFT | train.py | Megatron-Bridge | +| RL | train.py | NeMo-RL | +| Data prep | data_prep.py | Nemotron data_prep + Ray | -The execution layer is one forkable unit. Want SkyPilot + MLflow? Fork the CLI and rewrite it. Runtime scripts stay unchanged because they're just thin wrappers around library calls. +The execution layer is one forkable unit. Want SkyPilot + MLflow? Fork the CLI and rewrite it. Runtime scripts stay unchanged because they’re just thin wrappers around library calls. This separation means: + - Swapping nemo-run for SkyPilot only touches `cli/commands/` + - Changing training algorithms only touches `recipes/` + - Each layer can be forked independently ## Package Boundaries | Package | Owns | Does NOT own | -|---------|------|-------------| -| **`nemo_runspec`** | Runspec parsing, config loading, env.toml, execution helpers, packaging, pipeline, artifact registry | Domain-specific artifact types, W&B integration | -| **`nemotron.kit`** | Artifact types, lineage trackers, W&B config, training script utilities | CLI, config loading, execution, packaging | -| **`nemotron.cli`** | Command implementations, typer app tree | Reusable infrastructure | +| --- | --- | --- | +| **nemo_runspec** | Runspec parsing, config loading, env.toml, execution helpers, packaging, pipeline, artifact registry | Domain-specific artifact types, W&B integration | +| **nemotron.kit** | Artifact types, lineage trackers, W&B config, training script utilities | CLI, config loading, execution, packaging | +| **nemotron.cli** | Command implementations, typer app tree | Reusable infrastructure | Dependency flows one way: `nemotron.cli` -> `nemo_runspec` + `nemotron.kit`. Never the reverse. @@ -151,21 +175,28 @@ Dependency flows one way: `nemotron.cli` -> `nemo_runspec` + `nemotron.kit`. Nev ### For LLMs -- **Clear boundaries**: "Read `cli/commands/nano3/pretrain.py`, replace the execution logic" +- **Clear boundaries**: “Read `cli/commands/nano3/pretrain.py`, replace the execution logic” + - **No dispatch tables**: No need to understand registration systems + - **No inheritance**: No base classes to trace + - **Self-describing scripts**: Metadata lives with the script, not in a separate config ### For Humans - **Visible execution**: Read one file to understand how jobs run + - **Simple forking**: Copy file, modify, done + - **Testable runtime**: Training logic is pure and separate ### For Maintenance -- **Execution backends don't couple to algorithms**: Clean separation +- **Execution backends don’t couple to algorithms**: Clean separation + - **Easy to add new models**: Just create new recipe directory + - **Easy to add new backends**: Just modify CLI layer ## Trade-offs We Accept @@ -173,24 +204,33 @@ Dependency flows one way: `nemotron.cli` -> `nemo_runspec` + `nemotron.kit`. Nev ### More Duplication Each command has similar executor setup code. We accept this because: + - Differences are visible (Slurm vs Ray, torchrun vs not) + - Changes are local to the file + - Forking is straightforward ### Bigger Diffs for Backend Changes Changing from nemo-run to SkyPilot requires updating multiple command files. We accept this because: + - Each update is simple (no abstractions to navigate) + - The changes are mechanical (same pattern repeated) ### No Centralized Abstraction -There's no `run_recipe()` function that handles all execution. We accept this because: +There’s no `run_recipe()` function that handles all execution. We accept this because: + - Each command shows its own execution path + - Differences between commands are visible + - LLMs can understand without tracing through layers ## References - [The Grug Brained Developer](https://grugbrain.dev/) - Complexity bad, simple good + - [Locality of Behavior](https://htmx.org/essays/locality-of-behaviour/) - Keep related code together diff --git a/docs/build-benchmarks/explanation/data-preparation.md b/docs/fern/pages-vnightly/build-benchmarks/explanation/data-preparation.mdx similarity index 78% rename from docs/build-benchmarks/explanation/data-preparation.md rename to docs/fern/pages-vnightly/build-benchmarks/explanation/data-preparation.mdx index ce32a398d..2620928f4 100644 --- a/docs/build-benchmarks/explanation/data-preparation.md +++ b/docs/fern/pages-vnightly/build-benchmarks/explanation/data-preparation.mdx @@ -1,11 +1,13 @@ - +--- +title: "Data Preparation for Multiple-Choice Question Benchmarks" +slug: "build-benchmarks/explanation/data-preparation.html" +description: "The prepare stage builds the seed dataset that backs multiple-choice question (MCQ) generation in nemotron steps run byob/mcq." +--- - +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} -# Data Preparation for Multiple-Choice Question Benchmarks +{/* Explanation: how the BYOB prepare stage pairs Hugging Face few-shots with domain text into seed.parquet. */} The prepare stage builds the seed dataset that backs multiple-choice question (MCQ) generation in `nemotron steps run byob/mcq`. @@ -47,10 +49,13 @@ The loader treats each row as `parquet_path:file_name`, so `file_name` acts as t ### Content Practices - Curate plain text for every target. - One folder such as `medicine` can suffice for a pilot; another team might split into `radiology`, `podiatry`, `clinical_documentation`, and similar labels that mirror internal source taxonomy. +One folder such as `medicine` can suffice for a pilot; another team might split into `radiology`, `podiatry`, `clinical_documentation`, and similar labels that mirror internal source taxonomy. + - Avoid shipping personally identifiable information (PII), or replace sensitive spans with synthetic text before you run the step. + - Few-shot tag metadata is separate from domain files. - When you set `metadata_file`, you can attach tags to benchmark rows and filter few-shots with per-target `tags`, as described in {doc}`get-right-questions`. +When you set `metadata_file`, you can attach tags to benchmark rows and filter few-shots with per-target `tags`, as described in [Getting the Right Questions From the Source Benchmark](/get-right-questions). + - Start with data you can legally host in a development environment, then tighten controls before you connect restricted enterprise corpora. ## Step 1: Load Source Benchmark @@ -64,10 +69,12 @@ Expect question text, labeled choices, a keyed correct answer, subject labels, a Pick a benchmark whose tone matches the style you want the generator to echo, for example: - `cais/mmlu` for broad academic multiple-choice style. + - `TIGER-Lab/MMLU-Pro` for harder prompts with more reasoning surface. + - `Idavidrein/gpqa` for graduate-level science questions. -Authoritative identifiers and default subsets are listed in {doc}`../reference/benchmarks`. +Authoritative identifiers and default subsets are listed in [Supported Hugging Face Benchmarks](/../reference/benchmarks). ## Step 2: Filter by Target-Source Mapping @@ -93,16 +100,22 @@ The `tags` field always requires `metadata_file` with question-level rows the lo ### How It Works 1. Place domain text under `input_dir/banking/` or supply `input_dir/banking.parquet` with the required columns. + 2. Filter few-shot candidates to the listed subjects, then to tag combinations when tags are active. - Subject strings must exist in the Hugging Face split you loaded; confirm spelling on the dataset card. +Subject strings must exist in the Hugging Face split you loaded; confirm spelling on the dataset card. + 3. Weights on `subjects` and `tags` normalize to probabilities. + 4. The Cartesian product of subject and tag choices becomes the sampling categories inside `make_samples`. For the `banking` target above, you get four combined categories: - `management` + `reasoning,unambiguous`: 0.7 × 0.8 = 0.56 + - `management` + `knowledge`: 0.7 × 0.2 = 0.14 + - `marketing` + `reasoning,unambiguous`: 0.3 × 0.8 = 0.24 + - `marketing` + `knowledge`: 0.3 × 0.2 = 0.06 Strings such as `reasoning,unambiguous` split on commas when matched against metadata, following `mcq/dataset.py`. @@ -123,6 +136,7 @@ One to three few-shots per query is a common starting point; higher counts impro ### Input formats - Text files such as `input_dir/banking/intro.txt`. + - Parquet bundles such as `input_dir/banking.parquet` with `text` and `file_name`. ### Chunking @@ -142,7 +156,9 @@ Chunking spreads questions across long manuals, exposes different sections per q For every domain document under a target, `make_samples` follows this loop: 1. Sample `queries_per_target_subject_document` draws from the subject×tag distribution. + 2. For each draw, fetch `few_shot_samples_per_query` benchmark rows that satisfy the subject and tag filters. + 3. Attach either the full document or a chunked slice according to `chunking_config`. ```yaml @@ -150,12 +166,14 @@ queries_per_target_subject_document: 10 ``` Rows accumulate in `seed.parquet`. -Refer to {doc}`../reference/output-files` for column names. +Refer to [Output Files](/../reference/output-files) for column names. Generate then reads those paired fields so the model sees canonical MCQ structure from the benchmark plus grounding text from your files. ## Next Steps -- {doc}`question-generation` shows how generate consumes `seed.parquet`. -- {doc}`pipeline-overview` situates prepare inside the wider `mcq` family. -- {doc}`../reference/generate-config` documents every YAML knob, including chunking and query defaults. +- [Question Generation](/question-generation) shows how generate consumes `seed.parquet`. + +- [Pipeline Overview](/pipeline-overview) situates prepare inside the wider `mcq` family. + +- [Generation Configuration Reference](/../reference/generate-config) documents every YAML knob, including chunking and query defaults. diff --git a/docs/build-benchmarks/explanation/filtering.md b/docs/fern/pages-vnightly/build-benchmarks/explanation/filtering.mdx similarity index 60% rename from docs/build-benchmarks/explanation/filtering.md rename to docs/fern/pages-vnightly/build-benchmarks/explanation/filtering.mdx index 161949600..2b79e6aa1 100644 --- a/docs/build-benchmarks/explanation/filtering.md +++ b/docs/fern/pages-vnightly/build-benchmarks/explanation/filtering.mdx @@ -1,11 +1,13 @@ - +--- +title: "Easiness and Hallucination Filtering" +slug: "build-benchmarks/explanation/filtering.html" +description: "Decide which generated multiple-choice question (MCQ) rows look too trivial or unreliable before you export benchmark.parquet, using only configuration and prompts." +--- - +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} -# Easiness and Hallucination Filtering +{/* Explanation: easiness and hallucination scoring, YAML controls, and how rows reach benchmark.parquet. */} Decide which generated multiple-choice question (MCQ) rows look too trivial or unreliable before you export `benchmark.parquet`, using only configuration and prompts. @@ -13,20 +15,20 @@ The `HALLUCINATION_EASINESS_DETECTION` stage runs two prompt families in paralle Every row receives numeric scores and boolean flags. Optional removal rules decide what survives into the final export. -Artifacts and filenames are listed in {doc}`../reference/output-files`. -Field-level YAML is documented in {doc}`../reference/generate-config`. +Artifacts and filenames are listed in [Output Files](/../reference/output-files). +Field-level YAML is documented in [Generation Configuration Reference](/../reference/generate-config). ## What You Control | Control | Purpose | | --- | --- | -| `filtering_model_configs` | Which models answer the easiness and hallucination judge prompts. | -| `easiness_threshold` | When the easiness vote fraction is above this value, the row is marked `is_easy`. | -| `hallucination_threshold` | When the hallucination vote fraction is below this value, the row is marked `is_hallucination`. | -| `remove_easy` | If true, rows with `is_easy` drop out of `benchmark.parquet` during final assembly. | -| `remove_hallucinated` | If true, rows with `is_hallucination` drop out of `benchmark.parquet` during final assembly. | -| `prompt_config` | `null` keeps packaged prompts; a path must supply `easiness_filter` and `hallucination_filter` blocks. Refer to {doc}`../how-to/prompt-tuning`. | -| `ndd_batch_size` | Batch size for the Data Designer calls that run this stage. | +| filtering_model_configs | Which models answer the easiness and hallucination judge prompts. | +| easiness_threshold | When the easiness vote fraction is above this value, the row is marked is_easy. | +| hallucination_threshold | When the hallucination vote fraction is below this value, the row is marked is_hallucination. | +| remove_easy | If true, rows with is_easy drop out of benchmark.parquet during final assembly. | +| remove_hallucinated | If true, rows with is_hallucination drop out of benchmark.parquet during final assembly. | +| prompt_config | null keeps packaged prompts; a path must supply easiness_filter and hallucination_filter blocks. Refer to [Prompt Tuning for Benchmarks](/../how-to/prompt-tuning). | +| ndd_batch_size | Batch size for the Data Designer calls that run this stage. | Even when removals are false, `stage_cache/filtered_questions.parquet` keeps `correct_ratio_easiness`, `correct_ratio_hallucination`, `is_easy`, and `is_hallucination` so you can audit scores before tightening thresholds. @@ -36,9 +38,10 @@ For each filter family, every configured model returns a parsed letter answer. The pipeline compares those letters to `answer_generated` on the row. - Easiness builds `correct_ratio_easiness` as the fraction of easiness models whose answer matches `answer_generated`. - When that fraction is greater than `easiness_threshold`, `is_easy` is set to true to indicate the item was too easy for the swarm to disagree with. +When that fraction is greater than `easiness_threshold`, `is_easy` is set to true to indicate the item was too easy for the swarm to disagree with. + - Hallucination builds `correct_ratio_hallucination` the same way for the hallucination model list. - When that fraction is less than `hallucination_threshold`, `is_hallucination` is set to true to indicate that too few models agreed with the generated label. Typically, these need human-in-the-loop review. +When that fraction is less than `hallucination_threshold`, `is_hallucination` is set to true to indicate that too few models agreed with the generated label. Typically, these need human-in-the-loop review. Adding more models under a list increases the denominator of the ratio, so revisit thresholds whenever you add or remove swarm members. @@ -128,6 +131,8 @@ The default configuration files wire those prompts when `prompt_config` is `null ## Related Information -- {doc}`quality-validation` for upstream judgement, deduplication, distractors, and outlier stages that feed this step. -- {doc}`question-generation` for how rows enter the generate pipeline before filtering. -- {doc}`../how-to/skip-stages` if you need to rerun filtering after tweaking thresholds. +- [Quality Validation](/quality-validation) for upstream judgement, deduplication, distractors, and outlier stages that feed this step. + +- [Question Generation](/question-generation) for how rows enter the generate pipeline before filtering. + +- [Skip Stages When Iterating](/../how-to/skip-stages) if you need to rerun filtering after tweaking thresholds. diff --git a/docs/fern/pages-vnightly/build-benchmarks/explanation/get-right-questions.mdx b/docs/fern/pages-vnightly/build-benchmarks/explanation/get-right-questions.mdx new file mode 100644 index 000000000..157f381c9 --- /dev/null +++ b/docs/fern/pages-vnightly/build-benchmarks/explanation/get-right-questions.mdx @@ -0,0 +1,77 @@ +--- +title: "Getting the Right Questions From the Source Benchmark" +slug: "build-benchmarks/explanation/get-right-questions.html" +description: "Choose the best rows from the Hugging Face source benchmark, such as Massive Multitask Language Understanding (MMLU), to use as few-shot examples for each target, from broad choices down to very speci" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +Choose the best rows from the Hugging Face source benchmark, such as Massive Multitask Language Understanding (MMLU), to use as few-shot examples for each target, from broad choices down to very specific tags. + +You control which source questions appear as few-shots by configuring coarse filters (`split`, `subset`, `hf_dataset`, `source_subjects`) and fine filters (`target_source_mapping`, and optional `tags` backed by `metadata_file`). +The intent is to show the model exemplars that match the subject you are generating for. + +In `nemotron steps run byob/mcq`, each key in `target_source_mapping` must match a folder of `.txt` files or a `*.parquet` file under `input_dir`, not an abstract label on its own. + +## The Funnel: Coarse to Fine-Grained Control + +Most question-answer benchmark datasets expose many subjects, such as astronomy, econometrics, elementary mathematics, nutrition, and so on. +Coarse filters shrink that universe before you attach sources to each local target. + +You can narrow step by step until each target draws from the pool you intend. + +![Funnel from coarse to fine filtering: split, subset, source_subjects, then target_source_mapping with optional subjects and tags per target.](../../../_images/funnel.png) + +**Coarse (top of funnel)** + +- `hf_dataset`: which Hugging Face benchmark to load, for example `cais/mmlu`. + +- `split`: which split to read first, such as `test` or `train`, applied when the loader pulls the benchmark. + +- `subset`: which variant of that benchmark, such as `all` for MMLU or `kn` for MMLU Indic, also applied at load time. + +- `source_subjects`: which benchmark taxonomy labels may appear in the pool. +If you leave this list empty, the pipeline expands it to every subject available for the chosen `hf_dataset`, `subset`, and `split`. +Mappings only sample from subjects that remain in this pool. + +**Finer (middle of funnel)** + +- `target_source_mapping`: for each target key that exists under `input_dir`, you list which source subjects to sample and optionally assign weights. +This ties each corpus folder or Parquet file to the part of the benchmark taxonomy you want the model to imitate. + +**Finest (bottom of funnel)** + +- `tags`: optional. +When `metadata_file` lists question identifiers with tags, each target can filter few-shots further by tag strings such as `reasoning` or `unambiguous`, or by comma-joined combinations such as `reasoning,unambiguous`, optionally with weights. +Tags are the tightest lever on which rows become few-shots. + +## How It Fits Together + +1. Load: the pipeline loads the benchmark for `hf_dataset`, `split`, and `subset`, then keeps only the subjects in `source_subjects`, or all subjects when that list is empty after expansion. + +1. Map: for each target, `target_source_mapping` names source subjects and optional tag sets to sample from. +Source subjects and tags each support explicit weights; otherwise sampling is uniform over the listed entries. + +1. Sample: while building the seed dataset, the prepare step samples subject-tag pairs according to those weights and draws few-shot questions from the filtered source tables. + +The coarse settings define the global pool. +`target_source_mapping`, and tags when enabled, narrow which slice of that pool each target should use when it pairs exemplars with your domain chunks. + +## Configuration at a Glance + +| Control | Where | Effect | +| --- | --- | --- | +| hf_dataset | Top-level config | Which Hugging Face dataset supplies few-shot rows. | +| split | Top-level config | Dataset split, such as test, taken from the source benchmark. | +| subset | Top-level config | Dataset subset, such as all or kn, applied before subject filtering. | +| source_subjects | Top-level config | Restricts which benchmark subjects remain in the pool; an empty list expands to all subjects for the chosen dataset, split, and subset. | +| target_source_mapping | Per target directory or Parquet | For each target under input_dir, which source subjects and optional tags to use, with optional weights. | + +## Related documentation + +- For full option details and validation rules, see [Generation Configuration Reference](/../reference/generate-config). + +- For allowed Hugging Face benchmarks and subsets, see [Supported Hugging Face Benchmarks](/../reference/benchmarks). + +- For how the prepare step uses this mapping to build the seed dataset, see [Data Preparation for Multiple-Choice Question Benchmarks](/data-preparation). diff --git a/docs/fern/pages-vnightly/build-benchmarks/explanation/index.mdx b/docs/fern/pages-vnightly/build-benchmarks/explanation/index.mdx new file mode 100644 index 000000000..80c3061f0 --- /dev/null +++ b/docs/fern/pages-vnightly/build-benchmarks/explanation/index.mdx @@ -0,0 +1,99 @@ +--- +title: "Concepts" +slug: "build-benchmarks/explanation/index.html" +description: "These pages explain how the mcq family inside src/nemotron/steps/byob prepares data, runs each generation stage, and optionally translates benchmarks." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +These pages explain how the `mcq` family inside `src/nemotron/steps/byob` prepares data, runs each generation stage, and optionally translates benchmarks. + +## Architecture + + + +Prepare, generate, translate, and the Parquet stage cache. + +--- + +stages + + + + + +## Core processes + + + +Seeds from Hugging Face plus local corpus chunks. + +--- + +few-shot + + + + +`source_subjects`, weights, and optional tags. + +--- + +target_source_mapping + + + + +Data Designer batched calls from prepared seeds. + +--- + +generation + + + + + +## Quality assurance + + + +Judgement, deduplication, distractors, coverage, outliers. + +--- + +validation + + + + +Easiness and hallucination scores with removal flags. + +--- + +filtering + + + + + +## Translation + + + +Curator translation, backtranslation, metrics, final schema. + +--- + +translate + + + + + +## Next steps + +- Hands-on first run: [Getting Started with Building MCQ Benchmarks](/../getting-started) + +- YAML tables: [Reference](/../reference/index) diff --git a/docs/build-benchmarks/explanation/pipeline-overview.md b/docs/fern/pages-vnightly/build-benchmarks/explanation/pipeline-overview.mdx similarity index 69% rename from docs/build-benchmarks/explanation/pipeline-overview.md rename to docs/fern/pages-vnightly/build-benchmarks/explanation/pipeline-overview.mdx index cb65e020c..fb013717b 100644 --- a/docs/build-benchmarks/explanation/pipeline-overview.md +++ b/docs/fern/pages-vnightly/build-benchmarks/explanation/pipeline-overview.mdx @@ -1,20 +1,22 @@ - +--- +title: "Pipeline Overview" +slug: "build-benchmarks/explanation/pipeline-overview.html" +description: "The mcq family is registered in runtime/benchmark_families/registry.py and exposes three entrypoints: prepare_data, generate, and translate." +--- -# Pipeline Overview +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} The `mcq` family is registered in `runtime/benchmark_families/registry.py` and exposes three entrypoints: `prepare_data`, `generate`, and `translate`. `nemotron.steps.byob.scripts.runtime.run_byob` dispatches by `stage`: -| CLI / YAML `stage` | Calls | +| CLI / YAML stage | Calls | | --- | --- | -| `prepare` | `prepare_mcq_data` | -| `generate` | `generate_mcq` | -| `translate` | `translate_mcq` | -| `all` | `prepare_mcq_data` then `generate_mcq` | +| prepare | prepare_mcq_data | +| generate | generate_mcq | +| translate | translate_mcq | +| all | prepare_mcq_data then generate_mcq | `nemotron steps run byob/mcq` executes `mcq/step.py`, which forwards to the BYOB argparse dispatcher in `src/nemotron/steps/byob/scripts/run.py`. @@ -23,13 +25,21 @@ The `mcq` family is registered in `runtime/benchmark_families/registry.py` and e `generate_mcq` in `runtime/benchmark_families/mcq/pipeline.py` writes Parquet files under `output_dir/expt_name/stage_cache/` in this order: 1. **GENERATION** — `generated_questions.parquet` + 2. **JUDGEMENT** — `judged_questions.parquet` + 3. **SEMANTIC_DEDUPLICATION** — `semantic_deduplicated_questions.parquet` (skipped body when `semantic_deduplication_config.enabled` is false, but the file still materializes with duplicate flags) + 4. **DISTRACTOR_EXPANSION** — optional when `do_distractor_expansion` is true + 5. **COVERAGE_CHECK** — optional when `do_coverage_check` is true + 6. **DISTRACTOR_VALIDITY_CHECK** — `valid_distractors.parquet` + 7. **SEMANTIC_OUTLIER_DETECTION** — `semantic_outlier_detection.parquet` + 8. **HALLUCINATION_EASINESS_DETECTION** — `filtered_questions.parquet` + 9. **FINAL_OUTPUT** — copies into `benchmark_raw.parquet`, applies `remove_hallucinated` / `remove_easy`, renames columns, and writes `benchmark.parquet` ## Translate stage order @@ -37,8 +47,11 @@ The `mcq` family is registered in `runtime/benchmark_families/registry.py` and e `translate_mcq` writes: 1. **TRANSLATION** — `stage_cache/translated_questions.parquet` + 2. **BACKTRANSLATION** — `stage_cache/backtranslated_questions.parquet` + 3. **QUALITY_METRICS** — `stage_cache/quality_metrics.parquet` + 4. **FINAL_OUTPUT** — `benchmark_raw.parquet`, optional `remove_low_quality` filter, column rename to the MCQ schema, `benchmark.parquet` -See {doc}`../reference/output-files` for the exact filenames. +See [Output Files](/../reference/output-files) for the exact filenames. diff --git a/docs/build-benchmarks/explanation/quality-validation.md b/docs/fern/pages-vnightly/build-benchmarks/explanation/quality-validation.mdx similarity index 71% rename from docs/build-benchmarks/explanation/quality-validation.md rename to docs/fern/pages-vnightly/build-benchmarks/explanation/quality-validation.mdx index 769accb23..0017bbb48 100644 --- a/docs/build-benchmarks/explanation/quality-validation.md +++ b/docs/fern/pages-vnightly/build-benchmarks/explanation/quality-validation.mdx @@ -1,9 +1,11 @@ - +--- +title: "Quality Validation" +slug: "build-benchmarks/explanation/quality-validation.html" +description: "This page summarizes optional and mandatory checks between generation and the final Parquet export." +--- -# Quality Validation +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} This page summarizes optional and mandatory checks between generation and the final Parquet export. @@ -29,4 +31,4 @@ When `do_coverage_check` is true, `TextCoverageMCQ` analyzes whether generated t `semantic_outlier_detection_config.enabled` toggles `TextSemanticOutlierDetectionMCQ`. When disabled, the stage writes `is_outlier = False` and null neighbour metadata while still emitting the Parquet file expected by later stages. -Each stage writes its own Parquet under `stage_cache/`; see {doc}`../reference/output-files`. +Each stage writes its own Parquet under `stage_cache/`; see [Output Files](/../reference/output-files). diff --git a/docs/build-benchmarks/explanation/question-generation.md b/docs/fern/pages-vnightly/build-benchmarks/explanation/question-generation.mdx similarity index 71% rename from docs/build-benchmarks/explanation/question-generation.md rename to docs/fern/pages-vnightly/build-benchmarks/explanation/question-generation.mdx index f0b6d99c3..39ee6a1e9 100644 --- a/docs/build-benchmarks/explanation/question-generation.md +++ b/docs/fern/pages-vnightly/build-benchmarks/explanation/question-generation.mdx @@ -1,18 +1,20 @@ - +--- +title: "Question Generation" +slug: "build-benchmarks/explanation/question-generation.html" +description: "Understand how the generate stage turns prepared seeds into new multiple-choice question (MCQ) rows, and which YAML settings you control." +--- - +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} -# Question Generation +{/* Explanation: what operators configure for MCQ generation and what the model receives from seed.parquet. */} Understand how the generate stage turns prepared seeds into new multiple-choice question (MCQ) rows, and which YAML settings you control. Generation reads `seed.parquet` from the prepare step, batches work through Data Designer using `generation_model_config` and your prompt templates, and writes `stage_cache/generated_questions.parquet` under `output_dir`/`expt_name`. -For YAML field names and defaults, use {doc}`../reference/generate-config`. -To override packaged prompts, use {doc}`../how-to/prompt-tuning`. +For YAML field names and defaults, use [Generation Configuration Reference](/../reference/generate-config). +To override packaged prompts, use [Prompt Tuning for Benchmarks](/../how-to/prompt-tuning). ## Overview @@ -20,7 +22,9 @@ Question generation uses few-shot prompting so a configured model can draft MCQs Each call combines the following inputs: - Few-shot exemplars that show the answer format and tone you want, drawn from the Hugging Face benchmark you configured during prepare. + - Domain passages taken from your `input_dir` corpora and paired in `seed.parquet`. + - Model parameters under `generation_model_config`, including provider, model id, and `inference_parameters` such as temperature and token limits. ## Few-Shot Prompting @@ -50,7 +54,9 @@ Generate a question based on the content above, following the format of the exam What the model sees: 1. Example MCQs in the target shape. + 2. The domain passage the prepare step attached to that row. + 3. Instructions to match the exemplar format. What the model returns: @@ -68,11 +74,13 @@ To skip translation, you need benchmark rows and a model that both support your After prepare formats the seed for generation, each batch row carries at least: - `text`: domain passage the question must ground on. + - `few_shot_examples`: formatted benchmark exemplars for the prompt. + - `target_subject`: which corpus folder or Parquet target produced the row. Additional columns such as `source_subject`, `tags`, and `language` are carried through for tracing and templating. -Refer to {doc}`../reference/output-files` for the evolving Parquet layout. +Refer to [Output Files](/../reference/output-files) for the evolving Parquet layout. ## Model Configuration @@ -96,6 +104,7 @@ generation_model_config: `temperature` controls randomness in the provider request. - Values closer to zero usually produce steadier, more repeatable wording. + - Higher values increase variety but can also increase refusals or off-format answers, so raise them gradually while you watch `generated_questions.parquet`. `max_parallel_requests` caps concurrent calls per batch; balance it against provider rate limits. @@ -104,11 +113,14 @@ generation_model_config: New rows move through validation and cleanup stages before they become `benchmark.parquet`, including judgement, optional semantic deduplication, distractor expansion when enabled, optional coverage scoring, semantic outlier scoring, and easiness or hallucination filtering. -Read {doc}`quality-validation` for the full stage list and artifacts, {doc}`filtering` for threshold behavior, and {doc}`../reference/output-files` for filenames under `stage_cache/`. +Read [Quality Validation](/quality-validation) for the full stage list and artifacts, [Easiness and Hallucination Filtering](/filtering) for threshold behavior, and [Output Files](/../reference/output-files) for filenames under `stage_cache/`. ## Next Steps -- {doc}`quality-validation` for the checks that run after `generated_questions.parquet`. -- {doc}`filtering` for how easy or hallucinated items are removed or retained. -- {doc}`pipeline-overview` for where generate sits in the `mcq` family. -- {doc}`data-preparation` for how `seed.parquet` is built upstream. +- [Quality Validation](/quality-validation) for the checks that run after `generated_questions.parquet`. + +- [Easiness and Hallucination Filtering](/filtering) for how easy or hallucinated items are removed or retained. + +- [Pipeline Overview](/pipeline-overview) for where generate sits in the `mcq` family. + +- [Data Preparation for Multiple-Choice Question Benchmarks](/data-preparation) for how `seed.parquet` is built upstream. diff --git a/docs/build-benchmarks/explanation/translation.md b/docs/fern/pages-vnightly/build-benchmarks/explanation/translation.mdx similarity index 53% rename from docs/build-benchmarks/explanation/translation.md rename to docs/fern/pages-vnightly/build-benchmarks/explanation/translation.mdx index 99a6cc2d1..469b47183 100644 --- a/docs/build-benchmarks/explanation/translation.md +++ b/docs/fern/pages-vnightly/build-benchmarks/explanation/translation.mdx @@ -1,27 +1,29 @@ - +--- +title: "Translation" +slug: "build-benchmarks/explanation/translation.html" +description: "Learn how to take an existing benchmark.parquet from generation, translate it to a target locale, score quality with backtranslation metrics, and export another benchmark.parquet." +--- - +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} -# Translation +{/* Explanation: translation YAML, quality gates, and operator-visible artifacts for BYOB MCQ translate. */} Learn how to take an existing `benchmark.parquet` from generation, translate it to a target locale, score quality with backtranslation metrics, and export another `benchmark.parquet`. -The field names, defaults, and validation rules are listed in {doc}`../reference/translation-config`. -Artifact paths are summarized in {doc}`../reference/output-files`. +The field names, defaults, and validation rules are listed in [Translation Configuration Reference](/../reference/translation-config). +Artifact paths are summarized in [Output Files](/../reference/output-files). ## What You Configure | Control | What you set | | --- | --- | -| `dataset_path` | Absolute or workspace path to the source `benchmark.parquet` you want translated. | -| `output_dir` / `expt_name` | Where caches and the translated `benchmark.parquet` are written. | -| `source_language` / `target_language` | BCP-47 style tags, for example `en-US` and `hi-IN`. | -| `translation_model_config` | Curator experimental translation block: `backend_type`, `params` (model, provider, credentials, `inference_parameters`), plus optional `stage` and `segment_stage` maps. | -| `backtranslation_quality_metrics` | List of `{type, threshold}` entries. Each `type` must be `sacrebleu`, `chrf`, or `ter`; each `threshold` must be nonnegative. Keep at least one entry so scoring runs; outputs land in `quality_metrics.parquet` with per-metric scores and `is_quality_metric_passed`. | -| `remove_low_quality` | When `true` (the default if you omit the key), rows that fail the aggregate quality gate are dropped before the final export. When `false`, every row is kept so you can inspect scores first. | +| dataset_path | Absolute or workspace path to the source benchmark.parquet you want translated. | +| output_dir / expt_name | Where caches and the translated benchmark.parquet are written. | +| source_language / target_language | BCP-47 style tags, for example en-US and hi-IN. | +| translation_model_config | Curator experimental translation block: backend_type, params (model, provider, credentials, inference_parameters), plus optional stage and segment_stage maps. | +| backtranslation_quality_metrics | List of {type, threshold} entries. Each type must be sacrebleu, chrf, or ter; each threshold must be nonnegative. Keep at least one entry so scoring runs; outputs land in quality_metrics.parquet with per-metric scores and is_quality_metric_passed. | +| remove_low_quality | When true (the default if you omit the key), rows that fail the aggregate quality gate are dropped before the final export. When false, every row is kept so you can inspect scores first. | Do not set `translation_model_config.stage.enable_faith_eval` to true. Translation relies on backtranslation metrics instead of FAITH. @@ -46,13 +48,13 @@ After a run, open `quality_metrics.parquet` under `output_dir`/`expt_name`/`stag - `remove_low_quality` decides whether failing rows disappear from the exported `benchmark.parquet`. - ```yaml - remove_low_quality: true # omit to get the same default - ``` + ```yaml + remove_low_quality: true # omit to get the same default + ``` - ```yaml - remove_low_quality: false # keep failing rows; filter manually using Parquet columns - ``` + ```yaml + remove_low_quality: false # keep failing rows; filter manually using Parquet columns + ``` ## Reference Layout @@ -108,7 +110,10 @@ Use the intermediate files to debug language mix-ups, threshold misses, or model ## Related Information -- {doc}`../reference/translation-config` for every required and optional YAML key. -- {doc}`../how-to/custom-model-endpoints` for credentials and base URLs on your model blocks. -- {doc}`../how-to/skip-stages` when you need to rerun only translation or downstream stages after a config tweak. -- {doc}`pipeline-overview` to see where translate sits after generate. +- [Translation Configuration Reference](/../reference/translation-config) for every required and optional YAML key. + +- [Configure Model Endpoints for BYOB](/../how-to/custom-model-endpoints) for credentials and base URLs on your model blocks. + +- [Skip Stages When Iterating](/../how-to/skip-stages) when you need to rerun only translation or downstream stages after a config tweak. + +- [Pipeline Overview](/pipeline-overview) to see where translate sits after generate. diff --git a/docs/fern/pages-vnightly/build-benchmarks/getting-started.mdx b/docs/fern/pages-vnightly/build-benchmarks/getting-started.mdx new file mode 100644 index 000000000..184f8bc2e --- /dev/null +++ b/docs/fern/pages-vnightly/build-benchmarks/getting-started.mdx @@ -0,0 +1,107 @@ +--- +title: "Getting Started with Building MCQ Benchmarks" +slug: "build-benchmarks/getting-started.html" +description: "In this tutorial, you will:" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + +{/* Tutorial: end-to-end `tiny` BYOB run; about 10 to 15 minutes including model waits; requires Nemotron clone, uv, BYOB extra, and NVIDIA_API_KEY. */} + + + +**In this tutorial, you will**: + +1. Install Python dependencies. + +2. Run the `tiny` configuration from the repository root. + +3. Locate outputs and scan the main Parquet artifacts. + +4. Confirm `benchmark.parquet` columns against the output reference. + + This tutorial requires between 10 and 15 minutes to complete. + + + + +Help me create an MCQ benchmark using the `tiny` configuration from the Nemotron repository clone, write outputs under `./output`, then show me which Parquet files to open first. + + + + + +## Start Here + +- Run all commands from the repository root so the `input_dir` path in the procedure resolves. + +- The sample configuration uses the `cais/mmlu` dataset from Hugging Face for few-shot examples of multiple-choice questions. + +- The sample configuration uses the `src/nemotron/steps/byob/data/tiny_input/maths/tiny.txt` file for input. + + ```default startLine={1} + Algebra studies symbols and the rules for manipulating them. Linear equations can model simple relationships, such as converting between a starting value and a constant rate of change. + ``` + +## Prerequisites + +- You have a host with access to https://integrate.api.nvidia.com. + +- The `uv` tool available in your shell. + +- `NVIDIA_API_KEY` exported in the same shell session before you run the procedure. +The default model for the configuration is `openai/gpt-oss-120b`. + +## Procedure + +1. Clone the repository: + + ```console + git clone https://github.com/NVIDIA-NeMo/Nemotron && cd Nemotron + ``` + +1. From the repository root, add the dependencies for building benchmarks: + + ```console + uv sync --extra byob + ``` + +1. Run generation with host paths. +The `tiny` configuration sets `stage: all`. +This stage setting chains the data preparation and then generation for MCQ. + + ```console + uv run nemotron steps run byob/mcq \ + -c tiny \ + family=mcq \ + stage=all \ + input_dir="./src/nemotron/steps/byob/data/tiny_input" \ + output_dir=./byob-output + ``` + + When the `-c` / `--config` argument is not a path, the command resolves the config file name in the `src/nemotron/steps/byob/mcq/config/` directory. + + When the command finishes, list the `./byob-output/byob_mcq_tiny/` directory. +The `expt_name` field in the `src/nemotron/steps/byob/mcq/config/tiny.yaml` file specifies that directory. +Look for the following files: + + - `stage_cache/*.parquet`, one file per intermediate stage, described in [Output Files](/reference/output-files) + + - `benchmark_raw.parquet`, the full row set before optional removals + + - `benchmark.parquet`, the final `mcq` schema for downstream use + +1. Open `benchmark.parquet` with Pandas, Polars, or another Parquet-aware tool and confirm columns match [Output Files](/reference/output-files). + +## Next Steps + +For background on how stages connect, read [Pipeline Overview](/explanation/pipeline-overview). +For task-focused changes, continue with: + +- Swap in your own corpus and mapping: [Prepare Your Own Domain Data](/how-to/prepare-data). + +- Tune endpoints and keys: [Configure Model Endpoints for BYOB](/how-to/custom-model-endpoints). diff --git a/docs/build-benchmarks/how-to/custom-model-endpoints.md b/docs/fern/pages-vnightly/build-benchmarks/how-to/custom-model-endpoints.mdx similarity index 79% rename from docs/build-benchmarks/how-to/custom-model-endpoints.md rename to docs/fern/pages-vnightly/build-benchmarks/how-to/custom-model-endpoints.mdx index 652bdb917..72fe43155 100644 --- a/docs/build-benchmarks/how-to/custom-model-endpoints.md +++ b/docs/fern/pages-vnightly/build-benchmarks/how-to/custom-model-endpoints.mdx @@ -1,9 +1,11 @@ - - -# Configure Model Endpoints for BYOB +--- +title: "Configure Model Endpoints for BYOB" +slug: "build-benchmarks/how-to/custom-model-endpoints.html" +description: "BYOB does not ship model weights. Instead, YAML blocks describe OpenAI-compatible clients for each stage that calls a language model." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} BYOB does not ship model weights. Instead, YAML blocks describe OpenAI-compatible clients for each stage that calls a language model. diff --git a/docs/build-benchmarks/how-to/domain-data.md b/docs/fern/pages-vnightly/build-benchmarks/how-to/domain-data.mdx similarity index 78% rename from docs/build-benchmarks/how-to/domain-data.md rename to docs/fern/pages-vnightly/build-benchmarks/how-to/domain-data.mdx index 48bf0f9d3..db16867d8 100644 --- a/docs/build-benchmarks/how-to/domain-data.md +++ b/docs/fern/pages-vnightly/build-benchmarks/how-to/domain-data.mdx @@ -1,11 +1,13 @@ - +--- +title: "Using Your Own Domain Data" +slug: "build-benchmarks/how-to/domain-data.html" +description: "Use this tutorial to learn how to build your own benchmark with your own domain text." +--- - +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} -# Using Your Own Domain Data +{/* How-to: lay out bring your own benchmark (BYOB) `input_dir` with one UTF-8 `.txt` corpus per `target_source_mapping` key. Use when you supply your own domain text and need the directory layout the prepare step expects. */} Use this tutorial to learn how to build your own benchmark with your own domain text. @@ -14,7 +16,9 @@ You will create a parent folder, your `input_dir`, with one subdirectory per key When you finish the steps below, the prepare stage can build stems from your corpora together with your Hugging Face subject wiring. - Each directory name directly under `input_dir` must match a key in `target_source_mapping`, for example `banking`, `police`, or `maths`. + - Split long material across several `.txt` files when you want different documents to drive different queries. + - Set `input_dir` in YAML to the parent directory so `uv run nemotron steps run byob/mcq` resolves relative paths from the shell working directory, or use an absolute path for a fixed location. ## Step 1: Create Target Directories @@ -31,6 +35,7 @@ mkdir -p ./data/byob/maths Path tips: - Prefer absolute paths in YAML when several people reuse the same file from different working directories. + - Relative paths resolve from the shell working directory where you invoke `uv run nemotron steps run byob/mcq`. The pipeline resolves `input_dir` relative to that working directory. @@ -45,7 +50,7 @@ Place UTF-8 text under each target directory. Use several smaller files instead of one huge blob when you want different documents to drive different queries. ```bash -cat > ./data/byob/banking/intro.txt << 'EOF' +cat > ./data/byob/banking/intro.txt \<\< 'EOF' Modern banking in India originated in the mid-18th century... EOF ``` @@ -78,28 +83,33 @@ target_source_mapping: - high_school_mathematics ``` -Allowed `hf_dataset` values and default `subset` / `split` behavior are listed in {doc}`../reference/benchmarks`. +Allowed `hf_dataset` values and default `subset` / `split` behavior are listed in [Supported Hugging Face Benchmarks](/../reference/benchmarks). ## Best Practices ### Content Quality - Aim for a few thousand characters per document when you want diverse stems without exhausting context. + - Prefer complete explanations over fragments so judges and filters see coherent context. + - Strip or replace personally identifiable information before you run in shared environments. ### Organization - Keep one domain taxonomy per directory; do not mix unrelated subjects under the same target key. + - Split long manuals into several `.txt` files so `queries_per_target_subject_document` can visit different offsets. ### Performance and Chunking - Pilot with a handful of documents per target before scaling out. + - Use `chunking_config.window_size` when you need sliding windows over very long text; `null` keeps each file as one unit. - Field detail is in {doc}`../reference/generate-config`. +Field detail is in [Generation Configuration Reference](/../reference/generate-config). ## Next Steps -- Run prepare alone or the full pipeline after you align YAML: {doc}`prepare-data`. -- Inspect `seed.parquet` and downstream paths in {doc}`../reference/output-files`. +- Run prepare alone or the full pipeline after you align YAML: [Prepare Your Own Domain Data](/prepare-data). + +- Inspect `seed.parquet` and downstream paths in [Output Files](/../reference/output-files). diff --git a/docs/fern/pages-vnightly/build-benchmarks/how-to/index.mdx b/docs/fern/pages-vnightly/build-benchmarks/how-to/index.mdx new file mode 100644 index 000000000..d86d0748a --- /dev/null +++ b/docs/fern/pages-vnightly/build-benchmarks/how-to/index.mdx @@ -0,0 +1,87 @@ +--- +title: "How-To Guides" +slug: "build-benchmarks/how-to/index.html" +description: "Task-focused guides for nemotron steps run byob/mcq with the mcq family." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +Task-focused guides for `nemotron steps run byob/mcq` with the `mcq` family. + +Start with [Getting Started with Building MCQ Benchmarks](/../getting-started) if you have not produced `benchmark.parquet` yet. + +## Setup and configuration + + + +Lay out `input_dir`, text or Parquet inputs, and `target_source_mapping`. + +--- + +input_dir + + + + +Create per-target directories of `.txt` files and match them to YAML. + +--- + +corpus + + + + +Configure OpenAI-compatible providers for generation, judgement, expansion, validity, and filters. + +--- + +yaml + + + + + +## Advanced workflows + + + +Point `prompt_config` at a YAML file that defines stage templates. + +--- + +prompt + + + + +Resume with `skip_until` and cached Parquet files. + +--- + +iteration + + + + + +## Workflow overview + +```mermaid +flowchart LR + A[Prepare data layout] --> B[Edit YAML] + B --> C[uv run nemotron steps run byob/mcq] + C --> D{Need translation?} + D -->|yes| E[translate config + passthrough] + D -->|no| F[Done] + E --> F + C -.->|iterate| G[skip_until] + G --> C +``` + +## Related documentation + +- [Concepts](/../explanation/index) — how each stage behaves. + +- [Reference](/../reference/index) — full field lists and allowed datasets. diff --git a/docs/build-benchmarks/how-to/prepare-data.md b/docs/fern/pages-vnightly/build-benchmarks/how-to/prepare-data.mdx similarity index 63% rename from docs/build-benchmarks/how-to/prepare-data.md rename to docs/fern/pages-vnightly/build-benchmarks/how-to/prepare-data.mdx index e4b7d4d89..a77b61965 100644 --- a/docs/build-benchmarks/how-to/prepare-data.md +++ b/docs/fern/pages-vnightly/build-benchmarks/how-to/prepare-data.mdx @@ -1,11 +1,13 @@ - +--- +title: "Prepare Your Own Domain Data" +slug: "build-benchmarks/how-to/prepare-data.html" +description: "This guide shows how to place domain text under input_dir, map each target key in target_source_mapping, and set the positive integers that control how much work prepare does per document." +--- - +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} -# Prepare Your Own Domain Data +{/* How-to: lay out `input_dir`, wire `target_source_mapping`, and set sampling counts before running the prepare stage. Use when you already have a BYOB configuration and need a concrete checklist for local inputs. */} This guide shows how to place domain text under `input_dir`, map each target key in `target_source_mapping`, and set the positive integers that control how @@ -15,9 +17,9 @@ Use this guide when your configuration points at local sources and you want to validate layout before you run prepare or the full pipeline. For how prepare joins few-shot rows and domain text, see -{doc}`../explanation/data-preparation`. -For a filesystem-first walkthrough of directories and Parquet basenames, see {doc}`domain-data`. -Field-by-field options for the whole step live in {doc}`../reference/generate-config`. +[Data Preparation for Multiple-Choice Question Benchmarks](/../explanation/data-preparation). +For a filesystem-first walkthrough of directories and Parquet basenames, see [Using Your Own Domain Data](/domain-data). +Field-by-field options for the whole step live in [Generation Configuration Reference](/../reference/generate-config). ## Directory Layout @@ -28,8 +30,9 @@ For each key in `target_source_mapping`, supply one of the following next to `input_dir`: - A directory `input_dir//` that contains at least one `.txt` file. + - A Parquet file `input_dir/.parquet` whose rows include the columns the - loader expects, described in {doc}`../explanation/data-preparation`. +loader expects, described in [Data Preparation for Multiple-Choice Question Benchmarks](/../explanation/data-preparation). If both a directory and a file named `.parquet` exist, the loader prefers the directory and logs a warning. @@ -48,11 +51,13 @@ Each target entry in `target_source_mapping` carries a `subjects` value in one of two shapes: - A list of source subject names selects those rows with uniform weights. + - An empty list means use every entry in `source_subjects`, again with uniform - weights. +weights. + - A mapping from source subject name to a non-negative weight defines a - weighted mixture, and weights must sum to a value greater than zero. - The loader normalizes them internally. +weighted mixture, and weights must sum to a value greater than zero. +The loader normalizes them internally. Optional `tags` on a target pair with `metadata_file` when you supply tag metadata from a file. @@ -65,17 +70,19 @@ These positive integers live in the same configuration as the rest of the step and control how much generation work each stored document drives: - `few_shot_samples_per_query` caps how many few-shot exemplar rows feed each - query. +query. + - `queries_per_target_subject_document` sets how many queries run per domain - document. +document. + - `num_questions_per_query` sets how many questions each query produces. They must all be greater than zero. -Short definitions also appear in the tables under {doc}`../reference/generate-config`. +Short definitions also appear in the tables under [Generation Configuration Reference](/../reference/generate-config). ## Hugging Face Dataset -Set `hf_dataset` to one of the identifiers listed in {doc}`../reference/benchmarks`. +Set `hf_dataset` to one of the identifiers listed in [Supported Hugging Face Benchmarks](/../reference/benchmarks). If you omit `subset` or `split`, defaults come from `HF_DATASET_TO_SUBSET` and the loader logic in `ByobConfig.from_yaml`. @@ -84,4 +91,4 @@ the loader logic in `ByobConfig.from_yaml`. Set `stage: prepare` in your configuration file. Prepare writes the seed artifact that generate consumes. -The file names and roles are listed in {doc}`../reference/output-files`. +The file names and roles are listed in [Output Files](/../reference/output-files). diff --git a/docs/build-benchmarks/how-to/prompt-tuning.md b/docs/fern/pages-vnightly/build-benchmarks/how-to/prompt-tuning.mdx similarity index 54% rename from docs/build-benchmarks/how-to/prompt-tuning.md rename to docs/fern/pages-vnightly/build-benchmarks/how-to/prompt-tuning.mdx index 09a275043..f91198c71 100644 --- a/docs/build-benchmarks/how-to/prompt-tuning.md +++ b/docs/fern/pages-vnightly/build-benchmarks/how-to/prompt-tuning.mdx @@ -1,12 +1,15 @@ - +--- +title: "Prompt Tuning for Benchmarks" +slug: "build-benchmarks/how-to/prompt-tuning.html" +description: "The build-your-own benchmark (BYOB) pipeline for multiple-choice questions (MCQs) runs several stages that each call a large language model (LLM). Each stage reads prompt text from your configuration." +--- - +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} -(byob-mcq-prompt-tuning)= -# Prompt Tuning for Benchmarks +{/* How-to: point `prompt_config` at a YAML override for BYOB MCQ stages, keep placeholders valid, and run the step. Use when packaged prompts are close but you need different wording or guardrails. */} + + The build-your-own benchmark (BYOB) pipeline for multiple-choice questions (MCQs) runs several stages that each call a large language model (LLM). Each stage reads prompt text from your configuration. @@ -14,8 +17,8 @@ You can replace the packaged wording to change tone, difficulty, guardrails, and Use this guide when packaged prompts are almost right and you want different instructions, tone, or few-shot examples without changing stage order or the expected output shape. -For every field on the main experiment YAML file, see {doc}`../reference/generate-config`. -For load-time validation errors, see {doc}`../reference/troubleshooting`. +For every field on the main experiment YAML file, see [Generation Configuration Reference](/../reference/generate-config). +For load-time validation errors, see [Troubleshooting](/../reference/troubleshooting). ## Point the experiment file at your prompts @@ -53,12 +56,12 @@ You must include every stage even when you only intend to change one of them. | Stage key | Role in the pipeline | | --- | --- | -| `qa_generation` | Creates new questions with four choices from the seed passage and few-shot examples. | -| `question_judge` | Scores clarity, validity, and knowledge versus reasoning style. | -| `hallucination_filter` | Asks filter models to answer with the passage present to catch unsupported content. | -| `easiness_filter` | Asks filter models to answer without the passage to catch questions that are too easy. | -| `distractor_expansion` | Adds six distractors when expansion is enabled in the main configuration file. | -| `distractor_validity` | Checks that only the labeled answer is correct given the passage. | +| qa_generation | Creates new questions with four choices from the seed passage and few-shot examples. | +| question_judge | Scores clarity, validity, and knowledge versus reasoning style. | +| hallucination_filter | Asks filter models to answer with the passage present to catch unsupported content. | +| easiness_filter | Asks filter models to answer without the passage to catch questions that are too easy. | +| distractor_expansion | Adds six distractors when expansion is enabled in the main configuration file. | +| distractor_validity | Checks that only the labeled answer is correct given the passage. | ## How Placeholders Work @@ -66,23 +69,26 @@ Prompt strings are not plain static prose. They carry two different kinds of markers, and some stages use both kinds in the same string. *NeMo Data Designer* substitutes *seed column* markers. -After any earlier formatting, those markers look like `{{column_name}}` and pull values from the CSV row the stage is processing. +After any earlier formatting, those markers look like `\{\{column_name\}\}` and pull values from the CSV row the stage is processing. -Some stages run an earlier pass that substitutes *run-parameter* markers written with single braces, such as `{num_questions}`. +Some stages run an earlier pass that substitutes *run-parameter* markers written with single braces, such as `\{num_questions\}`. Those values come from your main experiment configuration file or from small integers the pipeline derives before Data Designer runs. -Packaged templates sometimes show column names with four braces, for example `{{{{target_subject}}}}`. -That pattern survives the run-parameter pass and leaves a normal `{{target_subject}}` marker for Data Designer. +Packaged templates sometimes show column names with four braces, for example `\{\{\{\{target_subject\}\}\}\}`. +That pattern survives the run-parameter pass and leaves a normal `\{\{target_subject\}\}` marker for Data Designer. If a stage forwards both strings as written, the pipeline does not apply the single-brace pass. -Every `{{column_name}}` token you leave in YAML must match a real column in that stage’s seed data. +Every `\{\{column_name\}\}` token you leave in YAML must match a real column in that stage’s seed data. ### Common Run-Parameter Tokens -- `{num_few_shot_samples}` is the few-shot count from the main configuration file. -- `{num_questions}` is the questions per query from the main configuration file. -- `{num_choices}` either rewritten for filter stages so Data Designer can inject `{{num_choices}}`, or replaced with the integer `4` or `10` for distractor validity’s system prompt. -- `{choices}` rewritten during filtering so Data Designer receives `{{choices_text}}` for the rendered choice list on each row. +- `\{num_few_shot_samples\}` is the few-shot count from the main configuration file. + +- `\{num_questions\}` is the questions per query from the main configuration file. + +- `\{num_choices\}` either rewritten for filter stages so Data Designer can inject `\{\{num_choices\}\}`, or replaced with the integer `4` or `10` for distractor validity’s system prompt. + +- `\{choices\}` rewritten during filtering so Data Designer receives `\{\{choices_text\}\}` for the rendered choice list on each row. ### Column Markers Copied from Packaged Templates @@ -90,27 +96,30 @@ The list below shows fields that appear in the sample files. Quadruple-brace forms are common in `qa_generation` and in some filter user prompts. Judging prompts use ordinary double braces because that stage is forwarded as written. -- `{{{{target_subject}}}}` — subject label for the target passage. -- `{{{{text}}}}` — source passage body. -- `{{{{few_shot_examples}}}}` — serialized few-shot examples. -- `{{{{language}}}}` — target locale string for generation. -- `{{{{question_generated_formatted}}}}` — question plus choices as produced upstream. -- `{{question}}` — generated question text for the judge stage. +- `\{\{\{\{target_subject\}\}\}\}` — subject label for the target passage. + +- `\{\{\{\{text\}\}\}\}` — source passage body. + +- `\{\{\{\{few_shot_examples\}\}\}\}` — serialized few-shot examples. + +- `\{\{\{\{language\}\}\}\}` — target locale string for generation. + +- `\{\{\{\{question_generated_formatted\}\}\}\}` — question plus choices as produced upstream. + +- `\{\{question\}\}` — generated question text for the judge stage. ## Example: QA Generation Block Use the layout from `src/nemotron/steps/byob/runtime/benchmark_families/mcq/prompts/qa_generation.py` as a starting point when you author your own file. -```{code-block} yaml -:class: scrollable - +```yaml qa_generation: system_prompt: | You are an expert in creating questions from a description of a given topic. - You will be given {num_few_shot_samples} example questions and answers unrelated to the topic. + You will be given \{num_few_shot_samples\} example questions and answers unrelated to the topic. You should - 1. Create {num_questions} questions, four choices and answers similar to the example question answer. + 1. Create \{num_questions\} questions, four choices and answers similar to the example question answer. 2. Follow the question style of the example question answers (Direct WH question/Completion/Best explanation/Best action/Equivalence/Other). 3. Try to create questions that are higher in the cognitive level scale, by mostly using concepts from the text passage. 4. The questions should not explicitly refer to the passage or example question answer. @@ -132,19 +141,18 @@ qa_generation: 5: Evaluate The question requires judgment among alternatives based on criteria, or synthesizing information to choose the best course of action or construct a plan (e.g., select the most appropriate investment strategy for a given Indian retail investor scenario). + Create \{num_questions\} questions, four choices and answers for the given topic: + Topic: {{{\{target_subject\}}}} + \ + {{{\{text\}}}} + \ - Create {num_questions} questions, four choices and answers for the given topic: - Topic: {{{{target_subject}}}} - - {{{{text}}}} - - - Now make {num_questions} questions, four choices and answers for the topic similar to the example question answer. Don't make the answer too obvious. + Now make \{num_questions\} questions, four choices and answers for the topic similar to the example question answer. Don't make the answer too obvious. Example questions and answers:- - {{{{few_shot_examples}}}} + {{{\{few_shot_examples\}}}} - Write the questions and options in the language: {{{{language}}}} + Write the questions and options in the language: {{{\{language\}}}} Return the questions in JSON format with each question having the following fields: - question: The question - choice_a: The first choice (A) @@ -164,66 +172,66 @@ Forwarded as written, so only double-brace column names appear. ```text Here is the question: -Question: {{question}} +Question: {\{question\}} ``` ### Filtering -The system line keeps `{num_choices}` in YAML. -The pipeline rewrites it so Data Designer later fills `{{num_choices}}` per row. +The system line keeps `\{num_choices\}` in YAML. +The pipeline rewrites it so Data Designer later fills `\{\{num_choices\}\}` per row. ```text -You are answering a multiple-choice question with {num_choices} choices. +You are answering a multiple-choice question with \{num_choices\} choices. You will be given a passage on a topic and a question and a list of choices. ``` -The hallucination user prompt carries passage markers, the formatted question, and `{choices}`, which becomes `{{choices_text}}` for Data Designer. +The hallucination user prompt carries passage markers, the formatted question, and `\{choices\}`, which becomes `\{\{choices_text\}\}` for Data Designer. ```text -Topic: {{{{target_subject}}}} - -{{{{text}}}} - +Topic: {{{\{target_subject\}}}} +\ +{{{\{text\}}}} +\ Answer the following question: -{{{{question_generated_formatted}}}} +{{{\{question_generated_formatted\}}}} -The answer should be one of {choices}. Think step by step and then finish your answer with "The answer is (X)" where X is the correct letter choice. +The answer should be one of \{choices\}. Think step by step and then finish your answer with "The answer is (X)" where X is the correct letter choice. ``` -The easiness filter reuses the same `{num_choices}` and `{choices}` contract on the system and user strings but omits the topic and passage block. +The easiness filter reuses the same `\{num_choices\}` and `\{choices\}` contract on the system and user strings but omits the topic and passage block. Copy each filter stage from its own packaged default instead of swapping strings between them. ### Distractor Validity -Only the system line runs the single-brace pass, replacing `{num_choices}` with the integer `4` or `10`. +Only the system line runs the single-brace pass, replacing `\{num_choices\}` with the integer `4` or `10`. ```text -The question claims that there is only one correct answer among the {num_choices} choices. +The question claims that there is only one correct answer among the \{num_choices\} choices. ``` -The user `prompt` is forwarded as written; keep its `{{column}}` names aligned with the packaged file. +The user `prompt` is forwarded as written; keep its `\{\{column\}\}` names aligned with the packaged file. ## Stage-by-Stage Formatting Checklist Use this table when you need a compact reminder of where single-brace substitution runs. -| Stage | Single-brace pass on `system_prompt` | Single-brace pass on `prompt` | +| Stage | Single-brace pass on system_prompt | Single-brace pass on prompt | | --- | --- | --- | -| `qa_generation` | Yes, `{num_few_shot_samples}` and `{num_questions}` | Yes, `{num_questions}` only | -| `question_judge` | No | No | -| `hallucination_filter` | Yes, `{num_choices}` becomes `{{num_choices}}` | Yes, `{choices}` becomes `{{choices_text}}` | -| `easiness_filter` | Same as hallucination | Same as hallucination | -| `distractor_expansion` | No | No | -| `distractor_validity` | Yes, `{num_choices}` becomes `4` or `10` | No | +| qa_generation | Yes, {num_few_shot_samples} and {num_questions} | Yes, {num_questions} only | +| question_judge | No | No | +| hallucination_filter | Yes, {num_choices} becomes {{num_choices}} | Yes, {choices} becomes {{choices_text}} | +| easiness_filter | Same as hallucination | Same as hallucination | +| distractor_expansion | No | No | +| distractor_validity | Yes, {num_choices} becomes 4 or 10 | No | `distractor_expansion` is fully forwarded, so treat it like judging for placeholder editing rules. ## Practical Tips Duplicate an entire packaged stage before you delete lines. -Partial copies are the most common source of missing `{{column}}` names. +Partial copies are the most common source of missing `\{\{column\}\}` names. When you only need small wording edits, change sentences around the placeholder lines first and leave the markers alone until you must move them. diff --git a/docs/build-benchmarks/how-to/skip-stages.md b/docs/fern/pages-vnightly/build-benchmarks/how-to/skip-stages.mdx similarity index 68% rename from docs/build-benchmarks/how-to/skip-stages.md rename to docs/fern/pages-vnightly/build-benchmarks/how-to/skip-stages.mdx index e1f1910d1..be2d52ba8 100644 --- a/docs/build-benchmarks/how-to/skip-stages.md +++ b/docs/fern/pages-vnightly/build-benchmarks/how-to/skip-stages.mdx @@ -1,9 +1,11 @@ - +--- +title: "Skip Stages When Iterating" +slug: "build-benchmarks/how-to/skip-stages.html" +description: "Both generate and translate honor skip_until, a string that names an enum entry on the internal stage list. Stages whose enum value is less than the named stage are skipped as long as the expected Par" +--- -# Skip Stages When Iterating +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} Both **generate** and **translate** honor `skip_until`, a string that names an enum entry on the internal stage list. Stages whose enum value is **less than** the named stage are skipped as long as the expected Parquet already exists. @@ -37,4 +39,4 @@ uv run nemotron steps run byob/mcq -c translate stage=translate skip_until=BACKT Skipping only works when the Parquet file produced by the previous stage is already on disk under `output_dir/expt_name/stage_cache/`. Otherwise the next stage reads missing input and fails. -For other common failure modes, see {doc}`../reference/troubleshooting`. +For other common failure modes, see [Troubleshooting](/../reference/troubleshooting). diff --git a/docs/fern/pages-vnightly/build-benchmarks/index.mdx b/docs/fern/pages-vnightly/build-benchmarks/index.mdx new file mode 100644 index 000000000..0cd7bad72 --- /dev/null +++ b/docs/fern/pages-vnightly/build-benchmarks/index.mdx @@ -0,0 +1,160 @@ +--- +title: "About Building Multiple-Choice Question Benchmarks" +slug: "build-benchmarks/index.html" +description: "This section describes how to build a custom multiple-choice question (MCQ) benchmark as Apache Parquet files with the nemotron steps run byob/mcq command. You supply domain text files under input_dir" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + +{/* Explanation and navigation hub for the bring your own benchmark (BYOB) MCQ series. */} + +This section describes how to build a custom multiple-choice question (MCQ) benchmark as Apache Parquet files with the `nemotron steps run byob/mcq` command. +You supply domain text files under `input_dir`, and the pipeline samples few-shot exemplars from a Hugging Face benchmark named in your configuration, such as `cais/mmlu`. +The configuration specifies subject filters such as `high_school_mathematics`. + +The benchmark step prepares seed rows, generates and judges questions, runs optional deduplication and distractor stages, and writes `benchmark.parquet`. +An optional translation stage reads an existing benchmark and writes another `benchmark.parquet` with the same column layout. + + +New to this flow? Follow [Getting Started with Building MCQ Benchmarks](/getting-started) once, then use the grids and tables below to jump to how-to guides, concepts, or reference pages. + + + +## When to Use + +The `nemotron steps run byob/mcq` command enables the following outcomes. + +- Questions grounded in your own documents, paired with few-shot items from a public benchmark subject you declare in configuration. + +- A repeatable Parquet artifact, one experiment folder under your configured `output_dir`, plus intermediate caches when you iterate. + +- Optional translation with forward passes, backtranslation, and metric thresholds before you export another Parquet benchmark. + +## Pipeline Summary + +At a high level, the benchmark step performs the following work. + +1. Prepare: sample few-shot examples and align them with chunks from your corpus into a seed dataset. + +2. Generate: run the staged MCQ pipeline from generation through filtering into `benchmark_raw.parquet` and `benchmark.parquet`. + +3. Translate, optional: translate questions and options, score backtranslation quality, and export a new `benchmark.parquet`. + +## Documentation Series + + + +Install the `byob` extra, run the sample `tiny` configuration with local paths, and inspect Parquet outputs. +The `tiny` fixture pairs `cais/mmlu` high school mathematics few-shots with a one-line input file related to algebra. + +--- + +hands-on + + + + +Prepare data, tune models in YAML, customize prompts, and resume with `skip_until`. + +--- + +task-based + + + + +How prepare, generate, and translate stages fit together and what each configuration block does. + +--- + +concept-focused + + + + +Supported Hugging Face datasets, Parquet outputs, and YAML fields. + +--- + +specification + + + + + +## All Documentation + + + + +| Guide | What you will do | +| --- | --- | +| [Getting Started with Building MCQ Benchmarks](/getting-started) | Run nemotron steps run byob/mcq with tiny and inspect outputs | + + + + +| Guide | What you will do | +| --- | --- | +| [Prepare Your Own Domain Data](/how-to/prepare-data) | Lay out input_dir and target_source_mapping | +| [Using Your Own Domain Data](/how-to/domain-data) | Lay out per-target .txt corpora under input_dir | +| [Configure Model Endpoints for BYOB](/how-to/custom-model-endpoints) | Point generation, judgement, and filter models at your endpoints | +| [Prompt Tuning for Benchmarks](/how-to/prompt-tuning) | Override prompts with a YAML file | +| [Skip Stages When Iterating](/how-to/skip-stages) | Resume after intermediate Parquet caches | + + + + +| Guide | What you will learn | +| --- | --- | +| [Pipeline Overview](/explanation/pipeline-overview) | Stage order for prepare, generate, and translate | +| [Data Preparation for Multiple-Choice Question Benchmarks](/explanation/data-preparation) | Seeds, chunking, and the prepare step | +| [Getting the Right Questions From the Source Benchmark](/explanation/get-right-questions) | source_subjects and target_source_mapping | +| [Question Generation](/explanation/question-generation) | Data Designer batched generation | +| [Quality Validation](/explanation/quality-validation) | Judgement, deduplication, distractors, coverage, outliers | +| [Easiness and Hallucination Filtering](/explanation/filtering) | Easiness and hallucination filters | +| [Translation](/explanation/translation) | Curator translation and backtranslation metrics | + + + + +| Guide | What you will find | +| --- | --- | +| [Output Files](/reference/output-files) | Paths under output_dir / expt_name | +| [Troubleshooting](/reference/troubleshooting) | Symptom-to-fix index for BYOB runs | +| [Supported Hugging Face Benchmarks](/reference/benchmarks) | Allowed hf_dataset values and default subsets | +| [Generation Configuration Reference](/reference/generate-config) | Generation YAML keys | +| [Translation Configuration Reference](/reference/translation-config) | Translation YAML keys | + + + + + +## What You Need + +- A Nemotron clone with dependencies installed, including the `byob` extra from `uv sync --extra byob`. + +- Model credentials and endpoints that match the `generation_model_config`, `judge_model_config`, and related blocks in your YAML, as described in [Configure Model Endpoints for BYOB](/how-to/custom-model-endpoints). + +- Network access to download the configured Hugging Face benchmark split unless it is already cached on disk. + +## Quick Start + +1. Follow [Getting Started with Building MCQ Benchmarks](/getting-started) if you have not run the step yet. + +2. Read [Prepare Your Own Domain Data](/how-to/prepare-data) when you are ready to point the pipeline at your own corpus and mapping. + +3. Open [Generation Configuration Reference](/reference/generate-config) or [Translation Configuration Reference](/reference/translation-config) when you need field-level YAML detail. + +## Limitations and Considerations + +- Cost: generation, judgement, expansion, validity checks, and filters call remote models whenever you configure them to do so. + +- Time: full runs depend on corpus size, model latency, and which optional stages stay enabled. + +- Rate limits: hosted APIs may throttle parallel requests that you set under `inference_parameters`. + +- Curator mount: checked-in configurations mount NeMo Curator from Git for translation and deduplication-related paths, so remote profiles must expose that tree the same way your environment expects. diff --git a/docs/fern/pages-vnightly/build-benchmarks/reference/benchmarks.mdx b/docs/fern/pages-vnightly/build-benchmarks/reference/benchmarks.mdx new file mode 100644 index 000000000..ebff40978 --- /dev/null +++ b/docs/fern/pages-vnightly/build-benchmarks/reference/benchmarks.mdx @@ -0,0 +1,26 @@ +--- +title: "Supported Hugging Face Benchmarks" +slug: "build-benchmarks/reference/benchmarks.html" +description: "hf_dataset in your generation YAML must be one of the strings in ALLOWED_HF_DATASETS inside src/nemotron/steps/byob/runtime/constants.py." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +`hf_dataset` in your generation YAML must be one of the strings in `ALLOWED_HF_DATASETS` inside `src/nemotron/steps/byob/runtime/constants.py`. + +If you omit `subset` in YAML, `ByobConfig.from_yaml` substitutes the default from `HF_DATASET_TO_SUBSET`. + +| hf_dataset | Default subset when omitted | +| --- | --- | +| cais/mmlu | all | +| TIGER-Lab/MMLU-Pro | default | +| ai4bharat/MILU | English | +| CohereLabs/Global-MMLU | en | +| CohereLabs/Global-MMLU-Lite | en | +| LinguaLift/IndicMMLU-Pro | hindi | +| openai/MMMLU | default | +| sarvamai/mmlu-indic | en | +| Idavidrein/gpqa | gpqa_main | + +Each identifier maps to the shared MCQ dataset implementation through `HF_DATASET_TO_MODULE`, which currently resolves every row to `nemotron.steps.byob.runtime.benchmark_families.mcq`. diff --git a/docs/fern/pages-vnightly/build-benchmarks/reference/generate-config.mdx b/docs/fern/pages-vnightly/build-benchmarks/reference/generate-config.mdx new file mode 100644 index 000000000..95b482595 --- /dev/null +++ b/docs/fern/pages-vnightly/build-benchmarks/reference/generate-config.mdx @@ -0,0 +1,77 @@ +--- +title: "Generation Configuration Reference" +slug: "build-benchmarks/reference/generate-config.html" +description: "This page lists the YAML keys validated inside ByobConfig.from_yaml in runtime/config.py. Optional keys show their defaults in the dataclass or in the get calls inside from_yaml." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +This page lists the YAML keys validated inside `ByobConfig.from_yaml` in `runtime/config.py`. +Optional keys show their defaults in the dataclass or in the `get` calls inside `from_yaml`. + +## Experiment layout + +| Key | Notes | +| --- | --- | +| expt_name | Required string; builds output_dir/expt_name/. | +| output_dir | Required writable directory. | +| input_dir | Required path containing each target_source_mapping corpus. | +| random_seed | Optional; seeds Python and NumPy when present. | +| ndd_batch_size | Optional positive int; defaults to 1000 in the dataclass but sample configs use smaller values. | + +## Dataset selection + +| Key | Notes | +| --- | --- | +| hf_dataset | Must appear in ALLOWED_HF_DATASETS. | +| subset | Optional; defaults per [Supported Hugging Face Benchmarks](/benchmarks). | +| split | Optional; defaults to "test". | +| language | Required string (for example en-US). | +| metadata_file | Optional CSV path enabling tag-aware sampling. | + +## Subjects and sampling + +| Key | Notes | +| --- | --- | +| source_subjects | Required non-empty list of benchmark subject strings. | +| target_source_mapping | Required mapping; see [Prepare Your Own Domain Data](/../how-to/prepare-data). | +| few_shot_samples_per_query | Required positive int. | +| queries_per_target_subject_document | Required positive int. | +| num_questions_per_query | Required positive int. | + +## Prompts and models + +| Key | Notes | +| --- | --- | +| prompt_config | null loads packaged defaults; a string path loads YAML with all required stages. | +| generation_model_config | Required mapping for Data Designer calls. | +| judge_model_config | Required mapping. | +| do_distractor_expansion | Required bool. | +| distractor_expansion_model_config | Required when expansion is true. | +| distractor_validity_model_config | Required mapping. | +| filtering_model_configs | Required dict with hallucination and easiness lists. | +| easiness_threshold | Required float in [0, 1]. | +| hallucination_threshold | Required float in [0, 1]. | +| remove_hallucinated | Optional bool; defaults to True. | +| remove_easy | Optional bool; defaults to False. | + +## Optional quality stages + +| Key | Notes | +| --- | --- | +| semantic_deduplication_config | Dict with enabled, embedding model id, clustering parameters, and remove_duplicates. | +| semantic_outlier_detection_config | Dict with enabled, embedding model id, and neighbour thresholds. | +| chunking_config | Dict; supports window_size (null keeps whole documents). | +| do_coverage_check | Bool; defaults to False when omitted. | +| coverage_check_config | Dict with window_size and model_identifier. | + +## Curator mount + +Sample configs include a `run.env.mounts` entry that uses `$\{auto_mount:...\}` to place NeMo Curator on `/opt/Curator`. +Remote profiles must preserve the same mount contract your environment expects. + +## Stage dispatch for `nemotron steps run` + +The generic steps CLI accepts `family`, `stage`, and `skip_until` as dotlist overrides, and you can also place those keys directly in YAML. +`family` defaults to `mcq` when omitted. diff --git a/docs/fern/pages-vnightly/build-benchmarks/reference/index.mdx b/docs/fern/pages-vnightly/build-benchmarks/reference/index.mdx new file mode 100644 index 000000000..f5003ad6d --- /dev/null +++ b/docs/fern/pages-vnightly/build-benchmarks/reference/index.mdx @@ -0,0 +1,76 @@ +--- +title: "Reference" +slug: "build-benchmarks/reference/index.html" +description: "Specifications grounded in src/nemotron/steps/byob." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +Specifications grounded in `src/nemotron/steps/byob`. + +## Outputs + + + +Seed, stage cache, raw and final Parquet paths. + +--- + +parquet + + + + +Common configuration errors, missing caches, filtering, and endpoint issues. + +--- + +faq + + + + + +## Configuration + + + +Required keys for `ByobConfig.from_yaml`. + +--- + +yaml + + + + +`ByobTranslationConfig.from_yaml` requirements. + +--- + +yaml + + + + + +## Source benchmarks + + + +Identifiers and default subsets from `runtime/constants.py`. + +--- + +hf_dataset + + + + + +## Related documentation + +- Tutorial: [Getting Started with Building MCQ Benchmarks](/../getting-started) + +- Concepts: [Concepts](/../explanation/index) diff --git a/docs/fern/pages-vnightly/build-benchmarks/reference/output-files.mdx b/docs/fern/pages-vnightly/build-benchmarks/reference/output-files.mdx new file mode 100644 index 000000000..857ca73b8 --- /dev/null +++ b/docs/fern/pages-vnightly/build-benchmarks/reference/output-files.mdx @@ -0,0 +1,91 @@ +--- +title: "Output Files" +slug: "build-benchmarks/reference/output-files.html" +description: "All paths below are relative to output_dir from your YAML and the string expt_name." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +All paths below are relative to `output_dir` from your YAML and the string `expt_name`. + +## Prepare + +| File | Description | +| --- | --- | +| seed.parquet | Few-shot rows plus domain chunks. | + +## Generate + +The final generation creates these files: + +| File | Description | +| --- | --- | +| benchmark_raw.parquet | Snapshot immediately before column renaming for the final schema. | +| benchmark.parquet | Final MCQ schema; column meanings and a sample row are in the next section. | + +The following intermediate files that are created in the `stage_cache` directory: + +| File | Stage | +| --- | --- | +| generated_questions.parquet | GENERATION | +| judged_questions.parquet | JUDGEMENT | +| semantic_deduplicated_questions.parquet | SEMANTIC_DEDUPLICATION | +| expanded_distractors.parquet | DISTRACTOR_EXPANSION (only when do_distractor_expansion is true) | +| coverage_check.parquet | COVERAGE_CHECK (only when do_coverage_check is true) | +| valid_distractors.parquet | DISTRACTOR_VALIDITY_CHECK | +| semantic_outlier_detection.parquet | SEMANTIC_OUTLIER_DETECTION | +| filtered_questions.parquet | HALLUCINATION_EASINESS_DETECTION | + + + +## Final MCQ Columns + +Generation and translation both export the same eight columns on the final `benchmark.parquet` file. + +| Column | Meaning | +| --- | --- | +| question_id | Stable identifier for the row, taken from the internal id_question field before export. | +| question | Stem text for the multiple-choice item. After translation this is the target-language text. | +| options | Ordered list of choice strings. The list order matches the letter labels implied by answer_index. | +| answer_index | Zero-based index into options for the correct choice. | +| answer | Letter label for the correct choice, derived from answer_index (0 → A, 1 → B, and so on). | +| cot_content | Reserved for chain-of-thought text. The current pipeline sets this column to the literal - for every row on export. | +| src | Reserved for a source document marker. The current pipeline sets this column to the literal - for every row on export. | +| category | Target key from target_source_mapping in your generation configuration, in other words the domain bucket name for the row, not the Hugging Face few-shot subject name. | + +### Sample Row + +Values below are illustrative; your identifiers and wording will differ. + +```json +{ + "question_id": "mcq-00042", + "question": "If x^2 = 9, which value can x take?", + "options": ["-3 only", "-3 or 3", "3 only", "9"], + "answer_index": 1, + "answer": "B", + "cot_content": "-", + "src": "-", + "category": "maths" +} +``` + +## Translate + +The translate stage creates the following final output files: + +| File | Description | +| --- | --- | +| benchmark_raw.parquet | Intermediate snapshot prior to optional quality filtering. | +| benchmark.parquet | Final translated MCQ after fields are renamed back to question, options, answer_index, and answer. Column semantics match generation; see [Final MCQ Columns](#final-mcq-columns). | + +The following intermediate files are created in the `staged_cache` directory. + +| File | Stage | +| --- | --- | +| translated_questions.parquet | TRANSLATION | +| backtranslated_questions.parquet | BACKTRANSLATION | +| quality_metrics.parquet | QUALITY_METRICS | + +Intermediate translation Parquet files can include additional columns such as `question_translated`, `options_translated`, backtranslation fields, and metric scores. diff --git a/docs/fern/pages-vnightly/build-benchmarks/reference/translation-config.mdx b/docs/fern/pages-vnightly/build-benchmarks/reference/translation-config.mdx new file mode 100644 index 000000000..409ff9c05 --- /dev/null +++ b/docs/fern/pages-vnightly/build-benchmarks/reference/translation-config.mdx @@ -0,0 +1,53 @@ +--- +title: "Translation Configuration Reference" +slug: "build-benchmarks/reference/translation-config.html" +description: "This page describes the YAML configuration file that you provide for the translate stage: the keys you set or override, how backtranslation quality scores show up in Parquet output columns, and which " +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +{/* Reference: BYOB translate YAML keys, metric semantics, and parse-time validation. */} + +This page describes the YAML configuration file that you provide for the translate stage: the keys you set or override, how backtranslation quality scores show up in Parquet output columns, and which rows are omitted from the final `benchmark.parquet` when quality filtering is enabled. + +## Required Keys + +| Key | Notes | +| --- | --- | +| expt_name | Directory name under output_dir for caches and final artifacts. | +| dataset_path | Existing benchmark.parquet from a generation run. | +| output_dir | Parent directory for expt_name. | +| source_language | BCP-47 style tag (for example en-US). | +| target_language | Target locale tag (for example hi-IN). | +| translation_model_config | Dictionary with backend_type, params, and optional stage and segment_stage. | +| backtranslation_quality_metrics | Non-empty list; each element is a dictionary with type and threshold. | + +## Quality Metrics + +Each `type` must be `sacrebleu`, `chrf`, or `ter`. +Each `threshold` must be nonnegative. + +NeMo Curator writes one numeric score column and one boolean pass column per configured metric, for example `score_chrf` and `score_chrf_passed`. +The column `is_quality_metric_passed` is true on a row when every per-metric pass column is true for that row. + +Each score compares the original benchmark text with the round-trip backtranslation from the target locale, using sentence-level APIs from the *sacrebleu* library. + +| type | Measures | Scale and direction | How to interpret scores | Row passes when | +| --- | --- | --- | --- | --- | +| sacrebleu | Sentence bilingual evaluation understudy (BLEU) | 0 through 100 after *sacrebleu* tokenization; higher values track closer matches to the reference. | High scores mean the backtranslation preserved wording and order; scores near zero mean little *n*-gram overlap. | score_sacrebleu ≥ threshold | +| chrf | Sentence character n-gram F-score (chrF) | 0 through 100 in typical sentence outputs; higher values mean closer character-level match. | High scores track spelling and phrasing fidelity; low scores mean the backtranslation diverged on the surface string. | score_chrf ≥ threshold | +| ter | Sentence translation error rate (TER) | Zero means no edits; larger values report more insertions, deletions, or substitutions relative to the reference. | Values close to zero mean the backtranslation needed minimal editing to match the original; large values signal heavy rewrites or mismatch. | score_ter ≤ threshold | + +Inspect `stage_cache/quality_metrics.parquet` under your experiment directory to pick thresholds from the score spread you see in data. + +## Optional Keys + +| Key | Default | Notes | +| --- | --- | --- | +| remove_low_quality | True unless YAML overrides it | When true, the pipeline omits rows where is_quality_metric_passed is false before export. | + +## FAITH evaluation + +`translation_model_config.stage.enable_faith_eval` must not be true. +The benchmark translation relies on backtranslation metrics instead of FAITH filtering diff --git a/docs/fern/pages-vnightly/build-benchmarks/reference/troubleshooting.mdx b/docs/fern/pages-vnightly/build-benchmarks/reference/troubleshooting.mdx new file mode 100644 index 000000000..a8d040f57 --- /dev/null +++ b/docs/fern/pages-vnightly/build-benchmarks/reference/troubleshooting.mdx @@ -0,0 +1,61 @@ +--- +title: "Troubleshooting" +slug: "build-benchmarks/reference/troubleshooting.html" +description: "This page lists common symptoms when you run nemotron steps run byob/mcq with the bring your own benchmark (BYOB) multiple choice question (MCQ) family and when you tune BYOB translation settings. Eac" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +{/* Reference: symptom-to-remedy tables for bring your own benchmark MCQ runs and translation YAML checks. */} + +This page lists common symptoms when you run `nemotron steps run byob/mcq` with the bring your own benchmark (BYOB) multiple choice question (MCQ) family and when you tune BYOB translation settings. +Each table row pairs a symptom with the files, fields, or flags you should inspect first. +For stage flow and design rationale, see the explanation pages linked from [Concepts](/../explanation/index). + +## Configuration Rejected Before the Pipeline Runs + +| Symptom | What to do | +| --- | --- | +| Assertion that tags should not be specified when metadata_file is absent | Remove tags from every target_source_mapping entry, or set top-level metadata_file to the comma-separated values (CSV) file that supplies tag metadata. See [Prepare Your Own Domain Data](/../how-to/prepare-data). | +| Assertion that BYOB translation does not support FAITH evaluation | Under translation_model_config.stage, set enable_faith_eval to false or omit the field. BYOB translation expects backtranslation_quality_metrics instead of FAITH. See [Translation Configuration Reference](/translation-config) and [Translation](/../explanation/translation). | +| Message that a prompt override key is missing or is not a string, or validation fails on prompt_config | Open your prompt_config YAML and match the structure in [Prompt Tuning for Benchmarks](/../how-to/prompt-tuning). Easiness and hallucination overrides must include the expected blocks. | +| Schema validation reports that distractor_validity_model_config is missing | The current generation schema requires this block even when distractor expansion is off. Add the block as described in [Configure Model Endpoints for BYOB](/../how-to/custom-model-endpoints). | + +## Skipped Stages and Missing Parquet Inputs + +| Symptom | What to do | +| --- | --- | +| A stage fails because an expected Parquet file is missing under output_dir/<expt_name>/stage_cache/ | When you use skip_until, every stage before the resume point must have written its output file to disk. Rerun from an earlier stage without skipping, or copy valid caches from a prior run. See [Skip Stages When Iterating](/../how-to/skip-stages). | + +## Generation Ends With No Final Benchmark Rows + +| Symptom | What to do | +| --- | --- | +| Log line No questions left after filtering, or benchmark.parquet is missing after a run that exited early | Open stage_cache/filtered_questions.parquet and inspect is_easy, is_hallucination, and score columns. Loosen easiness_threshold or hallucination_threshold, set remove_easy and remove_hallucinated to false for a diagnostic run, or adjust upstream judgement and deduplication settings. See [Easiness and Hallucination Filtering](/../explanation/filtering). | + +## Translation Export Drops Every Row + +| Symptom | What to do | +| --- | --- | +| benchmark.parquet exists but has zero rows after translation | When remove_low_quality is true, only rows with is_quality_metric_passed are exported. Inspect stage_cache/quality_metrics.parquet, relax metric thresholds in backtranslation_quality_metrics, or set remove_low_quality to false while you tune. See [Translation](/../explanation/translation). | + +## Few-Shot Sampling Finds No Rows + +| Symptom | What to do | +| --- | --- | +| Runtime error stating there are no samples for a given source subject and tag combination | Tag filters must match comma-separated tag strings that appear in the metadata CSV for that Hugging Face subject. Widen tags, correct the CSV, or confirm source_subjects and target_source_mapping names align with [Prepare Your Own Domain Data](/../how-to/prepare-data) and [Getting the Right Questions From the Source Benchmark](/../explanation/get-right-questions). | + +## Hosted Models Throttle or Stall + +| Symptom | What to do | +| --- | --- | +| Timeouts, HTTP responses in the 429 range, or bursty failures when calling remote endpoints | Reduce max_parallel_requests and related batch settings in your YAML, rerun on a smaller slice of data, and confirm API keys and quotas. See [Question Generation](/../explanation/question-generation) and [Configure Model Endpoints for BYOB](/../how-to/custom-model-endpoints). | + +## Related Reference + +- Parquet layout and final column list: [Output Files](/output-files) + +- Generation YAML fields: [Generation Configuration Reference](/generate-config) + +- Translation YAML fields: [Translation Configuration Reference](/translation-config) diff --git a/docs/curate/getting-started.md b/docs/fern/pages-vnightly/curate/getting-started.mdx similarity index 50% rename from docs/curate/getting-started.md rename to docs/fern/pages-vnightly/curate/getting-started.mdx index a8d8dce34..de49f0a5a 100644 --- a/docs/curate/getting-started.md +++ b/docs/fern/pages-vnightly/curate/getting-started.mdx @@ -1,49 +1,39 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Run nemotron steps run curate/nemo_curator on the packaged tiny JSONL file." -topics: ["Curation", "Tutorial", "NeMo Curator"] -tags: ["Tutorial", "Curation"] -content: - type: "Tutorial" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] +title: "Getting Started With Data Curation" +slug: "curate/getting-started.html" +description: "In this tutorial, you will:" --- -(getting-started-curate)= -# Getting Started With Data Curation + -::::{grid} 2 - -:::{grid-item-card} -:columns: 8 - -**What You'll Build**: a filtered set of JSONL shards from the packaged + + **In this tutorial, you will**: 1. Clone the repository and install dependencies. + 1. Configure the Ray runtime environment. + 1. Inspect the packaged fixture. + 1. Run the curation step with the tiny configuration. + 1. Inspect the output shards. -{octicon}`clock;1.5em;sd-mr-1` This tutorial requires approximately 5 minutes to complete. -::: + This tutorial requires approximately 5 minutes to complete. -:::{grid-item-card} {octicon}`flame;1.5em;sd-mr-1` **Sample Prompt** -:columns: 4 + + Run the `curate/nemo_curator` step on the packaged tiny JSONL fixture, then show me the names and record counts of the output shards. -::: -:::: + + + ## Prerequisites @@ -51,7 +41,7 @@ the names and record counts of the output shards. ## Procedure -1. Clone the repository, if you haven't already: +1. Clone the repository, if you haven’t already: ```console $ git clone https://github.com/NVIDIA-NeMo/Nemotron && cd Nemotron @@ -64,32 +54,32 @@ the names and record counts of the output shards. ``` 1. Set the Ray runtime environment variable so Ray workers reuse the synchronized - project environment: +project environment: ```console $ export RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 ``` 1. Inspect the packaged fixture at - `src/nemotron/steps/curate/nemo_curator/data/tiny.jsonl`. - Each record contains a `text` field. +`src/nemotron/steps/curate/nemo_curator/data/tiny.jsonl`. +Each record contains a `text` field. - ```{literalinclude} ../../src/nemotron/steps/curate/nemo_curator/data/tiny.jsonl - :language: json - :class: scrollable + ```json startLine={1} + {"text":"This is a small English document for the curation smoke test with enough words for optional quality filters."} + {"text":"Another English sample about mathematics, banking, and clean data processing for a tiny curation validation run."} ``` 1. Run the curation step. - The `tiny` configuration disables optional language, word-count, and domain - filters, making this run a baseline validation of the reader, writer, and Ray - startup. - The checked-in `tiny.yaml` uses container paths, so override `input_glob` and - `output_dir` with host paths: +The `tiny` configuration disables optional language, word-count, and domain +filters, making this run a baseline validation of the reader, writer, and Ray +startup. +The checked-in `tiny.yaml` uses container paths, so override `input_glob` and +`output_dir` with host paths: ```console $ uv run --no-sync nemotron steps run curate/nemo_curator -c tiny \ - input_glob="${PWD}/src/nemotron/steps/curate/nemo_curator/data/tiny.jsonl" \ - output_dir="${PWD}/output/curate-tiny" + input_glob="$\{PWD\}/src/nemotron/steps/curate/nemo_curator/data/tiny.jsonl" \ + output_dir="$\{PWD\}/output/curate-tiny" ``` 1. Inspect the output directory: @@ -99,17 +89,20 @@ the names and record counts of the output shards. ``` Open a shard and confirm that records contain the configured `text_field`. - NeMo Curator assigns the exact shard name. +NeMo Curator assigns the exact shard name. ## Summary In this tutorial, you completed the following tasks: - Cloned the repository and installed the project dependencies. + - Configured the Ray runtime environment. + - Ran the `curate/nemo_curator` step with the packaged tiny JSONL fixture. + - Inspected the output shards and verified that records contain the configured - text field. +text field. The `tiny` configuration disables all optional filters. To add language, word-count, or domain filters to a production corpus, refer to @@ -117,9 +110,12 @@ the how-to guides below. ## Next Steps -- Point the step at your own JSONL corpus: {doc}`how-to/run-local-jsonl`. +- Point the step at your own JSONL corpus: [Run Curation on Local JSONL](/how-to/run-local-jsonl). + - Download a Hugging Face dataset before curation: - {doc}`how-to/use-huggingface-snapshot`. -- Add language, word-count, or domain filters: {doc}`how-to/enable-filters`. -- Look up all configuration fields and CLI flags: {doc}`reference/curate-config` - and {doc}`reference/cli-curate`. +[Use a Hugging Face Snapshot](/how-to/use-huggingface-snapshot). + +- Add language, word-count, or domain filters: [Enable Curation Filters](/how-to/enable-filters). + +- Look up all configuration fields and CLI flags: [curate/nemo_curator Configuration](/reference/curate-config) +and [curate/nemo_curator CLI](/reference/cli-curate). diff --git a/docs/curate/how-to/enable-filters.md b/docs/fern/pages-vnightly/curate/how-to/enable-filters.mdx similarity index 59% rename from docs/curate/how-to/enable-filters.md rename to docs/fern/pages-vnightly/curate/how-to/enable-filters.mdx index cdb1bb0ed..95861c9e7 100644 --- a/docs/curate/how-to/enable-filters.md +++ b/docs/fern/pages-vnightly/curate/how-to/enable-filters.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Enable language, word-count, and domain filters in curate/nemo_curator." -topics: ["Curation", "How-To", "Filters"] -tags: ["How-To", "Curation", "Language ID", "Domain Classification"] -content: - type: "How-To" - difficulty: "Intermediate" - audience: ["ML Engineer", "Data Scientist"] +title: "Enable Curation Filters" +slug: "curate/how-to/enable-filters.html" +description: "Start with no filters, confirm JSONL input and output, then add one filter family at a time." --- -# Enable Curation Filters - Start with no filters, confirm JSONL input and output, then add one filter family at a time. ## Language Filtering @@ -20,10 +12,10 @@ Set `language_codes` to uppercase language codes and provide a FastText language ```console $ uv run --no-sync nemotron steps run curate/nemo_curator -c tiny \ - input_glob="${PWD}/data/my_corpus/**/*.jsonl" \ - output_dir="${PWD}/output/curated-en" \ + input_glob="$\{PWD\}/data/my_corpus/**/*.jsonl" \ + output_dir="$\{PWD\}/output/curated-en" \ language_codes=[EN] \ - models.fasttext_langid="${PWD}/cache/models/fasttext/lid.176.bin" \ + models.fasttext_langid="$\{PWD\}/cache/models/fasttext/lid.176.bin" \ quality_filters.min_langid_score=0.3 ``` @@ -36,38 +28,41 @@ The step raises an error if only one of those keys is present. ```console $ uv run --no-sync nemotron steps run curate/nemo_curator -c tiny \ - input_glob="${PWD}/data/my_corpus/**/*.jsonl" \ - output_dir="${PWD}/output/curated-word-count" \ + input_glob="$\{PWD\}/data/my_corpus/**/*.jsonl" \ + output_dir="$\{PWD\}/output/curated-word-count" \ quality_filters.min_words=50 \ quality_filters.max_words=5000 ``` -Set `quality_filters={}` to skip word-count filtering. +Set `quality_filters=\{\}` to skip word-count filtering. ## Domain Filtering Set `domains` to the domains you want to keep. -The step uses NeMo Curator's multilingual domain classifier. +The step uses NeMo Curator’s multilingual domain classifier. ```console $ uv run --no-sync nemotron steps run curate/nemo_curator -c tiny \ - input_glob="${PWD}/data/my_corpus/**/*.jsonl" \ - output_dir="${PWD}/output/curated-domain" \ + input_glob="$\{PWD\}/data/my_corpus/**/*.jsonl" \ + output_dir="$\{PWD\}/output/curated-domain" \ domains=[STEM] \ - models.hf_cache_dir="${PWD}/cache/huggingface" + models.hf_cache_dir="$\{PWD\}/cache/huggingface" ``` -```{tip} + Keep the first domain-filtered run small. The classifier may download or cache model assets on first use. -``` + + ## Filter Order The step applies filters in this order: 1. FastText language identification and language filtering, when `language_codes` is non-empty. + 2. Word-count filtering, when `quality_filters.min_words` and `quality_filters.max_words` are both set. + 3. Multilingual domain classification, when `domains` is non-empty. When output is unexpectedly small, disable later filters first, then relax thresholds. diff --git a/docs/fern/pages-vnightly/curate/how-to/index.mdx b/docs/fern/pages-vnightly/curate/how-to/index.mdx new file mode 100644 index 000000000..53a1da7c0 --- /dev/null +++ b/docs/fern/pages-vnightly/curate/how-to/index.mdx @@ -0,0 +1,13 @@ +--- +title: "Curation How-To Guides" +slug: "curate/how-to/index.html" +description: "Use these guides after the local initial validation in Getting Started With Data Curation." +--- + +Use these guides after the local initial validation in [Getting Started With Data Curation](/../getting-started). + +- [Run Curation on Local JSONL](/run-local-jsonl) + +- [Use a Hugging Face Snapshot](/use-huggingface-snapshot) + +- [Enable Curation Filters](/enable-filters) diff --git a/docs/curate/how-to/run-local-jsonl.md b/docs/fern/pages-vnightly/curate/how-to/run-local-jsonl.mdx similarity index 69% rename from docs/curate/how-to/run-local-jsonl.md rename to docs/fern/pages-vnightly/curate/how-to/run-local-jsonl.mdx index dfb205458..86ccc313d 100644 --- a/docs/curate/how-to/run-local-jsonl.md +++ b/docs/fern/pages-vnightly/curate/how-to/run-local-jsonl.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Run curate/nemo_curator on local JSONL files." -topics: ["Curation", "How-To", "JSONL"] -tags: ["How-To", "Curation", "JSONL"] -content: - type: "How-To" - difficulty: "Intermediate" - audience: ["ML Engineer", "Data Scientist"] +title: "Run Curation on Local JSONL" +slug: "curate/how-to/run-local-jsonl.html" +description: "Use this path when your corpus already exists as local JSONL files." --- -# Run Curation on Local JSONL - Use this path when your corpus already exists as local JSONL files. ## Input Requirements @@ -35,8 +27,8 @@ $ uv sync --extra curate $ export RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 $ uv run --no-sync nemotron steps run curate/nemo_curator -c tiny \ - input_glob="${PWD}/data/my_corpus/**/*.jsonl" \ - output_dir="${PWD}/output/curated-jsonl" \ + input_glob="$\{PWD\}/data/my_corpus/**/*.jsonl" \ + output_dir="$\{PWD\}/output/curated-jsonl" \ text_field=text \ language_codes=[] \ domains=[] \ @@ -52,8 +44,8 @@ For local runs, you can set Ray CPU count in YAML or as a CLI override: ```console $ uv run --no-sync nemotron steps run curate/nemo_curator -c tiny \ - input_glob="${PWD}/data/my_corpus/**/*.jsonl" \ - output_dir="${PWD}/output/curated-jsonl" \ + input_glob="$\{PWD\}/data/my_corpus/**/*.jsonl" \ + output_dir="$\{PWD\}/output/curated-jsonl" \ ray.num_cpus=4 ``` @@ -64,7 +56,9 @@ For generated Lepton profiles, `NEMOTRON_CURATOR_RAY_NUM_CPUS` can provide the C After the run: - Confirm that output shards exist under `output_dir`. + - Count records before and after filtering. + - Inspect a few output records to confirm the `text_field` is present and not empty. -If output is empty, run again with `language_codes=[]`, `domains=[]`, and `quality_filters={}` before enabling filters. +If output is empty, run again with `language_codes=[]`, `domains=[]`, and `quality_filters=\{\}` before enabling filters. diff --git a/docs/curate/how-to/use-huggingface-snapshot.md b/docs/fern/pages-vnightly/curate/how-to/use-huggingface-snapshot.mdx similarity index 61% rename from docs/curate/how-to/use-huggingface-snapshot.md rename to docs/fern/pages-vnightly/curate/how-to/use-huggingface-snapshot.mdx index 5e40b1292..4515e44ea 100644 --- a/docs/curate/how-to/use-huggingface-snapshot.md +++ b/docs/fern/pages-vnightly/curate/how-to/use-huggingface-snapshot.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Use the dataset block in curate/nemo_curator to materialize a Hugging Face dataset snapshot before curation." -topics: ["Curation", "How-To", "Hugging Face"] -tags: ["How-To", "Curation", "Hugging Face"] -content: - type: "How-To" - difficulty: "Intermediate" - audience: ["ML Engineer", "Data Scientist"] +title: "Use a Hugging Face Snapshot" +slug: "curate/how-to/use-huggingface-snapshot.html" +description: "Set the dataset block when the curation job should call huggingface_hub.snapshot_download before NeMo Curator reads files." --- -# Use a Hugging Face Snapshot - Set the `dataset` block when the curation job should call `huggingface_hub.snapshot_download` before NeMo Curator reads files. ## Configuration Shape @@ -40,10 +32,10 @@ $ uv sync --extra curate $ export RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 $ uv run --no-sync nemotron steps run curate/nemo_curator -c default \ - dataset.local_dir="${PWD}/data/fineweb-edu" \ - input_glob="${PWD}/data/fineweb-edu/**/*.jsonl" \ - output_dir="${PWD}/output/fineweb-edu-curated" \ - models.fasttext_langid="${PWD}/cache/models/fasttext/lid.176.bin" + dataset.local_dir="$\{PWD\}/data/fineweb-edu" \ + input_glob="$\{PWD\}/data/fineweb-edu/**/*.jsonl" \ + output_dir="$\{PWD\}/output/fineweb-edu-curated" \ + models.fasttext_langid="$\{PWD\}/cache/models/fasttext/lid.176.bin" ``` ## Snapshot Without Optional Filters @@ -52,9 +44,9 @@ For a first infrastructure run, disable filters and verify that snapshot downloa ```console $ uv run --no-sync nemotron steps run curate/nemo_curator -c default \ - dataset.local_dir="${PWD}/data/fineweb-edu" \ - input_glob="${PWD}/data/fineweb-edu/**/*.jsonl" \ - output_dir="${PWD}/output/fineweb-edu-curated" \ + dataset.local_dir="$\{PWD\}/data/fineweb-edu" \ + input_glob="$\{PWD\}/data/fineweb-edu/**/*.jsonl" \ + output_dir="$\{PWD\}/output/fineweb-edu-curated" \ language_codes=[] \ domains=[] \ quality_filters={} @@ -66,5 +58,5 @@ If the Hugging Face repository requires authentication, export `HF_TOKEN` before For remote jobs, pass `HF_TOKEN` through the environment profile. ```console -$ export HF_TOKEN="" +$ export HF_TOKEN="\" ``` diff --git a/docs/curate/index.md b/docs/fern/pages-vnightly/curate/index.mdx similarity index 51% rename from docs/curate/index.md rename to docs/fern/pages-vnightly/curate/index.mdx index 4393bb068..9c2894dbc 100644 --- a/docs/curate/index.md +++ b/docs/fern/pages-vnightly/curate/index.mdx @@ -1,17 +1,10 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Curate JSONL text with nemotron steps run curate/nemo_curator and NeMo Curator reader, filter, classifier, and writer stages." -topics: ["Curation", "NeMo Curator", "JSONL"] -tags: ["Curation", "Documentation"] -content: - type: "Explanation" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] +title: "About Data Curation With NeMo Curator" +slug: "curate/index.html" +description: "The nemotron steps run curate/nemo_curator command reads JSONL data, optionally materializes a Hugging Face dataset snapshot, applies lightweight NeMo Curator filters, and writes filtered JSONL shards" --- -(curate-index)= -# About Data Curation With NeMo Curator + The `nemotron steps run curate/nemo_curator` command reads JSONL data, optionally materializes a Hugging Face dataset snapshot, applies lightweight NeMo Curator filters, and writes filtered JSONL shards for downstream translation or training data preparation. @@ -22,20 +15,25 @@ Use this step when you already have JSONL records and need a small, repeatable c Use `curate/nemo_curator` when you need: - A local JSONL reader and writer path using NeMo Curator. + - Optional FastText language identification and language filtering. + - Optional word-count filtering. + - Optional multilingual domain classification and filtering. + - Optional Hugging Face dataset snapshot download before the Curator reader runs. -```{note} + This step is intentionally lightweight. It does not crawl web pages, extract Common Crawl WARC files, or run large deduplication workflows. Use a dedicated Curator recipe for those jobs before this step, or add a separate step when that behavior is needed. -``` + + ## Pipeline Summary -```{mermaid} +```mermaid flowchart LR A[Optional Hugging Face snapshot] --> B[JSONL files] C[Local JSONL files] --> B @@ -55,80 +53,84 @@ flowchart LR ## Documentation Series -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`book;1.5em;sd-mr-1` Tutorial -:link: getting-started -:link-type: doc + + Install the Nemotron CLI, run a local tiny JSONL initial curation validation, and inspect output shards. -+++ -{bdg-secondary}`hands-on` -::: -:::{grid-item-card} {octicon}`tools;1.5em;sd-mr-1` How-To Guides -:link: how-to/index -:link-type: doc +--- + +hands-on + + + + Run local JSONL curation, download a Hugging Face snapshot, and enable optional filters. -+++ -{bdg-secondary}`task-based` -::: -:::{grid-item-card} {octicon}`list-unordered;1.5em;sd-mr-1` Reference -:link: reference/index -:link-type: doc +--- + +task-based + + + + YAML parameters, CLI syntax, input/output format, and troubleshooting. -+++ -{bdg-secondary}`lookup` -::: -:::: +--- -## All Documentation +lookup + + -````{tab-set} + + +## All Documentation -```{tab-item} Tutorial + + | Guide | What you do | | --- | --- | -| {doc}`getting-started` | Run `curate/nemo_curator` on the packaged tiny JSONL fixture | +| [Getting Started With Data Curation](/getting-started) | Run curate/nemo_curator on the packaged tiny JSONL fixture | -``` - -```{tab-item} How-To Guides + + | Guide | Focus | | --- | --- | -| {doc}`how-to/run-local-jsonl` | Local JSONL reader/writer path | -| {doc}`how-to/use-huggingface-snapshot` | `dataset` block and Hugging Face snapshot download | -| {doc}`how-to/enable-filters` | Language, word-count, and domain filters | - -``` +| [Run Curation on Local JSONL](/how-to/run-local-jsonl) | Local JSONL reader/writer path | +| [Use a Hugging Face Snapshot](/how-to/use-huggingface-snapshot) | dataset block and Hugging Face snapshot download | +| [Enable Curation Filters](/how-to/enable-filters) | Language, word-count, and domain filters | -```{tab-item} Reference + + | Guide | Content | | --- | --- | -| {doc}`reference/curate-config` | YAML field reference | -| {doc}`reference/cli-curate` | `nemotron steps run curate/nemo_curator` syntax | -| {doc}`reference/io-format` | Input and output shapes | -| {doc}`reference/troubleshooting` | Common failures and fixes | +| [curate/nemo_curator Configuration](/reference/curate-config) | YAML field reference | +| [curate/nemo_curator CLI](/reference/cli-curate) | nemotron steps run curate/nemo_curator syntax | +| [Curation Input and Output Format](/reference/io-format) | Input and output shapes | +| [Curation Troubleshooting](/reference/troubleshooting) | Common failures and fixes | -``` + -```` + ## What You Need - JSONL input with one text field, usually named `text`. + - Optional model assets when filters are enabled, such as a FastText language identification model for `language_codes`. + - A writable output directory for JSONL shards. ## Quick Paths -1. First local run: {doc}`getting-started` -2. Local corpus setup: {doc}`how-to/run-local-jsonl` -3. Hugging Face snapshot setup: {doc}`how-to/use-huggingface-snapshot` -4. Filter setup: {doc}`how-to/enable-filters` -5. Lookup flags: {doc}`reference/cli-curate` +1. First local run: [Getting Started With Data Curation](/getting-started) + +2. Local corpus setup: [Run Curation on Local JSONL](/how-to/run-local-jsonl) + +3. Hugging Face snapshot setup: [Use a Hugging Face Snapshot](/how-to/use-huggingface-snapshot) + +4. Filter setup: [Enable Curation Filters](/how-to/enable-filters) + +5. Lookup flags: [curate/nemo_curator CLI](/reference/cli-curate) diff --git a/docs/curate/reference/cli-curate.md b/docs/fern/pages-vnightly/curate/reference/cli-curate.mdx similarity index 59% rename from docs/curate/reference/cli-curate.md rename to docs/fern/pages-vnightly/curate/reference/cli-curate.mdx index 305d46732..eee7eccbd 100644 --- a/docs/curate/reference/cli-curate.md +++ b/docs/fern/pages-vnightly/curate/reference/cli-curate.mdx @@ -1,29 +1,21 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "CLI reference for nemotron steps run curate/nemo_curator." -topics: ["Curation", "Reference", "CLI"] -tags: ["Reference", "CLI", "Curation"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Data Scientist"] +title: "curate/nemo_curator CLI" +slug: "curate/reference/cli-curate.html" +description: "Use -c tiny for a small initial validation configuration and -c default for the Hugging Face snapshot example. Refer to Nemotron Steps CLI Reference for the shared flag set." --- -# curate/nemo_curator CLI - ## Syntax ```bash uv run --no-sync nemotron steps run curate/nemo_curator \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ - [...] + [\...] ``` Use `-c tiny` for a small initial validation configuration and `-c default` for the Hugging Face snapshot example. -Refer to [Nemotron Steps CLI Reference](../../train-models/reference/cli-reference.md) for the shared flag set. +Refer to [Nemotron Steps CLI Reference](/../../train-models/reference/cli-reference) for the shared flag set. ## Common Commands @@ -37,8 +29,8 @@ Run a local JSONL initial validation: ```console $ uv run --no-sync nemotron steps run curate/nemo_curator -c tiny \ - input_glob="${PWD}/src/nemotron/steps/curate/nemo_curator/data/tiny.jsonl" \ - output_dir="${PWD}/output/curate-tiny" + input_glob="$\{PWD\}/src/nemotron/steps/curate/nemo_curator/data/tiny.jsonl" \ + output_dir="$\{PWD\}/output/curate-tiny" ``` Run on Lepton with the generated Curator profile: @@ -51,8 +43,8 @@ Run against local corpus shards: ```console $ uv run --no-sync nemotron steps run curate/nemo_curator -c tiny \ - input_glob="${PWD}/data/my_corpus/**/*.jsonl" \ - output_dir="${PWD}/output/curated-jsonl" \ + input_glob="$\{PWD\}/data/my_corpus/**/*.jsonl" \ + output_dir="$\{PWD\}/output/curated-jsonl" \ text_field=text \ language_codes=[] \ domains=[] \ @@ -65,11 +57,17 @@ All YAML fields can be overridden from the command line with `key=value` syntax. Examples: - `input_glob=/data/**/*.jsonl` + - `output_dir=/output/curated` + - `text_field=body` + - `language_codes=[EN]` + - `quality_filters.min_words=50` + - `quality_filters.max_words=5000` + - `ray.num_cpus=4` Use shell quoting around globs or lists when your shell expands them unexpectedly. diff --git a/docs/curate/reference/curate-config.md b/docs/fern/pages-vnightly/curate/reference/curate-config.mdx similarity index 65% rename from docs/curate/reference/curate-config.md rename to docs/fern/pages-vnightly/curate/reference/curate-config.mdx index cade4e1cf..bc97e554c 100644 --- a/docs/curate/reference/curate-config.md +++ b/docs/fern/pages-vnightly/curate/reference/curate-config.mdx @@ -1,87 +1,91 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Configuration field reference for curate/nemo_curator." -topics: ["Curation", "Reference", "Configuration"] -tags: ["Reference", "Configuration", "Curation"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Data Scientist"] +title: "curate/nemo_curator Configuration" +slug: "curate/reference/curate-config.html" +description: "The step reads YAML from src/nemotron/steps/curate/nemo_curator/config/." --- -# curate/nemo_curator Configuration - The step reads YAML from `src/nemotron/steps/curate/nemo_curator/config/`. | File | Purpose | | --- | --- | -| `tiny.yaml` | Curator-container initial validation configuration. Optional filters are disabled. Override `input_glob` for local runs because the checked-in path is a container path. | -| `default.yaml` | Example Hugging Face snapshot workflow for FineWeb-Edu-style JSONL with language and word-count filters enabled. | +| tiny.yaml | Curator-container initial validation configuration. Optional filters are disabled. Override input_glob for local runs because the checked-in path is a container path. | +| default.yaml | Example Hugging Face snapshot workflow for FineWeb-Edu-style JSONL with language and word-count filters enabled. | ## Top-Level Fields -```{option} input_glob +### `input_glob` JSONL file path or glob passed to NeMo Curator `JsonlReader`. -``` -```{option} output_dir +--- + +### `output_dir` Directory where NeMo Curator writes JSONL output shards. -``` -```{option} text_field +--- + +### `text_field` Record field containing the text to curate. Default: `text`. -``` -```{option} dataset +--- + +### `dataset` Optional keyword arguments passed to `huggingface_hub.snapshot_download`. Set `dataset: null` for local-input-only runs. Common keys are `repo_id`, `repo_type`, `local_dir`, and `allow_patterns`. -``` -```{option} language_codes +--- + +### `language_codes` Uppercase language codes to keep. Set `language_codes: []` to skip FastText language identification and language filtering. When this list is non-empty, `models.fasttext_langid` must point at a FastText language identification model. -``` -```{option} domains +--- + +### `domains` Domains to keep through NeMo Curator `MultilingualDomainClassifier`. Set `domains: []` to skip domain classification. -``` -```{option} quality_filters +--- + +### `quality_filters` Optional quality settings. `min_langid_score` applies when language filtering is enabled. `min_words` and `max_words` enable word-count filtering and must be set together. -Set `quality_filters: {}` to skip word-count filtering. -``` +Set `quality_filters: \{\}` to skip word-count filtering. + +--- -```{option} models +### `models` Optional model and cache paths. Common keys: - Set `fasttext_langid` to the path of the FastText language identification model. + - Set `hf_cache_dir` to the Hugging Face model cache directory for classifier assets. -``` -```{option} ray.num_cpus +--- + +### `num_cpus` + +```python +ray.num_cpus +``` Optional Ray CPU count. If omitted, the Lepton curate profile can provide `NEMOTRON_CURATOR_RAY_NUM_CPUS`. -``` ## Minimal Local Configuration diff --git a/docs/fern/pages-vnightly/curate/reference/index.mdx b/docs/fern/pages-vnightly/curate/reference/index.mdx new file mode 100644 index 000000000..3c848b912 --- /dev/null +++ b/docs/fern/pages-vnightly/curate/reference/index.mdx @@ -0,0 +1,15 @@ +--- +title: "Curation Reference" +slug: "curate/reference/index.html" +description: "Use these pages to look up CLI syntax, configuration fields, input/output format, and common failures." +--- + +Use these pages to look up CLI syntax, configuration fields, input/output format, and common failures. + +- [curate/nemo_curator CLI](/cli-curate) + +- [curate/nemo_curator Configuration](/curate-config) + +- [Curation Input and Output Format](/io-format) + +- [Curation Troubleshooting](/troubleshooting) diff --git a/docs/curate/reference/io-format.md b/docs/fern/pages-vnightly/curate/reference/io-format.mdx similarity index 75% rename from docs/curate/reference/io-format.md rename to docs/fern/pages-vnightly/curate/reference/io-format.mdx index de10fb236..ceeb55e62 100644 --- a/docs/curate/reference/io-format.md +++ b/docs/fern/pages-vnightly/curate/reference/io-format.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Input and output format for curate/nemo_curator." -topics: ["Curation", "Reference", "IO"] -tags: ["Reference", "JSONL", "Curation"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Data Scientist"] +title: "Curation Input and Output Format" +slug: "curate/reference/io-format.html" +description: "Input files must be JSON Lines. Each line is a JSON object. The configured text_field must exist on each record." --- -# Curation Input and Output Format - ## Input Input files must be JSON Lines. @@ -44,7 +36,9 @@ Use the output as `filtered_jsonl`. Common downstream paths are: - Use `translate/nemo_curator` for corpus translation. + - Use `data_prep/pretrain_prep` for pretraining data preparation. + - Use `data_prep/sft_packing` when the curated records are already in the required supervised fine-tuning (SFT) format. If a downstream step needs fields beyond `text`, verify that the curation reader/writer path preserves those fields before scaling the run. diff --git a/docs/fern/pages-vnightly/curate/reference/troubleshooting.mdx b/docs/fern/pages-vnightly/curate/reference/troubleshooting.mdx new file mode 100644 index 000000000..feecb9eb0 --- /dev/null +++ b/docs/fern/pages-vnightly/curate/reference/troubleshooting.mdx @@ -0,0 +1,27 @@ +--- +title: "Curation Troubleshooting" +slug: "curate/reference/troubleshooting.html" +description: "Symptom" +--- + +| Symptom | Likely Cause | Fix | +| --- | --- | --- | +| input_glob matches no files | Path does not exist in the current host, container, or shared mount | Use an absolute path or verify the mount. For local tiny runs, override the packaged /nemo_run/code/... path with ${PWD}/src/nemotron/steps/curate/nemo_curator/data/tiny.jsonl. | +| Missing FastText model | language_codes is non-empty but models.fasttext_langid is missing or invalid | Set language_codes=[] to disable language filtering, or provide the FastText lid.176.bin path. | +| quality_filters error about min_words and max_words | Only one word-count bound was set | Set both quality_filters.min_words and quality_filters.max_words, or set quality_filters={}. | +| Output is empty or much smaller than expected | Filters are too strict or applied before corpus shape is understood | Re-run with language_codes=[], domains=[], and quality_filters={}. Add filters back one at a time. | +| Ray worker starts a new .venv or cannot import dependencies | Local uv run and the Ray runtime environment are both attempting to manage dependency setup | Export RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 and run with uv run --no-sync after uv sync --extra curate. | +| Large local file causes memory pressure | Input shard is too large for the available Ray worker memory | Split large JSONL files into smaller shards before running Curator. | +| Domain classifier downloads repeatedly | Hugging Face cache path is not persistent | Set models.hf_cache_dir to a persistent cache location and mount it in remote profiles. | + +## Debug Checklist + +1. Run the local tiny command with filters disabled. + +2. Confirm `uv sync --extra curate` completed in the same repository clone. + +3. Confirm the input path exists where the command runs. + +4. Confirm `output_dir` is writable. + +5. Add language, word-count, and domain filters one at a time. diff --git a/docs/fern/pages-vnightly/deployment-guides.mdx b/docs/fern/pages-vnightly/deployment-guides.mdx new file mode 100644 index 000000000..e08706b2b --- /dev/null +++ b/docs/fern/pages-vnightly/deployment-guides.mdx @@ -0,0 +1,104 @@ +--- +title: "Deployment Guides" +slug: "deployment-guides.html" +description: "Deployment guides, fine-tuning recipes, and agentic usage examples for Nemotron models. Each card links to its directory in the Nemotron GitHub repository." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +{/* Card footer badges + +Add a badge only when the attribute applies. Omit it (and do not substitute its opposite) when it does not. +Absence is the signal for the simpler case. + +{bdg-success\}`Beginner` — no GPU required and no fine-tuning step. Uses an API or cloud endpoint. + Add when no other attribute badges apply. + +{bdg-success\}`Notebook` — self-contained notebook and no environment beyond pip install. + Omit for multi-file projects. + +{bdg-secondary\}`Local GPU` — requires a local GPU or managed hardware. + Omit for API/cloud-only examples. + +{bdg-info\}`Fine-tuning` — example includes a training or fine-tuning step. + Omit for inference-only examples. */} + + + +Deployment guides, fine-tuning recipes, and agentic usage examples for Nemotron models. Each card links to its directory in the [Nemotron GitHub repository](https://github.com/NVIDIA-NeMo/nemotron). + + + +Notebooks for deploying the 120B/12B-active hybrid Mamba-Transformer MoE model with vLLM, SGLang, and TensorRT-LLM. + +--- + +Notebook Local GPU Apr 28, 2026 + + + + +Supervised fine-tuning with LoRA for Text2SQL using the BIRD SQL benchmark. Includes recipes for both NeMo AutoModel and Megatron Bridge. + +--- + +Local GPU Fine-tuning Apr 28, 2026 + + + + +Deploy on a single DGX Spark with 128 GB unified memory using vLLM (nightly) and TensorRT-LLM, including NVFP4 quantization and MTP speculative decoding. + +--- + +Local GPU Apr 10, 2026 + + + + +550B total / 55B active parameter base model checkpoint announced at GTC 2026. A starting point for custom fine-tuning and RL post-training pipelines — not yet instruction-tuned. + +--- + +Local GPU Fine-tuning Mar 23, 2026 + + + + +Full-weight RL training from a base model using the GRPO/DAPO algorithm to reproduce emergent math reasoning. Requires 5× GB200 or 3× B200 nodes. + +--- + +Local GPU Fine-tuning Mar 11, 2026 + + + + +Use Nemotron 3 Super with OpenCode, OpenClaw, Kilo Code CLI, and OpenHands via OpenRouter and build.nvidia.com. + +--- + +Beginner Mar 11, 2026 + + + + +Notebooks for the 12B multimodal model that unifies visual and textual understanding. Covers NIM inference via build.nvidia.com and local Hugging Face deployment. + +--- + +Notebook Local GPU Oct 28, 2025 + + + + +Notebook for the document-parsing VLM that converts PDFs and unstructured documents into structured JSON, LaTeX, and Markdown. Available via NIM at build.nvidia.com. + +--- + +Beginner Notebook Oct 28, 2025 + + + + diff --git a/docs/fern/pages-vnightly/index.mdx b/docs/fern/pages-vnightly/index.mdx new file mode 100644 index 000000000..173e4426d --- /dev/null +++ b/docs/fern/pages-vnightly/index.mdx @@ -0,0 +1,170 @@ +--- +title: "Nemotron Training Recipes" +slug: "index.html" +description: "Open and efficient models for agentic AI. Reproducible training pipelines with transparent data, techniques, and weights." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +**Open and efficient models for agentic AI.** Reproducible training pipelines with transparent data, techniques, and weights. + +
+ +
+## Quick Start + +
+```console +// Install the Nemotron training recipes +$ git clone https://github.com/NVIDIA-NeMo/Nemotron +$ cd Nemotron && uv sync + +// Run a tiny SFT job on your cluster +$ uv run nemotron steps run sft/automodel -c tiny --run YOUR-CLUSTER + +// Run the Nano3 pipeline stage by stage +$ uv run nemotron nano3 data prep pretrain --run YOUR-CLUSTER +$ uv run nemotron nano3 pretrain --run YOUR-CLUSTER +$ uv run nemotron nano3 data prep sft --run YOUR-CLUSTER +$ uv run nemotron nano3 sft --run YOUR-CLUSTER +$ uv run nemotron nano3 data prep rl --run YOUR-CLUSTER +$ uv run nemotron nano3 rl --run YOUR-CLUSTER +``` + +
+> **Note**: The `--run YOUR-CLUSTER` flag submits jobs to your configured Slurm cluster via [NeMo-Run](/nemo_runspec/nemo-run). See [Execution through NeMo-Run](/nemo_runspec/nemo-run) for setup instructions. + +## Sample Deployments and Applications + + + +Deployment guides for Nemotron models: TensorRT-LLM, vLLM, SGLang, NIM, and Hugging Face. + + + + +End-to-end applications: RAG agents, ML agents, and multi-agent systems. + + + + + +## Customization Workflows with Nemotron Steps + + + +Translate JSONL or Parquet corpora with `translate/nemo_curator`, NeMo Curator +backends, and optional FAITH quality scoring. + + + + +Generate and translate custom multiple-choice benchmarks with `byob/mcq`. + + + + +Filter JSONL text with `curate/nemo_curator` before translation or training data preparation. + + + + +Use `sdg/data_designer` to produce SFT, tool-use, and preference datasets. + + + + +Evaluate hosted endpoints or checkpoints with `eval/model_eval`. + + + + + +## Training Recipes + + + +31.6B total / 3.6B active parameters, 25T tokens, up to 1M context. Hybrid Mamba-Transformer with sparse MoE. + +**Stages:** Pretraining → SFT → RL + + + + +GA-checkpoint multimodal post-training recipe with stage-local container builds and a three-step RL stack. + +**Stages:** SFT → RL MPO → RL text → RL vision → Eval + + + + +Fine-tune Llama-Nemotron-Embed-1B-v2 on domain-specific data with synthetic data generation, evaluation, and NIM deployment. + +**Stages:** SDG → Data Prep → Finetune → Eval → Export → Deploy + + + + +Fine-tune Llama-Nemotron-Rerank-1B-v2 cross-encoders for domain-specific reranking with synthetic data generation, evaluation, export, and NIM deployment. + +**Stages:** SDG → Data Prep → Finetune → Eval → Export → Deploy + + + + + +## Recipe Layout + +Nemotron keeps **data-producing recipes** separate from **model-family training recipes**: + +| Path | Purpose | Example | +| --- | --- | --- | +| src/nemotron/recipes/data/curation/ | Filter, dedup, and curate existing corpora | [Nemotron-CC](/nemotron/data/curation/nemotron-cc) | +| src/nemotron/recipes/data/sdg/ | Generate synthetic datasets that can feed multiple families | [Long-document SDG](/nemotron/data/sdg/long-document) feeding [Omni3 SFT](/nemotron/omni3/sft) | +| src/nemotron/recipes/<family>/ | Family-specific training, RL, evaluation, and model lifecycle commands | [Nano3](/nemotron/nano3/README), [Omni3](/nemotron/omni3/README) | + +## Training Pipeline + +Each recipe family has its own stage layout, and all of them can be tracked through [artifact lineage](/nemotron/artifacts): + +| Family | Stage layout | +| --- | --- | +| [Nano3](/nemotron/nano3/README) | Pretraining → SFT → RL | +| [Omni3](/nemotron/omni3/README) | SFT → RL MPO → RL text → RL vision → Eval | +| [Super3](/nemotron/super3/README) | Pretraining → SFT → RL → Quantization → Eval | +| [Embed](/nemotron/embed/README) | SDG → Data Prep → Finetune → Eval → Export → Deploy | +| [Rerank](/nemotron/rerank/README) | SDG → Data Prep → Finetune → Eval → Export → Deploy | + +## Why Nemotron? + +| | | +| --- | --- | +| **Open Models** | Transparent training data, techniques, and weights for community innovation | +| **Compute Efficiency** | Model pruning enabling higher throughput via TensorRT-LLM | +| **High Accuracy** | Built on frontier open models with human-aligned reasoning | +| **Flexible Deployment** | Deploy anywhere: edge, single GPU, or data center with NIM | + +## Features + +- **End-to-end pipelines** from raw data to deployment-ready models + +- **[Artifact lineage](/nemotron/artifacts)** via [W&B](/nemotron/wandb) from data to model + +- **Built on [NVIDIA’s NeMo stack](/nemotron/nvidia-stack)** (Megatron-Bridge, NeMo-RL) + +- **Reproducible** with versioned configs, data blends, and checkpoints + +## Resources + +- [Tech Report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf) – Nemotron 3 Nano methodology + +- [Model Weights](https://huggingface.co/collections/nvidia/nvidia-nemotron-v3) – pre-trained checkpoints on HuggingFace + +- [Pre-training Datasets](https://huggingface.co/collections/nvidia/nemotron-pre-training-datasets) – open pre-training data + +- [Post-training Datasets](https://huggingface.co/collections/nvidia/nemotron-post-training-v3) – SFT and RL data + +- [Artifact Lineage](/nemotron/artifacts) – W&B integration guide + +- [Model training steps](/train-models/index) – SFT, PEFT, RL, and optimization with `nemotron step run` diff --git a/docs/fern/pages-vnightly/model-eval/explanation/endpoint-types-and-benchmarks.mdx b/docs/fern/pages-vnightly/model-eval/explanation/endpoint-types-and-benchmarks.mdx new file mode 100644 index 000000000..9f2e5b65c --- /dev/null +++ b/docs/fern/pages-vnightly/model-eval/explanation/endpoint-types-and-benchmarks.mdx @@ -0,0 +1,51 @@ +--- +title: "Endpoint Types And Task Families" +slug: "model-eval/explanation/endpoint-types-and-benchmarks.html" +description: "eval/model_eval passes endpoint and task configuration to NeMo Evaluator Launcher. The endpoint type must match the selected task family." +--- + + + +`eval/model_eval` passes endpoint and task configuration to NeMo Evaluator Launcher. +The endpoint type must match the selected task family. + +## Endpoint Fields + +Hosted endpoint runs use: + +```text +target.api_endpoint.url +target.api_endpoint.model_id +target.api_endpoint.api_key_name +target.api_endpoint.type +``` + +The `type` value is usually `chat` or `completions`. +The URL path should agree with that value. + +## Task Families + +- Chat and instruction tasks issue chat-completions requests and score generated answers. + +- Log-probability tasks need a completions endpoint with logprobs support and a tokenizer that matches the served model. + +## Decision Table + +| Task family | Required endpoint type | Extra requirements | +| --- | --- | --- | +| Hosted chat smoke tests | chat | A chat-completions URL and a valid API key. | +| Instruction/chat tasks | chat | Generation parameters appropriate for the model and task. | +| Log-probability tasks | completions | A completions endpoint with logprobs support and a matching tokenizer. | + +The repository smoke-test config, `tiny_chat.yaml`, uses `mmlu_instruct` with `target.api_endpoint.type=chat`. +The checkpoint config, `default.yaml`, includes launcher tasks for Megatron checkpoint evaluation; verify endpoint and tokenizer requirements before changing those tasks. + +## Related Pages + +- [Tokenizer Alignment](/tokenizer-alignment) for the tokenizer side of log-probability tasks. + +- [Pipeline Overview](/pipeline-overview) for where endpoint config enters the run. + +- [Evaluate A Deployed Checkpoint](/../how-to/evaluate-deployed-checkpoint) for choosing the hosted or checkpoint path. + +- [Tasks Catalog](/../reference/benchmarks-catalog) for task identifiers. diff --git a/docs/fern/pages-vnightly/model-eval/explanation/index.mdx b/docs/fern/pages-vnightly/model-eval/explanation/index.mdx new file mode 100644 index 000000000..7d5bf7b21 --- /dev/null +++ b/docs/fern/pages-vnightly/model-eval/explanation/index.mdx @@ -0,0 +1,45 @@ +--- +title: "Concepts" +slug: "model-eval/explanation/index.html" +description: "The pages in this section cover the design rules behind eval/model_eval. Read them when you want to understand why the how-to pages take the actions they do, before you change a configuration default " +--- + +The pages in this section cover the design rules behind `eval/model_eval`. +Read them when you want to understand why the how-to pages take the actions they do, before you change a configuration default or adapt a recipe to a new deployment. + +## Pipeline And Architecture + + + +Artifact flow from a checkpoint or hosted endpoint, through `eval/model_eval`, into `eval_results` on disk. + +--- + +architecture + + + + + +## Deployment Contract + + + +Chat versus completions endpoints, and which benchmark families match each one. + +--- + +endpoint + + + + +Why log-probability benchmarks need a tokenizer that matches the served model. + +--- + +tokenizer + + + + diff --git a/docs/model-eval/explanation/pipeline-overview.md b/docs/fern/pages-vnightly/model-eval/explanation/pipeline-overview.mdx similarity index 62% rename from docs/model-eval/explanation/pipeline-overview.md rename to docs/fern/pages-vnightly/model-eval/explanation/pipeline-overview.mdx index 4afd034c6..7c76e9ca8 100644 --- a/docs/model-eval/explanation/pipeline-overview.md +++ b/docs/fern/pages-vnightly/model-eval/explanation/pipeline-overview.mdx @@ -1,17 +1,10 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "How nemotron eval/model_eval builds a NeMo Evaluator Launcher config and writes eval_results." -topics: ["Model Evaluation", "Pipeline"] -tags: ["Explanation", "Architecture"] -content: - type: "Explanation" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] +title: "Pipeline Overview" +slug: "model-eval/explanation/pipeline-overview.html" +description: "The eval/model_eval step is a thin Nemotron wrapper around NeMo Evaluator Launcher. It does not implement benchmark scoring itself. It loads a YAML config, applies command-line overrides, saves the la" --- -(model-eval-pipeline-overview)= -# Pipeline Overview + The `eval/model_eval` step is a thin Nemotron wrapper around NeMo Evaluator Launcher. It does not implement benchmark scoring itself. @@ -19,7 +12,7 @@ It loads a YAML config, applies command-line overrides, saves the launcher confi ## Architecture -```{mermaid} +```mermaid %%{init: {'theme': 'base', 'themeVariables': { 'primaryBorderColor': '#333333', 'lineColor': '#333333', 'primaryTextColor': '#333333', 'clusterBkg': '#ffffff', 'clusterBorder': '#333333'}}}%% flowchart LR hosted["Hosted OpenAI-compatible endpoint"] --> cfg["target.api_endpoint"] @@ -33,11 +26,17 @@ flowchart LR ## Runtime Flow 1. `step.py` calls `run_model_eval` from `runtime.py`. + 1. The runtime loads the selected config from `config/default.yaml`, `config/tiny_chat.yaml`, or a user-supplied YAML path. + 1. Hydra-style dotlist overrides are merged into the config. + 1. Nemotron-only keys are removed before launcher dispatch: `dry_run`, `output_dir`, `task_filters`, and `run`. + 1. `output_dir` is copied into `execution.output_dir`. + 1. The resolved launcher config is saved and printed as `launcher_config`. + 1. `nemo_evaluator_launcher.api.functional.run_eval` is called with the launcher config and optional task filters. ## Input Artifacts @@ -50,19 +49,22 @@ Launcher-managed checkpoint runs usually pass a concrete Megatron Bridge `iter_* The step produces `eval_results`. The exact directory layout and files are owned by NeMo Evaluator Launcher and the selected task implementations. -For result inspection guidance, refer to {doc}`../reference/output-artifacts`. +For result inspection guidance, refer to [Output Artifacts](/../reference/output-artifacts). ## What Is Owned Where | Owned by Nemotron | Owned by NeMo Evaluator Launcher | | --- | --- | | Step discovery, config loading, dotlist overrides, launcher config saving. | Task implementations, endpoint probing, deployment orchestration, and result files. | -| `dry_run`, `output_dir`, `task_filters`, and `run` preprocessing. | `execution`, `deployment`, `target`, `evaluation`, `tasks`, and `export` semantics after dispatch. | -| The `step.toml` contract and agent-facing guidance. | Accepted task identifiers and version-specific task behavior. | +| dry_run, output_dir, task_filters, and run preprocessing. | execution, deployment, target, evaluation, tasks, and export semantics after dispatch. | +| The step.toml contract and agent-facing guidance. | Accepted task identifiers and version-specific task behavior. | ## Related Pages -- {doc}`endpoint-types-and-benchmarks` for endpoint/task pairing. -- {doc}`tokenizer-alignment` for why log-probability tasks need a matching tokenizer. -- {doc}`../reference/output-artifacts` for result inspection. -- {doc}`../how-to/discover-the-step` for reading the step contract before configuring a run. +- [Endpoint Types And Task Families](/endpoint-types-and-benchmarks) for endpoint/task pairing. + +- [Tokenizer Alignment](/tokenizer-alignment) for why log-probability tasks need a matching tokenizer. + +- [Output Artifacts](/../reference/output-artifacts) for result inspection. + +- [Discover The Model Evaluation Step](/../how-to/discover-the-step) for reading the step contract before configuring a run. diff --git a/docs/model-eval/explanation/tokenizer-alignment.md b/docs/fern/pages-vnightly/model-eval/explanation/tokenizer-alignment.mdx similarity index 55% rename from docs/model-eval/explanation/tokenizer-alignment.md rename to docs/fern/pages-vnightly/model-eval/explanation/tokenizer-alignment.mdx index 6ecf69b94..0adcf41cd 100644 --- a/docs/model-eval/explanation/tokenizer-alignment.md +++ b/docs/fern/pages-vnightly/model-eval/explanation/tokenizer-alignment.mdx @@ -1,17 +1,10 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Why log-probability tasks in eval/model_eval require a tokenizer that matches the served model." -topics: ["Model Evaluation", "Tokenizer"] -tags: ["Explanation", "Model Evaluation"] -content: - type: "Explanation" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] +title: "Tokenizer Alignment" +slug: "model-eval/explanation/tokenizer-alignment.html" +description: "The hosted chat smoke path in tiny_chat.yaml does not require a tokenizer override. Tokenizer alignment becomes important when you run log-probability tasks such as HellaSwag or other tasks that score" --- -(model-eval-tokenizer-alignment)= -# Tokenizer Alignment + The hosted chat smoke path in `tiny_chat.yaml` does not require a tokenizer override. Tokenizer alignment becomes important when you run log-probability tasks such as HellaSwag or other tasks that score candidate continuations by token likelihood. @@ -25,7 +18,7 @@ evaluation.nemo_evaluator_config.config.params.extra.tokenizer evaluation.nemo_evaluator_config.config.params.extra.tokenizer_backend ``` -The `default.yaml` config sets the tokenizer to `${deployment.checkpoint_path}/tokenizer`, which matches the Megatron Bridge checkpoint path when that checkpoint contains a tokenizer subdirectory. +The `default.yaml` config sets the tokenizer to `$\{deployment.checkpoint_path\}/tokenizer`, which matches the Megatron Bridge checkpoint path when that checkpoint contains a tokenizer subdirectory. ## Why It Must Match @@ -37,14 +30,19 @@ If the evaluator tokenizes candidates differently from the served model, the mod Use one of these tokenizer values when a selected task requires local tokenization: - A Hugging Face model id. + - A filesystem path containing tokenizer files. + - The `tokenizer/` subdirectory inside a Megatron Bridge `iter_*` checkpoint. Use `huggingface` for `evaluation.nemo_evaluator_config.config.params.extra.tokenizer_backend` unless the selected launcher task explicitly requires another backend. ## Related Pages -- {doc}`endpoint-types-and-benchmarks` for endpoint/task pairing. -- {doc}`pipeline-overview` for runtime flow. -- {doc}`../reference/config-schema` for field-by-field documentation. -- {doc}`../reference/troubleshooting` for common tokenizer and checkpoint-path failures. +- [Endpoint Types And Task Families](/endpoint-types-and-benchmarks) for endpoint/task pairing. + +- [Pipeline Overview](/pipeline-overview) for runtime flow. + +- [Configuration Reference](/../reference/config-schema) for field-by-field documentation. + +- [Troubleshooting](/../reference/troubleshooting) for common tokenizer and checkpoint-path failures. diff --git a/docs/fern/pages-vnightly/model-eval/getting-started.mdx b/docs/fern/pages-vnightly/model-eval/getting-started.mdx new file mode 100644 index 000000000..70563f50b --- /dev/null +++ b/docs/fern/pages-vnightly/model-eval/getting-started.mdx @@ -0,0 +1,179 @@ +--- +title: "Getting Started With Model Evaluation" +slug: "model-eval/getting-started.html" +description: "In this tutorial, you will:" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + + + +**In this tutorial, you will**: + +1. Discover the `eval/model_eval` step from the local catalog. + +1. Inspect the hosted-endpoint sample config, `tiny_chat.yaml`. + +1. Run a one-sample hosted chat evaluation. + +1. List the result files on disk. + + This tutorial requires between 15 and 30 minutes to complete, depending on endpoint latency. + + + + +Run a one-sample hosted chat evaluation with `eval/model_eval` and `tiny_chat.yaml`, then show me the launcher config and result files. + + + + + +## Prerequisites + +- Run all commands from the repository root. + +- Install the evaluator extra: + + ```console + $ uv sync --extra evaluator + ``` + +- A reachable OpenAI-compatible chat-completions endpoint. + +- A model identifier advertised by that endpoint. + +- A bearer token exported as the environment variable referenced by `target.api_endpoint.api_key_name`. + +## About The Sample Configuration + +The hosted chat sample file is at `src/nemotron/steps/eval/model_eval/config/tiny_chat.yaml`. +It sets `deployment.type: none`, points NeMo Evaluator Launcher at `target.api_endpoint`, and runs the chat-compatible `mmlu_instruct` task with `limit_samples: 1`. + +```yaml startLine={1} +# Tiny hosted chat endpoint smoke-test config. +# +# Export endpoint settings before running: +# export NEMO_EVALUATOR_MODEL_ID=\ +# export NEMO_EVALUATOR_MODEL_URL=\ +# export NEMO_EVALUATOR_API_KEY_NAME=NVIDIA_API_KEY +# export NEMO_EVALUATOR_ENDPOINT_TYPE=chat + +dry_run: false +output_dir: ./results-tiny-chat +task_filters: null + +execution: + type: local + mode: sequential + output_dir: $\{output_dir\} + +deployment: + type: none + +target: + api_endpoint: + model_id: ${oc.env:NEMO_EVALUATOR_MODEL_ID,''} + url: ${oc.env:NEMO_EVALUATOR_MODEL_URL,''} + api_key_name: ${oc.env:NEMO_EVALUATOR_API_KEY_NAME,NVIDIA_API_KEY} + type: ${oc.env:NEMO_EVALUATOR_ENDPOINT_TYPE,chat} + +evaluation: + nemo_evaluator_config: + config: + params: + temperature: 0.0 + top_p: 1.0 + max_new_tokens: 1024 + max_retries: 5 + parallelism: 1 + request_timeout: 3600 + limit_samples: 1 + target: + api_endpoint: + adapter_config: + output_dir: /results + use_progress_tracking: false + use_caching: true + caching_dir: /results/cache + use_response_logging: true + max_logged_responses: 5 + use_request_logging: true + max_logged_requests: 5 + tasks: + - name: mmlu_instruct +``` + +## Procedure + +1. Clone the repository, if you haven’t already: + + ```console + $ git clone https://github.com/NVIDIA-NeMo/Nemotron && cd Nemotron + ``` + +1. Synchronize dependencies: + + ```console + $ uv sync --extra evaluator + ``` + +1. Export the endpoint values. +`EVAL_ROOT` is a directory you choose; it is the parent of the per-run `output_dir`. + + ```console + $ export NVIDIA_API_KEY="\" + $ export NEMO_EVALUATOR_MODEL_URL="\" + $ export NEMO_EVALUATOR_MODEL_ID="\" + $ export NEMO_EVALUATOR_ENDPOINT_TYPE=chat + $ export EVAL_ROOT="$(pwd)/output/eval-getting-started" + ``` + +1. Confirm that the local catalog exposes `eval/model_eval`. + + ```console + $ uv run --no-sync nemotron steps show eval/model_eval + ``` + +1. Run the hosted chat smoke test. + + ```console + $ uv run --no-sync nemotron steps run eval/model_eval \ + -c tiny_chat \ + output_dir="$EVAL_ROOT/results-tiny-chat" \ + target.api_endpoint.url="$NEMO_EVALUATOR_MODEL_URL" \ + target.api_endpoint.model_id="$NEMO_EVALUATOR_MODEL_ID" \ + target.api_endpoint.api_key_name=NVIDIA_API_KEY \ + target.api_endpoint.type=chat \ + evaluation.nemo_evaluator_config.config.params.limit_samples=1 + ``` + + The step writes the launcher config path to stdout. +If NeMo Evaluator Launcher returns an invocation id, the step also prints `status_command` and `logs_command` values that you can run to inspect the job. +Treat those commands as part of the run: wait until the launcher reports a +terminal status before expecting final metric artifacts. + + To inspect the merged Nemotron job config without invoking the launcher, add `--dry-run`. +To pass NeMo Evaluator Launcher’s own dry-run flag, use the config override `dry_run=true`. + +1. List the files written under the output directory after the launcher job +reaches a terminal status. + + ```console + $ find "$EVAL_ROOT/results-tiny-chat" -maxdepth 5 -type f | sort + ``` + + The exact file names are owned by NeMo Evaluator Launcher and can vary by task version. + +## Next Steps + +- Run the standard checkpoint-evaluation config: [Evaluate A Deployed Checkpoint](/how-to/evaluate-deployed-checkpoint). + +- Look up the full YAML schema: [Configuration Reference](/reference/config-schema). + +- Drive the step from a coding agent: [Use The Model Evaluation Skill With Confidence](/using-skills). + +- Run hosted evaluations with custom task settings: [Run A Hosted Evaluation](/how-to/run-hosted-evaluation). diff --git a/docs/fern/pages-vnightly/model-eval/how-to/discover-the-step.mdx b/docs/fern/pages-vnightly/model-eval/how-to/discover-the-step.mdx new file mode 100644 index 000000000..7caca4521 --- /dev/null +++ b/docs/fern/pages-vnightly/model-eval/how-to/discover-the-step.mdx @@ -0,0 +1,244 @@ +--- +title: "Discover The Model Evaluation Step" +slug: "model-eval/how-to/discover-the-step.html" +description: "This guide shows how to find eval/model_eval in the step catalog, how to read its contract, and how to decide whether it applies." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + +This guide shows how to find `eval/model_eval` in the step catalog, how to read its contract, and how to decide whether it applies. + +## Prerequisites + +- The Nemotron repository is synced. + +- A local checkout is sufficient; discovery reads local `step.toml` files only. + +## List Eval-Category Steps + +```bash +uv run --no-sync nemotron steps list --category eval --json +``` + +The response includes `eval/model_eval`, the step that wraps NeMo Evaluator Launcher. + +## Inspect The Step Contract + +```bash +uv run --no-sync nemotron steps show eval/model_eval --json +``` + +The response contains the fields declared in `src/nemotron/steps/eval/model_eval/step.toml`. + +| Field | What It Tells You | +| --- | --- | +| consumes | Optional input artifact type. This step accepts checkpoint_megatron. | +| produces | Output artifact type. This step produces eval_results. | +| parameters | Documented knobs such as target.api_endpoint.*, deployment.checkpoint_path, task_filters, and launcher params. | +| strategies | Rules for hosted smoke tests, checkpoint evaluation, endpoint/task pairing, and task-name selection. | +| errors | Named failure modes and recovery guidance. | +| reference | Upstream NeMo Evaluator Launcher references. | + +## Read The Sample Files + +The step provides two config files under `src/nemotron/steps/eval/model_eval/config/`. + +```yaml startLine={1} +# Tiny hosted chat endpoint smoke-test config. +# +# Export endpoint settings before running: +# export NEMO_EVALUATOR_MODEL_ID=\ +# export NEMO_EVALUATOR_MODEL_URL=\ +# export NEMO_EVALUATOR_API_KEY_NAME=NVIDIA_API_KEY +# export NEMO_EVALUATOR_ENDPOINT_TYPE=chat + +dry_run: false +output_dir: ./results-tiny-chat +task_filters: null + +execution: + type: local + mode: sequential + output_dir: $\{output_dir\} + +deployment: + type: none + +target: + api_endpoint: + model_id: ${oc.env:NEMO_EVALUATOR_MODEL_ID,''} + url: ${oc.env:NEMO_EVALUATOR_MODEL_URL,''} + api_key_name: ${oc.env:NEMO_EVALUATOR_API_KEY_NAME,NVIDIA_API_KEY} + type: ${oc.env:NEMO_EVALUATOR_ENDPOINT_TYPE,chat} + +evaluation: + nemo_evaluator_config: + config: + params: + temperature: 0.0 + top_p: 1.0 + max_new_tokens: 1024 + max_retries: 5 + parallelism: 1 + request_timeout: 3600 + limit_samples: 1 + target: + api_endpoint: + adapter_config: + output_dir: /results + use_progress_tracking: false + use_caching: true + caching_dir: /results/cache + use_response_logging: true + max_logged_responses: 5 + use_request_logging: true + max_logged_requests: 5 + tasks: + - name: mmlu_instruct +``` + +`tiny_chat.yaml` is the hosted chat smoke-test config. +It sets `deployment.type: none`, reads `target.api_endpoint.*` from environment variables, and runs `mmlu_instruct` with `limit_samples: 1`. + +```yaml startLine={1} +# Standard NeMo Evaluator Launcher config for Megatron checkpoint evaluation. +# +# This mirrors the Nano3/Super3 eval shape: the `run` section is used by +# Nemotron for env/profile/artifact interpolation, then removed before handing +# the config to NeMo Evaluator Launcher. + +dry_run: false +output_dir: ./results + +run: + # Use a concrete Megatron Bridge iter_* checkpoint via + # `deployment.checkpoint_path=...`, or keep this as a W&B artifact reference + # consumed by `${art:model,path}`. + model: model:latest + env: + executor: local + container_image: nvcr.io/nvidia/nemo:25.11.nemotron_3_nano + host: ${oc.env:HOSTNAME,localhost} + user: ${oc.env:USER,''} + account: null + partition: null + remote_job_dir: ${oc.env:PWD}/.nemotron + time: "04:00:00" + wandb: + entity: null + project: null + +execution: + type: ${run.env.executor} + hostname: ${run.env.host} + username: ${run.env.user} + account: ${run.env.account} + partition: ${run.env.partition} + output_dir: $\{output_dir\} + walltime: ${run.env.time} + num_nodes: ${oc.select:run.env.nodes,1} + deployment: + n_tasks: ${execution.num_nodes} + auto_export: + destinations: + - wandb + env_vars: + deployment: + HF_HOME: ${run.env.remote_job_dir}/hf + HF_TOKEN: HF_TOKEN + NIM_CACHE_PATH: ${run.env.remote_job_dir}/nim + VLLM_CACHE_ROOT: ${run.env.remote_job_dir}/vllm + evaluation: + HF_HOME: ${run.env.remote_job_dir}/hf + HF_TOKEN: HF_TOKEN + mounts: + deployment: {} + evaluation: {} + mount_home: false + +deployment: + type: generic + image: ${run.env.container_image} + checkpoint_path: ${art:model,path} + multiple_instances: false + port: 1235 + served_model_name: nemo-model + health_check_path: /v1/health + command: >- + bash -c 'export TRITON_CACHE_DIR=/tmp/triton_cache; + python /opt/Export-Deploy/scripts/deploy/nlp/deploy_ray_inframework.py + --megatron_checkpoint /checkpoint/ + --num_gpus ${oc.select:run.env.gpus_per_node,1} + --tensor_model_parallel_size 1 + --expert_model_parallel_size 1 + --port 1235 + --num_replicas 1' + endpoints: + chat: /v1/chat/completions/ + completions: /v1/completions/ + health: /v1/health + +evaluation: + nemo_evaluator_config: + config: + params: + max_retries: 5 + parallelism: 4 + request_timeout: 6000 + limit_samples: null + extra: + tokenizer: ${deployment.checkpoint_path}/tokenizer + tokenizer_backend: huggingface + target: + api_endpoint: + adapter_config: + output_dir: /results + use_progress_tracking: false + use_caching: true + caching_dir: /results/cache + use_response_logging: true + max_logged_responses: 10 + use_request_logging: true + max_logged_requests: 10 + tasks: + - name: adlr_mmlu + nemo_evaluator_config: + config: + params: + top_p: 0.0 + - name: hellaswag + +export: + wandb: + entity: ${run.wandb.entity} + project: ${run.wandb.project} +``` + +`default.yaml` is the Megatron Bridge checkpoint evaluation config. +It uses NeMo Evaluator Launcher deployment and evaluates the configured `tasks` entries. + +## Decide Whether It Applies + +`eval/model_eval` applies when the following statements are true. + +- The model is already available as an OpenAI-compatible endpoint, or NeMo Evaluator Launcher can deploy the checkpoint from the selected config. + +- The tasks you need are implemented by the installed NeMo Evaluator Launcher stack. + +- The endpoint type matches the selected task family. + +`eval/model_eval` is not the right step when the evaluation needs a custom scorer that NeMo Evaluator Launcher does not implement. +Write a dedicated evaluation step in that case, modeled on the contract layout under `src/nemotron/steps/`. + +## Related + +- `src/nemotron/steps/eval/model_eval/step.toml` for the full step contract. + +- [Run A Hosted Evaluation](/run-hosted-evaluation) for the first procedural walk-through after discovery. + +- [Configuration Reference](/../reference/config-schema) for field-by-field YAML reference. + +- [CLI Reference](/../reference/cli-reference) for the flag and override surface. diff --git a/docs/model-eval/how-to/evaluate-deployed-checkpoint.md b/docs/fern/pages-vnightly/model-eval/how-to/evaluate-deployed-checkpoint.mdx similarity index 59% rename from docs/model-eval/how-to/evaluate-deployed-checkpoint.md rename to docs/fern/pages-vnightly/model-eval/how-to/evaluate-deployed-checkpoint.mdx index 3c2a0f52f..40e2d1b79 100644 --- a/docs/model-eval/how-to/evaluate-deployed-checkpoint.md +++ b/docs/fern/pages-vnightly/model-eval/how-to/evaluate-deployed-checkpoint.mdx @@ -1,30 +1,36 @@ - +--- +title: "Evaluate A Deployed Checkpoint" +slug: "model-eval/how-to/evaluate-deployed-checkpoint.html" +description: "This guide covers the two supported evaluation shapes in the current eval/model_eval step." +--- -(model-eval-evaluate-deployed-checkpoint)= -# Evaluate A Deployed Checkpoint +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + This guide covers the two supported evaluation shapes in the current `eval/model_eval` step. - Use `tiny_chat.yaml` when the model is already hosted behind an OpenAI-compatible chat endpoint. + - Use `default.yaml` when NeMo Evaluator Launcher should deploy a Megatron Bridge checkpoint and run the configured tasks. ## Prerequisites - `uv sync --extra evaluator` has completed. + - For hosted evaluation, you have the endpoint URL, model id, and API key environment variable. + - For checkpoint evaluation, you have a concrete Megatron Bridge `iter_*` checkpoint path. ## Hosted Endpoint Path -For an existing endpoint, use the same command shape as {doc}`run-hosted-evaluation`. +For an existing endpoint, use the same command shape as [Run A Hosted Evaluation](/run-hosted-evaluation). ```bash -export NVIDIA_API_KEY="" -export NEMO_EVALUATOR_MODEL_URL="https:///v1/chat/completions" -export NEMO_EVALUATOR_MODEL_ID="" +export NVIDIA_API_KEY="\" +export NEMO_EVALUATOR_MODEL_URL="https://\/v1/chat/completions" +export NEMO_EVALUATOR_MODEL_ID="\" uv run --no-sync nemotron steps run eval/model_eval \ -c tiny_chat \ @@ -56,7 +62,7 @@ If you change tasks to a log-probability task, keep `evaluation.nemo_evaluator_c The endpoint type must match the task family. Chat and instruction tasks need `target.api_endpoint.type=chat`. Log-probability tasks such as HellaSwag need a completions endpoint with logprobs support and a matching tokenizer. -For the matching rule, refer to {doc}`../explanation/endpoint-types-and-benchmarks`. +For the matching rule, refer to [Endpoint Types And Task Families](/../explanation/endpoint-types-and-benchmarks). ## What To Check After Submission @@ -64,16 +70,20 @@ The step prints the launcher config path. When NeMo Evaluator Launcher returns an invocation id, it also prints: ```text -status_command: nemo-evaluator-launcher status -logs_command: nemo-evaluator-launcher logs +status_command: nemo-evaluator-launcher status \ +logs_command: nemo-evaluator-launcher logs \ ``` Run those commands to monitor the job, then inspect `output_dir` after completion. ## Related -- {doc}`run-hosted-evaluation` for the hosted endpoint walk-through. -- {doc}`../explanation/index` for endpoint type, tokenizer alignment, and task-family concepts. -- {ref}`model-eval-comparing-runs` for before-and-after evaluation framing. -- {doc}`../../deployment-guides` for broader deployment options. -- {doc}`../reference/config-schema` for the YAML field reference. +- [Run A Hosted Evaluation](/run-hosted-evaluation) for the hosted endpoint walk-through. + +- [Concepts](/../explanation/index) for endpoint type, tokenizer alignment, and task-family concepts. + +- [Comparing Runs](/../reference/output-artifacts#model-eval-comparing-runs) for before-and-after evaluation framing. + +- [Deployment Guides](/../../deployment-guides) for broader deployment options. + +- [Configuration Reference](/../reference/config-schema) for the YAML field reference. diff --git a/docs/fern/pages-vnightly/model-eval/how-to/index.mdx b/docs/fern/pages-vnightly/model-eval/how-to/index.mdx new file mode 100644 index 000000000..7fc19479c --- /dev/null +++ b/docs/fern/pages-vnightly/model-eval/how-to/index.mdx @@ -0,0 +1,46 @@ +--- +title: "Model Evaluation How-To Guides" +slug: "model-eval/how-to/index.html" +description: "This section provides task-focused procedures for running eval/model_eval. For your first run, start with Getting Started With Model Evaluation. For agent-driven sessions, read Use The Model Evaluatio" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + +This section provides task-focused procedures for running `eval/model_eval`. +For your first run, start with [Getting Started With Model Evaluation](/../getting-started). +For agent-driven sessions, read [Use The Model Evaluation Skill With Confidence](/../using-skills) first. + +## Choose A Guide + + + +List the step, read its contract, and decide whether it applies to the task. + +--- + +discovery + + + + +Run benchmarks against an already-running, OpenAI-compatible endpoint. + +--- + +hosted-endpoint + + + + +Choose a deployment path, deploy the endpoint, and point the step at it. + +--- + +deployment + + + + diff --git a/docs/model-eval/how-to/run-hosted-evaluation.md b/docs/fern/pages-vnightly/model-eval/how-to/run-hosted-evaluation.mdx similarity index 58% rename from docs/model-eval/how-to/run-hosted-evaluation.md rename to docs/fern/pages-vnightly/model-eval/how-to/run-hosted-evaluation.mdx index 664820aca..e9cf70a9d 100644 --- a/docs/model-eval/how-to/run-hosted-evaluation.md +++ b/docs/fern/pages-vnightly/model-eval/how-to/run-hosted-evaluation.mdx @@ -1,10 +1,13 @@ - +--- +title: "Run A Hosted Evaluation" +slug: "model-eval/how-to/run-hosted-evaluation.html" +description: "This guide runs eval/model_eval against an already-running OpenAI-compatible endpoint. For the out-of-the-box hosted smoke test, use tiny_chat.yaml." +--- -(model-eval-run-hosted-evaluation)= -# Run A Hosted Evaluation +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + This guide runs `eval/model_eval` against an already-running OpenAI-compatible endpoint. For the out-of-the-box hosted smoke test, use `tiny_chat.yaml`. @@ -12,25 +15,28 @@ For the out-of-the-box hosted smoke test, use `tiny_chat.yaml`. ## Prerequisites - The Nemotron repository is synced with `uv sync --extra evaluator`. + - A reachable endpoint URL. -- The endpoint's advertised model id. + +- The endpoint’s advertised model id. + - A credential exported as an environment variable. ## Choose The Starting Config | Config | Use | | --- | --- | -| `tiny_chat.yaml` | Hosted chat smoke test. Runs `mmlu_instruct` with `limit_samples: 1`. | -| `default.yaml` | Launcher-managed checkpoint deployment and evaluation. Use this when the launcher should deploy a Megatron Bridge checkpoint. | +| tiny_chat.yaml | Hosted chat smoke test. Runs mmlu_instruct with limit_samples: 1. | +| default.yaml | Launcher-managed checkpoint deployment and evaluation. Use this when the launcher should deploy a Megatron Bridge checkpoint. | Hosted chat QA should start with `tiny_chat.yaml`. ## Set Endpoint Values ```bash -export NVIDIA_API_KEY="" -export NEMO_EVALUATOR_MODEL_URL="" -export NEMO_EVALUATOR_MODEL_ID="" +export NVIDIA_API_KEY="\" +export NEMO_EVALUATOR_MODEL_URL="\" +export NEMO_EVALUATOR_MODEL_ID="\" export NEMO_EVALUATOR_ENDPOINT_TYPE=chat ``` @@ -78,7 +84,10 @@ The exact file set is owned by NeMo Evaluator Launcher and can vary by task vers ## Related -- {doc}`discover-the-step` for discovery commands. -- {doc}`evaluate-deployed-checkpoint` for the launcher-managed checkpoint path. -- {doc}`../reference/cli-reference` for the full flag and override surface. -- {doc}`../reference/config-schema` for the YAML field reference. +- [Discover The Model Evaluation Step](/discover-the-step) for discovery commands. + +- [Evaluate A Deployed Checkpoint](/evaluate-deployed-checkpoint) for the launcher-managed checkpoint path. + +- [CLI Reference](/../reference/cli-reference) for the full flag and override surface. + +- [Configuration Reference](/../reference/config-schema) for the YAML field reference. diff --git a/docs/fern/pages-vnightly/model-eval/index.mdx b/docs/fern/pages-vnightly/model-eval/index.mdx new file mode 100644 index 000000000..2dd682e9b --- /dev/null +++ b/docs/fern/pages-vnightly/model-eval/index.mdx @@ -0,0 +1,184 @@ +--- +title: "About Model Evaluation" +slug: "model-eval/index.html" +description: "The eval/model_eval Nemotron step is a wrapper around NeMo Evaluator Launcher. It runs launcher tasks against either an existing OpenAI-compatible endpoint or a launcher-managed Megatron Bridge checkp" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + +The `eval/model_eval` Nemotron step is a wrapper around NeMo Evaluator Launcher. +It runs launcher tasks against either an existing OpenAI-compatible endpoint or a launcher-managed Megatron Bridge checkpoint deployment, then writes an `eval_results` artifact to disk. + + +New to model evaluation or the Nemotron CLI? +Read [Use The Model Evaluation Skill With Confidence](/using-skills) for a short guide to productive agent sessions, then start the [Getting Started With Model Evaluation](/getting-started) tutorial to run one benchmark on one sample against a hosted endpoint. + + + +## When To Use + +Use `eval/model_eval` when the work matches one of the following. + +- Score a trained checkpoint with NeMo Evaluator Launcher tasks. + +- Compare a new training run against a baseline by running the same task set against both, with generation parameters and endpoint type held constant. + +- Perform a sample run against a hosted endpoint, to confirm the URL, credential, and model id before scaling up. + +- Pair this step with a baseline evaluation before training to capture before-and-after measurements around a training change, by following [Comparing Runs](/reference/output-artifacts#model-eval-comparing-runs). + +## Pipeline At A Glance + +```mermaid +%%{init: {'theme': 'base', 'themeVariables': { 'primaryBorderColor': '#333333', 'lineColor': '#333333', 'primaryTextColor': '#333333', 'clusterBkg': '#ffffff', 'clusterBorder': '#333333'}}}%% +flowchart LR + ckpt["Hugging Face or
Megatron Bridge checkpoint"] --> deploy["OpenAI-compatible
endpoint"] + hosted["Hosted endpoint"] --> deploy + deploy --> step["eval/model_eval
(NeMo Evaluator)"] + step --> results["eval_results
per-benchmark subdirs"] +``` + +NeMo Evaluator Launcher owns task execution and result files under `output_dir`. +For the contract and the on-disk layout, refer to [Output Artifacts](/reference/output-artifacts). + +## How It Works + +The runner reads a single YAML document, applies command-line overrides, removes Nemotron-only keys, saves the resolved launcher config, and calls `nemo_evaluator_launcher.api.functional.run_eval`. + +The endpoint type must match the benchmark family. +Chat and instruction benchmarks need a *chat* endpoint. +*Log-probability* tasks, such as HellaSwag, need a *completions* endpoint with `logprobs` support and a tokenizer that matches the served model. + +The hosted smoke-test config is `tiny_chat.yaml`. +The checkpoint-evaluation config is `default.yaml`. +Generation settings live under `evaluation.nemo_evaluator_config.config.params`. + +For the full concept set behind these design rules, refer to [Concepts](/explanation/index). + +## Documentation + + + +Run one benchmark on one sample against a hosted endpoint, end to end. + +--- + +15-30 min tutorial + + + + +Run a productive agent session: opening brief, four required inputs, and how `SKILL.md` keeps the session focused. + +--- + +10 min read newcomer + + + + +Discover the step, run a hosted evaluation, and evaluate a deployed checkpoint. + +--- + +3 guides task-focused + + + + +YAML schema, command-line flags, output artifact layout, benchmark catalog, and troubleshooting. + +--- + +5 references lookup + + + + +Architecture, endpoint and benchmark families, and tokenizer alignment. + +--- + +3 pages explanation + + + + + +## All Documentation + + + + +| Guide | What You Will Do | Time | +| --- | --- | --- | +| [Getting Started With Model Evaluation](/getting-started) | Run a one-sample evaluation against a hosted endpoint | 15-30 min | +| [Use The Model Evaluation Skill With Confidence](/using-skills) | Drive eval/model_eval from a coding agent | 10 min read | + + + + +| Guide | What You Will Do | +| --- | --- | +| [Discover The Model Evaluation Step](/how-to/discover-the-step) | List the step, read its contract, and decide whether it applies | +| [Run A Hosted Evaluation](/how-to/run-hosted-evaluation) | Run benchmarks against an already-running endpoint | +| [Evaluate A Deployed Checkpoint](/how-to/evaluate-deployed-checkpoint) | Pick a deployment path, then point the step at the endpoint | + + + + +| Reference | What You Will Find | +| --- | --- | +| [Configuration Reference](/reference/config-schema) | YAML field reference for default.yaml and tiny_chat.yaml | +| [CLI Reference](/reference/cli-reference) | Flags and Hydra overrides for nemotron steps run eval/model_eval | +| [Output Artifacts](/reference/output-artifacts) | eval_results contract and on-disk layout | +| [Tasks Catalog](/reference/benchmarks-catalog) | NeMo Evaluator Launcher task identifiers grouped by family | +| [Troubleshooting](/reference/troubleshooting) | Named error modes from step.toml, with cause and recovery | + + + + +| Concept | What You Will Learn | +| --- | --- | +| [Concepts](/explanation/index) | Map of the concept pages and how they relate | +| [Pipeline Overview](/explanation/pipeline-overview) | Artifact flow from checkpoint through eval/model_eval into eval_results | +| [Endpoint Types And Task Families](/explanation/endpoint-types-and-benchmarks) | Chat versus completions endpoints, and which benchmark families match each one | +| [Tokenizer Alignment](/explanation/tokenizer-alignment) | Why log-probability benchmarks need a tokenizer that matches the served model | + + + + + +## Before You Start + +- The Nemotron repository is synced and `uv sync` is complete. + +- A bearer token is exported as the environment variable named in `target.api_endpoint.api_key_name`. +Hosted smoke tests usually use `NVIDIA_API_KEY`. + +- A reachable evaluation endpoint URL and a model identifier the endpoint advertises. + +- A tokenizer that matches the served model when running log-probability tasks. +The hosted chat smoke test does not require a tokenizer override. + +## Limitations And Considerations + +- Cost: every benchmark sample issues at least one request to the endpoint, and hosted endpoints incur per-token cost. + +- Rate limits: hosted endpoints throttle concurrent requests, so set `evaluation.nemo_evaluator_config.config.params.parallelism` to a value the endpoint can serve. + +- Deployment: `tiny_chat.yaml` targets an already-deployed endpoint; `default.yaml` uses launcher-managed deployment for a Megatron Bridge checkpoint. + +- Comparability: scores are comparable when the endpoint type, task version, tokenizer, and generation parameters are held constant across runs. +The [Comparing Runs](/reference/output-artifacts#model-eval-comparing-runs) section explains the framing. + +## Related Documentation + +- The full `step.toml` contract: `src/nemotron/steps/eval/model_eval/step.toml` in the repository. + +- The before-and-after evaluation framing: [Comparing Runs](/reference/output-artifacts#model-eval-comparing-runs). + +- Upstream NeMo Evaluator quick-start: [https://docs.nvidia.com/nemo/evaluator/latest/get-started/quickstart/launcher.html](https://docs.nvidia.com/nemo/evaluator/latest/get-started/quickstart/launcher.html). diff --git a/docs/fern/pages-vnightly/model-eval/reference/benchmarks-catalog.mdx b/docs/fern/pages-vnightly/model-eval/reference/benchmarks-catalog.mdx new file mode 100644 index 000000000..bd4f85cd8 --- /dev/null +++ b/docs/fern/pages-vnightly/model-eval/reference/benchmarks-catalog.mdx @@ -0,0 +1,78 @@ +--- +title: "Tasks Catalog" +slug: "model-eval/reference/benchmarks-catalog.html" +description: "This page catalogs task identifiers used by eval/model_eval. NeMo Evaluator Launcher owns the authoritative task list. Use this page as a quick map, then verify exact names with the installed launcher" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + +This page catalogs task identifiers used by `eval/model_eval`. +NeMo Evaluator Launcher owns the authoritative task list. +Use this page as a quick map, then verify exact names with the installed launcher. + +```bash +nemo-evaluator-launcher ls tasks +nemo-evaluator-launcher ls task \ +``` + +## Naming Rule + +Use the exact task id listed by NeMo Evaluator Launcher. +Do not prepend a harness name unless the launcher lists that exact dotted id. + +## Repository Starting Points + +| Config | Task entries | When to use | +| --- | --- | --- | +| tiny_chat.yaml | mmlu_instruct | Hosted chat smoke test. | +| default.yaml | adlr_mmlu, hellaswag | Launcher-managed Megatron checkpoint evaluation. | + +## Chat And Instruction Tasks + +These tasks use a chat endpoint. +The hosted smoke-test config uses this family. + +| Identifier | Notes | +| --- | --- | +| mmlu_instruct | Chat/instruction smoke task used by tiny_chat.yaml. | +| adlr_mmlu | Configured by default.yaml; verify endpoint requirements in the installed launcher. | + +## Log-Probability Tasks + +These tasks generally need a completions endpoint with logprobs support and a tokenizer that matches the served model. + +| Identifier | Notes | +| --- | --- | +| hellaswag | Configured by default.yaml; requires endpoint/tokenizer compatibility for meaningful scores. | + +Configure tokenizer values under: + +```text +evaluation.nemo_evaluator_config.config.params.extra.tokenizer +evaluation.nemo_evaluator_config.config.params.extra.tokenizer_backend +``` + +## Choosing Tasks + +Ask three questions before changing the task list. + +1. Does the installed launcher list the task id exactly? + +1. Does the endpoint type match the task family? + +1. Is this a smoke test or a production comparison? + +For production comparisons, keep the same task list, endpoint type, tokenizer, and generation parameters across baseline and post-training runs. + +## Related + +- [Configuration Reference](/config-schema) for the `tasks` section and evaluator params. + +- [Output Artifacts](/output-artifacts) for result layout expectations. + +- [Endpoint Types And Task Families](/../explanation/endpoint-types-and-benchmarks) for endpoint/task pairing. + +- [Comparing Runs](/output-artifacts#model-eval-comparing-runs) for before-and-after evaluation framing. diff --git a/docs/fern/pages-vnightly/model-eval/reference/cli-reference.mdx b/docs/fern/pages-vnightly/model-eval/reference/cli-reference.mdx new file mode 100644 index 000000000..47928d89c --- /dev/null +++ b/docs/fern/pages-vnightly/model-eval/reference/cli-reference.mdx @@ -0,0 +1,117 @@ +--- +title: "CLI Reference" +slug: "model-eval/reference/cli-reference.html" +description: "This page documents the CLI surface for nemotron steps run eval/model_eval. The flags are shared by every Nemotron step. The override examples are specific to the eval/model_eval YAML schema." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + +This page documents the CLI surface for `nemotron steps run eval/model_eval`. +The flags are shared by every Nemotron step. +The override examples are specific to the `eval/model_eval` YAML schema. + +## Syntax + +```bash +uv run nemotron steps run eval/model_eval [FLAGS] [HYDRA_OVERRIDES...] +``` + +Run the command from the repository root after `uv sync --extra evaluator`. +Pass the configuration name with `-c`, per-step overrides as `key=value` dotlists, and optional execution flags. + +## Flags + +| Flag | Long form | Purpose | +| --- | --- | --- | +| -c | --config | Config name inside src/nemotron/steps/eval/model_eval/config/, such as default or tiny_chat. Accepts a path to a YAML file. | +| -r | --run | Attached execution by using an environment profile defined in env.toml. | +| -b | --batch | Detached execution by using an environment profile defined in env.toml. | +| -d | --dry-run | Compile the Nemotron job config and exit without dispatching. | +| | --force-squash | Force re-squash of the container image when the selected backend builds one. | + +Invoking the command without `-c` resolves the runspec default, `default.yaml`. + +## Common Overrides + +| Override | Purpose | +| --- | --- | +| output_dir=<path> | Base output directory. The runtime also writes this into execution.output_dir before calling NeMo Evaluator Launcher. | +| dry_run=true | Pass dry-run mode to NeMo Evaluator Launcher. This is different from CLI --dry-run, which only compiles the Nemotron job. | +| task_filters=[<task>,...] | Optional subset of configured task names passed to NeMo Evaluator Launcher. | +| target.api_endpoint.url=<url> | OpenAI-compatible endpoint URL for hosted evaluation when deployment.type=none. | +| target.api_endpoint.model_id=<id> | Exact model id advertised by the hosted endpoint. | +| target.api_endpoint.api_key_name=<env-var-name> | Name of the environment variable holding the bearer token. This is the variable name, not the secret. | +| `target.api_endpoint.type=\` | +| evaluation.nemo_evaluator_config.config.params.limit_samples=<int> | Per-task sample cap for smoke tests. | +| evaluation.nemo_evaluator_config.config.params.parallelism=<int> | Concurrent requests issued by the evaluator where supported. | +| evaluation.nemo_evaluator_config.config.params.request_timeout=<int> | Per-request timeout in seconds. | +| evaluation.nemo_evaluator_config.config.params.extra.tokenizer=<path-or-id> | Tokenizer used by log-probability tasks such as HellaSwag. | +| deployment.checkpoint_path=<iter_* path> | Megatron Bridge checkpoint path used by default.yaml launcher deployment. | +| deployment.image=<container> | Container image used by the launcher deployment in default.yaml. | + +## Discovery Commands + +```bash +uv run --no-sync nemotron steps list --category eval --json +uv run --no-sync nemotron steps show eval/model_eval --json +``` + +`nemotron steps show eval/model_eval --json` prints the full step contract, including `consumes`, `produces`, `parameters`, `strategies`, and `errors`. + +## Examples + +### Hosted Chat Smoke Test + +```bash +: "${NVIDIA_API_KEY:?Set NVIDIA_API_KEY}" +: "${NEMO_EVALUATOR_MODEL_URL:?Set the chat-completions endpoint URL}" +: "${NEMO_EVALUATOR_MODEL_ID:?Set the endpoint model id}" + +uv run --no-sync nemotron steps run eval/model_eval \ + -c tiny_chat \ + output_dir=./output/eval-tiny-chat \ + target.api_endpoint.url="$NEMO_EVALUATOR_MODEL_URL" \ + target.api_endpoint.model_id="$NEMO_EVALUATOR_MODEL_ID" \ + target.api_endpoint.api_key_name=NVIDIA_API_KEY \ + target.api_endpoint.type=chat \ + evaluation.nemo_evaluator_config.config.params.limit_samples=1 +``` + +### Megatron Checkpoint Evaluation Config + +Use `default.yaml` when NeMo Evaluator Launcher should deploy a Megatron Bridge checkpoint and then run the configured tasks. + +```bash +uv run --no-sync nemotron steps run eval/model_eval \ + -c default \ + output_dir=./output/eval-megatron \ + deployment.checkpoint_path=/path/to/checkpoint/iter_0001000 \ + evaluation.nemo_evaluator_config.config.params.limit_samples=1 +``` + +### Compile Without Dispatching + +```bash +uv run --no-sync nemotron steps run eval/model_eval -d -c tiny_chat \ + target.api_endpoint.url="$NEMO_EVALUATOR_MODEL_URL" \ + target.api_endpoint.model_id="$NEMO_EVALUATOR_MODEL_ID" +``` + +### Launcher Dry Run + +```bash +uv run --no-sync nemotron steps run eval/model_eval -c tiny_chat dry_run=true +``` + +## Related + +- [Configuration Reference](/config-schema) for the YAML schema accepted by `-c` and dotlist overrides. + +- [Output Artifacts](/output-artifacts) for the on-disk layout produced under `output_dir`. + +- [Run A Hosted Evaluation](/../how-to/run-hosted-evaluation) for a procedural walk-through. + +- [Discover The Model Evaluation Step](/../how-to/discover-the-step) for the step-contract discovery commands. diff --git a/docs/fern/pages-vnightly/model-eval/reference/config-schema.mdx b/docs/fern/pages-vnightly/model-eval/reference/config-schema.mdx new file mode 100644 index 000000000..f0faa2d8f --- /dev/null +++ b/docs/fern/pages-vnightly/model-eval/reference/config-schema.mdx @@ -0,0 +1,287 @@ +--- +title: "Configuration Reference" +slug: "model-eval/reference/config-schema.html" +description: "This page documents the YAML schema consumed by nemotron steps run eval/model_eval. The step is a thin wrapper around NeMo Evaluator Launcher: it loads a YAML config, applies Hydra-style overrides, re" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + +This page documents the YAML schema consumed by `nemotron steps run eval/model_eval`. +The step is a thin wrapper around NeMo Evaluator Launcher: it loads a YAML config, applies Hydra-style overrides, removes Nemotron-only keys, saves a launcher config, and calls `nemo_evaluator_launcher.api.functional.run_eval`. + +## Sample Configs + +| Config | Purpose | +| --- | --- | +| tiny_chat.yaml | Hosted chat endpoint smoke test. Uses deployment.type: none, target.api_endpoint.*, and one configured task, mmlu_instruct. | +| default.yaml | Megatron Bridge checkpoint evaluation through NeMo Evaluator Launcher. Uses launcher-managed execution, deployment, evaluation, and tasks sections. | + +## Top-Level Keys + +```yaml startLine={1} +# Tiny hosted chat endpoint smoke-test config. +# +# Export endpoint settings before running: +# export NEMO_EVALUATOR_MODEL_ID=\ +# export NEMO_EVALUATOR_MODEL_URL=\ +# export NEMO_EVALUATOR_API_KEY_NAME=NVIDIA_API_KEY +# export NEMO_EVALUATOR_ENDPOINT_TYPE=chat + +dry_run: false +output_dir: ./results-tiny-chat +task_filters: null + +execution: + type: local + mode: sequential + output_dir: $\{output_dir\} + +deployment: + type: none + +target: + api_endpoint: + model_id: ${oc.env:NEMO_EVALUATOR_MODEL_ID,''} + url: ${oc.env:NEMO_EVALUATOR_MODEL_URL,''} + api_key_name: ${oc.env:NEMO_EVALUATOR_API_KEY_NAME,NVIDIA_API_KEY} + type: ${oc.env:NEMO_EVALUATOR_ENDPOINT_TYPE,chat} + +evaluation: + nemo_evaluator_config: + config: + params: + temperature: 0.0 + top_p: 1.0 + max_new_tokens: 1024 + max_retries: 5 + parallelism: 1 + request_timeout: 3600 + limit_samples: 1 + target: + api_endpoint: + adapter_config: + output_dir: /results + use_progress_tracking: false + use_caching: true + caching_dir: /results/cache + use_response_logging: true + max_logged_responses: 5 + use_request_logging: true + max_logged_requests: 5 + tasks: + - name: mmlu_instruct +``` + +```yaml startLine={1} +# Standard NeMo Evaluator Launcher config for Megatron checkpoint evaluation. +# +# This mirrors the Nano3/Super3 eval shape: the `run` section is used by +# Nemotron for env/profile/artifact interpolation, then removed before handing +# the config to NeMo Evaluator Launcher. + +dry_run: false +output_dir: ./results + +run: + # Use a concrete Megatron Bridge iter_* checkpoint via + # `deployment.checkpoint_path=...`, or keep this as a W&B artifact reference + # consumed by `${art:model,path}`. + model: model:latest + env: + executor: local + container_image: nvcr.io/nvidia/nemo:25.11.nemotron_3_nano + host: ${oc.env:HOSTNAME,localhost} + user: ${oc.env:USER,''} + account: null + partition: null + remote_job_dir: ${oc.env:PWD}/.nemotron + time: "04:00:00" + wandb: + entity: null + project: null + +execution: + type: ${run.env.executor} + hostname: ${run.env.host} + username: ${run.env.user} + account: ${run.env.account} + partition: ${run.env.partition} + output_dir: $\{output_dir\} + walltime: ${run.env.time} + num_nodes: ${oc.select:run.env.nodes,1} + deployment: + n_tasks: ${execution.num_nodes} + auto_export: + destinations: + - wandb + env_vars: + deployment: + HF_HOME: ${run.env.remote_job_dir}/hf + HF_TOKEN: HF_TOKEN + NIM_CACHE_PATH: ${run.env.remote_job_dir}/nim + VLLM_CACHE_ROOT: ${run.env.remote_job_dir}/vllm + evaluation: + HF_HOME: ${run.env.remote_job_dir}/hf + HF_TOKEN: HF_TOKEN + mounts: + deployment: {} + evaluation: {} + mount_home: false + +deployment: + type: generic + image: ${run.env.container_image} + checkpoint_path: ${art:model,path} + multiple_instances: false + port: 1235 + served_model_name: nemo-model + health_check_path: /v1/health + command: >- + bash -c 'export TRITON_CACHE_DIR=/tmp/triton_cache; + python /opt/Export-Deploy/scripts/deploy/nlp/deploy_ray_inframework.py + --megatron_checkpoint /checkpoint/ + --num_gpus ${oc.select:run.env.gpus_per_node,1} + --tensor_model_parallel_size 1 + --expert_model_parallel_size 1 + --port 1235 + --num_replicas 1' + endpoints: + chat: /v1/chat/completions/ + completions: /v1/completions/ + health: /v1/health + +evaluation: + nemo_evaluator_config: + config: + params: + max_retries: 5 + parallelism: 4 + request_timeout: 6000 + limit_samples: null + extra: + tokenizer: ${deployment.checkpoint_path}/tokenizer + tokenizer_backend: huggingface + target: + api_endpoint: + adapter_config: + output_dir: /results + use_progress_tracking: false + use_caching: true + caching_dir: /results/cache + use_response_logging: true + max_logged_responses: 10 + use_request_logging: true + max_logged_requests: 10 + tasks: + - name: adlr_mmlu + nemo_evaluator_config: + config: + params: + top_p: 0.0 + - name: hellaswag + +export: + wandb: + entity: ${run.wandb.entity} + project: ${run.wandb.project} +``` + +| Key | Used By | Purpose | +| --- | --- | --- | +| dry_run | Nemotron runtime | Passed to NeMo Evaluator Launcher as run_eval(..., dry_run=...). | +| output_dir | Nemotron runtime | Copied into execution.output_dir before launcher dispatch. | +| task_filters | Nemotron runtime | Optional task-name subset passed to launcher. | +| run | Nemotron runtime | Nemotron-side artifact, environment, and W&B interpolation. Removed before launcher dispatch. | +| execution | NeMo Evaluator Launcher | Where and how launcher execution runs. | +| deployment | NeMo Evaluator Launcher | How the evaluated model is deployed, or type: none for an existing endpoint. | +| target | NeMo Evaluator Launcher | Existing API endpoint metadata for hosted evaluation. | +| evaluation | NeMo Evaluator Launcher | Evaluator config, generation params, logging, caching, and adapter settings. | +| tasks | NeMo Evaluator Launcher | Exact task entries to run. Each entry has a name. | +| export | NeMo Evaluator Launcher | Optional export settings, such as W&B export. | + +## Hosted Endpoint Fields + +Use these fields with `tiny_chat.yaml` or any config that sets `deployment.type: none`. + +| Field | Purpose | +| --- | --- | +| target.api_endpoint.model_id | Exact model id advertised by the endpoint. | +| target.api_endpoint.url | Full OpenAI-compatible endpoint URL, including /v1/chat/completions or /v1/completions. | +| target.api_endpoint.api_key_name | Environment variable name that holds the bearer token. Never put the secret value in config. | +| target.api_endpoint.type | Endpoint type, usually chat for hosted chat smoke tests. | + +The `tiny_chat.yaml` file reads these values from `NEMO_EVALUATOR_MODEL_ID`, `NEMO_EVALUATOR_MODEL_URL`, `NEMO_EVALUATOR_API_KEY_NAME`, and `NEMO_EVALUATOR_ENDPOINT_TYPE`. + +## Evaluation Params + +Generation and evaluator controls live under: + +```text +evaluation.nemo_evaluator_config.config.params +``` + +Common fields are: + +| Field | Purpose | +| --- | --- | +| temperature | Sampling temperature for generation tasks. | +| top_p | Top-p nucleus sampling. | +| max_new_tokens | Maximum generated tokens for chat/instruction tasks. | +| max_retries | Request retry count. | +| parallelism | Request concurrency where supported. | +| request_timeout | Per-request timeout in seconds. | +| limit_samples | Optional per-task sample cap. Use 1 for smoke tests. | +| extra.tokenizer | Tokenizer path or Hugging Face id required by log-probability tasks. | +| extra.tokenizer_backend | Tokenizer backend, usually huggingface. | + +## Tasks + +Tasks are NeMo Evaluator Launcher task entries. +Use exact task IDs from the installed launcher, for example: + +```bash +nemo-evaluator-launcher ls tasks +nemo-evaluator-launcher ls task mmlu_instruct +``` + +The sample configs define these starting points. + +| Config | Tasks | +| --- | --- | +| tiny_chat.yaml | mmlu_instruct | +| default.yaml | adlr_mmlu, hellaswag | + +Do not prepend a harness name unless the launcher lists that exact dotted task id. + +## Checkpoint Deployment Fields + +The `default.yaml` config uses launcher-managed deployment for a Megatron Bridge checkpoint. +The most common override is: + +```bash +deployment.checkpoint_path=/path/to/iter_0001000 +``` + +Use the concrete `iter_*` checkpoint directory, not just the parent training output directory. +For log-probability tasks, keep the tokenizer aligned with the deployed checkpoint through `evaluation.nemo_evaluator_config.config.params.extra.tokenizer`. + +## Validation Behavior + +Nemotron does not implement a separate benchmark loop for this step. +It validates only enough to build the launcher config and import NeMo Evaluator Launcher. +Endpoint checks, task validation, result writing, and launcher invocation state are owned by NeMo Evaluator Launcher. + +## Related + +- [CLI Reference](/cli-reference) for command-line flags and Hydra override syntax. + +- [Tasks Catalog](/benchmarks-catalog) for task identifiers grouped by endpoint family. + +- [Output Artifacts](/output-artifacts) for the `eval_results` contract and the on-disk layout. + +- [Troubleshooting](/troubleshooting) for common launcher and config failures. + +- `src/nemotron/steps/eval/model_eval/step.toml` for the full step contract. diff --git a/docs/fern/pages-vnightly/model-eval/reference/index.mdx b/docs/fern/pages-vnightly/model-eval/reference/index.mdx new file mode 100644 index 000000000..91e3e89bc --- /dev/null +++ b/docs/fern/pages-vnightly/model-eval/reference/index.mdx @@ -0,0 +1,62 @@ +--- +title: "Model Evaluation Reference" +slug: "model-eval/reference/index.html" +description: "Lookup pages for eval/model_eval. For the section overview, refer to About Model Evaluation. For procedural walk-throughs, refer to Model Evaluation How-To Guides." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + +Lookup pages for `eval/model_eval`. +For the section overview, refer to [About Model Evaluation](/../index). +For procedural walk-throughs, refer to [Model Evaluation How-To Guides](/../how-to/index). + + + +YAML schema for `default.yaml` and `tiny_chat.yaml`, field by field. + +--- + +yaml + + + + +`nemotron steps run eval/model_eval` flags and Hydra overrides. + +--- + +cli + + + + +The `eval_results` contract and the on-disk directory layout. + +--- + +artifacts + + + + +Benchmark identifiers grouped by family, with endpoint-type guidance. + +--- + +tasks + + + + +Named error modes from `step.toml`, with the most common cause and the recovery for each. + +--- + +errors + + + + diff --git a/docs/model-eval/reference/output-artifacts.md b/docs/fern/pages-vnightly/model-eval/reference/output-artifacts.mdx similarity index 70% rename from docs/model-eval/reference/output-artifacts.md rename to docs/fern/pages-vnightly/model-eval/reference/output-artifacts.mdx index 7ff9d09b4..b084aa0c2 100644 --- a/docs/model-eval/reference/output-artifacts.md +++ b/docs/fern/pages-vnightly/model-eval/reference/output-artifacts.mdx @@ -1,10 +1,13 @@ - +--- +title: "Output Artifacts" +slug: "model-eval/reference/output-artifacts.html" +description: "This page describes the artifact produced by eval/model_eval." +--- -(model-eval-output-artifacts)= -# Output Artifacts +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + This page describes the artifact produced by `eval/model_eval`. @@ -14,8 +17,8 @@ This page describes the artifact produced by `eval/model_eval`. | Field | Value | | --- | --- | -| `type` | `eval_results` | -| `description` | Benchmark metrics, artifacts, and evaluation summaries produced by NeMo Evaluator. | +| type | eval_results | +| description | Benchmark metrics, artifacts, and evaluation summaries produced by NeMo Evaluator. | The contract is intentionally loose. Nemotron does not normalize evaluator outputs. @@ -26,15 +29,15 @@ NeMo Evaluator Launcher owns the exact file set and directory shape under the co Before calling the launcher, the step saves the resolved launcher config and prints: ```text -launcher_config: +launcher_config: \ ``` If the launcher returns an invocation id, the step also prints: ```text -launcher_invocation_id: -status_command: nemo-evaluator-launcher status -logs_command: nemo-evaluator-launcher logs +launcher_invocation_id: \ +status_command: nemo-evaluator-launcher status \ +logs_command: nemo-evaluator-launcher logs \ ``` Those commands are the source of truth for job state and logs after submission. @@ -56,7 +59,8 @@ For checkpoint evaluation, inspect the output directory you supplied: find ./output/eval-megatron -maxdepth 5 -type f | sort ``` -(model-eval-comparing-runs)= + + ## Comparing Runs Evaluation results carry meaning when paired with another evaluation. @@ -66,13 +70,19 @@ The comparison is honest when the surrounding configuration is held constant. Apply the following practices before treating any single evaluation as a result. - Run a lightweight baseline before the training, conversion, or quantization step you are measuring. + - Snapshot the exact evaluation config, including config file name, `output_dir`, endpoint fields, task list, tokenizer, and generation parameters. + - Place a date or run identifier in `output_dir` so baseline and post-change directories live side by side. + - Keep endpoint type, task versions, tokenizer, and generation parameters identical between runs. + - Rerun the baseline task set first before exploring new tasks. ## Related -- {doc}`config-schema` for the YAML keys that influence what is written. -- {doc}`benchmarks-catalog` for task identifiers. +- [Configuration Reference](/config-schema) for the YAML keys that influence what is written. + +- [Tasks Catalog](/benchmarks-catalog) for task identifiers. + - `src/nemotron/steps/eval/model_eval/step.toml` for the full step contract. diff --git a/docs/model-eval/reference/troubleshooting.md b/docs/fern/pages-vnightly/model-eval/reference/troubleshooting.mdx similarity index 57% rename from docs/model-eval/reference/troubleshooting.md rename to docs/fern/pages-vnightly/model-eval/reference/troubleshooting.mdx index 8828d5983..55dc85776 100644 --- a/docs/model-eval/reference/troubleshooting.md +++ b/docs/fern/pages-vnightly/model-eval/reference/troubleshooting.mdx @@ -1,10 +1,13 @@ - +--- +title: "Troubleshooting" +slug: "model-eval/reference/troubleshooting.html" +description: "This page maps common eval/model_eval failures to the config fields that usually need correction. Nemotron builds a launcher config and calls NeMo Evaluator Launcher; task execution, endpoint checks, " +--- -(model-eval-troubleshooting)= -# Troubleshooting +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + This page maps common `eval/model_eval` failures to the config fields that usually need correction. Nemotron builds a launcher config and calls NeMo Evaluator Launcher; task execution, endpoint checks, and result writing are owned by the launcher. @@ -32,10 +35,10 @@ Most hosted failures come from one of these fields: | Field | What To Check | | --- | --- | -| `target.api_endpoint.url` | Full endpoint URL, including `/v1/chat/completions` or `/v1/completions`. | -| `target.api_endpoint.model_id` | Exact model id returned by the endpoint's models API or UI. | -| `target.api_endpoint.api_key_name` | Environment variable name, not the secret value. | -| `target.api_endpoint.type` | `chat` for chat tasks, `completions` for completions/logprob tasks. | +| target.api_endpoint.url | Full endpoint URL, including /v1/chat/completions or /v1/completions. | +| target.api_endpoint.model_id | Exact model id returned by the endpoint’s models API or UI. | +| target.api_endpoint.api_key_name | Environment variable name, not the secret value. | +| target.api_endpoint.type | chat for chat tasks, completions for completions/logprob tasks. | For hosted smoke tests, start with `tiny_chat.yaml` and `target.api_endpoint.type=chat`. @@ -78,8 +81,8 @@ evaluation.nemo_evaluator_config.config.params.extra.tokenizer=/path/to/run/iter The step prints launcher follow-up commands when the launcher returns an invocation id. ```text -status_command: nemo-evaluator-launcher status -logs_command: nemo-evaluator-launcher logs +status_command: nemo-evaluator-launcher status \ +logs_command: nemo-evaluator-launcher logs \ ``` Run those commands before changing config. @@ -87,8 +90,12 @@ The launcher logs usually distinguish endpoint/authentication failures from task ## Related Pages -- {doc}`config-schema` for field names and config shape. -- {doc}`output-artifacts` for launcher config and result paths. -- {doc}`../explanation/tokenizer-alignment` for tokenizer alignment. -- {doc}`../explanation/endpoint-types-and-benchmarks` for endpoint/task pairing. +- [Configuration Reference](/config-schema) for field names and config shape. + +- [Output Artifacts](/output-artifacts) for launcher config and result paths. + +- [Tokenizer Alignment](/../explanation/tokenizer-alignment) for tokenizer alignment. + +- [Endpoint Types And Task Families](/../explanation/endpoint-types-and-benchmarks) for endpoint/task pairing. + - `src/nemotron/steps/eval/model_eval/step.toml` for the documented error names. diff --git a/docs/model-eval/using-skills.md b/docs/fern/pages-vnightly/model-eval/using-skills.mdx similarity index 71% rename from docs/model-eval/using-skills.md rename to docs/fern/pages-vnightly/model-eval/using-skills.mdx index f6a9c6162..8af7746b8 100644 --- a/docs/model-eval/using-skills.md +++ b/docs/fern/pages-vnightly/model-eval/using-skills.mdx @@ -1,10 +1,13 @@ - +--- +title: "Use The Model Evaluation Skill With Confidence" +slug: "model-eval/using-skills.html" +description: "This page is for users who plan to drive eval/model_eval from a coding agent. The goal is a clear handoff between what you decide and what the agent edits or runs." +--- -(model-eval-using-skills)= -# Use The Model Evaluation Skill With Confidence +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + This page is for users who plan to drive `eval/model_eval` from a coding agent. The goal is a clear handoff between what you decide and what the agent edits or runs. @@ -14,13 +17,17 @@ The goal is a clear handoff between what you decide and what the agent edits or For the hosted chat smoke test, provide: - The endpoint URL, including the `/v1/chat/completions` path. + - The model id advertised by the endpoint. + - The API key environment variable name, usually `NVIDIA_API_KEY`. + - The output directory to use. For checkpoint evaluation with `default.yaml`, also provide: - The concrete Megatron Bridge `iter_*` checkpoint path. + - The tokenizer path or Hugging Face tokenizer id if the selected task needs logprobs. ## Recommended First Run @@ -56,11 +63,13 @@ The agent should ask for missing fields instead of guessing. ## What Success Looks Like -A reasonable first success is the hosted chat smoke test described in {doc}`getting-started`. +A reasonable first success is the hosted chat smoke test described in [Getting Started With Model Evaluation](/getting-started). The session reaches that point when: - The agent issues one `nemotron steps run eval/model_eval -c tiny_chat ...` command. + - The command prints a `launcher_config` path. + - The output directory contains files after NeMo Evaluator Launcher completes. If the launcher fails, the agent should report the error and the relevant config fields. @@ -68,7 +77,10 @@ It should not retry with fabricated endpoint, model, or credential values. ## Next Steps -- Run the tutorial: {doc}`getting-started`. -- Pick a deployment path: {doc}`how-to/evaluate-deployed-checkpoint`. -- Run a hosted evaluation: {doc}`how-to/run-hosted-evaluation`. -- Look up flags and YAML fields: {doc}`reference/cli-reference` and {doc}`reference/config-schema`. +- Run the tutorial: [Getting Started With Model Evaluation](/getting-started). + +- Pick a deployment path: [Evaluate A Deployed Checkpoint](/how-to/evaluate-deployed-checkpoint). + +- Run a hosted evaluation: [Run A Hosted Evaluation](/how-to/run-hosted-evaluation). + +- Look up flags and YAML fields: [CLI Reference](/reference/cli-reference) and [Configuration Reference](/reference/config-schema). diff --git a/docs/nemo_runspec/artifacts.md b/docs/fern/pages-vnightly/nemo_runspec/artifacts.mdx similarity index 81% rename from docs/nemo_runspec/artifacts.md rename to docs/fern/pages-vnightly/nemo_runspec/artifacts.mdx index 2a8e31065..a53269f55 100644 --- a/docs/nemo_runspec/artifacts.md +++ b/docs/fern/pages-vnightly/nemo_runspec/artifacts.mdx @@ -1,13 +1,18 @@ -# Artifact Tracking +--- +title: "Artifact Tracking" +slug: "nemo_runspec/artifacts.html" +description: "nemo_runspec.artifacts provides the tracking infrastructure that connects data prep, training, and evaluation stages through versioned artifact references. It supports two backends that can run simult" +--- `nemo_runspec.artifacts` provides the tracking infrastructure that connects data prep, training, and evaluation stages through versioned artifact references. It supports two backends that can run simultaneously: - **Manifest-based tracking** (`nemo_runspec.manifest_tracker`) — writes structured JSON manifests to any fsspec-compatible storage (local, Lustre, S3, GCS, HF Hub). Always reliable, zero external dependencies. -- **W&B artifact tracking** — logs artifacts to [Weights & Biases](../nemotron/wandb.md) for team collaboration, UI browsing, and lineage graphs. + +- **W&B artifact tracking** — logs artifacts to [Weights & Biases](/../nemotron/wandb) for team collaboration, UI browsing, and lineage graphs. Manifests are the always-on foundation; W&B is best-effort on top. -> For artifact *types* (PretrainBlendsArtifact, SFTDataArtifact, etc.) and the Pydantic base class, see [nemotron.kit artifacts](../nemotron/artifacts.md). +> For artifact *types* (PretrainBlendsArtifact, SFTDataArtifact, etc.) and the Pydantic base class, see [nemotron.kit artifacts](/../nemotron/artifacts). ## Configuration @@ -31,10 +36,10 @@ entity = "YOUR-TEAM" Backend combinations: | Setup | Use Case | -|-------|----------| -| `manifest` + `wandb = true` | **Recommended.** Manifest is always reliable; wandb adds UI + team features | -| `manifest` only | Offline / local development, no wandb dependency | -| `wandb = true` only | Legacy behavior, wandb-only tracking | +| --- | --- | +| manifest + wandb = true | **Recommended.** Manifest is always reliable; wandb adds UI + team features | +| manifest only | Offline / local development, no wandb dependency | +| wandb = true only | Legacy behavior, wandb-only tracking | | Neither | No artifact tracking | ### Disabling per-run @@ -54,17 +59,20 @@ uv run nemotron super3 sft --run dlw artifacts.manifest.root=null artifacts.wand The `manifest.root` value supports any fsspec-compatible URI: | Backend | Example | Notes | -|---------|---------|-------| -| Local / Lustre / NFS | `/lustre/team/artifacts` | Best for training clusters | -| S3 | `s3://bucket/artifacts` | Requires AWS credentials | -| GCS | `gs://bucket/artifacts` | Requires GCP credentials | -| HF Hub | `hf://org/repo-name` | Great for sharing; batched commits | +| --- | --- | --- | +| Local / Lustre / NFS | /lustre/team/artifacts | Best for training clusters | +| S3 | s3://bucket/artifacts | Requires AWS credentials | +| GCS | gs://bucket/artifacts | Requires GCP credentials | +| HF Hub | hf://org/repo-name | Great for sharing; batched commits | ### Config Flow 1. `build_job_config()` merges `[artifacts]` from env.toml into the job config (YAML overrides env.toml) + 2. `extract_train_config()` preserves the top-level `artifacts:` section + 3. Inside the container, `setup_artifact_tracking()` reads `config.artifacts` to initialize backends + 4. `build_env_vars()` extracts `WANDB_PROJECT` / `WANDB_ENTITY` from `[wandb]` in env.toml ## The Two-Function API @@ -77,7 +85,7 @@ from nemo_runspec.artifacts import setup_artifact_tracking, log_artifact ### `setup_artifact_tracking(config)` — Initialize backends and resolve references -Called early, **before** dataclass conversion. Reads `config.artifacts`, initializes the active backends, and resolves `${art:...}` references. +Called early, **before** dataclass conversion. Reads `config.artifacts`, initializes the active backends, and resolves `$\{art:...\}` references. ```python config = load_omegaconf_yaml(config_path) @@ -86,8 +94,11 @@ cfg = omegaconf_to_dataclass(config, MyConfig) ``` Returns an `ArtifactTrackingResult` with flags: + - `tracking.manifest` — whether manifest backend is active + - `tracking.wandb` — whether wandb backend is active + - `tracking.qualified_names` — wandb artifact qualified names for lineage registration ### `log_artifact(artifact, tracking)` — Save to all active backends @@ -100,17 +111,19 @@ log_artifact(artifact, tracking) # logs to manifest + wandb ``` When both backends are active: + 1. `artifact.save()` logs via the global lineage tracker (WandbTracker after `init_wandb_from_env()`) + 2. `log_artifact` additionally writes to ManifestTracker (stored reference survives the global overwrite) When only one backend is active, `artifact.save()` handles everything and `log_artifact` is effectively a pass-through. ### Resolution Priority -When resolving `${art:...}` references: +When resolving `$\{art:...\}` references: | Active Backends | Resolution Method | -|----------------|-------------------| +| --- | --- | | wandb + manifest | Resolve via wandb API (downloads artifact, gets lineage) | | manifest only | Resolve from local/fsspec manifest files | | wandb only | Resolve via wandb API | @@ -159,8 +172,8 @@ wandb_kit.finish_run(exit_code=0) ## Manifest Directory Structure -``` -{root}/ +```default +\{root\}/ ├── nano3-pretrain-data/ │ ├── v1/ │ │ ├── manifest.json # Full provenance record @@ -178,7 +191,9 @@ wandb_kit.finish_run(exit_code=0) ``` - **Zero-copy**: Data stays at its original location. Only JSON metadata is written. + - **`latest` file**: Plain text containing the version directory name (e.g., `v2`). Works on all filesystems — no symlink issues. + - **Version discovery**: Scan `v*/` directories. `latest` provides O(1) latest lookup. ### manifest.json @@ -204,7 +219,7 @@ Full provenance and lineage record: ### metadata.json -Resolver-compatible format — the full Pydantic `model_dump()` output. The `${art:data,field}` resolver reads fields from this file. +Resolver-compatible format — the full Pydantic `model_dump()` output. The `$\{art:data,field\}` resolver reads fields from this file. ## CLI Display @@ -212,7 +227,7 @@ Resolver-compatible format — the full Pydantic `model_dump()` output. The `${a Shows which artifact stores are active before the job runs: -``` +```default Job Submission ├── configs │ ├── job: /path/to/job.yaml @@ -227,7 +242,7 @@ Job Submission After a data prep or training job completes: -``` +```default ╭── Step Complete (super3-pretrain-data-tiny) ──╮ │ ... │ │ Manifest: /lustre/.../super3-pretrain-data/v1 │ @@ -253,26 +268,31 @@ cat /lustre/artifacts/nano3-sft-data/v2/manifest.json ### In W&B -1. Navigate to your project's **Artifacts** tab +1. Navigate to your project’s **Artifacts** tab + 2. Select any artifact (e.g., `ModelArtifact-rl`) + 3. Click the **Graph** view to see upstream dependencies ## Troubleshooting -### "Artifact not found" +### “Artifact not found” - Check artifact name and version (inspect manifest directory or W&B UI) + - Verify `manifest.root` in env.toml points to the correct location + - For wandb: ensure `project` and `entity` match, and run `wandb login` ### Manifest path empty in completion panel - Verify `[artifacts.manifest]` is configured in `env.toml` + - Check that the manifest root directory is writable ### Wandb digest mismatch -The pipeline automatically patches wandb's digest verification for local file references. If you still see errors, ensure you're using the latest version of the pipeline code. +The pipeline automatically patches wandb’s digest verification for local file references. If you still see errors, ensure you’re using the latest version of the pipeline code. ### Running without wandb @@ -280,7 +300,10 @@ Set `artifacts.wandb=false` on the command line or remove the `wandb = true` lin ## Further Reading -- [Artifact Types](../nemotron/artifacts.md) – Pydantic artifact classes and custom types -- [OmegaConf Resolvers](./omegaconf.md) – `${art:...}` interpolations -- [W&B Integration](../nemotron/wandb.md) – credentials and configuration -- [Execution & env.toml](./nemo-run.md) – execution profiles and env.toml reference +- [Artifact Types](/../nemotron/artifacts) – Pydantic artifact classes and custom types + +- [OmegaConf Resolvers](/omegaconf) – `$\{art:...\}` interpolations + +- [W&B Integration](/../nemotron/wandb) – credentials and configuration + +- [Execution & env.toml](/nemo-run) – execution profiles and env.toml reference diff --git a/docs/nemo_runspec/nemo-run.md b/docs/fern/pages-vnightly/nemo_runspec/nemo-run.mdx similarity index 66% rename from docs/nemo_runspec/nemo-run.md rename to docs/fern/pages-vnightly/nemo_runspec/nemo-run.mdx index d49cc3af6..9a025c5ea 100644 --- a/docs/nemo_runspec/nemo-run.md +++ b/docs/fern/pages-vnightly/nemo_runspec/nemo-run.mdx @@ -1,4 +1,8 @@ -# Execution through NeMo-Run +--- +title: "Execution through NeMo-Run" +slug: "nemo_runspec/nemo-run.html" +description: "Nemotron recipes use NeMo-Run for job orchestration. NeMo-Run is an NVIDIA tool for configuring, executing, and managing ML experiments across computing environments." +--- Nemotron recipes use [NeMo-Run](https://github.com/NVIDIA-NeMo/Run) for job orchestration. NeMo-Run is an NVIDIA tool for configuring, executing, and managing ML experiments across computing environments. @@ -36,8 +40,11 @@ flowchart LR ``` **Core concepts:** + - **Executor** – where to run (local, Docker, Slurm, cloud) + - **Packager** – how to package code for the executor + - **Launcher** – how to launch the process (torchrun, direct) For full documentation, see the [NeMo-Run GitHub repository](https://github.com/NVIDIA-NeMo/Run). @@ -59,7 +66,7 @@ uv run nemotron nano3 pretrain -c tiny --run YOUR-CLUSTER --dry-run ## Execution Profiles -The `nemo_runspec` package adds an `env.toml` configuration layer on top of NeMo-Run. This gives you declarative execution profiles that integrate with the CLI. This is a **Nemotron-specific feature** -- standard NeMo-Run requires programmatic configuration. +The `nemo_runspec` package adds an `env.toml` configuration layer on top of NeMo-Run. This gives you declarative execution profiles that integrate with the CLI. This is a **Nemotron-specific feature** – standard NeMo-Run requires programmatic configuration. Create an `env.toml` in your project root. Each section defines a named execution profile that can be referenced via `--run ` or `--batch `: @@ -109,7 +116,7 @@ time = "08:00:00" ### Slurm -Submit jobs to a Slurm cluster. Container execution requires [Pyxis](https://github.com/NVIDIA/pyxis), NVIDIA's container plugin for Slurm. +Submit jobs to a Slurm cluster. Container execution requires [Pyxis](https://github.com/NVIDIA/pyxis), NVIDIA’s container plugin for Slurm. ```toml [YOUR-CLUSTER] @@ -235,38 +242,41 @@ build_partition = "cpu" build_time = "02:00:00" # Lustre-visible host path for the build cache; mounted into the build # container at /nemotron-cache and used to land the OCI archive output. -build_cache_dir = "/lustre/.../users//.cache/nemotron" +build_cache_dir = "/lustre/.../users/\/.cache/nemotron" ``` > **Why `build_cache_dir`?** The dispatcher mounts this path into the -> build container so podman can save the resulting OCI archive somewhere -> a future training job can read. Pre-`build_cache_dir`, the dispatcher -> hard-coded `~/.cache/nemotron` evaluated at submission time, which -> resolved to the laptop's home directory and didn't exist on cluster -> nodes. Set `build_cache_dir` to a Lustre-visible path; the dispatcher -> will `mkdir -p` it on the remote before submission so first-run is -> seamless. +build container so podman can save the resulting OCI archive somewhere +a future training job can read. Pre-`build_cache_dir`, the dispatcher +hard-coded `~/.cache/nemotron` evaluated at submission time, which +resolved to the laptop’s home directory and didn’t exist on cluster +nodes. Set `build_cache_dir` to a Lustre-visible path; the dispatcher +will `mkdir -p` it on the remote before submission so first-run is +seamless. ### How the build container authenticates with private registries -The SFT Dockerfile's `FROM` references `nvcr.io/nvidian/nemo:`, +The SFT Dockerfile’s `FROM` references `nvcr.io/nvidian/nemo:`, which is gated behind NGC credentials. Rather than ask operators to provision a separate `~/.docker/config.json`, the dispatcher reuses -enroot's existing credentials at job-submission time: +enroot’s existing credentials at job-submission time: 1. The dispatcher reads `~/.config/enroot/.credentials` (netrc format) - over the SSH tunnel. +over the SSH tunnel. + 2. It filters to the `nvcr.io` entry (other registries in the file — - gitlab tokens, etc. — are *not* exposed to the build container). +gitlab tokens, etc. — are *not* exposed to the build container). + 3. It transcodes the entry into a docker-format `auth.json` and writes - it to `/.auth/auth.json` with mode `0600`. +it to `/.auth/auth.json` with mode `0600`. + 4. It mounts that file into the build container at - `/root/.config/containers/auth.json:ro`. +`/root/.config/containers/auth.json:ro`. Podman inside the build container then authenticates with `nvcr.io` automatically. No env vars, no per-job secrets in slurm scripts. If you add a new private registry the build needs, add an entry for it in -`~/.config/enroot/.credentials` and extend the dispatcher's allowlist +`~/.config/enroot/.credentials` and extend the dispatcher’s allowlist (see `materialize_podman_auth_from_enroot` in `src/nemo_runspec/execution.py`). @@ -286,9 +296,9 @@ Use the local path when iterating on the Dockerfile itself; use `nemotron omni3 NeMo-Run also supports these executors (not yet integrated into env.toml profiles): | Executor | Description | -|----------|-------------| -| `skypilot` | Cloud instances (AWS, GCP, Azure) via SkyPilot | -| `kubeflow` | Kubernetes Training Operator (PyTorchJob) | +| --- | --- | +| skypilot | Cloud instances (AWS, GCP, Azure) via SkyPilot | +| kubeflow | Kubernetes Training Operator (PyTorchJob) | ## Packagers @@ -306,18 +316,22 @@ packager = "git" ``` **How it works:** + 1. Runs `git archive --format=tar.gz` from repository root + 2. Includes only committed files (uncommitted changes are excluded) + 3. Optionally includes git submodules + 4. Transfers archive to execution target **Key options:** | Option | Default | Description | -|--------|---------|-------------| -| `subpath` | - | Package only a subdirectory of the repo | -| `include_submodules` | `true` | Include git submodules in archive | -| `include_pattern` | - | Glob pattern for additional uncommitted files | +| --- | --- | --- | +| subpath | - | Package only a subdirectory of the repo | +| include_submodules | true | Include git submodules in archive | +| include_pattern | - | Glob pattern for additional uncommitted files | **Best for:** Production runs with version-controlled code. @@ -333,16 +347,19 @@ packager_include_pattern = "src/**/*.py" ``` **How it works:** + 1. Finds files matching the glob pattern + 2. Creates tar archive of matched files + 3. Preserves directory structure relative to pattern base **Key options:** | Option | Description | -|--------|-------------| -| `include_pattern` | Glob pattern(s) for files to include | -| `relative_path` | Base path for pattern matching | +| --- | --- | +| include_pattern | Glob pattern(s) for files to include | +| relative_path | Base path for pattern matching | **Best for:** Quick iterations, non-git projects, or including generated files. @@ -358,8 +375,11 @@ packager = "hybrid" ``` **How it works:** + 1. Runs each sub-packager independently + 2. Extracts outputs to temporary directories + 3. Merges all into final archive with folder organization **Example in code:** @@ -395,9 +415,9 @@ packager = "none" ### `--run` vs `--batch` | Option | Behavior | Use Case | -|--------|----------|----------| -| `--run` | Attached—waits for completion, streams logs | Interactive development | -| `--batch` | Detached—submits and exits immediately | Long-running jobs | +| --- | --- | --- | +| --run | Attached—waits for completion, streams logs | Interactive development | +| --batch | Detached—submits and exits immediately | Long-running jobs | ### Config Overrides @@ -436,13 +456,13 @@ theme = "github-light" # Rich console theme ``` | Section | Field | Type | Description | -|---------|-------|------|-------------| -| `[wandb]` | `project` | str | W&B project name (injected into `run.wandb.project`) | -| `[wandb]` | `entity` | str | W&B entity/team name (injected into `run.wandb.entity`) | -| `[artifacts]` | `backend` | str | Artifact storage backend: `"file"` or `"wandb"` | -| `[artifacts]` | `root` | str | Root directory for file-based artifact storage | -| `[cache]` | `git_dir` | str | Directory for caching git repos cloned by `${auto_mount:...}` | -| `[cli]` | `theme` | str | Rich console theme name | +| --- | --- | --- | --- | +| [wandb] | project | str | W&B project name (injected into run.wandb.project) | +| [wandb] | entity | str | W&B entity/team name (injected into run.wandb.entity) | +| [artifacts] | backend | str | Artifact storage backend: "file" or "wandb" | +| [artifacts] | root | str | Root directory for file-based artifact storage | +| [cache] | git_dir | str | Directory for caching git repos cloned by ${auto_mount:...} | +| [cli] | theme | str | Rich console theme name | ### Execution Profile Fields @@ -473,101 +493,104 @@ startup_commands = ["source /opt/env.sh"] **Core:** | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `executor` | str | `"local"` | Execution backend: `"local"`, `"docker"`, `"slurm"`, `"dgxcloud"`, or `"lepton"` | -| `extends` | str | - | Parent profile to inherit from | +| --- | --- | --- | --- | +| executor | str | "local" | Execution backend: "local", "docker", "slurm", "dgxcloud", or "lepton" | +| extends | str | - | Parent profile to inherit from | **Local executor:** | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `nproc_per_node` | int | `1` | Number of GPU processes (for torchrun) | +| --- | --- | --- | --- | +| nproc_per_node | int | 1 | Number of GPU processes (for torchrun) | **Slurm executor:** | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `account` | str | - | Slurm account for job billing | -| `partition` | str | - | Default Slurm partition | -| `run_partition` | str | - | Partition for `--run` (attached mode) | -| `batch_partition` | str | - | Partition for `--batch` (detached mode) | -| `nodes` | int | `1` | Number of compute nodes | -| `ntasks_per_node` | int | `1` | Tasks per node | -| `gpus_per_node` | int | - | GPUs per node | -| `cpus_per_task` | int | - | CPU cores per task | -| `time` | str | `"04:00:00"` | Job time limit (HH:MM:SS) | -| `mem` | str | - | Memory per node (`"0"` = all available) | -| `exclusive` | bool | - | Request exclusive node access | +| --- | --- | --- | --- | +| account | str | - | Slurm account for job billing | +| partition | str | - | Default Slurm partition | +| run_partition | str | - | Partition for --run (attached mode) | +| batch_partition | str | - | Partition for --batch (detached mode) | +| nodes | int | 1 | Number of compute nodes | +| ntasks_per_node | int | 1 | Tasks per node | +| gpus_per_node | int | - | GPUs per node | +| cpus_per_task | int | - | CPU cores per task | +| time | str | "04:00:00" | Job time limit (HH:MM:SS) | +| mem | str | - | Memory per node ("0" = all available) | +| exclusive | bool | - | Request exclusive node access | **SSH tunnel (for remote submission):** | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `tunnel` | str | - | Set to `"ssh"` for remote submission | -| `host` | str | - | SSH hostname | -| `user` | str | - | SSH username | -| `remote_job_dir` | str | - | Working directory on the remote cluster | +| --- | --- | --- | --- | +| tunnel | str | - | Set to "ssh" for remote submission | +| host | str | - | SSH hostname | +| user | str | - | SSH username | +| remote_job_dir | str | - | Working directory on the remote cluster | **Container:** | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `container_image` | str | - | Container image path (`.sqsh` for Slurm, Docker URI for local) | -| `container` | str | - | Alias for `container_image` (checked as fallback) | -| `mounts` | list | `[]` | Container mount points (`"/host:/container"`) | +| --- | --- | --- | --- | +| container_image | str | - | Container image path (.sqsh for Slurm, Docker URI for local) | +| container | str | - | Alias for container_image (checked as fallback) | +| mounts | list | [] | Container mount points ("/host:/container") | **Startup:** | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `startup_commands` | list | `[]` | Shell commands to run before the training script | +| --- | --- | --- | --- | +| startup_commands | list | [] | Shell commands to run before the training script | **DGX Cloud executor:** | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `base_url` | str | *required* | DGX Cloud API base URL | -| `kube_apiserver_url` | str | *required* | Kubernetes API server URL for the DGX Cloud cluster | -| `client_id` | str | *required* | Client ID for authentication | -| `client_secret` | str | *required* | Client secret for authentication | -| `app_id` | str | - | Legacy alias for `client_id` (back-compat shim) | -| `app_secret` | str | - | Legacy alias for `client_secret` (back-compat shim) | -| `project_name` | str | *required* | DGX Cloud project name | -| `pvc_nemo_run_dir` | str | *required* | PVC path for nemo-run job directory | -| `nodes` | int | `1` | Number of compute nodes | -| `gpus_per_node` | int | `0` | GPUs per node | -| `nprocs_per_node` | int | `1` | Processes per node | -| `pvcs` | list | `[]` | PVC mount specifications (list of dicts with `claimName`, `path`, `readOnly`) | -| `distributed_framework` | str | `"PyTorch"` | Distributed framework (`"PyTorch"`) | -| `custom_spec` | dict | `{}` | Additional workload spec overrides (e.g., `schedulerName` for run:ai) | +| --- | --- | --- | --- | +| base_url | str | *required* | DGX Cloud API base URL | +| kube_apiserver_url | str | *required* | Kubernetes API server URL for the DGX Cloud cluster | +| client_id | str | *required* | Client ID for authentication | +| client_secret | str | *required* | Client secret for authentication | +| app_id | str | - | Legacy alias for client_id (back-compat shim) | +| app_secret | str | - | Legacy alias for client_secret (back-compat shim) | +| project_name | str | *required* | DGX Cloud project name | +| pvc_nemo_run_dir | str | *required* | PVC path for nemo-run job directory | +| nodes | int | 1 | Number of compute nodes | +| gpus_per_node | int | 0 | GPUs per node | +| nprocs_per_node | int | 1 | Processes per node | +| pvcs | list | [] | PVC mount specifications (list of dicts with claimName, path, readOnly) | +| distributed_framework | str | "PyTorch" | Distributed framework ("PyTorch") | +| custom_spec | dict | {} | Additional workload spec overrides (e.g., schedulerName for run:ai) | **Lepton executor:** | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `nemo_run_dir` | str | *required* | Remote directory for nemo-run job files | -| `nodes` | int | `1` | Number of compute nodes | -| `gpus_per_node` | int | `0` | GPUs per node | -| `nprocs_per_node` | int | `1` | Processes per node | -| `resource_shape` | str | `""` | Resource shape (e.g., `"gpu.h100.8"`) | -| `node_group` | str | `""` | Target node group | -| `node_reservation` | str | `""` | Node reservation identifier | -| `shared_memory_size` | int | `65536` | Shared memory size in MB | -| `mounts` | list | `[]` | Mount specifications (list of dicts with `path`, `mount_path`) | -| `image_pull_secrets` | list | `[]` | Container registry authentication secrets | -| `pre_launch_commands` | list | `[]` | Commands to run before launching the job | -| `custom_spec` | dict | `{}` | Additional job spec overrides | +| --- | --- | --- | --- | +| nemo_run_dir | str | *required* | Remote directory for nemo-run job files | +| nodes | int | 1 | Number of compute nodes | +| gpus_per_node | int | 0 | GPUs per node | +| nprocs_per_node | int | 1 | Processes per node | +| resource_shape | str | "" | Resource shape (e.g., "gpu.h100.8") | +| node_group | str | "" | Target node group | +| node_reservation | str | "" | Node reservation identifier | +| shared_memory_size | int | 65536 | Shared memory size in MB | +| mounts | list | [] | Mount specifications (list of dicts with path, mount_path) | +| image_pull_secrets | list | [] | Container registry authentication secrets | +| pre_launch_commands | list | [] | Commands to run before launching the job | +| custom_spec | dict | {} | Additional job spec overrides | ### How Profiles Are Resolved When you run `--run my-cluster`: 1. **Load**: `env.toml` is found by walking up from the current directory + 2. **Inherit**: If `extends = "parent"` is set, fields are inherited recursively -3. **Merge**: The profile overlays the config YAML's `run.env` defaults (`{**yaml_defaults, **profile}`) + +3. **Merge**: The profile overlays the config YAML’s `run.env` defaults (`\{**yaml_defaults, **profile\}`) + 4. **Inject**: `[wandb]` section is injected into `run.wandb` -This means config YAML provides defaults for any field env.toml doesn't set. For example, the evaluator config sets `container: nvcr.io/nvidia/nemo-evaluator:latest` in its YAML, which is used unless your env.toml profile overrides it. +This means config YAML provides defaults for any field env.toml doesn’t set. For example, the evaluator config sets `container: nvcr.io/nvidia/nemo-evaluator:latest` in its YAML, which is used unless your env.toml profile overrides it. ### Full Example @@ -677,7 +700,9 @@ uv run nemotron nano3 rl -c tiny --run YOUR-CLUSTER Ray-based recipes work with DGX Cloud and Lepton executors. The framework automatically selects the appropriate Ray backend based on the executor type: - **Slurm**: Uses `SlurmRayJob` with SSH tunnel (default) + - **DGX Cloud**: Uses `DGXCloudRayJob` for self-organizing Ray topology within distributed workloads + - **Lepton**: Uses `LeptonRayJob` with the Lepton SDK ```toml @@ -714,6 +739,9 @@ uv run nemotron nano3 rl -c tiny --run lepton-rl ## Further Reading - [NeMo-Run GitHub](https://github.com/NVIDIA-NeMo/Run) – full documentation -- [W&B Integration](../nemotron/wandb.md) – credential handling -- [Nemotron Kit](../nemotron/kit.md) – artifact system and lineage tracking -- [CLI Framework](../nemotron/cli.md) – building recipe CLIs + +- [W&B Integration](/../nemotron/wandb) – credential handling + +- [Nemotron Kit](/../nemotron/kit) – artifact system and lineage tracking + +- [CLI Framework](/../nemotron/cli) – building recipe CLIs diff --git a/docs/nemo_runspec/omegaconf.md b/docs/fern/pages-vnightly/nemo_runspec/omegaconf.mdx similarity index 85% rename from docs/nemo_runspec/omegaconf.md rename to docs/fern/pages-vnightly/nemo_runspec/omegaconf.mdx index 9dc05bd9e..3fe1d946f 100644 --- a/docs/nemo_runspec/omegaconf.md +++ b/docs/fern/pages-vnightly/nemo_runspec/omegaconf.mdx @@ -1,10 +1,14 @@ -# OmegaConf Configuration System +--- +title: "OmegaConf Configuration System" +slug: "nemo_runspec/omegaconf.html" +description: "Nemotron uses OmegaConf for configuration management, with custom resolvers (in nemo_runspec.config.resolvers) for automatic artifact resolution and W&B lineage tracking. This page covers the run sect" +--- Nemotron uses [OmegaConf](https://omegaconf.readthedocs.io/) for configuration management, with custom resolvers (in `nemo_runspec.config.resolvers`) for automatic artifact resolution and W&B lineage tracking. This page covers the `run` section in configs, artifact interpolations, and unified W&B logging. ## The `run` Section -The `run` section in recipe configs holds execution and artifact metadata. It's separate from the training algorithm configuration. +The `run` section in recipe configs holds execution and artifact metadata. It’s separate from the training algorithm configuration. ```yaml # config.yaml @@ -46,11 +50,11 @@ executor = "slurm" # ... ``` -This allows configs to reference W&B settings via interpolation (`${run.wandb.project}`) without hardcoding them. +This allows configs to reference W&B settings via interpolation (`$\{run.wandb.project\}`) without hardcoding them. ## Artifact Interpolations -The `${art:NAME,FIELD}` resolver enables automatic artifact resolution with W&B lineage tracking. +The `$\{art:NAME,FIELD\}` resolver enables automatic artifact resolution with W&B lineage tracking. ### Syntax @@ -71,13 +75,13 @@ training_path: ${art:data,training_path} # /path/to/training_4096.parque ### Supported Fields | Field | Source | Description | -|-------|--------|-------------| -| `path` | Artifact info | Local filesystem path to artifact (default) | -| `version` | Artifact info | W&B artifact version (e.g., "v5") | -| `name` | Artifact info | Artifact name | -| `type` | Artifact info | Artifact type ("dataset", "model") | -| `iteration` | Metadata | Training iteration (for model checkpoints) | -| `*` | `metadata.json` | Any field from the artifact's metadata | +| --- | --- | --- | +| path | Artifact info | Local filesystem path to artifact (default) | +| version | Artifact info | W&B artifact version (e.g., “v5”) | +| name | Artifact info | Artifact name | +| type | Artifact info | Artifact type (“dataset”, “model”) | +| iteration | Metadata | Training iteration (for model checkpoints) | +| * | metadata.json | Any field from the artifact’s metadata | ### Example: Pretrain Config @@ -132,15 +136,15 @@ data: The artifact resolver supports two modes to handle different framework requirements: | Mode | When Used | Description | -|------|-----------|-------------| -| `active_run` | W&B run already active | Calls `wandb.use_artifact()` directly | -| `pre_init` | Before `wandb.init()` | Uses `wandb.Api()` to resolve, defers lineage | +| --- | --- | --- | +| active_run | W&B run already active | Calls wandb.use_artifact() directly | +| pre_init | Before wandb.init() | Uses wandb.Api() to resolve, defers lineage | **Why two modes?** Megatron-Bridge owns `wandb.init()` during training. The kit resolves artifacts *before* training starts, then patches `wandb.init()` to register lineage once the run is active. ### Resolution Pipeline -``` +```default ┌─────────────────────────────────────────────────────────────────────┐ │ 1. Config Loading │ │ - Load YAML with OmegaConf │ @@ -172,7 +176,9 @@ The artifact resolver supports two modes to handle different framework requireme In multi-GPU training, only rank 0 downloads artifacts: 1. **Rank 0**: Downloads artifacts, writes results to shared marker file + 2. **Other ranks**: Wait for marker file, read shared results + 3. **All ranks**: Use identical artifact paths This prevents redundant downloads and ensures consistency across workers. @@ -186,13 +192,16 @@ Nemotron Kit provides a unified W&B logging approach that works across Megatron- ### The Problem | Framework | Checkpoint Logging | W&B Init | -|-----------|-------------------|----------| -| Megatron-Bridge | `on_save_checkpoint_success()` | Owns `wandb.init()` | -| NeMo-RL | `CheckpointManager.finalize_checkpoint()` | Separate init | +| --- | --- | --- | +| Megatron-Bridge | on_save_checkpoint_success() | Owns wandb.init() | +| NeMo-RL | CheckpointManager.finalize_checkpoint() | Separate init | Both frameworks need to: + - Log checkpoints as W&B artifacts + - Track lineage from input artifacts + - Store metadata for downstream jobs ### The Solution: Monkey Patches (Temporary) @@ -227,18 +236,27 @@ patch_nemo_rl_checkpoint_logging() ### What the Patches Do **`patch_wandb_checkpoint_logging()`** (Megatron-Bridge): + - Wraps `on_save_checkpoint_success()` + - Adds `wait()` call so artifacts appear immediately in W&B + - Stores `absolute_path` in metadata for cross-job access + - Resolves container paths (`/nemo_run/`) to actual Lustre paths **`patch_nemo_rl_checkpoint_logging()`** (NeMo-RL): + - Wraps `CheckpointManager.finalize_checkpoint()` + - Logs checkpoints as W&B artifacts with consistent naming + - Same metadata format as Megatron-Bridge patches **`patch_wandb_init_for_lineage()`**: + - Patches `wandb.init()` to call `use_artifact()` for resolved artifacts + - Registers lineage in W&B graph once run is active ### Container Path Resolution @@ -254,7 +272,9 @@ When running in containers, checkpoints are saved to mount paths like `/nemo_run ``` Resolution uses: + 1. `NEMO_RUN_DIR` environment variable (set by nemo-run) + 2. `/proc/mounts` to find bind mount source ## Usage in Training Scripts @@ -323,8 +343,12 @@ train_mb_tokens: ${mul:${policy.max_total_sequence_length}, ${policy.train_micro ## Further Reading -- [Artifact Lineage](../nemotron/artifacts.md) – W&B artifact system and lineage tracking -- [Creating Custom Artifacts](../nemotron/artifacts.md#creating-custom-artifacts) – defining typed artifact classes -- [W&B Integration](../nemotron/wandb.md) – credential handling -- [CLI Framework](../nemotron/cli.md) – recipe CLIs and `--run` execution -- [Execution through NeMo-Run](./nemo-run.md) – `env.toml` profiles +- [Artifact Lineage](/../nemotron/artifacts) – W&B artifact system and lineage tracking + +- [Creating Custom Artifacts](/../nemotron/artifacts#creating-custom-artifacts) – defining typed artifact classes + +- [W&B Integration](/../nemotron/wandb) – credential handling + +- [CLI Framework](/../nemotron/cli) – recipe CLIs and `--run` execution + +- [Execution through NeMo-Run](/nemo-run) – `env.toml` profiles diff --git a/docs/fern/pages-vnightly/nemo_runspec/package-readme.mdx b/docs/fern/pages-vnightly/nemo_runspec/package-readme.mdx new file mode 100644 index 000000000..c20f41da2 --- /dev/null +++ b/docs/fern/pages-vnightly/nemo_runspec/package-readme.mdx @@ -0,0 +1,152 @@ +--- +title: "nemo_runspec Package" +slug: "nemo_runspec/package-readme.html" +description: "The following content is pulled from the package source for convenience. The canonical source file in the repository is src/nemo_runspec/README.md." +--- + +The following content is pulled from the package source for convenience. The canonical source file in the repository is `src/nemo_runspec/README.md`. + +# nemo_runspec + +Bridge layer for PEP 723 `[tool.runspec]` metadata. Parses declarative metadata +from recipe scripts and provides the shared CLI toolkit that Nemotron commands +build on. + +## Philosophy + +Recipe scripts should be self-describing. Rather than scattering identity, +container images, launch methods, and resource defaults across CLI wrappers and +config files, each recipe script declares all of this as standard PEP 723 inline +metadata in a `[tool.runspec]` block at the top of the file. The CLI layer reads +this metadata and stays thin – it doesn’t encode policy about *how* to run a +script, it just asks the script what it needs. This keeps recipes portable +(any tool can read the same metadata), eliminates hidden coupling between CLI +commands and the scripts they wrap, and makes it trivial to add a new recipe: +write the script, add the `[tool.runspec]` block, and the CLI machinery picks +it up automatically. + +## What it does + +`nemo_runspec` solves two problems: + +1. **Runspec parsing** – Extracts `[tool.runspec]` TOML from PEP 723 inline +script metadata blocks, returning a frozen `Runspec` dataclass describing a +recipe’s identity, container image, launch method, config directory, and +resource requirements. + +1. **CLI toolkit** – Provides the reusable building blocks that every recipe +command needs: config loading, env.toml profile resolution, display helpers, +`RecipeTyper`, packaging, and nemo-run support. + +## Quick start + +```python +from nemo_runspec import parse + +SPEC = parse("src/nemotron/recipes/nano3/stage0_pretrain/train.py") +print(SPEC.name) # "nano3/pretrain" +print(SPEC.image) # "nvcr.io/nvidia/nemo:25.11.nemotron_3_nano" +print(SPEC.config_dir) # Path("/abs/path/to/config") +``` + +## Runspec schema + +See [docs/runspec/v1/spec.md](/../runspec/v1/spec) for the +full `[tool.runspec]` specification – field reference, format, and usage guide. + +## Package modules + +| Module | Purpose | +| --- | --- | +| _parser | PEP 723 TOML extraction and [tool.runspec] parsing | +| _models | Frozen Runspec, RunspecRun, RunspecConfig, RunspecResources dataclasses | +| config/ | Config loading and OmegaConf resolver package | +| config/loader | Config pipeline: YAML loading, dotlist overrides, profile merging, job YAML | +| config/resolvers | OmegaConf resolvers: ${art:...} artifact resolution, ${auto_mount:...} git mounts | +| env | env.toml profile loading with inheritance (extends), plus wandb/cache/artifacts config | +| cli_context | GlobalContext for shared CLI state (config, run, batch, dry-run) | +| recipe_config | RecipeConfig – normalizes CLI options into a typed object | +| recipe_typer | RecipeTyper – Typer subclass standardizing recipe command registration | +| help | RecipeCommand with custom Rich help panels (configs, overrides, profiles) | +| display | Rich display utilities for dry-run output and job submission summaries | +| step | Step dataclass for pipeline step definition (module, torchrun, command builders) | +| exceptions | ArtifactNotFoundError, ArtifactVersionNotFoundError | +| artifacts | High-level setup_artifact_tracking() + log_artifact() API for scripts | +| artifact_registry | ArtifactRegistry with fsspec/wandb backends, global accessors, resolver mode | +| manifest_tracker | ManifestTracker – zero-copy manifest-based artifact tracker (fsspec) | +| filesystem | ArtifactFileSystem – fsspec filesystem for art:// URIs | +| run | nemo-run patches (Ray CPU template, rsync host key handling) | +| pipeline | Pipeline orchestration: local subprocess piping, nemo-run, and sbatch launchers | +| execution | Execution helpers: startup commands, env vars, executor creation, local run | +| packaging | SelfContainedPackager and CodePackager for remote execution | +| squash | Container squash utilities (Docker to enroot sqsh, ensure squashed on cluster) | +| templates/ | Custom Ray CPU Slurm template (ray_cpu.sub.j2) | +| evaluator | Evaluator helpers: task flag parsing, W&B injection, config save, image collection | +| utils | Shared utilities like ${run.*} template interpolation | + +## env.toml + +Environment configuration uses TOML profiles with inheritance: + +```toml +[base] +executor = "slurm" +account = "my-account" +remote_job_dir = "/lustre/jobs" + +[dev] +extends = "base" +partition = "dev-gpu" +nodes = 1 + +[prod] +extends = "base" +partition = "prod-gpu" +nodes = 8 + +[wandb] +entity = "my-team" +project = "nemotron" + +[artifacts] +wandb = true + +[artifacts.manifest] +root = "/lustre/artifacts" + +[cache] +git_dir = "/lustre/git-cache" +``` + +Profiles are selected via `--run ` or `--batch `. +Special sections (`wandb`, `cli`, `cache`, `artifacts`) are not executor profiles. + +### Build-context keys + +For commands that compile or import container images on Slurm +(`nemotron build`, `kit squash`, etc.), profiles can set +build-specific overrides. Each key falls back through a precedence chain +so non-build jobs are unaffected: + +| Key | Purpose | Precedence | +| --- | --- | --- | +| build_partition | Slurm partition for the build job | build_partition > run_partition > partition | +| build_time | Walltime for the build job | build_time > time > caller default | +| build_image | Container image used to *run* the build (e.g. podman-in-pyxis) | build_image > caller default | +| build_cache_dir | Host-side cache dir mounted into the build container at /nemotron-cache | build_cache_dir > caller default (~/.cache/nemotron) | + +Builds are typically CPU-only, so on training profiles whose +`run_partition` is GPU-only you should set `build_partition` to a CPU +partition. Likewise, on remote builds `build_cache_dir` should point at +a cluster-visible path (typically Lustre); the laptop’s `~/.cache/` +default is not visible to compute nodes. + +```toml +[dlw] +extends = "base" +partition = "batch" +run_partition = "interactive" # GPU partition, used for training +build_partition = "cpu" # CPU partition, used for builds +build_cache_dir = "/lustre/fsw/portfolios/\/users/\/.cache/nemotron" +build_image = "docker://quay.io#podman/stable:v5.3" +``` diff --git a/docs/nemotron/artifacts.md b/docs/fern/pages-vnightly/nemotron/artifacts.mdx similarity index 68% rename from docs/nemotron/artifacts.md rename to docs/fern/pages-vnightly/nemotron/artifacts.mdx index a5b526b87..55266dd8c 100644 --- a/docs/nemotron/artifacts.md +++ b/docs/fern/pages-vnightly/nemotron/artifacts.mdx @@ -1,8 +1,12 @@ -# Artifact Types & Lineage +--- +title: "Artifact Types & Lineage" +slug: "nemotron/artifacts.html" +description: "Nemotron uses typed Pydantic artifacts to version data and models across training stages. Each artifact stores its output path plus typed metadata fields that are accessible via ${art:NAME,FIELD} conf" +--- -Nemotron uses typed Pydantic artifacts to version data and models across training stages. Each artifact stores its output path plus typed metadata fields that are accessible via `${art:NAME,FIELD}` config resolvers. +Nemotron uses typed Pydantic artifacts to version data and models across training stages. Each artifact stores its output path plus typed metadata fields that are accessible via `$\{art:NAME,FIELD\}` config resolvers. -> For the tracking infrastructure (manifest + wandb backends, `setup_artifact_tracking`, `log_artifact`, env.toml configuration), see [nemo_runspec artifacts](../nemo_runspec/artifacts.md). +> For the tracking infrastructure (manifest + wandb backends, `setup_artifact_tracking`, `log_artifact`, env.toml configuration), see [nemo_runspec artifacts](/../nemo_runspec/artifacts). ## End-to-End Lineage @@ -42,25 +46,25 @@ flowchart TB ## Artifact Types | Artifact | Stage | Format | Description | -|----------|-------|--------|-------------| -| `PretrainBlendsArtifact` | [0](./nano3/pretrain.md) | bin/idx | Tokenized pretraining data in Megatron format | -| `ModelArtifact` | 0, 1, 2 | checkpoint | Model checkpoints (pretrain, sft, rl) | -| `SFTDataArtifact` | [1](./nano3/sft.md) | Packed Parquet | Packed SFT sequences with loss masks | -| `SplitJsonlDataArtifact` | [2](./nano3/rl.md) | JSONL | RL prompts for [NeMo-RL](./nvidia-stack.md#nemo-rl) | +| --- | --- | --- | --- | +| PretrainBlendsArtifact | [0](/nano3/pretrain) | bin/idx | Tokenized pretraining data in Megatron format | +| ModelArtifact | 0, 1, 2 | checkpoint | Model checkpoints (pretrain, sft, rl) | +| SFTDataArtifact | [1](/nano3/sft) | Packed Parquet | Packed SFT sequences with loss masks | +| SplitJsonlDataArtifact | [2](/nano3/rl) | JSONL | RL prompts for [NeMo-RL](/nvidia-stack#nemo-rl) | ## Artifact Naming | Concept | Example | Where Used | -|---------|---------|------------| -| **Python class** | `PretrainBlendsArtifact` | Code imports (`from nemotron.kit import ...`) | -| **Registered name** | `super3-pretrain-data-tiny` | W&B artifact names, manifest directories | -| **Config reference** | `super3-pretrain-data-tiny:latest` | YAML configs (`run.data`), CLI overrides | +| --- | --- | --- | +| **Python class** | PretrainBlendsArtifact | Code imports (from nemotron.kit import ...) | +| **Registered name** | super3-pretrain-data-tiny | W&B artifact names, manifest directories | +| **Config reference** | super3-pretrain-data-tiny:latest | YAML configs (run.data), CLI overrides | ## Using Artifacts in Configs ### Semantic URIs -``` +```default art://super3-pretrain-data-tiny:latest # Latest version art://ModelArtifact-sft:v3 # Specific version ``` @@ -76,7 +80,7 @@ recipe: seq_length: ${art:data,pack_size} ``` -The `${art:data,FIELD}` resolver reads typed fields from the artifact's `metadata.json`. +The `$\{art:data,FIELD\}` resolver reads typed fields from the artifact’s `metadata.json`. ### CLI Overrides @@ -95,7 +99,6 @@ from typing import Annotated from pydantic import Field from nemotron.kit.artifacts.base import Artifact - class MyDataArtifact(Artifact): """Custom data artifact with typed metadata.""" @@ -150,11 +153,14 @@ uv run nemotron nano3 data import pretrain /path/to/blend.json uv run nemotron nano3 data import sft /path/to/sft_data/ ``` -See [Importing Models & Data](./nano3/import.md) for detailed directory structures. +See [Importing Models & Data](/nano3/import) for detailed directory structures. ## Further Reading -- [Artifact Tracking](../nemo_runspec/artifacts.md) – tracking infrastructure, manifest backend, env.toml config -- [Nemotron Kit](./kit.md) – kit internals -- [OmegaConf Configuration](../nemo_runspec/omegaconf.md) – `${art:...}` resolver details -- [W&B Integration](./wandb.md) – credentials and configuration +- [Artifact Tracking](/../nemo_runspec/artifacts) – tracking infrastructure, manifest backend, env.toml config + +- [Nemotron Kit](/kit) – kit internals + +- [OmegaConf Configuration](/../nemo_runspec/omegaconf) – `$\{art:...\}` resolver details + +- [W&B Integration](/wandb) – credentials and configuration diff --git a/docs/nemotron/cli.md b/docs/fern/pages-vnightly/nemotron/cli.mdx similarity index 80% rename from docs/nemotron/cli.md rename to docs/fern/pages-vnightly/nemotron/cli.mdx index 2f8471f08..55b671a51 100644 --- a/docs/nemotron/cli.md +++ b/docs/fern/pages-vnightly/nemotron/cli.mdx @@ -1,9 +1,12 @@ -# CLI Framework +--- +title: "CLI Framework" +slug: "nemotron/cli.html" +description: "The CLI framework is built on Typer and nemo_runspec. Each command file contains its own execution logic, so you can see exactly how jobs are submitted." +--- -The CLI framework is built on [Typer](https://typer.tiangolo.com/) and [`nemo_runspec`](../nemo_runspec/package-readme). Each command file contains its own execution logic, so you can see exactly how jobs are submitted. +The CLI framework is built on [Typer](https://typer.tiangolo.com/) and [`nemo_runspec`](/../nemo_runspec/package-readme). Each command file contains its own execution logic, so you can see exactly how jobs are submitted.
- ```console $ uv run nemotron nano3 sft --help Usage: nemotron nano3 sft [OPTIONS] @@ -49,18 +52,21 @@ Usage: nemotron nano3 sft [OPTIONS] ```
- ## Overview The CLI framework supports: - **Nested commands** like `uv run nemotron nano3 data prep pretrain` + - **Config integration** with automatic YAML loading and dotlist overrides -- **[Artifact resolution](./artifacts.md)** mapping [W&B artifacts](./wandb.md) to config fields via `${art:...}` -- **[Remote execution](../nemo_runspec/nemo-run.md)** via NeMo-Run with `--run` / `--batch` + +- **[Artifact resolution](/artifacts)** mapping [W&B artifacts](/wandb) to config fields via `$\{art:...\}` + +- **[Remote execution](/../nemo_runspec/nemo-run)** via NeMo-Run with `--run` / `--batch` + - **Visible execution** with all submission logic in each command file -For artifacts, see [Nemotron Kit](./kit.md). For execution profiles, see [Execution through NeMo-Run](../nemo_runspec/nemo-run.md). For the full `nemo_runspec` toolkit, see the [nemo_runspec package readme](../nemo_runspec/package-readme). +For artifacts, see [Nemotron Kit](/kit). For execution profiles, see [Execution through NeMo-Run](/../nemo_runspec/nemo-run). For the full `nemo_runspec` toolkit, see the [nemo_runspec package readme](/../nemo_runspec/package-readme). ## Architecture @@ -149,13 +155,13 @@ nano3_app.add_recipe_command(pretrain, meta=PRETRAIN_META, rich_help_panel="Trai All recipe commands automatically receive these global options: | Option | Short | Description | -|--------|-------|-------------| -| `--config` | `-c` | Config name or path (from `config_dir`) | -| `--run` | `-r` | Attached [NeMo-Run](../nemo_runspec/nemo-run.md) execution (waits, streams logs) | -| `--batch` | `-b` | Detached [NeMo-Run](../nemo_runspec/nemo-run.md) execution (submits, exits) | -| `--dry-run` | `-d` | Preview config without executing | -| `--stage` | | Stage files to remote for debugging | -| `key=value` | | Dotlist overrides (any position) | +| --- | --- | --- | +| --config | -c | Config name or path (from config_dir) | +| --run | -r | Attached [NeMo-Run](/../nemo_runspec/nemo-run) execution (waits, streams logs) | +| --batch | -b | Detached [NeMo-Run](/../nemo_runspec/nemo-run) execution (submits, exits) | +| --dry-run | -d | Preview config without executing | +| --stage | | Stage files to remote for debugging | +| key=value | | Dotlist overrides (any position) | ### GlobalContext @@ -174,7 +180,9 @@ class GlobalContext: ``` Key properties: + - `mode` -> `"run"`, `"batch"`, or `"local"` + - `profile` -> Environment profile name (from `--run` or `--batch`) ## Configuration Pipeline @@ -196,11 +204,12 @@ flowchart LR The CLI generates two config files: | File | Purpose | -|------|---------| -| `job.yaml` | Full provenance: config + CLI args + env profile | -| `train.yaml` | Clean config for script (paths rewritten for remote) | +| --- | --- | +| job.yaml | Full provenance: config + CLI args + env profile | +| train.yaml | Clean config for script (paths rewritten for remote) | **job.yaml structure:** + ```yaml recipe: _target_: megatron.bridge.recipes... @@ -286,7 +295,7 @@ uv run nemotron nano3 rl -c tiny --run MY-CLUSTER ### Config Resolver -Use `${art:...}` in YAML configs to resolve artifact paths: +Use `$\{art:...\}` in YAML configs to resolve artifact paths: ```yaml run: @@ -311,15 +320,14 @@ uv run nemotron nano3 sft --run MY-CLUSTER \ Control how code is synced to remote (configured in `[tool.runspec.run]`): | Packager | Description | Use Case | -|----------|-------------|----------| -| `pattern` | Minimal sync (`main.py` + `config.yaml`) | Default | -| `code` | Full codebase with exclusions | Ray jobs needing imports | -| `self_contained` | Inline all `nemotron.*` imports | Isolated scripts | +| --- | --- | --- | +| pattern | Minimal sync (main.py + config.yaml) | Default | +| code | Full codebase with exclusions | Ray jobs needing imports | +| self_contained | Inline all nemotron.* imports | Isolated scripts | ## CLI Examples
- ```console // Preview config without executing $ uv run nemotron nano3 pretrain -c tiny --dry-run @@ -344,7 +352,6 @@ $ uv run nemotron nano3 rl -c tiny --run MY-CLUSTER ```
- ## Building a Recipe ### Step 1: Create Recipe Script with Runspec @@ -386,7 +393,7 @@ if __name__ == "__main__": ### Step 2: Create Config Directory -``` +```default src/nemotron/recipes/myrecipe/ ├── config/ │ ├── default.yaml @@ -463,26 +470,32 @@ uv run nemotron myrecipe train -c tiny --run MY-CLUSTER ### nemo_runspec Toolkit | Export | Module | Description | -|--------|--------|-------------| -| `parse()` | `nemo_runspec` | Parse `[tool.runspec]` from a script file | -| `parse_config()` | `nemo_runspec.config` | Load YAML config with dotlist overrides | -| `build_job_config()` | `nemo_runspec.config` | Build full job config with provenance | -| `save_configs()` | `nemo_runspec.config` | Save job.yaml and train.yaml | -| `parse_env()` | `nemo_runspec.env` | Load env.toml profile | -| `parse_recipe_config()` | `nemo_runspec.recipe_config` | Parse CLI options into RecipeConfig | -| `RecipeTyper` | `nemo_runspec.recipe_typer` | Typer subclass with rich help panels | -| `RecipeMeta` | `nemo_runspec.recipe_typer` | Recipe metadata for help panels | -| `GlobalContext` | `nemo_runspec.cli_context` | Shared CLI state | -| `create_executor()` | `nemo_runspec.execution` | Build NeMo-Run executor | -| `execute_local()` | `nemo_runspec.execution` | Run locally via torchrun | -| `build_env_vars()` | `nemo_runspec.execution` | Build env vars (HF, W&B tokens) | +| --- | --- | --- | +| parse() | nemo_runspec | Parse [tool.runspec] from a script file | +| parse_config() | nemo_runspec.config | Load YAML config with dotlist overrides | +| build_job_config() | nemo_runspec.config | Build full job config with provenance | +| save_configs() | nemo_runspec.config | Save job.yaml and train.yaml | +| parse_env() | nemo_runspec.env | Load env.toml profile | +| parse_recipe_config() | nemo_runspec.recipe_config | Parse CLI options into RecipeConfig | +| RecipeTyper | nemo_runspec.recipe_typer | Typer subclass with rich help panels | +| RecipeMeta | nemo_runspec.recipe_typer | Recipe metadata for help panels | +| GlobalContext | nemo_runspec.cli_context | Shared CLI state | +| create_executor() | nemo_runspec.execution | Build NeMo-Run executor | +| execute_local() | nemo_runspec.execution | Run locally via torchrun | +| build_env_vars() | nemo_runspec.execution | Build env vars (HF, W&B tokens) | ## Further Reading -- [Nemotron Kit](./kit.md) – artifacts and lineage tracking -- [`nemo_runspec` Package](../nemo_runspec/package-readme) – toolkit documentation -- [Execution through NeMo-Run](../nemo_runspec/nemo-run.md) – execution profiles and env.toml -- [Data Preparation](./data-prep.md) – data preparation module -- [Artifact Lineage](./artifacts.md) – W&B artifact system and lineage tracking -- [W&B Integration](./wandb.md) – credentials and configuration -- [Nano3 Recipe](./nano3/README.md) – training recipe example +- [Nemotron Kit](/kit) – artifacts and lineage tracking + +- [`nemo_runspec` Package](/../nemo_runspec/package-readme) – toolkit documentation + +- [Execution through NeMo-Run](/../nemo_runspec/nemo-run) – execution profiles and env.toml + +- [Data Preparation](/data-prep) – data preparation module + +- [Artifact Lineage](/artifacts) – W&B artifact system and lineage tracking + +- [W&B Integration](/wandb) – credentials and configuration + +- [Nano3 Recipe](/nano3/README) – training recipe example diff --git a/docs/nemotron/data-prep.md b/docs/fern/pages-vnightly/nemotron/data-prep.mdx similarity index 79% rename from docs/nemotron/data-prep.md rename to docs/fern/pages-vnightly/nemotron/data-prep.mdx index 113e43e6d..3c626dca3 100644 --- a/docs/nemotron/data-prep.md +++ b/docs/fern/pages-vnightly/nemotron/data-prep.mdx @@ -1,4 +1,8 @@ -# Data Preparation Module +--- +title: "Data Preparation Module" +slug: "nemotron/data-prep.html" +description: "The nemotron.data_prep module handles last-mile data processing: transforming curated datasets into training-ready formats. It sits between data curation (handled by NeMo Curator) and model training, " +--- The `nemotron.data_prep` module handles **last-mile data processing**: transforming curated datasets into training-ready formats. It sits between data curation (handled by [NeMo Curator](https://github.com/NVIDIA-NeMo/Curator)) and model training, producing outputs compatible with the NVIDIA AI training stack. @@ -9,9 +13,13 @@ The `nemotron.data_prep` module handles **last-mile data processing**: transform Built on [Ray](https://ray.io/), the module provides: - **Last-mile processing** – convert curated datasets to training-ready formats (tokenization, packing, chat templating) + - **Distributed processing** – scale from a single machine to a cluster of workers using Ray actors + - **Cloud-native I/O** – read from HuggingFace Hub (`hf://`), S3 (`s3://`), GCS (`gs://`), or local paths via fsspec + - **Deterministic output** – frozen shard plans ensure reproducible results across runs + - **Resumable pipelines** – skip completed shards on restart; verify output integrity with checksums ### Data Pipeline: Curator → Data Prep → Training @@ -54,22 +62,24 @@ flowchart LR ``` **Typical workflow:** + 1. Use **[NeMo Curator](https://github.com/NVIDIA-NeMo/Curator)** to curate raw data at scale—deduplication, quality filtering, language identification, PII removal + 2. Use **Data Prep** to transform curated data into training-ready formats—tokenization, chat templating, sequence packing, loss mask generation This separation allows you to curate once and prepare data multiple times for different training configurations (different tokenizers, sequence lengths, or output formats). ### Recipe Integration -Each training stage in a recipe includes a dedicated data preparation step that transforms source data into the format required by that stage's training framework: +Each training stage in a recipe includes a dedicated data preparation step that transforms source data into the format required by that stage’s training framework: | Stage | Data Prep Output | Training Framework | Guide | -|-------|------------------|-------------------|-------| -| Stage 0: Pretrain | bin/idx indexed datasets | [Megatron-Bridge](./nvidia-stack.md#megatron-bridge) | [pretrain.md](./nano3/pretrain.md#data-preparation) | -| Stage 1: SFT | Packed Parquet with loss masks | [Megatron-Bridge](./nvidia-stack.md#megatron-bridge) | [sft.md](./nano3/sft.md#data-preparation) | -| Stage 2: RL | JSONL with OpenAI chat format | [NeMo-RL](./nvidia-stack.md#nemo-rl) | [rl.md](./nano3/rl.md#data-preparation) | +| --- | --- | --- | --- | +| Stage 0: Pretrain | bin/idx indexed datasets | [Megatron-Bridge](/nvidia-stack#megatron-bridge) | [pretrain.md](/nano3/pretrain#data-preparation) | +| Stage 1: SFT | Packed Parquet with loss masks | [Megatron-Bridge](/nvidia-stack#megatron-bridge) | [sft.md](/nano3/sft#data-preparation) | +| Stage 2: RL | JSONL with OpenAI chat format | [NeMo-RL](/nvidia-stack#nemo-rl) | [rl.md](/nano3/rl#data-preparation) | -Run data preparation for any stage using the [CLI](./cli.md): +Run data preparation for any stage using the [CLI](/cli): ```bash uv run nemotron nano3 data prep pretrain --run YOUR-CLUSTER # Stage 0 @@ -77,11 +87,11 @@ uv run nemotron nano3 data prep sft --run YOUR-CLUSTER # Stage 1 uv run nemotron nano3 data prep rl --run YOUR-CLUSTER # Stage 2 ``` -> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](../nemo_runspec/nemo-run.md). See [Execution through NeMo-Run](../nemo_runspec/nemo-run.md) for setup. +> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](/../nemo_runspec/nemo-run). See [Execution through NeMo-Run](/../nemo_runspec/nemo-run) for setup. ### NeMo-Run Integration -The module integrates natively with [NeMo-Run](../nemo_runspec/nemo-run.md) for job orchestration. Submit data preparation jobs to various executors (Slurm, local, Docker, cloud) directly from your local machine: +The module integrates natively with [NeMo-Run](/../nemo_runspec/nemo-run) for job orchestration. Submit data preparation jobs to various executors (Slurm, local, Docker, cloud) directly from your local machine: ```bash # Submit to Slurm cluster @@ -103,29 +113,32 @@ account = "YOUR-ACCOUNT" partition = "batch" ``` -See [Execution through NeMo-Run](../nemo_runspec/nemo-run.md) for complete configuration options. +See [Execution through NeMo-Run](/../nemo_runspec/nemo-run) for complete configuration options. ## Choosing an API | API | Use When | Output Format | -|-----|----------|---------------| -| `run_pretrain_pipeline()` | Pretraining tokenization | bin/idx | -| `run_sft_pipeline()` | Chat SFT with loss masking | Packed Parquet | +| --- | --- | --- | +| run_pretrain_pipeline() | Pretraining tokenization | bin/idx | +| run_sft_pipeline() | Chat SFT with loss masking | Packed Parquet | - `run_pretrain_pipeline()` — Standard pretraining tokenization to bin/idx format + - `run_sft_pipeline()` — Chat SFT with role-based loss masking to packed Parquet **For JSONL output** (RL training): + - Use the stage-specific scripts in `nemotron/recipes/nano3/stage2_rl/data_prep.py` + - Or call `process_jsonl_shard_core()` directly from `nemotron.data_prep.core` ## Supported Output Formats | Format | Recipe | Output | Use Case | -|--------|--------|--------|----------| -| `binidx` | `run_pretrain_pipeline()` | `.bin/.idx` pairs | Pretraining | -| `packed_parquet` | `run_sft_pipeline()` | `.parquet` files | Chat SFT | -| `jsonl` | Stage scripts | `.jsonl` files | RL training | +| --- | --- | --- | --- | +| binidx | run_pretrain_pipeline() | .bin/.idx pairs | Pretraining | +| packed_parquet | run_sft_pipeline() | .parquet files | Chat SFT | +| jsonl | Stage scripts | .jsonl files | RL training | ## Quick Start @@ -170,7 +183,6 @@ print(f"Run hash: {result.run_hash}") print(f"Total sequences: {result.total_sequences:,}") ``` - ## Output Formats ### BinIdx (Default) @@ -243,6 +255,7 @@ result = run_sft_pipeline( ``` **Input format** (OpenAI chat messages): + ```json { "messages": [ @@ -254,8 +267,11 @@ result = run_sft_pipeline( ``` **Output**: + - `.parquet` files with packed `input_ids` and `loss_mask` arrays + - Loss mask: `0` for system/user tokens, `1` for assistant tokens + - Metadata files for Megatron-Bridge compatibility ## Transforms @@ -374,7 +390,7 @@ transform = lambda r: {"input": r["q"], "output": r["a"]} if r.get("valid") else # Function def my_transform(record: dict) -> dict | None: - if len(record.get("text", "")) < 10: + if len(record.get("text", "")) \< 10: return None # Skip short records return {"input": record["question"], "output": record["answer"]} ``` @@ -388,7 +404,7 @@ def filter_by_length(min_chars: int = 100) -> Transform: """Skip records with text shorter than min_chars.""" def transform(record: dict) -> dict | None: text = record.get("text", "") - if len(text) < min_chars: + if len(text) \< min_chars: return None # Record will be skipped return record return transform @@ -442,7 +458,8 @@ config = PipelineConfig( ``` **Output structure:** -``` + +```default output/ ├── train/ │ ├── shard_000000.bin @@ -456,6 +473,7 @@ output/ ``` **blend.json format** (per-split mode): + ```json { "train": [["1.0", "/path/to/train/shard_000000"], ["1.0", "/path/to/train/shard_000001"]], @@ -464,7 +482,7 @@ output/ } ``` -This format is directly compatible with Megatron-Bridge's per-split data loading. +This format is directly compatible with Megatron-Bridge’s per-split data loading. ## Type Definitions @@ -484,37 +502,37 @@ from nemotron.data_prep.formats.transforms import ( ### Recipe Entry Points | Function | Description | -|----------|-------------| -| `run_pretrain_pipeline(blend, output_dir, tokenizer, num_shards, ...)` | Tokenize to Megatron bin/idx format | -| `run_sft_pipeline(blend, output_dir, tokenizer, num_shards, ...)` | Chat SFT to packed Parquet format | +| --- | --- | +| run_pretrain_pipeline(blend, output_dir, tokenizer, num_shards, ...) | Tokenize to Megatron bin/idx format | +| run_sft_pipeline(blend, output_dir, tokenizer, num_shards, ...) | Chat SFT to packed Parquet format | ### Core Processing Functions | Function | Description | -|----------|-------------| -| `process_binidx_shard_core(...)` | Tokenize shard to bin/idx (alias: `process_binidx_shard_files_core`) | -| `process_jsonl_shard_core(...)` | Transform and write JSONL records | -| `process_chat_sft_spool_core(...)` | Tokenize chat messages to spool intermediate | -| `process_chat_sft_parquet_core(...)` | Pack spool to Parquet output | +| --- | --- | +| process_binidx_shard_core(...) | Tokenize shard to bin/idx (alias: process_binidx_shard_files_core) | +| process_jsonl_shard_core(...) | Transform and write JSONL records | +| process_chat_sft_spool_core(...) | Tokenize chat messages to spool intermediate | +| process_chat_sft_parquet_core(...) | Pack spool to Parquet output | ### Configuration Classes | Class | Description | -|-------|-------------| -| `PipelineConfig` | Pipeline configuration | -| `TokenizerConfig` | Tokenizer settings (model, type, add_bos, add_eos) | -| `OutputConfig` | Output directory and format | -| `BinIdxOutputConfig` | Tokenized binary format options | -| `JsonlOutputConfig` | JSONL format options | -| `ChatSftOutputConfig` | Chat SFT with loss masking options | -| `ObservabilityConfig` | W&B and pipeline logging settings | +| --- | --- | +| PipelineConfig | Pipeline configuration | +| TokenizerConfig | Tokenizer settings (model, type, add_bos, add_eos) | +| OutputConfig | Output directory and format | +| BinIdxOutputConfig | Tokenized binary format options | +| JsonlOutputConfig | JSONL format options | +| ChatSftOutputConfig | Chat SFT with loss masking options | +| ObservabilityConfig | W&B and pipeline logging settings | ### Result Classes | Class | Description | -|-------|-------------| -| `FormatResult` | Pipeline result with run metadata, data paths, and statistics | -| `DataBlendsArtifact` | Artifact with blend.json path and metrics | +| --- | --- | +| FormatResult | Pipeline result with run metadata, data paths, and statistics | +| DataBlendsArtifact | Artifact with blend.json path and metrics | ## Compression @@ -531,21 +549,33 @@ Requires the `zstandard` package: `uv pip install zstandard` ## Dependencies Core dependencies: + - `ray` - Parallel processing + - `pyarrow` - Parquet file reading + - `xxhash` - Fast checksums Optional dependencies: + - `orjson` - Fast JSON serialization (falls back to stdlib json) + - `zstandard` - Zstd compression for JSONL output ## Further Reading - [NeMo Curator](https://github.com/NVIDIA-NeMo/Curator) – data curation at scale (coming soon) + - [NeMo Data Designer](https://github.com/NVIDIA-NeMo/DataDesigner) – synthetic data generation (coming soon) -- [NVIDIA AI Stack](./nvidia-stack.md) – Megatron-Core, Megatron-Bridge, NeMo-RL -- [Execution through NeMo-Run](../nemo_runspec/nemo-run.md) – job orchestration and execution profiles -- [CLI Framework](./cli.md) – CLI building and recipe commands -- [Artifact Lineage](./artifacts.md) – W&B artifact system and lineage tracking -- [Xenna Observability](./xenna-observability.md) – real-time W&B logging for xenna pipelines -- [Nano3 Recipe](./nano3/README.md) – training recipe example + +- [NVIDIA AI Stack](/nvidia-stack) – Megatron-Core, Megatron-Bridge, NeMo-RL + +- [Execution through NeMo-Run](/../nemo_runspec/nemo-run) – job orchestration and execution profiles + +- [CLI Framework](/cli) – CLI building and recipe commands + +- [Artifact Lineage](/artifacts) – W&B artifact system and lineage tracking + +- [Xenna Observability](/xenna-observability) – real-time W&B logging for xenna pipelines + +- [Nano3 Recipe](/nano3/README) – training recipe example diff --git a/docs/nemotron/embed/README.md b/docs/fern/pages-vnightly/nemotron/embed/README.mdx similarity index 92% rename from docs/nemotron/embed/README.md rename to docs/fern/pages-vnightly/nemotron/embed/README.mdx index 82480f0b4..763a3176e 100644 --- a/docs/nemotron/embed/README.md +++ b/docs/fern/pages-vnightly/nemotron/embed/README.mdx @@ -1,22 +1,28 @@ -# Embedding Model Fine-Tuning Recipe +--- +title: "Embedding Model Fine-Tuning Recipe" +slug: "nemotron/embed/README.html" +description: "A complete 6-stage pipeline for fine-tuning and deploying embedding models on domain-specific data using synthetic data generation." +--- A complete 6-stage pipeline for fine-tuning and deploying embedding models on domain-specific data using synthetic data generation. ## Overview -This recipe fine-tunes NVIDIA's [Llama-Nemotron-Embed-1B-v2](https://huggingface.co/nvidia/llama-nemotron-embed-1b-v2) embedding model on your own domain data. By the end of this pipeline, you'll have a domain-adapted embedding model that excels at retrieving relevant documents from your specific corpus. +This recipe fine-tunes NVIDIA’s [Llama-Nemotron-Embed-1B-v2](https://huggingface.co/nvidia/llama-nemotron-embed-1b-v2) embedding model on your own domain data. By the end of this pipeline, you’ll have a domain-adapted embedding model that excels at retrieving relevant documents from your specific corpus. ### Why Fine-Tune Embedding Models? Pre-trained embedding models work well for general-purpose retrieval, but may underperform on specialized domains with unique terminology, document structures, or query patterns. Fine-tuning adapts the model to: - Understand domain-specific vocabulary and concepts + - Better match the types of queries your users will ask + - Improve retrieval accuracy on your specific document corpus ## Training Pipeline -``` +```default ┌─────────────────────────────────────────────────────────────────────────────┐ │ YOUR DOCUMENT CORPUS │ │ (Text files: .txt, .md, etc.) │ @@ -74,13 +80,13 @@ Pre-trained embedding models work well for general-purpose retrieval, but may un ``` | Stage | Command | Description | Output | -|-------|---------|-------------|--------| -| Stage 0: SDG | `nemotron embed sdg` | Validate corpus, generate synthetic Q&A pairs from documents | Q&A pairs with quality scores | -| Stage 1: Data Prep | `nemotron embed prep` | Convert, mine hard negatives, unroll | Training-ready data | -| Stage 2: Finetune | `nemotron embed finetune` | Fine-tune embedding model | Model checkpoint | -| Stage 3: Eval | `nemotron embed eval` | Evaluate on retrieval metrics | Metrics comparison | -| Stage 4: Export | `nemotron embed export` | Export to ONNX/TensorRT | Optimized inference models | -| Stage 5: Deploy | `nemotron embed deploy` | Deploy NIM with custom model | Running inference service | +| --- | --- | --- | --- | +| Stage 0: SDG | nemotron embed sdg | Validate corpus, generate synthetic Q&A pairs from documents | Q&A pairs with quality scores | +| Stage 1: Data Prep | nemotron embed prep | Convert, mine hard negatives, unroll | Training-ready data | +| Stage 2: Finetune | nemotron embed finetune | Fine-tune embedding model | Model checkpoint | +| Stage 3: Eval | nemotron embed eval | Evaluate on retrieval metrics | Metrics comparison | +| Stage 4: Export | nemotron embed export | Export to ONNX/TensorRT | Optimized inference models | +| Stage 5: Deploy | nemotron embed deploy | Deploy NIM with custom model | Running inference service | ## Installation @@ -105,10 +111,12 @@ uv sync --all-extras ### 3. Get Your NVIDIA API Key -The SDG stage (Stage 0) uses NVIDIA's hosted LLM APIs for synthetic data generation. +The SDG stage (Stage 0) uses NVIDIA’s hosted LLM APIs for synthetic data generation. 1. Sign up at [build.nvidia.com](https://build.nvidia.com) + 2. Create an API key + 3. Set the environment variable: ```bash @@ -120,6 +128,7 @@ export NVIDIA_API_KEY=nvapi-your_key_here For Docker or Slurm execution, create `env.toml` in the **repository root directory**. **Minimal configuration (local execution only):** + ```toml [wandb] project = "my-embedding-project" @@ -134,13 +143,15 @@ See the [Execution Profiles](#execution-profiles) section below. ### Supported Formats - Any text files, default: .txt, .md, .text, and files with no extension + - Documents should be UTF-8 encoded + - Files are processed recursively from the corpus directory ### Corpus Size Recommendations | Corpus Size | Documents | Expected Results | -|-------------|-----------|------------------| +| --- | --- | --- | | **Minimum** | 50-100 docs (~50K tokens) | Basic domain adaptation | | **Recommended** | 500+ docs | Good domain coverage | | **Optimal** | 1000+ docs | Best performance | @@ -162,8 +173,11 @@ All files matching the `file_extensions` config (default: `.txt,.md`) will be pr ### Document Quality Tips - **Length**: Aim for 200-2000 tokens per document + - **Content**: Ensure documents are representative of your domain + - **Diversity**: Include various document types/topics from your domain + - **Quality**: Clean, well-formatted text yields better synthetic Q&A pairs ## Prerequisites @@ -171,25 +185,35 @@ All files matching the `file_extensions` config (default: `.txt,.md`) will be pr ### Hardware Requirements - **GPU**: NVIDIA GPU with at least 80GB VRAM (e.g., A100, H100) - - Stages 0 uses NVIDIA API (no GPU required) - - Stage 1-5: Require GPU for model inference and training + + - Stages 0 uses NVIDIA API (no GPU required) + + - Stage 1-5: Require GPU for model inference and training + - **CPU**: Modern multi-core processor (16+ cores recommended) + - **Memory**: 128GB+ RAM recommended + - **Storage**: ~50GB free disk space for outputs, models, and containers ### Software Requirements - **Python**: 3.12 or later + - **UV**: Package manager (installation instructions above) + - **NVIDIA API Key**: Required for synthetic data generation + - **NVIDIA GPU Drivers**: Latest drivers for your GPU + - **Docker** (optional): For containerized execution + - **Slurm** (optional): For cluster execution ### Expected Runtime & Resources | Stage | GPU VRAM | CPU | Notes | -|-------|----------|-----|-------| +| --- | --- | --- | --- | | Stage 0 (SDG) | N/A | 8+ cores | Uses API (no local GPU); runtime varies by dataset size | | Stage 1 (Data Prep) | 40GB | 16+ cores | Hard negative mining on GPU; runtime varies by dataset size | | Stage 2 (Finetune) | 80GB | 16+ cores | Runtime varies by dataset size and epochs | @@ -200,22 +224,30 @@ All files matching the `file_extensions` config (default: `.txt,.md`) will be pr **Total disk space**: ~50GB for outputs, model checkpoints, and containers **Runtime**: Highly dependent on dataset size. Expect longer runtimes for larger corpora and more training epochs. - - For small dataset (e.g. nv_pp_random with ~70 input files), it can take ~30 minutes for Stage 0 (SDG) with the default setup. Changing to other LLM endpoints or tune `max_parallel_requests_for_gen` can affect the runtime, rate limit failures, and generation quality. It can take 10-20 minutes for Stage 2 (Finetune) with the default setup. - - For large dataset (e.g. 10K+ input files), it can take tens of hours or 1-2 days for Stage 0 (SDG) and 5-10 hours for Stage 2 (Finetune). Changing model endpoints, type and number of GPUs (and other fine-tune parameters) can affect the runtime. +- For small dataset (e.g. nv_pp_random with ~70 input files), it can take ~30 minutes for Stage 0 (SDG) with the default setup. Changing to other LLM endpoints or tune `max_parallel_requests_for_gen` can affect the runtime, rate limit failures, and generation quality. It can take 10-20 minutes for Stage 2 (Finetune) with the default setup. + +- For large dataset (e.g. 10K+ input files), it can take tens of hours or 1-2 days for Stage 0 (SDG) and 5-10 hours for Stage 2 (Finetune). Changing model endpoints, type and number of GPUs (and other fine-tune parameters) can affect the runtime. ### LLM API Usage (Stage 0) -Stage 0 uses LLM APIs for synthetic data generation. By default, it uses NVIDIA's hosted LLMs: +Stage 0 uses LLM APIs for synthetic data generation. By default, it uses NVIDIA’s hosted LLMs: - **Default provider**: NVIDIA API (free tier available at [build.nvidia.com](https://build.nvidia.com)) + - **Default model**: `nvidia/nemotron-3-nano-30b-a3b` (fast, reliable for structured generation) + - **Usage**: ~4 API calls per document (artifact extraction, QA generation, dedup, quality eval) + - **Cost**: Free tier has rate limits; contact NVIDIA for production usage + - **Progress**: Built-in progress logging shows completion %, records/second, and ETA per stage + - **Other providers**: NeMo Data Designer supports multiple providers (OpenAI, OpenRouter, etc.) - - Customize provider settings in the config file - - See [default provider settings](https://nvidia-nemo.github.io/DataDesigner/latest/concepts/models/default-model-settings/) for configuration options + + - Customize provider settings in the config file + + - See [default provider settings](https://nvidia-nemo.github.io/DataDesigner/latest/concepts/models/default-model-settings/) for configuration options ## Quick Start @@ -260,9 +292,9 @@ nemotron embed finetune -c default --dry-run Stages are designed to run sequentially, but you can start from any stage if you have the required inputs: | Start From | Requirement | Use Case | -|------------|-------------|----------| +| --- | --- | --- | | **Stage 0** | Document corpus | Full pipeline from scratch | -| **Stage 1** | Q&A pairs (JSON) | Skip SDG if you have labeled data or use [NVIDIA's pre-generated dataset](#using-nvidias-pre-generated-dataset) | +| **Stage 1** | Q&A pairs (JSON) | Skip SDG if you have labeled data or use [NVIDIA’s pre-generated dataset](#using-nvidia-s-pre-generated-dataset) | | **Stage 2** | Training data (Automodel format) | Skip data prep if data is ready | | **Stage 3** | Model checkpoint | Evaluate existing checkpoint | | **Stage 4** | Model checkpoint | Export existing model | @@ -270,9 +302,9 @@ Stages are designed to run sequentially, but you can start from any stage if you See individual stage READMEs for input format requirements. -### Using NVIDIA's Pre-Generated Dataset +### Using NVIDIA’s Pre-Generated Dataset -NVIDIA provides a ready-to-use synthetic retrieval dataset on Hugging Face: [Retrieval-Synthetic-NVDocs-v1](https://huggingface.co/datasets/nvidia/Retrieval-Synthetic-NVDocs-v1). This dataset was generated from NVIDIA's publicly available content using the same SDG pipeline (Stage 0) in this recipe, and contains ~15K documents with 105K+ question-answer pairs across multiple reasoning types. +NVIDIA provides a ready-to-use synthetic retrieval dataset on Hugging Face: [Retrieval-Synthetic-NVDocs-v1](https://huggingface.co/datasets/nvidia/Retrieval-Synthetic-NVDocs-v1). This dataset was generated from NVIDIA’s publicly available content using the same SDG pipeline (Stage 0) in this recipe, and contains ~15K documents with 105K+ question-answer pairs across multiple reasoning types. If you want to fine-tune an embedding model on NVIDIA-related content, you can **skip Stage 0 entirely** and start directly from Stage 1: @@ -413,12 +445,13 @@ cd /path/to/staged/files Each stage has a `config/` directory with YAML configuration files. | File | Purpose | -|------|---------| -| `default.yaml` | Production-ready configuration | +| --- | --- | +| default.yaml | Production-ready configuration | ### Key Configuration Options **Stage 0: SDG** + ```yaml corpus_id: my_corpus # Identifier for your corpus corpus_dir: ./data/corpus # Path to your documents @@ -431,6 +464,7 @@ max_parallel_requests_for_gen: 4 # Number of parallel requests to submit to LLM ``` **Stage 1: Data Prep** + ```yaml base_model: nvidia/llama-nemotron-embed-1b-v2 # Model for hard negative mining quality_threshold: 7.0 # Minimum Q&A quality score (0-10) @@ -446,6 +480,7 @@ test_ratio: 0.1 # Test split (10%) ``` **Stage 2: Finetune** + ```yaml base_model: nvidia/llama-nemotron-embed-1b-v2 num_epochs: 3 @@ -460,6 +495,7 @@ train_n_passages: 5 # 1 positive + 4 hard negatives > **Warning — Overfitting risk**: The default `num_epochs: 3` is set for the small example dataset shipped with this recipe, where fewer epochs may not produce a visible training signal. For most real-world datasets, **1–2 epochs is sufficient** and 3 epochs carries a high risk of overfitting. Lower this value when working with your own data (e.g., `nemotron embed finetune -c default num_epochs=1`). **Stage 3: Eval** + ```yaml k_values: [1, 5, 10, 100] # K values for Recall@k, nDCG@k max_length: 512 # Max sequence length (check your base model's max sequence length) @@ -469,6 +505,7 @@ eval_nim: false # Evaluate NIM endpoint ``` **Stage 4: Export** + ```yaml model_path: ./output/embed/stage2_finetune/checkpoints/LATEST/model/consolidated export_to_trt: true # Export to TensorRT (requires nemo:25.07+ container) @@ -478,6 +515,7 @@ trt_opt_seq_len: 128 # Optimal sequence length for TRT ``` **Stage 5: Deploy** + ```yaml nim_image: nvcr.io/nim/nvidia/llama-3.2-nv-embedqa-1b-v2:1.10.1 model_dir: ./output/embed/stage4_export/onnx # Path to exported model @@ -487,7 +525,7 @@ detach: false # Run in background ### Customizing Sequence Length -The pipeline defaults to 512-token sequences. You can change this to match your use case, up to the base model's max sequence length (e.g., 8192 for the default `nvidia/llama-nemotron-embed-1b-v2`; check your model's documentation if using a different base model). +The pipeline defaults to 512-token sequences. You can change this to match your use case, up to the base model’s max sequence length (e.g., 8192 for the default `nvidia/llama-nemotron-embed-1b-v2`; check your model’s documentation if using a different base model). For example, to use 2000-token passages, override the sequence length consistently across stages: @@ -606,7 +644,7 @@ nemotron embed eval -c default eval_nim=true eval_base=false After running the full pipeline: -``` +```default output/embed/ ├── stage0_sdg/ # Synthetic Q&A pairs │ └── generated_batch*.json @@ -634,7 +672,7 @@ output/embed/ The evaluation stage computes standard information retrieval metrics using the BEIR framework. | Metric | Description | Range | -|--------|-------------|-------| +| --- | --- | --- | | **nDCG@k** | Normalized Discounted Cumulative Gain (ranking quality) | 0.0-1.0 | | **Recall@k** | Fraction of relevant documents in top-k results | 0.0-1.0 | | **Precision@k** | Fraction of retrieved documents that are relevant | 0.0-1.0 | @@ -645,12 +683,14 @@ Higher scores indicate better retrieval performance. ### Interpreting Results **Good fine-tuning results typically show:** + - nDCG@10 and Recall@10 improvement of **15%** over base model + - Consistent improvements across all k values **Example successful evaluation:** -``` +```default Model: base - nDCG@10: 0.42 - Recall@10: 0.65 @@ -663,14 +703,17 @@ Model: fine-tuned ``` **Warning signs:** + - **No improvement**: May need more training data or higher quality Q&A pairs + - **Worse performance**: Check for data quality issues or training hyperparameters + - **Overfitting**: Good training metrics but poor validation metrics ## Key Components | Component | Purpose | Repository | -|-----------|---------|------------| +| --- | --- | --- | | retriever-sdg | Synthetic data generation using NeMo Data Designer | [GitHub](https://github.com/NVIDIA-NeMo/DataDesigner) | | Automodel | Embedding model training framework | [GitHub](https://github.com/NVIDIA/NeMo-Automodel) | | BEIR | Evaluation framework for information retrieval | [GitHub](https://github.com/beir-cellar/beir) | @@ -680,7 +723,7 @@ Model: fine-tuned ## Base Model | Property | Value | -|----------|-------| +| --- | --- | | Model | nvidia/llama-nemotron-embed-1b-v2 | | Parameters | ~1B | | Embedding Dimension | 768 | @@ -693,6 +736,7 @@ Model: fine-tuned ### Installation Issues **Error: `uv: command not found`** + ```bash # Install UV package manager curl -LsSf https://astral.sh/uv/install.sh | sh @@ -701,6 +745,7 @@ export PATH="$HOME/.cargo/bin:$PATH" ``` **Error: `nemotron: command not found`** + ```bash # Make sure you're in the Nemotron directory cd /path/to/Nemotron @@ -711,32 +756,41 @@ uv run nemotron embed info ### Stage 0: SDG Issues **Error: `NVIDIA_API_KEY not set`** + ```bash # Set your API key export NVIDIA_API_KEY=nvapi-your_key_here ``` **Error: API rate limiting** + - **Solution**: Reduce batch size in config or add delays between API calls + - **Alternative**: Contact NVIDIA for increased rate limits for production use **Error: Poor Q&A quality scores** + - **Solution**: Check document quality - ensure clean, well-formatted text + - **Solution**: Adjust `sentences_per_chunk` in config (default: 5 sentences per chunk) ### Stage 1: Data Preparation Issues **Error: `CUDA out of memory` during hard negative mining** + ```bash # Reduce mining batch size in config nemotron embed prep -c default mining_batch_size=64 ``` **Error: No valid Q&A pairs after quality filtering** + - **Solution**: Lower quality_threshold (default: 7.0) + - **Solution**: Check SDG output quality scores **Error: Import errors for `nemo_automodel`** + ```bash # Ensure dependencies are installed cd /path/to/Nemotron @@ -746,28 +800,38 @@ uv sync --all-extras ### Stage 2: Training Issues **Error: Train Loss not decreasing** + - **Solution**: Try adjusting learning rate (default: 1e-5; try 5e-6 or 2e-5) + - **Solution**: Lower `global_batch_size` to increase the number of gradient update steps + - **Solution**: Check training data quality **Error: Train Loss is NaN** + - **Solution**: Reduce learning rate significantly + - **Solution**: Check for data quality issues (missing values, corrupted entries) **Error: `CUDA out of memory` during training** + ```bash # Reduce local batch size nemotron embed finetune -c default local_batch_size=2 ``` **Error: Training very slow** + - **Check**: GPU utilization with `nvidia-smi` + - **Solution**: Increase batch size if GPU not fully utilized + - **Solution**: Enable mixed precision training (usually enabled by default) ### Stage 3: Evaluation Issues **Error: Model checkpoint not found** + ```bash # Check checkpoint path ls -la output/embed/stage2_finetune/checkpoints/LATEST/model/consolidated/ @@ -777,22 +841,29 @@ nemotron embed eval -c default finetuned_model_path=/path/to/checkpoint ``` **Error: BEIR evaluation fails** + - **Solution**: Ensure eval_beir data was created in Stage 1 + - **Solution**: Check that corpus.jsonl and queries.jsonl exist ### Stage 4: Export Issues **Error: TensorRT export fails** + - **Solution**: Ensure using NGC container with TensorRT (nemo:25.07+) + - **Solution**: Try ONNX-only export first: `export_to_trt=false` **Error: ONNX export fails** + - **Solution**: Check model checkpoint is valid + - **Solution**: Ensure sufficient disk space ### Stage 5: Deployment Issues **Error: NIM container fails to start** + ```bash # Check NGC credentials docker login nvcr.io @@ -805,19 +876,24 @@ nemotron embed deploy -c default host_port=8002 ``` **Error: NIM accuracy differs from checkpoint** + - **Solution**: Ensure using same model format (TensorRT vs ONNX) + - **Solution**: Check quantization settings match + - **Solution**: Verify model files are complete and not corrupted ### CUDA Library Errors **Error: `nvJitLink` or CUDA symbol errors** + ```bash # Clear LD_LIBRARY_PATH to avoid conflicts export LD_LIBRARY_PATH="" ``` **Error: HybridCache import errors** + ```bash # Clear HuggingFace cache rm -rf ~/.cache/huggingface/modules/transformers_modules/nvidia/ @@ -826,6 +902,7 @@ rm -rf ~/.cache/huggingface/modules/transformers_modules/nvidia/ ### Docker Issues **Error: Container has no GPU access** + ```bash # Verify NVIDIA runtime is installed docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi @@ -837,6 +914,7 @@ cat /etc/docker/daemon.json ### Slurm Issues **Error: Job submission fails** + ```bash # Check Slurm is configured in env.toml cat env.toml @@ -849,15 +927,17 @@ sinfo -p interactive ``` **Error: Job stays in pending state** + ```bash # Check job queue squeue -u $USER # Check job reason -squeue -j -o "%.18i %.9P %.8j %.8u %.2t %.10M %.6D %R" +squeue -j \ -o "%.18i %.9P %.8j %.8u %.2t %.10M %.6D %R" ``` **Debugging Slurm jobs** + ```bash # Check job status squeue -u $USER @@ -867,15 +947,16 @@ cat /path/to/job/logs/stdout.txt cat /path/to/job/logs/stderr.txt # Cancel stuck job -scancel +scancel \ # View job details -scontrol show job +scontrol show job \ ``` ### General Debugging **Enable verbose logging** + ```bash # Add --verbose flag (if available) nemotron embed finetune -c default --verbose @@ -885,6 +966,7 @@ cat output/embed/stage2_finetune/logs/*.log ``` **Dry run to preview** + ```bash # Preview command without executing nemotron embed finetune -c default --dry-run @@ -907,16 +989,19 @@ Monitor training progress at: `https://wandb.ai//` ### Local Monitoring **Check training logs:** + ```bash tail -f output/embed/stage2_finetune/logs/train.log ``` **GPU utilization:** + ```bash watch -n 1 nvidia-smi ``` **Checkpoint progress:** + ```bash ls -lh output/embed/stage2_finetune/checkpoints/ ``` @@ -924,36 +1009,52 @@ ls -lh output/embed/stage2_finetune/checkpoints/ ## Best Practices ### Data Quality + - Use clean, well-formatted documents + - Ensure documents represent your target domain + - Aim for diverse document types and topics + - Start with small corpus to test pipeline, then scale up ### Training + - Start with default hyperparameters (1-2 epochs, LR 1e-5, batch size 128) + - Monitor validation metrics to avoid overfitting + - Attention implementation is auto-detected (flash_attention_2 if available, else sdpa) + - Checkpoint frequency: if `ckpt_every_steps` is omitted, defaults to once per epoch for map-style datasets or twice during training for iterable datasets **Key hyperparameters to tune:** | Parameter | Default | Notes | -| :---- | :---- | :---- | +| --- | --- | --- | | Epochs | 3 | **Default is tuned for the small example dataset; for real-world data, 1–2 epochs is usually sufficient.** 3 epochs risks overfitting on most datasets. See [epoch guidance in FAQ](#how-many-epochs-typically-improve-accuracy-before-overfitting-becomes-a-risk-is-there-a-rule-of-thumb). | | Learning rate | 1e-5 | Try double and half of the default value | | Learning rate warmup steps | 5 | Set to 5-10% of total steps of finetune to have better early training stability | -| Sequence length | 512 | Set `query_max_length` / `passage_max_length` consistently across Stages 1-3 (up to your base model's max sequence length). Increase `sentences_per_chunk` in Stage 0 accordingly. Longer sequences require reducing batch size. See [Customizing Sequence Length](#customizing-sequence-length). | +| Sequence length | 512 | Set query_max_length / passage_max_length consistently across Stages 1-3 (up to your base model’s max sequence length). Increase sentences_per_chunk in Stage 0 accordingly. Longer sequences require reducing batch size. See [Customizing Sequence Length](#customizing-sequence-length). | ### Evaluation + - Always compare against base model + - Test on held-out test set (not used in training) + - Evaluate on realistic queries from your domain + - Consider multiple metrics (nDCG, Recall, Precision) ### Deployment + - Test exported models thoroughly before production + - Verify NIM accuracy matches checkpoint + - Monitor inference latency and throughput + - Set up proper logging and monitoring ## FAQ @@ -979,12 +1080,12 @@ In addition, prompts can be tailored to the specific document type - bug vs tick There is no universal threshold — saturation depends on domain complexity, vocabulary diversity, and document heterogeneity. As a rough guide: | Corpus Size | Typical Outcome | -|-------------|-----------------| +| --- | --- | | 100+ docs | Basic domain adaptation | | 500-1000 docs | Good domain coverage for enterprise corpora | | 5000+ docs | Strong and reliable adaptation | -After SDG and quality filtering (default threshold 7.0), the effective training set is typically smaller than the raw doc count. Monitor Stage 3 eval metrics (nDCG@10, Recall@10) across runs with increasing data to find your domain's saturation point. +After SDG and quality filtering (default threshold 7.0), the effective training set is typically smaller than the raw doc count. Monitor Stage 3 eval metrics (nDCG@10, Recall@10) across runs with increasing data to find your domain’s saturation point. **How can we reliably detect saturation of the embedding model as we scale data volume?** @@ -1015,7 +1116,9 @@ Exact matching is ideal but approximate alignment is usually good enough. What m Hard-negative mining uses a margin-based filter to exclude documents that are too similar to the positive. The key parameter is `hard_neg_margin` (default: 0.95 with `perc` margin type), which acts as an exclusion ceiling: any document scoring *above* `min_positive_score * margin` is eliminated, and the top-k highest-scoring survivors become the hard negatives. To tune: - **Raise the margin** (e.g., 0.98–1.0) to narrow the exclusion zone, allowing negatives that score closer to the positive. This produces harder negatives that improve discrimination but risks including false negatives (relevant documents mislabeled as negative), especially in corpora with near-duplicate passages. + - **Lower the margin** (e.g., 0.85–0.90) to widen the exclusion zone, forcing negatives to be further from the positive score. This produces easier, safer negatives with less risk of false negatives, but provides weaker training signal. + - **Increase `hard_negatives_to_mine`** (default: 5) to give the model more contrastive examples per query. The training stage uses `train_n_passages` (default: 5, meaning 1 positive + 4 negatives), so mine at least as many as you plan to train with. Start with defaults and only raise the margin if Stage 3 metrics plateau — aggressive hard negatives on noisy data can hurt more than help. @@ -1031,21 +1134,24 @@ The default of 4 hard negatives per query (`train_n_passages: 5` = 1 positive + In order of typical impact: 1. **Learning rate** (default: 1e-5) — the single most sensitive parameter. Try 5e-6 and 2e-5 as first alternatives. Too high causes instability or NaN loss; too low undertrains. + 2. **Epochs** (default: 3) — controls how many passes the model makes over the data. The default of 3 is calibrated for the small example dataset in this recipe; **for most real-world datasets, 1–2 epochs is recommended** to avoid overfitting. See the epoch table below. + 3. **Learning rate warmup** (default: 5 steps) — set to 5–10% of total training steps for better early stability. + 4. **Batch size** (default: 128) — determines the number of gradient update steps per epoch. Use smaller values for small datasets to get more updates; see the [batch size FAQ](#how-does-batch-size-affect-training-and-how-should-it-be-set) below. **What learning-rate sweep strategy is recommended to maximize accuracy (e.g., halve/double defaults)?** -A simple three-point sweep around the default is the most cost-effective approach. Start with the default 1e-5, then try 5e-6 (half) and 2e-5 (double). Compare Stage 3 eval metrics (nDCG@10) across the three runs — the winner is usually obvious. If the best result is at an endpoint (e.g., 2e-5 beats both others), extend one more step in that direction (try 4e-5) to confirm you haven't undershot. Keep epochs and all other hyperparameters fixed during the sweep so that LR is the only variable. +A simple three-point sweep around the default is the most cost-effective approach. Start with the default 1e-5, then try 5e-6 (half) and 2e-5 (double). Compare Stage 3 eval metrics (nDCG@10) across the three runs — the winner is usually obvious. If the best result is at an endpoint (e.g., 2e-5 beats both others), extend one more step in that direction (try 4e-5) to confirm you haven’t undershot. Keep epochs and all other hyperparameters fixed during the sweep so that LR is the only variable. #### How many epochs typically improve accuracy before overfitting becomes a risk? Is there a rule of thumb? The default `num_epochs: 3` exists because the example dataset shipped with this recipe is very small and training for only 1–2 epochs may not produce a measurable signal. **For your own data, start with 1–2 epochs and only increase if evaluation metrics are still improving.** | Dataset Size | Recommended Epochs | Notes | -|--------------|--------------------|-------| -| Small (<1K examples) | 2–3 | Use 3 only if val loss is still decreasing | +| --- | --- | --- | +| Small (\<1K examples) | 2–3 | Use 3 only if val loss is still decreasing | | Medium (1K–10K examples) | 1–2 | 2 epochs is usually the upper bound | | Large (10K+ examples) | 1 | More than 1 epoch rarely helps and often hurts | @@ -1060,12 +1166,14 @@ As a rule of thumb, use a **smaller `global_batch_size` for small datasets** and **How should training loss and evaluation loss be interpreted to assess real accuracy gains?** - **Training loss** (contrastive/InfoNCE loss) measures how well the model separates positives from negatives in each batch. A steadily decreasing training loss is expected; a very low floor (~0.0–0.01) suggests the model has learned the training set well. + - **Validation loss** tracks the same metric on held-out data. The gap between training and validation loss is your primary overfitting indicator. If validation loss decreases alongside training loss, the model is generalizing. If validation loss plateaus or rises while training loss keeps falling, stop training or reduce epochs. -- **Neither loss directly equals retrieval accuracy.** Always rely on Stage 3 eval metrics (nDCG@k, Recall@k) as the ground truth for actual embedding quality. Loss is a proxy — it's possible for loss to improve while retrieval metrics stagnate if the hard negatives are too easy. + +- **Neither loss directly equals retrieval accuracy.** Always rely on Stage 3 eval metrics (nDCG@k, Recall@k) as the ground truth for actual embedding quality. Loss is a proxy — it’s possible for loss to improve while retrieval metrics stagnate if the hard negatives are too easy. **Are there target loss behaviors or patterns that indicate optimal embedding learning?** -Healthy training typically shows: (1) rapid loss decrease in the first 20–30% of training, (2) gradual flattening toward a stable floor, (3) validation loss tracking close to training loss throughout. Warning signs include loss spikes (often caused by bad data or LR too high), NaN loss (reduce LR or batch size), or loss that never decreases (LR too low, or data quality issues). There is no universal "target loss value" — the absolute number depends on batch size, number of negatives, and temperature. Focus on the trajectory and the train/val gap rather than the absolute value. +Healthy training typically shows: (1) rapid loss decrease in the first 20–30% of training, (2) gradual flattening toward a stable floor, (3) validation loss tracking close to training loss throughout. Warning signs include loss spikes (often caused by bad data or LR too high), NaN loss (reduce LR or batch size), or loss that never decreases (LR too low, or data quality issues). There is no universal “target loss value” — the absolute number depends on batch size, number of negatives, and temperature. Focus on the trajectory and the train/val gap rather than the absolute value. **Should a fixed evaluation dataset always be used to measure true accuracy gains across runs?** @@ -1077,20 +1185,28 @@ Aim for at least 100 queries in the evaluation set to get stable metric estimate **What level of accuracy improvement (relative vs absolute) is typical or expected from embedding fine-tuning in similar enterprise domains?** -Typical results on enterprise domains show **+5 to +20 absolute points of nDCG@10** over the base model, depending on how specialized the domain is. Domains with highly specialized vocabulary (legal, biomedical, internal engineering docs) tend to see larger gains because the base model has less prior exposure. Domains closer to general web text see smaller but still meaningful improvements. If you see less than 5 absolute points of nDCG@10 improvement, investigate data quality, SDG coverage, or hyperparameter settings before concluding that fine-tuning doesn't help your domain. +Typical results on enterprise domains show **+5 to +20 absolute points of nDCG@10** over the base model, depending on how specialized the domain is. Domains with highly specialized vocabulary (legal, biomedical, internal engineering docs) tend to see larger gains because the base model has less prior exposure. Domains closer to general web text see smaller but still meaningful improvements. If you see less than 5 absolute points of nDCG@10 improvement, investigate data quality, SDG coverage, or hyperparameter settings before concluding that fine-tuning doesn’t help your domain. ## Further Reading - [NeMo Data Designer](https://github.com/NVIDIA-NeMo/DataDesigner) - Synthetic data generation framework + - [Automodel](https://github.com/NVIDIA/NeMo-Automodel) - Model training framework + - [BEIR Benchmark](https://github.com/beir-cellar/beir) - Information retrieval evaluation + - [NVIDIA NIM Documentation](https://developer.nvidia.com/nim) - Production inference microservices + - [Llama-Nemotron-Embed-1B-v2 Model Card](https://huggingface.co/nvidia/llama-nemotron-embed-1b-v2) - Base model details + - [Retrieval-Synthetic-NVDocs-v1 Dataset](https://huggingface.co/datasets/nvidia/Retrieval-Synthetic-NVDocs-v1) - Pre-generated synthetic retrieval dataset on NVIDIA content ## Support For issues, questions, or contributions: + - **Issues**: [GitHub Issues](https://github.com/NVIDIA-NeMo/Nemotron/issues) + - **Discussions**: [GitHub Discussions](https://github.com/NVIDIA-NeMo/Nemotron/discussions) + - **Documentation**: [Nemotron Documentation](https://docs.nvidia.com/nemotron/latest) diff --git a/docs/nemotron/kit.md b/docs/fern/pages-vnightly/nemotron/kit.mdx similarity index 54% rename from docs/nemotron/kit.md rename to docs/fern/pages-vnightly/nemotron/kit.mdx index 025026f48..6c0baac1d 100644 --- a/docs/nemotron/kit.md +++ b/docs/fern/pages-vnightly/nemotron/kit.mdx @@ -1,20 +1,24 @@ -# Nemotron Kit +--- +title: "Nemotron Kit" +slug: "nemotron/kit.html" +description: "The nemotron.kit module provides artifact type definitions, lineage trackers, and W&B integration for Nemotron training recipes." +--- The `nemotron.kit` module provides artifact type definitions, lineage trackers, and W&B integration for Nemotron training recipes. -> **Focused by Design**: Kit owns the artifact *types* (data classes like `PretrainBlendsArtifact`, `ModelArtifact`) and *tracking behavior* (W&B/file-based lineage). The underlying artifact *registry* and *resolution* (`art://` URIs, fsspec/wandb storage backends) live in [`nemo_runspec`](../nemo_runspec/package-readme). CLI, configuration, and execution also live in `nemo_runspec`. All heavy-lifting training is done by the [NVIDIA AI Stack](./nvidia-stack.md): [Megatron-Core](https://github.com/NVIDIA/Megatron-LM) for distributed training primitives, [Megatron-Bridge](https://github.com/NVIDIA-NeMo/Megatron-Bridge) for model training, and [NeMo-RL](https://github.com/NVIDIA/NeMo-RL) for reinforcement learning. +> **Focused by Design**: Kit owns the artifact *types* (data classes like `PretrainBlendsArtifact`, `ModelArtifact`) and *tracking behavior* (W&B/file-based lineage). The underlying artifact *registry* and *resolution* (`art://` URIs, fsspec/wandb storage backends) live in [`nemo_runspec`](/../nemo_runspec/package-readme). CLI, configuration, and execution also live in `nemo_runspec`. All heavy-lifting training is done by the [NVIDIA AI Stack](/nvidia-stack): [Megatron-Core](https://github.com/NVIDIA/Megatron-LM) for distributed training primitives, [Megatron-Bridge](https://github.com/NVIDIA-NeMo/Megatron-Bridge) for model training, and [NeMo-RL](https://github.com/NVIDIA/NeMo-RL) for reinforcement learning. ## Overview Kit handles three core responsibilities: | Component | What kit owns | What nemo_runspec owns | -|-----------|--------------|----------------------| -| **[Artifacts](./artifacts.md)** | Type definitions (`PretrainBlendsArtifact`, `ModelArtifact`, etc.) | Registry, `art://` resolution, fsspec/wandb storage backends | -| **[Lineage Tracking](./artifacts.md)** | Trackers (`WandbTracker`, `FileTracker`) | `${art:...}` OmegaConf resolvers, distributed coordination | -| **[W&B Integration](./wandb.md)** | Init, credential handling, monkey patches, tag management | Env var injection (`build_env_vars`), `[wandb]` config loading | +| --- | --- | --- | +| **[Artifacts](/artifacts)** | Type definitions (PretrainBlendsArtifact, ModelArtifact, etc.) | Registry, art:// resolution, fsspec/wandb storage backends | +| **[Lineage Tracking](/artifacts)** | Trackers (WandbTracker, FileTracker) | ${art:...} OmegaConf resolvers, distributed coordination | +| **[W&B Integration](/wandb)** | Init, credential handling, monkey patches, tag management | Env var injection (build_env_vars), [wandb] config loading | -For CLI infrastructure, config loading, execution, and packaging, see [`nemo_runspec`](../nemo_runspec/package-readme). +For CLI infrastructure, config loading, execution, and packaging, see [`nemo_runspec`](/../nemo_runspec/package-readme). ## Architecture @@ -91,7 +95,7 @@ model.save(name="ModelArtifact-pretrain") ### Artifacts -Artifacts are path-centric objects with typed metadata. The core field is always `path` -- the filesystem location of the data. See [Artifact Lineage](./artifacts.md) for details. +Artifacts are path-centric objects with typed metadata. The core field is always `path` – the filesystem location of the data. See [Artifact Lineage](/artifacts) for details. ```python from nemotron.kit import PretrainBlendsArtifact @@ -104,7 +108,7 @@ print(f"Tokens: {artifact.total_tokens:,}") ### Lineage Tracking -Kit tracks artifact lineage through pluggable backends. The `WandbTracker` logs to W&B; the `FileTracker` writes to local filesystem. See [W&B Integration](./wandb.md) for credential handling and [Artifact Lineage](./artifacts.md) for the lineage graph. +Kit tracks artifact lineage through pluggable backends. The `WandbTracker` logs to W&B; the `FileTracker` writes to local filesystem. See [W&B Integration](/wandb) for credential handling and [Artifact Lineage](/artifacts) for the lineage graph. ```python from nemotron.kit import set_lineage_tracker, WandbTracker @@ -128,7 +132,7 @@ add_run_tags(["pretrain", "nano3"]) ## Module Structure -``` +```default src/nemotron/kit/ ├── __init__.py # Public API exports + kit.init() ├── artifact.py # Artifact base class, ArtifactInput, display helpers @@ -145,51 +149,58 @@ src/nemotron/kit/ ### Artifacts | Export | Description | -|--------|-------------| -| `Artifact` | Base artifact class | -| `PretrainBlendsArtifact` | Pretrain data with train/valid/test splits | -| `PretrainDataArtifact` | Raw pretrain data | -| `SFTDataArtifact` | Packed SFT sequences | -| `SplitJsonlDataArtifact` | RL JSONL data | -| `DataBlendsArtifact` | Generic data blends | -| `ModelArtifact` | Model checkpoints | -| `TrackingInfo` | Tracking metadata for artifacts | +| --- | --- | +| Artifact | Base artifact class | +| PretrainBlendsArtifact | Pretrain data with train/valid/test splits | +| PretrainDataArtifact | Raw pretrain data | +| SFTDataArtifact | Packed SFT sequences | +| SplitJsonlDataArtifact | RL JSONL data | +| DataBlendsArtifact | Generic data blends | +| ModelArtifact | Model checkpoints | +| TrackingInfo | Tracking metadata for artifacts | ### Tracking | Export | Description | -|--------|-------------| -| `LineageTracker` | Abstract base for lineage tracking | -| `WandbTracker` | W&B-backed lineage tracker | -| `FileTracker` | File-based lineage tracker | -| `NoOpTracker` | No-op tracker (for testing) | -| `set_lineage_tracker()` | Set the global lineage tracker | -| `get_lineage_tracker()` | Get the current lineage tracker | -| `to_wandb_uri()` | Convert artifact to W&B URI | -| `tokenizer_to_uri()` | Convert tokenizer to URI | +| --- | --- | +| LineageTracker | Abstract base for lineage tracking | +| WandbTracker | W&B-backed lineage tracker | +| FileTracker | File-based lineage tracker | +| NoOpTracker | No-op tracker (for testing) | +| set_lineage_tracker() | Set the global lineage tracker | +| get_lineage_tracker() | Get the current lineage tracker | +| to_wandb_uri() | Convert artifact to W&B URI | +| tokenizer_to_uri() | Convert tokenizer to URI | ### W&B | Export | Description | -|--------|-------------| -| `WandbConfig` | W&B configuration dataclass | -| `init_wandb_if_configured()` | Conditional W&B initialization | -| `add_run_tags()` | Add tags to W&B runs | +| --- | --- | +| WandbConfig | W&B configuration dataclass | +| init_wandb_if_configured() | Conditional W&B initialization | +| add_run_tags() | Add tags to W&B runs | ### Kit Initialization | Export | Description | -|--------|-------------| -| `init()` | Initialize kit with storage backend (fsspec or wandb) | -| `is_initialized()` | Check if kit has been initialized | +| --- | --- | +| init() | Initialize kit with storage backend (fsspec or wandb) | +| is_initialized() | Check if kit has been initialized | ## Further Reading -- [`nemo_runspec` Package](../nemo_runspec/package-readme) – CLI toolkit, config loading, execution, packaging -- [NVIDIA AI Stack](./nvidia-stack.md) – Megatron-Core, Megatron-Bridge, NeMo-RL -- [OmegaConf Configuration](../nemo_runspec/omegaconf.md) – artifact interpolations and unified W&B logging -- [Artifact Lineage](./artifacts.md) – artifact versioning and W&B lineage -- [W&B Integration](./wandb.md) – credential handling -- [Execution through NeMo-Run](../nemo_runspec/nemo-run.md) – execution profiles and packagers -- [CLI Framework](./cli.md) – building recipe CLIs -- [Data Preparation](./data-prep.md) – data prep module +- [`nemo_runspec` Package](/../nemo_runspec/package-readme) – CLI toolkit, config loading, execution, packaging + +- [NVIDIA AI Stack](/nvidia-stack) – Megatron-Core, Megatron-Bridge, NeMo-RL + +- [OmegaConf Configuration](/../nemo_runspec/omegaconf) – artifact interpolations and unified W&B logging + +- [Artifact Lineage](/artifacts) – artifact versioning and W&B lineage + +- [W&B Integration](/wandb) – credential handling + +- [Execution through NeMo-Run](/../nemo_runspec/nemo-run) – execution profiles and packagers + +- [CLI Framework](/cli) – building recipe CLIs + +- [Data Preparation](/data-prep) – data prep module diff --git a/docs/nemotron/nano3/README.md b/docs/fern/pages-vnightly/nemotron/nano3/README.mdx similarity index 79% rename from docs/nemotron/nano3/README.md rename to docs/fern/pages-vnightly/nemotron/nano3/README.mdx index 50316081d..31e0b2290 100644 --- a/docs/nemotron/nano3/README.md +++ b/docs/fern/pages-vnightly/nemotron/nano3/README.mdx @@ -1,4 +1,8 @@ -# Nemotron 3 Nano Training Recipe +--- +title: "Nemotron 3 Nano Training Recipe" +slug: "nemotron/nano3/README.html" +description: "Reproducible training pipeline for Nemotron 3 Nano, an open Mixture-of-Experts hybrid Mamba-Transformer model optimized for agentic reasoning." +--- Reproducible training pipeline for Nemotron 3 Nano, an open Mixture-of-Experts hybrid Mamba-Transformer model optimized for agentic reasoning. @@ -6,11 +10,15 @@ Reproducible training pipeline for Nemotron 3 Nano, an open Mixture-of-Experts h ### Prerequisites -- **Slurm cluster** with GPU nodes (H100 recommended). See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) -- **[Weights & Biases](../wandb.md) account** for experiment tracking and [artifact lineage](../artifacts.md) +- **Slurm cluster** with GPU nodes (H100 recommended). See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) + +- **[Weights & Biases](/../wandb) account** for experiment tracking and [artifact lineage](/../artifacts) + - **Container images**: - - Training: `nvcr.io/nvidia/nemo:25.11.nemotron_3_nano` - - RL: `nvcr.io/nvidia/nemo-rl:v0.4.0.nemotron_3_nano` + + - Training: `nvcr.io/nvidia/nemo:25.11.nemotron_3_nano` + + - RL: `nvcr.io/nvidia/nemo-rl:v0.4.0.nemotron_3_nano` ### Installation @@ -22,7 +30,7 @@ uv sync ### Configuration -Create an `env.toml` file (see [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for details): +Create an `env.toml` file (see [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for details): ```toml [wandb] @@ -42,7 +50,6 @@ mounts = ["/lustre:/lustre"] ### Run the Pipeline
- ```console // Stage 0: Pretraining $ uv run nemotron nano3 data prep pretrain --run YOUR-CLUSTER @@ -61,40 +68,46 @@ $ uv run nemotron nano3 pipe --run YOUR-CLUSTER ```
- > **Note**: The `pipe` command composes pretrain → SFT into a single nemo-run Experiment for coordinated remote execution. RL uses Ray and must be run separately. ## Resources - **Tech Report:** [Nemotron 3 Nano Technical Report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf) + - **Model Weights:** - - [NVIDIA-Nemotron-3-Nano-30B-A3B-Base-BF16](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-Base-BF16) (Base model) - - [NVIDIA-Nemotron-3-Nano-30B-A3B-BF16](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16) (Instruct model) - - [NVIDIA-Nemotron-3-Nano-30B-A3B-FP8](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8) (FP8 quantized) + + - [NVIDIA-Nemotron-3-Nano-30B-A3B-Base-BF16](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-Base-BF16) (Base model) + + - [NVIDIA-Nemotron-3-Nano-30B-A3B-BF16](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16) (Instruct model) + + - [NVIDIA-Nemotron-3-Nano-30B-A3B-FP8](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8) (FP8 quantized) + - **Model Collection:** [NVIDIA Nemotron v3 Collection](https://huggingface.co/collections/nvidia/nvidia-nemotron-v3) + - **Training Datasets:** - - [Pre-training Datasets](https://huggingface.co/collections/nvidia/nemotron-pre-training-datasets) (Open pre-training data) - - [Post-training Datasets](https://huggingface.co/collections/nvidia/nemotron-post-training-v3) (SFT and RL data) - + - [Pre-training Datasets](https://huggingface.co/collections/nvidia/nemotron-pre-training-datasets) (Open pre-training data) + + - [Post-training Datasets](https://huggingface.co/collections/nvidia/nemotron-post-training-v3) (SFT and RL data) + +{/* TODO - move whatever customization docs for Nano 3 to this section of the docs. +```{seealso\} +For model cards, technical report chunks, and recipe summaries, see {doc\}`/customize/models/nano3/index`. +``` */} ## Training Pipeline | Stage | Name | Purpose | Guide | -|-------|------|---------|-------| -| 0 | [Pretraining](./pretrain.md) | Base model on 25T tokens with curriculum learning | [pretrain.md](./pretrain.md) | -| 1 | [SFT](./sft.md) | Multi-domain instruction tuning with 12+ data sources | [sft.md](./sft.md) | -| 2 | [RL](./rl.md) | GRPO alignment with multi-environment rewards | [rl.md](./rl.md) | -| 3 | [Evaluation](./evaluate.md) | Benchmark evaluation with NeMo Evaluator | [evaluate.md](./evaluate.md) | +| --- | --- | --- | --- | +| 0 | [Pretraining](/pretrain) | Base model on 25T tokens with curriculum learning | [pretrain.md](/pretrain) | +| 1 | [SFT](/sft) | Multi-domain instruction tuning with 12+ data sources | [sft.md](/sft) | +| 2 | [RL](/rl) | GRPO alignment with multi-environment rewards | [rl.md](/rl) | +| 3 | [Evaluation](/evaluate) | Benchmark evaluation with NeMo Evaluator | [evaluate.md](/evaluate) | ## Model Specifications | Specification | Value | -|---------------|-------| +| --- | --- | | **Total Parameters** | 31.6B | | **Active Parameters** | 3.6B (per forward pass) | | **Pretraining Tokens** | 25 trillion | @@ -109,35 +122,35 @@ For model cards, technical report chunks, and recipe summaries, see {doc}`/custo Two-phase curriculum on 25 trillion tokens: Phase 1 (23.5T) focuses on diversity across web, code, math, and multilingual data; Phase 2 (1.5T) emphasizes high-quality sources. Includes long-context extension to 1M tokens. -→ [Pretraining Guide](./pretrain.md) +→ [Pretraining Guide](/pretrain) ### Stage 1: Supervised Fine-Tuning Multi-domain instruction tuning covering 12+ data domains including competition math/code, InfinityByte cross-domain synthesis, STEM reasoning, conversational tool use, and multilingual support. -→ [SFT Guide](./sft.md) +→ [SFT Guide](/sft) ### Stage 2: Reinforcement Learning Multi-environment RLVR training across 7 reward environments using GRPO, plus GenRM-based RLHF and DPO for reducing tool hallucination. -→ [RL Guide](./rl.md) +→ [RL Guide](/rl) ## Execution Options -All commands support [NeMo-Run](../../nemo_runspec/nemo-run.md) execution modes: +All commands support [NeMo-Run](/../../nemo_runspec/nemo-run) execution modes: | Option | Behavior | Use Case | -|--------|----------|----------| -| `--run ` | Attached—submits job and streams logs | Interactive development | -| `--batch ` | Detached—submits and exits immediately | Long-running jobs | -| `--dry-run` | Preview execution plan | Validation | +| --- | --- | --- | +| --run <profile> | Attached—submits job and streams logs | Interactive development | +| --batch <profile> | Detached—submits and exits immediately | Long-running jobs | +| --dry-run | Preview execution plan | Validation | -See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for profile configuration and advanced options. +See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for profile configuration and advanced options. ## Artifact Lineage -The pipeline tracks lineage via [W&B Artifacts](../artifacts.md), so you can trace any model back to the data it was trained on. +The pipeline tracks lineage via [W&B Artifacts](/../artifacts), so you can trace any model back to the data it was trained on. ```mermaid %%{init: {'theme': 'base', 'themeVariables': { 'primaryBorderColor': '#333333', 'lineColor': '#333333', 'primaryTextColor': '#333333', 'clusterBkg': '#ffffff', 'clusterBorder': '#333333'}}}%% @@ -165,7 +178,7 @@ flowchart TB style rl fill:#e8f5e9,stroke:#4caf50 ``` -→ [Artifact Lineage & W&B Integration](../artifacts.md) +→ [Artifact Lineage & W&B Integration](/../artifacts) ## Open-Source Data @@ -173,10 +186,10 @@ flowchart TB ## Coming Soon -Native integrations with NVIDIA's NeMo ecosystem: +Native integrations with NVIDIA’s NeMo ecosystem: | Tool | Description | Status | -|------|-------------|--------| +| --- | --- | --- | | [NeMo Curator](https://github.com/NVIDIA-NeMo/Curator) | Data curation: deduplication, quality filtering, PII removal | Planned | | [NeMo Data Designer](https://github.com/NVIDIA-NeMo/DataDesigner) | Synthetic data generation for instruction tuning and alignment | Planned | | [NeMo Export-Deploy](https://github.com/NVIDIA-NeMo/Export-Deploy) | Model export to TensorRT-LLM and deployment | Planned | @@ -187,7 +200,6 @@ These integrations will connect data curation directly to model evaluation. ## CLI Reference
- ```console // Show available commands $ uv run nemotron nano3 --help @@ -256,38 +268,38 @@ Usage: nemotron nano3 sft [OPTIONS] ```
- ## Troubleshooting -**W&B authentication**: See [W&B Integration](../wandb.md) for setup. +**W&B authentication**: See [W&B Integration](/../wandb) for setup. + ```bash wandb login ``` **Container not found**: Verify image path in config files. -**Job submission fails**: Check Slurm account and partition in `env.toml`. See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md). +**Job submission fails**: Check Slurm account and partition in `env.toml`. See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run). ## Further Reading -- [Stage 0: Pretraining](./pretrain.md) -- [Stage 1: SFT](./sft.md) -- [Stage 2: RL](./rl.md) -- [Stage 3: Evaluation](./evaluate.md) -- [Importing Models & Data](./import.md) -- [Artifact Lineage](../artifacts.md) -- [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) -- [W&B Integration](../wandb.md) -- [NVIDIA AI Stack](../nvidia-stack.md) -- [CLI Framework](../cli.md) -- [Data Preparation Module](../data-prep.md) - -```{toctree} -:hidden: - -pretrain.md -sft.md -rl.md -evaluate.md -import.md -``` +- [Stage 0: Pretraining](/pretrain) + +- [Stage 1: SFT](/sft) + +- [Stage 2: RL](/rl) + +- [Stage 3: Evaluation](/evaluate) + +- [Importing Models & Data](/import) + +- [Artifact Lineage](/../artifacts) + +- [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) + +- [W&B Integration](/../wandb) + +- [NVIDIA AI Stack](/../nvidia-stack) + +- [CLI Framework](/../cli) + +- [Data Preparation Module](/../data-prep) diff --git a/docs/nemotron/nano3/evaluate.md b/docs/fern/pages-vnightly/nemotron/nano3/evaluate.mdx similarity index 75% rename from docs/nemotron/nano3/evaluate.md rename to docs/fern/pages-vnightly/nemotron/nano3/evaluate.mdx index 34ef60af4..9bb89d2c2 100644 --- a/docs/nemotron/nano3/evaluate.md +++ b/docs/fern/pages-vnightly/nemotron/nano3/evaluate.mdx @@ -1,4 +1,8 @@ -# Stage 3: Evaluation +--- +title: "Stage 3: Evaluation" +slug: "nemotron/nano3/evaluate.html" +description: "Evaluate trained Nemotron Nano 3 models against standard benchmarks using NeMo Evaluator." +--- Evaluate trained Nemotron Nano 3 models against standard benchmarks using [NeMo Evaluator](https://github.com/NVIDIA-NeMo/Evaluator). @@ -8,7 +12,7 @@ Evaluate trained Nemotron Nano 3 models against standard benchmarks using [NeMo ## How Evaluation Works -The eval command resolves model artifacts from W&B lineage and uses NeMo Framework's Ray-based in-framework deployment. It defaults to evaluating the latest RL stage output. +The eval command resolves model artifacts from W&B lineage and uses NeMo Framework’s Ray-based in-framework deployment. It defaults to evaluating the latest RL stage output. ```mermaid %%{init: {'theme': 'base', 'themeVariables': { 'primaryBorderColor': '#333333', 'lineColor': '#333333', 'primaryTextColor': '#333333'}}}%% @@ -35,20 +39,28 @@ flowchart TB The CLI performs several transformations on the YAML config before passing it to the launcher: 1. **Load** the YAML config via OmegaConf (with Hydra defaults resolution) + 2. **Merge** env.toml profile values and CLI dotlist overrides + 3. **Auto-inject** W&B credential mappings if W&B export is configured + 4. **Auto-squash** container images for Slurm (converts Docker images to `.sqsh` files) -5. **Strip** the `run` section and resolve all `${run.*}` interpolations -6. **Resolve** artifact references (`${art:model,path}`) via W&B Artifacts -7. **Pass** the cleaned config to `nemo-evaluator-launcher`'s `run_eval()` + +5. **Strip** the `run` section and resolve all `$\{run.*\}` interpolations + +6. **Resolve** artifact references (`$\{art:model,path\}`) via W&B Artifacts + +7. **Pass** the cleaned config to `nemo-evaluator-launcher`’s `run_eval()` Two YAML files are saved for provenance: + - `job.yaml` — full config including `run` section (for reproducibility) + - `eval.yaml` — compiled config as seen by the launcher ### Deployment -The default config uses NeMo Framework's Ray-based in-framework deployment (`type: generic`) with a custom command for serving: +The default config uses NeMo Framework’s Ray-based in-framework deployment (`type: generic`) with a custom command for serving: ```yaml deployment: @@ -69,11 +81,11 @@ deployment: Parallelism settings are tuned for the Nano3 30B MoE model: | Setting | Value | Purpose | -|---------|-------|---------| -| `tensor_model_parallel_size` | 2 | Tensor parallelism across GPUs | -| `expert_model_parallel_size` | 8 | Expert parallelism for MoE layers | -| `num_gpus` | 8 | Total GPUs per node | -| `port` | 1235 | Ray serving port | +| --- | --- | --- | +| tensor_model_parallel_size | 2 | Tensor parallelism across GPUs | +| expert_model_parallel_size | 8 | Expert parallelism for MoE layers | +| num_gpus | 8 | Total GPUs per node | +| port | 1235 | Ray serving port | The model is deployed using the same NeMo Megatron container as training (`nvcr.io/nvidia/nemo:25.11.nemotron_3_nano`); nemo-evaluator-launcher pulls its own containers for evaluation tasks. @@ -98,12 +110,12 @@ evaluation: The default config includes five standard benchmarks: | Task | Type | Description | -|------|------|-------------| -| `adlr_mmlu` | Text Generation | Massive Multitask Language Understanding | -| `adlr_arc_challenge_llama_25_shot` | Log Probability | ARC Challenge with 25-shot prompting | -| `adlr_winogrande_5_shot` | Log Probability | Winogrande commonsense reasoning | -| `hellaswag` | Log Probability | Commonsense sentence completion | -| `openbookqa` | Log Probability | Open-domain science questions | +| --- | --- | --- | +| adlr_mmlu | Text Generation | Massive Multitask Language Understanding | +| adlr_arc_challenge_llama_25_shot | Log Probability | ARC Challenge with 25-shot prompting | +| adlr_winogrande_5_shot | Log Probability | Winogrande commonsense reasoning | +| hellaswag | Log Probability | Commonsense sentence completion | +| openbookqa | Log Probability | Open-domain science questions | To discover additional tasks: `nemo-evaluator-launcher ls tasks` @@ -114,7 +126,6 @@ To discover additional tasks: `nemo-evaluator-launcher ls tasks` ### Quick Start
- ```console // Evaluate the latest RL model from the pipeline $ uv run nemotron nano3 eval --run YOUR-CLUSTER @@ -130,21 +141,23 @@ $ uv run nemotron nano3 eval --dry-run ```
- -> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](../../nemo_runspec/nemo-run.md). See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for setup. +> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](/../../nemo_runspec/nemo-run). See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for setup. ### Prerequisites - **[NeMo Evaluator](https://github.com/NVIDIA-NeMo/Evaluator)**: Install with `pip install "nemotron[evaluator]"` or ensure `nemo-evaluator-launcher` is available + - **Container image**: `nvcr.io/nvidia/nemo:25.11.nemotron_3_nano` (NeMo Megatron container for model serving) -- **[Weights & Biases](../wandb.md)**: For result export (optional but recommended) + +- **[Weights & Biases](/../wandb)**: For result export (optional but recommended) + - **Slurm cluster**: For remote execution ### Configuration | File | Purpose | -|------|---------| -| `config/default.yaml` | Evaluation config with NeMo Ray deployment and benchmark tasks | +| --- | --- | +| config/default.yaml | Evaluation config with NeMo Ray deployment and benchmark tasks | The config has five sections: @@ -201,16 +214,16 @@ export: ``` | Section | Purpose | Passed to Launcher? | -|---------|---------|:-------------------:| -| `run` | env.toml injection, artifact references | No (stripped) | -| `execution` | Where to run, auto-export, mounts | Yes | -| `deployment` | How to serve the model | Yes | -| `evaluation` | Tasks and evaluation parameters | Yes | -| `export` | Result destinations (W&B) | Yes | +| --- | --- | --- | +| run | env.toml injection, artifact references | No (stripped) | +| execution | Where to run, auto-export, mounts | Yes | +| deployment | How to serve the model | Yes | +| evaluation | Tasks and evaluation parameters | Yes | +| export | Result destinations (W&B) | Yes | ### Artifact Resolution -The default config uses `${art:model,path}` for the model checkpoint: +The default config uses `$\{art:model,path\}` for the model checkpoint: ```yaml run: @@ -274,17 +287,19 @@ gpus_per_node = 8 mounts = ["/lustre:/lustre"] ``` -See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for complete configuration options. +See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for complete configuration options. ### W&B Integration Results are automatically exported to W&B when configured: 1. **Auto-detection**: The CLI detects your local `wandb login` and propagates `WANDB_API_KEY` to evaluation containers + 2. **env.toml config**: `WANDB_PROJECT` and `WANDB_ENTITY` are loaded from `env.toml` + 3. **Auto-export**: Results are exported after evaluation completes when `execution.auto_export.destinations` includes `wandb` -See [W&B Integration](../wandb.md) for setup. +See [W&B Integration](/../wandb) for setup. ### Artifact Lineage @@ -305,7 +320,7 @@ flowchart TB style results fill:#e8f5e9,stroke:#4caf50 ``` -> [Artifact Lineage & W&B Integration](../artifacts.md) +> [Artifact Lineage & W&B Integration](/../artifacts) --- @@ -314,13 +329,13 @@ flowchart TB This stage uses the following components: | Component | Role | Documentation | -|-----------|------|---------------| +| --- | --- | --- | | [NeMo Evaluator](https://github.com/NVIDIA-NeMo/Evaluator) | Benchmark evaluation framework and launcher | [GitHub](https://github.com/NVIDIA-NeMo/Evaluator) | -| [NeMo Framework](../nvidia-stack.md) | Ray-based in-framework model deployment | [Docs](https://docs.nvidia.com/nemo/) | +| [NeMo Framework](/../nvidia-stack) | Ray-based in-framework model deployment | [Docs](https://docs.nvidia.com/nemo/) | ### Container -``` +```default nvcr.io/nvidia/nemo:25.11.nemotron_3_nano ``` @@ -329,7 +344,6 @@ The NeMo Megatron container is used for model serving. The nemo-evaluator-launch ## CLI Reference
- ```console $ uv run nemotron nano3 eval --help Usage: nemotron nano3 eval [OPTIONS] @@ -355,24 +369,29 @@ Usage: nemotron nano3 eval [OPTIONS] ## Troubleshooting | Problem | Solution | -|---------|----------| -| `nemo-evaluator-launcher` not found | Install with `pip install "nemotron[evaluator]"` | -| W&B authentication fails | Run `wandb login`. See [W&B Integration](../wandb.md) | +| --- | --- | +| nemo-evaluator-launcher not found | Install with pip install "nemotron[evaluator]" | +| W&B authentication fails | Run wandb login. See [W&B Integration](/../wandb) | | Model deployment fails | Check parallelism settings match GPU config (TP=2, EP=8 for Nano3) | -| Artifact resolution fails | Verify artifact exists in W&B. Use `deployment.checkpoint_path=/explicit/path` to bypass | -| Task not found | List available tasks with `nemo-evaluator-launcher ls tasks` | +| Artifact resolution fails | Verify artifact exists in W&B. Use deployment.checkpoint_path=/explicit/path to bypass | +| Task not found | List available tasks with nemo-evaluator-launcher ls tasks | --- ## Previous Stage -After RL completes in [Stage 2: RL](./rl.md), evaluation is the final step in the pipeline. +After RL completes in [Stage 2: RL](/rl), evaluation is the final step in the pipeline. ## Reference -- [NeMo Evaluator](https://github.com/NVIDIA-NeMo/Evaluator) -- Upstream evaluation framework -- [Artifact Lineage](../artifacts.md) -- W&B artifact system -- [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) -- Cluster configuration -- [W&B Integration](../wandb.md) -- Credentials and export setup +- [NeMo Evaluator](https://github.com/NVIDIA-NeMo/Evaluator) – Upstream evaluation framework + +- [Artifact Lineage](/../artifacts) – W&B artifact system + +- [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) – Cluster configuration + +- [W&B Integration](/../wandb) – Credentials and export setup + - **Recipe Source:** `src/nemotron/recipes/nano3/stage3_eval/` -- [Back to Overview](./README.md) + +- [Back to Overview](/README) diff --git a/docs/nemotron/nano3/import.md b/docs/fern/pages-vnightly/nemotron/nano3/import.mdx similarity index 68% rename from docs/nemotron/nano3/import.md rename to docs/fern/pages-vnightly/nemotron/nano3/import.mdx index 023d7aba4..d7235c2f6 100644 --- a/docs/nemotron/nano3/import.md +++ b/docs/fern/pages-vnightly/nemotron/nano3/import.mdx @@ -1,24 +1,32 @@ -# Importing Models and Data +--- +title: "Importing Models and Data" +slug: "nemotron/nano3/import.html" +description: "This guide covers how to import existing models and data as W&B artifacts using the nemotron CLI. This is useful when you want to:" +--- -This guide covers how to import existing models and data as [W&B artifacts](../artifacts.md) using the nemotron CLI. This is useful when you want to: +This guide covers how to import existing models and data as [W&B artifacts](/../artifacts) using the nemotron CLI. This is useful when you want to: - Use a pre-existing checkpoint from another training run + - Import data prepared outside of the standard pipeline -- Connect external assets to the [W&B artifact lineage](../artifacts.md) system + +- Connect external assets to the [W&B artifact lineage](/../artifacts) system ## Prerequisites -- [W&B](../wandb.md) configuration in `env.toml` (see [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md)): +- [W&B](/../wandb) configuration in `env.toml` (see [Execution through NeMo-Run](/../../nemo_runspec/nemo-run)): + ```toml [wandb] project = "nemotron" entity = "YOUR-TEAM" ``` + - Or provide `--project` and `--entity` CLI flags ## Model Import -Import model checkpoints as [W&B artifacts](../artifacts.md) for use in downstream training stages. +Import model checkpoints as [W&B artifacts](/../artifacts) for use in downstream training stages. ### Commands @@ -36,11 +44,11 @@ uv run nemotron nano3 model import rl /path/to/model_dir --step 2000 ### Options | Option | Description | -|--------|-------------| -| `--step, -s` | Training step number (optional) | -| `--name, -n` | Custom artifact name (default: `nano3//model`) | -| `--project, -p` | W&B project (overrides env.toml) | -| `--entity, -e` | W&B entity (overrides env.toml) | +| --- | --- | +| --step, -s | Training step number (optional) | +| --name, -n | Custom artifact name (default: nano3/<stage>/model) | +| --project, -p | W&B project (overrides env.toml) | +| --entity, -e | W&B entity (overrides env.toml) | ### Examples @@ -54,7 +62,7 @@ uv run nemotron nano3 model import sft /path/to/sft_checkpoint --project other-p ## Data Import -Import data directories as [W&B artifacts](../artifacts.md) for use in training stages. +Import data directories as [W&B artifacts](/../artifacts) for use in training stages. ### Commands @@ -72,12 +80,14 @@ uv run nemotron nano3 data import rl /path/to/rl_data_dir ### Expected Directory Structures **Pretrain**: Direct path to `blend.json` file -``` + +```default /path/to/blend.json ``` **SFT**: Directory containing `blend.json` and split subdirectories -``` + +```default /path/to/sft_data_dir/ ├── blend.json ├── splits/ @@ -91,7 +101,8 @@ uv run nemotron nano3 data import rl /path/to/rl_data_dir ``` **RL**: Directory containing `manifest.json` -``` + +```default /path/to/rl_data_dir/ ├── manifest.json ├── train.jsonl # or path referenced in manifest.json @@ -102,10 +113,10 @@ uv run nemotron nano3 data import rl /path/to/rl_data_dir ### Options | Option | Description | -|--------|-------------| -| `--name, -n` | Custom artifact name (default: `nano3//data`) | -| `--project, -p` | W&B project (overrides env.toml) | -| `--entity, -e` | W&B entity (overrides env.toml) | +| --- | --- | +| --name, -n | Custom artifact name (default: nano3/<stage>/data) | +| --project, -p | W&B project (overrides env.toml) | +| --entity, -e | W&B entity (overrides env.toml) | ### Examples @@ -127,7 +138,7 @@ Runs model evaluation using [NeMo Evaluator](https://github.com/NVIDIA-NeMo/Eval ## Using Imported Artifacts -After importing, [artifacts](../artifacts.md) can be referenced in training commands via dotlist overrides (see [CLI Framework](../cli.md#artifact-resolution)): +After importing, [artifacts](/../artifacts) can be referenced in training commands via dotlist overrides (see [CLI Framework](/../cli#artifact-resolution)): ```bash # Use imported model in SFT training @@ -161,7 +172,10 @@ uv run nemotron nano3 data import rl --help ## Further Reading -- [Artifact Lineage](../artifacts.md) – W&B artifact system -- [W&B Integration](../wandb.md) – credentials and configuration -- [CLI Framework](../cli.md) – CLI documentation -- [Back to Overview](./README.md) +- [Artifact Lineage](/../artifacts) – W&B artifact system + +- [W&B Integration](/../wandb) – credentials and configuration + +- [CLI Framework](/../cli) – CLI documentation + +- [Back to Overview](/README) diff --git a/docs/nemotron/nano3/pretrain.md b/docs/fern/pages-vnightly/nemotron/nano3/pretrain.mdx similarity index 75% rename from docs/nemotron/nano3/pretrain.md rename to docs/fern/pages-vnightly/nemotron/nano3/pretrain.mdx index a07477af7..faac39a60 100644 --- a/docs/nemotron/nano3/pretrain.md +++ b/docs/fern/pages-vnightly/nemotron/nano3/pretrain.mdx @@ -1,6 +1,10 @@ -# Stage 0: Pretraining +--- +title: "Stage 0: Pretraining" +slug: "nemotron/nano3/pretrain.html" +description: "This stage trains the base Nemotron 3 Nano model from scratch on 25 trillion tokens using Megatron-Bridge." +--- -This stage trains the base Nemotron 3 Nano model from scratch on 25 trillion tokens using [Megatron-Bridge](../nvidia-stack.md#megatron-bridge). +This stage trains the base Nemotron 3 Nano model from scratch on 25 trillion tokens using [Megatron-Bridge](/../nvidia-stack#megatron-bridge). Nemotron 3 Nano is a **hybrid Mamba-Transformer-MoE** model with 52 layers, combining state-space models for efficiency, attention for global context, and mixture-of-experts for capacity. Notable design choices include aux-loss-free MoE balancing and a two-phase data curriculum. @@ -11,15 +15,15 @@ Nemotron 3 Nano is a **hybrid Mamba-Transformer-MoE** model with 52 layers, comb ## Training Methodology > **Training Framework**: Pretraining is implemented using [Megatron-Bridge](https://docs.nvidia.com/nemo/megatron-bridge/latest/), which provides the training loop, distributed training primitives, and checkpoint management. See [Training Entry Points](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/entry-points.html) for details on how `pretrain()` works. -> -> For complete methodology, see [Tech Report Section 2](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf). + +For complete methodology, see [Tech Report Section 2](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf). ### Model Architecture Nemotron 3 Nano uses a **hybrid Mamba-Transformer-MoE** architecture with 52 layers: | Layer Type | Count | Role | -|------------|-------|------| +| --- | --- | --- | | Mamba-2 | 23 | Efficient sequence modeling via state space | | Attention | 6 | Global context at key positions | | MoE | 23 | Sparse computation with 8 experts per layer | @@ -45,19 +49,21 @@ flowchart LR **Design choices:** - **Mamba-2 layers** provide linear-time sequence processing, making long-context inference practical + - **Attention layers** appear at regular intervals (every ~8 layers) for global information mixing + - **MoE layers** use 128 routed experts plus 1 shared expert, with 6 experts activated per token. This keeps active parameters at ~3.5B while total parameters reach ~31.6B > For architecture rationale, see [Tech Report Section 2.1](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf). -> -> For implementation details, see [Megatron-Bridge Nemotron 3](https://docs.nvidia.com/nemo/megatron-bridge/latest/models/llm/nemotron3.html). + +For implementation details, see [Megatron-Bridge Nemotron 3](https://docs.nvidia.com/nemo/megatron-bridge/latest/models/llm/nemotron3.html). ### Pretraining Data The pretraining corpus comprises four main dataset families: | Dataset Family | Description | -|----------------|-------------| +| --- | --- | | **Nemotron-CC-Code-v1** | High-quality code from Common Crawl | | **Nemotron-Pretraining-Code-v2** | GitHub code with student-teacher generation | | **Nemotron-CC-v2.1** | General English web crawl with synthetic rephrasing | @@ -72,22 +78,28 @@ Data spans 15 categories including web crawl (various quality tiers), code, math Training follows a two-phase curriculum that transitions from broad coverage to focused quality: | Phase | Tokens | Focus | Strategy | -|-------|--------|-------|----------| +| --- | --- | --- | --- | | Phase 1 | 23.5T | Diversity | Broad coverage across all data sources | | Phase 2 | 1.5T | Quality | Increased weight on high-quality and STEM data | **Phase 1: Foundation Building** - Uses all dataset families with balanced weights + - Emphasizes diversity: web (multiple quality tiers), code, math, multilingual + - Builds broad knowledge base and language understanding **Phase 2: Quality Refinement** - Increases sampling from high-quality sources: - - `High-Quality` and `High-Quality-Synthetic` subsets - - Nemotron-Pretraining-Specialized-v1 (STEM, math textbooks, scientific coding) + + - `High-Quality` and `High-Quality-Synthetic` subsets + + - Nemotron-Pretraining-Specialized-v1 (STEM, math textbooks, scientific coding) + - Reduces low-quality web content + - Sharpens model capabilities on curated data > For mixture strategy details, see [Tech Report Section 2.3](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf). @@ -95,7 +107,7 @@ Training follows a two-phase curriculum that transitions from broad coverage to ### Hyperparameters | Parameter | Value | -|-----------|-------| +| --- | --- | | **Total Tokens** | 25 trillion | | **Batch Size** | 3,072 sequences | | **Sequence Length** | 8,192 tokens | @@ -108,7 +120,7 @@ Training follows a two-phase curriculum that transitions from broad coverage to **Learning Rate Schedule:** | Phase | Tokens | LR | -|-------|--------|-----| +| --- | --- | --- | | Warmup | 8.4B | 0 → 1e-3 | | Stable | 20T (80%) | 1e-3 | | Decay | 5T (20%) | 1e-3 → 1e-5 | @@ -124,16 +136,23 @@ Nemotron 3 Nano uses the **aux-loss-free load balancing** strategy from DeepSeek **Why aux-loss-free?** Traditional MoE training adds an auxiliary loss term to encourage balanced routing. However, this: -- Adds a hyperparameter (aux loss weight) that's hard to tune + +- Adds a hyperparameter (aux loss weight) that’s hard to tune + - Can conflict with the main training objective + - May hurt model quality at scale **How it works:** Instead of auxiliary losses, the router uses **bias terms** that are adjusted dynamically: + - Track expert utilization over a sliding window + - Increase bias for underutilized experts (more tokens routed to them) + - Decrease bias for overloaded experts + - No gradient flows through the bias adjustment This achieves balanced expert utilization without interfering with the main loss function. @@ -145,7 +164,7 @@ This achieves balanced expert utilization without interfering with the main loss The LC-Phase extends context to 1M tokens after main pretraining: | Parameter | Value | -|-----------|-------| +| --- | --- | | **Duration** | 121 billion tokens | | **Learning Rate** | 1e-5 (constant) | | **Global Batch Size** | 48 | @@ -160,7 +179,6 @@ The LC-Phase extends context to 1M tokens after main pretraining: ### Quick Start
- ```console // 1. Prepare data (tokenize to bin/idx format) $ uv run nemotron nano3 data prep pretrain --run YOUR-CLUSTER @@ -170,8 +188,7 @@ $ uv run nemotron nano3 pretrain --run YOUR-CLUSTER ```
- -> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](../../nemo_runspec/nemo-run.md). See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for setup. +> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](/../../nemo_runspec/nemo-run). See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for setup. #### Direct Script Execution (Megatron-Bridge) @@ -200,10 +217,10 @@ See the [Megatron-Bridge Nemotron 3 documentation](https://docs.nvidia.com/nemo/ ### Configuration | File | Purpose | -|------|---------| -| `config/default.yaml` | Production configuration | -| `config/data_prep/default.yaml` | Data preparation settings | -| `config/data_prep/data_blend_raw.json` | Dataset blend definition | +| --- | --- | +| config/default.yaml | Production configuration | +| config/data_prep/default.yaml | Data preparation settings | +| config/data_prep/data_blend_raw.json | Dataset blend definition | **Blend Configuration** @@ -222,7 +239,7 @@ Weights control sampling probability during data preparation. Phase transitions ### Data Preparation -The `data_prep.py` script tokenizes raw text datasets into Megatron's binary format. See [Data Preparation Module](../data-prep.md) for detailed documentation. +The `data_prep.py` script tokenizes raw text datasets into Megatron’s binary format. See [Data Preparation Module](/../data-prep) for detailed documentation. #### CLI Command @@ -231,14 +248,14 @@ uv run nemotron nano3 data prep pretrain [options] ``` | Option | Description | -|--------|-------------| -| `--run ` | Execute on Slurm via [NeMo-Run](../../nemo_runspec/nemo-run.md) | -| `sample=N` | Limit rows per dataset (for testing) | -| `force=true` | Force re-run, ignoring cache | +| --- | --- | +| --run <profile> | Execute on Slurm via [NeMo-Run](/../../nemo_runspec/nemo-run) | +| sample=N | Limit rows per dataset (for testing) | +| force=true | Force re-run, ignoring cache | #### Output -``` +```default output/nano3/stage0_pretrain/ ├── blend.json # Per-split blend {"train": [...], "valid": [...], "test": [...]} ├── splits/ @@ -249,10 +266,10 @@ output/nano3/stage0_pretrain/ │ │ └── shard_000000.bin/.idx │ └── test/ │ └── shard_000000.bin/.idx -└── runs// # Raw shard outputs (splits/ symlinks here) +└── runs/\/ # Raw shard outputs (splits/ symlinks here) ``` -The output is registered as a [W&B Artifact](../artifacts.md) (`PretrainBlendsArtifact-`) for lineage tracking. +The output is registered as a [W&B Artifact](/../artifacts) (`PretrainBlendsArtifact-`) for lineage tracking. ### Training @@ -263,11 +280,11 @@ uv run nemotron nano3 pretrain [options] [overrides...] ``` | Option | Description | -|--------|-------------| -| `--run ` | Attached—submits and waits, streaming logs ([NeMo-Run](../../nemo_runspec/nemo-run.md)) | -| `--batch ` | Detached—submits and exits immediately ([NeMo-Run](../../nemo_runspec/nemo-run.md)) | -| `--dry-run` | Preview execution plan | -| `key=value` | Override config values ([CLI Framework](../cli.md#dotlist-overrides)) | +| --- | --- | +| --run <profile> | Attached—submits and waits, streaming logs ([NeMo-Run](/../../nemo_runspec/nemo-run)) | +| --batch <profile> | Detached—submits and exits immediately ([NeMo-Run](/../../nemo_runspec/nemo-run)) | +| --dry-run | Preview execution plan | +| key=value | Override config values ([CLI Framework](/../cli#dotlist-overrides)) | #### Override Examples @@ -301,7 +318,7 @@ gpus_per_node = 8 mounts = ["/lustre:/lustre"] ``` -See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for complete configuration options. +See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for complete configuration options. ### Checkpoint & Resume @@ -318,12 +335,12 @@ uv run nemotron nano3 pretrain checkpoint.load=/path/to/checkpoints/ **Checkpoint Configuration:** | Option | Description | -|--------|-------------| -| `checkpoint.save` | Directory for saving checkpoints | -| `checkpoint.load` | Path to checkpoint for resuming | -| `checkpoint.save_interval` | Steps between saves (default: 1000) | +| --- | --- | +| checkpoint.save | Directory for saving checkpoints | +| checkpoint.load | Path to checkpoint for resuming | +| checkpoint.save_interval | Steps between saves (default: 1000) | -Checkpoints use Megatron's distributed format, which handles model parallelism automatically. Each checkpoint contains model weights, optimizer state, and training progress. +Checkpoints use Megatron’s distributed format, which handles model parallelism automatically. Each checkpoint contains model weights, optimizer state, and training progress. > For checkpoint format and advanced options, see [Megatron-Bridge Checkpointing](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/checkpointing.html). @@ -350,37 +367,39 @@ flowchart TB ## Infrastructure -This stage uses the following components from the [NVIDIA AI Stack](../nvidia-stack.md): +This stage uses the following components from the [NVIDIA AI Stack](/../nvidia-stack): | Component | Role | Documentation | -|-----------|------|---------------| -| [Megatron-Core](../nvidia-stack.md#megatron-core) | Distributed training primitives (TP, PP, DP, EP, CP, SP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | -| [Megatron-Bridge](../nvidia-stack.md#megatron-bridge) | Model definitions, training loop, checkpoint management | [Docs](https://docs.nvidia.com/nemo/megatron-bridge/latest/) | +| --- | --- | --- | +| [Megatron-Core](/../nvidia-stack#megatron-core) | Distributed training primitives (TP, PP, DP, EP, CP, SP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | +| [Megatron-Bridge](/../nvidia-stack#megatron-bridge) | Model definitions, training loop, checkpoint management | [Docs](https://docs.nvidia.com/nemo/megatron-bridge/latest/) | ### Parallelism Configuration Pretraining uses multiple parallelism strategies for efficient scaling. The specific values differ between main pretraining and long-context extension: | Parallelism | Main Pretraining | Long-Context (LC) | Config Key | -|-------------|------------------|-------------------|------------| -| Tensor (TP) | 8 | 8 | `model.tensor_model_parallel_size` | -| Pipeline (PP) | 1 | 4 | `model.pipeline_model_parallel_size` | -| Expert (EP) | 8 | 8 | `model.expert_model_parallel_size` | -| Context (CP) | 1 | 8 | `model.context_parallel_size` | -| Sequence (SP) | Yes | Yes | `model.sequence_parallel` | +| --- | --- | --- | --- | +| Tensor (TP) | 8 | 8 | model.tensor_model_parallel_size | +| Pipeline (PP) | 1 | 4 | model.pipeline_model_parallel_size | +| Expert (EP) | 8 | 8 | model.expert_model_parallel_size | +| Context (CP) | 1 | 8 | model.context_parallel_size | +| Sequence (SP) | Yes | Yes | model.sequence_parallel | | Data (DP) | Auto | Auto | Computed from world size | **Why the difference?** -- **Main pretraining** uses 4K sequences, so context parallelism (CP=1) isn't needed +- **Main pretraining** uses 4K sequences, so context parallelism (CP=1) isn’t needed + - **Long-context extension** handles up to 1M tokens, requiring CP=8 to distribute sequences across GPUs + - **Pipeline parallelism** increases in LC phase (PP=4) to handle larger activation memory -> For parallelism concepts, see [NVIDIA AI Stack: Parallelism](../nvidia-stack.md#parallelism-strategies). +> For parallelism concepts, see [NVIDIA AI Stack: Parallelism](/../nvidia-stack#parallelism-strategies). ### Container -``` +```default nvcr.io/nvidia/nemo:25.11.nemotron_3_nano ``` @@ -388,12 +407,16 @@ nvcr.io/nvidia/nemo:25.11.nemotron_3_nano ## Next Steps -After pretraining completes, proceed to [Stage 1: SFT](./sft.md) for instruction tuning. +After pretraining completes, proceed to [Stage 1: SFT](/sft) for instruction tuning. ## Reference - [Tech Report Section 2](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf) – pretraining methodology -- [NVIDIA AI Stack](../nvidia-stack.md) – Megatron-Core, Megatron-Bridge -- [Artifact Lineage](../artifacts.md) – W&B artifact system + +- [NVIDIA AI Stack](/../nvidia-stack) – Megatron-Core, Megatron-Bridge + +- [Artifact Lineage](/../artifacts) – W&B artifact system + - **Recipe Source:** `src/nemotron/recipes/nano3/stage0_pretrain/` -- [Back to Overview](./README.md) + +- [Back to Overview](/README) diff --git a/docs/nemotron/nano3/rl.md b/docs/fern/pages-vnightly/nemotron/nano3/rl.mdx similarity index 63% rename from docs/nemotron/nano3/rl.md rename to docs/fern/pages-vnightly/nemotron/nano3/rl.mdx index 6dfc65e4c..7d6f4ab25 100644 --- a/docs/nemotron/nano3/rl.md +++ b/docs/fern/pages-vnightly/nemotron/nano3/rl.mdx @@ -1,6 +1,10 @@ -# Stage 2: Reinforcement Learning (RL) +--- +title: "Stage 2: Reinforcement Learning (RL)" +slug: "nemotron/nano3/rl.html" +description: "This stage aligns the instruction-tuned model using GRPO (Group Relative Policy Optimization) with NeMo-RL." +--- -This stage aligns the instruction-tuned model using GRPO (Group Relative Policy Optimization) with [NeMo-RL](../nvidia-stack.md#nemo-rl). +This stage aligns the instruction-tuned model using GRPO (Group Relative Policy Optimization) with [NeMo-RL](/../nvidia-stack#nemo-rl). > **Open-Source Data Only**: This recipe uses exclusively open-sourced RL data from the [Nemotron Post-training Datasets](https://huggingface.co/collections/nvidia/nemotron-post-training-v3) collection, which is a subset of the full data used to train the released model. The recipe uses the [Nemotron-3-Nano-RL-Training-Blend](https://huggingface.co/datasets/nvidia/Nemotron-3-Nano-RL-Training-Blend) dataset. Results will differ from the benchmarks in the [tech report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf). Use this recipe as a reference implementation to apply the methodology with your own data. @@ -9,14 +13,17 @@ This stage aligns the instruction-tuned model using GRPO (Group Relative Policy ## Training Methodology > **Training Framework**: RL alignment is implemented using [NeMo-RL](https://docs.nvidia.com/nemo/rl/latest/) with Ray for distributed actor coordination and vLLM for fast rollout generation. The Megatron backend handles distributed policy training with tensor, pipeline, context, and expert parallelism. See [NeMo-RL Documentation](https://docs.nvidia.com/nemo/rl/latest/) for implementation details. -> -> For complete methodology, see [Tech Report Section 3.2](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf). + +For complete methodology, see [Tech Report Section 3.2](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf). ### RL Pipeline Overview The RL pipeline consists of three components: + 1. **RLVR** – multi-environment training with verifiable rewards + 2. **RLHF with GenRM** – generative reward model-based alignment + 3. **DPO** – preference learning to reduce tool hallucination ### Data Preparation Pipeline @@ -44,10 +51,10 @@ flowchart LR ``` | Stage | What Happens | -|-------|--------------| +| --- | --- | | **HuggingFace Dataset** | Load [Nemotron-3-Nano-RL-Training-Blend](https://huggingface.co/datasets/nvidia/Nemotron-3-Nano-RL-Training-Blend) from HuggingFace Hub | -| **Placeholder Resolution** | Resolve `_hf_placeholder` records by fetching from external datasets (DAPO, Skywork) and applying template restoration | -| **JSONL Format** | Convert to JSONL with `question`, `expected_answer`, and `responses_create_params` fields | +| **Placeholder Resolution** | Resolve _hf_placeholder records by fetching from external datasets (DAPO, Skywork) and applying template restoration | +| **JSONL Format** | Convert to JSONL with question, expected_answer, and responses_create_params fields | | **Train/Val/Test Split** | Split into training (98%), validation (1%), and test (1%) sets | | **NeMo-Gym Environment** | Route samples to appropriate reward environments based on task type | | **Reward Computation** | Compute verifiable rewards (math correctness, code execution, schema adherence) | @@ -57,10 +64,14 @@ flowchart LR The [Nemotron-3-Nano-RL-Training-Blend](https://huggingface.co/datasets/nvidia/Nemotron-3-Nano-RL-Training-Blend) dataset contains placeholder records that reference external HuggingFace datasets. The `data_prep.py` script resolves these by: 1. Detecting placeholder records by the presence of `_hf_placeholder` field + 2. Fetching actual data from external HF datasets: - - [BytedTsinghua-SIA/DAPO-Math-17k](https://huggingface.co/datasets/BytedTsinghua-SIA/DAPO-Math-17k) — Math reasoning problems - - [Skywork/Skywork-OR1-RL-Data](https://huggingface.co/datasets/Skywork/Skywork-OR1-RL-Data) — Open reasoning data -3. Applying template restoration (DAPO prefix/suffix, Skywork `{question}` replacement) + + - [BytedTsinghua-SIA/DAPO-Math-17k](https://huggingface.co/datasets/BytedTsinghua-SIA/DAPO-Math-17k) — Math reasoning problems + + - [Skywork/Skywork-OR1-RL-Data](https://huggingface.co/datasets/Skywork/Skywork-OR1-RL-Data) — Open reasoning data + +3. Applying template restoration (DAPO prefix/suffix, Skywork `\{question\}` replacement) > For data preparation implementation, see **Recipe Source**: `src/nemotron/recipes/nano3/stage2_rl/data_prep.py` @@ -69,34 +80,40 @@ The [Nemotron-3-Nano-RL-Training-Blend](https://huggingface.co/datasets/nvidia/N GRPO (Group Relative Policy Optimization) optimizes the policy using group-relative advantages: 1. **Generate responses** from the current policy using vLLM + 2. **Evaluate** responses using NeMo-Gym reward environments + 3. **Compute group-relative advantages** across response groups per prompt + 4. **Update the policy** to favor higher-reward responses with clipped gradients **Loss Function:** The GRPO loss uses clipped policy gradients with KL regularization: -$$ -L(\theta) = E_{x \sim \pi_{\theta_{\text{old}}}} \Big[ \min \Big(\frac{\pi_\theta(x)}{\pi_{\theta_{\text{old}}}(x)}A_t, \text{clip} \big( \frac{\pi_\theta(x)}{\pi_{\theta_{\text{old}}}(x)}, 1 - \varepsilon, 1 + \varepsilon \big) A_t \Big) \Big] - \beta D_{\text{KL}} (\pi_\theta \| \pi_\text{ref}) -$$ - +L(\theta) = E_\{x \sim \pi_\{\theta_\{\text\{old\}\}\}\} \Big[ \min \Big(\frac\{\pi_\theta(x)\}\{\pi_\{\theta_\{\text\{old\}\}\}(x)\}A_t, \text\{clip\} \big( \frac\{\pi_\theta(x)\}\{\pi_\{\theta_\{\text\{old\}\}\}(x)\}, 1 - \varepsilon, 1 + \varepsilon \big) A_t \Big) \Big] - \beta D_\{\text\{KL\}\} (\pi_\theta \| \pi_\text\{ref\}) Where: -- $\pi_\theta$ is the policy being optimized -- $\pi_{\theta_{\text{old}}}$ is the policy from the beginning of this step -- $A_t$ is the advantage estimate (group-relative) -- $\varepsilon$ is the clipping hyperparameter (0.2–0.28) -- $\beta$ is the KL penalty coefficient -- $\pi_{\text{ref}}$ is the reference policy (frozen SFT checkpoint) + +- \pi_\theta is the policy being optimized + +- \pi_\{\theta_\{\text\{old\}\}\} is the policy from the beginning of this step + +- A_t is the advantage estimate (group-relative) + +- \varepsilon is the clipping hyperparameter (0.2–0.28) + +- \beta is the KL penalty coefficient + +- \pi_\{\text\{ref\}\} is the reference policy (frozen SFT checkpoint) **Stability Improvements:** | Improvement | Description | -|-------------|-------------| +| --- | --- | | **On-Policy KL Approximation** | Uses importance weights to correct for off-policy samples. This gives an unbiased and guaranteed-positive KL estimator | | **Importance Sampling Correction** | Corrects for discrepancies between inference (vLLM) and training (Megatron) token probabilities | | **Overlong Filtering** | Excludes sequences that hit max length without EOS from loss computation, reducing noise from truncated generations | -| **Asymmetric Clipping** | Uses `ratio_clip_min=0.2` and `ratio_clip_max=0.28` for asymmetric policy update bounds | +| **Asymmetric Clipping** | Uses ratio_clip_min=0.2 and ratio_clip_max=0.28 for asymmetric policy update bounds | > For detailed loss function derivations, see the [NeMo-RL GRPO Guide](https://docs.nvidia.com/nemo/rl/latest/guides/grpo.html#loss). @@ -105,7 +122,7 @@ Where: Training uses 6 reward environments through NeMo-Gym: | Environment | Description | Reward Type | -|-------------|-------------|-------------| +| --- | --- | --- | | **math_with_judge** | Mathematical reasoning (DAPO, Skywork math) | Answer correctness verification | | **code_gen** | Code correctness with test case execution | Unit test pass rate | | **mcqa** | STEM multiple choice questions | Answer matching | @@ -122,7 +139,7 @@ Training on all environments simultaneously provides stable gains without co-rew Generative reward models use circular comparison strategy (N comparisons instead of O(N²)) with length-normalized reward adjustment: | Parameter | Value | -|-----------|-------| +| --- | --- | | **Prompts per batch** | 128 | | **Responses per prompt** | 16 | | **Comparison strategy** | Circular | @@ -135,7 +152,7 @@ Generative reward models use circular comparison strategy (N comparisons instead DPO reduces hallucinated tool usage with minimal computational overhead: | Metric | Before DPO | After DPO | -|--------|------------|-----------| +| --- | --- | --- | | **AIME25 Accuracy** | 80.88% | 84.58% | | **Hallucination Rate** | 8.33% | 0.7% | @@ -144,7 +161,9 @@ DPO reduces hallucinated tool usage with minimal computational overhead: ### Reasoning Control The model supports: + - **Reasoning on/off control** – strip reasoning from 10% of samples + - **Token budget control** – truncate 3% of reasoning traces to different budgets ### Hyperparameters @@ -152,47 +171,47 @@ The model supports: **GRPO Settings:** | Parameter | Value | Description | -|-----------|-------|-------------| -| `num_prompts_per_step` | 128 | Prompts sampled per training step | -| `num_generations_per_prompt` | 16 | Rollouts generated per prompt | -| `max_total_sequence_length` | 49152 | Maximum sequence length (~49K tokens) | -| `normalize_rewards` | true | Normalize rewards across batch | -| `use_leave_one_out_baseline` | true | Variance reduction for advantage estimation | -| `val_period` | 5 | Validation every N steps | -| `max_num_epochs` | 1 | Single epoch over data | -| `seed` | 42 | Random seed for reproducibility | +| --- | --- | --- | +| num_prompts_per_step | 128 | Prompts sampled per training step | +| num_generations_per_prompt | 16 | Rollouts generated per prompt | +| max_total_sequence_length | 49152 | Maximum sequence length (~49K tokens) | +| normalize_rewards | true | Normalize rewards across batch | +| use_leave_one_out_baseline | true | Variance reduction for advantage estimation | +| val_period | 5 | Validation every N steps | +| max_num_epochs | 1 | Single epoch over data | +| seed | 42 | Random seed for reproducibility | **Loss Function:** | Parameter | Value | Description | -|-----------|-------|-------------| -| `ratio_clip_min` | 0.2 | Lower bound for importance ratio clipping | -| `ratio_clip_max` | 0.28 | Upper bound for importance ratio clipping | -| `use_on_policy_kl_approximation` | true | Use unbiased on-policy KL estimator | -| `use_importance_sampling_correction` | true | Correct for inference/training mismatch | -| `token_level_loss` | true | Per-token loss normalization | -| `reference_policy_kl_penalty` | 0 | KL regularization weight (disabled) | +| --- | --- | --- | +| ratio_clip_min | 0.2 | Lower bound for importance ratio clipping | +| ratio_clip_max | 0.28 | Upper bound for importance ratio clipping | +| use_on_policy_kl_approximation | true | Use unbiased on-policy KL estimator | +| use_importance_sampling_correction | true | Correct for inference/training mismatch | +| token_level_loss | true | Per-token loss normalization | +| reference_policy_kl_penalty | 0 | KL regularization weight (disabled) | **Optimizer:** | Parameter | Value | -|-----------|-------| -| `optimizer` | AdamW | -| `lr` | 3e-6 | -| `min_lr` | 3e-6 | -| `weight_decay` | 0.0 | -| `adam_beta1` | 0.9 | -| `adam_beta2` | 0.999 | -| `adam_eps` | 1e-8 | -| `clip_grad` | 1.0 | +| --- | --- | +| optimizer | AdamW | +| lr | 3e-6 | +| min_lr | 3e-6 | +| weight_decay | 0.0 | +| adam_beta1 | 0.9 | +| adam_beta2 | 0.999 | +| adam_eps | 1e-8 | +| clip_grad | 1.0 | **Sequence Packing:** | Parameter | Value | -|-----------|-------| -| `enabled` | true | -| `algorithm` | modified_first_fit_decreasing | -| `sequence_length_round` | 64 | +| --- | --- | +| enabled | true | +| algorithm | modified_first_fit_decreasing | +| sequence_length_round | 64 | --- @@ -201,7 +220,6 @@ The model supports: ### Quick Start
- ```console // 1. Prepare data (convert to JSONL format) $ uv run nemotron nano3 data prep rl --run YOUR-CLUSTER @@ -211,8 +229,7 @@ $ uv run nemotron nano3 rl --run YOUR-CLUSTER ```
- -> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](../../nemo_runspec/nemo-run.md). See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for setup. +> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](/../../nemo_runspec/nemo-run). See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for setup. ### Running in NeMo-RL Repository @@ -251,14 +268,14 @@ uv run python examples/nemo_gym/run_grpo_nemo_gym.py \ ### Configuration | File | Purpose | -|------|---------| -| `config/default.yaml` | Production GRPO configuration | -| `config/data_prep/default.yaml` | Data preparation settings | -| `config/data_prep/data_blend_raw.json` | RL dataset blend | +| --- | --- | +| config/default.yaml | Production GRPO configuration | +| config/data_prep/default.yaml | Data preparation settings | +| config/data_prep/data_blend_raw.json | RL dataset blend | ### Data Preparation -The `data_prep.py` script converts datasets to JSONL format compatible with [NeMo-RL](../nvidia-stack.md#nemo-rl)'s NeMo-Gym interface. See [Data Preparation Module](../data-prep.md) for detailed documentation. +The `data_prep.py` script converts datasets to JSONL format compatible with [NeMo-RL](/../nvidia-stack#nemo-rl)’s NeMo-Gym interface. See [Data Preparation Module](/../data-prep) for detailed documentation. #### CLI Command @@ -267,26 +284,26 @@ uv run nemotron nano3 data prep rl [options] ``` | Option | Description | -|--------|-------------| -| `--run ` | Execute on Slurm via [NeMo-Run](../../nemo_runspec/nemo-run.md) | -| `sample=N` | Limit rows per dataset (for testing) | -| `force=true` | Force re-run, ignoring cache | +| --- | --- | +| --run <profile> | Execute on Slurm via [NeMo-Run](/../../nemo_runspec/nemo-run) | +| sample=N | Limit rows per dataset (for testing) | +| force=true | Force re-run, ignoring cache | #### Output -``` +```default output/nano3/stage2_rl/ -├── manifest.json # {"train": "", "val": "", "test": ""} -└── runs// - ├── __train/ +├── manifest.json # {"train": "\", "val": "\", "test": "\"} +└── runs/\/ + ├── \__train/ │ └── shard_000000.jsonl - ├── __val/ + ├── \__val/ │ └── shard_000000.jsonl - └── __test/ + └── \__test/ └── shard_000000.jsonl ``` -The output is registered as a [W&B Artifact](../artifacts.md) (`SplitJsonlDataArtifact-`) for lineage tracking. +The output is registered as a [W&B Artifact](/../artifacts) (`SplitJsonlDataArtifact-`) for lineage tracking. ### Training @@ -297,11 +314,11 @@ uv run nemotron nano3 rl [options] [overrides...] ``` | Option | Description | -|--------|-------------| -| `--run ` | Attached—submits and waits, streaming logs ([NeMo-Run](../../nemo_runspec/nemo-run.md)) | -| `--batch ` | Detached—submits and exits immediately ([NeMo-Run](../../nemo_runspec/nemo-run.md)) | -| `--dry-run` | Preview execution plan | -| `key=value` | Override config values ([CLI Framework](../cli.md#dotlist-overrides)) | +| --- | --- | +| --run <profile> | Attached—submits and waits, streaming logs ([NeMo-Run](/../../nemo_runspec/nemo-run)) | +| --batch <profile> | Detached—submits and exits immediately ([NeMo-Run](/../../nemo_runspec/nemo-run)) | +| --dry-run | Preview execution plan | +| key=value | Override config values ([CLI Framework](/../cli#dotlist-overrides)) | #### Override Examples @@ -340,7 +357,7 @@ exclusive = true mounts = ["/lustre:/lustre"] ``` -See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for complete configuration options. +See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for complete configuration options. ### Checkpoint & Resume @@ -357,28 +374,31 @@ uv run nemotron nano3 rl checkpointing.checkpoint_dir=/path/to/results **Checkpoint Configuration:** | Option | Value | Description | -|--------|-------|-------------| -| `save_period` | 10 | Steps between checkpoint saves | -| `metric_name` | val:total_reward/mean | Metric for best checkpoint selection | -| `higher_is_better` | true | Higher reward = better checkpoint | -| `keep_top_k` | 1000000 | Number of checkpoints to retain | +| --- | --- | --- | +| save_period | 10 | Steps between checkpoint saves | +| metric_name | val:total_reward/mean | Metric for best checkpoint selection | +| higher_is_better | true | Higher reward = better checkpoint | +| keep_top_k | 1000000 | Number of checkpoints to retain | ### Troubleshooting Common errors and solutions: | Error | Cause | Solution | -|-------|-------|----------| -| High `token_mult_prob_error` | Mismatch between vLLM and Megatron probabilities | Check weight refitting; ensure vLLM compilation settings match | -| KL divergence spikes | Single token probability errors in MoE | Monitor `gen_kl_error` metric; values above 1e-3 indicate issues | -| OOM during generation | vLLM memory allocation too high | Reduce `gpu_memory_utilization` (default 0.5) | -| Slow convergence | Learning rate too low or high | Adjust `policy.megatron_cfg.optimizer.lr` | +| --- | --- | --- | +| High token_mult_prob_error | Mismatch between vLLM and Megatron probabilities | Check weight refitting; ensure vLLM compilation settings match | +| KL divergence spikes | Single token probability errors in MoE | Monitor gen_kl_error metric; values above 1e-3 indicate issues | +| OOM during generation | vLLM memory allocation too high | Reduce gpu_memory_utilization (default 0.5) | +| Slow convergence | Learning rate too low or high | Adjust policy.megatron_cfg.optimizer.lr | **Debugging tips:** - Monitor `token_mult_prob_error` for inference/training consistency (should stay below ~2%) + - Watch `sampling_importance_ratio` (should hover around 1.0) + - Check `approx_entropy` for entropy collapse during training + - Use `sample=N` in data prep for quick iteration --- @@ -406,12 +426,12 @@ flowchart TB ## Infrastructure -This stage uses the following components from the [NVIDIA AI Stack](../nvidia-stack.md): +This stage uses the following components from the [NVIDIA AI Stack](/../nvidia-stack): | Component | Role | Documentation | -|-----------|------|---------------| -| [NeMo-RL](../nvidia-stack.md#nemo-rl) | GRPO algorithm, policy training, reward computation | [Docs](https://docs.nvidia.com/nemo/rl/latest/) | -| [Megatron-Core](../nvidia-stack.md#megatron-core) | Distributed training primitives (TP, PP, CP, EP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | +| --- | --- | --- | +| [NeMo-RL](/../nvidia-stack#nemo-rl) | GRPO algorithm, policy training, reward computation | [Docs](https://docs.nvidia.com/nemo/rl/latest/) | +| [Megatron-Core](/../nvidia-stack#megatron-core) | Distributed training primitives (TP, PP, CP, EP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | | [Ray](https://ray.io/) | Distributed actor coordination | [Docs](https://docs.ray.io/) | | vLLM | Fast rollout generation | [GitHub](https://github.com/vllm-project/vllm) | @@ -420,39 +440,39 @@ This stage uses the following components from the [NVIDIA AI Stack](../nvidia-st Training uses multiple parallelism strategies for efficient scaling: | Parallelism | Value | Config Key | -|-------------|-------|------------| -| Tensor (TP) | 2 | `policy.megatron_cfg.tensor_model_parallel_size` | -| Pipeline (PP) | 2 | `policy.megatron_cfg.pipeline_model_parallel_size` | -| Context (CP) | 4 | `policy.megatron_cfg.context_parallel_size` | -| Expert (EP) | 8 | `policy.megatron_cfg.expert_model_parallel_size` | -| Sequence (SP) | Yes | `policy.megatron_cfg.sequence_parallel` | +| --- | --- | --- | +| Tensor (TP) | 2 | policy.megatron_cfg.tensor_model_parallel_size | +| Pipeline (PP) | 2 | policy.megatron_cfg.pipeline_model_parallel_size | +| Context (CP) | 4 | policy.megatron_cfg.context_parallel_size | +| Expert (EP) | 8 | policy.megatron_cfg.expert_model_parallel_size | +| Sequence (SP) | Yes | policy.megatron_cfg.sequence_parallel | **Generation (vLLM):** | Parameter | Value | Description | -|-----------|-------|-------------| -| `tensor_parallel_size` | 4 | TP for vLLM generation | -| `gpu_memory_utilization` | 0.5 | GPU memory fraction for KV cache | -| `colocated` | true | Share GPUs with training | -| `enforce_eager` | false | Use torch.compile | +| --- | --- | --- | +| tensor_parallel_size | 4 | TP for vLLM generation | +| gpu_memory_utilization | 0.5 | GPU memory fraction for KV cache | +| colocated | true | Share GPUs with training | +| enforce_eager | false | Use torch.compile | **Cluster:** | Parameter | Value | -|-----------|-------| -| `num_nodes` | 32 | -| `gpus_per_node` | 8 | +| --- | --- | +| num_nodes | 32 | +| gpus_per_node | 8 | ### Features Used | Feature | Purpose | -|---------|--------| +| --- | --- | | GRPO algorithm | Group Relative Policy Optimization with clipped gradients | | Megatron backend | Distributed training with TP/PP/CP/EP parallelism | | Sequence Packing | Efficient batch utilization for variable-length generations | | vLLM Generation | Fast rollout with tensor parallelism | -| MoE Router Bias | Aux-loss-free load balancing (`freeze_moe_router=true`) | -| Per-token Loss | Consistent gradient signal (`calculate_per_token_loss=true`) | +| MoE Router Bias | Aux-loss-free load balancing (freeze_moe_router=true) | +| Per-token Loss | Consistent gradient signal (calculate_per_token_loss=true) | ### NeMo-Gym Environments @@ -476,7 +496,7 @@ env: NeMo-RL uses a Ray-based actor model: | Actor | Function | -|-------|----------| +| --- | --- | | **Policy Model** | Trainable policy weights (Megatron backend) | | **Generator** | vLLM-backed rollout generation (colocated) | | **Reward Environments** | NeMo-Gym environments for reward computation | @@ -484,7 +504,7 @@ NeMo-RL uses a Ray-based actor model: ### Container -``` +```default nvcr.io/nvidia/nemo-rl:v0.4.0.nemotron_3_nano ``` @@ -492,16 +512,24 @@ nvcr.io/nvidia/nemo-rl:v0.4.0.nemotron_3_nano ## Next Steps -After RL completes, proceed to [Stage 3: Evaluation](./evaluate.md) to benchmark the aligned model. +After RL completes, proceed to [Stage 3: Evaluation](/evaluate) to benchmark the aligned model. ## Reference - [Tech Report Section 3.2](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf) – RL methodology + - [NeMo-RL Documentation](https://docs.nvidia.com/nemo/rl/latest/) – GRPO, DPO, environments + - [NeMo-RL Nemotron 3 Nano Guide](https://docs.nvidia.com/nemo/rl/nightly/guides/nemotron-3-nano.html) — upstream training guide -- [NVIDIA AI Stack](../nvidia-stack.md) – NeMo-RL, Megatron-Core -- [Artifact Lineage](../artifacts.md) – W&B artifact system -- [Stage 0: Pretraining](./pretrain.md) – pretrain the base model -- [Stage 1: SFT](./sft.md) – instruction tuning + +- [NVIDIA AI Stack](/../nvidia-stack) – NeMo-RL, Megatron-Core + +- [Artifact Lineage](/../artifacts) – W&B artifact system + +- [Stage 0: Pretraining](/pretrain) – pretrain the base model + +- [Stage 1: SFT](/sft) – instruction tuning + - **Recipe Source:** `src/nemotron/recipes/nano3/stage2_rl/` -- [Back to Overview](./README.md) + +- [Back to Overview](/README) diff --git a/docs/nemotron/nano3/sft.md b/docs/fern/pages-vnightly/nemotron/nano3/sft.mdx similarity index 71% rename from docs/nemotron/nano3/sft.md rename to docs/fern/pages-vnightly/nemotron/nano3/sft.mdx index a55b491ff..cb7834faf 100644 --- a/docs/nemotron/nano3/sft.md +++ b/docs/fern/pages-vnightly/nemotron/nano3/sft.mdx @@ -1,6 +1,10 @@ -# Stage 1: Supervised Fine-Tuning (SFT) +--- +title: "Stage 1: Supervised Fine-Tuning (SFT)" +slug: "nemotron/nano3/sft.html" +description: "This stage fine-tunes the pretrained model for instruction following using Megatron-Bridge." +--- -This stage fine-tunes the pretrained model for instruction following using [Megatron-Bridge](../nvidia-stack.md#megatron-bridge). +This stage fine-tunes the pretrained model for instruction following using [Megatron-Bridge](/../nvidia-stack#megatron-bridge). > **Open-Source Data Only**: This recipe uses exclusively open-sourced SFT data from the [Nemotron Post-training Datasets](https://huggingface.co/collections/nvidia/nemotron-post-training-v3) collection, which is a subset of the full data used to train the released model. The recipe includes datasets from Nemotron-Science-v1, Nemotron-Instruction-Following-Chat-v1, Nemotron-Math-Proofs-v1, Nemotron-SWE-v1, Nemotron-Agentic-v1, and Nemotron-Competitive-Programming-v1. Results will differ from the benchmarks in the [tech report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf). Use this recipe as a reference implementation to apply the methodology with your own data. @@ -8,9 +12,9 @@ This stage fine-tunes the pretrained model for instruction following using [Mega ## Training Methodology -> **Training Framework**: SFT is implemented using [Megatron-Bridge](https://docs.nvidia.com/nemo/megatron-bridge/latest/)'s `finetune()` entry point, which loads a pretrained checkpoint and handles the training loop with role-based loss masking. See [Training Entry Points](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/entry-points.html) for implementation details. -> -> For complete methodology, see [Tech Report Section 3.1](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf). +> **Training Framework**: SFT is implemented using [Megatron-Bridge](https://docs.nvidia.com/nemo/megatron-bridge/latest/)’s `finetune()` entry point, which loads a pretrained checkpoint and handles the training loop with role-based loss masking. See [Training Entry Points](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/entry-points.html) for implementation details. + +For complete methodology, see [Tech Report Section 3.1](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf). ### Data Preparation Pipeline @@ -41,16 +45,16 @@ flowchart LR ``` | Stage | What Happens | -|-------|--------------| -| **OpenAI Chat Format** | Input messages with `role` (system/user/assistant) and `content` fields | -| **Chat Template** | Renders messages using Nano3 Jinja template with special tokens (`<\|im_start\|>`, `<\|im_end\|>`) | +| --- | --- | +| **OpenAI Chat Format** | Input messages with role (system/user/assistant) and content fields | +| **Chat Template** | Renders messages using Nano3 Jinja template with special tokens (<|im_start|>, <|im_end|>) | | **Role-Labeled Chunks** | Splits rendered text back into chunks, each tagged with its source role | | **Tokenization** | Converts text chunks to token IDs | -| **Loss Mask** | Builds mask: `1` for assistant tokens, `0` for system/user tokens | +| **Loss Mask** | Builds mask: 1 for assistant tokens, 0 for system/user tokens | | **Packing** | Multiple sequences packed into fixed-length bins (4096 tokens) | | **Mask Rolling** | Shifts mask by 1 position for next-token prediction alignment | -**Multi-turn splitting**: For conversations with reasoning content (`reasoning_content` field), the pipeline creates separate training sequences at each user turn. Reasoning from previous turns is dropped when a new user message appears—this matches inference behavior where users don't see intermediate reasoning. +**Multi-turn splitting**: For conversations with reasoning content (`reasoning_content` field), the pipeline creates separate training sequences at each user turn. Reasoning from previous turns is dropped when a new user message appears—this matches inference behavior where users don’t see intermediate reasoning. > For data preparation implementation, see **Recipe Source**: `src/nemotron/recipes/nano3/stage1_sft/data_prep.py` @@ -60,29 +64,29 @@ Loss masking determines which tokens contribute to the training loss. In SFT, we **Why mask non-assistant tokens?** -The model should learn to *respond*, not to *prompt*. If we computed loss on user messages, the model would be optimized to predict "What is 2+2?" given prior context—which isn't useful for an assistant. By masking user and system tokens (setting their loss weight to 0), gradients only flow from assistant responses, teaching the model what to generate without wasting capacity on predicting inputs. +The model should learn to *respond*, not to *prompt*. If we computed loss on user messages, the model would be optimized to predict “What is 2+2?” given prior context—which isn’t useful for an assistant. By masking user and system tokens (setting their loss weight to 0), gradients only flow from assistant responses, teaching the model what to generate without wasting capacity on predicting inputs. | Role | Loss Mask | Training Signal | -|------|-----------|-----------------| -| `system` | 0 | Ignored (instructions) | -| `user` | 0 | Ignored (prompts) | -| `assistant` | 1 | Learned (responses) | +| --- | --- | --- | +| system | 0 | Ignored (instructions) | +| user | 0 | Ignored (prompts) | +| assistant | 1 | Learned (responses) | **Why roll the mask by 1?** In next-token prediction, the model predicts `token[i+1]` given `tokens[0:i]`. The loss compares the prediction against the *label*, which is the input sequence shifted by one position: -``` +```default Position: 0 1 2 3 4 Input: [A] [B] [C] [D] [E] -Label: [B] [C] [D] [E] [_] <- shifted by 1 +Label: [B] [C] [D] [E] [_] \<- shifted by 1 ``` If assistant content starts at position 2 (`[C]`), we want loss on predicting `[C]`, `[D]`, and `[E]`. But the label for position 2 is `[D]`—so we need to shift the mask to align with labels: -``` -Original mask: [0] [0] [1] [1] [1] <- "assistant starts at C" -Rolled mask: [0] [0] [0] [1] [1] <- aligns with labels D, E +```default +Original mask: [0] [0] [1] [1] [1] \<- "assistant starts at C" +Rolled mask: [0] [0] [0] [1] [1] \<- aligns with labels D, E ``` The pipeline rolls the loss mask by 1 position so it correctly masks the *predictions* (labels) rather than the *inputs*. @@ -90,6 +94,7 @@ The pipeline rolls the loss mask by 1 position so it correctly masks the *predic **Truncation behavior (`max_doc_tokens`):** - **Default (null)**: No truncation—full sequences are preserved + - **When set**: Sequences exceeding the limit are truncated from the end, with the loss mask adjusted accordingly > For implementation details, see `src/nemotron/data_prep/core/chat_sft_shard_core.py` @@ -103,23 +108,25 @@ Individual chat conversations vary in length—some are 50 tokens, others 3000. The packed sequence format stores everything Megatron-Bridge needs for training: | Field | Description | -|-------|-------------| -| `input_ids` | Concatenated token IDs from multiple conversations | -| `loss_mask` | Rolled mask indicating which positions contribute to loss (see [Loss Masking](#loss-masking)) | -| `seq_start_id` | Boundary indices marking where each original conversation starts within the pack | +| --- | --- | +| input_ids | Concatenated token IDs from multiple conversations | +| loss_mask | Rolled mask indicating which positions contribute to loss (see [Loss Masking](#loss-masking)) | +| seq_start_id | Boundary indices marking where each original conversation starts within the pack | **How `seq_start_id` works:** -When multiple conversations are packed together, the model needs to know where one ends and another begins—otherwise attention could "leak" between unrelated conversations. The `seq_start_id` array marks these boundaries: +When multiple conversations are packed together, the model needs to know where one ends and another begins—otherwise attention could “leak” between unrelated conversations. The `seq_start_id` array marks these boundaries: -``` +```default Pack: [Conv A tokens] [Conv B tokens] [Conv C tokens] ^ ^ ^ seq_start_id: [0, 128, 384] ``` Megatron-Bridge uses these boundaries for: -- **Variable-length attention**: Attention is masked so tokens from Conv A can't attend to Conv B + +- **Variable-length attention**: Attention is masked so tokens from Conv A can’t attend to Conv B + - **FlashAttention optimization**: Boundaries map to `cu_seqlens` parameter for efficient packed attention > For packing implementation, see `src/nemotron/data_prep/packing/builder.py` @@ -129,13 +136,15 @@ Megatron-Bridge uses these boundaries for: Nemotron 3 Nano supports both reasoning and non-reasoning modes: - **Multi-Step**: Existing reasoning tokens preserved for reuse in subsequent steps + - **Multi-Turn**: Reasoning from previous turns dropped when user message introduced + - **Tool Calling**: Uses XML-style special tags to reduce character escaping ### SFT Data Domains | Domain | Description | -|--------|-------------| +| --- | --- | | **Competition Math** | Tool-integrated reasoning with GPT-OSS teachers | | **Competition Code** | OpenCodeReasoning solutions with obfuscation/complication | | **InfinityByte** | Cross-domain code synthesis at model capability boundaries | @@ -156,9 +165,13 @@ Nemotron 3 Nano supports both reasoning and non-reasoning modes: ### Data Filtering The pipeline applies: + - **Structural checks**: Discard malformed examples + - **Pathological repetition filtering**: Remove repeated n-grams + - **Consistency filtering**: Judge-based action consistency verification + - **Narrative filtering**: Remove political/nationalistic narratives ### Troubleshooting @@ -166,32 +179,35 @@ The pipeline applies: Common data preparation errors and solutions: | Error | Cause | Solution | -|-------|-------|----------| -| "# Tools missing" validation failure | Messages contain `` but system prompt lacks `# Tools` header | Add a `# Tools` section in the system prompt before tool definitions | +| --- | --- | --- | +| “# Tools missing” validation failure | Messages contain <tool_call> but system prompt lacks # Tools header | Add a # Tools section in the system prompt before tool definitions | | Empty sequences after processing | All tokens masked (no assistant content in conversation) | Verify input data contains assistant responses with actual content | | Template rendering mismatch | Tokenizer BPE splits differ from template expectations | Ensure tokenizer model matches the one used during template creation | -| Sequences truncated excessively | Many conversations exceed `max_doc_tokens` | Consider increasing `max_doc_tokens` or `pack_size`, or chunking long conversations | +| Sequences truncated excessively | Many conversations exceed max_doc_tokens | Consider increasing max_doc_tokens or pack_size, or chunking long conversations | **Debugging tips:** - Use `sample=100` to test data preparation on a small subset + - Check `metadata.json` output for statistics on filtered/truncated sequences + - Review W&B artifacts for lineage tracking and validation metrics ### Hyperparameters | Parameter | Value | -|-----------|-------| +| --- | --- | | **Learning Rate** | 1e-5 | | **Sequence Length** | 4096 tokens (pack_size) | | **Loss Masking** | Role-based (assistant tokens only) | -| **Loss Normalization** | Per-token (`calculate_per_token_loss: true`) | +| **Loss Normalization** | Per-token (calculate_per_token_loss: true) | | **Optimizer** | AdamW | | **Total Samples** | 18M+ | **`calculate_per_token_loss` explained:** - **True (default)**: Loss is normalized by the number of tokens with `loss_mask=1` across the batch. Each token contributes equally regardless of which sequence it belongs to. + - **False**: Loss is normalized by the number of sequences. Longer sequences (more assistant tokens) contribute more to the gradient. Per-token normalization is preferred for SFT because it ensures consistent learning signal regardless of conversation length. @@ -203,7 +219,6 @@ Per-token normalization is preferred for SFT because it ensures consistent learn ### Quick Start
- ```console // 1. Prepare data (apply chat templates, tokenize to Packed Parquet) $ uv run nemotron nano3 data prep sft --run YOUR-CLUSTER @@ -213,8 +228,7 @@ $ uv run nemotron nano3 sft --run YOUR-CLUSTER ```
- -> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](../../nemo_runspec/nemo-run.md). See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for setup. +> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](/../../nemo_runspec/nemo-run). See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for setup. #### Direct Script Execution (Megatron-Bridge) @@ -243,14 +257,14 @@ See the [Megatron-Bridge Nemotron 3 documentation](https://docs.nvidia.com/nemo/ ### Configuration | File | Purpose | -|------|---------| -| `config/default.yaml` | Production configuration | -| `config/data_prep/default.yaml` | Data preparation settings | -| `config/data_prep/data_blend_raw.json` | Dataset blend definition | +| --- | --- | +| config/default.yaml | Production configuration | +| config/data_prep/default.yaml | Data preparation settings | +| config/data_prep/data_blend_raw.json | Dataset blend definition | ### Data Preparation -The `data_prep.py` script processes OpenAI-format chat data into packed sequences with role-based loss masking. See [Data Preparation Module](../data-prep.md) for detailed documentation. +The `data_prep.py` script processes OpenAI-format chat data into packed sequences with role-based loss masking. See [Data Preparation Module](/../data-prep) for detailed documentation. #### CLI Command @@ -259,14 +273,14 @@ uv run nemotron nano3 data prep sft [options] ``` | Option | Description | -|--------|-------------| -| `--run ` | Execute on Slurm via [NeMo-Run](../../nemo_runspec/nemo-run.md) | -| `sample=N` | Limit rows per dataset (for testing) | -| `force=true` | Force re-run, ignoring cache | +| --- | --- | +| --run <profile> | Execute on Slurm via [NeMo-Run](/../../nemo_runspec/nemo-run) | +| sample=N | Limit rows per dataset (for testing) | +| force=true | Force re-run, ignoring cache | #### Output -``` +```default output/stage1_sft/ ├── blend.json # Per-split blend {"train": [...], "valid": [...], "test": [...]} ├── splits/ @@ -277,10 +291,10 @@ output/stage1_sft/ │ │ └── shard_000000.parquet │ └── test/ │ └── shard_000000.parquet -└── runs// # Raw shard outputs (splits/ symlinks here) +└── runs/\/ # Raw shard outputs (splits/ symlinks here) ``` -The output is registered as a [W&B Artifact](../artifacts.md) (`SFTDataArtifact-`) for lineage tracking. +The output is registered as a [W&B Artifact](/../artifacts) (`SFTDataArtifact-`) for lineage tracking. ### Training @@ -291,11 +305,11 @@ uv run nemotron nano3 sft [options] [overrides...] ``` | Option | Description | -|--------|-------------| -| `--run ` | Attached—submits and waits, streaming logs ([NeMo-Run](../../nemo_runspec/nemo-run.md)) | -| `--batch ` | Detached—submits and exits immediately ([NeMo-Run](../../nemo_runspec/nemo-run.md)) | -| `--dry-run` | Preview execution plan | -| `key=value` | Override config values ([CLI Framework](../cli.md#dotlist-overrides)) | +| --- | --- | +| --run <profile> | Attached—submits and waits, streaming logs ([NeMo-Run](/../../nemo_runspec/nemo-run)) | +| --batch <profile> | Detached—submits and exits immediately ([NeMo-Run](/../../nemo_runspec/nemo-run)) | +| --dry-run | Preview execution plan | +| key=value | Override config values ([CLI Framework](/../cli#dotlist-overrides)) | #### Override Examples @@ -329,7 +343,7 @@ gpus_per_node = 8 mounts = ["/lustre:/lustre"] ``` -See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for complete configuration options. +See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for complete configuration options. ### Artifact Lineage @@ -356,25 +370,25 @@ flowchart TB ## Infrastructure -This stage uses the following components from the [NVIDIA AI Stack](../nvidia-stack.md): +This stage uses the following components from the [NVIDIA AI Stack](/../nvidia-stack): | Component | Role | Documentation | -|-----------|------|---------------| -| [Megatron-Core](../nvidia-stack.md#megatron-core) | Distributed training primitives (TP, PP, DP, EP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | -| [Megatron-Bridge](../nvidia-stack.md#megatron-bridge) | Fine-tuning loop, checkpoint loading, loss masking | [Docs](https://docs.nvidia.com/nemo/megatron-bridge/latest/) | +| --- | --- | --- | +| [Megatron-Core](/../nvidia-stack#megatron-core) | Distributed training primitives (TP, PP, DP, EP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | +| [Megatron-Bridge](/../nvidia-stack#megatron-bridge) | Fine-tuning loop, checkpoint loading, loss masking | [Docs](https://docs.nvidia.com/nemo/megatron-bridge/latest/) | ### Features Used | Feature | Purpose | -|---------|--------| -| `finetune()` entry point | SFT training with pre-loaded checkpoint | +| --- | --- | +| finetune() entry point | SFT training with pre-loaded checkpoint | | Role-based loss masking | Only compute loss on assistant tokens | | Mixed precision (BF16) | Memory-efficient training | | Gradient checkpointing | Reduce memory footprint | ### Container -``` +```default nvcr.io/nvidia/nemo:25.11.nemotron_3_nano ``` @@ -382,13 +396,18 @@ nvcr.io/nvidia/nemo:25.11.nemotron_3_nano ## Next Steps -After SFT completes, proceed to [Stage 2: RL](./rl.md) for alignment training. +After SFT completes, proceed to [Stage 2: RL](/rl) for alignment training. ## Reference - [Tech Report Section 3.1](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf) – SFT methodology -- [NVIDIA AI Stack](../nvidia-stack.md) – Megatron-Core, Megatron-Bridge -- [Artifact Lineage](../artifacts.md) – W&B artifact system -- [Stage 0: Pretraining](./pretrain.md) – pretrain the base model + +- [NVIDIA AI Stack](/../nvidia-stack) – Megatron-Core, Megatron-Bridge + +- [Artifact Lineage](/../artifacts) – W&B artifact system + +- [Stage 0: Pretraining](/pretrain) – pretrain the base model + - **Recipe Source:** `src/nemotron/recipes/nano3/stage1_sft/` -- [Back to Overview](./README.md) + +- [Back to Overview](/README) diff --git a/docs/nemotron/nvidia-stack.md b/docs/fern/pages-vnightly/nemotron/nvidia-stack.mdx similarity index 73% rename from docs/nemotron/nvidia-stack.md rename to docs/fern/pages-vnightly/nemotron/nvidia-stack.mdx index 9a2113d9d..6376af6f4 100644 --- a/docs/nemotron/nvidia-stack.md +++ b/docs/fern/pages-vnightly/nemotron/nvidia-stack.mdx @@ -1,12 +1,16 @@ -# NVIDIA AI Stack +--- +title: "NVIDIA AI Stack" +slug: "nemotron/nvidia-stack.html" +description: "Nemotron training recipes are built on NVIDIA’s AI stack. While nemotron.kit handles artifact versioning and lineage tracking and nemo_runspec provides the CLI toolkit and execution infrastructure, al" +--- -Nemotron training recipes are built on NVIDIA's AI stack. While `nemotron.kit` handles artifact versioning and lineage tracking and `nemo_runspec` provides the CLI toolkit and execution infrastructure, all heavy-lifting for distributed training is delegated to specialized NVIDIA libraries. +Nemotron training recipes are built on NVIDIA’s AI stack. While `nemotron.kit` handles artifact versioning and lineage tracking and `nemo_runspec` provides the CLI toolkit and execution infrastructure, all heavy-lifting for distributed training is delegated to specialized NVIDIA libraries. ## NeMo Framework Nemotron recipes are part of the broader NeMo Framework ecosystem, which provides end-to-end tools for the full LLM lifecycle: -![NeMo Framework Overview](../assets/nemo-framework-overview.png) +![NeMo Framework Overview](../../_images/nemo-framework-overview.png) *Image credit: [NeMo-RL Documentation](https://docs.nvidia.com/nemo/rl/latest/)* @@ -15,7 +19,7 @@ The Nemotron recipes focus on the **Pre-training & SFT** (via Megatron-Bridge) a ## Stack Overview | Component | Purpose | Used In | -|-----------|---------|---------| +| --- | --- | --- | | [Megatron-Core](https://github.com/NVIDIA/Megatron-LM) | Distributed training primitives (TP, PP, DP, CP) | All stages | | [Megatron-Bridge](https://github.com/NVIDIA-NeMo/Megatron-Bridge) | Model definitions, training loops, HF conversion | Pretrain, SFT | | [NeMo-RL](https://github.com/NVIDIA-NeMo/RL) | RL algorithms (GRPO, DPO), reward environments | RL stage | @@ -32,7 +36,7 @@ Megatron-Core implements multiple parallelism strategies that can be combined fo Split model layers across GPUs to handle large weight matrices: -![Tensor Parallelism](../assets/tensor-parallelism.png) +![Tensor Parallelism](../../_images/tensor-parallelism.png) *Image credit: [Megatron-Bridge Documentation](https://docs.nvidia.com/nemo/megatron-bridge/latest/)* @@ -40,22 +44,22 @@ Split model layers across GPUs to handle large weight matrices: Distribute LayerNorm and Dropout activations across the sequence dimension: -![Sequence Parallelism](../assets/sequence-parallelism.png) +![Sequence Parallelism](../../_images/sequence-parallelism.png) *Image credit: [Megatron-Bridge Documentation](https://docs.nvidia.com/nemo/megatron-bridge/latest/)* #### Expert Parallelism (EP) -Distribute MoE experts across GPUs, which is central to Nemotron's sparse MoE architecture: +Distribute MoE experts across GPUs, which is central to Nemotron’s sparse MoE architecture: -![Expert Parallelism](../assets/expert-parallelism.png) +![Expert Parallelism](../../_images/expert-parallelism.png) *Image credit: [Megatron-Bridge Documentation](https://docs.nvidia.com/nemo/megatron-bridge/latest/)* ### All Parallelism Types | Parallelism | Abbreviation | Description | -|-------------|--------------|-------------| +| --- | --- | --- | | Tensor | TP | Split weight matrices across GPUs | | Pipeline | PP | Split model layers into stages | | Data | DP | Replicate model, distribute batches | @@ -66,6 +70,7 @@ Distribute MoE experts across GPUs, which is central to Nemotron's sparse MoE ar ### Documentation - [Megatron-Core GitHub](https://github.com/NVIDIA/Megatron-LM/tree/main/megatron/core) + - [Parallelism Tutorial](https://docs.nvidia.com/nemo-framework/user-guide/latest/nemotoolkit/features/parallelisms.html) ## Megatron-Bridge @@ -75,18 +80,25 @@ Megatron-Bridge is a PyTorch-native library that bridges Hugging Face models wit ### Features - **Bidirectional checkpoint conversion** between Hugging Face and Megatron formats + - **Scalable training loop** with all Megatron parallelisms + - **Pre-configured recipes** for Llama, Qwen, DeepSeek, Nemotron, and more + - **Mixed precision** (FP8, BF16, FP4) via Transformer Engine + - **PEFT** with LoRA and DoRA ### How Nemotron Uses It -Nemotron's pretraining and SFT stages use Megatron-Bridge for: +Nemotron’s pretraining and SFT stages use Megatron-Bridge for: 1. **Model definition** via `NemotronHModel` provider for the hybrid Mamba-Transformer architecture + 2. **Training loop** with `pretrain()` and `finetune()` entry points + 3. **Checkpoint management** with distributed save/load in Megatron format + 4. **HF export** to convert trained checkpoints back to Hugging Face format ```python @@ -103,20 +115,23 @@ pretrain(config) Megatron-Bridge uses a central `ConfigContainer` dataclass that combines: | Section | Purpose | -|---------|---------| -| `model` | Model architecture and parallelism settings | -| `train` | Batch sizes, iterations, gradient accumulation | -| `optimizer` | Optimizer type, learning rate, weight decay | -| `scheduler` | LR schedule (warmup, decay) | -| `dataset` | Data loading configuration | -| `checkpoint` | Save/load intervals and paths | -| `mixed_precision` | FP8/BF16 settings | +| --- | --- | +| model | Model architecture and parallelism settings | +| train | Batch sizes, iterations, gradient accumulation | +| optimizer | Optimizer type, learning rate, weight decay | +| scheduler | LR schedule (warmup, decay) | +| dataset | Data loading configuration | +| checkpoint | Save/load intervals and paths | +| mixed_precision | FP8/BF16 settings | ### Documentation - [Megatron-Bridge GitHub](https://github.com/NVIDIA-NeMo/Megatron-Bridge) + - [Official Documentation](https://docs.nvidia.com/nemo/megatron-bridge/latest/) + - [Training Entry Points](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/entry-points.html) + - [Adding New Models](https://docs.nvidia.com/nemo/megatron-bridge/latest/adding-new-models.html) ## NeMo-RL @@ -126,19 +141,27 @@ NeMo-RL is a post-training library for reinforcement learning on LLMs and VLMs, ### Features - **GRPO** (Group Relative Policy Optimization) – main RL algorithm with clipped policy gradients + - **DAPO** (Dual-Clip Asymmetric Policy Optimization) – extended GRPO with asymmetric clipping + - **DPO** (Direct Preference Optimization) – RL-free alignment from preference data + - **Reward Models** – Bradley-Terry reward model training + - **Multi-Environment Training** – math, code, tool-use, and custom reward environments + - **Flexible Backends** – DTensor (FSDP2) for native PyTorch, Megatron for large models ### How Nemotron Uses It -Nemotron's RL stage uses NeMo-RL for: +Nemotron’s RL stage uses NeMo-RL for: 1. **GRPO Training** with multi-environment RLVR across 7 reward environments + 2. **Generation** via vLLM backend for fast rollouts + 3. **Reward Computation** including math verification, code execution, GenRM scoring + 4. **Ray Orchestration** for distributed policy-environment coordination ```python @@ -155,16 +178,20 @@ run_grpo(config) ### Architecture -NeMo-RL uses a Ray-based actor model for distributed training. Each "RL Actor" (Policy, Generator, Reward Model) manages a `RayWorkerGroup` that controls multiple workers distributed across GPUs: +NeMo-RL uses a Ray-based actor model for distributed training. Each “RL Actor” (Policy, Generator, Reward Model) manages a `RayWorkerGroup` that controls multiple workers distributed across GPUs: -![NeMo-RL Actor Architecture](../assets/nemo-rl-actors.png) +![NeMo-RL Actor Architecture](../../_images/nemo-rl-actors.png) *Image credit: [NeMo-RL Documentation](https://docs.nvidia.com/nemo/rl/latest/)* Core concepts: + - **RL Actors** – high-level components (Policy Model, Generator, Reward Model) + - **RayWorkerGroup** – manages a pool of workers for each actor + - **Workers** – individual processes handling computation + - **RayVirtualCluster** – allocates GPU resources to worker groups ### Reward Environments @@ -172,17 +199,17 @@ Core concepts: NeMo-RL provides several built-in reward environments: | Environment | Description | -|-------------|-------------| -| `MathEnvironment` | Verifies mathematical solutions | -| `CodeEnvironment` | Executes code in sandbox, checks correctness | -| `RewardModelEnvironment` | Scores responses with trained reward model | -| `ToolEnvironment` | Evaluates tool-use and function calling | -| `NemoGym` | Game environments for multi-turn RL | +| --- | --- | +| MathEnvironment | Verifies mathematical solutions | +| CodeEnvironment | Executes code in sandbox, checks correctness | +| RewardModelEnvironment | Scores responses with trained reward model | +| ToolEnvironment | Evaluates tool-use and function calling | +| NemoGym | Game environments for multi-turn RL | ### Training Backends | Backend | Best For | Parallelism | -|---------|----------|-------------| +| --- | --- | --- | | **DTensor (FSDP2)** | Models up to ~32B | FSDP, TP, CP, SP | | **Megatron** | Large models (>100B) | Full 6D parallelism | @@ -191,9 +218,13 @@ Backend selection is automatic based on YAML configuration. ### Documentation - [NeMo-RL GitHub](https://github.com/NVIDIA/NeMo-RL) + - [Official Documentation](https://docs.nvidia.com/nemo/rl/latest/) + - [GRPO Guide](https://docs.nvidia.com/nemo/rl/latest/guides/grpo.html) + - [Environment Guide](https://docs.nvidia.com/nemo/rl/latest/guides/environments.html) + - [Training Backends](https://docs.nvidia.com/nemo/rl/latest/design-docs/training-backends.html) ## Version Compatibility @@ -201,13 +232,15 @@ Backend selection is automatic based on YAML configuration. Nemotron recipes are tested with specific versions of the NVIDIA AI stack. Check the container images in recipe configs for exact versions. | Component | Tested Version | Container | -|-----------|----------------|-----------| -| Megatron-Core | 0.13+ | `nvcr.io/nvidia/nemo:*` | -| Megatron-Bridge | 0.2+ | `nvcr.io/nvidia/nemo:*` | -| NeMo-RL | 0.4+ | `nvcr.io/nvidia/nemo-rl:*` | +| --- | --- | --- | +| Megatron-Core | 0.13+ | nvcr.io/nvidia/nemo:* | +| Megatron-Bridge | 0.2+ | nvcr.io/nvidia/nemo:* | +| NeMo-RL | 0.4+ | nvcr.io/nvidia/nemo-rl:* | ## Further Reading -- [Nemotron Kit](./kit.md) – artifact system and lineage tracking -- [Execution through NeMo-Run](../nemo_runspec/nemo-run.md) – execution profiles and packagers -- [Nano3 Recipe](./nano3/README.md) – training pipeline +- [Nemotron Kit](/kit) – artifact system and lineage tracking + +- [Execution through NeMo-Run](/../nemo_runspec/nemo-run) – execution profiles and packagers + +- [Nano3 Recipe](/nano3/README) – training pipeline diff --git a/docs/nemotron/omni3/README.md b/docs/fern/pages-vnightly/nemotron/omni3/README.mdx similarity index 69% rename from docs/nemotron/omni3/README.md rename to docs/fern/pages-vnightly/nemotron/omni3/README.mdx index 105e92a96..8b2ab126e 100644 --- a/docs/nemotron/omni3/README.md +++ b/docs/fern/pages-vnightly/nemotron/omni3/README.mdx @@ -1,6 +1,10 @@ -# Nemotron 3 Omni Training Recipe +--- +title: "Nemotron 3 Omni Training Recipe" +slug: "nemotron/omni3/README.html" +description: "Multimodal post-training pipeline for Nemotron 3 Nano Omni, NVIDIA’s 30B-A3B hybrid mixture-of-experts model. Unlike Nano3 and Super3, Omni starts from a GA checkpoint and owns its stage-local contain" +--- -Multimodal post-training pipeline for **Nemotron 3 Nano Omni**, NVIDIA's +Multimodal post-training pipeline for **Nemotron 3 Nano Omni**, NVIDIA’s 30B-A3B hybrid mixture-of-experts model. Unlike Nano3 and Super3, Omni starts from a GA checkpoint and owns its stage-local container builds. @@ -10,76 +14,85 @@ builds. Quick navigation for developers landing here from the [release blog](https://developer.nvidia.com/blog/nvidia-nemotron-3-nano-omni-powers-multimodal-agent-reasoning-in-a-single-efficient-open-model/): | You want… | Go to | -|---|---| -| Architecture deep-dive (Mamba+transformer, EVS, NemoClaw) | [`architecture.md`](./architecture.md) | -| Inference engines, quantization, cloud platforms, providers | [`inference.md`](./inference.md) | +| --- | --- | +| Architecture deep-dive (Mamba+transformer, EVS, NemoClaw) | [architecture.md](/architecture) | +| Inference engines, quantization, cloud platforms, providers | [inference.md](/inference) | | Reproduce training | [§Quick Start](#quick-start) below | -| SFT details | [`sft.md`](./sft.md) | -| RL details | [`rl.md`](./rl.md) · [`rl/data-prep.md`](./rl/data-prep.md) | - +| SFT details | [sft.md](/sft) | +| RL details | [rl.md](/rl) · [rl/data-prep.md](/rl/data-prep) | ## Model Overview -![Nemotron 3 Nano Omni hybrid MoE architecture: Parakeet audio encoder → audio adaptor, C-RADIOv4-H vision encoder + 3D convolution + Efficient Video Sampling → vision adaptor, text tokenizer, all feeding the unified 30B-A3B LLM decoder](../../assets/omni-3.png) +![Nemotron 3 Nano Omni hybrid MoE architecture: Parakeet audio encoder → audio adaptor, C-RADIOv4-H vision encoder + 3D convolution + Efficient Video Sampling → vision adaptor, text tokenizer, all feeding the unified 30B-A3B LLM decoder](../../../_images/omni-3.png) | Property | Value | -|---|---| -| Architecture | Hybrid MoE — Mamba layers (sequence/memory efficiency) + transformer layers (reasoning), with a unified text decoder ([details](./architecture.md#hybrid-moe-decoder)) | +| --- | --- | +| Architecture | Hybrid MoE — Mamba layers (sequence/memory efficiency) + transformer layers (reasoning), with a unified text decoder ([details](/architecture#hybrid-moe-decoder)) | | Total / active parameters | 30B / 3B (A3B MoE) | | Native modalities | Text, image, video, audio | | Max context length | 262K tokens | -| Training context schedule | 16K → 49K → 262K (progressive scaling, see [§Progressive context scaling](./architecture.md#progressive-context-scaling)) | -| Vision encoder | [C-RADIOv4-H](./architecture.md#vision-encoder--c-radiov4-h) | -| Audio encoder | [NVIDIA Parakeet (extended via Granary, Music Flamingo)](./architecture.md#audio-encoder--parakeet-extended) | -| Video pipeline | [3D convolutions + Efficient Video Sampling (EVS)](./architecture.md#video-pipeline--3d-convolutions--efficient-video-sampling-evs) | -| GA checkpoint | [`nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16`](https://huggingface.co/nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16) | +| Training context schedule | 16K → 49K → 262K (progressive scaling, see [§Progressive context scaling](/architecture#progressive-context-scaling)) | +| Vision encoder | [C-RADIOv4-H](/architecture#vision-encoder-c-radiov4-h) | +| Audio encoder | [NVIDIA Parakeet (extended via Granary, Music Flamingo)](/architecture#audio-encoder-parakeet-extended) | +| Video pipeline | [3D convolutions + Efficient Video Sampling (EVS)](/architecture#video-pipeline-3d-convolutions-efficient-video-sampling-evs) | +| GA checkpoint | [nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16](https://huggingface.co/nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16) | | License | [NVIDIA Nemotron Open Model License](https://huggingface.co/nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16) (enterprise-friendly, on-prem and any deployment) | -For the full architectural deep-dive — including why EVS drives the throughput numbers, the perception-sub-agent framing, and the released training-data scale (127B / 124M / 20×25 / 11.4M) — see [`architecture.md`](./architecture.md). +For the full architectural deep-dive — including why EVS drives the throughput numbers, the perception-sub-agent framing, and the released training-data scale (127B / 124M / 20×25 / 11.4M) — see [`architecture.md`](/architecture). ### Capabilities (released benchmarks) - Best-in-class on [MMlongbench-Doc](https://github.com/mayubo2333/MMLongBench-Doc) and [OCRBenchV2](https://github.com/Yuliang-Liu/MultimodalOCR) (document intelligence) + - Leading on [WorldSense](https://huggingface.co/datasets/honglyhly/WorldSense), [DailyOmni](https://lliar-liar.github.io/Daily-Omni/#leaderboard), [VoiceBench](https://huggingface.co/datasets/hlt-lab/voicebench) (video / audio understanding) + - **~9.2×** greater effective system capacity on video reasoning, **~7.4×** on multi-document workloads vs. comparable open omni models -- "Highest throughput across every task" in MediaPerf; "lowest inference cost for video-level tagging" -- See [`inference.md`](./inference.md) for engines, quantization paths, hardware support, and deployment + +- “Highest throughput across every task” in MediaPerf; “lowest inference cost for video-level tagging” + +- See [`inference.md`](/inference) for engines, quantization paths, hardware support, and deployment ### Use cases -Designed as a **multimodal perception sub-agent** for agentic AI — finance, healthcare, scientific discovery, media/entertainment, ad-tech. Especially strong on long-horizon reasoning over complex documents and large video batches. The [NemoClaw sandbox](./inference.md#nemoclaw--privacy-first-video-processing) provides privacy-first video processing for compliance-bounded workloads. +Designed as a **multimodal perception sub-agent** for agentic AI — finance, healthcare, scientific discovery, media/entertainment, ad-tech. Especially strong on long-horizon reasoning over complex documents and large video batches. The [NemoClaw sandbox](/inference#nemoclaw-privacy-first-video-processing) provides privacy-first video processing for compliance-bounded workloads. ### Upstream training recipes This recipe folder is the cookbook view; upstream sources are: | Stage | Upstream guide | Branch root | -|---|---|---| -| SFT (Megatron-Bridge) | [`nemotron_3_omni` README](https://github.com/NVIDIA-NeMo/Megatron-Bridge/blob/nemotron_3_omni/examples/models/vlm/nemotron_3_omni/README.md) | [`Megatron-Bridge` `nemotron_3_omni`](https://github.com/NVIDIA-NeMo/Megatron-Bridge/tree/nemotron_3_omni) | -| RL (NeMo-RL) | [`nano-v3-omni` Nemotron 3 Nano Omni guide](https://github.com/NVIDIA-NeMo/RL/blob/nano-v3-omni/docs/guides/nemotron-3-nano-omni.md) | [`NeMo-RL` `nano-v3-omni`](https://github.com/NVIDIA-NeMo/RL/tree/nano-v3-omni) | +| --- | --- | --- | +| SFT (Megatron-Bridge) | [nemotron_3_omni README](https://github.com/NVIDIA-NeMo/Megatron-Bridge/blob/nemotron_3_omni/examples/models/vlm/nemotron_3_omni/README.md) | [Megatron-Bridge nemotron_3_omni](https://github.com/NVIDIA-NeMo/Megatron-Bridge/tree/nemotron_3_omni) | +| RL (NeMo-RL) | [nano-v3-omni Nemotron 3 Nano Omni guide](https://github.com/NVIDIA-NeMo/RL/blob/nano-v3-omni/docs/guides/nemotron-3-nano-omni.md) | [NeMo-RL nano-v3-omni](https://github.com/NVIDIA-NeMo/RL/tree/nano-v3-omni) | | Evaluation | Same Megatron-Bridge path | (above) | -| Image training data | — | [`huggingface.co/datasets/nvidia/Nemotron-Image-Training-v3`](https://huggingface.co/datasets/nvidia/Nemotron-Image-Training-v3) | -| Long-document SDG | [Long-document SDG guide](../data/sdg/long-document.md) | [`src/nemotron/recipes/data/sdg/long-document/`](https://github.com/NVIDIA-NeMo/Nemotron/tree/main/src/nemotron/recipes/data/sdg/long-document) (structure released; bodies port at upstream release) | +| Image training data | — | [huggingface.co/datasets/nvidia/Nemotron-Image-Training-v3](https://huggingface.co/datasets/nvidia/Nemotron-Image-Training-v3) | +| Long-document SDG | [Long-document SDG guide](/../data/sdg/long-document) | [src/nemotron/recipes/data/sdg/long-document/](https://github.com/NVIDIA-NeMo/Nemotron/tree/main/src/nemotron/recipes/data/sdg/long-document) (structure released; bodies port at upstream release) | ## Current Limitations The recipe structure, CLI, Dockerfiles, and configs are all in place, but some pieces still depend on upstream work or internal-only data: -- **Evaluation stage not yet included — coming soon.** The omni3 CLI doesn't have an `eval` subcommand today. Multimodal sanity checks against a trained checkpoint run via `nemotron omni3 model eval`; see [SFT guide §Model lifecycle](./sft.md). A dedicated eval stage that compiles a benchmark task list and submits through `nemo-evaluator-launcher` will land in a follow-up release. +- **Evaluation stage not yet included — coming soon.** The omni3 CLI doesn’t have an `eval` subcommand today. Multimodal sanity checks against a trained checkpoint run via `nemotron omni3 model eval`; see [SFT guide §Model lifecycle](/sft). A dedicated eval stage that compiles a benchmark task list and submits through `nemo-evaluator-launcher` will land in a follow-up release. + - **SFT default uses CORD-v2 (open); Valor32k is an opt-in.** `default.yaml` pulls [CORD-v2](https://huggingface.co/datasets/naver-clova-ix/cord-v2) from HuggingFace via the `vlm-hf` loader — no local shard building required. `-c valor32k` switches to the full audio-visual-language flow, but requires internal access to a prepared Valor32k-AVQA Energon dataset (the raw-shard builder is internal-only at release). `data_prep.py` validates the Energon path or emits a manifest for HF — it does not assemble shards. + - **Long-document SDG pipeline is a scaffold.** `src/nemotron/recipes/data/sdg/long-document/` has 9 numbered scripts with their argparse surfaces and a thorough README, but the script bodies raise `NotImplementedError` — port bodies from upstream at release time. See `designs/long-document-sdg-pipeline.md`. + - **Pinned to release branches.** The SFT Dockerfile pulls `github.com/NVIDIA-NeMo/Megatron-Bridge @ nemotron_3_omni` (and `github.com/NVIDIA/Megatron-LM @ nemotron_3_omni` as a recursive submodule fetch); the RL flow uses `github.com/NVIDIA/NeMo-RL @ nano-v3-omni`. These are the active release branches for Nemotron 3 Omni — bump to a versioned tag (or `main`) once these changes merge upstream. -The linked stage guides (SFT / RL / Evaluate) call out each stage's specific limitations. +The linked stage guides (SFT / RL / Evaluate) call out each stage’s specific limitations. ## Quick Start ### Prerequisites -- **Slurm cluster** with GPU nodes for SFT, RL, and evaluation — see [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) -- **[Weights & Biases](../wandb.md)** for experiment tracking and [artifact lineage](../artifacts.md) +- **Slurm cluster** with GPU nodes for SFT, RL, and evaluation — see [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) + +- **[Weights & Biases](/../wandb)** for experiment tracking and [artifact lineage](/../artifacts) + - **Build-capable execution profile** for `nemotron omni3 build ` jobs -- **GA checkpoint**: [nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16](https://huggingface.co/nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16) (BF16 weights). FP8 and NVFP4 quantization paths are supported by the inference engines listed in [`inference.md`](./inference.md#inference-engines). + +- **GA checkpoint**: [nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16](https://huggingface.co/nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16) (BF16 weights). FP8 and NVFP4 quantization paths are supported by the inference engines listed in [`inference.md`](/inference#inference-engines). ### Installation @@ -116,15 +129,14 @@ gpus_per_node = 8 mounts = ["/lustre:/lustre"] ``` -> See [How container builds authenticate](../../nemo_runspec/nemo-run.md#how-the-build-container-authenticates-with-private-registries) -> for how the dispatcher reuses your existing -> `~/.config/enroot/.credentials` to pull `nvcr.io` images inside the -> build container — no separate podman login required. +> See [How container builds authenticate](/../../nemo_runspec/nemo-run#how-the-build-container-authenticates-with-private-registries) +for how the dispatcher reuses your existing +`~/.config/enroot/.credentials` to pull `nvcr.io` images inside the +build container — no separate podman login required. ### Run the Pipeline
- ```console // Stage 0: SFT $ uv run nemotron omni3 build sft --run YOUR-CLUSTER @@ -150,25 +162,28 @@ $ uv run nemotron omni3 rl vision --run YOUR-CLUSTER ```
- -> **Note**: `omni3 build` submits a short CPU-only container build job through [NeMo-Run](../../nemo_runspec/nemo-run.md). The build produces `${build_cache_dir}/containers/omni3-{sft,rl}.sqsh` (squashfs) which pyxis mounts directly at training time — no per-job `enroot import`. +> **Note**: `omni3 build` submits a short CPU-only container build job through [NeMo-Run](/../../nemo_runspec/nemo-run). The build produces `$\{build_cache_dir\}/containers/omni3-\{sft,rl\}.sqsh` (squashfs) which pyxis mounts directly at training time — no per-job `enroot import`. ## Resources - **Model checkpoint**: [nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16](https://huggingface.co/nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16) + - **Release blog**: [NVIDIA Nemotron 3 Nano Omni — multimodal agent reasoning](https://developer.nvidia.com/blog/nvidia-nemotron-3-nano-omni-powers-multimodal-agent-reasoning-in-a-single-efficient-open-model/) -- **SFT recipe**: [Stage 0: SFT](./sft.md) -- **RL recipe**: [Stage 1: RL](./rl.md) + +- **SFT recipe**: [Stage 0: SFT](/sft) + +- **RL recipe**: [Stage 1: RL](/rl) + - **Image training data**: [`nvidia/Nemotron-Image-Training-v3`](https://huggingface.co/datasets/nvidia/Nemotron-Image-Training-v3) ## Training Pipeline | Stage | Name | Purpose | Guide | -|-------|------|---------|-------| -| 0 | [SFT](./sft.md) | Fine-tune the GA checkpoint on Valor32k and related multimodal variants | [sft.md](./sft.md) | -| 1 | [RL](./rl.md) | Multi-stage Omni RL: MPO → text RL → vision RL | [rl.md](./rl.md) | +| --- | --- | --- | --- | +| 0 | [SFT](/sft) | Fine-tune the GA checkpoint on Valor32k and related multimodal variants | [sft.md](/sft) | +| 1 | [RL](/rl) | Multi-stage Omni RL: MPO → text RL → vision RL | [rl.md](/rl) | -> An evaluation stage (`nemotron omni3 eval`) is on the roadmap; until it lands, run benchmarks via `nemotron omni3 model eval` (see [SFT guide §Model lifecycle](./sft.md)). +> An evaluation stage (`nemotron omni3 eval`) is on the roadmap; until it lands, run benchmarks via `nemotron omni3 model eval` (see [SFT guide §Model lifecycle](/sft)). ## Pipeline Overview @@ -192,44 +207,47 @@ flowchart LR The upstream synthetic-data pipeline lives outside the family tree under `src/nemotron/recipes/data/sdg/long-document/`. That keeps the recipe split explicit: -- **`src/nemotron/recipes/data/curation/`** — filter, dedup, and curate existing corpora (for example [Nemotron-CC](../data/curation/nemotron-cc.md)) +- **`src/nemotron/recipes/data/curation/`** — filter, dedup, and curate existing corpora (for example [Nemotron-CC](/../data/curation/nemotron-cc)) + - **`src/nemotron/recipes/data/sdg/`** — generate new datasets, including the long-document SDG pipeline consumed by Omni SFT + - **`src/nemotron/recipes/omni3/`** — family-specific training, RL, and evaluation stages ## Stage Summaries ### Stage 0: SFT -Omni SFT owns its own `Dockerfile`, `data_prep.py`, and `train.py` (built via the `nemotron omni3 build sft` dispatcher). The stage ports the Valor32k flow plus LoRA/PEFT variants for image-text and audio-text tuning. The released open-data configs target shorter sequence lengths; the upstream 16K → 49K → 262K progressive schedule is documented in [`architecture.md`](./architecture.md#progressive-context-scaling). +Omni SFT owns its own `Dockerfile`, `data_prep.py`, and `train.py` (built via the `nemotron omni3 build sft` dispatcher). The stage ports the Valor32k flow plus LoRA/PEFT variants for image-text and audio-text tuning. The released open-data configs target shorter sequence lengths; the upstream 16K → 49K → 262K progressive schedule is documented in [`architecture.md`](/architecture#progressive-context-scaling). -→ [SFT Guide](./sft.md) +→ [SFT Guide](/sft) ### Stage 1: RL The RL stack uses one shared NeMo-RL container and three sub-stages, mirroring the upstream [`nano-v3-omni` flow](https://github.com/NVIDIA-NeMo/RL/tree/nano-v3-omni): 1. **MPO** — multimodal preference optimization on the public MMPR dataset (~83K-row preference triples per subset) + 2. **Text RL** — GRPO continuation of alignment on `nvidia/Nemotron-3-Nano-RL-Training-Blend` + 3. **Vision RL** — GRPO on MMPR-Tiny (data prep ready; training launcher pending upstream) The 20 RL datasets / 25 environments / ~2.3M rollouts referenced in the [release blog](https://developer.nvidia.com/blog/nvidia-nemotron-3-nano-omni-powers-multimodal-agent-reasoning-in-a-single-efficient-open-model/) compose the full upstream alignment corpus; this recipe surfaces the public/open-source subset. -→ [RL Guide](./rl.md) · [RL Data Prep](./rl/data-prep.md) +→ [RL Guide](/rl) · [RL Data Prep](/rl/data-prep) ## Execution Options -All Omni commands support [NeMo-Run](../../nemo_runspec/nemo-run.md) execution modes: +All Omni commands support [NeMo-Run](/../../nemo_runspec/nemo-run) execution modes: | Option | Behavior | Use Case | -|--------|----------|----------| -| `--run ` | Attached—submits job and streams logs | Interactive development | -| `--batch ` | Detached—submits and exits immediately | Long-running jobs | -| `--dry-run` | Preview resolved config or build plan | Validation | +| --- | --- | --- | +| --run <profile> | Attached—submits job and streams logs | Interactive development | +| --batch <profile> | Detached—submits and exits immediately | Long-running jobs | +| --dry-run | Preview resolved config or build plan | Validation | ## CLI Reference
- ```console $ uv run nemotron omni3 --help Usage: nemotron omni3 [OPTIONS] COMMAND [ARGS]... @@ -250,23 +268,18 @@ Usage: nemotron omni3 [OPTIONS] COMMAND [ARGS]... ```
- ## Further Reading -- [Stage 0: SFT](./sft.md) -- [Stage 1: RL](./rl.md) -- [Architecture](./architecture.md) -- [Inference & Deployment](./inference.md) -- [Artifact Lineage](../artifacts.md) -- [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) -- [W&B Integration](../wandb.md) - -```{toctree} -:hidden: - -sft.md -rl.md -rl/data-prep.md -architecture.md -inference.md -``` +- [Stage 0: SFT](/sft) + +- [Stage 1: RL](/rl) + +- [Architecture](/architecture) + +- [Inference & Deployment](/inference) + +- [Artifact Lineage](/../artifacts) + +- [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) + +- [W&B Integration](/../wandb) diff --git a/docs/nemotron/omni3/architecture.md b/docs/fern/pages-vnightly/nemotron/omni3/architecture.mdx similarity index 63% rename from docs/nemotron/omni3/architecture.md rename to docs/fern/pages-vnightly/nemotron/omni3/architecture.mdx index d11eec840..3b1366b2e 100644 --- a/docs/nemotron/omni3/architecture.md +++ b/docs/fern/pages-vnightly/nemotron/omni3/architecture.mdx @@ -1,15 +1,19 @@ -# Nemotron 3 Nano Omni — Architecture +--- +title: "Nemotron 3 Nano Omni — Architecture" +slug: "nemotron/omni3/architecture.html" +description: "A deep-dive into the architectural decisions behind Nemotron 3 Nano Omni — what’s in the model, why each piece is there, and where the efficiency story comes from. For training instructions see the re" +--- -A deep-dive into the architectural decisions behind Nemotron 3 Nano Omni — what's in the model, why each piece is there, and where the efficiency story comes from. For training instructions see the [recipe overview](./README.md); for deployment see [`inference.md`](./inference.md). +A deep-dive into the architectural decisions behind Nemotron 3 Nano Omni — what’s in the model, why each piece is there, and where the efficiency story comes from. For training instructions see the [recipe overview](/README); for deployment see [`inference.md`](/inference). -![Nemotron 3 Nano Omni hybrid MoE architecture: Parakeet audio encoder → audio adaptor, C-RADIOv4-H vision encoder + 3D convolution + Efficient Video Sampling → vision adaptor, text tokenizer, all feeding the unified 30B-A3B LLM decoder](../../assets/omni-3.png) +![Nemotron 3 Nano Omni hybrid MoE architecture: Parakeet audio encoder → audio adaptor, C-RADIOv4-H vision encoder + 3D convolution + Efficient Video Sampling → vision adaptor, text tokenizer, all feeding the unified 30B-A3B LLM decoder](../../../_images/omni-3.png) *Figure 1. Cross-modal integration. Each modality has a dedicated encoder and adaptor; all token streams converge on the unified 30B-A3B Mamba-transformer decoder, which is the only place reasoning happens.* ## Hybrid MoE decoder | Property | Value | -|---|---| +| --- | --- | | Total parameters | 30B | | Active parameters per forward pass | 3B | | Architecture | Hybrid MoE | @@ -18,11 +22,11 @@ A deep-dive into the architectural decisions behind Nemotron 3 Nano Omni — wha | Max context length | 262K tokens | | Training context schedule | 16K → 49K → 262K (progressive scaling, see [§Progressive context scaling](#progressive-context-scaling)) | -The "A3B" in the model name (`30B-A3B`) means **30B total parameters / 3B active**: the MoE router selects a small subset of expert layers per token, so inference compute is bounded by the 3B active count rather than the 30B total. The Mamba layers handle long-context state with linear time/memory; the transformer layers handle the local-reasoning hot path. The two compose into a unified decoder that all modality encoders feed into — so reasoning, planning, and tool-calling stay in one place rather than fanning out to per-modality heads. +The “A3B” in the model name (`30B-A3B`) means **30B total parameters / 3B active**: the MoE router selects a small subset of expert layers per token, so inference compute is bounded by the 3B active count rather than the 30B total. The Mamba layers handle long-context state with linear time/memory; the transformer layers handle the local-reasoning hot path. The two compose into a unified decoder that all modality encoders feed into — so reasoning, planning, and tool-calling stay in one place rather than fanning out to per-modality heads. ## Vision encoder — C-RADIOv4-H -The vision side uses **C-RADIOv4-H**, a high-resolution image encoder. It's the same family as RADIO (Robust Anti-Distillation On vision foundation models) — a learned distillation across multiple frozen teacher models (CLIP, DINOv2, SAM, etc.) that produces a single ViT capable of standing in for any of them. The "v4-H" variant is the high-res release with stronger document-understanding signal, which is part of why omni places best-in-class on **MMlongbench-Doc** and **OCRBenchV2**. +The vision side uses **C-RADIOv4-H**, a high-resolution image encoder. It’s the same family as RADIO (Robust Anti-Distillation On vision foundation models) — a learned distillation across multiple frozen teacher models (CLIP, DINOv2, SAM, etc.) that produces a single ViT capable of standing in for any of them. The “v4-H” variant is the high-res release with stronger document-understanding signal, which is part of why omni places best-in-class on **MMlongbench-Doc** and **OCRBenchV2**. ## Audio encoder — Parakeet (extended) @@ -33,41 +37,45 @@ Audio uses **NVIDIA Parakeet** as the encoder, extended via the **Granary** and Video is handled in two stages: **3D convolutions** capture spatiotemporal features natively (motion is a first-class signal, not inferred from a frame-by-frame transcript), and an **Efficient Video Sampling (EVS) layer** compresses high-density visual tokens across consecutive frames before they hit the decoder. This is the key efficiency lever for the model. The release blog cites: + - **~9.2× greater effective system capacity** vs. comparable open omni models on video reasoning workloads + - **~7.4× greater capacity** on multi-document workloads -- **"Highest throughput across every task"** in the MediaPerf benchmark, **"lowest inference cost for video-level tagging"** + +- **“Highest throughput across every task”** in the MediaPerf benchmark, **“lowest inference cost for video-level tagging”** Why 3D conv + EVS is decisive vs. transcript-style approaches: -- **3D conv preserves motion**. Frame-by-frame transcript pipelines can't see motion natively — they hallucinate temporal relations from spatial features in adjacent frames. Native 3D conv gives the decoder real motion features. +- **3D conv preserves motion**. Frame-by-frame transcript pipelines can’t see motion natively — they hallucinate temporal relations from spatial features in adjacent frames. Native 3D conv gives the decoder real motion features. + - **EVS bounds the token count**. Without EVS, a 60-second video at 24 fps × per-frame patch count blows past 262K tokens trivially. EVS compresses frame redundancy *before* the decoder, so the unified text decoder can still reason over the full clip in-context. -If you're doing video-heavy inference and tuning for throughput, EVS configuration is the lever to optimize — see [`inference.md`](./inference.md) for runtime knobs. +If you’re doing video-heavy inference and tuning for throughput, EVS configuration is the lever to optimize — see [`inference.md`](/inference) for runtime knobs. ## Progressive context scaling -The **16K → 49K → 262K** sequence is a *training schedule*, not a property of the inference model. The training pipeline grows the context window in stages so the model first masters short-context cross-modal instruction-following, then extends to medium context, and finally to long context — each stage unfreezing more parameters as needed. This is the same recipe shape used by Nemotron 3 Nano's pretrain → SFT → RL flow, scaled to the multimodal case. +The **16K → 49K → 262K** sequence is a *training schedule*, not a property of the inference model. The training pipeline grows the context window in stages so the model first masters short-context cross-modal instruction-following, then extends to medium context, and finally to long context — each stage unfreezing more parameters as needed. This is the same recipe shape used by Nemotron 3 Nano’s pretrain → SFT → RL flow, scaled to the multimodal case. > **Implementation note for this recipe folder.** The released configs in -> `src/nemotron/recipes/omni3/stage0_sft/config/` target shorter context -> lengths than the upstream 49K/262K stages — those longer-context -> schedules use additional internal data and aren't fully reproducible -> from the open-source subset. The `default.yaml` open-data flow trains -> the projector only on CORD-v2 with the GA model frozen; longer-context -> stages are documented here for completeness but ship as configuration -> stubs. Operators with internal data access can reproduce them by -> bumping `seq_length` and the data path. See -> [`docs/nemotron/omni3/sft.md`](./sft.md#config-variants) for the -> per-config breakdown. +`src/nemotron/recipes/omni3/stage0_sft/config/` target shorter context +lengths than the upstream 49K/262K stages — those longer-context +schedules use additional internal data and aren’t fully reproducible +from the open-source subset. The `default.yaml` open-data flow trains +the projector only on CORD-v2 with the GA model frozen; longer-context +stages are documented here for completeness but ship as configuration +stubs. Operators with internal data access can reproduce them by +bumping `seq_length` and the data path. See +[`docs/nemotron/omni3/sft.md`](/sft#config-variants) for the +per-config breakdown. ## Synthetic data — long-document SDG -The release blog calls out **~11.4M synthetic visual QA pairs (~45B tokens)** generated via NVIDIA NeMo Data Designer. The long-document SDG recipe is published in this repository ([guide](../data/sdg/long-document.md), [source](https://github.com/NVIDIA-NeMo/Nemotron/tree/main/src/nemotron/recipes/data/sdg/long-document)) — a 9-stage pipeline with structured argparse surfaces. +The release blog calls out **~11.4M synthetic visual QA pairs (~45B tokens)** generated via NVIDIA NeMo Data Designer. The long-document SDG recipe is published in this repository ([guide](/../data/sdg/long-document), [source](https://github.com/NVIDIA-NeMo/Nemotron/tree/main/src/nemotron/recipes/data/sdg/long-document)) — a 9-stage pipeline with structured argparse surfaces. ## Training scale (release figures) | Stage | Scale | -|---|---| +| --- | --- | | Adapter & encoder training | ~127B tokens, mixed modalities (text+image, text+video, text+audio, text+video+audio) | | Curated post-training examples | ~124M | | RL alignment | 20 datasets across 25 environments, ~2.3M rollouts | @@ -75,16 +83,19 @@ The release blog calls out **~11.4M synthetic visual QA pairs (~45B tokens)** ge This recipe folder reproduces the **public-data subset** of these stages — see each stage doc for which datasets are open-source vs. internal-only. -## Why "perception sub-agent" +## Why “perception sub-agent” The release blog frames omni as a **multimodal perception sub-agent for agentic AI** — *not* a general-purpose chat model. The architecture choices follow: - **Single unified decoder** so an outer agent can call this model with any combination of modalities and get reasoning back through one stable interface + - **EVS-bounded video tokens** so the model can be invoked on full-length video inputs without per-clip pre-processing pipelines + - **Reasoning-trained checkpoint** (`Reasoning-BF16` suffix) for explicit multi-step thinking before tool calls + - **NIM + open-license** so it can drop into existing agent stacks (LangChain, LlamaIndex, custom orchestrators) without licensing friction -Stage docs ([`sft.md`](./sft.md), [`rl.md`](./rl.md)) train and align this perception-sub-agent surface — instruction-following over multimodal inputs, not free-form chat. +Stage docs ([`sft.md`](/sft), [`rl.md`](/rl)) train and align this perception-sub-agent surface — instruction-following over multimodal inputs, not free-form chat. ## License @@ -93,7 +104,11 @@ The model is released under the **NVIDIA Nemotron Open Model License**, which pe ## References - **[Release blog](https://developer.nvidia.com/blog/nvidia-nemotron-3-nano-omni-powers-multimodal-agent-reasoning-in-a-single-efficient-open-model/)** — the canonical positioning + benchmark source for this doc + - **[Model weights — `nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16`](https://huggingface.co/nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16)** + - **[Image training data — `nvidia/Nemotron-Image-Training-v3`](https://huggingface.co/datasets/nvidia/Nemotron-Image-Training-v3)** + - **Upstream pre-training recipe**: [`NVIDIA-NeMo/Megatron-Bridge` `nemotron_3_omni`](https://github.com/NVIDIA-NeMo/Megatron-Bridge/tree/nemotron_3_omni/examples/models/vlm/nemotron_3_omni) + - **Upstream RL recipe**: [`NVIDIA-NeMo/RL` `nano-v3-omni`](https://github.com/NVIDIA-NeMo/RL/tree/nano-v3-omni) diff --git a/docs/nemotron/omni3/inference.md b/docs/fern/pages-vnightly/nemotron/omni3/inference.mdx similarity index 60% rename from docs/nemotron/omni3/inference.md rename to docs/fern/pages-vnightly/nemotron/omni3/inference.mdx index 306762161..044bb1e24 100644 --- a/docs/nemotron/omni3/inference.md +++ b/docs/fern/pages-vnightly/nemotron/omni3/inference.mdx @@ -1,17 +1,21 @@ -# Nemotron 3 Nano Omni — Inference & Deployment +--- +title: "Nemotron 3 Nano Omni — Inference & Deployment" +slug: "nemotron/omni3/inference.html" +description: "How to deploy and serve Nemotron 3 Nano Omni after training (or against the public release checkpoint). For training instructions see the recipe overview; for architectural background see architecture" +--- -How to deploy and serve Nemotron 3 Nano Omni after training (or against the public release checkpoint). For training instructions see the [recipe overview](./README.md); for architectural background see [`architecture.md`](./architecture.md). +How to deploy and serve Nemotron 3 Nano Omni after training (or against the public release checkpoint). For training instructions see the [recipe overview](/README); for architectural background see [`architecture.md`](/architecture). ## TL;DR | If you want… | Use | -|---|---| -| Drop-in agent endpoint | NIM at [`build.nvidia.com`](https://build.nvidia.com) | +| --- | --- | +| Drop-in agent endpoint | NIM at [build.nvidia.com](https://build.nvidia.com) | | Production high-throughput serving | TensorRT-LLM (Hopper / Blackwell) with NVFP4 | | Continuous batching + streaming | vLLM | | Multi-agent + tool-calling, lightweight | SGLang | | Disaggregated serving with intelligent routing | Dynamo | -| Local laptop inference | Ollama or `llama.cpp` (GGUF) | +| Local laptop inference | Ollama or llama.cpp (GGUF) | | Local desktop UI | LM Studio | | Managed cloud | Amazon SageMaker JumpStart, Oracle Cloud, Microsoft Azure (coming soon), Dell on-premises | | Privacy-first video processing | NemoClaw sandbox (sandboxed video analysis with policy-bounded output) | @@ -19,19 +23,20 @@ How to deploy and serve Nemotron 3 Nano Omni after training (or against the publ ## Inference engines | Engine | Strengths | Hardware | Quantization | -|---|---|---|---| +| --- | --- | --- | --- | | **vLLM** | Continuous batching, streaming, broad ecosystem | Ampere / Hopper / Blackwell | FP8, NVFP4 | | **SGLang** | Lightweight, strong multi-agent + tool-calling story | Ampere / Hopper / Blackwell | FP8, NVFP4 | | **NVIDIA TensorRT-LLM** | Lowest-latency production serving, latent MoE kernels | Hopper / Blackwell | FP8, NVFP4 | | **Dynamo** | Disaggregated serving, intelligent routing, multi-tier KV caching | Hopper / Blackwell | FP8, NVFP4 | -Pyxis-mounting the trained `omni3-sft.sqsh` from this repo's training pipeline produces a container compatible with all four engines — see the engine documentation for serving entry points. For the open release checkpoint, pull `nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16` from Hugging Face directly and let the engine handle weight loading + (optional) on-the-fly quantization. +Pyxis-mounting the trained `omni3-sft.sqsh` from this repo’s training pipeline produces a container compatible with all four engines — see the engine documentation for serving entry points. For the open release checkpoint, pull `nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16` from Hugging Face directly and let the engine handle weight loading + (optional) on-the-fly quantization. ## Quantization The model supports two quantization paths out of the box: - **FP8** — works on Hopper and Blackwell; ~2× memory reduction over BF16 with minimal quality loss for this model class + - **NVFP4** — Blackwell-only; produces the highest reported throughput among open omnimodal models per the release blog Quantization is applied at the inference-engine level, not as separately published HF checkpoints. All four engines above support both formats. For Blackwell + NVFP4 specifically, the release blog reports the highest throughput of any open omnimodal model in this class. @@ -39,7 +44,7 @@ Quantization is applied at the inference-engine level, not as separately publish ## Hardware | Family | Supported | Notes | -|---|---|---| +| --- | --- | --- | | Ampere (A100, A40, …) | ✅ | BF16 / FP8; older GPUs lack NVFP4 hardware | | Hopper (H100, H200) | ✅ | All paths supported; FP8 most efficient | | Blackwell (B100, B200, GB200) | ✅ | NVFP4 unlocks peak throughput | @@ -47,8 +52,8 @@ Quantization is applied at the inference-engine level, not as separately publish ## Cloud platforms | Platform | Status | Path | -|---|---|---| -| Amazon SageMaker JumpStart | Available | Search for `Nemotron-3-Nano-Omni` in JumpStart catalog | +| --- | --- | --- | +| Amazon SageMaker JumpStart | Available | Search for Nemotron-3-Nano-Omni in JumpStart catalog | | Oracle Cloud | Available | OCI AI services | | Microsoft Azure | Coming soon (per release blog) | Azure AI catalog | | Dell Technologies | Available (on-premises / hybrid) | Dell AI Factory | @@ -59,14 +64,14 @@ The model is hosted by: - **Baseten**, **Clarifai**, **DeepInfra**, **Fireworks AI**, **Together AI**, **Vultr**, **Bitdeer**, **Crusoe**, **DigitalOcean**, **Lightning AI**, **Nebius** -These provide managed endpoints if you don't want to run inference yourself. +These provide managed endpoints if you don’t want to run inference yourself. ## Local / edge | Format | Tool | Notes | -|---|---|---| -| GGUF | **`llama.cpp`** | Quantized weights for CPU / Apple Silicon / consumer GPU | -| GGUF | **Ollama** | Wraps `llama.cpp`; one-line model pull + chat | +| --- | --- | --- | +| GGUF | **llama.cpp** | Quantized weights for CPU / Apple Silicon / consumer GPU | +| GGUF | **Ollama** | Wraps llama.cpp; one-line model pull + chat | | Native | **LM Studio** | Desktop UI for local inference | | Inference Snaps | NVIDIA Inference Snaps | Pre-packaged endpoints for edge deployment | @@ -74,26 +79,28 @@ These are best for local development, offline analysis, or edge inference where ## NemoClaw — privacy-first video processing -For workloads where video frames can't leave a sandboxed environment (compliance, healthcare, classified content), the model integrates with **NemoClaw**, NVIDIA's sandboxed video-processing layer. The sandbox runs the perception model, then exports only policy-bounded outputs (transcripts, summaries, structured tags) — raw frames stay inside. +For workloads where video frames can’t leave a sandboxed environment (compliance, healthcare, classified content), the model integrates with **NemoClaw**, NVIDIA’s sandboxed video-processing layer. The sandbox runs the perception model, then exports only policy-bounded outputs (transcripts, summaries, structured tags) — raw frames stay inside. -This is a distinguishing capability for the model's "perception sub-agent" framing: a downstream agent can invoke the omni model on private video content and get usable summaries back without ever handling raw frames itself. +This is a distinguishing capability for the model’s “perception sub-agent” framing: a downstream agent can invoke the omni model on private video content and get usable summaries back without ever handling raw frames itself. ## Tuning notes - **Per-user interactivity**: the release blog reports throughput numbers at a fixed per-user tokens-per-second floor; aggregate throughput scales by holding user-level interactivity constant and adding concurrency. -- **EVS configuration**: for video-heavy workloads, the EVS layer's frame-compression ratio is the most important throughput knob (see [`architecture.md` §Video pipeline](./architecture.md#video-pipeline--3d-convolutions--efficient-video-sampling-evs) for the why). Lower compression → higher quality, lower throughput; tune per workload. + +- **EVS configuration**: for video-heavy workloads, the EVS layer’s frame-compression ratio is the most important throughput knob (see [`architecture.md` §Video pipeline](/architecture#video-pipeline-3d-convolutions-efficient-video-sampling-evs) for the why). Lower compression → higher quality, lower throughput; tune per workload. + - **MoE expert dispatch**: the 30B-A3B router is sensitive to batch composition. For peak throughput, group requests with similar modality mix. -## Deployment from this recipe's training output +## Deployment from this recipe’s training output -The training pipeline in this repo produces `${build_cache_dir}/containers/omni3-sft.sqsh`, a squashfs container that pyxis mounts directly. To use it for inference: +The training pipeline in this repo produces `$\{build_cache_dir\}/containers/omni3-sft.sqsh`, a squashfs container that pyxis mounts directly. To use it for inference: ```bash # Verify the squashfs is in place -ls -lh ${build_cache_dir}/containers/omni3-sft.sqsh +ls -lh $\{build_cache_dir\}/containers/omni3-sft.sqsh # Submit an inference job (example with vLLM) -srun --container-image=${build_cache_dir}/containers/omni3-sft.sqsh \ +srun --container-image=$\{build_cache_dir\}/containers/omni3-sft.sqsh \ --container-mounts=/lustre:/lustre,/path/to/checkpoint:/checkpoint \ bash -lc 'vllm serve /checkpoint --tensor-parallel-size 1 --gpu-memory-utilization 0.9' ``` @@ -103,6 +110,9 @@ For benchmark evaluation against a deployed checkpoint, run `nemotron omni3 mode ## References - **[Release blog](https://developer.nvidia.com/blog/nvidia-nemotron-3-nano-omni-powers-multimodal-agent-reasoning-in-a-single-efficient-open-model/)** — canonical source for the throughput claims, provider list, and deployment paths + - **[NIM at build.nvidia.com](https://build.nvidia.com)** + - **[Model weights](https://huggingface.co/nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16)** -- [`architecture.md`](./architecture.md) — the *why* behind the inference characteristics + +- [`architecture.md`](/architecture) — the *why* behind the inference characteristics diff --git a/docs/nemotron/omni3/rl.md b/docs/fern/pages-vnightly/nemotron/omni3/rl.mdx similarity index 62% rename from docs/nemotron/omni3/rl.md rename to docs/fern/pages-vnightly/nemotron/omni3/rl.mdx index 9d19ef2c5..3f8409dd7 100644 --- a/docs/nemotron/omni3/rl.md +++ b/docs/fern/pages-vnightly/nemotron/omni3/rl.mdx @@ -1,13 +1,20 @@ -# Stage 1: Reinforcement Learning (RL) +--- +title: "Stage 1: Reinforcement Learning (RL)" +slug: "nemotron/omni3/rl.html" +description: "Omni RL continues the multimodal post-training pipeline with NeMo-RL using one shared container and three explicit sub-stages. RL aligns the model’s perception-sub-agent surface — preference quality o" +--- -Omni RL continues the multimodal post-training pipeline with [NeMo-RL](../nvidia-stack.md#nemo-rl) using one shared container and three explicit sub-stages. RL aligns the model's perception-sub-agent surface — preference quality on visual reasoning, factual grounding for downstream agent calls, and ASR fidelity. The full upstream alignment corpus runs **~2.3M rollouts across 20 RL datasets / 25 environments** covering visual grounding, charts, vision-critical STEM, video understanding, and ASR (per the [release blog](https://developer.nvidia.com/blog/nvidia-nemotron-3-nano-omni-powers-multimodal-agent-reasoning-in-a-single-efficient-open-model/)). This recipe folder surfaces the **3 of 25** environments that have public data: MMPR (preference), the Nano RL training blend (text), and MMPR-Tiny (vision); the remaining 22 environments use internal or third-party data and aren't included. +Omni RL continues the multimodal post-training pipeline with [NeMo-RL](/../nvidia-stack#nemo-rl) using one shared container and three explicit sub-stages. RL aligns the model’s perception-sub-agent surface — preference quality on visual reasoning, factual grounding for downstream agent calls, and ASR fidelity. The full upstream alignment corpus runs **~2.3M rollouts across 20 RL datasets / 25 environments** covering visual grounding, charts, vision-critical STEM, video understanding, and ASR (per the [release blog](https://developer.nvidia.com/blog/nvidia-nemotron-3-nano-omni-powers-multimodal-agent-reasoning-in-a-single-efficient-open-model/)). This recipe folder surfaces the **3 of 25** environments that have public data: MMPR (preference), the Nano RL training blend (text), and MMPR-Tiny (vision); the remaining 22 environments use internal or third-party data and aren’t included. > **Shared container**: All RL sub-stages use `src/nemotron/recipes/omni3/stage1_rl/Dockerfile`. The `nemotron omni3 build rl` dispatcher turns it into `omni3-rl.sqsh` under your `build_cache_dir`. -> **Current notes** (also summarized in the [family README](./README.md#current-limitations)): -> - **All three sub-stages have working launchers** that mirror the upstream NeMo-RL `nano-v3-omni` flow (`scripts/nanov3_mpo.sh`, `scripts/nanov3_text_rl.sh`, `scripts/nanov3_vision_rl.sh`). -> - **`stage1_rl/Dockerfile` mirrors NeMo-RL's release Dockerfile** — clones `NVIDIA/NeMo-RL @ nano-v3-omni` recursively (carrying the [omni vllm fork](https://github.com/aroshanghias-nvd/vllm) as a `3rdparty/vllm` submodule) and runs the same `BUILD_CUSTOM_VLLM=1` + `uv sync` flow as the upstream `docker/Dockerfile`. `omni3 build rl` produces `omni3-rl.sqsh`. -> - **`nano-v3-omni` is the active release branch for Nemotron 3 Omni**; bump to a versioned tag (or `main`) once these changes merge upstream. +> **Current notes** (also summarized in the [family README](/README#current-limitations)): + +- **All three sub-stages have working launchers** that mirror the upstream NeMo-RL `nano-v3-omni` flow (`scripts/nanov3_mpo.sh`, `scripts/nanov3_text_rl.sh`, `scripts/nanov3_vision_rl.sh`). + +- **`stage1_rl/Dockerfile` mirrors NeMo-RL’s release Dockerfile** — clones `NVIDIA/NeMo-RL @ nano-v3-omni` recursively (carrying the [omni vllm fork](https://github.com/aroshanghias-nvd/vllm) as a `3rdparty/vllm` submodule) and runs the same `BUILD_CUSTOM_VLLM=1` + `uv sync` flow as the upstream `docker/Dockerfile`. `omni3 build rl` produces `omni3-rl.sqsh`. + +- **`nano-v3-omni` is the active release branch for Nemotron 3 Omni**; bump to a versioned tag (or `main`) once these changes merge upstream. --- @@ -30,20 +37,20 @@ flowchart LR The shared RL tree contains: | Path | Purpose | -|------|---------| -| `stage1_rl/Dockerfile` | Shared NeMo-RL Omni image | -| `stage1_rl/data_prep.py` | Dispatcher for `-c mpo` / `-c text` / `-c vision` | -| `stage1_rl/stage1_mpo/` | MPO launcher, config, and data prep | -| `stage1_rl/stage2_text_rl/` | Text RL launcher, config, and data prep | -| `stage1_rl/stage3_vision_rl/` | Vision RL launcher stub, config, and data prep | +| --- | --- | +| stage1_rl/Dockerfile | Shared NeMo-RL Omni image | +| stage1_rl/data_prep.py | Dispatcher for -c mpo / -c text / -c vision | +| stage1_rl/stage1_mpo/ | MPO launcher, config, and data prep | +| stage1_rl/stage2_text_rl/ | Text RL launcher, config, and data prep | +| stage1_rl/stage3_vision_rl/ | Vision RL launcher stub, config, and data prep | ## Sub-Stages | Sub-stage | Command | Default input model | Data prep config | Notes | -|-----------|---------|---------------------|------------------|-------| -| MPO | `nemotron omni3 rl mpo` | `omni3-sft-model:latest` | `-c mpo` | Public MMPR preference optimization | -| Text RL | `nemotron omni3 rl text` | `omni3-rl-mpo-model:latest` | `-c text` | Continues alignment on text-only RL data | -| Vision RL | `nemotron omni3 rl vision` | `omni3-rl-text-model:latest` | `-c vision` | Data prep is wired; training launcher is still upstream-stubbed | +| --- | --- | --- | --- | --- | +| MPO | nemotron omni3 rl mpo | omni3-sft-model:latest | -c mpo | Public MMPR preference optimization | +| Text RL | nemotron omni3 rl text | omni3-rl-mpo-model:latest | -c text | Continues alignment on text-only RL data | +| Vision RL | nemotron omni3 rl vision | omni3-rl-text-model:latest | -c vision | Data prep is wired; training launcher is still upstream-stubbed | ## Build the Shared RL Container @@ -69,7 +76,6 @@ podman build -t nemotron/omni3-rl:latest -f Dockerfile . ## Quick Start
- ```console // 1. Build the shared RL container $ uv run nemotron omni3 build rl --run YOUR-CLUSTER @@ -88,7 +94,6 @@ $ uv run nemotron omni3 rl vision --run YOUR-CLUSTER ```
- ## Data Preparation Use one CLI command with config variants: @@ -102,19 +107,19 @@ uv run nemotron omni3 data prep rl -c vision --run YOUR-CLUSTER The configs under `stage1_rl/config/data_prep/` map to: | Config | Source | Output | -|--------|--------|--------| -| `mpo.yaml` | `hf://OpenGVLab/MMPR` (auto-downloads via `source_uri`) | `MMPR-v1.2/` cache + rewritten `meta_public.json` | -| `text.yaml` | `hf://nvidia/Nemotron-3-Nano-RL-Training-Blend` (resolved through Nano3's HF placeholder pipeline) | per-blend train/val JSONL with `responses_create_params` schema | -| `vision.yaml` | `hf://OpenGVLab/MMPR-Tiny` (auto-downloads via `source_uri`) | `MMPR-Tiny/` cache + parquet + preview | +| --- | --- | --- | +| mpo.yaml | hf://OpenGVLab/MMPR (auto-downloads via source_uri) | MMPR-v1.2/ cache + rewritten meta_public.json | +| text.yaml | hf://nvidia/Nemotron-3-Nano-RL-Training-Blend (resolved through Nano3’s HF placeholder pipeline) | per-blend train/val JSONL with responses_create_params schema | +| vision.yaml | hf://OpenGVLab/MMPR-Tiny (auto-downloads via source_uri) | MMPR-Tiny/ cache + parquet + preview | When `input_dir` is empty/incomplete and `source_uri` is set, the dispatcher snapshot-downloads the HF repo before the prep stage runs. Pre-stage data manually (or set `OMNI3_MMPR_PUBLIC_RAW` / `OMNI3_MMPR_TINY_RAW`) to skip the download. -> **See [data-prep.md](rl/data-prep.md)** for the full data-prep guide: -> auto-download semantics, helper scripts under `scripts/`, output -> layouts, artifact registration, and parallel-submission notes. +> **See [data-prep.md](/rl/data-prep)** for the full data-prep guide: +auto-download semantics, helper scripts under `scripts/`, output +layouts, artifact registration, and parallel-submission notes. ## Stage-Specific Notes @@ -127,9 +132,13 @@ MPO uses the SFT checkpoint as input and launches `bash scripts/omni/step_1_nano Text RL consumes the MPO checkpoint and exposes the key launcher overrides described in the design doc: - `CONTEXT_PARALLEL_SIZE` + - `TRAIN_GLOBAL_BATCH_SIZE` + - `NUM_PROMPTS_PER_STEP` + - `NUM_GENERATIONS_PER_PROMPT` + - `WANDB_PROJECT` ### Vision RL @@ -137,7 +146,9 @@ Text RL consumes the MPO checkpoint and exposes the key launcher overrides descr The vision stage is intentionally honest about its current status: - data prep is implemented + - the command exists and resolves the expected config + - `train.py` raises `NotImplementedError` until the upstream launcher lands That keeps the pipeline wiring visible without pretending the missing upstream piece is available yet. @@ -147,10 +158,10 @@ That keeps the pipeline wiring visible without pretending the missing upstream p This stage uses: | Component | Role | Documentation | -|-----------|------|---------------| -| [NeMo-RL](../nvidia-stack.md#nemo-rl) | RL trainers and launch scripts | [Docs](https://docs.nvidia.com/nemo/rl/latest/) | +| --- | --- | --- | +| [NeMo-RL](/../nvidia-stack#nemo-rl) | RL trainers and launch scripts | [Docs](https://docs.nvidia.com/nemo/rl/latest/) | | [Ray](https://ray.io/) | Distributed execution for RL and data prep | [Docs](https://docs.ray.io/) | -| [Megatron-Core](../nvidia-stack.md#megatron-core) | Distributed training backend | [GitHub](https://github.com/NVIDIA/Megatron-LM) | +| [Megatron-Core](/../nvidia-stack#megatron-core) | Distributed training backend | [GitHub](https://github.com/NVIDIA/Megatron-LM) | ## Next Steps @@ -171,9 +182,15 @@ to a versioned tag. ## Reference - **Recipe source:** [`src/nemotron/recipes/omni3/stage1_rl/`](https://github.com/NVIDIA-NeMo/Nemotron/tree/main/src/nemotron/recipes/omni3/stage1_rl) ([README](https://github.com/NVIDIA-NeMo/Nemotron/blob/main/src/nemotron/recipes/omni3/stage1_rl/README.md)) + - **Upstream**: [NeMo-RL `nano-v3-omni` guide](https://github.com/NVIDIA-NeMo/RL/blob/nano-v3-omni/docs/guides/nemotron-3-nano-omni.md) -- [RL data prep deep-dive](./rl/data-prep.md) -- [Architecture deep-dive](./architecture.md) -- [Inference & deployment](./inference.md) -- [Back to Overview](./README.md) -- [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) + +- [RL data prep deep-dive](/rl/data-prep) + +- [Architecture deep-dive](/architecture) + +- [Inference & deployment](/inference) + +- [Back to Overview](/README) + +- [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) diff --git a/docs/nemotron/omni3/rl/data-prep.md b/docs/fern/pages-vnightly/nemotron/omni3/rl/data-prep.mdx similarity index 67% rename from docs/nemotron/omni3/rl/data-prep.md rename to docs/fern/pages-vnightly/nemotron/omni3/rl/data-prep.mdx index 564fba86b..349d448f7 100644 --- a/docs/nemotron/omni3/rl/data-prep.md +++ b/docs/fern/pages-vnightly/nemotron/omni3/rl/data-prep.mdx @@ -1,15 +1,19 @@ -# RL Data Preparation +--- +title: "RL Data Preparation" +slug: "nemotron/omni3/rl/data-prep.html" +description: "The omni3 RL pipeline has three sub-stages (MPO, text RL, vision RL), each backed by its own dataset and prep flow. The CLI dispatches by -c {mpo|text|vision} and routes through a single shared data_p" +--- The omni3 RL pipeline has three sub-stages (MPO, text RL, vision RL), each backed by its own dataset and prep flow. The CLI dispatches by -`-c {mpo|text|vision}` and routes through a single shared +`-c \{mpo|text|vision\}` and routes through a single shared `data_prep.py` driver. | Sub-stage | Source | Cache shape | Backed by | -|-----------|--------|-------------|-----------| -| `mpo` | `hf://OpenGVLab/MMPR` (full preference dataset) | `MMPR/images/` + `MMPR/annotations/` + `meta_public.json` | Vendored `scripts/prepare_public_mmpr_for_mpo.py` (subprocess inside a Xenna stage) | -| `text` | `hf://nvidia/Nemotron-3-Nano-RL-Training-Blend` | per-blend train/val JSONL with `responses_create_params` schema | Shared with Nano3's text-RL recipe (`run_rl_resolve_pipeline`) | -| `vision` | `hf://OpenGVLab/MMPR-Tiny` | `MMPR-Tiny/images/` + `mmpr_tiny.parquet` + preview JSONL | In-tree `VlmPreferencePrepStage(flavor="tiny")` (no shell-out) | +| --- | --- | --- | --- | +| mpo | hf://OpenGVLab/MMPR (full preference dataset) | MMPR/images/ + MMPR/annotations/ + meta_public.json | Vendored scripts/prepare_public_mmpr_for_mpo.py (subprocess inside a Xenna stage) | +| text | hf://nvidia/Nemotron-3-Nano-RL-Training-Blend | per-blend train/val JSONL with responses_create_params schema | Shared with Nano3’s text-RL recipe (run_rl_resolve_pipeline) | +| vision | hf://OpenGVLab/MMPR-Tiny | MMPR-Tiny/images/ + mmpr_tiny.parquet + preview JSONL | In-tree VlmPreferencePrepStage(flavor="tiny") (no shell-out) | All three flows go through the same shared dispatcher (`src/nemotron/cli/commands/omni3/data/prep/rl.py`) so they share @@ -34,7 +38,7 @@ flowchart LR style manifest fill:#e8f5e9,stroke:#4caf50 ``` -`ensure_raw_dir` is a precondition step: when the per-stage YAML's +`ensure_raw_dir` is a precondition step: when the per-stage YAML’s `source_uri` is set and `input_dir` is empty/incomplete, it fetches the HF snapshot into `input_dir` before the prep stage runs. Operators who pre-stage data manually (or set `OMNI3_MMPR_PUBLIC_RAW` / @@ -53,20 +57,23 @@ uv run nemotron --batch prep omni3 data prep rl -c vision Each command: 1. Resolves the per-stage YAML - (`src/nemotron/recipes/omni3/stage1_rl/config/data_prep/{mpo,text,vision}.yaml`) - merged with your env profile. +(`src/nemotron/recipes/omni3/stage1_rl/config/data_prep/\{mpo,text,vision\}.yaml`) +merged with your env profile. + 2. Downloads inputs from `source_uri` into `input_dir` if missing - (vision/mpo only; text uses `run_rl_resolve_pipeline` which downloads - directly from HF as part of the recipe). +(vision/mpo only; text uses `run_rl_resolve_pipeline` which downloads +directly from HF as part of the recipe). + 3. Runs the prep stage (Xenna single-worker pipeline) with run-hash - caching, receipts, and W&B lineage. -4. Registers the result as an artifact under `omni3/rl/{stage}/data`. +caching, receipts, and W&B lineage. + +4. Registers the result as an artifact under `omni3/rl/\{stage\}/data`. > **Submitting in parallel:** safe — sibling RL configs (mpo / text / -> vision) get unique job names from `_make_job_name` (PID + random -> token), so the local config-staging file and the remote Ray code dir -> never collide between concurrent invocations. Earlier versions raced -> on a wall-clock-second timestamp; that's fixed. +vision) get unique job names from `_make_job_name` (PID + random +token), so the local config-staging file and the remote Ray code dir +never collide between concurrent invocations. Earlier versions raced +on a wall-clock-second timestamp; that’s fixed. ## Auto-download via `source_uri` @@ -91,19 +98,20 @@ input_dir: ${oc.env:OMNI3_MMPR_PUBLIC_RAW,data/mmpr_public/raw} When the dispatcher runs: - If `input_dir` already contains the required files - (`images.zip`, `mmpr_tiny.parquet` for tiny; *any* non-empty content - for mpo, since the upstream layout isn't fully declarative), it - skips the download. +(`images.zip`, `mmpr_tiny.parquet` for tiny; *any* non-empty content +for mpo, since the upstream layout isn’t fully declarative), it +skips the download. + - Otherwise, if `source_uri` is set, it calls - `huggingface_hub.snapshot_download(repo_id=…, repo_type="dataset", - local_dir=input_dir)` and proceeds. +`huggingface_hub.snapshot_download(repo_id=…, repo_type="dataset", local_dir=input_dir)` and proceeds. + - If `input_dir` is missing required files *and* `source_uri` is - unset/empty, it fails fast with the exact list of missing files - and a remediation hint. +unset/empty, it fails fast with the exact list of missing files +and a remediation hint. The download lands in whatever you set `input_dir` to. Default is `data//raw` (relative to `cwd` of the Ray worker, which is -the rsync'd repo root); override per environment by exporting +the rsync’d repo root); override per environment by exporting `OMNI3_MMPR_TINY_RAW` / `OMNI3_MMPR_PUBLIC_RAW`. ## What each substage produces @@ -114,12 +122,12 @@ Cache rooted at `/MMPR-v1.2/` (where `output_dir` defaults to `/stage1_rl/data_prep/mpo/MMPR-v1.2`): -``` +```default MMPR-v1.2/ ├── meta_public.json # rewritten meta with relative paths ├── MMPR/ -│ ├── images//... # extracted images.zip -│ └── annotations/.jsonl # extracted annotations.zip +│ ├── images/\/... # extracted images.zip +│ └── annotations/\.jsonl # extracted annotations.zip ├── mmpr_public_preview.jsonl # 2 sampled rows per subset ├── prepare_public_mmpr_for_mpo_summary.json # per-run summary └── .mmpr_ready # sentinel for trainer-side discovery @@ -134,7 +142,7 @@ paths, swap `_relpath_for_meta` in ### `text` -Per-blend train/val JSONL split, identical schema to Nano3's +Per-blend train/val JSONL split, identical schema to Nano3’s `stage2_rl` recipe. Shared with Nano3 because the source dataset (`nvidia/Nemotron-3-Nano-RL-Training-Blend`) and output schema (`responses_create_params`-shaped JSONL) are the same. @@ -144,7 +152,7 @@ Per-blend train/val JSONL split, identical schema to Nano3's Cache rooted at `/` (defaults to `/stage1_rl/data_prep/vision`): -``` +```default vision/ ├── MMPR-Tiny/images/... # extracted images.zip ├── mmpr_tiny.parquet # source records, copied through @@ -160,25 +168,25 @@ operators who want to run the prep by hand or debug it outside the dispatcher: | Script | Equivalent dispatcher path | When to invoke directly | -|--------|---------------------------|------------------------| -| `scripts/prepare_mmpr_tiny_for_vision_rl.py` | `omni3 data prep rl -c vision` | Iterating on the tiny prep logic; reproducing a cache shape outside Ray; CI dry-runs. | -| `scripts/prepare_public_mmpr_for_mpo.py` | `omni3 data prep rl -c mpo` | Iterating on MMPR-Public layout; testing meta-rewrite changes; bisecting subset-extraction issues. | +| --- | --- | --- | +| scripts/prepare_mmpr_tiny_for_vision_rl.py | omni3 data prep rl -c vision | Iterating on the tiny prep logic; reproducing a cache shape outside Ray; CI dry-runs. | +| scripts/prepare_public_mmpr_for_mpo.py | omni3 data prep rl -c mpo | Iterating on MMPR-Public layout; testing meta-rewrite changes; bisecting subset-extraction issues. | Both take the same `--input-dir` / `--output-dir` shape and produce the cache layout above. The dispatcher invokes the *MMPR-Public* script -through `mpo.yaml`'s `builder_command`; the *MMPR-Tiny* logic is also +through `mpo.yaml`’s `builder_command`; the *MMPR-Tiny* logic is also vendored inline in `nemotron.data_prep.stages.vlm_preference_prep._run_tiny`, so the dispatcher does not currently shell out for the tiny flavor. The standalone tiny script is for ad-hoc / reproducible-by-hand use. - - ## Output artifact registration Each successful run emits an artifact: - `art://omni3/rl/mpo/data` → `/MMPR-v1.2/meta_public.json` + - `art://omni3/rl/text/data` → `/manifest.json` + - `art://omni3/rl/vision/data` → `/` Artifact metadata captures `elapsed_sec`, `run_hash`, and (for vision) @@ -188,7 +196,7 @@ Artifact metadata captures `elapsed_sec`, `run_hash`, and (for vision) All three substages declare `resources: nodes=1, gpus_per_node=0` so they fit on the prep / CPU -partition. MMPR-Public's images.zip is ~14 GB so first-run takes +partition. MMPR-Public’s images.zip is ~14 GB so first-run takes ~5–10 min on Lustre; subsequent runs short-circuit via run-hash cache. --- @@ -196,7 +204,11 @@ partition. MMPR-Public's images.zip is ~14 GB so first-run takes **Recipe sources**: - Dispatcher: `src/nemotron/cli/commands/omni3/data/prep/rl.py` + - Driver: `src/nemotron/recipes/omni3/stage1_rl/_data_prep_base.py` + - Stage logic: `src/nemotron/data_prep/stages/vlm_preference_prep.py` + - Auto-download: `src/nemotron/data_prep/recipes/rl_omni.py::ensure_raw_dir` + - Standalone scripts: `scripts/prepare_*.py` diff --git a/docs/nemotron/omni3/sft.md b/docs/fern/pages-vnightly/nemotron/omni3/sft.mdx similarity index 62% rename from docs/nemotron/omni3/sft.md rename to docs/fern/pages-vnightly/nemotron/omni3/sft.mdx index 2235ac51e..cb15504d4 100644 --- a/docs/nemotron/omni3/sft.md +++ b/docs/fern/pages-vnightly/nemotron/omni3/sft.mdx @@ -1,15 +1,22 @@ -# Stage 0: Supervised Fine-Tuning (SFT) +--- +title: "Stage 0: Supervised Fine-Tuning (SFT)" +slug: "nemotron/omni3/sft.html" +description: "Omni starts from the GA nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16 checkpoint (30B-A3B hybrid Mamba-transformer MoE) and fine-tunes it with the Valor32k multimodal recipe family using Megatron" +--- -Omni starts from the GA [`nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16`](https://huggingface.co/nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16) checkpoint (30B-A3B hybrid Mamba-transformer MoE) and fine-tunes it with the Valor32k multimodal recipe family using [Megatron-Bridge](../nvidia-stack.md#megatron-bridge). SFT teaches the perception-sub-agent surface — instruction-following over multimodal inputs — that downstream RL alignment and agentic systems consume. The released configs target the open-data subset; see [`architecture.md` §Progressive context scaling](./architecture.md#progressive-context-scaling) for how the open configs relate to the upstream 16K → 49K → 262K training schedule. +Omni starts from the GA [`nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16`](https://huggingface.co/nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16) checkpoint (30B-A3B hybrid Mamba-transformer MoE) and fine-tunes it with the Valor32k multimodal recipe family using [Megatron-Bridge](/../nvidia-stack#megatron-bridge). SFT teaches the perception-sub-agent surface — instruction-following over multimodal inputs — that downstream RL alignment and agentic systems consume. The released configs target the open-data subset; see [`architecture.md` §Progressive context scaling](/architecture#progressive-context-scaling) for how the open configs relate to the upstream 16K → 49K → 262K training schedule. > **Container-first stage**: Omni does not ship with a pre-baked image. This stage owns the `Dockerfile` that the `nemotron omni3 build sft` dispatcher turns into `omni3-sft.sqsh`, which all later SFT/eval commands reuse via the per-cluster `build_cache_dir`. -> **Defaults** — the shipped `default.yaml` uses [CORD-v2](https://huggingface.co/datasets/naver-clova-ix/cord-v2) from HuggingFace via Megatron-Bridge's `vlm-hf` loader, so `nemotron omni3 sft --run ` works out of the box with no internal data access. `-c valor32k` switches to the full audio-visual-language Energon flow but requires the internal Valor32k-AVQA dataset (see [Config Variants](#config-variants)). +> **Defaults** — the shipped `default.yaml` uses [CORD-v2](https://huggingface.co/datasets/naver-clova-ix/cord-v2) from HuggingFace via Megatron-Bridge’s `vlm-hf` loader, so `nemotron omni3 sft --run ` works out of the box with no internal data access. `-c valor32k` switches to the full audio-visual-language Energon flow but requires the internal Valor32k-AVQA dataset (see [Config Variants](#config-variants)). + +> **Current limitations** (also summarized in the [family README](/README#current-limitations)): + +- **Open-dataset default trains projector only.** CORD-v2 plus `freeze_language_model: true` fits on a single 8-GPU node (per QA guide §5.2.2). For full-model SFT, switch to `-c image_text_peft` (LoRA on CORD-v2) or prepare your own Energon dataset and point `dataset.path` at it. + +- `nemotron omni3 data prep sft` with `-c valor32k` validates a **prepared** Energon dataset; the raw-shard builder is internal-only. With the default (HF) flow the command is a no-op manifest writer — the training container pulls from the Hub on demand. -> **Current limitations** (also summarized in the [family README](./README.md#current-limitations)): -> - **Open-dataset default trains projector only.** CORD-v2 plus `freeze_language_model: true` fits on a single 8-GPU node (per QA guide §5.2.2). For full-model SFT, switch to `-c image_text_peft` (LoRA on CORD-v2) or prepare your own Energon dataset and point `dataset.path` at it. -> - `nemotron omni3 data prep sft` with `-c valor32k` validates a **prepared** Energon dataset; the raw-shard builder is internal-only. With the default (HF) flow the command is a no-op manifest writer — the training container pulls from the Hub on demand. -> - The `omni3-sft` Dockerfile clones `NVIDIA-NeMo/Megatron-Bridge @ nemotron_3_omni` (with `NVIDIA/Megatron-LM @ nemotron_3_omni` as a recursive submodule fetch). These are the active release branches for Nemotron 3 Omni; bump to a versioned tag (or `main`) once these changes merge upstream. +- The `omni3-sft` Dockerfile clones `NVIDIA-NeMo/Megatron-Bridge @ nemotron_3_omni` (with `NVIDIA/Megatron-LM @ nemotron_3_omni` as a recursive submodule fetch). These are the active release branches for Nemotron 3 Omni; bump to a versioned tag (or `main`) once these changes merge upstream. --- @@ -18,8 +25,8 @@ Omni starts from the GA [`nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-BF16`](h The stage directory is `src/nemotron/recipes/omni3/stage0_sft/` and contains: | File | Purpose | -|------|---------| -| `Dockerfile` | Builds the Megatron-Bridge `nemotron_3_omni` environment | +| --- | --- | +| Dockerfile | Builds the Megatron-Bridge nemotron_3_omni environment | | `data_prep.py` | Validates or stages a prepared Valor32k Energon dataset | | `train.py` | Runs `scripts/training/run_recipe.py` with the selected recipe | @@ -36,7 +43,7 @@ uv run nemotron omni3 build sft --run YOUR-CLUSTER The canonical archive path is: ```text -${build_cache_dir}/containers/omni3-sft.sqsh +$\{build_cache_dir\}/containers/omni3-sft.sqsh ``` `build_cache_dir` is set per profile in `env.toml` and is mounted into @@ -44,7 +51,7 @@ the build container at `/nemotron-cache`. The dispatcher also pulls your `nvcr.io` credentials out of `~/.config/enroot/.credentials` and exposes them to the build container as a docker-format `auth.json`, so `FROM nvcr.io/nvidian/nemo:` resolves without a separate -podman login. See [How container builds authenticate](../../nemo_runspec/nemo-run.md#how-the-build-container-authenticates-with-private-registries) +podman login. See [How container builds authenticate](/../../nemo_runspec/nemo-run#how-the-build-container-authenticates-with-private-registries) for the full mechanism + how to extend the registry allowlist. For local iteration, you can build the same stage directly from the Dockerfile: @@ -78,8 +85,11 @@ flowchart LR The public CLI does not build Valor32k shards from scratch yet. Instead, `data_prep.py` gives the recipe a concrete staging hook by: - validating `dataset_path` + - optionally running a site-local `builder_command` + - writing `manifest.json` under `metadata_dir` + - optionally refreshing a convenience symlink with `link_path` Run it with: @@ -91,7 +101,6 @@ uv run nemotron omni3 data prep sft --run YOUR-CLUSTER ## Quick Start
- ```console // 1. Build the container $ uv run nemotron omni3 build sft --run YOUR-CLUSTER @@ -109,19 +118,18 @@ $ uv run nemotron omni3 sft --run YOUR-CLUSTER ```
- ## Config Variants The stage ports the QA-guide variants into explicit YAML files: | Config | Purpose | -|--------|---------| -| `default.yaml` | Full Valor32k SFT | -| `image_text_sft.yaml` | Image-text projector SFT | -| `image_text_peft.yaml` | Image-text LoRA / PEFT | -| `audio_text.yaml` | Audio-text SFT | -| `peft_valor32k.yaml` | Valor32k LoRA / PEFT | -| `tiny.yaml` | Small smoke-test config | +| --- | --- | +| default.yaml | Full Valor32k SFT | +| image_text_sft.yaml | Image-text projector SFT | +| image_text_peft.yaml | Image-text LoRA / PEFT | +| audio_text.yaml | Audio-text SFT | +| peft_valor32k.yaml | Valor32k LoRA / PEFT | +| tiny.yaml | Small smoke-test config | Select a variant with `-c`: @@ -134,12 +142,15 @@ uv run nemotron omni3 sft -c image_text_peft --run YOUR-CLUSTER The two PEFT-oriented configs are: - `image_text_peft.yaml` + - `peft_valor32k.yaml` They keep the same stage-local execution path as full SFT but swap in LoRA-oriented training settings. After training, the family also exposes the related model lifecycle commands: - `uv run nemotron omni3 model lora-merge --run YOUR-CLUSTER ...` + - `uv run nemotron omni3 model adapter-export --run YOUR-CLUSTER ...` + - `uv run nemotron omni3 model export pretrain --run YOUR-CLUSTER ...` ## Training Configuration Notes @@ -147,13 +158,13 @@ They keep the same stage-local execution path as full SFT but swap in LoRA-orien The default Omni SFT config currently uses: | Setting | Value | -|---------|-------| -| `nproc_per_node` | 8 | -| `tensor_model_parallel_size` | 4 | -| `expert_model_parallel_size` | 4 | -| `seq_length` | 4096 | -| `global_batch_size` | 128 | -| `micro_batch_size` | 1 | +| --- | --- | +| nproc_per_node | 8 | +| tensor_model_parallel_size | 4 | +| expert_model_parallel_size | 4 | +| seq_length | 4096 | +| global_batch_size | 128 | +| micro_batch_size | 1 | The model checkpoint and staged dataset are passed through the artifact system or environment overrides: @@ -170,13 +181,13 @@ dataset: This stage uses: | Component | Role | Documentation | -|-----------|------|---------------| -| [Megatron-Core](../nvidia-stack.md#megatron-core) | Distributed TP/EP training primitives | [GitHub](https://github.com/NVIDIA/Megatron-LM) | -| [Megatron-Bridge](../nvidia-stack.md#megatron-bridge) | Recipe execution and checkpoint conversion | [Docs](https://docs.nvidia.com/nemo/megatron-bridge/latest/) | +| --- | --- | --- | +| [Megatron-Core](/../nvidia-stack#megatron-core) | Distributed TP/EP training primitives | [GitHub](https://github.com/NVIDIA/Megatron-LM) | +| [Megatron-Bridge](/../nvidia-stack#megatron-bridge) | Recipe execution and checkpoint conversion | [Docs](https://docs.nvidia.com/nemo/megatron-bridge/latest/) | ## Next Steps -After SFT completes, proceed to [Stage 1: RL](./rl.md). +After SFT completes, proceed to [Stage 1: RL](/rl). ## Upstream @@ -189,8 +200,13 @@ The Dockerfile in this stage pins `NVIDIA-NeMo/Megatron-Bridge @ nemotron_3_omni ## Reference - **Recipe source:** [`src/nemotron/recipes/omni3/stage0_sft/`](https://github.com/NVIDIA-NeMo/Nemotron/tree/main/src/nemotron/recipes/omni3/stage0_sft) ([README](https://github.com/NVIDIA-NeMo/Nemotron/blob/main/src/nemotron/recipes/omni3/stage0_sft/README.md)) + - **Upstream**: [Megatron-Bridge omni SFT recipe](https://github.com/NVIDIA-NeMo/Megatron-Bridge/blob/nemotron_3_omni/examples/models/vlm/nemotron_3_omni/README.md) -- [Architecture deep-dive](./architecture.md) -- [Inference & deployment](./inference.md) -- [Back to Overview](./README.md) -- [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) + +- [Architecture deep-dive](/architecture) + +- [Inference & deployment](/inference) + +- [Back to Overview](/README) + +- [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) diff --git a/docs/nemotron/super3/README.md b/docs/fern/pages-vnightly/nemotron/super3/README.mdx similarity index 70% rename from docs/nemotron/super3/README.md rename to docs/fern/pages-vnightly/nemotron/super3/README.mdx index 24f92da87..a52fafe43 100644 --- a/docs/nemotron/super3/README.md +++ b/docs/fern/pages-vnightly/nemotron/super3/README.mdx @@ -1,4 +1,8 @@ -# Nemotron 3 Super Training Recipe +--- +title: "Nemotron 3 Super Training Recipe" +slug: "nemotron/super3/README.html" +description: "A complete, reproducible training pipeline for Nemotron 3 Super—an open, high-capacity Mixture-of-Experts hybrid Mamba-Transformer model with LatentMoE and multi-token prediction." +--- A complete, reproducible training pipeline for Nemotron 3 Super—an open, high-capacity Mixture-of-Experts hybrid Mamba-Transformer model with LatentMoE and multi-token prediction. @@ -6,8 +10,10 @@ A complete, reproducible training pipeline for Nemotron 3 Super—an open, high- ### Prerequisites -- **Slurm cluster** with GPU nodes (B200 recommended for NVFP4 support) — see [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) -- **[Weights & Biases](../wandb.md) account** for experiment tracking and [artifact lineage](../../nemo_runspec/artifacts.md) +- **Slurm cluster** with GPU nodes (B200 recommended for NVFP4 support) — see [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) + +- **[Weights & Biases](/../wandb) account** for experiment tracking and [artifact lineage](/../../nemo_runspec/artifacts) + - **Container image**: `nvcr.io/nvidia/nemo:26.02.nemotron_3_super` ### Installation @@ -20,7 +26,7 @@ uv sync ### Configuration -Create an `env.toml` file (see [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for details): +Create an `env.toml` file (see [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for details): ```toml [wandb] @@ -40,7 +46,6 @@ mounts = ["/lustre:/lustre"] ### Run the Pipeline
- ```console // Stage 0: Pretraining $ uv run nemotron super3 data prep pretrain --run YOUR-CLUSTER @@ -59,44 +64,50 @@ $ uv run nemotron super3 eval --run YOUR-CLUSTER ```
- ## Resources - **Tech Report**: [Nemotron 3 Super Technical Report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Super-Technical-Report.pdf) + - **Model Weights**: - - [NVIDIA-Nemotron-3-Super-120B-A12B-BF16](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16) (Post-trained model) - - [NVIDIA-Nemotron-3-Super-120B-A12B-FP8](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-FP8) (FP8 quantized) - - [NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4) (NVFP4 quantized) - - [NVIDIA-Nemotron-3-Super-120B-A12B-Base-BF16](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-Base-BF16) (Base model) + + - [NVIDIA-Nemotron-3-Super-120B-A12B-BF16](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16) (Post-trained model) + + - [NVIDIA-Nemotron-3-Super-120B-A12B-FP8](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-FP8) (FP8 quantized) + + - [NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4) (NVFP4 quantized) + + - [NVIDIA-Nemotron-3-Super-120B-A12B-Base-BF16](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-Base-BF16) (Base model) + - **Training Datasets**: - - [Nemotron-Pretraining-Specialized-v1.1](https://huggingface.co/datasets/nvidia/Nemotron-Pretraining-Specialized-v1.1) (Synthetic pretraining data) + + - [Nemotron-Pretraining-Specialized-v1.1](https://huggingface.co/datasets/nvidia/Nemotron-Pretraining-Specialized-v1.1) (Synthetic pretraining data) + - **Megatron-Bridge Docs**: [Nemotron 3 Super](https://github.com/NVIDIA-NeMo/Megatron-Bridge/blob/super-v3/docs/models/llm/nemotron3-super.md) - +{/* TODO - Move whatever customization docs for Super 3 to this section of the docs. +```{seealso\} +For model cards, technical report chunks, and recipe summaries, see {doc\}`/customize/models/super3/index`. +``` */} ## Training Pipeline | Stage | Name | Purpose | Guide | -|-------|------|---------|-------| -| 0 | [Pretraining](./pretrain.md) | Base model training on 25T tokens with LatentMoE and MTP | [pretrain.md](./pretrain.md) | -| 1 | [SFT](./sft.md) | Multi-domain instruction tuning with two-stage loss | [sft.md](./sft.md) | -| 2 | [RL](./rl/index.md) | Multi-environment RLVR + SWE-RL + RLHF alignment | [rl/](./rl/index.md) | -| 3 | [Quantization](./quantization.md) | FP8 and NVFP4 post-training quantization | [quantization.md](./quantization.md) | +| --- | --- | --- | --- | +| 0 | [Pretraining](/pretrain) | Base model training on 25T tokens with LatentMoE and MTP | [pretrain.md](/pretrain) | +| 1 | [SFT](/sft) | Multi-domain instruction tuning with two-stage loss | [sft.md](/sft) | +| 2 | [RL](/rl/index) | Multi-environment RLVR + SWE-RL + RLHF alignment | [rl/](/rl/index) | +| 3 | [Quantization](/quantization) | FP8 and NVFP4 post-training quantization | [quantization.md](/quantization) | | — | Distillation | Knowledge distillation (see tech report) | Coming soon | -| 4 | [Evaluation](./evaluate.md) | Benchmark evaluation across 20+ benchmarks | [evaluate.md](./evaluate.md) | +| 4 | [Evaluation](/evaluate) | Benchmark evaluation across 20+ benchmarks | [evaluate.md](/evaluate) | ## Architecture -![Nemotron 3 Super architecture](../../assets/super3/super-pattern.png) +![Nemotron 3 Super architecture](../../../_images/super-pattern.png) ## Model Specifications | Specification | Value | -|---------------|-------| +| --- | --- | | **Total Parameters** | 120.6B | | **Active Parameters** | 12.7B (per forward pass) | | **Pretraining Tokens** | 25 trillion | @@ -118,47 +129,47 @@ For model cards, technical report chunks, and recipe summaries, see {doc}`/custo Two-phase curriculum on 25 trillion tokens: Phase 1 (20T, 80%) focuses on diversity across 16 data categories; Phase 2 (5T, 20%) emphasizes high-quality sources. Introduces LatentMoE for hardware-aware sparse scaling, MTP for inference acceleration, and checkpoint merging for quality tracking during the stable LR phase. Includes long-context extension to 1M tokens. -> [Pretraining Guide](./pretrain.md) +> [Pretraining Guide](/pretrain) ### Stage 1: Supervised Fine-Tuning Multi-domain instruction tuning over 7M samples covering 15+ data domains including competition math/code, software engineering, agentic programming, CUDA, financial reasoning, long context, safety, search, terminal use, SQL, and more. Uses a novel two-stage SFT loss (token-level then sample-level) and continues MTP training from pretraining. Supports three reasoning modes: reasoning-off, regular, and low-effort. -> [SFT Guide](./sft.md) +> [SFT Guide](/sft) ### Stage 2: Reinforcement Learning Three-stage RL pipeline: (1) multi-environment RLVR across 21 environments and 37 datasets covering math, code, STEM, safety, agentic tasks, and reasoning gym; (2) SWE-RL for end-to-end software engineering using OpenHands with Apptainer containers; (3) RLHF with a principle-following GenRM (Qwen3-235B initialization). -> [RL Guide](./rl/index.md) +> [RL Guide](/rl/index) ### Stage 3: Quantization Post-training quantization producing FP8 (Hopper) and NVFP4 (Blackwell) checkpoints. NVFP4 uses a hybrid PTQ recipe with AutoQuantize mixed-precision NAS achieving 99.8% median accuracy vs BF16. Includes QAD (Quantization-Aware Distillation) and Mamba state quantization with FP16 stochastic rounding. -> [Quantization Guide](./quantization.md) +> [Quantization Guide](/quantization) ### Stage 4: Evaluation Comprehensive evaluation across general knowledge (MMLU-Pro), reasoning (AIME25, HMMT, GPQA, LiveCodeBench, SciCode, HLE), agentic (TerminalBench, SWE-Bench with 3 harnesses, TauBench V2, BrowseComp, BIRD), chat & IF (IFBench, Multi-Challenge, Arena-Hard-V2), long context (AA-LCR, RULER at 256K/512K/1M), and multilingual (MMLU-ProX, WMT24++). -> [Evaluation Guide](./evaluate.md) +> [Evaluation Guide](/evaluate) ## Execution Options -All commands support [NeMo-Run](../../nemo_runspec/nemo-run.md) execution modes: +All commands support [NeMo-Run](/../../nemo_runspec/nemo-run) execution modes: | Option | Behavior | Use Case | -|--------|----------|----------| -| `--run ` | Attached—submits job and streams logs | Interactive development | -| `--batch ` | Detached—submits and exits immediately | Long-running jobs | -| `--dry-run` | Preview execution plan | Validation | +| --- | --- | --- | +| --run <profile> | Attached—submits job and streams logs | Interactive development | +| --batch <profile> | Detached—submits and exits immediately | Long-running jobs | +| --dry-run | Preview execution plan | Validation | -See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for profile configuration and advanced options. +See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for profile configuration and advanced options. ## Artifact Lineage -The pipeline tracks full lineage via [W&B Artifacts](../../nemo_runspec/artifacts.md), enabling traceability from raw data to final model. +The pipeline tracks full lineage via [W&B Artifacts](/../../nemo_runspec/artifacts), enabling traceability from raw data to final model. ```mermaid %%{init: {'theme': 'base', 'themeVariables': { 'primaryBorderColor': '#333333', 'lineColor': '#333333', 'primaryTextColor': '#333333', 'clusterBkg': '#ffffff', 'clusterBorder': '#333333'}}}%% @@ -209,7 +220,7 @@ flowchart TB style eval fill:#fce4ec,stroke:#e91e63 ``` -> [Artifact Lineage & W&B Integration](../../nemo_runspec/artifacts.md) +> [Artifact Lineage & W&B Integration](/../../nemo_runspec/artifacts) ## Open-Source Data @@ -218,7 +229,6 @@ flowchart TB ## CLI Reference
- ```console // Show available commands $ uv run nemotron super3 --help @@ -239,42 +249,38 @@ Usage: nemotron super3 [OPTIONS] COMMAND [ARGS]... ```
- ## Troubleshooting -**W&B authentication**: See [W&B Integration](../wandb.md) for setup. +**W&B authentication**: See [W&B Integration](/../wandb) for setup. + ```bash wandb login ``` **Container not found**: Verify image path in config files. -**Job submission fails**: Check Slurm account and partition in `env.toml`. See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md). +**Job submission fails**: Check Slurm account and partition in `env.toml`. See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run). ## Further Reading -- [Stage 0: Pretraining](./pretrain.md) -- [Stage 1: SFT](./sft.md) -- [Stage 2: RL](./rl/index.md) -- [Stage 3: Quantization](./quantization.md) -- [Stage 4: Evaluation](./evaluate.md) -- [Artifact Lineage](../../nemo_runspec/artifacts.md) -- [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) -- [W&B Integration](../wandb.md) -- [NVIDIA AI Stack](../nvidia-stack.md) -- [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) -- [Data Preparation Module](../data-prep.md) - -```{toctree} -:hidden: - -pretrain.md -sft.md -rl/index.md -rl/rlvr.md -rl/swe.md -rl/rlhf.md -rl/data-prep.md -evaluate.md -quantization.md -``` +- [Stage 0: Pretraining](/pretrain) + +- [Stage 1: SFT](/sft) + +- [Stage 2: RL](/rl/index) + +- [Stage 3: Quantization](/quantization) + +- [Stage 4: Evaluation](/evaluate) + +- [Artifact Lineage](/../../nemo_runspec/artifacts) + +- [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) + +- [W&B Integration](/../wandb) + +- [NVIDIA AI Stack](/../nvidia-stack) + +- [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) + +- [Data Preparation Module](/../data-prep) diff --git a/docs/nemotron/super3/evaluate.md b/docs/fern/pages-vnightly/nemotron/super3/evaluate.mdx similarity index 77% rename from docs/nemotron/super3/evaluate.md rename to docs/fern/pages-vnightly/nemotron/super3/evaluate.mdx index c476f6d65..94a931f8a 100644 --- a/docs/nemotron/super3/evaluate.md +++ b/docs/fern/pages-vnightly/nemotron/super3/evaluate.mdx @@ -1,4 +1,8 @@ -# Stage 4: Evaluation +--- +title: "Stage 4: Evaluation" +slug: "nemotron/super3/evaluate.html" +description: "Evaluate trained Nemotron 3 Super models against standard benchmarks using NeMo Evaluator." +--- Evaluate trained Nemotron 3 Super models against standard benchmarks using [NeMo Evaluator](https://github.com/NVIDIA-NeMo/Evaluator). @@ -10,7 +14,7 @@ The evaluation recipe here covers a subset of the benchmarks used in the full te ## How Evaluation Works -The eval command resolves model artifacts from W&B lineage and uses NeMo Framework's Ray-based in-framework deployment. It defaults to evaluating the latest RL stage output. +The eval command resolves model artifacts from W&B lineage and uses NeMo Framework’s Ray-based in-framework deployment. It defaults to evaluating the latest RL stage output. ```mermaid %%{init: {'theme': 'base', 'themeVariables': { 'primaryBorderColor': '#333333', 'lineColor': '#333333', 'primaryTextColor': '#333333'}}}%% @@ -34,10 +38,10 @@ flowchart TB ### Deployment -The model checkpoint (HuggingFace format) is converted to [Megatron-Bridge](../nvidia-stack.md#megatron-bridge) format and deployed with Ray as an OpenAI API-compatible endpoint. The evaluator launcher handles deployment, benchmark execution, and result export in a single command. +The model checkpoint (HuggingFace format) is converted to [Megatron-Bridge](/../nvidia-stack#megatron-bridge) format and deployed with Ray as an OpenAI API-compatible endpoint. The evaluator launcher handles deployment, benchmark execution, and result export in a single command. | Setting | Value | Notes | -|---------|-------|-------| +| --- | --- | --- | | Deployment backend | MBridge + Ray | In-framework NeMo deployment | | Minimum GPUs | 8 (1 node) | Expert parallelism requires 8 GPUs | | Tensor parallelism (TP) | 1 | Single-GPU tensor parallelism | @@ -52,24 +56,24 @@ The evaluation covers six categories of benchmarks, matching the tech report eva ### General Knowledge | Benchmark | Description | -|-----------|-------------| +| --- | --- | | MMLU-Pro | Massive Multitask Language Understanding (Professional) | ### Reasoning | Benchmark | Description | -|-----------|-------------| +| --- | --- | | AIME25 | American Invitational Mathematics Examination 2025 (no tools / with tools) | | HMMT | Harvard-MIT Mathematics Tournament (no tools) | | GPQA | Graduate-Level Google-Proof QA (no tools / with tools) | | LiveCodeBench v5 | Live competitive coding (2024-08 to 2025-05) | | SciCode | Scientific coding (subtask) | -| HLE | Humanity's Last Exam (no tools / with tools) | +| HLE | Humanity’s Last Exam (no tools / with tools) | ### Agentic | Benchmark | Description | -|-----------|-------------| +| --- | --- | | TerminalBench | Terminal use (hard subset + v2.0) | | SWE-Bench | Software engineering (OpenHands, OpenCode, Codex harnesses + Multilingual) | | TauBench V2 | Conversational tool use (Airline, Retail, Telecom) | @@ -79,7 +83,7 @@ The evaluation covers six categories of benchmarks, matching the tech report eva ### Chat & Instruction Following | Benchmark | Description | -|-----------|-------------| +| --- | --- | | IFBench | Instruction following (prompt-level) | | Multi-Challenge | Complex multi-constraint instructions | | Arena-Hard-V2 | Hard prompt evaluation | @@ -87,14 +91,14 @@ The evaluation covers six categories of benchmarks, matching the tech report eva ### Long Context | Benchmark | Description | -|-----------|-------------| +| --- | --- | | AA-LCR | Long-context reasoning | | RULER-100 | Retrieval tasks at 256K, 512K, and 1M context | ### Multilingual | Benchmark | Description | -|-----------|-------------| +| --- | --- | | MMLU-ProX | Multilingual MMLU-Pro (averaged over languages) | | WMT24++ | Machine translation (en→xx) | @@ -105,10 +109,10 @@ The evaluation covers six categories of benchmarks, matching the tech report eva Comparison against Qwen3.5-122B-A10B and GPT-OSS-120B (officially reported numbers are used when available; otherwise scores are computed using official evaluation settings): | Benchmark | N-3-Super | Qwen3.5-122B-A10B | GPT-OSS-120B | -|-----------|-----------|---------------------|--------------| -| **General Knowledge** | | | | +| --- | --- | --- | --- | +| **General Knowledge** | | | | | MMLU-Pro | 83.73 | 86.70 | 81.00 | -| **Reasoning** | | | | +| **Reasoning** | | | | | AIME25 (no tools) | 90.21 | 90.36 | 92.50 | | HMMT (no tools) | 93.67 | 91.67 | 92.33 | | GPQA (no tools) | 79.23 | 86.60 | 80.10 | @@ -117,7 +121,7 @@ Comparison against Qwen3.5-122B-A10B and GPT-OSS-120B (officially reported numbe | SciCode (subtask) | 42.05 | 42.00 | 39.00 | | HLE (no tools) | 18.26 | 25.30 | 14.90 | | HLE (with tools) | 22.82 | — | 19.00 | -| **Agentic** | | | | +| **Agentic** | | | | | TerminalBench (hard) | 22.30 | 26.80 | 24.00 | | TerminalBench 2.0 | 31.00 | 37.50 | 18.70 | | SWE-Bench (OpenHands) | 60.47 | 66.40 | 41.90 | @@ -130,16 +134,16 @@ Comparison against Qwen3.5-122B-A10B and GPT-OSS-120B (officially reported numbe | TauBench V2 Average | 64.64 | 74.53 | 61.00 | | BrowseComp | 31.28 | TBD | 33.89 | | BIRD Bench | 41.80 | — | 38.25 | -| **Chat & IF** | | | | +| **Chat & IF** | | | | | IFBench (prompt) | 75.03 | 76.10 | 65.00 | | Multi-Challenge | 55.23 | 61.50 | 58.29 | | Arena-Hard-V2 | 73.88 | 75.15 | 90.26 | -| **Long Context** | | | | +| **Long Context** | | | | | AA-LCR | 59.67 | 66.90 | 51.00 | | RULER-100 @ 256k | 96.30 | TBD | 52.30 | | RULER-100 @ 512k | 95.67 | TBD | 46.70 | | RULER-100 @ 1M | 91.75 | TBD | 22.30 | -| **Multilingual** | | | | +| **Multilingual** | | | | | MMLU-ProX (avg) | 80.00 | 82.20 | 75.90 | | WMT24++ (en→xx) | 87.30 | 78.30 | 87.80 | @@ -148,7 +152,7 @@ Comparison against Qwen3.5-122B-A10B and GPT-OSS-120B (officially reported numbe The following table validates the MBridge deployment by comparing accuracy against research team numbers on the base (pretrained) model: | Benchmark | MBridge Deployment | Research Team | Delta | -|-----------|-------------------|---------------|-------| +| --- | --- | --- | --- | | MMLU (5-shot) | 85.86 | 85.89 | -0.03 | | ARC-Challenge (25-shot) | 95.82 | 95.65 | +0.17 | | Winogrande (5-shot) | 78.37 | 78.69 | -0.32 | @@ -162,7 +166,6 @@ The following table validates the MBridge deployment by comparing accuracy again ### Quick Start
- ```console // Evaluate the latest RL model from the pipeline $ uv run nemotron super3 eval --run YOUR-CLUSTER @@ -178,37 +181,39 @@ $ uv run nemotron super3 eval --dry-run ```
- -> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](../../nemo_runspec/nemo-run.md). See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for setup. +> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](/../../nemo_runspec/nemo-run). See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for setup. ### Prerequisites - **[NeMo Evaluator](https://github.com/NVIDIA-NeMo/Evaluator)**: Install with `pip install "nemotron[evaluator]"` or ensure `nemo-evaluator-launcher` is available + - **`HF_TOKEN`**: Required for gated models and some benchmark datasets -- **[Weights & Biases](../wandb.md)**: For result export (optional but recommended) + +- **[Weights & Biases](/../wandb)**: For result export (optional but recommended) + - **Slurm cluster**: For remote execution ### Configuration | File | Purpose | -|------|---------| -| `config/default.yaml` | Evaluation config with deployment and benchmark tasks | +| --- | --- | +| config/default.yaml | Evaluation config with deployment and benchmark tasks | ### Default Evaluation Tasks The recipe config ships with the following default benchmarks: | Task | Benchmark | Shots | -|------|-----------|-------| -| `adlr_mmlu` | MMLU | 5-shot | -| `adlr_arc_challenge_llama_25_shot` | ARC-Challenge | 25-shot | -| `hellaswag` | HellaSwag | 10-shot | -| `openbookqa` | OpenBookQA | 0-shot | -| `adlr_winogrande_5_shot` | Winogrande | 5-shot | +| --- | --- | --- | +| adlr_mmlu | MMLU | 5-shot | +| adlr_arc_challenge_llama_25_shot | ARC-Challenge | 25-shot | +| hellaswag | HellaSwag | 10-shot | +| openbookqa | OpenBookQA | 0-shot | +| adlr_winogrande_5_shot | Winogrande | 5-shot | ### Artifact Resolution -The default config uses `${art:model,path}` for the model checkpoint: +The default config uses `$\{art:model,path\}` for the model checkpoint: ```yaml run: @@ -260,7 +265,7 @@ pip install "nemo-evaluator-launcher[all]" **2. Set your HuggingFace token** (required for gated models and some benchmarks): ```bash -export HF_TOKEN= +export HF_TOKEN=\ ``` **3. Run evaluation:** @@ -290,17 +295,19 @@ gpus_per_node = 8 mounts = ["/lustre:/lustre"] ``` -See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for complete configuration options. +See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for complete configuration options. ### W&B Integration Results are automatically exported to W&B when configured: 1. **Auto-detection**: The CLI detects your local `wandb login` and propagates `WANDB_API_KEY` to evaluation containers + 2. **env.toml config**: `WANDB_PROJECT` and `WANDB_ENTITY` are loaded from `env.toml` + 3. **Auto-export**: Results are exported after evaluation completes -See [W&B Integration](../wandb.md) for setup. +See [W&B Integration](/../wandb) for setup. ### Artifact Lineage @@ -321,7 +328,7 @@ flowchart TB style results fill:#e8f5e9,stroke:#4caf50 ``` -> [Artifact Lineage & W&B Integration](../../nemo_runspec/artifacts.md) +> [Artifact Lineage & W&B Integration](/../../nemo_runspec/artifacts) --- @@ -330,45 +337,54 @@ flowchart TB This stage uses the following components: | Component | Role | Documentation | -|-----------|------|---------------| +| --- | --- | --- | | [NeMo Evaluator](https://github.com/NVIDIA-NeMo/Evaluator) | Benchmark evaluation framework and launcher | [GitHub](https://github.com/NVIDIA-NeMo/Evaluator) | -| [NeMo Framework](../nvidia-stack.md) | Ray-based in-framework model deployment | [Docs](https://docs.nvidia.com/nemo/) | +| [NeMo Framework](/../nvidia-stack) | Ray-based in-framework model deployment | [Docs](https://docs.nvidia.com/nemo/) | ### Parallelism Configuration | Setting | Value | Purpose | -|---------|-------|---------| -| `tensor_parallel_size` | 1 | Tensor parallelism per GPU | -| `expert_model_parallel_size` | 8 | Expert parallelism for MoE layers | -| `num_gpus` | 8 | Total GPUs per node | +| --- | --- | --- | +| tensor_parallel_size | 1 | Tensor parallelism per GPU | +| expert_model_parallel_size | 8 | Expert parallelism for MoE layers | +| num_gpus | 8 | Total GPUs per node | --- ## Troubleshooting | Problem | Solution | -|---------|----------| -| `nemo-evaluator-launcher` not found | Install with `pip install "nemotron[evaluator]"` | -| W&B authentication fails | Run `wandb login`. See [W&B Integration](../wandb.md) | +| --- | --- | +| nemo-evaluator-launcher not found | Install with pip install "nemotron[evaluator]" | +| W&B authentication fails | Run wandb login. See [W&B Integration](/../wandb) | | Model deployment fails | Check parallelism settings match GPU config (TP=1, EP=8 for Super3) | -| Artifact resolution fails | Verify artifact exists in W&B. Use `deployment.checkpoint_path=/explicit/path` to bypass | -| Task not found | List available tasks with `nemo-evaluator-launcher ls tasks` | +| Artifact resolution fails | Verify artifact exists in W&B. Use deployment.checkpoint_path=/explicit/path to bypass | +| Task not found | List available tasks with nemo-evaluator-launcher ls tasks | --- ## Previous Stages -- [Stage 0: Pretraining](./pretrain.md) — Pretrain the base model -- [Stage 1: SFT](./sft.md) — Instruction tuning -- [Stage 2: RL](./rl/index.md) — Reinforcement learning alignment -- [Stage 3: Quantization](./quantization.md) — Post-training quantization +- [Stage 0: Pretraining](/pretrain) — Pretrain the base model + +- [Stage 1: SFT](/sft) — Instruction tuning + +- [Stage 2: RL](/rl/index) — Reinforcement learning alignment + +- [Stage 3: Quantization](/quantization) — Post-training quantization ## Reference - [NeMo Evaluator](https://github.com/NVIDIA-NeMo/Evaluator) — Upstream evaluation framework + - [Nemotron 3 Super Reproducibility Guide](https://github.com/NVIDIA-NeMo/Evaluator/blob/main/packages/nemo-evaluator-launcher/examples/nemotron/nemotron-3-super/reproducibility.md) — Full reproduction instructions with configs and expected scores -- [Artifact Lineage](../../nemo_runspec/artifacts.md) — W&B artifact system -- [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) — Cluster configuration -- [W&B Integration](../wandb.md) — Credentials and export setup + +- [Artifact Lineage](/../../nemo_runspec/artifacts) — W&B artifact system + +- [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) — Cluster configuration + +- [W&B Integration](/../wandb) — Credentials and export setup + - **Recipe Source:** `src/nemotron/recipes/super3/stage3_eval/` -- [Back to Overview](./README.md) + +- [Back to Overview](/README) diff --git a/docs/nemotron/super3/pretrain.md b/docs/fern/pages-vnightly/nemotron/super3/pretrain.mdx similarity index 73% rename from docs/nemotron/super3/pretrain.md rename to docs/fern/pages-vnightly/nemotron/super3/pretrain.mdx index cb44c3b17..fcc11bc99 100644 --- a/docs/nemotron/super3/pretrain.md +++ b/docs/fern/pages-vnightly/nemotron/super3/pretrain.mdx @@ -1,6 +1,10 @@ -# Stage 0: Pretraining +--- +title: "Stage 0: Pretraining" +slug: "nemotron/super3/pretrain.html" +description: "This stage trains the base Nemotron 3 Super model using Megatron-Bridge." +--- -This stage trains the base Nemotron 3 Super model using [Megatron-Bridge](../nvidia-stack.md#megatron-bridge). +This stage trains the base Nemotron 3 Super model using [Megatron-Bridge](/../nvidia-stack#megatron-bridge). Nemotron 3 Super is a **hybrid Mamba-Transformer-MoE** model with multi-token prediction (MTP) and LatentMoE, combining state-space models for efficiency, attention for global context, LatentMoE for hardware-aware sparse scaling, and MTP for improved training signal and inference acceleration. @@ -8,7 +12,7 @@ Nemotron 3 Super is a **hybrid Mamba-Transformer-MoE** model with multi-token pr ## Training Methodology -> **Training Framework**: Pretraining is implemented using [Megatron-Bridge](https://docs.nvidia.com/nemo/megatron-bridge/latest/)'s `pretrain()` entry point. See [Training Entry Points](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/entry-points.html) for implementation details. +> **Training Framework**: Pretraining is implemented using [Megatron-Bridge](https://docs.nvidia.com/nemo/megatron-bridge/latest/)’s `pretrain()` entry point. See [Training Entry Points](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/entry-points.html) for implementation details. ### Model Architecture @@ -17,7 +21,7 @@ Nemotron 3 Super extends the hybrid Mamba-Transformer MoE design from Nemotron 3 #### Architecture Dimensions | Configuration | Value | -|---------------|-------| +| --- | --- | | **Total Layers** | 88 | | **Model Dimension** | 4096 | | **Q-Heads** | 32 | @@ -36,31 +40,35 @@ Nemotron 3 Super extends the hybrid Mamba-Transformer MoE design from Nemotron 3 #### LatentMoE: Hardware-Aware Expert Design -Nemotron 3 Super is the first model to scale sparsely using **LatentMoE** rather than standard MoE layers. In LatentMoE, input tokens are projected from the hidden dimension $d$ into a smaller latent dimension $\ell$ (1024) for routing and expert computation, reducing routed parameter loads and all-to-all traffic by a factor of $d/\ell$. +Nemotron 3 Super is the first model to scale sparsely using **LatentMoE** rather than standard MoE layers. In LatentMoE, input tokens are projected from the hidden dimension d into a smaller latent dimension \ell (1024) for routing and expert computation, reducing routed parameter loads and all-to-all traffic by a factor of d/\ell. -These savings are used to increase both the total number of experts (to 512) and the top-k active experts per token (to 22), improving model accuracy at approximately constant inference cost. All non-routed computations—including the routing gate, shared expert computation, and non-expert layers—remain in the full hidden dimension $d$. +These savings are used to increase both the total number of experts (to 512) and the top-k active experts per token (to 22), improving model accuracy at approximately constant inference cost. All non-routed computations—including the routing gate, shared expert computation, and non-expert layers—remain in the full hidden dimension d. **Key design principles:** -- Reducing hidden dimension $d$ for routed computation relieves memory bandwidth and communication bottlenecks -- Increasing both total experts $N$ and active experts $K$ improves quality by exponentially expanding the space of expert combinations + +- Reducing hidden dimension d for routed computation relieves memory bandwidth and communication bottlenecks + +- Increasing both total experts N and active experts K improves quality by exponentially expanding the space of expert combinations + - Shared experts provide additional knowledge sharing across tokens -The MoE blocks employ squared ReLU activations, a sigmoid router with expert biasing, and aux-loss-free load balancing (update rate $10^{-3}$) paired with standard load balancing loss (coefficient $10^{-4}$). +The MoE blocks employ squared ReLU activations, a sigmoid router with expert biasing, and aux-loss-free load balancing (update rate 10^\{-3\}) paired with standard load balancing loss (coefficient 10^\{-4\}). #### Multi-Token Prediction (MTP) MTP optimizes the model to predict multiple future tokens at each position, improving both training quality and inference efficiency: - **Quality improvement**: Encourages representations that capture multi-step dependencies and longer-range structure + - **Inference acceleration**: MTP heads function as a native speculative decoding engine, generating candidate continuations verified by the main model in a single forward pass -**Shared-weight design for robust autoregressive drafting:** Unlike standard MTP with $N$ independent heads, Nemotron 3 Super shares parameters across MTP heads during training. This yields a unified prediction head that can be applied recursively at inference to generate longer drafts with stable acceptance behavior. The model achieves the highest overall average acceptance length (3.45 on SPEED-Bench) across all domains compared to DeepSeek-R1 (2.70) and is competitive with Qwen3-Next (3.33). +**Shared-weight design for robust autoregressive drafting:** Unlike standard MTP with N independent heads, Nemotron 3 Super shares parameters across MTP heads during training. This yields a unified prediction head that can be applied recursively at inference to generate longer drafts with stable acceptance behavior. The model achieves the highest overall average acceptance length (3.45 on SPEED-Bench) across all domains compared to DeepSeek-R1 (2.70) and is competitive with Qwen3-Next (3.33). #### Hybrid Interleaving Pattern -![Nemotron 3 Super architecture pattern](../../assets/super3/super-pattern.png) +![Nemotron 3 Super architecture pattern](../../../_images/super-pattern.png) -The 88-layer stack follows a periodic interleaving pattern where MoE layers are paired with Mamba-2 blocks. A limited number of self-attention layers are strategically inserted as global "anchors" to enable full-token interaction and long-range information routing. The attention layers employ Grouped-Query Attention (GQA) with 32 query heads and 2 KV heads. Consistent with the Nemotron family, the model omits positional embeddings, dropout, and bias terms in linear layers, uses RMSNorm for normalization, and maintains un-tied embedding and output weights. +The 88-layer stack follows a periodic interleaving pattern where MoE layers are paired with Mamba-2 blocks. A limited number of self-attention layers are strategically inserted as global “anchors” to enable full-token interaction and long-range information routing. The attention layers employ Grouped-Query Attention (GQA) with 32 query heads and 2 KV heads. Consistent with the Nemotron family, the model omits positional embeddings, dropout, and bias terms in linear layers, uses RMSNorm for normalization, and maintains un-tied embedding and output weights. This synergy enables up to **6.4x higher inference throughput** compared to similarly-sized Transformer MoEs (e.g., GPT-OSS-120B) under 8K input / 16K output workloads. @@ -73,7 +81,7 @@ This synergy enables up to **6.4x higher inference throughput** compared to simi Several new datasets were added for Super3, released as [Nemotron-Pretraining-Specialized-v1.1](https://huggingface.co/datasets/nvidia/Nemotron-Pretraining-Specialized-v1.1): | Dataset | Description | Scale | -|---------|-------------|-------| +| --- | --- | --- | | **Synthetic Code Concepts** | Python problems and solutions generated using concept taxonomy from HumanEval | ~15M problem-solution pairs | | **Synthetic Algorithmic** | Algorithmic Python problems with edge cases and unit tests | ~0.2B tokens | | **Synthetic Economics** | Economics MCQs across microeconomics, macroeconomics, econometrics | TBD | @@ -87,33 +95,29 @@ The pretraining corpus spans **16 high-level categories** including web crawl da **Two-phase curriculum:** | Phase | Internal Scale | Focus | Proportion | -|-------|----------------|-------|------------| +| --- | --- | --- | --- | | Phase 1 | 20T (80%) | Data diversity — broad coverage and generalization | Higher weight on crawl data | | Phase 2 | 5T (20%) | High-quality sources — refined model performance | Higher weight on Wikipedia, curated sources |
Phase 1 blend distribution (click to expand) - -![Phase 1 pretrain data blend](../../assets/super3/super-phase1.png) +![Phase 1 pretrain data blend](../../../_images/super-phase1.png)
-
Phase 2 blend distribution (click to expand) - -![Phase 2 pretrain data blend](../../assets/super3/super-phase2.png) +![Phase 2 pretrain data blend](../../../_images/super-phase2.png)
- > **Open-source data coverage**: The released datasets cover an estimated 8–10T tokens -> (~40–50% of the internal 25T blend). Missing categories include code (~14% of blend), -> nemotron-cc-code (~2%), crawl++ (~2%), and academic text (~2%). Users should supplement -> with their own data for these categories and adjust `train_iters` accordingly. +(~40–50% of the internal 25T blend). Missing categories include code (~14% of blend), +nemotron-cc-code (~2%), crawl++ (~2%), and academic text (~2%). Users should supplement +with their own data for these categories and adjust `train_iters` accordingly. ### Hyperparameters | Parameter | Value | -|-----------|-------| +| --- | --- | | **Total Training Tokens** | 25 trillion | | **Batch Size** | 3,072 sequences (~25.17M tokens/batch) | | **Sequence Length** | 8,192 tokens | @@ -132,7 +136,7 @@ The pretraining corpus spans **16 high-level categories** including web crawl da Nemotron 3 Super was trained with NVFP4 precision on B200 GPUs for the entire 25T token horizon, demonstrating stable and accurate low-precision pretraining at scale. | Layer Type | Format | Rationale | -|------------|--------|-----------| +| --- | --- | --- | | All Linear Layers (default) | NVFP4 | — | | Final 15% of Network | BF16 | Training stability at scale | | Latent Projections | BF16 | Negligible step-time impact | @@ -148,7 +152,7 @@ Testing showed that switching all tensors to MXFP8 before LR annealing improved During the stable phase of the WSD learning rate schedule, individual checkpoints exhibit noisy benchmark performance. Following recent work on weight-space merging, checkpoint merging (weighted averaging over a sliding window of recent checkpoints) produces stronger readouts of model quality without requiring dedicated learning rate decay runs. | Metric | Value | -|--------|-------| +| --- | --- | | **Improvement** | 2–4 points on 12-benchmark average during stable LR phase | | **FLOP Savings** | ~16% of total pretraining budget (eliminates ~4T tokens of decay-run compute) | | **Merge Schedule** | minus-sqrt decay emulation | @@ -162,7 +166,7 @@ The final base model checkpoint selected for downstream alignment was a 500B mer A long-context phase (LC-Phase) at the end of pretraining extends the model to **1M token context**: | Parameter | Value | -|-----------|-------| +| --- | --- | | **Context Length** | 1,048,576 (1M) tokens | | **Learning Rate** | 4.5e-6 (constant) | | **Global Batch Size** | 16 | @@ -180,23 +184,23 @@ Data blend: 20% document QA data (reused from Nemotron 2 & 3 Nano), 80% downscal ### Base Model Evaluations -![Average benchmark score during pretraining](../../assets/super3/avg_benchmark.png) +![Average benchmark score during pretraining](../../../_images/avg_benchmark.png) | Task | N-Super-3 Base | Ling-flash Base-2.0 | GLM-4.5 Air-Base | -|------|----------------|---------------------|-------------------| -| **General** | | | | +| --- | --- | --- | --- | +| **General** | | | | | MMLU | **85.89** | 81.0 | 81.0 | | MMLU-Pro 5-shot | **74.65** | 62.1 | 58.2 | | AGIEval English CoT | **77.45** | 61.7 | 59.4 | -| **Math** | | | | +| **Math** | | | | | GSM8K CoT | **91.05** | 90.4 | 82.6 | | MATH | **84.68** | 62.4 | 49.6 | | MATH Level 5 | **70.00** | 39.8 | 26.3 | | AIME 2024 pass@32 | **53.33** | 30.0 | 20.0 | -| **Code** | | | | +| **Code** | | | | | HumanEval+ avg@32 | **79.40** | 70.1 | 76.3 | | MBPP+ avg@32 | 77.60 | 77.3 | **77.5** | -| **Commonsense** | | | | +| **Commonsense** | | | | | ARC Challenge | **95.65** | 94.8 | 93.9 | | HellaSwag | **88.99** | 84.5 | 87.7 | | OpenBookQA | **50.20** | 47.0 | 47.8 | @@ -206,8 +210,8 @@ Data blend: 20% document QA data (reused from Nemotron 2 & 3 Nano), 80% downscal #### Multilingual Base Model Evaluations | Task | N-Super-3 Base | Ling-flash Base-2.0 | GLM-4.5 Air-Base | -|------|----------------|---------------------|-------------------| -| **Global-MMLU-Lite** | | | | +| --- | --- | --- | --- | +| **Global-MMLU-Lite** | | | | | German | **87.50** | 75.8 | 78.0 | | Spanish | **88.50** | 78.0 | 81.3 | | French | **85.75** | 76.8 | 79.3 | @@ -217,7 +221,7 @@ Data blend: 20% document QA data (reused from Nemotron 2 & 3 Nano), 80% downscal | Portuguese | **86.25** | 79.3 | 82.8 | | Chinese | **84.00** | 76.0 | 77.8 | | Average | **85.88** | 74.81 | 79.00 | -| **Multilingual Math (MGSM)** | | | | +| **Multilingual Math (MGSM)** | | | | | Spanish | **90.40** | — | 85.6 | | German | **89.60** | — | 80.8 | | French | **86.40** | — | 80.8 | @@ -235,7 +239,6 @@ Data blend: 20% document QA data (reused from Nemotron 2 & 3 Nano), 80% downscal Pretraining follows a **4-phase curriculum**:
- ```console // 1. Prepare data for each phase $ uv run nemotron super3 data prep pretrain -c phase1 --run YOUR-CLUSTER @@ -250,10 +253,9 @@ $ uv run nemotron super3 pretrain -c long_context_mixed --run YOUR-CLUSTER # 17B ```
+Each phase resumes from the previous phase’s checkpoint automatically. -Each phase resumes from the previous phase's checkpoint automatically. - -> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](../../nemo_runspec/nemo-run.md). See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for setup. +> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](/../../nemo_runspec/nemo-run). See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for setup. #### Direct Script Execution (Megatron-Bridge) @@ -289,21 +291,21 @@ See the [Megatron-Bridge Nemotron 3 Super documentation](https://github.com/NVID **Training configs:** | File | Phase | Tokens | Key differences | -|------|-------|--------|----------------| -| `config/phase1.yaml` | Phase 1 | 20T | Diversity blend, WSD warmup + stable LR | -| `config/phase2.yaml` | Phase 2 | 5T | Quality blend, WSD minus_sqrt decay | -| `config/long_context_1m.yaml` | LC Stage 1 | 34B | seq_len=1M, GBS=16, CP=64, constant LR | -| `config/long_context_mixed.yaml` | LC Stage 2 | 17B | Alternating 1M/4K sequences | -| `config/default.yaml` | (alias) | — | Points to phase1 | -| `config/tiny.yaml` | (test) | — | Quick testing configuration | +| --- | --- | --- | --- | +| config/phase1.yaml | Phase 1 | 20T | Diversity blend, WSD warmup + stable LR | +| config/phase2.yaml | Phase 2 | 5T | Quality blend, WSD minus_sqrt decay | +| config/long_context_1m.yaml | LC Stage 1 | 34B | seq_len=1M, GBS=16, CP=64, constant LR | +| config/long_context_mixed.yaml | LC Stage 2 | 17B | Alternating 1M/4K sequences | +| config/default.yaml | (alias) | — | Points to phase1 | +| config/tiny.yaml | (test) | — | Quick testing configuration | **Data prep configs:** | File | Purpose | -|------|---------| -| `config/data_prep/phase1.yaml` | Phase 1 data blend (29 datasets, ~13.06B rows) | -| `config/data_prep/phase2.yaml` | Phase 2 data blend (27 datasets, ~10.53B rows) | -| `config/data_prep/long_context.yaml` | LC blend (80% phase2 + 20% doc QA) | +| --- | --- | +| config/data_prep/phase1.yaml | Phase 1 data blend (29 datasets, ~13.06B rows) | +| config/data_prep/phase2.yaml | Phase 2 data blend (27 datasets, ~10.53B rows) | +| config/data_prep/long_context.yaml | LC blend (80% phase2 + 20% doc QA) | ### Training @@ -314,11 +316,11 @@ uv run nemotron super3 pretrain [options] [overrides...] ``` | Option | Description | -|--------|-------------| -| `--run ` | Attached—submits and waits, streaming logs ([NeMo-Run](../../nemo_runspec/nemo-run.md)) | -| `--batch ` | Detached—submits and exits immediately ([NeMo-Run](../../nemo_runspec/nemo-run.md)) | -| `--dry-run` | Preview execution plan | -| `key=value` | Override config values ([NeMo-Run](../../nemo_runspec/nemo-run.md)) | +| --- | --- | +| --run <profile> | Attached—submits and waits, streaming logs ([NeMo-Run](/../../nemo_runspec/nemo-run)) | +| --batch <profile> | Detached—submits and exits immediately ([NeMo-Run](/../../nemo_runspec/nemo-run)) | +| --dry-run | Preview execution plan | +| key=value | Override config values ([NeMo-Run](/../../nemo_runspec/nemo-run)) | #### Override Examples @@ -364,31 +366,31 @@ flowchart TB ## Infrastructure -This stage uses the following components from the [NVIDIA AI Stack](../nvidia-stack.md): +This stage uses the following components from the [NVIDIA AI Stack](/../nvidia-stack): | Component | Role | Documentation | -|-----------|------|---------------| -| [Megatron-Core](../nvidia-stack.md#megatron-core) | Distributed training primitives (TP, PP, DP, EP, CP, SP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | -| [Megatron-Bridge](../nvidia-stack.md#megatron-bridge) | Model definitions, training loop, checkpoint management | [Docs](https://docs.nvidia.com/nemo/megatron-bridge/latest/) | +| --- | --- | --- | +| [Megatron-Core](/../nvidia-stack#megatron-core) | Distributed training primitives (TP, PP, DP, EP, CP, SP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | +| [Megatron-Bridge](/../nvidia-stack#megatron-bridge) | Model definitions, training loop, checkpoint management | [Docs](https://docs.nvidia.com/nemo/megatron-bridge/latest/) | | [Transformer Engine](https://github.com/NVIDIA/TransformerEngine) | NVFP4 GEMM kernels (cuBLAS backend) | [GitHub](https://github.com/NVIDIA/TransformerEngine) | ### Parallelism Configuration | Parallelism | Default | Config Key | -|-------------|---------|------------| -| Tensor (TP) | 4 | `model.tensor_model_parallel_size` | -| Pipeline (PP) | 1 | `model.pipeline_model_parallel_size` | -| Expert (EP) | 8 | `model.expert_model_parallel_size` | -| Expert Tensor (ETP) | 1 | `model.expert_tensor_parallel_size` | -| Context (CP) | 1 | `model.context_parallel_size` | -| Sequence (SP) | Yes | `model.sequence_parallel` | +| --- | --- | --- | +| Tensor (TP) | 4 | model.tensor_model_parallel_size | +| Pipeline (PP) | 1 | model.pipeline_model_parallel_size | +| Expert (EP) | 8 | model.expert_model_parallel_size | +| Expert Tensor (ETP) | 1 | model.expert_tensor_parallel_size | +| Context (CP) | 1 | model.context_parallel_size | +| Sequence (SP) | Yes | model.sequence_parallel | | Data (DP) | Auto | Computed from world size | **Minimum resources:** 4 nodes with 8 GPUs each (32 GPUs total). ### Container -``` +```default nvcr.io/nvidia/nemo:26.02.nemotron_3_super ``` @@ -396,13 +398,18 @@ nvcr.io/nvidia/nemo:26.02.nemotron_3_super ## Next Steps -After pretraining completes, proceed to [Stage 1: SFT](./sft.md) for instruction tuning. +After pretraining completes, proceed to [Stage 1: SFT](/sft) for instruction tuning. ## Reference - [Nemotron 3 Super Tech Report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Super-Technical-Report.pdf) — Pretraining methodology + - [Megatron-Bridge Nemotron 3 Super](https://github.com/NVIDIA-NeMo/Megatron-Bridge/blob/super-v3/docs/models/llm/nemotron3-super.md) — MB documentation and examples -- [NVIDIA AI Stack](../nvidia-stack.md) — Megatron-Core, Megatron-Bridge documentation -- [Artifact Lineage](../../nemo_runspec/artifacts.md) — W&B artifact system + +- [NVIDIA AI Stack](/../nvidia-stack) — Megatron-Core, Megatron-Bridge documentation + +- [Artifact Lineage](/../../nemo_runspec/artifacts) — W&B artifact system + - **Recipe Source**: `src/nemotron/recipes/super3/stage0_pretrain/` — Implementation details -- [Back to Overview](./README.md) + +- [Back to Overview](/README) diff --git a/docs/nemotron/super3/quantization.md b/docs/fern/pages-vnightly/nemotron/super3/quantization.mdx similarity index 77% rename from docs/nemotron/super3/quantization.md rename to docs/fern/pages-vnightly/nemotron/super3/quantization.mdx index 8c650b883..4e03430ca 100644 --- a/docs/nemotron/super3/quantization.md +++ b/docs/fern/pages-vnightly/nemotron/super3/quantization.mdx @@ -1,4 +1,8 @@ -# Stage 3: Quantization +--- +title: "Stage 3: Quantization" +slug: "nemotron/super3/quantization.html" +description: "This stage applies post-training quantization (PTQ) to the aligned Nemotron 3 Super model for efficient deployment across GPU generations." +--- This stage applies post-training quantization (PTQ) to the aligned Nemotron 3 Super model for efficient deployment across GPU generations. @@ -11,11 +15,11 @@ Quantization improves inference efficiency in several ways: quantized GEMMs incr Two quantized checkpoints are released: | Checkpoint | Target Hardware | Format | Key Benefit | -|------------|-----------------|--------|-------------| +| --- | --- | --- | --- | | **FP8** (W8A8) | Hopper (H100) | FP8 weights and activations | Balanced accuracy/throughput | -| **NVFP4** (W4A4) | Blackwell (B200) | NVFP4 weights and activations | 1.5--2.2x higher GEMM FLOPS than FP8 | +| **NVFP4** (W4A4) | Blackwell (B200) | NVFP4 weights and activations | 1.5–2.2x higher GEMM FLOPS than FP8 | -Both checkpoints are produced using [Model Optimizer](https://github.com/NVIDIA/Model-Optimizer/tree/main/examples/llm_ptq) PTQ with [Megatron-Bridge](../nvidia-stack.md#megatron-bridge). +Both checkpoints are produced using [Model Optimizer](https://github.com/NVIDIA/Model-Optimizer/tree/main/examples/llm_ptq) PTQ with [Megatron-Bridge](/../nvidia-stack#megatron-bridge). --- @@ -26,7 +30,7 @@ The FP8 checkpoint quantizes MoE GEMMs and Mamba GEMMs to FP8, with FP8 KV Cache ### Precision Settings | Configuration | FP8 Checkpoint | BF16 Baseline | -|---------------|----------------|---------------| +| --- | --- | --- | | Embedding | BF16 | BF16 | | Attention GEMM (QKV and Out Projection) | BF16 | BF16 | | KV Cache + Attention BMM1 | FP8 | FP8 | @@ -43,14 +47,14 @@ The FP8 checkpoint quantizes MoE GEMMs and Mamba GEMMs to FP8, with FP8 KV Cache ## NVFP4 Checkpoint -FP4 is attractive for efficient inference because NVFP4 offers roughly 1.5x--2.2x higher GEMM FLOPS than FP8 on Blackwell GPUs, while also reducing model memory footprint by about 2x. This makes FP4 especially appealing for prefill-heavy workloads, such as coding-agent deployments, where MoE GEMMs dominate latency. +FP4 is attractive for efficient inference because NVFP4 offers roughly 1.5x–2.2x higher GEMM FLOPS than FP8 on Blackwell GPUs, while also reducing model memory footprint by about 2x. This makes FP4 especially appealing for prefill-heavy workloads, such as coding-agent deployments, where MoE GEMMs dominate latency. ### FP4 PTQ Recipe The best results were obtained with a **hybrid FP4 recipe**: | Component | Scaling Method | Rationale | -|-----------|---------------|-----------| +| --- | --- | --- | | **Weight per-block scales** | Minimizing weight MSE | Calibrated offline; supports scale search | | **Activation per-block scales** | Max-based scaling | Must be computed efficiently at runtime | @@ -65,7 +69,7 @@ AutoQuantize is a mixed-precision quantization algorithm that casts format assig QAD uses the BF16 checkpoint as teacher and the NVFP4 checkpoint as student: | Parameter | Value | -|-----------|-------| +| --- | --- | | **Calibration (PTQ student)** | 2K samples, 131K context from post-training reasoning SFT | | **Loss Function** | Logit-based loss (best of logit, logit+LM, hidden-cosine) | | **Learning Rate** | 1e-5 | @@ -76,10 +80,10 @@ QAD uses the BF16 checkpoint as teacher and the NVFP4 checkpoint as student: The Mamba SSM cache presents a unique quantization challenge: during training the cache is computed via chunked SSD without per-token quantization boundaries, but during inference per-token recurrent quantization accumulates errors across every token. -**Selected Recipe:** FP16 with Stochastic Rounding (Philox<5>) +**Selected Recipe:** FP16 with Stochastic Rounding (Philox\<5>) | Reason | Detail | -|--------|--------| +| --- | --- | | No block scales required | Simpler implementation | | Blackwell hardware support | Dedicated PTX instruction for FP16 conversion with stochastic rounding | | cuRAND support | Philox PRNG on Blackwell via cuRAND | @@ -92,11 +96,11 @@ The Mamba SSM cache presents a unique quantization challenge: during training th Nemotron 3 Super supports four quantization configurations tailored for the Mamba-MoE architecture: | Config Name | Format | Description | -|---|---|---| -| `mamba_moe_fp8_aggressive` | FP8 | Aggressive FP8 quantization for Mamba-MoE | -| `mamba_moe_fp8_conservative` | FP8 | Conservative FP8 quantization for Mamba-MoE | -| `mamba_moe_nvfp4_aggressive` | NVFP4 | Aggressive NVFP4 quantization for Mamba-MoE | -| `mamba_moe_nvfp4_conservative` | NVFP4 | Conservative NVFP4 quantization for Mamba-MoE | +| --- | --- | --- | +| mamba_moe_fp8_aggressive | FP8 | Aggressive FP8 quantization for Mamba-MoE | +| mamba_moe_fp8_conservative | FP8 | Conservative FP8 quantization for Mamba-MoE | +| mamba_moe_nvfp4_aggressive | NVFP4 | Aggressive NVFP4 quantization for Mamba-MoE | +| mamba_moe_nvfp4_conservative | NVFP4 | Conservative NVFP4 quantization for Mamba-MoE | Pass the desired config name via `--export-quant-cfg` to `quantize.py`. @@ -167,51 +171,51 @@ torchrun --nproc_per_node=16 examples/quantization/export.py \ Comparison of BF16, FP8, and NVFP4 checkpoints. -> **Note**: LiveCodeBench uses v6 here (vs v5 in the [post-trained model evaluations](./evaluate.md)), which accounts for the slightly different BF16 baselines between the two tables. +> **Note**: LiveCodeBench uses v6 here (vs v5 in the [post-trained model evaluations](/evaluate)), which accounts for the slightly different BF16 baselines between the two tables. | Benchmark | N-3-Super (BF16) | N-3-Super FP8 | N-3-Super NVFP4 | -|-----------|-------------------|---------------|-----------------| -| **General Knowledge** | | | | +| --- | --- | --- | --- | +| **General Knowledge** | | | | | MMLU-Pro | 83.57 | 83.78 | 83.41 | -| **Reasoning** | | | | +| **Reasoning** | | | | | GPQA (no tools) | 79.29 | 79.67 | 79.23 | | LiveCodeBench (v6 2024-08↔2025-05) | 78.25 | 78.80 | 78.57 | | SciCode (subtask) | 40.64 | 39.87 | 39.94 | | HLE (no tools) | 18.02 | 17.70 | 17.33 | -| **Agentic** | | | | +| **Agentic** | | | | | Terminal Bench (hard) | 25.78 | 26.82 | 25.78 | | TauBench V2 Airline | 57.00 | 55.00 | 55.25 | | TauBench V2 Retail | 65.13 | 62.17 | 63.71 | | TauBench V2 Telecom | 60.96 | 62.39 | 60.63 | -| **Chat & IF** | | | | +| **Chat & IF** | | | | | IFBench (prompt) | 72.91 | 71.25 | 72.79 | | Multi-Challenge | 52.31 | 54.55 | 51.70 | | Arena-Hard-V2 | 75.19 | 74.83 | 75.50 | -| **Long Context** | | | | +| **Long Context** | | | | | AA-LCR | 57.63 | 58.13 | 59.25 | -| **Multilingual** | | | | +| **Multilingual** | | | | | MMLU-ProX (avg) | 80.00 | 78.97 | 79.36 | --- ## Infrastructure -This stage uses the following components from the [NVIDIA AI Stack](../nvidia-stack.md): +This stage uses the following components from the [NVIDIA AI Stack](/../nvidia-stack): | Component | Role | Documentation | -|-----------|------|---------------| -| [Megatron-Core](../nvidia-stack.md#megatron-core) | Distributed training primitives (TP, PP, EP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | -| [Megatron-Bridge](../nvidia-stack.md#megatron-bridge) | PTQ quantization, checkpoint export | [Docs](https://docs.nvidia.com/nemo/megatron-bridge/latest/) | +| --- | --- | --- | +| [Megatron-Core](/../nvidia-stack#megatron-core) | Distributed training primitives (TP, PP, EP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | +| [Megatron-Bridge](/../nvidia-stack#megatron-bridge) | PTQ quantization, checkpoint export | [Docs](https://docs.nvidia.com/nemo/megatron-bridge/latest/) | | [Model-Optimizer](https://github.com/NVIDIA/TensorRT-Model-Optimizer) | Quantization algorithms (FP8, NVFP4), AutoQuantize, QAD | [GitHub](https://github.com/NVIDIA/TensorRT-Model-Optimizer) | | [Transformer Engine](https://github.com/NVIDIA/TransformerEngine) | NVFP4/FP8 GEMM kernels | [GitHub](https://github.com/NVIDIA/TransformerEngine) | ### Parallelism Configuration | Parallelism | Default | Flag | -|-------------|---------|------| -| Tensor (TP) | 8 | `--tp` | -| Pipeline (PP) | 2 | `--pp` | -| Expert (EP) | 8 | `--ep` | +| --- | --- | --- | +| Tensor (TP) | 8 | --tp | +| Pipeline (PP) | 2 | --pp | +| Expert (EP) | 8 | --ep | **Minimum resources:** 2 nodes with 8× H100 GPUs. @@ -220,10 +224,17 @@ This stage uses the following components from the [NVIDIA AI Stack](../nvidia-st ## Reference - [Nemotron 3 Super Tech Report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Super-Technical-Report.pdf) — Quantization methodology + - [Megatron-Bridge Nemotron 3 Super](https://github.com/NVIDIA-NeMo/Megatron-Bridge/blob/super-v3/docs/models/llm/nemotron3-super.md) — MB documentation and examples + - [Model-Optimizer](https://github.com/NVIDIA/TensorRT-Model-Optimizer) — PTQ and AutoQuantize -- [NVIDIA AI Stack](../nvidia-stack.md) — Megatron-Core, Megatron-Bridge, Transformer Engine -- [Stage 2: RL](./rl/index.md) — RL alignment (input to quantization) -- [Stage 4: Evaluation](./evaluate.md) — Benchmark evaluation + +- [NVIDIA AI Stack](/../nvidia-stack) — Megatron-Core, Megatron-Bridge, Transformer Engine + +- [Stage 2: RL](/rl/index) — RL alignment (input to quantization) + +- [Stage 4: Evaluation](/evaluate) — Benchmark evaluation + - **Recipe Source**: `src/nemotron/recipes/super3/` — Implementation details -- [Back to Overview](./README.md) + +- [Back to Overview](/README) diff --git a/docs/nemotron/super3/rl/data-prep.md b/docs/fern/pages-vnightly/nemotron/super3/rl/data-prep.mdx similarity index 71% rename from docs/nemotron/super3/rl/data-prep.md rename to docs/fern/pages-vnightly/nemotron/super3/rl/data-prep.mdx index 056fa6a98..45d9c3610 100644 --- a/docs/nemotron/super3/rl/data-prep.md +++ b/docs/fern/pages-vnightly/nemotron/super3/rl/data-prep.mdx @@ -1,4 +1,8 @@ -# RL Data Preparation +--- +title: "RL Data Preparation" +slug: "nemotron/super3/rl/data-prep.html" +description: "Data preparation for the RL pipeline downloads nvidia/Nemotron-3-Super-RL-Training-Blends from HuggingFace, resolves placeholder entries by fetching from external datasets (DAPO, Skywork), and produce" +--- Data preparation for the RL pipeline downloads `nvidia/Nemotron-3-Super-RL-Training-Blends` from HuggingFace, resolves placeholder entries by fetching from external datasets (DAPO, Skywork), and produces 6 data blends with train/val splits. @@ -25,12 +29,12 @@ flowchart LR ``` | Stage | What Happens | -|-------|--------------| -| **HuggingFace Dataset** | Download `nvidia/Nemotron-3-Super-RL-Training-Blends` (6 blend files) | -| **Placeholder Resolution** | Resolve `_hf_placeholder` records by fetching from external datasets (DAPO, Skywork) and applying template restoration | -| **JSONL Format** | Convert to JSONL with `question`, `expected_answer`, and `responses_create_params` fields | +| --- | --- | +| **HuggingFace Dataset** | Download nvidia/Nemotron-3-Super-RL-Training-Blends (6 blend files) | +| **Placeholder Resolution** | Resolve _hf_placeholder records by fetching from external datasets (DAPO, Skywork) and applying template restoration | +| **JSONL Format** | Convert to JSONL with question, expected_answer, and responses_create_params fields | | **Train/Val Split** | Last 100 rows held out for validation per blend | -| **6 Data Blends** | `rlvr1/`, `rlvr2/`, `rlvr3/`, `swe1/`, `swe2/`, `rlhf/` — each with `train-split.jsonl` + `val-split.jsonl` | +| **6 Data Blends** | rlvr1/, rlvr2/, rlvr3/, swe1/, swe2/, rlhf/ — each with train-split.jsonl + val-split.jsonl | --- @@ -72,19 +76,19 @@ uv run nemotron super3 data prep rl rlhf --run YOUR-CLUSTER Each sub-stage has its own data prep command because the data blends differ (RLVR uses HF placeholder resolution, while SWE/RLHF use direct JSONL splitting). > **`--run YOUR-CLUSTER`** refers to a profile defined in your `env.toml` file. -> See the [env.toml setup guide](../README.md#configuration) for details. +See the [env.toml setup guide](/../README#configuration) for details. | Option | Description | -|--------|-------------| -| `--run ` | Execute on Slurm via [NeMo-Run](../../../nemo_runspec/nemo-run.md) | -| `sample=N` | Limit rows per dataset (for testing) | -| `force=true` | Force re-run, ignoring cache | +| --- | --- | +| --run <profile> | Execute on Slurm via [NeMo-Run](/../../../nemo_runspec/nemo-run) | +| sample=N | Limit rows per dataset (for testing) | +| force=true | Force re-run, ignoring cache | --- ## Output -``` +```default output/stage2_rl_resolved/ ├── rlvr1/ │ ├── train-split.jsonl diff --git a/docs/nemotron/super3/rl/index.md b/docs/fern/pages-vnightly/nemotron/super3/rl/index.mdx similarity index 69% rename from docs/nemotron/super3/rl/index.md rename to docs/fern/pages-vnightly/nemotron/super3/rl/index.mdx index 71943598d..f1459d7af 100644 --- a/docs/nemotron/super3/rl/index.md +++ b/docs/fern/pages-vnightly/nemotron/super3/rl/index.mdx @@ -1,6 +1,10 @@ -# Stage 2: Reinforcement Learning (RL) +--- +title: "Stage 2: Reinforcement Learning (RL)" +slug: "nemotron/super3/rl/index.html" +description: "This stage aligns the instruction-tuned model using GRPO (Group Relative Policy Optimization) with NeMo-RL." +--- -This stage aligns the instruction-tuned model using GRPO (Group Relative Policy Optimization) with [NeMo-RL](../../nvidia-stack.md#nemo-rl). +This stage aligns the instruction-tuned model using GRPO (Group Relative Policy Optimization) with [NeMo-RL](/../../nvidia-stack#nemo-rl). > **Open-Source Data Only**: This recipe uses exclusively open-sourced RL data, which is a subset of the full data used to train the released model. Results will differ from the benchmarks in the tech report. Use this recipe as a reference implementation to apply the methodology with your own data. @@ -9,23 +13,30 @@ This stage aligns the instruction-tuned model using GRPO (Group Relative Policy ## Training Methodology > **Training Framework**: RL alignment is implemented using [NeMo-RL](https://docs.nvidia.com/nemo/rl/latest/) with Ray for distributed actor coordination and vLLM for fast rollout generation. The Megatron backend handles distributed policy training with tensor, pipeline, context, and expert parallelism. See [NeMo-RL Documentation](https://docs.nvidia.com/nemo/rl/latest/) for implementation details. -> -> For complete methodology, see the [Nemotron 3 Super Tech Report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Super-Technical-Report.pdf). + +For complete methodology, see the [Nemotron 3 Super Tech Report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Super-Technical-Report.pdf). ### RL Pipeline Overview The RL pipeline consists of three main stages with 6 total sub-stages, each targeting a different alignment objective: -1. **[Multi-Environment RLVR](rlvr.md)** (3 sub-stages) — Unified training across 21 environments with verifiable rewards - - RL Phase 1.1: RLVR 1 — Initial RL training from SFT checkpoint - - RL Phase 1.2: RLVR 2 — Continued training with second data blend - - RL Phase 1.3: RLVR 3 — Final RLVR with third data blend -2. **[SWE-RL](swe.md)** (2 sub-stages) — End-to-end reinforcement learning for software engineering tasks - - RL Phase 2.1: SWE 1 — SWE-pivot training - - RL Phase 2.2: SWE 2 — SWE-bench training with isolated sandbox environments -3. **[RLHF](rlhf.md)** (1 sub-stage) — Principle-following generative reward model-based alignment +1. **[Multi-Environment RLVR](/rlvr)** (3 sub-stages) — Unified training across 21 environments with verifiable rewards + + - RL Phase 1.1: RLVR 1 — Initial RL training from SFT checkpoint + + - RL Phase 1.2: RLVR 2 — Continued training with second data blend + + - RL Phase 1.3: RLVR 3 — Final RLVR with third data blend -> **Note on numbering**: The RL sub-stage numbering (Phases 1.1–3) is internal to Stage 2 of the overall pipeline. See the [pipeline overview](../README.md) for the top-level stage numbering. +2. **[SWE-RL](/swe)** (2 sub-stages) — End-to-end reinforcement learning for software engineering tasks + + - RL Phase 2.1: SWE 1 — SWE-pivot training + + - RL Phase 2.2: SWE 2 — SWE-bench training with isolated sandbox environments + +3. **[RLHF](/rlhf)** (1 sub-stage) — Principle-following generative reward model-based alignment + +> **Note on numbering**: The RL sub-stage numbering (Phases 1.1–3) is internal to Stage 2 of the overall pipeline. See the [pipeline overview](/../README) for the top-level stage numbering. Each sub-stage uses a different data blend and takes the output checkpoint of the previous sub-stage as input. The RLVR sub-stages share the same config (`stage1_rlvr.yaml`) with different data paths. @@ -54,8 +65,8 @@ Multi-environment RLVR is the primary stage, training on all environments simult ### Per-Stage Parameters -| | RLVR (1.1–1.3) | SWE 1 (2.1) | SWE 2 (2.2) | RLHF (3) | -|---|---|---|---|---| +| | RLVR (1.1–1.3) | SWE 1 (2.1) | SWE 2 (2.2) | RLHF (3) | +| --- | --- | --- | --- | --- | | **Nodes** | 109 | 64 | 64 | 72 | | **Prompts/step** | 256 | 64 | 16 | 128 | | **Gens/prompt** | 16 | 16 | 32 | 16 | @@ -64,7 +75,7 @@ Multi-environment RLVR is the primary stage, training on all environments simult | **Learning rate** | 3e-6 | 1e-6 | 1e-6 | 1e-6 | | **KL penalty** | 0 | 0 | 0 | 1e-4 | | **Overlong filter** | false | true | true | false | -| **Config** | `stage1_rlvr.yaml` | `stage2_swe1.yaml` | `stage2_swe2.yaml` | `stage3_rlhf.yaml` | +| **Config** | stage1_rlvr.yaml | stage2_swe1.yaml | stage2_swe2.yaml | stage3_rlhf.yaml | Node counts assume B200 nodes with 8 GPUs each and may need adjustment for other GPU types. @@ -73,11 +84,14 @@ Node counts assume B200 nodes with 8 GPUs each and may need adjustment for other GRPO (Group Relative Policy Optimization) optimizes the policy using group-relative advantages: 1. **Generate responses** from the current policy using vLLM + 2. **Evaluate** responses using NeMo-Gym reward environments + 3. **Compute group-relative advantages** across response groups per prompt + 4. **Update the policy** to favor higher-reward responses with clipped gradients -All stages use **asynchronous GRPO** where training and inference are decoupled across separate GPU devices. See [RLVR](rlvr.md#algorithm) for full algorithm details. +All stages use **asynchronous GRPO** where training and inference are decoupled across separate GPU devices. See [RLVR](/rlvr#algorithm) for full algorithm details. --- @@ -86,8 +100,11 @@ All stages use **asynchronous GRPO** where training and inference are decoupled ### Prerequisites - **NeMo-RL repo**: Clone the `super-v3` branch + - **Sandbox container**: Required for code execution environments + - **SWE container**: Required for SWE stages 2.1 and 2.2 (pre-fetched venvs) — see [SWE container build](#swe-container) below + - **SIF images**: Required for Stage 2.2 only (SWE-bench sandbox environments (Apptainer `.sif` on SLURM, or Docker/Podman)) ### Using nemotron CLI (Recommended) @@ -119,8 +136,8 @@ uv run nemotron super3 rl rlvr -c test --run YOUR-CLUSTER ``` > **`--run YOUR-CLUSTER`** refers to a profile defined in your `env.toml` file, -> which configures SLURM account, partition, mounts, and other cluster settings. -> See the [env.toml setup guide](../README.md#configuration) for details. +which configures SLURM account, partition, mounts, and other cluster settings. +See the [env.toml setup guide](/../README#configuration) for details. ### Using super_launch.sh (Direct) @@ -158,14 +175,14 @@ done Set these environment variables before launching each stage: | Variable | Description | -|----------|-------------| -| `DATA_DIR` | Path to the `data/` directory produced above | -| `SANDBOX_CONTAINER` | Sandbox container image (`.sqsh` path or registry URI) | -| `PERSISTENT_CACHE` | Directory for vLLM and FlashInfer caches | -| `EXTRA_MOUNTS` | Comma-separated `host:container` mount pairs for shared filesystems | -| `SIF_DIR` | *(Stage 2.2 only)* Directory containing Apptainer `.sif` images | -| `SLURM_PARTITION` | Slurm partition | -| `SLURM_ACCOUNT` | Slurm account | +| --- | --- | +| DATA_DIR | Path to the data/ directory produced above | +| SANDBOX_CONTAINER | Sandbox container image (.sqsh path or registry URI) | +| PERSISTENT_CACHE | Directory for vLLM and FlashInfer caches | +| EXTRA_MOUNTS | Comma-separated host:container mount pairs for shared filesystems | +| SIF_DIR | *(Stage 2.2 only)* Directory containing Apptainer .sif images | +| SLURM_PARTITION | Slurm partition | +| SLURM_ACCOUNT | Slurm account | Then launch each stage sequentially. `MODEL_PATH` is the input checkpoint — Stage 1.1 starts from SFT; every subsequent stage takes the output of the previous one. @@ -185,7 +202,7 @@ SLURM_ACCOUNT=$SLURM_ACCOUNT \ bash super_launch.sh ``` -See [RLVR](rlvr.md), [SWE-RL](swe.md), and [RLHF](rlhf.md) for complete launch commands for each stage. +See [RLVR](/rlvr), [SWE-RL](/swe), and [RLHF](/rlhf) for complete launch commands for each stage. --- @@ -194,30 +211,30 @@ See [RLVR](rlvr.md), [SWE-RL](swe.md), and [RLHF](rlhf.md) for complete launch c ### Config Files | File | Purpose | Details | -|------|---------|---------| -| `stage1_rlvr.yaml` | RLVR stages 1.1–1.3 (109 nodes, 21 environments) | [RLVR](rlvr.md) | -| `stage2_swe1.yaml` | SWE stage 2.1 — SWE-pivot (64 nodes) | [SWE-RL](swe.md#stage-21--swe-1-64-nodes) | -| `stage2_swe2.yaml` | SWE stage 2.2 — SWE-bench with sandbox containers (64 nodes) | [SWE-RL](swe.md#stage-22--swe-2-64-nodes) | -| `stage3_rlhf.yaml` | RLHF stage (72 nodes, GenRM reward) | [RLHF](rlhf.md) | -| `small_*.yaml` | Reduced-scale variants for testing | | -| `default.yaml` | Base GRPO configuration | | -| `tiny.yaml` | Testing variant (1 node) | | +| --- | --- | --- | +| stage1_rlvr.yaml | RLVR stages 1.1–1.3 (109 nodes, 21 environments) | [RLVR](/rlvr) | +| stage2_swe1.yaml | SWE stage 2.1 — SWE-pivot (64 nodes) | [SWE-RL](/swe#stage-2-1-swe-1-64-nodes) | +| stage2_swe2.yaml | SWE stage 2.2 — SWE-bench with sandbox containers (64 nodes) | [SWE-RL](/swe#stage-2-2-swe-2-64-nodes) | +| stage3_rlhf.yaml | RLHF stage (72 nodes, GenRM reward) | [RLHF](/rlhf) | +| small_*.yaml | Reduced-scale variants for testing | | +| default.yaml | Base GRPO configuration | | +| tiny.yaml | Testing variant (1 node) | | ### Data Preparation -The `data_prep.py` script downloads `nvidia/Nemotron-3-Super-RL-Training-Blends` from HuggingFace, resolves placeholder entries, and produces 6 data blends. See [Data Preparation](data-prep.md) for details. +The `data_prep.py` script downloads `nvidia/Nemotron-3-Super-RL-Training-Blends` from HuggingFace, resolves placeholder entries, and produces 6 data blends. See [Data Preparation](/data-prep) for details. --- ## Infrastructure -This stage uses the following components from the [NVIDIA AI Stack](../../nvidia-stack.md): +This stage uses the following components from the [NVIDIA AI Stack](/../../nvidia-stack): | Component | Role | Documentation | -|-----------|------|---------------| -| [NeMo-RL](../../nvidia-stack.md#nemo-rl) | Async GRPO algorithm, policy training, reward computation | [Docs](https://docs.nvidia.com/nemo/rl/latest/) | +| --- | --- | --- | +| [NeMo-RL](/../../nvidia-stack#nemo-rl) | Async GRPO algorithm, policy training, reward computation | [Docs](https://docs.nvidia.com/nemo/rl/latest/) | | [NeMo-Gym](https://github.com/NVIDIA-NeMo/Gym) | Multi-environment reward evaluation (21+ environments) | [GitHub](https://github.com/NVIDIA-NeMo/Gym) | -| [Megatron-Core](../../nvidia-stack.md#megatron-core) | Distributed training primitives (TP, PP, CP, EP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | +| [Megatron-Core](/../../nvidia-stack#megatron-core) | Distributed training primitives (TP, PP, CP, EP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | | [Ray](https://ray.io/) | Distributed actor coordination and resource management | [Docs](https://docs.ray.io/) | | vLLM | Fast rollout generation | [GitHub](https://github.com/vllm-project/vllm) | @@ -225,7 +242,7 @@ This stage uses the following components from the [NVIDIA AI Stack](../../nvidia All RL stages use the base NeMo-RL container: -``` +```default nvcr.io/nvidia/nemo-rl:v0.5.0.nemotron_3_super ``` @@ -241,10 +258,10 @@ included in the base image. Build the SWE container once (from within the docker buildx build \ -t your-registry/nemo-rl:v0.5.0.nemotron_3_super_swe \ --push \ - -f- . <<'EOF' + -f- . \<\<'EOF' FROM nvcr.io/nvidia/nemo-rl:v0.5.0.nemotron_3_super -RUN <<'RUNEOF' +RUN \<\<'RUNEOF' set -euxo pipefail UV_TORCH_BACKEND=$(uv run python -c "import tomllib,pathlib; \ indexes=tomllib.loads(pathlib.Path('pyproject.toml').read_text())['tool']['uv']['index']; \ @@ -256,28 +273,24 @@ RUNEOF EOF ``` -SWE2 additionally requires Apptainer `.sif` images — see [SWE-RL Stage 2.2](swe.md#prerequisites). +SWE2 additionally requires Apptainer `.sif` images — see [SWE-RL Stage 2.2](/swe#prerequisites). --- ## Next Steps -After RL completes, the aligned model can be [quantized](../quantization.md) for efficient deployment or [evaluated](../evaluate.md) against standard benchmarks. +After RL completes, the aligned model can be [quantized](/../quantization) for efficient deployment or [evaluated](/../evaluate) against standard benchmarks. ## Reference - [Nemotron 3 Super Tech Report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Super-Technical-Report.pdf) — RL methodology + - [NeMo-RL Documentation](https://docs.nvidia.com/nemo/rl/latest/) — GRPO, DPO, environments -- [NVIDIA AI Stack](../../nvidia-stack.md) — NeMo-RL, Megatron-Core documentation -- [Artifact Lineage](../../../nemo_runspec/artifacts.md) — W&B artifact system -- **Recipe Source**: `src/nemotron/recipes/super3/stage2_rl/` — Implementation details -- [Back to Overview](../README.md) -```{toctree} -:hidden: +- [NVIDIA AI Stack](/../../nvidia-stack) — NeMo-RL, Megatron-Core documentation -rlvr.md -swe.md -rlhf.md -data-prep.md -``` +- [Artifact Lineage](/../../../nemo_runspec/artifacts) — W&B artifact system + +- **Recipe Source**: `src/nemotron/recipes/super3/stage2_rl/` — Implementation details + +- [Back to Overview](/../README) diff --git a/docs/nemotron/super3/rl/rlhf.md b/docs/fern/pages-vnightly/nemotron/super3/rl/rlhf.mdx similarity index 86% rename from docs/nemotron/super3/rl/rlhf.md rename to docs/fern/pages-vnightly/nemotron/super3/rl/rlhf.mdx index dfeca5322..e8c0b315a 100644 --- a/docs/nemotron/super3/rl/rlhf.md +++ b/docs/fern/pages-vnightly/nemotron/super3/rl/rlhf.mdx @@ -1,4 +1,8 @@ -# RLHF (Stage 3) +--- +title: "RLHF (Stage 3)" +slug: "nemotron/super3/rl/rlhf.html" +description: "Reinforcement Learning from Human Feedback is the final RL stage, run after RLVR and SWE-RL to improve model behavior and interaction quality." +--- Reinforcement Learning from Human Feedback is the final RL stage, run after RLVR and SWE-RL to improve model behavior and interaction quality. @@ -6,12 +10,12 @@ Reinforcement Learning from Human Feedback is the final RL stage, run after RLVR ## Approach -Uses a large **Generative Reward Model (GenRM)** to provide supervision during RL. The GenRM is a principle-following model trained as described in [RL-BFF](https://arxiv.org/abs/2505.18849), which allows guiding Nemotron Super 3's behavior on important domains like identity and safety-related topics. +Uses a large **Generative Reward Model (GenRM)** to provide supervision during RL. The GenRM is a principle-following model trained as described in [RL-BFF](https://arxiv.org/abs/2505.18849), which allows guiding Nemotron Super 3’s behavior on important domains like identity and safety-related topics. ### GenRM Model | Parameter | Value | -|-----------|-------| +| --- | --- | | **Initialization** | Qwen3-235B-A22B-Thinking-2507 | | **Training Data** | [HelpSteer 3](https://huggingface.co/datasets/nvidia/HelpSteer3) + commercially friendly subsets of lmarena-140k + recently collected human preference data | | **Approach** | Principle-following GenRM for guiding behavior on identity and safety domains | @@ -27,7 +31,7 @@ Unlike the RLVR and SWE stages (which use KL=0), RLHF applies a **KL penalty of ## Configuration | Parameter | Value | -|-----------|-------| +| --- | --- | | Nodes | 72 (576 GPUs) | | Generation nodes | 32 (colocated=false) | | NeMo Gym GPU nodes | 8 | @@ -46,11 +50,13 @@ Unlike the RLVR and SWE stages (which use KL=0), RLHF applies a **KL penalty of The RLHF stage uses GenRM comparison as the primary reward signal, along with tool use evaluation: - `genrm_compare` — Pairwise comparison using the GenRM model with principle-following prompts + - `single_step_tool_use_with_argument_comparison` — Tool use correctness ### Config Files - `stage3_rlhf/config/default.yaml` — Full-scale 72-node config + - `stage3_rlhf/config/small.yaml` — Reduced 24-node variant for testing --- @@ -64,7 +70,7 @@ uv run nemotron super3 rl rlhf --run YOUR-CLUSTER ``` > **`--run YOUR-CLUSTER`** refers to a profile defined in your `env.toml` file. -> See the [env.toml setup guide](../README.md#configuration) for details. +See the [env.toml setup guide](/../README#configuration) for details. ### Using super_launch.sh @@ -88,6 +94,7 @@ bash super_launch.sh ## References - [RL-BFF: Reinforcement Learning with Best-of-F Feedback](https://arxiv.org/abs/2505.18849) + - [HelpSteer 3](https://huggingface.co/datasets/nvidia/HelpSteer3) **Recipe Source**: `src/nemotron/recipes/super3/stage2_rl/stage3_rlhf/` diff --git a/docs/nemotron/super3/rl/rlvr.md b/docs/fern/pages-vnightly/nemotron/super3/rl/rlvr.mdx similarity index 87% rename from docs/nemotron/super3/rl/rlvr.md rename to docs/fern/pages-vnightly/nemotron/super3/rl/rlvr.mdx index 8d9ec56f2..f7a61846f 100644 --- a/docs/nemotron/super3/rl/rlvr.md +++ b/docs/fern/pages-vnightly/nemotron/super3/rl/rlvr.mdx @@ -1,4 +1,8 @@ -# Multi-Environment RLVR (Stages 1.1–1.3) +--- +title: "Multi-Environment RLVR (Stages 1.1–1.3)" +slug: "nemotron/super3/rl/rlvr.html" +description: "Multi-environment Reinforcement Learning from Verifiable Rewards (RLVR) is the primary RL stage for Nemotron 3 Super. It trains on 21 environments and 37 datasets simultaneously, covering math, code, " +--- Multi-environment Reinforcement Learning from Verifiable Rewards (RLVR) is the primary RL stage for Nemotron 3 Super. It trains on 21 environments and 37 datasets simultaneously, covering math, code, STEM, safety, chat, instruction following, long context, puzzles, and agentic tasks. @@ -11,7 +15,7 @@ The RLVR stage consists of 3 sub-stages with different data blends. All 3 use th ## Data | Domain | Description | -|--------|-------------| +| --- | --- | | **Math** | Competitive math problems, trained with and without python execution tool. Includes formal proof verification environment. | | **Code** | Competition code data. | | **STEM** | Scientific problems including newly curated difficult problems. | @@ -28,7 +32,7 @@ The RLVR stage consists of 3 sub-stages with different data blends. All 3 use th A subset of prompts are converted to low-effort mode. For each low-effort prompt, the reward accounts for both correctness and token count, encouraging efficient reasoning. | Phase | Scope | Proportion | -|-------|-------|------------| +| --- | --- | --- | | Early | Math, STEM QA, Competitive Coding | 2% of all RL prompts | | Late | Math, STEM QA only | 1% of RL prompts | @@ -39,11 +43,17 @@ A subset of prompts are converted to low-effort mode. For each low-effort prompt Uses **asynchronous GRPO** where training and inference are decoupled across separate GPU devices: - Inference workers continuously generate trajectories stored in a rollout buffer + - Batches are sent to the training engine once enough trajectories are collected + - Updated weights are pushed to inference workers as soon as a new model version is available + - **In-flight weight updates**: weights can be pushed mid-rollout without waiting for ongoing rollouts to finish + - KV cache is NOT recomputed after weight updates + - Policy lag is limited to at most one step behind the latest model version + - Importance sampling ratio masking stabilizes training under the training-inference mismatch --- @@ -51,7 +61,7 @@ Uses **asynchronous GRPO** where training and inference are decoupled across sep ## Configuration | Parameter | Value | -|-----------|-------| +| --- | --- | | Nodes | 109 (872 GPUs) | | Generation nodes | 72 (colocated=false) | | NeMo Gym GPU nodes | 5 | @@ -67,16 +77,17 @@ Uses **asynchronous GRPO** where training and inference are decoupled across sep ### Parallelism | Parallelism | Value | Config Key | -|-------------|-------|------------| -| Tensor (TP) | 4 | `policy.megatron_cfg.tensor_model_parallel_size` | -| Pipeline (PP) | 1 | `policy.megatron_cfg.pipeline_model_parallel_size` | -| Context (CP) | 8 | `policy.megatron_cfg.context_parallel_size` | -| Expert (EP) | 8 | `policy.megatron_cfg.expert_model_parallel_size` | -| Sequence (SP) | Yes | `policy.megatron_cfg.sequence_parallel` | +| --- | --- | --- | +| Tensor (TP) | 4 | policy.megatron_cfg.tensor_model_parallel_size | +| Pipeline (PP) | 1 | policy.megatron_cfg.pipeline_model_parallel_size | +| Context (CP) | 8 | policy.megatron_cfg.context_parallel_size | +| Expert (EP) | 8 | policy.megatron_cfg.expert_model_parallel_size | +| Sequence (SP) | Yes | policy.megatron_cfg.sequence_parallel | ### Config Files - `stage1_rlvr/config/default.yaml` — Full-scale 109-node config + - `stage1_rlvr/config/small.yaml` — Reduced 21-node variant for testing --- @@ -86,13 +97,15 @@ Uses **asynchronous GRPO** where training and inference are decoupled across sep All RLVR experiments use an integrated NeMo RL + NeMo Gym infrastructure: - **NeMo RL** acts as the RL training loop controller using Megatron-Core for model training + - **NeMo Gym** handles rollout environments using three server types: agents, models (vLLM), and resources (verifiers) + - **Ray** orchestrates resource management on SLURM — training workers, vLLM generation workers, Gym environments, and judge models all run on a single Ray cluster ### Judge Models | Model | Purpose | -|-------|---------| +| --- | --- | | Qwen3-235B-A22B | Equivalence/instruction-following judging | | Nemotron-Content-Safety-Reasoning-4B | Safety evaluation | | Qwen3-Nemotron-235B-A22B-GenRM | GenRM pairwise comparison | @@ -102,7 +115,9 @@ All RLVR experiments use an integrated NeMo RL + NeMo Gym infrastructure: At 1K GPU scale, intermittent failures from hardware and software issues required: - Parallelized initialization with prefetching of virtual environments and binaries + - Careful port management to avoid TOCTOU race conditions between Ray control plane, vLLM workers, TCP rendezvous, and NeMo Gym servers + - Caching in upstream repos (vLLM, flashinfer) to reduce startup time --- @@ -119,7 +134,7 @@ uv run nemotron super3 rl rlvr -c rlvr3 --run YOUR-CLUSTER ``` > **`--run YOUR-CLUSTER`** refers to a profile defined in your `env.toml` file. -> See the [env.toml setup guide](../README.md#configuration) for details. +See the [env.toml setup guide](/../README#configuration) for details. ### Using super_launch.sh diff --git a/docs/nemotron/super3/rl/swe.md b/docs/fern/pages-vnightly/nemotron/super3/rl/swe.mdx similarity index 88% rename from docs/nemotron/super3/rl/swe.md rename to docs/fern/pages-vnightly/nemotron/super3/rl/swe.mdx index fe3ae0a0d..37fcb39cd 100644 --- a/docs/nemotron/super3/rl/swe.md +++ b/docs/fern/pages-vnightly/nemotron/super3/rl/swe.mdx @@ -1,4 +1,8 @@ -# SWE-RL (Stages 2.1–2.2) +--- +title: "SWE-RL (Stages 2.1–2.2)" +slug: "nemotron/super3/rl/swe.html" +description: "End-to-end RL for software engineering tasks. SWE-RL is handled as a separate stage because its rollouts take substantially longer and require much longer context lengths, making it a throughput bottl" +--- End-to-end RL for software engineering tasks. SWE-RL is handled as a separate stage because its rollouts take substantially longer and require much longer context lengths, making it a throughput bottleneck when trained alongside the other RLVR environments. @@ -12,10 +16,10 @@ Both SWE stages require pre-fetched Python virtual environments that are not inc docker buildx build \ -t your-registry/nemo-rl:v0.5.0.nemotron_3_super_swe \ --push \ - -f- . <<'EOF' + -f- . \<\<'EOF' FROM nvcr.io/nvidia/nemo-rl:v0.5.0.nemotron_3_super -RUN <<'RUNEOF' +RUN \<\<'RUNEOF' set -euxo pipefail UV_TORCH_BACKEND=$(uv run python -c "import tomllib,pathlib; \ indexes=tomllib.loads(pathlib.Path('pyproject.toml').read_text())['tool']['uv']['index']; \ @@ -43,7 +47,7 @@ SWE-pivot training using a single-step tool use comparison approach. The model r ### Configuration | Parameter | Value | -|-----------|-------| +| --- | --- | | Nodes | 64 (512 GPUs) | | Generation nodes | 32 (colocated=false) | | Prompts/step | 64 | @@ -59,6 +63,7 @@ SWE-pivot training using a single-step tool use comparison approach. The model r ### Config Files - `stage2_swe1/config/default.yaml` — Full-scale 64-node config + - `stage2_swe1/config/small.yaml` — Reduced 8-node variant for testing ### Using nemotron CLI @@ -68,9 +73,9 @@ uv run nemotron super3 rl swe1 --run YOUR-CLUSTER ``` > **`--run YOUR-CLUSTER`** refers to a profile defined in your `env.toml` file. -> See the [env.toml setup guide](../README.md#configuration) for details. -> -> SWE stages require the [SWE container](index.md#swe-container) with pre-fetched venvs. +See the [env.toml setup guide](/../README#configuration) for details. + +SWE stages require the [SWE container](/index#swe-container) with pre-fetched venvs. ### Using super_launch.sh @@ -98,7 +103,7 @@ Full SWE-bench training with container-isolated sandboxes. Each rollout launches ### Configuration | Parameter | Value | -|-----------|-------| +| --- | --- | | Nodes | 64 (512 GPUs) | | Generation nodes | 32 (colocated=false) | | Prompts/step | 16 | @@ -129,16 +134,16 @@ Each SWE task instance needs an isolated environment with its own filesystem to Because Apptainer shares the host kernel and memory space, additional safeguards are needed: | Component | Description | -|-----------|-------------| -| **Memory Watchdog** | Monitors aggregate RSS of tmux process trees and proactively kills runaway processes, since Apptainer containers share host memory (unlike Docker's cgroup isolation). | -| **Command Blocklist** | Regex-based blocklist intercepts dangerous commands (`killall`, `pkill`) that could terminate training processes or vLLM servers on the same node. | +| --- | --- | +| **Memory Watchdog** | Monitors aggregate RSS of tmux process trees and proactively kills runaway processes, since Apptainer containers share host memory (unlike Docker’s cgroup isolation). | +| **Command Blocklist** | Regex-based blocklist intercepts dangerous commands (killall, pkill) that could terminate training processes or vLLM servers on the same node. | These safeguards are less critical when using Docker or Podman, which provide cgroup-based process and memory isolation by default. #### Agent Loop | Component | Description | -|-----------|-------------| +| --- | --- | | **OpenHands Agent Loop** | Manages the full lifecycle: initializing runtime, presenting problems, running agent steps (up to 200 turns), extracting git patches, and running tests for binary reward. | | **Harness Diversity** | OpenCode and Codex agent classes within OpenHands match external harness tool formats (Claude Code, Codex CLI) for training diversity. | @@ -164,9 +169,9 @@ uv run nemotron super3 rl swe2 \ ``` > **`--run YOUR-CLUSTER`** refers to a profile defined in your `env.toml` file. -> See the [env.toml setup guide](../README.md#configuration) for details. -> -> SWE stages require the [SWE container](index.md#swe-container) with pre-fetched venvs. +See the [env.toml setup guide](/../README#configuration) for details. + +SWE stages require the [SWE container](/index#swe-container) with pre-fetched venvs. ### Using super_launch.sh diff --git a/docs/nemotron/super3/sft.md b/docs/fern/pages-vnightly/nemotron/super3/sft.mdx similarity index 72% rename from docs/nemotron/super3/sft.md rename to docs/fern/pages-vnightly/nemotron/super3/sft.mdx index 85002b9a6..c4ee64d0f 100644 --- a/docs/nemotron/super3/sft.md +++ b/docs/fern/pages-vnightly/nemotron/super3/sft.mdx @@ -1,6 +1,10 @@ -# Stage 1: Supervised Fine-Tuning (SFT) +--- +title: "Stage 1: Supervised Fine-Tuning (SFT)" +slug: "nemotron/super3/sft.html" +description: "This stage fine-tunes the pretrained Nemotron 3 Super model for instruction following using Megatron-Bridge." +--- -This stage fine-tunes the pretrained Nemotron 3 Super model for instruction following using [Megatron-Bridge](../nvidia-stack.md#megatron-bridge). +This stage fine-tunes the pretrained Nemotron 3 Super model for instruction following using [Megatron-Bridge](/../nvidia-stack#megatron-bridge). --- @@ -8,7 +12,7 @@ This stage fine-tunes the pretrained Nemotron 3 Super model for instruction foll > **Chat Template**: The chat template is identical to Nemotron 3 Nano. -> **Training Framework**: SFT is implemented using [Megatron-Bridge](https://docs.nvidia.com/nemo/megatron-bridge/latest/)'s `finetune()` entry point, which loads a pretrained checkpoint and handles the training loop with role-based loss masking. See [Training Entry Points](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/entry-points.html) for implementation details. +> **Training Framework**: SFT is implemented using [Megatron-Bridge](https://docs.nvidia.com/nemo/megatron-bridge/latest/)’s `finetune()` entry point, which loads a pretrained checkpoint and handles the training loop with role-based loss masking. See [Training Entry Points](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/entry-points.html) for implementation details. ### Two-Stage SFT Loss @@ -16,18 +20,12 @@ Nemotron 3 Super uses a novel **two-stage SFT loss** procedure. The model is sup **Stage 1: Token-level (global) average.** The loss averages over all output tokens in the packed global batch: -$$ -\mathcal{L}_{\text{tok}} = \frac{\sum_{c \in \mathcal{B}} \sum_{t \in \mathcal{O}_c} \ell_t}{\sum_{c \in \mathcal{B}} |\mathcal{O}_c|} -$$ - +\mathcal\{L\}_\{\text\{tok\}\} = \frac\{\sum_\{c \in \mathcal\{B\}\} \sum_\{t \in \mathcal\{O\}_c\} \ell_t\}\{\sum_\{c \in \mathcal\{B\}\} |\mathcal\{O\}_c|\} This corresponds to summing output-token log probabilities across all conversations and normalizing by the total number of output tokens. **Stage 2: Sample-level average.** The loss then switches to a per-conversation normalized loss averaged equally across conversations: -$$ -\mathcal{L}_{\text{samp}} = \frac{1}{|\mathcal{B}|} \sum_{c \in \mathcal{B}} \left( \frac{1}{|\mathcal{O}_c|} \sum_{t \in \mathcal{O}_c} \ell_t \right) -$$ - +\mathcal\{L\}_\{\text\{samp\}\} = \frac\{1\}\{|\mathcal\{B\}|\} \sum_\{c \in \mathcal\{B\}\} \left( \frac\{1\}\{|\mathcal\{O\}_c|\} \sum_\{t \in \mathcal\{O\}_c\} \ell_t \right) This stage reduces the dominance of long outputs by normalizing each conversation by its own output-token count before averaging across the batch. The switch from token-level to sample-level loss is configured in the recipe YAML (`config/default.yaml`). @@ -65,12 +63,12 @@ flowchart LR ``` | Stage | What Happens | -|-------|--------------| -| **OpenAI Chat Format** | Input messages with `role` (system/user/assistant) and `content` fields | +| --- | --- | +| **OpenAI Chat Format** | Input messages with role (system/user/assistant) and content fields | | **Chat Template** | Renders messages using the Jinja chat template (identical to Nemotron 3 Nano) | | **Role-Labeled Chunks** | Splits rendered text back into chunks, each tagged with its source role | | **Tokenization** | Converts text chunks to token IDs | -| **Loss Mask** | Builds mask: `1` for assistant tokens, `0` for system/user tokens | +| **Loss Mask** | Builds mask: 1 for assistant tokens, 0 for system/user tokens | | **Packing** | Multiple sequences packed into fixed-length bins (4096 tokens) | | **Mask Rolling** | Shifts mask by 1 position for next-token prediction alignment | @@ -81,10 +79,10 @@ flowchart LR Loss masking determines which tokens contribute to the training loss. In SFT, we only want the model to learn to generate responses—not to predict prompts or system instructions. | Role | Loss Mask | Training Signal | -|------|-----------|-----------------| -| `system` | 0 | Ignored (instructions) | -| `user` | 0 | Ignored (prompts) | -| `assistant` | 1 | Learned (responses) | +| --- | --- | --- | +| system | 0 | Ignored (instructions) | +| user | 0 | Ignored (prompts) | +| assistant | 1 | Learned (responses) | ### Packed Sequences @@ -93,23 +91,23 @@ Individual chat conversations vary in length. Packing concatenates multiple conv The packed sequence format stores everything Megatron-Bridge needs for training: | Field | Description | -|-------|-------------| -| `input_ids` | Concatenated token IDs from multiple conversations | -| `loss_mask` | Rolled mask indicating which positions contribute to loss | -| `seq_start_id` | Boundary indices marking where each original conversation starts within the pack | +| --- | --- | +| input_ids | Concatenated token IDs from multiple conversations | +| loss_mask | Rolled mask indicating which positions contribute to loss | +| seq_start_id | Boundary indices marking where each original conversation starts within the pack | Megatron-Bridge uses `seq_start_id` boundaries for variable-length attention (preventing cross-conversation attention leak) and FlashAttention optimization. ### SFT Data Domains -![SFT data blend distribution](../../assets/super3/super_sft_blend.png) +![SFT data blend distribution](../../../_images/super_sft_blend.png) The SFT dataset covers 15+ domains across **7M total samples**: #### Reused from Nano3 | Domain | Description | -|--------|-------------| +| --- | --- | | **Chat** | General conversational data | | **Infinibyte** | Cross-domain synthesis | | **Formal Proofs** | Mathematical proof generation | @@ -117,7 +115,7 @@ The SFT dataset covers 15+ domains across **7M total samples**: #### Refreshed with New Teachers (DeepSeek v3.2, Kimi K2) | Domain | Description | -|--------|-------------| +| --- | --- | | **Competition Math** | Competitive mathematics problems | | **Competition Code** | Competitive programming problems | | **Conversational Tool Use** | Multi-turn tool-using interactions (fully rebuilt pipeline: scaled from 5 domains/15K conversations in Nano3 to 838 domains/279K conversations) | @@ -127,7 +125,7 @@ The SFT dataset covers 15+ domains across **7M total samples**: #### New Domains | Domain | Description | Scale | -|--------|-------------|-------| +| --- | --- | --- | | **Software Engineering** | Coding tasks from GitHub issues (SWE-Gym, R2E-Gym, SWE-rebench) distilled via OpenHands with Qwen3-Coder-480B | — | | **Agentic Programming** | Agentic CLI tasks: solution synthesis, SWE tasks, web development across Codex/OpenCode/Qwen Code CLI harnesses | ~28K tasks | | **Long Context** | Multi-document QA at 128K–512K context with multi-hop reasoning (4–7 retrieval steps) + 7 synthetic sequential reasoning tasks | — | @@ -143,7 +141,7 @@ The SFT dataset covers 15+ domains across **7M total samples**: Nemotron 3 Super supports **three reasoning modes**: | Mode | Description | -|------|-------------| +| --- | --- | | **Reasoning-off** | No reasoning traces (3% of samples have reasoning stripped) | | **Regular reasoning** | Standard chain-of-thought reasoning | | **Low-effort reasoning** | New: shorter reasoning traces generated by GPT-OSS-120B low-effort mode (2% of SFT data) | @@ -155,7 +153,7 @@ Both regular and low-effort modes support **inference-time budget control**. Aft #### Full SFT (default) | Parameter | Value | -|-----------|-------| +| --- | --- | | **Learning Rate** | 1e-5 (constant after warmup) | | **LR Warmup** | 30,000 samples (linear ramp to constant LR) | | **Sequence Packing** | Up to 256K context | @@ -172,9 +170,9 @@ Both regular and low-effort modes support **inference-time budget control**. Aft #### LoRA Fine-Tuning | Parameter | Value | -|-----------|-------| +| --- | --- | | **Learning Rate** | 1e-4 | -| **Target Modules** | `linear_qkv`, `linear_proj`, `linear_fc1`, `linear_fc2`, `in_proj`, `out_proj` | +| **Target Modules** | linear_qkv, linear_proj, linear_fc1, linear_fc2, in_proj, out_proj | | **Parallelism** | TP=1, EP=1 | ### Troubleshooting @@ -182,15 +180,17 @@ Both regular and low-effort modes support **inference-time budget control**. Aft Common data preparation errors and solutions: | Error | Cause | Solution | -|-------|-------|----------| +| --- | --- | --- | | Empty sequences after processing | All tokens masked (no assistant content) | Verify input data contains assistant responses | | Template rendering mismatch | Tokenizer BPE splits differ from template expectations | Ensure tokenizer model matches the one used during template creation | -| Sequences truncated excessively | Many conversations exceed `max_doc_tokens` | Consider increasing `max_doc_tokens` or `pack_size` | +| Sequences truncated excessively | Many conversations exceed max_doc_tokens | Consider increasing max_doc_tokens or pack_size | **Debugging tips:** - Use `--sample 100` to test data preparation on a small subset + - Check `metadata.json` output for statistics on filtered/truncated sequences + - Review W&B artifacts for lineage tracking and validation metrics --- @@ -200,7 +200,6 @@ Common data preparation errors and solutions: ### Quick Start
- ```console // 1. Prepare data (apply chat templates, tokenize to Packed Parquet) $ uv run nemotron super3 data prep sft --run YOUR-CLUSTER @@ -210,8 +209,7 @@ $ uv run nemotron super3 sft --run YOUR-CLUSTER ```
- -> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](../../nemo_runspec/nemo-run.md). See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for setup. +> **Note**: The `--run YOUR-CLUSTER` flag submits jobs via [NeMo-Run](/../../nemo_runspec/nemo-run). See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for setup. #### Direct Script Execution (Megatron-Bridge) @@ -254,14 +252,14 @@ See the [Megatron-Bridge Nemotron 3 Super documentation](https://github.com/NVID ### Configuration | File | Purpose | -|------|---------| -| `config/default.yaml` | Production configuration (full SFT) | -| `config/tiny.yaml` | Quick testing configuration | -| `config/data_prep/default.yaml` | Data preparation settings | +| --- | --- | +| config/default.yaml | Production configuration (full SFT) | +| config/tiny.yaml | Quick testing configuration | +| config/data_prep/default.yaml | Data preparation settings | ### Data Preparation -The `data_prep.py` script processes OpenAI-format chat data into packed sequences with role-based loss masking. See [Data Preparation Module](../data-prep.md) for detailed documentation. +The `data_prep.py` script processes OpenAI-format chat data into packed sequences with role-based loss masking. See [Data Preparation Module](/../data-prep) for detailed documentation. #### CLI Command @@ -270,14 +268,14 @@ uv run nemotron super3 data prep sft [options] ``` | Option | Description | -|--------|-------------| -| `--run ` | Execute on Slurm via [NeMo-Run](../../nemo_runspec/nemo-run.md) | -| `--sample N` | Limit rows per dataset (for testing) | -| `--force` | Force re-run, ignoring cache | +| --- | --- | +| --run <profile> | Execute on Slurm via [NeMo-Run](/../../nemo_runspec/nemo-run) | +| --sample N | Limit rows per dataset (for testing) | +| --force | Force re-run, ignoring cache | #### Output -``` +```default output/stage1_sft/ ├── blend.json ├── splits/ @@ -286,11 +284,11 @@ output/stage1_sft/ │ │ └── ... │ ├── valid/ │ └── test/ -└── runs/{run_hash}/ - └── datasets/{name}/{hash}/ +└── runs/\{run_hash\}/ + └── datasets/\{name\}/\{hash\}/ ``` -The output is registered as a [W&B Artifact](../../nemo_runspec/artifacts.md) (`SFTDataArtifact-sft`) for lineage tracking. +The output is registered as a [W&B Artifact](/../../nemo_runspec/artifacts) (`SFTDataArtifact-sft`) for lineage tracking. ### Training @@ -301,11 +299,11 @@ uv run nemotron super3 sft [options] [overrides...] ``` | Option | Description | -|--------|-------------| -| `--run ` | Attached—submits and waits, streaming logs ([NeMo-Run](../../nemo_runspec/nemo-run.md)) | -| `--batch ` | Detached—submits and exits immediately ([NeMo-Run](../../nemo_runspec/nemo-run.md)) | -| `--dry-run` | Preview execution plan | -| `key=value` | Override config values ([NeMo-Run](../../nemo_runspec/nemo-run.md)) | +| --- | --- | +| --run <profile> | Attached—submits and waits, streaming logs ([NeMo-Run](/../../nemo_runspec/nemo-run)) | +| --batch <profile> | Detached—submits and exits immediately ([NeMo-Run](/../../nemo_runspec/nemo-run)) | +| --dry-run | Preview execution plan | +| key=value | Override config values ([NeMo-Run](/../../nemo_runspec/nemo-run)) | #### Override Examples @@ -339,7 +337,7 @@ gpus_per_node = 8 mounts = ["/lustre:/lustre"] ``` -See [Execution through NeMo-Run](../../nemo_runspec/nemo-run.md) for complete configuration options. +See [Execution through NeMo-Run](/../../nemo_runspec/nemo-run) for complete configuration options. ### Artifact Lineage @@ -364,18 +362,18 @@ flowchart TB ## Infrastructure -This stage uses the following components from the [NVIDIA AI Stack](../nvidia-stack.md): +This stage uses the following components from the [NVIDIA AI Stack](/../nvidia-stack): | Component | Role | Documentation | -|-----------|------|---------------| -| [Megatron-Core](../nvidia-stack.md#megatron-core) | Distributed training primitives (TP, PP, DP, EP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | -| [Megatron-Bridge](../nvidia-stack.md#megatron-bridge) | Fine-tuning loop, checkpoint loading, loss masking | [Docs](https://docs.nvidia.com/nemo/megatron-bridge/latest/) | +| --- | --- | --- | +| [Megatron-Core](/../nvidia-stack#megatron-core) | Distributed training primitives (TP, PP, DP, EP) | [GitHub](https://github.com/NVIDIA/Megatron-LM) | +| [Megatron-Bridge](/../nvidia-stack#megatron-bridge) | Fine-tuning loop, checkpoint loading, loss masking | [Docs](https://docs.nvidia.com/nemo/megatron-bridge/latest/) | ### Key Features Used | Feature | Purpose | -|---------|---------| -| `finetune()` entry point | SFT training with pre-loaded checkpoint | +| --- | --- | +| finetune() entry point | SFT training with pre-loaded checkpoint | | Role-based loss masking | Only compute loss on assistant tokens | | Two-stage loss | Token-level then sample-level normalization | | Mixed precision (BF16) | Memory-efficient training | @@ -387,28 +385,28 @@ This stage uses the following components from the [NVIDIA AI Stack](../nvidia-st #### Full SFT (default, `peft: null`) | Parallelism | Default | Config Key | -|-------------|---------|------------| -| Tensor (TP) | 1 | `model.tensor_model_parallel_size` | -| Pipeline (PP) | 1 | `model.pipeline_model_parallel_size` | -| Expert (EP) | 8 | `model.expert_model_parallel_size` | -| Expert Tensor (ETP) | 1 | `model.expert_tensor_parallel_size` | -| Sequence (SP) | Yes | `model.sequence_parallel` | +| --- | --- | --- | +| Tensor (TP) | 1 | model.tensor_model_parallel_size | +| Pipeline (PP) | 1 | model.pipeline_model_parallel_size | +| Expert (EP) | 8 | model.expert_model_parallel_size | +| Expert Tensor (ETP) | 1 | model.expert_tensor_parallel_size | +| Sequence (SP) | Yes | model.sequence_parallel | | Data (DP) | Auto | Computed from world size | #### LoRA (`peft: lora`) | Parallelism | Default | Config Key | -|-------------|---------|------------| -| Tensor (TP) | 1 | `model.tensor_model_parallel_size` | -| Pipeline (PP) | 1 | `model.pipeline_model_parallel_size` | -| Expert (EP) | 1 | `model.expert_model_parallel_size` | -| Sequence (SP) | Yes | `model.sequence_parallel` | +| --- | --- | --- | +| Tensor (TP) | 1 | model.tensor_model_parallel_size | +| Pipeline (PP) | 1 | model.pipeline_model_parallel_size | +| Expert (EP) | 1 | model.expert_model_parallel_size | +| Sequence (SP) | Yes | model.sequence_parallel | **Minimum resources:** 4 nodes with 8 GPUs each (32 GPUs total). ### Container -``` +```default nvcr.io/nvidia/nemo:26.02.nemotron_3_super ``` @@ -416,15 +414,22 @@ nvcr.io/nvidia/nemo:26.02.nemotron_3_super ## Next Steps -After SFT completes, proceed to [Stage 2: RL](./rl/index.md) for reinforcement learning alignment. +After SFT completes, proceed to [Stage 2: RL](/rl/index) for reinforcement learning alignment. ## Reference - [Nemotron 3 Super Tech Report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Super-Technical-Report.pdf) — SFT methodology + - [Megatron-Bridge Nemotron 3 Super](https://github.com/NVIDIA-NeMo/Megatron-Bridge/blob/super-v3/docs/models/llm/nemotron3-super.md) — MB documentation and examples -- [NVIDIA AI Stack](../nvidia-stack.md) — Megatron-Core, Megatron-Bridge documentation -- [Artifact Lineage](../../nemo_runspec/artifacts.md) — W&B artifact system -- [Stage 0: Pretraining](./pretrain.md) — Pretrain the base model -- [Stage 2: RL](./rl/index.md) — Reinforcement learning alignment + +- [NVIDIA AI Stack](/../nvidia-stack) — Megatron-Core, Megatron-Bridge documentation + +- [Artifact Lineage](/../../nemo_runspec/artifacts) — W&B artifact system + +- [Stage 0: Pretraining](/pretrain) — Pretrain the base model + +- [Stage 2: RL](/rl/index) — Reinforcement learning alignment + - **Recipe Source**: `src/nemotron/recipes/super3/stage1_sft/` — Implementation details -- [Back to Overview](./README.md) + +- [Back to Overview](/README) diff --git a/docs/nemotron/wandb.md b/docs/fern/pages-vnightly/nemotron/wandb.mdx similarity index 65% rename from docs/nemotron/wandb.md rename to docs/fern/pages-vnightly/nemotron/wandb.mdx index 81613dedc..6810f3343 100644 --- a/docs/nemotron/wandb.md +++ b/docs/fern/pages-vnightly/nemotron/wandb.mdx @@ -1,8 +1,12 @@ -# Weights & Biases Integration +--- +title: "Weights & Biases Integration" +slug: "nemotron/wandb.html" +description: "Nemotron automatically passes W&B credentials and settings to containers running via nemo-run. nemotron.kit.wandb_kit handles W&B initialization; nemo_runspec.execution handles credential injection in" +--- -Nemotron automatically passes W&B credentials and settings to containers running via nemo-run. `nemotron.kit.wandb_kit` handles W&B initialization; `nemo_runspec.execution` handles credential injection into executors. You don't need to manage credentials manually across local, Docker, Slurm, or cloud executors. +Nemotron automatically passes W&B credentials and settings to containers running via nemo-run. `nemotron.kit.wandb_kit` handles W&B initialization; `nemo_runspec.execution` handles credential injection into executors. You don’t need to manage credentials manually across local, Docker, Slurm, or cloud executors. -> **Note**: W&B works alongside the [manifest-based tracker](./artifacts.md) for full lineage tracking and team collaboration. Configure both in your `env.toml` under `[artifacts]`. The manifest backend provides always-reliable local tracking; W&B adds the UI, lineage graphs, and team sharing. +> **Note**: W&B works alongside the [manifest-based tracker](/artifacts) for full lineage tracking and team collaboration. Configure both in your `env.toml` under `[artifacts]`. The manifest backend provides always-reliable local tracking; W&B adds the UI, lineage graphs, and team sharing. ## Configuration @@ -17,9 +21,9 @@ entity = "YOUR-TEAM" ``` | Field | Description | -|-------|-------------| -| `project` | W&B project name (required to enable tracking) | -| `entity` | W&B team/entity name | +| --- | --- | +| project | W&B project name (required to enable tracking) | +| entity | W&B team/entity name | ### Authentication @@ -36,17 +40,21 @@ Your API key is stored in `~/.netrc` and automatically detected by the kit. When you run jobs via nemo-run, `nemo_runspec.execution.build_env_vars()` automatically detects your W&B configuration and passes it to the container as environment variables: | Variable | Source | Description | -|----------|--------|-------------| -| `WANDB_API_KEY` | `wandb.api.api_key` | API key from local wandb login | -| `WANDB_PROJECT` | `env.toml [wandb]` | Project name | -| `WANDB_ENTITY` | `env.toml [wandb]` | Team/entity name | +| --- | --- | --- | +| WANDB_API_KEY | wandb.api.api_key | API key from local wandb login | +| WANDB_PROJECT | env.toml [wandb] | Project name | +| WANDB_ENTITY | env.toml [wandb] | Team/entity name | This works across all executor types: - **Local** – environment variables set directly + - **Docker** – passed via container env vars + - **Slurm** – included in job submission + - **SkyPilot** – set in cloud instance environment + - **Ray** – passed via `runtime_env.env_vars` ### How It Works @@ -118,10 +126,12 @@ if config.enabled: ## Artifact Lineage -W&B artifacts provide lineage tracking. See [Artifact Lineage](./artifacts.md) for details on: +W&B artifacts provide lineage tracking. See [Artifact Lineage](/artifacts) for details on: - End-to-end lineage from raw data to final model + - Semantic URIs for artifact references + - Viewing lineage in the W&B UI ## Advanced Features @@ -138,8 +148,11 @@ patch_wandb_checkpoint_logging() ``` This enables: + - Automatic artifact creation for each checkpoint + - Lineage links to training data artifacts + - Version tracking with step numbers ### NeMo-RL Checkpoint Logging @@ -155,7 +168,7 @@ patch_nemo_rl_checkpoint_logging() ### Seeded Random Fix -When using seeded random states (common in RL), W&B's default run ID generation can fail. The kit provides a patch: +When using seeded random states (common in RL), W&B’s default run ID generation can fail. The kit provides a patch: ```python from nemotron.kit.wandb_kit import patch_wandb_runid_for_seeded_random @@ -166,15 +179,15 @@ patch_wandb_runid_for_seeded_random() ## Troubleshooting -### "WANDB_API_KEY not found" +### “WANDB_API_KEY not found” -Ensure you're logged in locally: +Ensure you’re logged in locally: ```bash wandb login ``` -### "Project not found" +### “Project not found” Verify the project exists in your W&B workspace, or let W&B create it automatically on first run. @@ -197,23 +210,26 @@ For Ray data prep jobs, credentials are passed via `runtime_env.env_vars`. Ensur ### wandb.py Exports | Export | Description | -|--------|-------------| -| `WandbConfig` | Configuration dataclass | -| `init_wandb_if_configured()` | Conditional W&B initialization | -| `patch_wandb_checkpoint_logging()` | Enable Megatron-Bridge checkpoint artifacts | -| `patch_nemo_rl_checkpoint_logging()` | Enable NeMo-RL checkpoint artifacts | -| `patch_wandb_runid_for_seeded_random()` | Fix seeded random ID generation | +| --- | --- | +| WandbConfig | Configuration dataclass | +| init_wandb_if_configured() | Conditional W&B initialization | +| patch_wandb_checkpoint_logging() | Enable Megatron-Bridge checkpoint artifacts | +| patch_nemo_rl_checkpoint_logging() | Enable NeMo-RL checkpoint artifacts | +| patch_wandb_runid_for_seeded_random() | Fix seeded random ID generation | ### nemo_runspec Exports | Export | Module | Description | -|--------|--------|-------------| -| `get_wandb_config()` | `nemo_runspec.env` | Load W&B config from env.toml | -| `build_env_vars()` | `nemo_runspec.execution` | Build env vars with auto W&B detection | +| --- | --- | --- | +| get_wandb_config() | nemo_runspec.env | Load W&B config from env.toml | +| build_env_vars() | nemo_runspec.execution | Build env vars with auto W&B detection | ## Further Reading -- [OmegaConf Configuration](../nemo_runspec/omegaconf.md) – artifact interpolations and unified logging patches -- [Artifact Lineage](./artifacts.md) – lineage tracking and W&B UI -- [Nemotron Kit](./kit.md) – artifact system and lineage tracking -- [Execution through NeMo-Run](../nemo_runspec/nemo-run.md) – execution profiles and env.toml +- [OmegaConf Configuration](/../nemo_runspec/omegaconf) – artifact interpolations and unified logging patches + +- [Artifact Lineage](/artifacts) – lineage tracking and W&B UI + +- [Nemotron Kit](/kit) – artifact system and lineage tracking + +- [Execution through NeMo-Run](/../nemo_runspec/nemo-run) – execution profiles and env.toml diff --git a/docs/nemotron/xenna-observability.md b/docs/fern/pages-vnightly/nemotron/xenna-observability.mdx similarity index 60% rename from docs/nemotron/xenna-observability.md rename to docs/fern/pages-vnightly/nemotron/xenna-observability.mdx index fb46c0506..ef48246ae 100644 --- a/docs/nemotron/xenna-observability.md +++ b/docs/fern/pages-vnightly/nemotron/xenna-observability.mdx @@ -1,4 +1,8 @@ -# Xenna Pipeline Observability +--- +title: "Xenna Pipeline Observability" +slug: "nemotron/xenna-observability.html" +description: "Real-time observability for cosmos-xenna data preparation pipelines, with W&B metrics logging and pipeline statistics tracking." +--- Real-time observability for cosmos-xenna data preparation pipelines, with W&B metrics logging and pipeline statistics tracking. @@ -9,8 +13,11 @@ Real-time observability for cosmos-xenna data preparation pipelines, with W&B me When running data preparation pipelines (pretrain, SFT), you can log pipeline statistics to Weights & Biases in real time. This gives you visibility into: - **Pipeline progress** – inputs processed, outputs generated, completion percentage + - **Cluster utilization** – CPU/GPU/memory usage across the Ray cluster + - **Per-stage metrics** – actor counts, queue depths, processing speeds for each pipeline stage + - **Bottleneck detection** – which stages are blocking throughput ## Configuration @@ -34,9 +41,9 @@ observability: ### The Monkey-Patch Approach -cosmos-xenna's `PipelineMonitor` class builds a `PipelineStats` object every `logging_interval_s` via the internal `_make_stats()` method. Our hook intercepts this method: +cosmos-xenna’s `PipelineMonitor` class builds a `PipelineStats` object every `logging_interval_s` via the internal `_make_stats()` method. Our hook intercepts this method: -``` +```default ┌─────────────────────────────────────────────────────────────────┐ │ cosmos-xenna pipeline │ │ │ @@ -53,16 +60,23 @@ cosmos-xenna's `PipelineMonitor` class builds a `PipelineStats` object every `lo ``` **Benefits of this approach:** + - **No cosmos-xenna changes required** – works with current cosmos-xenna main -- **Same update frequency** – matches cosmos-xenna's internal logging cadence + +- **Same update frequency** – matches cosmos-xenna’s internal logging cadence + - **Structured data** – gets full `PipelineStats` object, not just text output + - **Zero pipeline impact** – original return value is preserved unchanged ### Thread Safety The hook uses reference counting for safe nested contexts: + - Multiple hooks can be active simultaneously + - Patch is installed when first hook enters, restored when last hook exits + - Thread-safe with a reentrant lock ## Metrics Logged @@ -70,41 +84,41 @@ The hook uses reference counting for safe nested contexts: ### Pipeline-Level Metrics | Metric | Description | -|--------|-------------| -| `{kind}/pipeline_duration_s` | Total elapsed time since pipeline start | -| `{kind}/main_loop_rate_hz` | Pipeline main loop frequency | -| `{kind}/progress` | Percentage of inputs processed (0-100) | -| `{kind}/num_input_remaining` | Inputs still waiting to be processed | -| `{kind}/num_outputs` | Total outputs generated | -| `{kind}/inputs_processed_per_s` | Input processing rate | -| `{kind}/outputs_per_s` | Output generation rate | +| --- | --- | +| {kind}/pipeline_duration_s | Total elapsed time since pipeline start | +| {kind}/main_loop_rate_hz | Pipeline main loop frequency | +| {kind}/progress | Percentage of inputs processed (0-100) | +| {kind}/num_input_remaining | Inputs still waiting to be processed | +| {kind}/num_outputs | Total outputs generated | +| {kind}/inputs_processed_per_s | Input processing rate | +| {kind}/outputs_per_s | Output generation rate | ### Cluster Resource Metrics | Metric | Description | -|--------|-------------| -| `{kind}/cluster/total_cpus` | Total CPUs in Ray cluster | -| `{kind}/cluster/avail_cpus` | Available (unused) CPUs | -| `{kind}/cluster/total_gpus` | Total GPUs in cluster | -| `{kind}/cluster/avail_gpus` | Available GPUs | -| `{kind}/cluster/total_mem_gb` | Total cluster memory (GB) | -| `{kind}/cluster/avail_mem_gb` | Available memory (GB) | +| --- | --- | +| {kind}/cluster/total_cpus | Total CPUs in Ray cluster | +| {kind}/cluster/avail_cpus | Available (unused) CPUs | +| {kind}/cluster/total_gpus | Total GPUs in cluster | +| {kind}/cluster/avail_gpus | Available GPUs | +| {kind}/cluster/total_mem_gb | Total cluster memory (GB) | +| {kind}/cluster/avail_mem_gb | Available memory (GB) | ### Per-Stage Metrics (Consolidated Charts) Stage metrics are logged as consolidated `line_series` charts (one chart per metric, one line per stage): | Metric | Description | -|--------|-------------| -| `stages/actors_target` | Target number of actors per stage | -| `stages/actors_ready` | Actors ready to process per stage | -| `stages/actors_running` | Actors currently processing per stage | -| `stages/tasks_completed` | Total completed tasks per stage | -| `stages/queue_in` | Input queue depth per stage | -| `stages/queue_out` | Output queue depth per stage | -| `stages/speed_tasks_per_s` | Processing speed per stage | -| `stages/resource_cpu_util_pct` | CPU utilization per stage | -| `stages/resource_mem_gb` | Memory usage (GB) per stage | +| --- | --- | +| stages/actors_target | Target number of actors per stage | +| stages/actors_ready | Actors ready to process per stage | +| stages/actors_running | Actors currently processing per stage | +| stages/tasks_completed | Total completed tasks per stage | +| stages/queue_in | Input queue depth per stage | +| stages/queue_out | Output queue depth per stage | +| stages/speed_tasks_per_s | Processing speed per stage | +| stages/resource_cpu_util_pct | CPU utilization per stage | +| stages/resource_mem_gb | Memory usage (GB) per stage | ## Usage in Recipes @@ -132,7 +146,7 @@ else: ## JSONL Output -For offline analysis or when W&B isn't available, enable JSONL output: +For offline analysis or when W&B isn’t available, enable JSONL output: ```yaml observability: @@ -162,27 +176,28 @@ Each line contains a JSON record: ### wandb_hook.py | Export | Description | -|--------|-------------| -| `WandbStatsHook` | Context manager that patches `PipelineMonitor._make_stats` | -| `make_wandb_stats_hook()` | Factory function for recipes | -| `log_plan_table_to_wandb()` | Log plan table showing datasets and processing config | +| --- | --- | +| WandbStatsHook | Context manager that patches PipelineMonitor._make_stats | +| make_wandb_stats_hook() | Factory function for recipes | +| log_plan_table_to_wandb() | Log plan table showing datasets and processing config | ### ObservabilityConfig | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `wandb_log_pipeline_stats` | `bool` | `True` | Enable W&B logging | -| `wandb_log_plan_table` | `bool` | `True` | Log plan table to W&B | -| `wandb_log_progress_table` | `bool` | `True` | Log per-dataset progress table | -| `wandb_log_stage_table` | `bool` | `True` | Log stage overview table | -| `pipeline_logging_interval_s` | `int` | `30` | Logging interval in seconds | -| `pipeline_stats_jsonl_path` | `str \| None` | `None` | Path for JSONL output | +| --- | --- | --- | --- | +| wandb_log_pipeline_stats | bool | True | Enable W&B logging | +| wandb_log_plan_table | bool | True | Log plan table to W&B | +| wandb_log_progress_table | bool | True | Log per-dataset progress table | +| wandb_log_stage_table | bool | True | Log stage overview table | +| pipeline_logging_interval_s | int | 30 | Logging interval in seconds | +| pipeline_stats_jsonl_path | str | None | None | Path for JSONL output | ## Troubleshooting ### Metrics not appearing in W&B 1. Verify W&B is initialized before the pipeline runs: + ```python import wandb assert wandb.run is not None, "W&B not initialized" @@ -190,25 +205,30 @@ Each line contains a JSON record: 2. Check that `wandb_log_pipeline_stats: true` in your config -3. Ensure the hook is active during pipeline execution (check for log message: "Installed PipelineMonitor._make_stats patch") +3. Ensure the hook is active during pipeline execution (check for log message: “Installed PipelineMonitor._make_stats patch”) ### Import errors for cosmos_xenna The hook lazy-imports `cosmos_xenna` only when entering the context. If you see import errors: 1. Ensure cosmos-xenna is installed: `uv pip install cosmos-xenna` + 2. For Ray workers, use `--extra xenna` in the run command (handled automatically by recipes) ### Missing stage metrics Some stages may not report all metrics if: -- The stage hasn't processed any tasks yet + +- The stage hasn’t processed any tasks yet + - The stage has `processing_speed_tasks_per_second = None` (no speed data available) These are expected behaviors and the hook gracefully handles missing data. ## Further Reading -- [Weights & Biases Integration](./wandb.md) – W&B configuration and authentication -- [Data Preparation](./data-prep.md) – data prep module overview -- [Artifact Lineage](./artifacts.md) – tracking data lineage in W&B +- [Weights & Biases Integration](/wandb) – W&B configuration and authentication + +- [Data Preparation](/data-prep) – data prep module overview + +- [Artifact Lineage](/artifacts) – tracking data lineage in W&B diff --git a/docs/runspec/v1/spec.md b/docs/fern/pages-vnightly/runspec/v1/spec.mdx similarity index 64% rename from docs/runspec/v1/spec.md rename to docs/fern/pages-vnightly/runspec/v1/spec.mdx index d72fd4bb5..d17a7a857 100644 --- a/docs/runspec/v1/spec.md +++ b/docs/fern/pages-vnightly/runspec/v1/spec.mdx @@ -1,4 +1,8 @@ -# Runspec: `[tool.runspec]` Specification +--- +title: "Runspec: `[tool.runspec]` Specification" +slug: "runspec/v1/spec.html" +description: "Runspec is a declarative metadata format for recipe scripts. Each recipe embeds a [tool.runspec] block inside standard PEP 723 inline script metadata, describing what the script is and what it needs t" +--- ## What is runspec? @@ -27,14 +31,18 @@ image, launch method, and resource requirements. Runspec collapses all of this into the script itself: - **Identity**: what is this recipe called? + - **Environment**: what container image and setup does it need? + - **Launch**: how should it be started (torchrun, ray, direct)? + - **Config**: where do YAML configs live relative to the script? + - **Resources**: what are sensible defaults for nodes and GPUs? Because this metadata is declarative and machine-readable, any tool can consume it — a CLI, a CI pipeline, a notebook, or an agent building a completely -different execution backend. See the [Design Philosophy](../../architecture/design-philosophy.md) +different execution backend. See the [Design Philosophy](/../../architecture/design-philosophy) for the broader principles behind this approach. ## Format @@ -75,35 +83,35 @@ Each line is prefixed with `# ` per PEP 723 convention. The block starts with ### `[tool.runspec]` — Top-level | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `schema` | `str` | `"1"` | Schema version. Always `"1"` for now. | -| `docs` | `str` | `""` | URL to this specification. Enables agents and tools to fetch the spec for context. Use a raw GitHub URL (e.g., `https://raw.githubusercontent.com/NVIDIA-NeMo/Nemotron/main/docs/runspec/v1/spec.md`). | -| `name` | `str` | `""` | Recipe identity (e.g., `"nano3/pretrain"`, `"nano3/data/prep/sft"`). Used in job names, display, and directory layout. | -| `image` | `str?` | `null` | Default container image for remote execution. | -| `setup` | `str` | `""` | Human-readable description of what the image provides or what setup is needed. | +| --- | --- | --- | --- | +| schema | str | "1" | Schema version. Always "1" for now. | +| docs | str | "" | URL to this specification. Enables agents and tools to fetch the spec for context. Use a raw GitHub URL (e.g., https://raw.githubusercontent.com/NVIDIA-NeMo/Nemotron/main/docs/runspec/v1/spec.md). | +| name | str | "" | Recipe identity (e.g., "nano3/pretrain", "nano3/data/prep/sft"). Used in job names, display, and directory layout. | +| image | str? | null | Default container image for remote execution. | +| setup | str | "" | Human-readable description of what the image provides or what setup is needed. | ### `[tool.runspec.run]` — Launch configuration | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `launch` | `str` | `"torchrun"` | How to start the script: `"torchrun"` (distributed), `"ray"` (Ray cluster), or `"direct"` (plain python). | -| `cmd` | `str` | `"python {script} --config {config}"` | Command template. Supports `{script}` and `{config}` placeholders. | -| `workdir` | `str?` | `null` | Working directory inside the container (e.g., `"/opt/nemo-rl"`). | +| --- | --- | --- | --- | +| launch | str | "torchrun" | How to start the script: "torchrun" (distributed), "ray" (Ray cluster), or "direct" (plain python). | +| cmd | str | "python {script} --config {config}" | Command template. Supports {script} and {config} placeholders. | +| workdir | str? | null | Working directory inside the container (e.g., "/opt/nemo-rl"). | ### `[tool.runspec.config]` — Config layout | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `dir` | `str` | `"./config"` | Config directory, relative to the script file. | -| `default` | `str` | `"default"` | Name of the default config (without extension). | -| `format` | `str` | `"omegaconf"` | Config format: `"omegaconf"`, `"yaml"`, or `"json"`. | +| --- | --- | --- | --- | +| dir | str | "./config" | Config directory, relative to the script file. | +| default | str | "default" | Name of the default config (without extension). | +| format | str | "omegaconf" | Config format: "omegaconf", "yaml", or "json". | ### `[tool.runspec.resources]` — Resource defaults | Field | Type | Default | Description | -|-------|------|---------|-------------| -| `nodes` | `int` | `1` | Default number of nodes. | -| `gpus_per_node` | `int` | `8` | Default GPUs per node. | +| --- | --- | --- | --- | +| nodes | int | 1 | Default number of nodes. | +| gpus_per_node | int | 8 | Default GPUs per node. | ### `[tool.runspec.env]` — Environment variables @@ -137,8 +145,11 @@ to run, the command decides **how** (local, slurm, ray, etc.). ## Adding a new recipe 1. Write the training/data-prep script + 2. Add a `[tool.runspec]` block at the top + 3. Create a CLI command that calls `parse_runspec()` on it + 4. Register the command in the typer group The runspec block is the single source of truth. No need to duplicate metadata @@ -149,7 +160,9 @@ in the CLI layer. The `nemo_runspec` Python package (`src/nemo_runspec/`) implements: - **Parsing**: `_parser.py` extracts the PEP 723 block and parses the TOML + - **Models**: `_models.py` defines the frozen `Runspec` dataclass + - **CLI toolkit**: config loading, env.toml profiles, RecipeTyper, packaging, etc. See `src/nemo_runspec/README.md` for package-level documentation. diff --git a/docs/fern/pages-vnightly/sdg/getting-started.mdx b/docs/fern/pages-vnightly/sdg/getting-started.mdx new file mode 100644 index 000000000..b6fd025eb --- /dev/null +++ b/docs/fern/pages-vnightly/sdg/getting-started.mdx @@ -0,0 +1,308 @@ +--- +title: "Generate Your First Synthetic Dataset" +slug: "sdg/getting-started.html" +description: "In this tutorial, you will:" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. */} + + + + + +**In this tutorial, you will**: + +1. Set up prerequisites: the repository and an NVIDIA API key. + +1. Read the default pipeline configuration. + +1. Run a preview to verify the pipeline and model. + +1. Generate a small dataset of five records. + +1. Locate and inspect the output JSON Lines (JSONL) file. + + This tutorial requires between 5 and 10 minutes to complete. + + + + +Run a 2-record preview of the default synthetic data generation (SDG) pipeline, then generate 5 records and show me the first output record. + + + + + +## Prerequisites + +- Run all commands from the repository root. + +- An `NVIDIA_API_KEY` for the default model, `nvidia/nemotron-3-nano-30b-a3b`. +Data generation runs against an NVIDIA-hosted endpoint, so you can complete this tutorial on any machine with network access. + +## How the Default Pipeline Works + +The default pipeline at `src/nemotron/steps/sdg/data_designer/config/default.yaml` combines two sources of variation for each record. +A *seed topic* is sampled from `sft_topic_seeds.jsonl`, for example a topic on safe deployment of AI assistants in enterprise support workflows. +A *persona category*, such as teacher or engineer, is sampled from a fixed category set. +Together they anchor a user prompt. +The pipeline generates a matching assistant response and projects the result into OpenAI chat-format messages. + +```yaml startLine={1} +# SFT synthetic chat — expand seed topics into user/assistant turns. +# Schema mirrors the NVIDIA-NeMo/DataDesigner Python SDK; column specs are +# translated by step.py into the corresponding typed config builder calls. +# +# Defaults are Lepton-friendly and local-friendly: output lands under +# $SDG_OUTPUT_DIR when set, otherwise $NEMO_RUN_DIR/sdg or ./output/sdg. +# The seed dataset is packaged with this step. Override either at the CLI: +# `output_path=... seed_dataset.path=...`. + +output_dir: ${oc.env:SDG_OUTPUT_DIR,${oc.env:NEMO_RUN_DIR,${oc.env:PWD}/output}/sdg} +output_path: $\{output_dir\}/sft.jsonl +num_records: 1000 + +seed_dataset: + path: ${oc.env:PWD}/src/nemotron/steps/sdg/data_designer/data/sft_topic_seeds.jsonl + strategy: shuffle # shuffle | ordered + fields: [topic] + +# Models map an `alias` (referenced by llm_text/llm_structured columns) to a +# concrete model + provider + inference parameters. Override per-environment: +# - Cloud: provider: nvidia, set NVIDIA_API_KEY in the env profile. +# - Local: provider: openai, point at a vLLM/OpenAI-compatible endpoint. +# +# Set skip_health_check: true to skip Designer's startup probe — useful when +# the model exists at runtime but isn't in the provider's catalog at config +# time, or for offline / vLLM endpoints. +models: + - alias: nvidia-text + model: nvidia/nemotron-3-nano-30b-a3b + provider: nvidia + skip_health_check: false + inference_parameters: + temperature: 0.8 + top_p: 1.0 + max_tokens: 1024 + +# Seed columns (e.g. `topic`) are added automatically when seed_dataset is set. +# Reference them in prompts as `{{ topic }}` without declaring them here. +columns: + - name: persona + type: category + values: [teacher, engineer, student, researcher, support_agent] + + - name: user_query + type: llm_text + model_alias: nvidia-text + prompt: | + Write a single user message for a {{ persona }} asking about: {{ topic }}. + Keep it natural, 1-3 sentences. + + - name: assistant_response + type: llm_text + model_alias: nvidia-text + prompt: | + Helpful assistant reply to: "{{ user_query }}". + Style: concise, factual, no markdown. + +output_projection: + type: openai_messages + user_field: user_query + assistant_field: assistant_response + metadata_fields: [persona, topic] +``` + +## Procedure + +1. Clone the repository, if you have not already done so: + + ```console + $ git clone https://github.com/NVIDIA-NeMo/Nemotron && cd Nemotron + ``` + +1. Install the dependencies for synthetic data generation: + + ```console + $ uv sync --extra data-sdg + ``` + +1. Set your NVIDIA API key: + + ```console + $ export NVIDIA_API_KEY="\" + ``` + +1. Run a 2-record preview to verify the model alias, prompts, and column mappings before generating at scale. + + ```console + $ uv run nemotron steps run sdg/data_designer -c default preview=true num_records=2 + ``` + + The pipeline registers the model alias, generates two rows, and prints a summary: + +**Example Output** + + ```text startLine={1} + + Compiled Configuration + + ╭──────────────────────────────────────── run ────────────────────────────────────────╮ + │ mode: local │ + │ profile: null │ + │ env: {} │ + │ cli: │ + │ argv: │ + │ - preview=true │ + │ - num_records=2 │ + │ dotlist: │ + │ - preview=true │ + │ - num_records=2 │ + │ passthrough: [] │ + │ config: default │ + │ recipe: │ + │ name: steps/sdg/data_designer │ + │ script: /local/var/tmp/nvidia/nemotron/src/nemotron/steps/sdg/data_designer/step.py │ + ╰─────────────────────────────────────────────────────────────────────────────────────╯ + + ╭─────────────────────────────────────── config ────────────────────────────────────────╮ + │ output_dir: ${oc.env:SDG_OUTPUT_DIR,${oc.env:NEMO_RUN_DIR,${oc.env:PWD}/output}/sdg} │ + │ output_path: $\{output_dir\}/sft.jsonl │ + │ num_records: 2 │ + │ seed_dataset: │ + │ path: ${oc.env:PWD}/src/nemotron/steps/sdg/data_designer/data/sft_topic_seeds.jsonl │ + │ strategy: shuffle │ + │ fields: │ + │ - topic │ + │ models: │ + │ - alias: nvidia-text │ + │ model: nvidia/nemotron-3-nano-30b-a3b │ + │ provider: nvidia │ + │ skip_health_check: true │ + │ inference_parameters: │ + │ temperature: 0.8 │ + │ top_p: 1.0 │ + │ max_tokens: '******' │ + │ columns: │ + │ - name: persona │ + │ type: category │ + │ values: │ + │ - teacher │ + │ - engineer │ + │ - student │ + │ - researcher │ + │ - support_agent │ + │ - name: user_query │ + │ type: llm_text │ + │ model_alias: nvidia-text │ + │ prompt: 'Write a single user message for a {{ persona }} asking about: {{ topic │ + │ }}. │ + │ │ + │ Keep it natural, 1-3 sentences. │ + │ │ + │ ' │ + │ - name: assistant_response │ + │ type: llm_text │ + │ model_alias: nvidia-text │ + │ prompt: 'Helpful assistant reply to: "{{ user_query }}". │ + │ │ + │ Style: concise, factual, no markdown. │ + │ │ + │ ' │ + │ output_projection: │ + │ type: openai_messages │ + │ user_field: user_query │ + │ assistant_field: assistant_response │ + │ metadata_fields: │ + │ - persona │ + │ - topic │ + │ preview: true │ + ╰───────────────────────────────────────────────────────────────────────────────────────╯ + + ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ + │ Job Submission │ + │ ├── configs │ + │ │ ├── job: /local/var/tmp/nvidia/nemotron/.nemotron/jobs/20260509-133530-steps-sdg-data_designer/job.yaml │ + │ │ └── train: /local/var/tmp/nvidia/nemotron/.nemotron/jobs/20260509-133530-steps-sdg-data_designer/train.yaml │ + │ └── mode: local │ + ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ + + Executing: /local/var/tmp/nvidia/nemotron/.venv/bin/python3 /local/var/tmp/nvidia/nemotron/src/nemotron/steps/sdg/data_designer/step.py --config /local/var/tmp/nvidia/nemotron/.nemotron/jobs/20260509-133530-steps-sdg-data_designer/train.yaml + Preview 2 records → /local/var/tmp/nvidia/nemotron/output/sdg/sft.jsonl + ``` + +1. Generate the five-record dataset: + + ```console + $ uv run nemotron steps run sdg/data_designer -c default num_records=5 + ``` + + The default output path is `./output/sdg/sft.jsonl`. +To change the path, set the `SDG_OUTPUT_DIR` environment variable or pass `output_path=...` on the command line. + +1. Inspect the output. +Each line of `sft.jsonl` is one chat record. +The `openai_messages` projection emits a `messages` array along with the seed `topic` and sampled `persona` as metadata for traceability. +The following sample shows one record from the `sft.jsonl` file. + + ```json startLine={1} + { + "messages": [ + { + "role": "user", + "content": "Could you explain how reducing latency affects the quality of the model’s responses? I’m trying to understand the trade‑offs involved." + }, + { + "role": "assistant", + "content": "Reducing latency shortens the time the model takes to generate a response, which often means it has less computational budget or fewer inference steps. With fewer steps or a tighter budget, the model may:\n\n- Produce shorter, less nuanced outputs \n- Miss subtle contextual cues or deeper reasoning \n- Rely more on surface‑level patterns rather than elaborate context \n- Be more prone to errors or hallucinations that would be filtered out with additional processing \n\nThe trade‑off is speed versus depth: faster responses can be less thorough, less coherent, or lower in quality, especially for tasks that benefit from extended reasoning or detailed elaboration. Balancing the two involves choosing an acceptable latency target while preserving enough inference capacity to maintain the desired response quality." + } + ], + "persona": "teacher", + "topic": "tradeoffs between model latency and response quality" + } + ``` + +## Summary + +In this tutorial, you completed the following tasks: + +- Ran a 2-record preview to verify the pipeline and model. + +- Generated a 5-record SFT chat dataset with `default.yaml`. + +- Located the OpenAI-format JSONL output. + +As you scale this workflow up, keep two principles in mind: + +- Run a preview first. +The `preview=true num_records=N` form runs the same pipeline against a small record count, so you can iterate on column specifications and prompts before scaling `num_records` up. + +- The output format matches the trainer. +The `openai_messages` projection emits records ready for `data_prep/sft_packing` or AutoModel SFT. + +## Next Steps + +- Adapt the pipeline to a specific domain: [Create a Domain Dataset for Airlines Customer Service](/how-to/create-domain-dataset). + +- Preview, generate, and customize output: [Tips for the Data Generation Pipeline](/how-to/run). + +- Generate preference pairs for direct preference optimization (DPO): [Generate Preference Data for DPO](/how-to/preference-data). + +- Dispatch to a cluster: [Dispatch SDG to a Cluster](/how-to/dispatch-to-cluster) describes env.toml profiles and container images. + +- Look up flags and config fields: [CLI Reference](/reference/cli-reference), [Config Schema](/reference/config-schema). diff --git a/docs/fern/pages-vnightly/sdg/how-to/create-domain-dataset.mdx b/docs/fern/pages-vnightly/sdg/how-to/create-domain-dataset.mdx new file mode 100644 index 000000000..ec13e564f --- /dev/null +++ b/docs/fern/pages-vnightly/sdg/how-to/create-domain-dataset.mdx @@ -0,0 +1,249 @@ +--- +title: "Create a Domain Dataset for Airlines Customer Service" +slug: "sdg/how-to/create-domain-dataset.html" +description: "In this how-to guide, you will:" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. */} + + + + + +**In this how-to guide, you will**: + +1. Create an airline-domain pipeline config. + +2. Create a seed file of airline inquiry scenarios. + +3. Swap the category columns for three airline-relevant dimensions. + +4. Rewrite the LLM prompts for the airline domain. + +5. Update the output projection and output path. + +6. Run a preview to verify, then generate 100 records. + + This guide requires between 20 and 30 minutes to complete. + + + + +Adapt the default SDG pipeline for Greenteme Airlines customer service with three category dimensions, run a 2-record preview, then generate 100 records and show me one output record. + + + + + +## Prerequisites + +- ✅ Completed [Generate Your First Synthetic Dataset](/../getting-started) — at least one successful preview and full run of `default.yaml` so you know the pipeline works end-to-end. + +- ✅ `NVIDIA_API_KEY` set in your environment. + +## How This Differs From the Default Pipeline + +The default pipeline mixes a single category dimension, `persona`, with seed topics. +This example adds category dimensions, `traveler_segment`, `inquiry_type`, and `channel`, on top of seed scenarios so that diversity comes from explicit, controllable values. + +## Procedure + +1. Create a `src/nemotron/steps/sdg/data_designer/config/greenteme.yaml` (download) file like the following example: + + ```yaml startLine={1} + output_dir: ${oc.env:SDG_OUTPUT_DIR,${oc.env:NEMO_RUN_DIR,${oc.env:PWD}/output}/sdg} + output_path: $\{output_dir\}/greenteme_sft.jsonl + num_records: 100 + + seed_dataset: + path: ${oc.env:PWD}/src/nemotron/steps/sdg/data_designer/data/greenteme_inquiry_seeds.jsonl + strategy: shuffle + fields: [scenario] + + models: + - alias: nvidia-text + model: nvidia/nemotron-3-nano-30b-a3b + provider: nvidia + skip_health_check: true + inference_parameters: + temperature: 0.8 + top_p: 1.0 + max_tokens: 1200 + + columns: + - name: traveler_segment + type: category + values: + - frequent_flyer + - business_traveler + - family_with_children + - first_time_international + - elite_loyalty_member + - leisure_couple + + - name: inquiry_type + type: category + values: + - rebooking + - baggage_issue + - refund_request + - loyalty_status + - fare_rules + - flight_status + + - name: channel + type: category + values: [chat, phone, app] + + - name: user_query + type: llm_text + model_alias: nvidia-text + prompt: | + You are role-playing a {{ traveler_segment }} contacting Greenteme Airlines + via {{ channel }} about a {{ inquiry_type }}. The scenario is: + "{{ scenario }}" + + Write the customer's first message. Keep it natural, 1-3 sentences. + Do not reference any real airline name, real flight number, or real + loyalty program. + + - name: assistant_response + type: llm_text + model_alias: nvidia-text + prompt: | + You are a customer-service agent at Greenteme Airlines, a fictional airline. + Reply to this customer message: + + "{{ user_query }}" + + Provide a concise, professional, compliant response, 2-4 sentences. Stay + realistic and grounded in standard airline policy. Do not invent real + airline names, real flight numbers, real PNR codes, or real loyalty + program details. No markdown. + + output_projection: + type: openai_messages + user_field: user_query + assistant_field: assistant_response + metadata_fields: [traveler_segment, inquiry_type, channel, scenario] + ``` + + The key differences from the default pipeline: + + - The variation for traveler segment, inquiry type, and channel are all provided by category-type columns. + + - The variation for the scenarios is provided by the seed JSONL file from the next step. + + - The system-style instruction lives at the top of each prompt rather than as a separate field. The LLM text columns take a single prompt that includes the role for the LLM to assume. + + - The `output_projection` field includes the new metadata fields. + +2. Create a seed file, `src/nemotron/steps/sdg/data_designer/data/greenteme_inquiry_seeds.jsonl`, (download) like the following example: + + ```json startLine={1} + {"scenario": "Connecting flight cancelled due to weather; customer needs to arrive at destination by tomorrow morning for a wedding."} + {"scenario": "Checked baggage missing on arrival; flight landed two hours ago and the bag did not appear at the carousel."} + {"scenario": "Customer wants a refund on a non-refundable ticket due to a documented medical emergency."} + {"scenario": "Customer is unsure why their loyalty status was downgraded this year and wants to understand the qualifying criteria."} + {"scenario": "Customer wants to change a fare class on an existing booking and needs to know the fare difference and any change fees."} + {"scenario": "Flight is showing a four-hour delay and the customer wants to know whether they will make their connection."} + {"scenario": "Customer was double-charged for a seat upgrade and wants the duplicate charge reversed."} + {"scenario": "Customer needs to add a service animal to an upcoming international flight and wants to know what documentation is required."} + {"scenario": "Bag damaged in transit; customer needs to file a claim and wants the timeline and required documentation."} + {"scenario": "Customer rebooked through self-service and is now seated apart from a travel companion; they want to be reseated together."} + {"scenario": "Customer wants to use a travel credit from a previous cancellation but cannot find the credit number in their account."} + {"scenario": "Customer's payment method was declined when trying to complete a booking and they want to know what to do."} + ``` + +1. Run a preview by specifying `preview=true num_records=2` to verify the pipeline before scaling: + + ```console + $ nemotron steps run sdg/data_designer -c greenteme preview=true num_records=2 + ``` + +**Example Output** + + ```json startLine={1} + { + "messages": [ + { + "role": "user", + "content": "Hi! I'm traveling internationally for the first time soon and need to add a service animal to my booking. Could you let me know what documentation I need to provide?" + }, + { + "role": "assistant", + "content": "Thank you for contacting Greenteme Airlines. Please provide a valid government-issued health certificate and a signed service animal relief form for your destination country. You can upload these documents through the Manage Booking section of our website at least 48 hours before departure." + } + ], + "traveler_segment": "first_time_international", + "inquiry_type": "rebooking", + "channel": "app", + "scenario": "Customer needs to add a service animal to an upcoming international flight and wants to know what documentation is required." + } + { + "messages": [ + { + "role": "user", + "content": "\"Hi, I just rebooked my flight online and realized my companion and I are now seated in different rows. Is there any way you can help us get seats together?\"" + }, + { + "role": "assistant", + "content": "Hello, thank you for reaching out to Greenteme Airlines. Please provide your booking reference, and we will check for available adjacent seats to move you and your companion together. Note that depending on your fare class, a seat selection fee may apply." + } + ], + "traveler_segment": "first_time_international", + "inquiry_type": "refund_request", + "channel": "phone", + "scenario": "Customer rebooked through self-service and is now seated apart from a travel companion; they want to be reseated together." + } + ``` + +1. Generate the dataset by raising `num_records` after the preview output looks correct: + + ```console + $ nemotron steps run sdg/data_designer -c greenteme num_records=100 + ``` + +## Going Further + +**Locale-aware persona profiles.** The current YAML schema supports category, seed, and LLM column types. To replace the static `traveler_segment` category with Census-grounded persona profiles using Data Designer’s [person sampler](https://nvidia-nemo.github.io/DataDesigner/latest/concepts/person_sampling/), you can include locale, age range, and synthetic-personas integration. + +**Multi-turn conversations.** The example shows a single user and assistant exchange. +For multi-turn dialogue, follow the `customer_support_tools.yaml` pattern: ask one `llm_text` column to return a JSON object with `messages` and optional `tools`, then use the `structured_messages` output projection to write training-ready JSONL. + +**Dispatch to a cluster.** Generation runs locally against the NVIDIA-hosted endpoint by default. To run on Lepton or Slurm, see [Dispatch SDG to a Cluster](/dispatch-to-cluster) — env.toml profiles, container images, and the gotchas that bite first-time cluster runs. + +## Schema and Downstream Use + +The `openai_messages` projection emits records with a `messages` array plus the metadata fields you list. These flow directly into: + +- `data_prep/sft_packing` for Megatron-Bridge-style training, or + +- AutoModel SFT, which consumes the chat format directly. + +For a full reference of available projection shapes, see [Output Projections](/../reference/output-projections). + +## Next Steps + +- **Generate preference pairs for DPO**: [Generate Preference Data for DPO](/preference-data) — the `rl_pref.yaml` pattern. + +- **Generate tool-calling SFT data**: [Generate Tool-Calling Data for SFT](/tool-call-data) — multi-turn `messages` and `tools` with `structured_messages`. + +- **CLI flags and overrides**: [CLI Reference](/../reference/cli-reference). + +- **Config schema**: [Config Schema](/../reference/config-schema) — full reference for column types, samplers, and projections. + +- **Pipeline overview**: [About Synthetic Data Generation](/../index). diff --git a/docs/sdg/how-to/dispatch-to-cluster.md b/docs/fern/pages-vnightly/sdg/how-to/dispatch-to-cluster.mdx similarity index 86% rename from docs/sdg/how-to/dispatch-to-cluster.md rename to docs/fern/pages-vnightly/sdg/how-to/dispatch-to-cluster.mdx index 2c27758f0..37d55b0f9 100644 --- a/docs/sdg/how-to/dispatch-to-cluster.md +++ b/docs/fern/pages-vnightly/sdg/how-to/dispatch-to-cluster.mdx @@ -1,5 +1,10 @@ - +limitations under the License. */} -(sdg-dispatch-to-cluster)= -# Dispatch SDG to a Cluster + This guide covers configuring an env.toml profile and running `sdg/data_designer` on Lepton or Slurm. Generation is CPU-only (no GPUs needed) and calls a remote LLM endpoint, so the step fits naturally on a CPU node with outbound network access. @@ -92,9 +95,10 @@ mounts = [ ] ``` -:::{note} + In the `mounts` table, `path` is the NFS **source** path on the NFS server — not the in-container destination. `mount_path` is the in-container path. -::: + + ### `NVIDIA_API_KEY` is not forwarded automatically @@ -141,9 +145,10 @@ startup_commands = [ NVIDIA_API_KEY = "${oc.env:NVIDIA_API_KEY}" ``` -:::{tip} -On clusters where the default partition requires GPUs (for example, NVIDIA's `dlw` cluster), set `run_partition` and `batch_partition` to a CPU-capable partition. `gpus_per_node = 0` alone is not sufficient — the partition itself must accept zero-GPU jobs. -::: + +On clusters where the default partition requires GPUs (for example, NVIDIA’s `dlw` cluster), set `run_partition` and `batch_partition` to a CPU-capable partition. `gpus_per_node = 0` alone is not sufficient — the partition itself must accept zero-GPU jobs. + + ## Verify Before Scaling @@ -158,5 +163,7 @@ Confirm the job reaches `Running`, the model alias check succeeds, and two recor ## Next Steps - **env.toml reference**: `docs/nemo_runspec/nemo-run.md` — full profile field reference. -- **CLI flags**: {doc}`../reference/cli-reference`. -- **Troubleshooting**: {doc}`../reference/troubleshooting` — full failure-mode reference. + +- **CLI flags**: [CLI Reference](/../reference/cli-reference). + +- **Troubleshooting**: [Troubleshooting](/../reference/troubleshooting) — full failure-mode reference. diff --git a/docs/fern/pages-vnightly/sdg/how-to/index.mdx b/docs/fern/pages-vnightly/sdg/how-to/index.mdx new file mode 100644 index 000000000..0be1b61cd --- /dev/null +++ b/docs/fern/pages-vnightly/sdg/how-to/index.mdx @@ -0,0 +1,75 @@ +--- +title: "Synthetic Data How-To Guides" +slug: "sdg/how-to/index.html" +description: "This section provides task-focused guides for common SDG workflows. For your first run, start with Generate Your First Synthetic Dataset." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. */} + + + +This section provides task-focused guides for common SDG workflows. +For your first run, start with [Generate Your First Synthetic Dataset](/../getting-started). + +If you are new to model training or want a calmer on-ramp before tasks, read [Use the SDG Skill With Confidence](/../using-skills) for how to run a productive session with a coding agent. + + + +Preview, generate, and customize output path and projection. + +--- + +10 min intermediate + + + + +Adapt the pipeline to a custom domain with a seed file and multiple category dimensions. + +--- + +20 min intermediate + + + + +Generate multi-turn conversations with OpenAI-style tool calls for tool-use SFT. + +--- + +15 min intermediate + + + + +Generate DPO preference pairs (prompt / chosen / rejected) from `rl_pref.yaml`. + +--- + +15 min intermediate + + + + +Configure an env.toml profile and run SDG on Lepton or Slurm. + +--- + +30 min intermediate + + + + diff --git a/docs/fern/pages-vnightly/sdg/how-to/preference-data.mdx b/docs/fern/pages-vnightly/sdg/how-to/preference-data.mdx new file mode 100644 index 000000000..2d428da19 --- /dev/null +++ b/docs/fern/pages-vnightly/sdg/how-to/preference-data.mdx @@ -0,0 +1,166 @@ +--- +title: "Generate Preference Data for DPO" +slug: "sdg/how-to/preference-data.html" +description: "This example shows how to use the rl_pref.yaml configuration file. The example generates prompt, chosen, and rejected triples for direct preference optimization (DPO) training. Output flows directly i" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. */} + + + +This example shows how to use the `rl_pref.yaml` configuration file. +The example generates *prompt*, *chosen*, and *rejected* triples for direct preference optimization (DPO) training. +Output flows directly into `data_prep/rl_prep` and then `rl/nemo_rl/dpo`. + +## How It Works + +The `rl_pref.yaml` file registers two model aliases at different temperatures: +a high-temperature creative model and a low-temperature precise model. +The goal is to produce two responses per prompt that are distinct: + +```yaml startLine={1} +# DPO preference data — two responses per prompt + LLM judge for chosen/rejected. + +output_dir: ${oc.env:SDG_OUTPUT_DIR,${oc.env:NEMO_RUN_DIR,${oc.env:PWD}/output}/sdg} +output_path: $\{output_dir\}/rl_pref.jsonl +num_records: 100 + +seed_dataset: + path: ${oc.env:PWD}/src/nemotron/steps/sdg/data_designer/data/rl_pref_prompt_seeds.jsonl + strategy: shuffle + fields: [prompt] + +# Two model aliases: a high-temperature 'creative' model and a low-temperature +# 'precise' model, so the resulting preference pairs are meaningfully distinct. +models: + - alias: nvidia-text + model: nvidia/nemotron-3-nano-30b-a3b + provider: nvidia + skip_health_check: false + inference_parameters: + temperature: 0.9 + top_p: 1.0 + max_tokens: 1024 + + - alias: nvidia-text-precise + model: nvidia/nemotron-3-nano-30b-a3b + provider: nvidia + skip_health_check: false + inference_parameters: + temperature: 0.3 + top_p: 1.0 + max_tokens: 1024 + +# `prompt` is supplied automatically by the seed dataset (must match the field +# name in the seed JSONL). No need to declare it here. +columns: + - name: response_a + type: llm_text + model_alias: nvidia-text + prompt: "Answer the user's question: {{ prompt }}" + + - name: response_b + type: llm_text + model_alias: nvidia-text-precise + prompt: "Answer the user's question: {{ prompt }}" + + - name: judge + type: llm_judge + model_alias: nvidia-text + prompt: | + Compare two responses for: {{ prompt }} + A: {{ response_a }} + B: {{ response_b }} + Which is more helpful and correct? + output_format: + type: object + properties: + winner: + type: string + enum: [A, B] + required: [winner] + +output_projection: + type: dpo_preference + prompt_field: prompt + response_a_field: response_a + response_b_field: response_b + judge_field: judge + winner_field: winner +``` + +For each seed prompt the pipeline: + +1. Generates `response_a` (high temperature) and `response_b` (low temperature) independently. + +2. Asks a third LLM call (`judge` column, `llm_judge` type) to compare them and return `\{"winner": "A"\}` or `\{"winner": "B"\}`. + +3. The `dpo_preference` projection maps winner → chosen / rejected and writes `\{"prompt": "...", "chosen": "...", "rejected": "..."\}`. + +## Prerequisites + +- `NVIDIA_API_KEY` set in your environment. + +- A seed file with one `prompt` field per line. The bundled `rl_pref_prompt_seeds.jsonl` contains general reasoning prompts. Replace it with domain-specific prompts for targeted preference data. + +## Procedure + +1. Preview two records to verify the judge returns valid `winner` values: + + ```console + $ nemotron steps run sdg/data_designer -c rl_pref preview=true num_records=2 + ``` + +2. Generate the dataset. The checked-in `rl_pref.yaml` default is 100 records: + + ```console + $ nemotron steps run sdg/data_designer -c rl_pref num_records=500 + ``` + + Output is written to `./output/sdg/rl_pref.jsonl`. + + Inspect the output. Each line is a preference triple: + + ```json + {"prompt": "Explain why retrieval-augmented generation can reduce hallucinations.", "chosen": "RAG grounds the model in retrieved documents, so claims are tied to specific passages rather than purely to weights.", "rejected": "RAG is better because it uses more data and is generally smarter than standard models."} + ``` + +## Adapt the Seed File + +Swap `seed_dataset.path` to point at your own prompt seed file. Each line must be valid JSON with a `prompt` field: + +```json +{"prompt": "Describe the tradeoffs between batch and streaming inference for real-time applications."} +``` + +Keep seed prompts representative of the target capability and diverse across difficulty levels. +The judge performs better when the two responses have a clear quality difference–consider widening the temperature gap between the two model aliases if the judge returns many ties or unexpected results. + +## Downstream Pipeline + +```text +rl_pref.jsonl → data_prep/rl_prep → rl/nemo_rl/dpo +``` + +`data_prep/rl_prep` tokenizes and prepares preference pairs. `rl/nemo_rl/dpo` consumes the prepared dataset. Verify the `prompt`, `chosen`, and `rejected` fields are present in every record before handing off. + +## Next Steps + +- **Output projection reference**: [Output Projections](/../reference/output-projections) — `dpo_preference` schema. + +- **Config schema**: [Config Schema](/../reference/config-schema) — `llm_judge` column type and `dpo_preference` projection fields. + +- **Dispatch to a cluster**: [Dispatch SDG to a Cluster](/dispatch-to-cluster). diff --git a/docs/sdg/how-to/run.md b/docs/fern/pages-vnightly/sdg/how-to/run.mdx similarity index 56% rename from docs/sdg/how-to/run.md rename to docs/fern/pages-vnightly/sdg/how-to/run.mdx index 24c35844d..7adfaa4ce 100644 --- a/docs/sdg/how-to/run.md +++ b/docs/fern/pages-vnightly/sdg/how-to/run.mdx @@ -1,5 +1,10 @@ - +limitations under the License. */} -(sdg-run)= -# Tips for the Data Generation Pipeline + ## Preview Before Generating @@ -28,9 +31,12 @@ $ nemotron steps run sdg/data_designer -c default preview=true num_records=2 Use preview to verify: -- Column references in prompts (`{{ column_name }}`) resolve to the expected values. -- Seed fields, such as `{{ scenario }}`, `{{ prompt }}`, and so on, are populated from the seed file. -- The model returns text that matches the prompt's intent. +- Column references in prompts (`\{\{ column_name \}\}`) resolve to the expected values. + +- Seed fields, such as `\{\{ scenario \}\}`, `\{\{ prompt \}\}`, and so on, are populated from the seed file. + +- The model returns text that matches the prompt’s intent. + - The `output_projection` produces the schema downstream steps expect. ## Specify a Configuration File @@ -38,11 +44,11 @@ Use preview to verify: The repository includes the following sample config files in the `src/nemotron/steps/sdg/data_designer/config` directory: | Config | Output | Use for | -|---|---|---| -| `default.yaml` | SFT chat (`openai_messages`) | General chat SFT | -| `customer_support_tools.yaml` | Tool-call SFT (`structured_messages`) | Tool-use SFT | -| `rl_pref.yaml` | Preference pairs (`dpo_preference`) | DPO / RLHF | -| `tiny.yaml` | SFT chat, 10 records, short tokens | Fast iteration | +| --- | --- | --- | +| default.yaml | SFT chat (openai_messages) | General chat SFT | +| customer_support_tools.yaml | Tool-call SFT (structured_messages) | Tool-use SFT | +| rl_pref.yaml | Preference pairs (dpo_preference) | DPO / RLHF | +| tiny.yaml | SFT chat, 10 records, short tokens | Fast iteration | Specify the file in the `-c` argument: @@ -58,4 +64,4 @@ To dispatch to a Lepton or Slurm profile configured in `env.toml`, use `--run` ( $ nemotron steps run sdg/data_designer -c default --run my-lepton-profile num_records=1000 ``` -For cluster setup, see {doc}`dispatch-to-cluster`. +For cluster setup, see [Dispatch SDG to a Cluster](/dispatch-to-cluster). diff --git a/docs/fern/pages-vnightly/sdg/how-to/tool-call-data.mdx b/docs/fern/pages-vnightly/sdg/how-to/tool-call-data.mdx new file mode 100644 index 000000000..796bac4a1 --- /dev/null +++ b/docs/fern/pages-vnightly/sdg/how-to/tool-call-data.mdx @@ -0,0 +1,310 @@ +--- +title: "Generate Tool-Calling Data for SFT" +slug: "sdg/how-to/tool-call-data.html" +description: "Use this guide when you need multi-turn chat JSONL where the assistant issues OpenAI-style tool_calls and a tool role returns structured results, suitable for supervised fine-tuning (SFT) with a tools" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. */} + + + +Use this guide when you need multi-turn chat JSONL where the assistant issues OpenAI-style `tool_calls` and a `tool` role returns structured results, suitable for supervised fine-tuning (SFT) with a `tools` definition array. + +You will use the sample config `customer_support_tools.yaml`, which produces ecommerce-style support threads. Each output row includes a `messages` array (with tool turns) and a `tools` array, ready for packing and training. + +## Outcomes + +- Understand how the shipped config asks one `llm_text` column to emit a full JSON multi-turn trace in a single model call. + +- Preview, generate, and validate records before training. + +- Know how to retarget seeds, prompts, and schema for your own domain. + +## How It Works + +Compared with single-turn configs such as `default.yaml`, this setup drives the whole conversation from one `llm_text` column. +The prompt tells the model to return a JSON object with `tools` and `messages` keys. +The `structured_messages` output projection parses that JSON object, extracts `messages` and `tools`, adds metadata, and serializes nested tool payload objects into OpenAI-compatible string fields. + +```yaml startLine={1} +# Multi-turn customer-support SFT data with OpenAI-style tool calls. +# +# Output records are training-ready JSONL: +# {"messages": [...], "tools": [...], ...metadata} +# +# Each generated conversation includes one assistant tool call, one matching +# tool response, and a final assistant answer grounded in that tool result. + +output_dir: ${oc.env:SDG_OUTPUT_DIR,${oc.env:NEMO_RUN_DIR,${oc.env:PWD}/output}/sdg} +output_path: $\{output_dir\}/customer_support_tool_sft.jsonl +num_records: 100 + +seed_dataset: + path: ${oc.env:PWD}/src/nemotron/steps/sdg/data_designer/data/customer_support_tool_seeds.jsonl + strategy: shuffle + fields: [customer_name, issue, order_id, product, policy_hint] + +# Optional custom endpoint example: +# +# To route this pipeline through an OpenAI-compatible endpoint instead of the +# built-in NVIDIA provider, uncomment and edit both blocks below. +# Keep providers[].api_key as the environment variable name. Data Designer +# resolves it at request time; using `${oc.env:OPENAI_API_KEY}` here would put +# the secret into the resolved config. +# +# providers: +# - name: my-provider +# endpoint: ${oc.env:OPENAI_BASE_URL} +# provider_type: openai +# api_key: OPENAI_API_KEY +# +# models: +# - alias: nvidia-text +# model: google/gemma-4-31B-it +# provider: my-provider +# skip_health_check: true +# inference_parameters: +# temperature: 0.75 +# top_p: 0.95 +# max_tokens: 1800 + +models: + - alias: nvidia-text + model: openai/gpt-oss-20b + provider: nvidia + skip_health_check: false + inference_parameters: + temperature: 0.75 + top_p: 0.95 + max_tokens: 1800 + +columns: + - name: urgency + type: category + values: [calm, frustrated, rushed, confused] + + - name: channel + type: category + values: [web_chat, mobile_app, email_followup] + + - name: conversation + # Keep this as text instead of llm_structured: Designer writes intermediate + # batches to parquet before this step can project records, and complex + # nested objects can produce mixed object schemas across rows. + type: llm_text + model_alias: nvidia-text + prompt: | + Generate one realistic multi-turn ecommerce customer-support chat for SFT. + + Seed facts: + - customer_name: {{ customer_name }} + - customer_issue: {{ issue }} + - order_id: {{ order_id }} + - product: {{ product }} + - policy_hint: {{ policy_hint }} + - customer_tone: {{ urgency }} + - channel: {{ channel }} + + Requirements: + - Return ONLY a JSON object. The first character MUST be `{`, the last MUST be `}`. + - No prose, no preamble, no apology, no commentary, no markdown fences (no ```). + - Top-level keys MUST be exactly "tools" and "messages". + - Produce 6 to 10 messages in OpenAI chat format. + - Include a brief system message that defines the support-agent behavior. + - The user should speak naturally and provide imperfect information at first. + - The assistant should ask at least one clarifying question before using a tool. + - Include exactly one assistant message with tool_calls. + - Include exactly one tool message that has the matching tool_call_id. + - The assistant's final answer must use the tool result and the policy_hint. + - Do not include markdown in message content. + - In the generated JSON object, function arguments must be JSON objects, not escaped JSON strings. + - In the generated JSON object, tool message content must be a JSON object, not an escaped JSON string. + + Available tool functions: + - lookup_order(order_id: string) + - check_refund_eligibility(order_id: string, reason: string) + - update_shipping_address(order_id: string, new_address: string) + - verify_warranty(order_id: string, product: string) + - get_subscription_status(order_id: string) + + Example assistant tool-call message shape: + { + "role": "assistant", + "content": "", + "tool_calls": [ + { + "id": "call_lookup_001", + "type": "function", + "function": { + "name": "lookup_order", + "arguments": {"order_id": "ORD-10492"} + } + } + ] + } + + Example tool message shape: + { + "role": "tool", + "tool_call_id": "call_lookup_001", + "name": "lookup_order", + "content": {"status": "delayed", "eta": "tomorrow"} + } + Schema: + { + "tools": [ + { + "type": "function", + "function": { + "name": "lookup_order", + "description": "Look up an order by ID.", + "parameters": { + "type": "object", + "properties": {"order_id": {"type": "string"}}, + "required": ["order_id"] + } + } + } + ], + "messages": [ + {"role": "system", "content": "You are a helpful support agent."}, + {"role": "user", "content": "User message"}, + { + "role": "assistant", + "content": "", + "tool_calls": [ + { + "id": "call_lookup_001", + "type": "function", + "function": { + "name": "lookup_order", + "arguments": {"order_id": "ORD-10492"} + } + } + ] + }, + { + "role": "tool", + "tool_call_id": "call_lookup_001", + "name": "lookup_order", + "content": {"status": "delayed", "eta": "tomorrow"} + }, + {"role": "assistant", "content": "Final grounded answer"} + ] + } + +output_projection: + type: structured_messages + source_field: conversation + messages_field: messages + tools_field: tools + metadata_fields: [customer_name, issue, order_id, product, urgency, channel] +``` + +Each seed row supplies five anchor fields the prompt interpolates: `customer_name`, `issue`, `order_id`, `product`, and `policy_hint`. Two extra category columns (`urgency`, `channel`) add variety without multiplying seed rows for every combination. + +## Prerequisites + +- Nemotron CLI available and working; if this is your first SDG run, complete [Generate Your First Synthetic Dataset](/../getting-started). + +- `NVIDIA_API_KEY` set in the environment. + +- The bundled seed file `data/customer_support_tool_seeds.jsonl` (shipped with the step). Add rows, or point the config at your own JSONL. + +## Procedure + +1. Preview two records so structured output matches the schema: + + ```console + $ nemotron steps run sdg/data_designer -c customer_support_tools preview=true num_records=2 + ``` + + In the preview, confirm: + + - Exactly one assistant message with `tool_calls`. + + - Exactly one `tool` message whose `tool_call_id` matches the call. + + - `function.arguments` and tool-message `content` are JSON strings after projection. + + - The assistant’s closing turn references the tool result (not a generic reply). + + - No markdown in message `content` if your trainer expects plain text. + +2. Generate the dataset: + + ```console + $ nemotron steps run sdg/data_designer -c customer_support_tools num_records=200 + ``` + + Output path: `./output/sdg/customer_support_tool_sft.jsonl`. +Spot-check a few lines. Each record exposes top-level `messages` and `tools` plus metadata, like the following example: + + ```text + { + "messages": [ + {"role": "system", "content": "You are a helpful ecommerce support agent..."}, + {"role": "user", "content": "Hi, I haven't received my headphones yet..."}, + {"role": "assistant", "content": "I'd be happy to help. Could you share your order number?"}, + {"role": "user", "content": "It's ORD-10492."}, + {"role": "assistant", "content": "", "tool_calls": [{"id": "call_001", "type": "function", "function": {"name": "lookup_order", "arguments": "{\"order_id\":\"ORD-10492\"}"}}]}, + {"role": "tool", "tool_call_id": "call_001", "name": "lookup_order", "content": "{\"status\":\"delayed\",\"eta\":\"tomorrow\"}"}, + {"role": "assistant", "content": "Your order is delayed and should arrive tomorrow. Per our policy, I can arrange an expedited replacement if you prefer."} + ], + "tools": [{"type": "function", "function": {"name": "lookup_order", "description": "...", "parameters": {...}}}], + "customer_name": "Priya", "issue": "late delivery", "urgency": "frustrated", "channel": "web_chat" + } + ``` + +## Adapt to Your Domain + +1. Replace or extend the seed file so rows cover your entities. You may rename the five anchor fields as long as the prompt and YAML refer to the same names. + +2. Update `seed_dataset.fields` in the YAML to match those names. + +3. Rewrite the `prompt` for your scenario and tool surface. + +4. Adjust the JSON schema described in the prompt if the message layout changes, for example multiple tool calls per conversation. + +Keep `output_projection` as `structured_messages` so the step extracts `messages` and `tools` from the structured column and merges category metadata onto each record. + +## Validation Checklist + +Before training, sample at least 50 records and verify: + +- Every `tool_calls` block has a matching `tool` message with the same `tool_call_id`. + +- `function.arguments` and tool-message `content` values are JSON strings in the projected JSONL. + +- The assistant’s final reply uses the tool result (not a canned answer that ignores it). + +- No unexpected markdown in `content` if the trainer assumes plain text. + +- `tools` is present and non-empty on every record. + +## Downstream Use + +```text +customer_support_tool_sft.jsonl → data_prep/sft_packing → SFT training +``` + +The `structured_messages` projection writes `messages` and `tools` at the top level, matching formats common to AutoModel-style SFT and Megatron-Bridge-style workflows. Run `data_prep/sft_packing` in dry-run mode before a large training job to confirm the packer accepts your file. + +## Next Steps + +- Output projection reference: [Output Projections](/../reference/output-projections) to learn the `structured_messages` schema. + +- Config schema: [Config Schema](/../reference/config-schema) for column types and output projections. diff --git a/docs/sdg/index.md b/docs/fern/pages-vnightly/sdg/index.mdx similarity index 54% rename from docs/sdg/index.md rename to docs/fern/pages-vnightly/sdg/index.mdx index 29d57c1aa..5717c6528 100644 --- a/docs/sdg/index.md +++ b/docs/fern/pages-vnightly/sdg/index.mdx @@ -1,5 +1,10 @@ - +limitations under the License. */} -(sdg-index)= -# About Synthetic Data Generation + Generate synthetic training data with [NeMo Data Designer](https://nvidia-nemo.github.io/DataDesigner/) using a declarative YAML pipeline. Seed a generation run with your domain-specific topics, scenarios, or personas; define the column structure and prompts in YAML; and produce training-ready JSONL without writing Python. Three output shapes ship out of the box: SFT chat data, tool-calling SFT data, and DPO preference pairs. -:::{tip} -New to SDG or new to model training? Read {doc}`using-skills` for a short guide to productive agent sessions, then start the {doc}`getting-started` tutorial to run the bundled pipeline and produce your first dataset in 5 to 10 minutes. -::: + +New to SDG or new to model training? Read [Use the SDG Skill With Confidence](/using-skills) for a short guide to productive agent sessions, then start the [Generate Your First Synthetic Dataset](/getting-started) tutorial to run the bundled pipeline and produce your first dataset in 5 to 10 minutes. + + ## When to Use Use SDG when you need training data that does not already exist in sufficient quantity or quality for your target domain or task. - **SFT chat data** — Generate user/assistant conversation pairs grounded in domain-specific topics, scenarios, or personas. Use `default.yaml` as a starting point and adapt it to your domain. + - **Tool-calling SFT data** — Generate multi-turn conversations that include assistant tool calls and tool responses in OpenAI format. Use `customer_support_tools.yaml` as a starting point. + - **DPO preference data** — Generate prompt / chosen / rejected triples for preference learning. Use `rl_pref.yaml`. + - **Custom domains** — Swap the seed file, category columns, and prompts to target any domain. The pipeline is fully declarative; customisation does not require editing Python. + - **Cluster-scale generation** — Dispatch generation to Lepton or Slurm via env.toml profiles when local throughput is insufficient. ## Pipeline at a Glance @@ -59,80 +67,79 @@ Each run is reproducible: the seed file, column specs, model alias, inference pa ## Documentation -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`rocket;1.5em;sd-mr-1` Getting Started -:link: getting-started -:link-type: doc + + Run the bundled pipeline end-to-end: preview two records, generate five, inspect the output JSONL. -+++ -{bdg-success}`5–10 min` {bdg-secondary}`tutorial` -::: -:::{grid-item-card} {octicon}`heart;1.5em;sd-mr-1` Use the SDG Skill With Confidence -:link: using-skills -:link-type: doc +--- + +5–10 min tutorial + + + + Prepare for a focused chat with a coding agent: opening brief, seed ideas, and how `SKILL.md` supports the session without memorization. -+++ -{bdg-success}`10 min read` {bdg-secondary}`newcomer` -::: -:::{grid-item-card} {octicon}`checklist;1.5em;sd-mr-1` How-To Guides -:link: how-to/index -:link-type: doc +--- + +10 min read newcomer + + + + Task-focused guides: adapt the pipeline to a domain, generate preference pairs, dispatch to a cluster. -+++ -{bdg-success}`5 guides` {bdg-secondary}`task-focused` -::: -:::{grid-item-card} {octicon}`list-unordered;1.5em;sd-mr-1` Reference -:link: reference/index -:link-type: doc +--- + +5 guides task-focused + + + + YAML config schema, CLI flags, output projection shapes, and troubleshooting. -+++ -{bdg-success}`4 references` {bdg-secondary}`lookup` -::: -:::: +--- -## All Documentation +4 references lookup -````{tab-set} + -```{tab-item} Getting Started + -| Guide | What You'll Do | Time | -|---|---|---| -| {doc}`getting-started` | Preview and generate your first synthetic SFT dataset | 5–10 min | -| {doc}`using-skills` | Run a productive agent session: brief, seeds, plain terms, and light use of `SKILL.md` | 10 min read | +## All Documentation -``` + + -```{tab-item} How-To Guides +| Guide | What You’ll Do | Time | +| --- | --- | --- | +| [Generate Your First Synthetic Dataset](/getting-started) | Preview and generate your first synthetic SFT dataset | 5–10 min | +| [Use the SDG Skill With Confidence](/using-skills) | Run a productive agent session: brief, seeds, plain terms, and light use of SKILL.md | 10 min read | -| Guide | What You'll Do | -|---|---| -| {doc}`how-to/run` | Preview, generate, and customize output path and projection | -| {doc}`how-to/create-domain-dataset` | Adapt the pipeline to a custom domain with a seed file and multiple category dimensions | -| {doc}`how-to/tool-call-data` | Generate multi-turn tool-calling SFT data | -| {doc}`how-to/preference-data` | Generate DPO preference pairs from `rl_pref.yaml` | -| {doc}`how-to/dispatch-to-cluster` | Dispatch generation to Lepton or Slurm via env.toml | + + -``` +| Guide | What You’ll Do | +| --- | --- | +| [Tips for the Data Generation Pipeline](/how-to/run) | Preview, generate, and customize output path and projection | +| [Create a Domain Dataset for Airlines Customer Service](/how-to/create-domain-dataset) | Adapt the pipeline to a custom domain with a seed file and multiple category dimensions | +| [Generate Tool-Calling Data for SFT](/how-to/tool-call-data) | Generate multi-turn tool-calling SFT data | +| [Generate Preference Data for DPO](/how-to/preference-data) | Generate DPO preference pairs from rl_pref.yaml | +| [Dispatch SDG to a Cluster](/how-to/dispatch-to-cluster) | Dispatch generation to Lepton or Slurm via env.toml | -```{tab-item} Reference + + -| Reference | What You'll Find | -|---|---| -| {doc}`reference/config-schema` | Full YAML column types, sampler parameters, and projection fields | -| {doc}`reference/cli-reference` | `nemotron steps run sdg/data_designer` flags and hydra overrides | -| {doc}`reference/output-projections` | The three projection shapes with annotated JSONL examples | -| {doc}`reference/troubleshooting` | Dispatch failures, image pull errors, API key issues, schema drift | +| Reference | What You’ll Find | +| --- | --- | +| [Config Schema](/reference/config-schema) | Full YAML column types, sampler parameters, and projection fields | +| [CLI Reference](/reference/cli-reference) | nemotron steps run sdg/data_designer flags and hydra overrides | +| [Output Projections](/reference/output-projections) | The three projection shapes with annotated JSONL examples | +| [Troubleshooting](/reference/troubleshooting) | Dispatch failures, image pull errors, API key issues, schema drift | -``` + -```` + ## Before You Start @@ -141,6 +148,9 @@ YAML config schema, CLI flags, output projection shapes, and troubleshooting. ## Limitations and Considerations - **Cost**: Generation calls a hosted LLM endpoint; each record incurs API cost. + - **Quality**: After generating records, review them before training. + - **Scale**: API rate limits apply. For large generation runs, dispatch to a cluster and consider batching across multiple nodes. + - **Reproducibility**: Seed files, column specs, model aliases, and inference parameters should all be version-controlled together. Changing any one of them changes the output distribution. diff --git a/docs/sdg/planning.md b/docs/fern/pages-vnightly/sdg/planning.mdx similarity index 65% rename from docs/sdg/planning.md rename to docs/fern/pages-vnightly/sdg/planning.mdx index 67d82e66d..77f7c0e26 100644 --- a/docs/sdg/planning.md +++ b/docs/fern/pages-vnightly/sdg/planning.mdx @@ -1,5 +1,10 @@ - +limitations under the License. */} -(sdg-planning)= -# Planning a Synthetic Data Generation Run + Synthetic data generation involves a sequence of decisions that determine whether the resulting data is useful for training. @@ -24,7 +27,7 @@ Synthetic data generation involves a sequence of decisions that determine whethe The seed file and prompts are where your domain knowledge enters the pipeline. The scenarios, constraints, and vocabulary you bring to the seed scenarios shape everything the generation produces. -A pipeline run without domain knowledge produces generic output from the model's own training data regardless of how well the column specs are written. +A pipeline run without domain knowledge produces generic output from the model’s own training data regardless of how well the column specs are written. The quality of your seed material is the strongest lever you have on the quality of what the pipeline produces. @@ -41,7 +44,10 @@ Preview records before you commit to generating thousands of records. ## Next Steps -- First run: {doc}`getting-started` -- Adapt the pipeline to your domain: {doc}`./how-to/create-domain-dataset` -- Preview and iterate on a config: {doc}`./how-to/run` -- Config field reference: {doc}`./reference/config-schema` +- First run: [Generate Your First Synthetic Dataset](/getting-started) + +- Adapt the pipeline to your domain: [Create a Domain Dataset for Airlines Customer Service](/how-to/create-domain-dataset) + +- Preview and iterate on a config: [Tips for the Data Generation Pipeline](/how-to/run) + +- Config field reference: [Config Schema](/reference/config-schema) diff --git a/docs/sdg/reference/cli-reference.md b/docs/fern/pages-vnightly/sdg/reference/cli-reference.mdx similarity index 61% rename from docs/sdg/reference/cli-reference.md rename to docs/fern/pages-vnightly/sdg/reference/cli-reference.mdx index 5c5f8b263..c1d3e01c0 100644 --- a/docs/sdg/reference/cli-reference.md +++ b/docs/fern/pages-vnightly/sdg/reference/cli-reference.mdx @@ -1,5 +1,10 @@ - +limitations under the License. */} -(sdg-cli-reference)= -# CLI Reference + -Command-line reference for `nemotron steps run sdg/data_designer`. For pipeline overview, see {doc}`../index`. +Command-line reference for `nemotron steps run sdg/data_designer`. For pipeline overview, see [About Synthetic Data Generation](/../index). ## Syntax @@ -32,41 +35,43 @@ $ nemotron steps run sdg/data_designer \ ## Flags -```{option} -c, --config CONFIG +### `-c, --config CONFIG` -Config name (resolved from the step's `config/` directory) or an absolute/relative path to a YAML file. +Config name (resolved from the step’s `config/` directory) or an absolute/relative path to a YAML file. Bundled names: `default`, `customer_support_tools`, `rl_pref`, `tiny`. **Default**: `default` -``` -```{option} -r, --run PROFILE +--- + +### `-r, --run PROFILE` Run attached using the env.toml profile named `PROFILE`. Job output streams to the terminal. Use for short interactive runs. -``` -```{option} -b, --batch PROFILE +--- + +### `-b, --batch PROFILE` Run detached using the env.toml profile named `PROFILE`. Job is submitted and the command returns immediately. Use for long cluster jobs. -``` -```{option} -d, --dry-run +--- + +### `-d, --dry-run` Compile the config and print the resolved job spec without executing. Useful for verifying hydra overrides before submission. -``` ## Hydra Overrides Any `KEY=VALUE` argument after the flags is passed as a hydra dotlist override and merged into the resolved config. Overrides take precedence over YAML values. | Override | Example | Effect | -|---|---|---| -| `num_records=N` | `num_records=50` | Generate N records | -| `preview=true` | `preview=true` | Run in preview mode | -| `output_path=PATH` | `output_path=/data/out.jsonl` | Write output to PATH | -| `seed_dataset.path=PATH` | `seed_dataset.path=/data/seeds.jsonl` | Override seed file | -| `models.0.inference_parameters.temperature=T` | `models.0.inference_parameters.temperature=0.5` | Override first model's temperature | +| --- | --- | --- | +| num_records=N | num_records=50 | Generate N records | +| preview=true | preview=true | Run in preview mode | +| output_path=PATH | output_path=/data/out.jsonl | Write output to PATH | +| seed_dataset.path=PATH | seed_dataset.path=/data/seeds.jsonl | Override seed file | +| models.0.inference_parameters.temperature=T | models.0.inference_parameters.temperature=0.5 | Override first model’s temperature | Dotlist path follows the YAML structure. Nested keys use `.` as separator; list items use `.N` (zero-indexed). @@ -106,6 +111,8 @@ $ nemotron steps run sdg/data_designer -c /path/to/my-config.yaml preview=true n ## Related -- {doc}`../how-to/run` — Preview, generate, and customize output. -- {doc}`../how-to/dispatch-to-cluster` — env.toml profile setup. -- {doc}`config-schema` — YAML config field reference. +- [Tips for the Data Generation Pipeline](/../how-to/run) — Preview, generate, and customize output. + +- [Dispatch SDG to a Cluster](/../how-to/dispatch-to-cluster) — env.toml profile setup. + +- [Config Schema](/config-schema) — YAML config field reference. diff --git a/docs/fern/pages-vnightly/sdg/reference/config-schema.mdx b/docs/fern/pages-vnightly/sdg/reference/config-schema.mdx new file mode 100644 index 000000000..fc9529931 --- /dev/null +++ b/docs/fern/pages-vnightly/sdg/reference/config-schema.mdx @@ -0,0 +1,240 @@ +--- +title: "Config Schema" +slug: "sdg/reference/config-schema.html" +description: "This page provides the reference information for the YAML config file consumed by sdg/data_designer." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. */} + + + +This page provides the reference information for the YAML config file consumed by `sdg/data_designer`. + +## Simple Fields + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| output_dir | string | no | Base output directory. Supports OmegaConf env-var interpolation. Default resolves $SDG_OUTPUT_DIR, then $NEMO_RUN_DIR/sdg, then ./output/sdg. | +| output_path | string | yes | Full path for the output JSONL file. Typically ${output_dir}/my-dataset.jsonl. | +| num_records | int | yes | Number of records to generate (client.create) or preview (client.preview). | +| preview | bool | no | When true, calls client.preview() instead of client.create(). Default: false. Prefer setting this as a CLI override (preview=true) rather than in the YAML. | + +## seed_dataset + +Optional top-level field. +When present, Data Designer samples one row per generated record from the seed file and makes the fields available to column prompts by using Jinja2. + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| path | string | yes | Path to a JSONL file. Each line is a JSON object. | +| strategy | string | no | shuffle (default) or ordered. | +| fields | list[string] | yes | Column names to expose. Must match keys in the seed JSONL objects. These become available as {{ field_name }} in prompts without being declared in columns. | + +## models + +A required top-level field. +The field specifies a list of model configurations. +Each entry defines one alias that column specs reference by name. + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| alias | string | yes | Short name referenced by model_alias in column specs. | +| model | string | yes | Model identifier such as nvidia/nemotron-3-nano-30b-a3b and openai/gpt-oss-20b. | +| provider | string | no | Provider name, such as nvidia or anthropic. | +| skip_health_check | bool | no | Skip the startup probe against the model provider. Useful for local or offline endpoints. Default: false. | +| inference_parameters.temperature | float | no | Sampling temperature. | +| inference_parameters.top_p | float | no | Top-p nucleus sampling. | +| inference_parameters.max_tokens | int | no | Maximum output tokens per call. | + +## columns + +A required top-level field. +This field is an ordered list of column specs. +Each column has a `name`, a `type`, and type-specific fields. +Columns can reference earlier columns and seed fields in prompts by using Jinja2 syntax like `\{\{ column_name \}\}`. + +### Categorical Columns + +Samples uniformly from a fixed list of string or numeric values like the following example. + +```yaml +- name: persona + type: category + values: [teacher, engineer, student, researcher] +``` + +| Field | Required | Description | +| --- | --- | --- | +| name | yes | Column name. | +| values | yes | List of values to sample from. | + +### Seed Columns + +Provides a named field from the seed dataset as a column. +Use this column type when a seed field needs to appear in `metadata_fields` or must be referenced in a way that requires it to be an explicit column. + +```yaml +- name: topic + type: seed +``` + +| Field | Required | Description | +| --- | --- | --- | +| name | yes | Must match a field name in seed_dataset.fields. | + +Seed fields declared in `seed_dataset.fields` are available directly in prompts without this column type. +Use `seed` only when you need the field as a named column in the output schema. + +### LLM Text Columns + +Generates free-form text using an LLM call. +These columns can references earlier specified columns and seed fields in `prompt` by using Jinja2 syntax. + +```yaml +- name: user_query + type: llm_text + model_alias: nvidia-text + prompt: | + Write a message from a {{ persona }} asking about: {{ topic }}. +``` + +| Field | Required | Description | +| --- | --- | --- | +| name | yes | Column name. | +| model_alias | no | Alias from models. Default: nvidia-text. | +| prompt | yes | Jinja2 template. Reference any earlier column or seed field with {{ name }}. | + +### LLM Structured Columns + +This column type generates structured JSON by making an LLM call. +The column definition instructs the model to return JSON matching `output_format`. +Use this column type for multi-turn conversations, preference judges, and any output that must conform to a schema. + +```yaml +- name: conversation + type: llm_structured + model_alias: nvidia-text + prompt: | + Generate a support conversation for customer {{ customer_name }}... + output_format: + type: object + properties: + messages: + type: array + ... + required: [messages] +``` + +| Field | Required | Description | +| --- | --- | --- | +| name | yes | Column name. | +| model_alias | no | Alias from models. Default: nvidia-text. | +| prompt | yes | Jinja2 template. | +| output_format | yes | JSON Schema dict describing the expected output structure. | + +### LLM Judge Columns + +This type is an alias for `llm_structured`. +This type is typically used for columns that compare or evaluate other columns. + +```yaml +- name: judge + type: llm_judge + model_alias: nvidia-text + prompt: | + Compare response A and B for: {{ prompt }} + A: {{ response_a }} + B: {{ response_b }} + output_format: + type: object + properties: + winner: + type: string + enum: [A, B] + required: [winner] +``` + +## output_projection + +This top-level field maps raw Data Designer records into the schema expected by downstream steps. +Refer to [Output Projections](/output-projections) for full field tables and annotated JSONL examples for each type. + +| type | Use for | Downstream | +| --- | --- | --- | +| openai_messages | Single-turn SFT chat | data_prep/sft_packing, AutoModel SFT | +| dpo_preference | Preference pairs | data_prep/rl_prep, rl/nemo_rl/dpo | +| structured_messages | Multi-turn with tool calls | data_prep/sft_packing, AutoModel SFT | + +## Extending the Schema: `person` and `datetime` Samplers + +The current `step.py` supports the column types above. To use Data Designer’s locale-aware person sampler or datetime sampler, `step.py`’s `build_columns()` function must be extended with `person` and `datetime` branches. A reference implementation showing both additions is in: + +```python startLine={1} + elif kind == "person": + builder.add_column( + dd.SamplerColumnConfig( + name=name, + sampler_type=dd.SamplerType.PERSON, + params=dd.PersonSamplerParams( + locale=spec.get("locale", "en_US"), + age_range=spec.get("age_range"), + with_synthetic_personas=spec.get("with_synthetic_personas", True), + ), + ) + ) + + elif kind == "datetime": + builder.add_column( + dd.SamplerColumnConfig( + name=name, + sampler_type=dd.SamplerType.DATETIME, + params=dd.DatetimeSamplerParams( + start=spec["start"], + end=spec["end"], + ), + ) + ) + +``` + +Once merged, configs can declare: + +```yaml +- name: traveler + type: person + locale: en_US + age_range: [22, 75] + with_synthetic_personas: true + +- name: booking_date + type: datetime + start: "2024-01-01" + end: "2025-12-31" +``` + +Download personas for the locale before running: + +```console +$ data-designer download personas --locale en_US +``` + +## Related Information + +- [Output Projections](/output-projections) — projection field reference and JSONL examples. + +- [CLI Reference](/cli-reference) — flags and hydra override syntax. + +- [Tips for the Data Generation Pipeline](/../how-to/run) — preview and generate workflow. diff --git a/docs/fern/pages-vnightly/sdg/reference/index.mdx b/docs/fern/pages-vnightly/sdg/reference/index.mdx new file mode 100644 index 000000000..403b0b525 --- /dev/null +++ b/docs/fern/pages-vnightly/sdg/reference/index.mdx @@ -0,0 +1,63 @@ +--- +title: "SDG Reference" +slug: "sdg/reference/index.html" +description: "Complete specifications for the SDG pipeline. For pipeline overview and when to use it, refer to About Synthetic Data Generation." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. */} + + + +Complete specifications for the SDG pipeline. For pipeline overview and when to use it, refer to [About Synthetic Data Generation](/../index). + + + +All YAML fields: top-level settings, seed dataset, model aliases, column types, and output projections. + +--- + +lookup + + + + +`nemotron steps run sdg/data_designer` flags and hydra override syntax. + +--- + +lookup + + + + +The three projection shapes with annotated JSONL examples. + +--- + +lookup + + + + +Failure modes for local runs and cluster dispatch. + +--- + +lookup + + + + diff --git a/docs/sdg/reference/output-projections.md b/docs/fern/pages-vnightly/sdg/reference/output-projections.mdx similarity index 68% rename from docs/sdg/reference/output-projections.md rename to docs/fern/pages-vnightly/sdg/reference/output-projections.mdx index a3ec2a670..32c33e0b4 100644 --- a/docs/sdg/reference/output-projections.md +++ b/docs/fern/pages-vnightly/sdg/reference/output-projections.mdx @@ -1,5 +1,10 @@ - +limitations under the License. */} -(sdg-output-projections)= -# Output Projections + The `output_projection` block in a config maps raw Data Designer records into the schema expected by downstream training steps. Each projection type extracts specific columns and writes one JSON object per line. @@ -50,11 +53,11 @@ output_projection: Fields: | Field | Required | Description | -|---|---|---| -| `type` | yes | `"openai_messages"` | -| `user_field` | yes | Column name for the user message content | -| `assistant_field` | yes | Column name for the assistant message content | -| `metadata_fields` | no | List of additional column names to include at the top level | +| --- | --- | --- | +| type | yes | "openai_messages" | +| user_field | yes | Column name for the user message content | +| assistant_field | yes | Column name for the assistant message content | +| metadata_fields | no | List of additional column names to include at the top level | ## DPO Preference @@ -85,13 +88,13 @@ output_projection: Fields: | Field | Required | Description | -|---|---|---| -| `type` | yes | `"dpo_preference"` | -| `prompt_field` | yes | Column name for the input prompt | -| `response_a_field` | yes | Column name for candidate A | -| `response_b_field` | yes | Column name for candidate B | -| `judge_field` | yes | Column name for the judge's structured output | -| `winner_field` | yes | Key within the judge output JSON that holds `"A"` or `"B"` | +| --- | --- | --- | +| type | yes | "dpo_preference" | +| prompt_field | yes | Column name for the input prompt | +| response_a_field | yes | Column name for candidate A | +| response_b_field | yes | Column name for candidate B | +| judge_field | yes | Column name for the judge’s structured output | +| winner_field | yes | Key within the judge output JSON that holds "A" or "B" | The projection raises `ValueError` if `winner` is not `"A"` or `"B"`. The `llm_judge` column must be configured to return exactly this structure. @@ -134,17 +137,19 @@ output_projection: Fields: | Field | Required | Description | -|---|---|---| -| `type` | yes | `"structured_messages"` | -| `source_field` | yes | Column containing the structured JSON conversation object | -| `messages_field` | no | Key in `source_field` for the messages array. Default: `"messages"` | -| `tools_field` | no | Key in `source_field` for the tools array. Omitted from output if not present in the record | -| `metadata_fields` | no | List of additional column names to include at the top level | +| --- | --- | --- | +| type | yes | "structured_messages" | +| source_field | yes | Column containing the structured JSON conversation object | +| messages_field | no | Key in source_field for the messages array. Default: "messages" | +| tools_field | no | Key in source_field for the tools array. Omitted from output if not present in the record | +| metadata_fields | no | List of additional column names to include at the top level | The `source_field` column value may be a JSON string or a dict; both are handled. ## Related Information -- {doc}`config-schema` — Full YAML config field reference. -- {doc}`../how-to/tool-call-data` — Using `structured_messages` with `customer_support_tools.yaml`. -- {doc}`../how-to/preference-data` — Using `dpo_preference` with `rl_pref.yaml`. +- [Config Schema](/config-schema) — Full YAML config field reference. + +- [Generate Tool-Calling Data for SFT](/../how-to/tool-call-data) — Using `structured_messages` with `customer_support_tools.yaml`. + +- [Generate Preference Data for DPO](/../how-to/preference-data) — Using `dpo_preference` with `rl_pref.yaml`. diff --git a/docs/sdg/reference/troubleshooting.md b/docs/fern/pages-vnightly/sdg/reference/troubleshooting.mdx similarity index 61% rename from docs/sdg/reference/troubleshooting.md rename to docs/fern/pages-vnightly/sdg/reference/troubleshooting.mdx index dc07f594a..8858009e3 100644 --- a/docs/sdg/reference/troubleshooting.md +++ b/docs/fern/pages-vnightly/sdg/reference/troubleshooting.mdx @@ -1,5 +1,10 @@ - +limitations under the License. */} -(sdg-troubleshooting)= -# Troubleshooting + -Failure modes for local runs and cluster dispatch. For cluster-specific setup, see {doc}`../how-to/dispatch-to-cluster`. +Failure modes for local runs and cluster dispatch. For cluster-specific setup, see [Dispatch SDG to a Cluster](/../how-to/dispatch-to-cluster). ## Local Run Failures -::::{dropdown} `Unknown column type: 'person'` or similar ValueError +**`Unknown column type: 'person'` or similar ValueError** -**Cause**: The YAML declares a column `type` that `step.py`'s `build_columns()` does not recognise. Currently supported types: `category`, `seed`, `llm_text`, `llm_structured`, `llm_judge`. +**Cause**: The YAML declares a column `type` that `step.py`’s `build_columns()` does not recognise. Currently supported types: `category`, `seed`, `llm_text`, `llm_structured`, `llm_judge`. -**Solution**: Check the spelling. For `person` and `datetime` sampler support, `step.py` must be extended — see the extension reference in {doc}`config-schema`. -:::: +**Solution**: Check the spelling. For `person` and `datetime` sampler support, `step.py` must be extended — see the extension reference in [Config Schema](/config-schema). -::::{dropdown} `config must declare a non-empty columns: list` +**`config must declare a non-empty columns: list`** **Cause**: The YAML has an empty or missing `columns:` block. **Solution**: Add at least one column spec. A minimal config must include at least one `llm_text` or `llm_structured` column that produces output content. -:::: -::::{dropdown} `Jinja2` template references an undefined variable +**`Jinja2` template references an undefined variable** -**Cause**: A prompt uses `{{ column_name }}` but `column_name` is neither a declared column, a seed field in `seed_dataset.fields`, nor an earlier column in the list. +**Cause**: A prompt uses `\{\{ column_name \}\}` but `column_name` is neither a declared column, a seed field in `seed_dataset.fields`, nor an earlier column in the list. **Solution**: Add the column or seed field, or fix the typo. Run `preview=true num_records=2` to catch this cheaply before a full generation job. -:::: -::::{dropdown} Model health check fails at startup +**Model health check fails at startup** **Cause**: Data Designer probes the model endpoint at startup. If the model is not available from the configured provider, or if `NVIDIA_API_KEY` is not set, the probe fails and the step exits before generating any records. **Solution**: + - Confirm `export NVIDIA_API_KEY="..."` is set. -- Add `skip_health_check: true` to the model spec to bypass the probe (useful for local or vLLM endpoints that aren't in the provider catalog). -:::: -::::{dropdown} Output JSONL is empty or has fewer records than `num_records` +- Add `skip_health_check: true` to the model spec to bypass the probe (useful for local or vLLM endpoints that aren’t in the provider catalog). -**Cause**: Data Designer skips or drops records where the structured output doesn't validate against `output_format`, or where the LLM returns a refusal. +**Output JSONL is empty or has fewer records than `num_records`** + +**Cause**: Data Designer skips or drops records where the structured output doesn’t validate against `output_format`, or where the LLM returns a refusal. **Solution**: + - Run `preview=true` and inspect a sample for refusals or schema mismatches. + - Simplify the `output_format` if the model consistently fails to match a complex schema. + - Raise `max_tokens` if responses are being cut off mid-JSON. -:::: ## Cluster Dispatch Failures -::::{dropdown} Job exits immediately with `No such file or directory` (launch script) +**Job exits immediately with `No such file or directory` (launch script)** **Cause**: `nemo_run_dir` is not on shared storage. The data-mover sidecar writes the launch script to `nemo_run_dir`, but the main container cannot see it if the path is local to a different node or not mounted. -**Solution**: Set `nemo_run_dir` to a path on the shared NFS mount and add the corresponding `mounts` entry to the env.toml profile. See {doc}`../how-to/dispatch-to-cluster`. -:::: +**Solution**: Set `nemo_run_dir` to a path on the shared NFS mount and add the corresponding `mounts` entry to the env.toml profile. See [Dispatch SDG to a Cluster](/../how-to/dispatch-to-cluster). -::::{dropdown} `data-designer` import error inside the container +**`data-designer` import error inside the container** **Cause**: The NeMo container image does not pre-install `data-designer`. @@ -82,16 +84,14 @@ startup_commands = [ "python -m pip install --quiet --break-system-packages 'data-designer==0.5.5'" ] ``` -:::: -::::{dropdown} Job rejected or OOM-killed immediately on a CPU node +**Job rejected or OOM-killed immediately on a CPU node** **Cause**: The default `shared_memory_size` (65536 MB) exceeds the available RAM on the CPU node type. **Solution**: Set `shared_memory_size = 1024` in the env.toml profile. The SDG step makes no use of shared memory. -:::: -::::{dropdown} `NVIDIA_API_KEY` not available inside the container +**`NVIDIA_API_KEY` not available inside the container** **Cause**: `NVIDIA_API_KEY` is not automatically forwarded to the job environment the way `HF_TOKEN` and `WANDB_API_KEY` are. @@ -103,10 +103,11 @@ NVIDIA_API_KEY = "${oc.env:NVIDIA_API_KEY}" ``` And set it in your shell before submitting: `export NVIDIA_API_KEY="..."`. -:::: ## Related -- {doc}`../how-to/dispatch-to-cluster` — Full cluster setup walkthrough. -- {doc}`cli-reference` — Flags and hydra overrides. -- {doc}`config-schema` — YAML field reference. +- [Dispatch SDG to a Cluster](/../how-to/dispatch-to-cluster) — Full cluster setup walkthrough. + +- [CLI Reference](/cli-reference) — Flags and hydra overrides. + +- [Config Schema](/config-schema) — YAML field reference. diff --git a/docs/sdg/using-skills.md b/docs/fern/pages-vnightly/sdg/using-skills.mdx similarity index 71% rename from docs/sdg/using-skills.md rename to docs/fern/pages-vnightly/sdg/using-skills.mdx index e6ff35adc..3f866e0c4 100644 --- a/docs/sdg/using-skills.md +++ b/docs/fern/pages-vnightly/sdg/using-skills.mdx @@ -1,5 +1,10 @@ - +limitations under the License. */} -(sdg-using-skills)= -# Use the SDG Skill With Confidence + This page is for newcomers to model training and new to *synthetic data generation (SDG)*. The main goal is to help you run a productive, efficient session with a coding agent: less back-and-forth, fewer clarifying questions, and clearer handoffs between what you decide and what the agent edits in the repository. @@ -28,12 +31,11 @@ Use an agent to translate your intent into the right YAML, seed files, and `nemo Provide a short brief you write yourself, not something the agent drafts for you: -```{div} sd-font-italic sd-font-weight-lighter -- "We need data for a model that can answer short questions about our company’s travel and expense policy." -- "I need multi-turn conversations for a retail support bot that can call tools such as order lookup and return eligibility. The tone must be friendly and concise." -``` +- “We need data for a model that can answer short questions about our company’s travel and expense policy.” + +- “I need multi-turn conversations for a retail support bot that can call tools such as order lookup and return eligibility. The tone must be friendly and concise.” -Ask the agent to start from shipped configs and the {doc}`getting-started` flow unless there is a strong reason to invent a new layout. +Ask the agent to start from shipped configs and the [Generate Your First Synthetic Dataset](/getting-started) flow unless there is a strong reason to invent a new layout. If you want a reusable shape, you can copy the following block into the chat and fill in the bracketed lines. @@ -50,8 +52,8 @@ Please: [one request]. Use Nemotron SDG defaults from the repo unless something A reasonable first success is a small preview run that writes plausible rows to `output_path`, plus a short list of seed ideas you believe are on-brand for your domain. If you have that, you are already operating SDG: iterate small, then scale record counts. -The hands-on path is {doc}`getting-started`. -When you are ready to attach your own domain, follow {doc}`how-to/create-domain-dataset`. +The hands-on path is [Generate Your First Synthetic Dataset](/getting-started). +When you are ready to attach your own domain, follow [Create a Domain Dataset for Airlines Customer Service](/how-to/create-domain-dataset). ## Where Domain-Specific Ideas Come From @@ -85,6 +87,8 @@ You can also say in the chat, “follow `src/nemotron/steps/sdg/SKILL.md` for SD ## Next Steps -- Run the tutorial: {doc}`getting-started`. -- Adapt seeds and YAML to your domain: {doc}`how-to/create-domain-dataset`. -- Look up flags and fields when the agent names them: {doc}`reference/cli-reference` and {doc}`reference/config-schema`. +- Run the tutorial: [Generate Your First Synthetic Dataset](/getting-started). + +- Adapt seeds and YAML to your domain: [Create a Domain Dataset for Airlines Customer Service](/how-to/create-domain-dataset). + +- Look up flags and fields when the agent names them: [CLI Reference](/reference/cli-reference) and [Config Schema](/reference/config-schema). diff --git a/docs/steps/airgap.md b/docs/fern/pages-vnightly/steps/airgap.mdx similarity index 81% rename from docs/steps/airgap.md rename to docs/fern/pages-vnightly/steps/airgap.mdx index 5569fdf6e..d271975bc 100644 --- a/docs/steps/airgap.md +++ b/docs/fern/pages-vnightly/steps/airgap.mdx @@ -1,10 +1,13 @@ - +--- +title: "Run Nemotron Steps in an Airgap Environment" +slug: "steps/airgap.html" +description: "This page describes how to run Nemotron steps in an airgap environment: a cluster or account boundary where training jobs cannot rely on the public internet for downloads, package indexes, or external" +--- -(steps-airgap)= -# Run Nemotron Steps in an Airgap Environment +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + This page describes how to run Nemotron steps in an *airgap environment*: a cluster or account boundary where training jobs cannot rely on the public internet for downloads, package indexes, or external APIs unless you explicitly provide replacements. @@ -12,16 +15,18 @@ A build process under `deploy/nemotron-customizer/airgap/` runs on a *networked You transfer those artifacts into the airgap environment, then submit jobs as usual with `nemotron steps`. A short checklist at the end of this page covers the storage, secrets, and providers you must manage for the environment. -For definitions of *step*, *configuration*, *environment profile*, and *artifact*, see [Nemotron Steps Basics](basics.md). +For definitions of *step*, *configuration*, *environment profile*, and *artifact*, see [Nemotron Steps Basics](/basics). ## Before You Start Confirm two things before you start the build process. - Docker is installed and can pull `nvcr.io` and Docker Hub images on the networked host. + - The networked host has disk space under `deploy/nemotron-customizer/airgap/out/` for the image TAR files you plan to produce. - Each image TAR file is several gigabytes. -- You [explored the Nemotron CLI](./getting-started.md). +Each image TAR file is several gigabytes. + +- You [explored the Nemotron CLI](/getting-started). ## Procedure: Build and Run the Airgap Bundle @@ -33,10 +38,11 @@ You decide which steps the build process covers by editing the `workflow.stages` The default value targets a small supervised fine-tuning workflow. 1. Edit `deploy/nemotron-customizer/airgap/airgap.yaml`. + 2. In `workflow.stages`, add the `` steps to run, such as `translate/nemo_curator:default`, and remove the rest. Prerequisites steps are automatically added from the `dependencies` map. - For example, an `sft/megatron_bridge:tiny` step also produces an image that covers `data_prep/sft_packing`. +For example, an `sft/megatron_bridge:tiny` step also produces an image that covers `data_prep/sft_packing`. If you would rather not edit the file, leave `workflow.stages` as is and specify `--target :` one or more times in the next phase to override the file. @@ -50,9 +56,9 @@ If you would rather not edit the file, leave `workflow.stages` as is and specify ``` Review the `[airgap]` section at the end of the output. - Confirm the images and steps match the steps you specified. - The following example is for the `translate/nemo_curator` and `sft/megatron_bridge` steps. - The `data_prep/sft_packing` step is a dependency. +Confirm the images and steps match the steps you specified. +The following example is for the `translate/nemo_curator` and `sft/megatron_bridge` steps. +The `data_prep/sft_packing` step is a dependency. ```text ... @@ -91,22 +97,26 @@ The `optimize/modelopt/prune` and `optimize/modelopt/distill` steps expect Model 3. If a run stops halfway, rerun the command. If you change the workflow or image plan, delete `airgap-build-state.yaml` before rerunning. - Otherwise, the build process reuses the stale state. +Otherwise, the build process reuses the stale state. 4. Collect `airgap-manifest.yaml`, launcher and execution image TAR files, and any generated requirements or repository-overlay metadata from the `deploy/nemotron-customizer/airgap/out/` directory. ### Transfer and Load Inside the Airgap Environment 1. Transfer the image TAR files and the manifest into the airgap environment by using a tool, such as `scp` or `rsync`. + 2. Load images into the cluster container runtime or private registry your executor uses. + 3. Stage large artifacts on executor-visible persistent storage. - They were not embedded in the images at build time. - These artifacts include model weights, datasets, checkpoints, tokenizer files, and customer data. +They were not embedded in the images at build time. +These artifacts include model weights, datasets, checkpoints, tokenizer files, and customer data. + 4. Reference those paths through configuration overrides and `run.env.mounts` in your environment profile. ### Inside the Airgap Environment: Submit Jobs 1. Open `airgap-manifest.yaml` and read the image tag or digest under `step_execution_images` for each step you run. + 2. For the steps that embed a repository at build time, override `run.env.mounts` to an empty list at submit time. ```yaml @@ -116,21 +126,23 @@ The `optimize/modelopt/prune` and `optimize/modelopt/distill` steps expect Model ``` The shipped overlay configs under `deploy/nemotron-customizer/airgap/configs/` do this for `sft/megatron_bridge`. + 3. Submit with `nemotron steps` and specify `run.env.container_image` to the manifest value. ```console - $ nemotron steps run \ - -c \ - -b \ - run.env.container_image= + $ nemotron steps run \ \ + -c \ \ + -b \ \ + run.env.container_image=\ ``` 4. If you operate an internal Hugging Face mirror or need the Hugging Face Hub reachable from inside the airgap environment, override the Dockerfile defaults using your profile `env_vars`. -:::{note} + The execution Dockerfiles set `HF_HUB_OFFLINE=1`, `TRANSFORMERS_OFFLINE=1`, `HF_DATASETS_OFFLINE=1`, and `WANDB_MODE=offline` so airgap runs do not reach out to public services by default. Those are upstream environment variable names from Hugging Face and Weights & Biases. -::: + + ## Cluster Checklist @@ -138,13 +150,19 @@ Use this short list after you load the bundle and before you submit production j It covers what stays your responsibility at the cluster, regardless of how the images were built. - Mount read-only storage for corpora, benchmarks, and pretrained checkpoints, and read-write storage for outputs. + - Replace any Hugging Face Hub identifier in your configuration with a filesystem path on a shared mount when the Hugging Face Hub is not reachable from the airgap environment. + - Update model provider configurations, such as `sdg/data_designer`, to an endpoint reachable from inside the airgap environment, such as a vLLM instance on the local network. + - Provide secrets through environment variables your executor injects, not through files committed to the repository. + - Run `nemotron steps show --json` and confirm every `consumes` entry maps to a local path or a mounted artifact before you submit. ## Related Material - `deploy/nemotron-customizer/airgap/README.md` for full airgap mechanics, pip cache volumes, and architecture notes. -- [Nemotron Steps Basics](basics.md) for environment profiles and mounts. -- Domain references for steps you run, for example [Model Training](../train-models/index.md), [Synthetic Data Generation](../sdg/index.md), and [Model Evaluation](../model-eval/index.md). + +- [Nemotron Steps Basics](/basics) for environment profiles and mounts. + +- Domain references for steps you run, for example [Model Training](/../train-models/index), [Synthetic Data Generation](/../sdg/index), and [Model Evaluation](/../model-eval/index). diff --git a/docs/steps/basics.md b/docs/fern/pages-vnightly/steps/basics.mdx similarity index 68% rename from docs/steps/basics.md rename to docs/fern/pages-vnightly/steps/basics.mdx index 41fa8795c..e929f51ab 100644 --- a/docs/steps/basics.md +++ b/docs/fern/pages-vnightly/steps/basics.mdx @@ -1,10 +1,13 @@ - +--- +title: "Nemotron Steps Basics" +slug: "steps/basics.html" +description: "This page defines the building blocks of the nemotron steps CLI. You do not need to read it to invoke a single command, but every domain section in the documentation assumes that you already understan" +--- -(steps-basics)= -# Nemotron Steps Basics +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + This page defines the building blocks of the `nemotron steps` CLI. You do not need to read it to invoke a single command, but every domain section in the documentation assumes that you already understand these definitions. @@ -15,8 +18,11 @@ A *step* is a named unit of work with a stable identifier, such as `sft/automode Each step packages four things: - A description of the work the step performs. + - The artifacts the step *consumes*, such as a chat-formatted JSON Lines (JSONL) dataset or a Megatron checkpoint. + - The artifacts the step *produces*, such as a Hugging Face checkpoint or a Parquet benchmark. + - One or more named configurations that supply parameter values. The step identifier is the only piece of information you need to invoke a job. @@ -31,9 +37,10 @@ A configuration sets values like the dataset path, the base model identifier, th Every step that runs at production scale ships at least two configurations: - `tiny` runs a short job that exercises the plumbing without consuming meaningful compute. - Use `tiny` to confirm that the step starts, that the data path is wired, and that the cluster accepts the submission. +Use `tiny` to confirm that the step starts, that the data path is wired, and that the cluster accepts the submission. + - `default` runs a production-shape job. - Use `default` as the starting point for real work, and override individual values from the command line when needed. +Use `default` as the starting point for real work, and override individual values from the command line when needed. You select the configuration with the `-c` option. You can supply ad hoc overrides as trailing `key=value` dotlist arguments on the same command line. @@ -46,12 +53,14 @@ A profile sets the container image, the node count, the resource shape, the moun You select the profile in one of three ways: - Omit the `-r` and `-b` flags to run on the local machine. + - Pass `-r ` to run attached, where the CLI streams logs back to your terminal until the job ends. + - Pass `-b ` to run detached, where the CLI submits the job and returns immediately. The CLI reads profiles from a TOML file named `env.toml` at the repository root by default. Set the `NEMOTRON_ENV_FILE` environment variable to point at a different profile file, such as `env.lepton.toml` or `env.slurm.toml`. -See [Execution Through NeMo Run](../nemo_runspec/nemo-run.md) for the full profile model, attached and detached execution, and cluster setup. +See [Execution Through NeMo Run](/../nemo_runspec/nemo-run) for the full profile model, attached and detached execution, and cluster setup. ### Generating Profile Files With the env Step @@ -62,28 +71,28 @@ Use `env/env_toml` when you need to bootstrap an `env.lepton.toml` or `env.slurm The following procedure generates a starter profile file, reviews it, and points the CLI at it. 1. Choose the bundled configuration that matches your target. - Use `lepton` for Lepton AI, `slurm` for a Slurm cluster, or `dgxcloud` for NVIDIA DGX Cloud. - List the available configurations with the following command. +Use `lepton` for Lepton AI, `slurm` for a Slurm cluster, or `dgxcloud` for NVIDIA DGX Cloud. +List the available configurations with the following command. ```console $ nemotron steps show env/env_toml ``` 2. Run the step from the repository root so the output lands beside `pyproject.toml`. - The following command generates an `env.lepton.toml` from the `lepton` configuration. +The following command generates an `env.lepton.toml` from the `lepton` configuration. ```console $ nemotron steps run env/env_toml -c lepton ``` Substitute `-c slurm` or `-c dgxcloud` for the other targets. - The step writes to `env.lepton.toml`, `env.slurm.toml`, or `env.dgxcloud.toml` by default, and it refuses to overwrite an existing file. - If you intentionally want to regenerate, pass `force=true` on the command line. +The step writes to `env.lepton.toml`, `env.slurm.toml`, or `env.dgxcloud.toml` by default, and it refuses to overwrite an existing file. +If you intentionally want to regenerate, pass `force=true` on the command line. 3. Open the generated TOML file and replace the site-specific values. - At minimum, set the node group, the resource shape, the workspace path, and the mount points. - For Slurm, also set the host, the user account, the partition, and the remote job directory. - Keep secrets out of the file and reference them through `${oc.env:VAR_NAME}` placeholders. +At minimum, set the node group, the resource shape, the workspace path, and the mount points. +For Slurm, also set the host, the user account, the partition, and the remote job directory. +Keep secrets out of the file and reference them through `$\{oc.env:VAR_NAME\}` placeholders. 4. Point the CLI at the generated file by exporting `NEMOTRON_ENV_FILE`. @@ -92,10 +101,10 @@ The following procedure generates a starter profile file, reviews it, and points ``` Add the export to your shell profile if you always work against the same target. - Without the variable, the CLI looks for a plain `env.toml` at the repository root. +Without the variable, the CLI looks for a plain `env.toml` at the repository root. 5. Confirm a profile resolves before you launch real work. - Pick a step that already has a generated profile and run it with the `tiny` configuration. +Pick a step that already has a generated profile and run it with the `tiny` configuration. ```console $ nemotron steps run sft/automodel -c tiny -r lepton_sft_automodel @@ -112,7 +121,7 @@ Steps chain together through *artifacts*. An artifact is a typed payload, such as `training_jsonl`, `packed_parquet`, `binidx`, `checkpoint_hf`, `checkpoint_megatron`, or `eval_results`. One step writes an artifact to a path you control, and a later step reads that same artifact as its input. -The chain holds as long as the consumer accepts the producer's artifact type. +The chain holds as long as the consumer accepts the producer’s artifact type. When two steps speak different layouts of the same idea, a `convert/*` step bridges the gap. For example, `convert/megatron_to_hf` turns a `checkpoint_megatron` artifact into a `checkpoint_hf` artifact for deployment. @@ -123,7 +132,7 @@ $ nemotron steps list --produces training_jsonl $ nemotron steps list --consumes training_jsonl ``` -See [Getting Started With Steps](getting-started.md) for a guided tour of these commands. +See [Getting Started With Steps](/getting-started) for a guided tour of these commands. ## Composing a Run @@ -140,7 +149,10 @@ Change the profile to move the same job to a different cluster. ## Where To Go Next -- [Getting Started With Steps](getting-started.md) walks through listing steps, inspecting inputs and outputs, and exploring the step graph from the CLI. -- [Model Training](../train-models/index.md) covers supervised fine-tuning, parameter-efficient fine-tuning, RL alignment, and post-training optimization. -- [Synthetic Data Generation](../sdg/index.md), [Translation](../translation/index.md), [Build MCQ Benchmarks](../build-benchmarks/index.md), and [Model Evaluation](../model-eval/index.md) each cover one family of steps end to end. -- [Execution Through NeMo Run](../nemo_runspec/nemo-run.md) describes profiles, attached and detached runs, and cluster setup. +- [Getting Started With Steps](/getting-started) walks through listing steps, inspecting inputs and outputs, and exploring the step graph from the CLI. + +- [Model Training](/../train-models/index) covers supervised fine-tuning, parameter-efficient fine-tuning, RL alignment, and post-training optimization. + +- [Synthetic Data Generation](/../sdg/index), [Translation](/../translation/index), [Build MCQ Benchmarks](/../build-benchmarks/index), and [Model Evaluation](/../model-eval/index) each cover one family of steps end to end. + +- [Execution Through NeMo Run](/../nemo_runspec/nemo-run) describes profiles, attached and detached runs, and cluster setup. diff --git a/docs/steps/getting-started.md b/docs/fern/pages-vnightly/steps/getting-started.mdx similarity index 77% rename from docs/steps/getting-started.md rename to docs/fern/pages-vnightly/steps/getting-started.mdx index 1130c3101..9c155d6fe 100644 --- a/docs/steps/getting-started.md +++ b/docs/fern/pages-vnightly/steps/getting-started.mdx @@ -1,20 +1,24 @@ - +--- +title: "Getting Started With Steps" +slug: "steps/getting-started.html" +description: "This guide walks through the basic CLI operations that you use to discover steps, inspect their inputs and outputs, and chain them into pipelines. You do not need a cluster or a GPU to follow along. E" +--- -(steps-getting-started)= -# Getting Started With Steps +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + This guide walks through the basic CLI operations that you use to discover steps, inspect their inputs and outputs, and chain them into pipelines. You do not need a cluster or a GPU to follow along. Every command in this guide reads metadata only. -If you have not read [Nemotron Steps Basics](basics.md), start there for the definitions of *step*, *configuration*, *environment profile*, and *artifact*. +If you have not read [Nemotron Steps Basics](/basics), start there for the definitions of *step*, *configuration*, *environment profile*, and *artifact*. ## Prerequisites - Python 3.10 or later. + - [uv](https://docs.astral.sh/uv/) installed and on your path. These prerequisites cover the basics for an introduction to using the steps. @@ -22,7 +26,7 @@ For each activity, such as model training or data generation, refer to the getti ## Getting Access to the Nemotron CLI -1. Clone the repository, if you haven't already: +1. Clone the repository, if you haven’t already: ```console $ git clone https://github.com/NVIDIA-NeMo/Nemotron && cd Nemotron @@ -128,8 +132,12 @@ The same pattern works for other artifact types, such as `packed_parquet`, `bini Pick the domain section that matches the work you have in mind. -- [Synthetic Data Generation](../sdg/index.md) to generate chat data, tool-calling data, or preference pairs. -- [Translation](../translation/index.md) to translate corpora with optional faithfulness, accuracy, integrity, and translation-quality holistic (FAITH) scoring. -- [Build MCQ Benchmarks](../build-benchmarks/index.md) to generate a multiple-choice question benchmark from your own documents. -- [Model Training](../train-models/index.md) to fine-tune, align, or optimize a model. -- [Model Evaluation](../model-eval/index.md) to score a deployed checkpoint with standard benchmarks. +- [Synthetic Data Generation](/../sdg/index) to generate chat data, tool-calling data, or preference pairs. + +- [Translation](/../translation/index) to translate corpora with optional faithfulness, accuracy, integrity, and translation-quality holistic (FAITH) scoring. + +- [Build MCQ Benchmarks](/../build-benchmarks/index) to generate a multiple-choice question benchmark from your own documents. + +- [Model Training](/../train-models/index) to fine-tune, align, or optimize a model. + +- [Model Evaluation](/../model-eval/index) to score a deployed checkpoint with standard benchmarks. diff --git a/docs/steps/index.md b/docs/fern/pages-vnightly/steps/index.mdx similarity index 61% rename from docs/steps/index.md rename to docs/fern/pages-vnightly/steps/index.mdx index 1df941f05..31a3866ea 100644 --- a/docs/steps/index.md +++ b/docs/fern/pages-vnightly/steps/index.mdx @@ -1,10 +1,13 @@ - +--- +title: "About Nemotron Steps" +slug: "steps/index.html" +description: "A Nemotron step is a named, reusable unit of work that you invoke with the nemotron steps CLI. Each step declares the artifacts it consumes, the artifacts it produces, and a set of named configuration" +--- -(steps-index)= -# About Nemotron Steps +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + A Nemotron *step* is a named, reusable unit of work that you invoke with the `nemotron steps` CLI. Each step declares the artifacts it consumes, the artifacts it produces, and a set of named configurations that you can run on your laptop, on a single node, or on a cluster. @@ -15,29 +18,27 @@ Use it to learn what a step is, to explore the available steps from the CLI, and ## The Basics -::::{grid} 1 2 2 2 -:gutter: 2 - -:::{grid-item-card} Nemotron Steps Basics -:link: basics -:link-type: doc - + + Definitions of *step*, *configuration*, *environment profile*, and *artifact*. Start here if you have not run a step before. -+++ + +--- + `Concepts` -::: -:::{grid-item-card} Getting Started With Steps -:link: getting-started -:link-type: doc + + List the available steps, inspect their inputs and outputs, and chain steps together. -+++ + +--- + `Beginner` -::: -:::: + + + ## Building Block Steps @@ -46,93 +47,43 @@ You can run a single step in isolation, and you can compose steps into longer fl The cards below group the available steps by the outcome they support. Follow the link in each card for tutorials, how-to guides, concepts, and reference material in that domain. -::::::{grid} 1 1 3 3 -:gutter: 2 - -:::::{grid-item} - -::::{grid} 1 -:gutter: 1 - -:::{grid-item-card} Synthetic Data Generation -:link: ../sdg/index -:link-type: doc - -Build your own dataset -^^^ - + + Generate supervised fine-tuning (SFT) chat data, tool-calling data, or preference pairs with NeMo Data Designer. Backed by the `sdg/data_designer` step. -::: -:::{grid-item-card} Translation -:link: ../translation/index -:link-type: doc + + Translate JSON Lines or Apache Parquet corpora with NeMo Curator, with optional faithfulness, accuracy, integrity, and translation-quality holistic (FAITH) scoring. Backed by the `translate/nemo_curator` step. -::: -:::{grid-item-card} Data Curation and Preparation -:link: ../curate/index -:link-type: doc + + Filter raw text with `curate/nemo_curator`, then tokenize and shard it with the `data_prep/pretrain_prep`, `data_prep/sft_packing`, and `data_prep/rl_prep` steps. Use the curation docs for JSONL filtering and the training docs for data preparation. -::: - -:::: - -::::: - -:::::{grid-item} - -::::{grid} 1 -:gutter: 1 - -:::{grid-item-card} Multiple-Choice Question Benchmarks -:link: ../build-benchmarks/index -:link-type: doc -Build your own benchmarks -^^^ + + Generate a custom multiple-choice question (MCQ) benchmark from your own documents, with optional translation. Backed by the `byob` step. -::: -:::: - -::::: - -:::::{grid-item} - -::::{grid} 1 -:gutter: 1 - -:::{grid-item-card} Model Training -:link: ../train-models/index -:link-type: doc - -Build your own models -^^^ + + Pretrain, fine-tune, align, and optimize models with the `pretrain/`, `sft/`, `peft/`, `rl/`, `optimize/`, and `convert/` step families. -::: -:::{grid-item-card} Model Evaluation -:link: ../model-eval/index -:link-type: doc + + Score a trained checkpoint on standard benchmarks with NeMo Evaluator. Backed by the `eval/model_eval` step. -::: - -:::: -::::: + -:::::: + ## Shared Infrastructure @@ -144,13 +95,13 @@ The Basics page covers profiles and the `env/env_toml` step in detail. | Goal | Go To | | --- | --- | -| Learn what a step, configuration, and profile are | [Nemotron Steps Basics](basics.md) | -| List the available steps from the CLI | [Getting Started With Steps](getting-started.md) | -| Run steps in an airgap environment | [Airgap](airgap.md) | -| Curate JSONL text | [Data Curation](../curate/index.md) | -| Generate synthetic training data | [Synthetic Data Generation](../sdg/index.md) | -| Translate a corpus | [Translation](../translation/index.md) | -| Build an MCQ benchmark | [Build MCQ Benchmarks](../build-benchmarks/index.md) | -| Fine-tune or align a model | [Model Training](../train-models/index.md) | -| Evaluate a model | [Model Evaluation](../model-eval/index.md) | -| Set up a Lepton or Slurm environment profile | [Nemotron Steps Basics](basics.md) | +| Learn what a step, configuration, and profile are | [Nemotron Steps Basics](/basics) | +| List the available steps from the CLI | [Getting Started With Steps](/getting-started) | +| Run steps in an airgap environment | [Airgap](/airgap) | +| Curate JSONL text | [Data Curation](/../curate/index) | +| Generate synthetic training data | [Synthetic Data Generation](/../sdg/index) | +| Translate a corpus | [Translation](/../translation/index) | +| Build an MCQ benchmark | [Build MCQ Benchmarks](/../build-benchmarks/index) | +| Fine-tune or align a model | [Model Training](/../train-models/index) | +| Evaluate a model | [Model Evaluation](/../model-eval/index) | +| Set up a Lepton or Slurm environment profile | [Nemotron Steps Basics](/basics) | diff --git a/docs/train-models/explanation/artifact-graph.md b/docs/fern/pages-vnightly/train-models/explanation/artifact-graph.mdx similarity index 51% rename from docs/train-models/explanation/artifact-graph.md rename to docs/fern/pages-vnightly/train-models/explanation/artifact-graph.mdx index 184f01034..89ed9b5ee 100644 --- a/docs/train-models/explanation/artifact-graph.md +++ b/docs/fern/pages-vnightly/train-models/explanation/artifact-graph.mdx @@ -1,18 +1,10 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Explains how training steps declare typed inputs and outputs, what the common training and alignment paths look like, and why tokenizer alignment matters across a pipeline." -topics: ["Training", "Explanation", "Concepts"] -tags: ["Artifact Graph", "Pipeline", "JSONL", "Checkpoint", "Tokenizer"] -content: - type: "Explanation" - difficulty: "Intermediate" - audience: ["ML Engineer", "Developer"] +title: "Artifact Graph" +slug: "train-models/explanation/artifact-graph.html" +description: "For definitions of artifact, step, and how the CLI’s --produces and --consumes filters let you walk the artifact graph, see Nemotron Steps Basics. This page focuses on the artifact types and common ch" --- -# Artifact Graph - -For definitions of *artifact*, *step*, and how the CLI's `--produces` and `--consumes` filters let you walk the artifact graph, see [Nemotron Steps Basics](../../steps/basics.md). +For definitions of *artifact*, *step*, and how the CLI’s `--produces` and `--consumes` filters let you walk the artifact graph, see [Nemotron Steps Basics](/../../steps/basics). This page focuses on the artifact types and common chains specific to model training. ## Common Training Paths @@ -20,6 +12,7 @@ This page focuses on the artifact types and common chains specific to model trai The supervised fine-tuning paths in the Nemotron pipeline follow one of the following two chains. - The Hugging Face line used by `sft/automodel`: `training_jsonl` → `sft/automodel` → `checkpoint_hf`. + - The packed Megatron line used by `sft/megatron_bridge`: `training_jsonl` → packing prep → `packed_parquet` → `sft/megatron_bridge` → `checkpoint_megatron`. A typical alignment path starts from a `checkpoint_megatron` policy, adds preference or reward-side data, runs one of the `rl/nemo_rl/...` steps, and produces a new `checkpoint_megatron`. @@ -35,7 +28,10 @@ A mismatch often appears as a plausible training loss curve with poor downstream ## Related Reading -- [Nemotron Steps Basics](../../steps/basics.md) defines the concepts of *step*, *configuration*, *environment profile*, and *artifact*. -- [Training Basics](basics.md) defines the training-specific terms, including tokenizers and chat templates. -- [Data and Checkpoint Formats](../how-to/data-and-checkpoint-formats.md) describes the on-disk layouts of each artifact type. -- [Training Libraries](training-libraries.md) describes the ecosystem of libraries that back the steps. +- [Nemotron Steps Basics](/../../steps/basics) defines the concepts of *step*, *configuration*, *environment profile*, and *artifact*. + +- [Training Basics](/basics) defines the training-specific terms, including tokenizers and chat templates. + +- [Data and Checkpoint Formats](/../how-to/data-and-checkpoint-formats) describes the on-disk layouts of each artifact type. + +- [Training Libraries](/training-libraries) describes the ecosystem of libraries that back the steps. diff --git a/docs/train-models/explanation/basics.md b/docs/fern/pages-vnightly/train-models/explanation/basics.mdx similarity index 79% rename from docs/train-models/explanation/basics.md rename to docs/fern/pages-vnightly/train-models/explanation/basics.mdx index 9f693f173..c5bce325b 100644 --- a/docs/train-models/explanation/basics.md +++ b/docs/fern/pages-vnightly/train-models/explanation/basics.mdx @@ -1,20 +1,12 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Plain-language introduction to fine-tuning approaches, tokenizers, datasets, and checkpoints. For the step, configuration, and environment profile model, see Nemotron Steps Basics." -topics: ["Training", "Explanation", "Concepts"] -tags: ["Beginner", "Explanation", "SFT", "PEFT", "RL", "Quantization", "Tokenizer", "Chat Template", "JSONL", "Checkpoint"] -content: - type: "Explanation" - difficulty: "Beginner" - audience: ["ML Engineer", "Developer"] +title: "Training Basics" +slug: "train-models/explanation/basics.html" +description: "This page defines the training-specific terms that the rest of the training documentation uses. You do not need to read it to run a command, but every other page in this section assumes that you alrea" --- -# Training Basics - This page defines the training-specific terms that the rest of the training documentation uses. You do not need to read it to run a command, but every other page in this section assumes that you already understand these basics. -For the step, configuration, and environment profile model that every Nemotron command shares, see [Nemotron Steps Basics](../../steps/basics.md). +For the step, configuration, and environment profile model that every Nemotron command shares, see [Nemotron Steps Basics](/../../steps/basics). ## Training Approaches @@ -52,7 +44,7 @@ The choice of quantization recipe, such as `fp8` or `nvfp4`, depends on the targ ## Tokenizers and Chat Templates -A *tokenizer* converts text strings into the integer identifiers the model consumes, and converts the model's output identifiers back into text. +A *tokenizer* converts text strings into the integer identifiers the model consumes, and converts the model’s output identifiers back into text. Each model family ships with its own tokenizer. A run that uses one tokenizer to prepare data and a different tokenizer to train will fail outright, or, worse, will train against meaningless input. Keep the tokenizer aligned across every stage that touches the same model. @@ -61,27 +53,42 @@ A *chat template* is a small text-substitution recipe that the tokenizer applies It inserts role markers such as `user` and `assistant`, any special start-of-turn and end-of-turn tokens, and any fixed system instructions. The template ships with the tokenizer. You do not write a chat template by hand for ordinary fine-tuning. -You do need to confirm that the conversation format of your dataset matches what the chosen tokenizer's template expects. +You do need to confirm that the conversation format of your dataset matches what the chosen tokenizer’s template expects. ## The Messages JSON Lines Format Most SFT and PEFT steps in this documentation consume chat-formatted *JSON Lines* (JSONL) datasets. JSONL is one independent JSON object per line, with no enclosing array. Each object has a single field named `messages` that holds an ordered list of conversation turns. -Each turn has a `role` of `system`, `user`, or `assistant`, and a `content` field with the turn's text. +Each turn has a `role` of `system`, `user`, or `assistant`, and a `content` field with the turn’s text. The following is one JSONL record covering a system instruction, a user question, and the assistant response. -```{literalinclude} ../_snippets/input/sample-messages.jsonl -:language: json +```json startLine={1} +{ + "messages": [ + { + "role": "system", + "content": "You answer arithmetic questions in one sentence." + }, + { + "role": "user", + "content": "What is twelve times seven?" + }, + { + "role": "assistant", + "content": "Twelve times seven is eighty-four." + } + ] +} ``` A real dataset has one such line for every training example. -The training loop reads the file line by line, applies the model's chat template to each `messages` list, and treats the assistant turns as the prediction targets. +The training loop reads the file line by line, applies the model’s chat template to each `messages` list, and treats the assistant turns as the prediction targets. ## Checkpoints -A *checkpoint* is a saved snapshot of a model's weights. +A *checkpoint* is a saved snapshot of a model’s weights. A checkpoint contains every numeric parameter the model uses to make predictions, in a serialization format the training and inference code can read back. Most training steps in the Nemotron pipeline produce one of the following three checkpoint layouts. @@ -97,6 +104,8 @@ Always record the tokenizer version that produced the data so the inference runt ## Where To Go Next -- [Nemotron Steps Basics](../../steps/basics.md) defines the *step*, *configuration*, and *environment profile* model that every training command uses. -- [Getting Started With Training Steps](../getting-started.md) walks through a first run. -- [Reference](../reference/index.md) lists every step, configuration, and command-line option. +- [Nemotron Steps Basics](/../../steps/basics) defines the *step*, *configuration*, and *environment profile* model that every training command uses. + +- [Getting Started With Training Steps](/../getting-started) walks through a first run. + +- [Reference](/../reference/index) lists every step, configuration, and command-line option. diff --git a/docs/fern/pages-vnightly/train-models/explanation/index.mdx b/docs/fern/pages-vnightly/train-models/explanation/index.mdx new file mode 100644 index 000000000..327535975 --- /dev/null +++ b/docs/fern/pages-vnightly/train-models/explanation/index.mdx @@ -0,0 +1,45 @@ +--- +title: "Training Concepts" +slug: "train-models/explanation/index.html" +description: "This section provides conceptual material for training with Nemotron steps. Training Basics introduces fine-tuning approaches, tokenizers, the chat dataset format, and checkpoint layouts. For the step" +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + +This section provides conceptual material for training with Nemotron steps. +[Training Basics](/basics) introduces fine-tuning approaches, tokenizers, the chat dataset format, and checkpoint layouts. +For the step, configuration, and environment profile model that every Nemotron command shares, see [Nemotron Steps Basics](/../../steps/basics). +The remaining pages explain how artifacts relate to one another and how the training libraries differ. + + + +Defines supervised fine-tuning, parameter-efficient fine-tuning, reinforcement learning alignment, quantization, tokenizers, the chat dataset format, and checkpoints. + +--- + +concepts + + + + +Explains how steps declare typed inputs and outputs and what common training and alignment paths look like. + +--- + +concepts + + + + +Explains which library backs each step and how that choice determines data format, checkpoint layout, and parallelism. + +--- + +concepts + + + + diff --git a/docs/train-models/explanation/training-libraries.md b/docs/fern/pages-vnightly/train-models/explanation/training-libraries.mdx similarity index 73% rename from docs/train-models/explanation/training-libraries.md rename to docs/fern/pages-vnightly/train-models/explanation/training-libraries.mdx index 81748769e..a087eb82d 100644 --- a/docs/train-models/explanation/training-libraries.md +++ b/docs/fern/pages-vnightly/train-models/explanation/training-libraries.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Explains which training library backs each Nemotron step, and how the choice of library determines data format, checkpoint layout, and parallelism conventions." -topics: ["Training", "Explanation", "Concepts"] -tags: ["Training Libraries", "NeMo AutoModel", "Megatron-Bridge", "NeMo RL", "Model Optimizer"] -content: - type: "Explanation" - difficulty: "Intermediate" - audience: ["ML Engineer", "Developer"] +title: "Training Libraries" +slug: "train-models/explanation/training-libraries.html" +description: "Each Nemotron training step delegates to a specific training library. The library determines how the step loads models, how it reads data, and the native checkpoint layout it writes. Different librari" --- -# Training Libraries - Each Nemotron training step delegates to a specific *training library*. The library determines how the step loads models, how it reads data, and the native checkpoint layout it writes. Different libraries impose different data formats, checkpoint formats, and parallelism conventions, so the choice of library shapes every step downstream of it. @@ -51,6 +43,8 @@ Switching from one library to another requires conversion steps and a new round ## Related Reading -- [Training Basics](basics.md) defines the training approaches and the artifact types each library consumes and produces. -- [Choose an SFT Backend](../how-to/choose-sft-backend.md) compares the two SFT libraries side by side. -- [Execution through NeMo Run](../../nemo_runspec/nemo-run.md) describes how each library is launched at runtime. +- [Training Basics](/basics) defines the training approaches and the artifact types each library consumes and produces. + +- [Choose an SFT Backend](/../how-to/choose-sft-backend) compares the two SFT libraries side by side. + +- [Execution through NeMo Run](/../../nemo_runspec/nemo-run) describes how each library is launched at runtime. diff --git a/docs/fern/pages-vnightly/train-models/getting-started.mdx b/docs/fern/pages-vnightly/train-models/getting-started.mdx new file mode 100644 index 000000000..81cf0f5d6 --- /dev/null +++ b/docs/fern/pages-vnightly/train-models/getting-started.mdx @@ -0,0 +1,183 @@ +--- +title: "Getting Started with Training Steps" +slug: "train-models/getting-started.html" +description: "This page walks through one supervised fine tuning (SFT) run on DGX Cloud Lepton using the tiny configuration. The tiny configuration lives in src/nemotron/steps/sft/automodel/config/tiny.yaml and is " +--- + +This page walks through one supervised fine tuning (SFT) run on DGX Cloud Lepton using the *tiny* configuration. +The tiny configuration lives in `src/nemotron/steps/sft/automodel/config/tiny.yaml` and is meant for short validation before you scale work. +The goal is to validate end-to-end execution, NeMo Run, and your environment profile on real multi-node hardware. + +## Prerequisites + +- You need access to DGX Cloud Lepton with GPU nodes. +This path assumes two nodes with eight A100 80 GB GPUs per node, matching the `run.env` block in `src/nemotron/steps/sft/automodel/config/tiny.yaml`. + +- You set the following environment variables: + + - `HF_TOKEN` + + - `WANDB_API_KEY` + + - `NVIDIA_API_KEY` + +- You ran `lep login` after syncronizing dependencies and are logged into Lepton. + +The preceding list applies to the steps on this page. +Refer to [Limitations and Restrictions](/index#limitations-and-restrictions) for information about supported environments. + +## Procedure + +1. Clone the repository, if you haven’t already: + + ```console + $ git clone https://github.com/NVIDIA-NeMo/Nemotron && cd Nemotron + ``` + +1. Set the dependencies: + + ```console + $ uv sync + ``` + +1. Create an `env.toml` at the root of the repository like the following example: + + ```text startLine={1} + [lepton_base] + executor = "lepton" + container_image = "nvcr.io/nvidia/nemo:25.11.nemotron_3_nano" + node_group = "\" + nemo_run_dir = "/mnt/lustre-shared/\/experiments" + remote_job_dir = "/mnt/lustre-shared/\/output/functional" + workspace = "/mnt/lustre-shared" + ray_version = "2.48.0" + shared_memory_size = 65536 + pip_extras = ["typer", "rich", "pydantic-settings"] + mounts = [ + { from = "node-nfs:\", path = "\", mount_path = "/mnt/lustre-shared" } + ] + env_vars = { + HF_TOKEN = "${oc.env:HF_TOKEN,''}", + HF_HOME = "/mnt/lustre-shared/hf", + WANDB_API_KEY = "${oc.env:WANDB_API_KEY,''}", + WANDB_PROJECT = "\", + NVIDIA_API_KEY = "${oc.env:NVIDIA_API_KEY,''}", + RAY_DEDUP_LOGS = "0", + RAY_GRAFANA_IFRAME_HOST = "" + } + + [lepton_sft_automodel] + extends = "lepton_base" + container_image = "nvcr.io/nvidia/nemo-automodel:26.04" + resource_shape = "gpu.8xa100-80gb" + nodes = 2 + pip_extras = ["typer", "rich", "pydantic-settings", "omegaconf"] + ``` + +**Summary of the Config File** + + The `[lepton_base]` table defines cluster fundamentals that every profile inherits: the executor, the base container image, the node group, shared-storage paths, the Ray runtime version, the shared-memory size, the Python package extras the Nemotron CLI needs, the cluster mount, and an `env_vars` block whose `$\{oc.env:VAR,''\}` entries pull credentials from your shell at submit time. +The `[lepton_sft_automodel]` table extends the base and adds the AutoModel container image, the resource shape needed for full-parameter SFT, the node count, and the additional Python package extras the AutoModel runtime expects. + + Contact your cluster administrator for the values that replace the placeholders. + + - ``: The Lepton node group identifier for the cluster you have access to. + + - ``: A directory you own on the shared mount where NeMo Run records each experiment. + + - ``: The alias of the Lepton storage fileset that each container mounts. + + - ``: The host path the fileset exposes. + + - ``: The Weights & Biases project name the run reports to. + + Export `HF_TOKEN`, `WANDB_API_KEY`, and `NVIDIA_API_KEY` in your shell before submitting; the env file pulls them in without writing the values to disk. + + If you would rather generate a complete env file with every Nemotron training profile pre-wired, run the bundled environment profile generator instead of writing the file by hand. + + ```console + $ uv run nemotron steps run env/env_toml -c lepton output_path=env.toml force=true + ``` + + The generator emits every canonical profile the training steps expect, including data-prep, SFT, PEFT, RL, and pretrain variants. + +1. View the step manifest and run specification: + + ```console + $ uv run nemotron steps show sft/automodel + ``` + +**Example Output** + + ```default startLine={1} + ──────────────────────────── sft/automodel — SFT Training (AutoModel) ──────────────────────────── + ~/nemotron/src/nemotron/steps/sft/automodel + + Supervised fine-tuning with the AutoModel stack for HF-format models and JSONL + datasets that already use OpenAI chat-format messages. Supports full SFT and + LoRA-style adapter tuning from the same step. + + Consumes + • training_jsonl — Instruction data in JSONL with a messages field + + Produces + • checkpoint_hf — HuggingFace checkpoint directory (full model or adapter-style PEFT output) + + Parameters + • peft (default=null) — Use 'lora' for adapter tuning, or 'null' for full fine-tuning. + + Runspec + launcher: torchrun + image: - + resources: nodes=1 gpus_per_node=4 + config dir: ~/nemotron/src/nemotron/steps/sft/automodel/config + default config: default + ``` + +1. Compile the job against your Lepton profile without submitting it. +The profile name `lepton_sft_automodel` must match a table in your root `env.toml`. + + ```console + $ uv run nemotron steps run sft/automodel --config tiny --run lepton_sft_automodel --dry-run + ``` + +**Partial Output** + + ```text + Compiled Configuration + + ╭─────────────────────────────────────────── run ───────────────────────────────────────────╮ + │ env: │ + │ nodes: 2 │ + │ gpus_per_node: 8 │ + │ nprocs_per_node: 8 │ + │ executor: lepton │ + │ container_image: nvcr.io/nvidia/nemo-automodel:26.04 │ + │ node_group: az-sat-lepton-001 │ + │ resource_shape: gpu.8xa100-80gb │ + │ remote_job_dir: /mnt/lustre-shared/user/nemotron/.nemotron-jobs + ... + ``` + +1. Submit the sample SFT job: + + ```console + $ uv run nemotron steps run sft/automodel -c tiny -r lepton_sft_automodel + ``` + +The sample `tiny` config sets small training and validation splits. +To specify the output path for checkpoints, set `SFT_OUTPUT_DIR` before running or specify the `checkpoint.checkpoint_dir` CLI override. + +## Success Checks + +- The command `nemotron steps show ` lists `consumes` and `produces` artifact types. Those types must line up with your pipeline when you chain steps. + +- A finished sample run leaves logs and job metadata where NeMo Run is configured to write them. See [Execution through NeMo Run](/../nemo_runspec/nemo-run) for experiment layout. + +- If you change tokenizer, template, or sequence length, keep them consistent across every step that touches the same model line. The [Artifact Graph](/explanation/artifact-graph) page explains why consistency matters. + +## Next Steps + +- Follow [Run SFT with AutoModel on Custom Data](/how-to/run-sft-automodel) when you need to point `tiny.yaml` at your own data or change the base model. + +- Read [Choose an SFT Backend](/how-to/choose-sft-backend) when you need Megatron Bridge instead of AutoModel. diff --git a/docs/train-models/how-to/choose-peft-backend.md b/docs/fern/pages-vnightly/train-models/how-to/choose-peft-backend.mdx similarity index 61% rename from docs/train-models/how-to/choose-peft-backend.md rename to docs/fern/pages-vnightly/train-models/how-to/choose-peft-backend.mdx index 53d9f923e..4bff17af8 100644 --- a/docs/train-models/how-to/choose-peft-backend.md +++ b/docs/fern/pages-vnightly/train-models/how-to/choose-peft-backend.mdx @@ -1,18 +1,24 @@ -# Choose a PEFT Backend +--- +title: "Choose a PEFT Backend" +slug: "train-models/how-to/choose-peft-backend.html" +description: "Parameter-efficient fine tuning (PEFT) in Nemotron is implemented as dedicated steps that emit adapter checkpoints. Pick the backend that matches your base checkpoint format and your data path." +--- Parameter-efficient fine tuning (PEFT) in Nemotron is implemented as dedicated steps that emit adapter checkpoints. Pick the backend that matches your base checkpoint format and your data path. ## Options | Step id | Best when | Primary inputs | Primary output artifact | -|---------|------------|------------------|---------------------------| -| `peft/automodel` | You have a Hugging Face base, chat-formatted JSON Lines (JSONL), and a small GPU count | `training_jsonl` | `checkpoint_lora` | -| `peft/megatron_bridge` | You have a Megatron base checkpoint and packed Apache Parquet at scale | `packed_parquet`, `checkpoint_megatron` | `checkpoint_lora` | +| --- | --- | --- | --- | +| peft/automodel | You have a Hugging Face base, chat-formatted JSON Lines (JSONL), and a small GPU count | training_jsonl | checkpoint_lora | +| peft/megatron_bridge | You have a Megatron base checkpoint and packed Apache Parquet at scale | packed_parquet, checkpoint_megatron | checkpoint_lora | ## Decision Flow 1. If you have one to four graphics processing units (GPUs) and JSON Lines (JSONL) chat data, use `peft/automodel`. + 2. If you have eight or more GPUs, you already run Megatron packing, and you train adapters on a Megatron base, use `peft/megatron_bridge`. + 3. If deployment requires a merged Hugging Face model, plan `convert/merge_lora` after training. Add any Megatron to Hugging Face conversion step that your pipeline needs before merge. Adapter evaluation scores are not identical to merged model scores. ## Sample Commands @@ -27,9 +33,11 @@ The Megatron Bridge path needs compatible packed Parquet and a base `checkpoint_ ## Success Criteria - You version adapter artifacts with base model id, data blend, rank, alpha, and target module set so you can reproduce runs. + - You re-evaluate after merge when production uses merged weights. ## Related Reading -- [Choose an SFT Backend](choose-sft-backend.md) -- [Data and Checkpoint Formats](data-and-checkpoint-formats.md) +- [Choose an SFT Backend](/choose-sft-backend) + +- [Data and Checkpoint Formats](/data-and-checkpoint-formats) diff --git a/docs/train-models/how-to/choose-rl-step.md b/docs/fern/pages-vnightly/train-models/how-to/choose-rl-step.mdx similarity index 65% rename from docs/train-models/how-to/choose-rl-step.md rename to docs/fern/pages-vnightly/train-models/how-to/choose-rl-step.mdx index 25ad0cdf0..0cd8d5d82 100644 --- a/docs/train-models/how-to/choose-rl-step.md +++ b/docs/fern/pages-vnightly/train-models/how-to/choose-rl-step.mdx @@ -1,22 +1,29 @@ -# Choose an RL Alignment Step +--- +title: "Choose an RL Alignment Step" +slug: "train-models/how-to/choose-rl-step.html" +description: "Post-training alignment with NeMo RL is split into three steps under rl/nemo_rl/. The table uses short names: direct preference optimization (DPO), reinforcement learning with verifiable rewards (RLVR" +--- Post-training alignment with NeMo RL is split into three steps under `rl/nemo_rl/`. The table uses short names: direct preference optimization (DPO), reinforcement learning with verifiable rewards (RLVR) paired with group relative policy optimization (GRPO), and reinforcement learning from human feedback (RLHF). Choose a step based on how the reward signal enters training, not based on model family alone. ## Options | Step id | Reward source | Typical data shape | Output | -|---------|---------------|-------------------|--------| -| `rl/nemo_rl/dpo` | Static preference pairs | Prompt with chosen and rejected completions | `checkpoint_megatron` | -| `rl/nemo_rl/rlvr` | Verifiable or programmatic checks | Prompt with answers, tests, or environment metadata | `checkpoint_megatron` | -| `rl/nemo_rl/rlhf` | Learned reward or judge model | Prompts plus a reward model checkpoint | `checkpoint_megatron` | +| --- | --- | --- | --- | +| rl/nemo_rl/dpo | Static preference pairs | Prompt with chosen and rejected completions | checkpoint_megatron | +| rl/nemo_rl/rlvr | Verifiable or programmatic checks | Prompt with answers, tests, or environment metadata | checkpoint_megatron | +| rl/nemo_rl/rlhf | Learned reward or judge model | Prompts plus a reward model checkpoint | checkpoint_megatron | All three steps consume a warm-start policy in `checkpoint_megatron` format produced by Megatron-style supervised fine tuning (SFT). They do not train a policy from scratch. ## Decision Flow 1. If you only have pairwise preferences and no online reward, use `rl/nemo_rl/dpo`. + 2. If reward is deterministic, for example unit tests, answer match, or tool success, use `rl/nemo_rl/rlvr`. + 3. If a separate reward model or judge produces scores, use `rl/nemo_rl/rlhf`. + 4. For resource-server rewards or NeMo Gym style rewards, use the RLVR or RLHF configuration paths documented in each step `SKILL.md` file and YAML file. Some flows use `config/nemo_gym.yaml`. ## Data Preparation @@ -34,9 +41,11 @@ $ uv run nemotron steps run rl/nemo_rl/rlhf -c tiny ## Success Criteria - You validate reward design on a small batch before you scale rollout count. + - You track Kullback–Leibler (KL) drift, reward variance, response length, and held-out task metrics. Average reward alone is not sufficient. ## Related Reading -- [Execution through NeMo Run](../../nemo_runspec/nemo-run.md) describes Ray-backed RL workloads on supported executors. -- [Training Libraries](../explanation/training-libraries.md) places NeMo RL in the wider library ecosystem. +- [Execution through NeMo Run](/../../nemo_runspec/nemo-run) describes Ray-backed RL workloads on supported executors. + +- [Training Libraries](/../explanation/training-libraries) places NeMo RL in the wider library ecosystem. diff --git a/docs/train-models/how-to/choose-sft-backend.md b/docs/fern/pages-vnightly/train-models/how-to/choose-sft-backend.mdx similarity index 65% rename from docs/train-models/how-to/choose-sft-backend.md rename to docs/fern/pages-vnightly/train-models/how-to/choose-sft-backend.mdx index 1402241d4..93d7d3c91 100644 --- a/docs/train-models/how-to/choose-sft-backend.md +++ b/docs/fern/pages-vnightly/train-models/how-to/choose-sft-backend.mdx @@ -1,18 +1,24 @@ -# Choose an SFT Backend +--- +title: "Choose an SFT Backend" +slug: "train-models/how-to/choose-sft-backend.html" +description: "Supervised fine tuning (SFT) is implemented by two interchangeable steps. Pick one step based on data format, checkpoint format, and scale." +--- Supervised fine tuning (SFT) is implemented by two interchangeable steps. Pick one step based on data format, checkpoint format, and scale. ## Options | Step id | Best when | Primary input artifact | Primary output artifact | -|---------|-----------|------------------------|-------------------------| -| `sft/automodel` | You have OpenAI chat-formatted JSON Lines (JSONL), you want Hugging Face style checkpoints, or you want the smallest cluster footprint for iteration | `training_jsonl` | `checkpoint_hf` | -| `sft/megatron_bridge` | You need distributed Megatron Bridge training with packed sequences and an Apache Parquet pipeline | `packed_parquet` | `checkpoint_megatron` | +| --- | --- | --- | --- | +| sft/automodel | You have OpenAI chat-formatted JSON Lines (JSONL), you want Hugging Face style checkpoints, or you want the smallest cluster footprint for iteration | training_jsonl | checkpoint_hf | +| sft/megatron_bridge | You need distributed Megatron Bridge training with packed sequences and an Apache Parquet pipeline | packed_parquet | checkpoint_megatron | ## Decision Flow 1. If your data is already chat-formatted JSON Lines (JSONL) and downstream tools expect Hugging Face safetensors, start with `sft/automodel`. + 2. If your data is packed Parquet produced by the packing prep step, or you require Megatron distributed checkpoints without an export round trip, use `sft/megatron_bridge`. + 3. If you start on one backend and later need the other output format, plan an explicit conversion step in your pipeline. Do not switch backends silently without conversion. ## Prerequisites for Megatron Bridge @@ -29,10 +35,13 @@ $ uv run nemotron steps run sft/megatron_bridge -c tiny ## Success Criteria - The commands `nemotron steps show sft/automodel` and `nemotron steps show sft/megatron_bridge` list the `consumes` types your workspace must provide. + - Loss decreases on a small slice before you scale data or learning rate. + - Tokenizer, chat template, and sequence length stay aligned with evaluation and with any later reinforcement learning (RL) step that reuses the policy. ## Related Reading -- [Data and Checkpoint Formats](data-and-checkpoint-formats.md) -- [Artifact Graph](../explanation/artifact-graph.md) +- [Data and Checkpoint Formats](/data-and-checkpoint-formats) + +- [Artifact Graph](/../explanation/artifact-graph) diff --git a/docs/train-models/how-to/convert-checkpoints.md b/docs/fern/pages-vnightly/train-models/how-to/convert-checkpoints.mdx similarity index 82% rename from docs/train-models/how-to/convert-checkpoints.md rename to docs/fern/pages-vnightly/train-models/how-to/convert-checkpoints.mdx index 609821acf..0bab3b7c5 100644 --- a/docs/train-models/how-to/convert-checkpoints.md +++ b/docs/fern/pages-vnightly/train-models/how-to/convert-checkpoints.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "How to choose and run Nemotron checkpoint conversion steps between Hugging Face, Megatron, and LoRA adapter layouts." -topics: ["Training", "How-To", "Checkpoint Conversion"] -tags: ["How-To", "Checkpoints", "Conversion", "Hugging Face", "Megatron", "LoRA"] -content: - type: "How-To" - difficulty: "Intermediate" - audience: ["ML Engineer", "Developer"] +title: "Convert Checkpoints Between Training Steps" +slug: "train-models/how-to/convert-checkpoints.html" +description: "Use a conversion step when one step produces a checkpoint layout that the next step cannot consume directly. The converter is an explicit pipeline step, not an implicit side effect of training." --- -# Convert Checkpoints Between Training Steps - Use a conversion step when one step produces a checkpoint layout that the next step cannot consume directly. The converter is an explicit pipeline step, not an implicit side effect of training. @@ -19,14 +11,16 @@ The converter is an explicit pipeline step, not an implicit side effect of train | Source artifact | Target artifact | Step | | --- | --- | --- | -| `checkpoint_hf` | `checkpoint_megatron` | `convert/hf_to_megatron` | -| `checkpoint_megatron` | `checkpoint_hf` | `convert/megatron_to_hf` | -| `checkpoint_lora` plus original base checkpoint | merged `checkpoint_hf` | `convert/merge_lora` | +| checkpoint_hf | checkpoint_megatron | convert/hf_to_megatron | +| checkpoint_megatron | checkpoint_hf | convert/megatron_to_hf | +| checkpoint_lora plus original base checkpoint | merged checkpoint_hf | convert/merge_lora | Common cases: - AutoModel SFT or PEFT produces Hugging Face layout checkpoints. Use `convert/hf_to_megatron` before Megatron-Bridge consumers that require Megatron layout. + - Megatron-Bridge SFT, RL, and some optimization steps produce Megatron distributed checkpoints. Use `convert/megatron_to_hf` before Hugging Face-native evaluation, deployment, or pruning flows. + - PEFT steps produce adapter checkpoints. Use `convert/merge_lora` when deployment or evaluation needs a single merged Hugging Face checkpoint. ## Preflight Checks @@ -34,8 +28,11 @@ Common cases: Before conversion: - Pick one validated checkpoint iteration. For Megatron exports, point `megatron_path` at the concrete `iter_*` checkpoint directory, not the parent run directory. + - Keep output paths separate from input paths. A failed conversion should never overwrite the source checkpoint. + - Keep tokenizer and chat-template provenance with the checkpoint. If the converter needs `hf_model_id`, use the original model or config source used by training. + - For LoRA merge, use the exact base checkpoint the adapter was trained against. ## Convert Hugging Face to Megatron @@ -113,11 +110,15 @@ Equivalent profile names are `slurm_convert_model` for Slurm and `dgxcloud_conve After conversion: - Confirm the output directory exists and contains model weights plus tokenizer/config files for Hugging Face outputs. + - Run a small generation or evaluation smoke test before using the checkpoint for a larger training or evaluation job. + - Preserve the source checkpoint until the converted checkpoint has passed validation. ## Related Documentation -- [Data and Checkpoint Formats](data-and-checkpoint-formats.md) -- [Artifact Graph](../explanation/artifact-graph.md) -- [Conversion Step References](../reference/convert/index.md) +- [Data and Checkpoint Formats](/data-and-checkpoint-formats) + +- [Artifact Graph](/../explanation/artifact-graph) + +- [Conversion Step References](/../reference/convert/index) diff --git a/docs/train-models/how-to/data-and-checkpoint-formats.md b/docs/fern/pages-vnightly/train-models/how-to/data-and-checkpoint-formats.mdx similarity index 84% rename from docs/train-models/how-to/data-and-checkpoint-formats.md rename to docs/fern/pages-vnightly/train-models/how-to/data-and-checkpoint-formats.mdx index 25fc20dd5..8aab9854b 100644 --- a/docs/train-models/how-to/data-and-checkpoint-formats.md +++ b/docs/fern/pages-vnightly/train-models/how-to/data-and-checkpoint-formats.mdx @@ -1,4 +1,8 @@ -# Data and Checkpoint Formats +--- +title: "Data and Checkpoint Formats" +slug: "train-models/how-to/data-and-checkpoint-formats.html" +description: "Training steps declare compatible artifacts in each step.toml file. This page summarizes the types that most training steps use so you can chain steps without format surprises." +--- Training steps declare compatible artifacts in each `step.toml` file. This page summarizes the types that most training steps use so you can chain steps without format surprises. @@ -9,15 +13,21 @@ Artifact names and compatibility rules live in `src/nemotron/steps/types.toml` a ## Frequently Used Types - The `training_jsonl` type means JSON Lines (JSONL) with a `messages` field in OpenAI chat shape. AutoModel supervised fine tuning (SFT) and parameter-efficient fine tuning (PEFT) consume it, and several reinforcement learning (RL) data paths consume it. + - The `packed_parquet` type means packed shards with token columns and masks for Megatron Bridge style trainers. You get this type only after you run a packing prep step when you use the Parquet path. + - The `checkpoint_hf` type means Hugging Face layout checkpoints or full weights on disk. + - The `checkpoint_megatron` type means Megatron distributed checkpoints sharded across parallel ranks. + - The `checkpoint_lora` type means low-rank adaptation (LoRA) adapter weights. Many downstream tools still need merge or export before deployment. ## Chaining Guidance 1. AutoModel SFT never consumes `packed_parquet`. Megatron Bridge SFT does not consume raw JSON Lines (JSONL) for the packed pipeline. + 2. RL steps in this repository expect a Megatron policy checkpoint for warm start. If your SFT used AutoModel, insert the appropriate conversion step before RL. + 3. Optimization steps that start from `checkpoint_hf` require a merged base when the trainable artifact was LoRA. ## Where to Look in the Tree @@ -25,11 +35,15 @@ Artifact names and compatibility rules live in `src/nemotron/steps/types.toml` a Each step directory contains the following files: - `step.toml` holds the identifier, human title, tags, `[[consumes]]`, `[[produces]]`, `[[parameters]]`, optional `[[strategies]]`, `[[errors]]`, and `[[models]]` blocks. + - `config/default.yaml` holds primary configuration tuned for real workloads. + - `config/tiny.yaml` holds reduced settings for short sample runs and end-to-end execution validation. + - Extra files such as `config/nemo_gym.yaml` appear only on steps that need alternate method profiles. ## Related Reading -- [Artifact Graph](../explanation/artifact-graph.md) -- [Step Catalog (Training)](../reference/step-catalog.md) +- [Artifact Graph](/../explanation/artifact-graph) + +- [Step Catalog (Training)](/../reference/step-catalog) diff --git a/docs/train-models/how-to/env-and-executors.md b/docs/fern/pages-vnightly/train-models/how-to/env-and-executors.mdx similarity index 73% rename from docs/train-models/how-to/env-and-executors.md rename to docs/fern/pages-vnightly/train-models/how-to/env-and-executors.mdx index b6ff5535f..fde4e08f0 100644 --- a/docs/train-models/how-to/env-and-executors.md +++ b/docs/fern/pages-vnightly/train-models/how-to/env-and-executors.mdx @@ -1,13 +1,19 @@ -# Environment Profiles and Executors +--- +title: "Environment Profiles and Executors" +slug: "train-models/how-to/env-and-executors.html" +description: "Training steps use the same NeMo Run integration as the rest of Nemotron. Configuration is compiled into a job. Then a backend submits that job locally, to Slurm, to Lepton, or to other supported targ" +--- Training steps use the same NeMo Run integration as the rest of Nemotron. Configuration is compiled into a job. Then a *backend* submits that job locally, to Slurm, to Lepton, or to other supported targets that your environment profile defines. ## What to Read First -[Execution through NeMo Run](../../nemo_runspec/nemo-run.md) is the canonical guide for the following topics: +[Execution through NeMo Run](/../../nemo_runspec/nemo-run) is the canonical guide for the following topics: - Environment profile files and how they attach clusters, images, and mounts. + - Attached runs with `--run` compared with detached runs with `--batch`. + - How dotlist overrides merge into YAML training configuration. ## How This Maps to Steps @@ -17,10 +23,13 @@ The command `nemotron steps run` resolves a step identifier to `step.py`, loads ## Practical Checklist 1. Confirm `uv run nemotron steps show ` prints the run specification you expect. + 2. Run with `--dry-run` once per new profile to catch mount and image issues early. + 3. For reinforcement learning (RL) steps that require Ray, align node count, GPU count, and Ray settings with what NeMo RL expects for your cluster. Long-form details stay in NeMo Run and NeMo RL documentation linked from each step `step.toml` reference block. ## Related Reading -- [Getting Started](../getting-started.md) -- [Nemotron CLI Overview](../../nemotron/cli.md) +- [Getting Started](/../getting-started) + +- [Nemotron CLI Overview](/../../nemotron/cli) diff --git a/docs/fern/pages-vnightly/train-models/how-to/index.mdx b/docs/fern/pages-vnightly/train-models/how-to/index.mdx new file mode 100644 index 000000000..9664b3d60 --- /dev/null +++ b/docs/fern/pages-vnightly/train-models/how-to/index.mdx @@ -0,0 +1,90 @@ +--- +title: "Model Training How-To Guides" +slug: "train-models/how-to/index.html" +description: "This section provides task-focused guides for common training workflows. For your first run, start with Getting Started with Training Steps." +--- + +{/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + +This section provides task-focused guides for common training workflows. +For your first run, start with [Getting Started with Training Steps](/../getting-started). + +If you are new to fine-tuning concepts, read [Training Concepts](/../explanation/index) for definitions of fine-tuning approaches, data formats, and checkpoints before working through these tasks. + + + +Configure `tiny.yaml` for your own JSONL data, run the step, verify the checkpoint output, and resolve common issues. + +--- + +30 min beginner + + + + +Pick between `sft/automodel` and `sft/megatron_bridge` based on checkpoint format and scale. + +--- + +intermediate + + + + +Pick between `peft/automodel` and `peft/megatron_bridge` based on base checkpoint format and data path. + +--- + +intermediate + + + + +Pick between DPO, RLVR, and RLHF based on how the reward signal enters training. + +--- + +intermediate + + + + +Apply quantization, pruning, or distillation with Model Optimizer after a trained model passes your quality bar. + +--- + +intermediate + + + + +Configure NeMo Run environment profiles for local, Slurm, and Lepton execution. + +--- + +intermediate + + + + +Understand the JSONL, Parquet, and checkpoint types that training steps declare in `step.toml`. + +--- + +intermediate + + + + +Run a conversion step when one step produces a checkpoint layout that the next step cannot consume directly. + +--- + +intermediate + + + + diff --git a/docs/train-models/how-to/run-optimization.md b/docs/fern/pages-vnightly/train-models/how-to/run-optimization.mdx similarity index 65% rename from docs/train-models/how-to/run-optimization.md rename to docs/fern/pages-vnightly/train-models/how-to/run-optimization.mdx index eacb96dab..86c3b353d 100644 --- a/docs/train-models/how-to/run-optimization.md +++ b/docs/fern/pages-vnightly/train-models/how-to/run-optimization.mdx @@ -1,20 +1,27 @@ -# Run Post-Training Optimization +--- +title: "Run Post-Training Optimization" +slug: "train-models/how-to/run-optimization.html" +description: "Optimization steps apply NVIDIA Model Optimizer flows after you have a trained model that is worth compressing. Run them only on checkpoints that already passed your quality bar." +--- Optimization steps apply NVIDIA Model Optimizer flows after you have a trained model that is worth compressing. Run them only on checkpoints that already passed your quality bar. ## Steps | Step id | Purpose | Typical input | Output | -|---------|---------|---------------|--------| -| `optimize/modelopt/quantize` | Post-training quantization | `checkpoint_hf` | `checkpoint_megatron` | -| `optimize/modelopt/prune` | Structured pruning | `checkpoint_hf` | `checkpoint_hf` | -| `optimize/modelopt/distill` | Teacher-student recovery | Teacher and student `checkpoint_hf`, optional `binidx` | `checkpoint_megatron` | +| --- | --- | --- | --- | +| optimize/modelopt/quantize | Post-training quantization | checkpoint_hf | checkpoint_megatron | +| optimize/modelopt/prune | Structured pruning | checkpoint_hf | checkpoint_hf | +| optimize/modelopt/distill | Teacher-student recovery | Teacher and student checkpoint_hf, optional binidx | checkpoint_megatron | ## Decision Flow 1. If you only need a smaller numeric type for inference, start with `optimize/modelopt/quantize`. Pick a quantization recipe that matches your hardware. FP8 suits Hopper. NVFP4 suits Blackwell. Read `step.toml` for parameter names and allowed values. + 2. If you need a smaller architecture, use `optimize/modelopt/prune`. + 3. If quality drops after compression, use `optimize/modelopt/distill` with a full-precision teacher while the student matches the compressed artifact. + 4. Do not run optimization on unmerged adapters. When the source was parameter-efficient fine tuning (PEFT) with low-rank adaptation (LoRA), merge LoRA into a base checkpoint first. ## Order of Operations @@ -34,9 +41,11 @@ Tiny runs and mock-data runs validate end-to-end execution only. Judge final qua ## Success Criteria - You keep the original high-precision checkpoint and its evaluation baseline. + - Post-optimization evaluation uses the same benchmark suite as pre-optimization evaluation. ## Related Reading -- [Optimization Steps Reference](../reference/optimize/index.md) -- [Artifact Graph](../explanation/artifact-graph.md) +- [Optimization Steps Reference](/../reference/optimize/index) + +- [Artifact Graph](/../explanation/artifact-graph) diff --git a/docs/train-models/how-to/run-sft-automodel.md b/docs/fern/pages-vnightly/train-models/how-to/run-sft-automodel.mdx similarity index 57% rename from docs/train-models/how-to/run-sft-automodel.md rename to docs/fern/pages-vnightly/train-models/how-to/run-sft-automodel.mdx index 8d1921088..50ca1acae 100644 --- a/docs/train-models/how-to/run-sft-automodel.md +++ b/docs/fern/pages-vnightly/train-models/how-to/run-sft-automodel.mdx @@ -1,5 +1,10 @@ - - -# Run SFT with AutoModel on Custom Data +limitations under the License. */} This guide walks through configuring and running the `sft/automodel` step with your own instruction data. The step trains models in a Hugging Face checkpoint layout from OpenAI chat-formatted JSON Lines (JSONL). -Before following this guide, complete [Getting Started with Training Steps](../getting-started.md) to verify your environment profile and confirm that the sample job runs to completion. +Before following this guide, complete [Getting Started with Training Steps](/../getting-started) to verify your environment profile and confirm that the sample job runs to completion. ## Prerequisites - A completed `env.toml` at the repository root with a training profile such as `lepton_sft_automodel`. - See [Getting Started with Training Steps](../getting-started.md) for the environment snippet and how to generate the full profile file. +See [Getting Started with Training Steps](/../getting-started) for the environment snippet and how to generate the full profile file. + - `HF_TOKEN`, `WANDB_API_KEY`, and `NVIDIA_API_KEY` exported in your shell. + - Instruction data in JSONL form where each record includes a `messages` field in OpenAI chat format. + - A Hugging Face access token if the base model is gated or must be downloaded from the Hugging Face Hub. + - Enough GPU memory for the model you select. - Verify memory requirements before scaling beyond a tiny configuration. +Verify memory requirements before scaling beyond a tiny configuration. ## Configure the Step 1. Open `src/nemotron/steps/sft/automodel/config/tiny.yaml`. - The checked-in defaults pull small public data slices from the Hugging Face Hub. - Replace the `dataset` and `model` fields with your paths and model identifier. +The checked-in defaults pull small public data slices from the Hugging Face Hub. +Replace the `dataset` and `model` fields with your paths and model identifier. 2. Align the tokenizer and chat template with how your JSONL was built. - The step applies the tokenizer at training time, so a mismatch between the template used during data preparation and the template applied here causes silent quality degradation or a hard failure at startup. - See [Data and Checkpoint Formats](data-and-checkpoint-formats.md) for the canonical field names the step expects. +The step applies the tokenizer at training time, so a mismatch between the template used during data preparation and the template applied here causes silent quality degradation or a hard failure at startup. +See [Data and Checkpoint Formats](/data-and-checkpoint-formats) for the canonical field names the step expects. ## Run the Step @@ -51,7 +57,7 @@ $ uv run nemotron steps run sft/automodel -c tiny -r lepton_sft_automodel ``` Replace `lepton_sft_automodel` with the profile name from your `env.toml` when your team uses a different table key. -See [Execution through NeMo Run](../../nemo_runspec/nemo-run.md) for profile setup and scheduler behavior. +See [Execution through NeMo Run](/../../nemo_runspec/nemo-run) for profile setup and scheduler behavior. ## Verify Output @@ -69,12 +75,16 @@ The `produces` block lists `checkpoint_hf` and the path it writes to. ## Common Issues - When you encounter CUDA out-of-memory errors, reduce batch sizes in YAML or switch to a smaller base model. + - When the trainer reports a missing chat template, pick a tokenizer that defines a template or convert your data to a format the trainer accepts. - The `step.toml` file lists `[[errors]]` entries such as `chat_template_missing` with recovery hints. +The `step.toml` file lists `[[errors]]` entries such as `chat_template_missing` with recovery hints. + - When you need to checkpoint to a specific directory, set `SFT_OUTPUT_DIR` in your shell before running or pass the `checkpoint.checkpoint_dir` override on the command line. ## Next Steps -- Read [Choose an SFT Backend](choose-sft-backend.md) when you need Megatron Bridge and packed Parquet instead of AutoModel and JSONL. -- Read [Data and Checkpoint Formats](data-and-checkpoint-formats.md) to understand how JSONL and checkpoints chain with other steps. -- Read [Convert Checkpoints Between Training Steps](convert-checkpoints.md) when the next step in your pipeline requires a different checkpoint layout. +- Read [Choose an SFT Backend](/choose-sft-backend) when you need Megatron Bridge and packed Parquet instead of AutoModel and JSONL. + +- Read [Data and Checkpoint Formats](/data-and-checkpoint-formats) to understand how JSONL and checkpoints chain with other steps. + +- Read [Convert Checkpoints Between Training Steps](/convert-checkpoints) when the next step in your pipeline requires a different checkpoint layout. diff --git a/docs/fern/pages-vnightly/train-models/index.mdx b/docs/fern/pages-vnightly/train-models/index.mdx new file mode 100644 index 000000000..7a609f91f --- /dev/null +++ b/docs/fern/pages-vnightly/train-models/index.mdx @@ -0,0 +1,103 @@ +--- +title: "Model Training with Nemotron Steps" +slug: "train-models/index.html" +description: "This section documents how to run supervised fine-tuning (SFT), parameter-efficient fine-tuning (PEFT), reinforcement learning (RL) alignment, and post-training optimization with Nemotron steps. Each " +--- + +This section documents how to run supervised fine-tuning (SFT), parameter-efficient fine-tuning (PEFT), reinforcement learning (RL) alignment, and post-training optimization with Nemotron *steps*. +Each step packages a training approach, configuration files, and entry logic that you invoke through the `nemotron steps` CLI. +For the definitions of *step*, *configuration*, and *environment profile* that apply across every domain, see [Nemotron Steps Basics](/../steps/basics). +If you are new to fine-tuning, start with [Training Basics](/explanation/basics), which defines the training-specific terms the rest of this section uses. + +## Capabilities at a Glance + +| Area | Step Names | Role | +| --- | --- | --- | +| SFT | sft/automodel, sft/megatron_bridge | Supervised fine tuning from chat-formatted JSON Lines (JSONL) or packed Apache Parquet | +| PEFT | peft/automodel, peft/megatron_bridge | Adapter training with a smaller trainable surface | +| RL | rl/nemo_rl/dpo, rl/nemo_rl/rlvr, rl/nemo_rl/rlhf | Alignment after a supervised fine tuning (SFT) policy exists | +| Optimize | optimize/modelopt/quantize, optimize/modelopt/prune, optimize/modelopt/distill | Compression and quality recovery | + +## Limitations and Restrictions + +The Nemotron steps for data preparation and model training do not support local training, such as on a developer workstation. + +These steps require access to at least two nodes, each equipped with 8 x NVIDIA A100 80 GB or better GPUs. +These steps support the following environments: + +- Slurm + +- NVIDIA DGX Cloud Lepton + +- NVIDIA Run:ai + +For assistance with configuring access to one of the supported computing environments, refer to [Env Profile Generator](/reference/env-profile-generator) or run the `nemotron-env-toml` skill with your agent. + +## Learning Path + + + +This page defines supervised fine-tuning, parameter-efficient fine-tuning, reinforcement learning alignment, quantization, tokenizers, the chat dataset format, and checkpoints. + +--- + +`Beginner Level` + + + + +This guide covers installation expectations, the environment profile, and how to run your first sample job with the `tiny` configuration. + +--- + +`Beginner` + + + + +These guides are task-focused. They explain how to pick a backend, wire data, and run optimization steps. + +--- + +`Intermediate` + + + + +This material explains the basics, the artifact graph, and how the training libraries differ. + +--- + +`Concepts` + + + + +This material is for lookup. It lists the step catalog, parameters, and configuration conventions. + +--- + +`Lookup` + + + + +Use the customize skill with a YAML-first plan: repo steps, then configs, then code only for gaps. + +--- + +`Workflow` + + + + + +## Quick Links + +- [Model Training with Agents](/using-skill) describes how to work with the `nemotron-customize` skill for multi-stage training plans and YAML-first deliverables. + +- [Getting Started](/getting-started) describes how to verify the CLI and run a tiny configuration. + +- [Execution through NeMo Run](/../nemo_runspec/nemo-run) describes profiles, attached and detached runs, and clusters. + +- [Nemotron CLI Overview](/../nemotron/cli) describes how the wider CLI relates to configuration and overrides. diff --git a/docs/train-models/reference/cli-reference.md b/docs/fern/pages-vnightly/train-models/reference/cli-reference.mdx similarity index 73% rename from docs/train-models/reference/cli-reference.md rename to docs/fern/pages-vnightly/train-models/reference/cli-reference.mdx index 18127fbea..9b48e15fa 100644 --- a/docs/train-models/reference/cli-reference.md +++ b/docs/fern/pages-vnightly/train-models/reference/cli-reference.mdx @@ -1,78 +1,74 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the nemotron steps subcommand group." -topics: ["Training", "Reference", "CLI"] -tags: ["Reference", "CLI", "Command-Line", "Steps"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "Nemotron Steps CLI Reference" +slug: "train-models/reference/cli-reference.html" +description: "This page documents the nemotron steps command group, the entry point for discovering, inspecting, and running every supervised fine-tuning (SFT), parameter-efficient fine-tuning (PEFT), reinforcement" --- -# Nemotron Steps CLI Reference - This page documents the `nemotron steps` command group, the entry point for discovering, inspecting, and running every supervised fine-tuning (SFT), parameter-efficient fine-tuning (PEFT), reinforcement learning (RL), and optimization step packaged under `src/nemotron/steps/`. The command group is registered by the Nemotron CLI and exposes three subcommands: - `nemotron steps list` enumerates discovered steps with optional filters. + - `nemotron steps show ` prints the manifest, runspec, and parameters for one step. + - `nemotron steps run ` compiles a configuration, selects an executor, and submits a job. Each subcommand resolves a step by its identifier, such as `sft/automodel` or `rl/nemo_rl/dpo`. -The [Step Catalog](step-catalog.md) lists every identifier. +The [Step Catalog](/step-catalog) lists every identifier. ## Syntax The `run` subcommand accepts a step identifier, a configuration name or path, an execution mode, and any number of trailing overrides: ```bash -nemotron steps run \ - [-c ] \ - [-r | -b ] \ +nemotron steps run \ \ + [-c \] \ + [-r \ | -b \] \ [-d] \ [--force-squash] \ - [...] \ - [...] + [\...] \ + [\...] ``` The `list` and `show` subcommands take only options and an optional step identifier: ```bash -nemotron steps list [--category ] [--consumes ] [--produces ] [--json] +nemotron steps list [--category \] [--consumes \] [--produces \] [--json] -nemotron steps show [--json] +nemotron steps show \ [--json] ``` ## Required Arguments -```{option} +### `` The step identifier under `src/nemotron/steps/`, such as `sft/automodel`, `peft/megatron_bridge`, `rl/nemo_rl/dpo`, or `optimize/modelopt/quantize`. This argument is positional and required for `nemotron steps run` and `nemotron steps show`. Example: `nemotron steps run sft/automodel` -``` ## Optional Arguments The following options apply to `nemotron steps run`. Pass them between the subcommand and any trailing overrides. -```{option} -c, --config +--- + +### `-c, --config ` The configuration to compile for the run. Bare names resolve to `config/.yaml` inside the step directory. A relative or absolute path resolves directly to that file. -Default: the configuration declared as `[config] default` in the step's runspec, typically `default`. +Default: the configuration declared as `[config] default` in the step’s runspec, typically `default`. Example: `-c tiny` resolves to `src/nemotron/steps/sft/automodel/config/tiny.yaml`. -``` -```{option} -r, --run +--- + +### `-r, --run ` The environment profile to attach to for synchronous execution. The profile name must match a top-level `[]` table in the active `env.toml` file. @@ -81,9 +77,10 @@ The CLI streams logs to your terminal until the job finishes. This option is mutually exclusive with `--batch`. Example: `-r lepton_sft_automodel` -``` -```{option} -b, --batch +--- + +### `-b, --batch ` The environment profile to submit to for detached execution. The profile name must match a top-level `[]` table in the active `env.toml` file. @@ -92,86 +89,102 @@ The CLI returns once the job is submitted. This option is mutually exclusive with `--run`. Example: `-b slurm_prod` -``` -```{option} -d, --dry-run +--- + +### `-d, --dry-run` Compile and print the merged configuration as a rich table, then exit without submitting the job. Use this option to validate overrides before you commit GPU time. Default: disabled. -``` -```{option} --force-squash +--- + +### `--force-squash` Force re-creation of the squashed container image used by remote executors even when a cached image already exists. Use this option after you change the container image referenced in your environment profile. Default: disabled. -``` The `list` subcommand has its own option set. -```{option} --category +--- + +### `--category ` Restrict the output to one step category, such as `sft`, `peft`, `rl`, or `optimize`. Example: `--category sft` -``` -```{option} --consumes +--- + +### `--consumes ` Restrict the output to steps that declare a `[[consumes]]` entry of the given artifact type, such as `training_jsonl`, `packed_parquet`, `checkpoint_hf`, or `checkpoint_megatron`. Example: `--consumes training_jsonl` -``` -```{option} --produces +--- + +### `--produces ` Restrict the output to steps that declare a `[[produces]]` entry of the given artifact type. Example: `--produces checkpoint_megatron` -``` -```{option} --json +--- + +### `--json` Emit machine-readable JSON instead of the human-formatted table. Use this option from agents or shell pipelines. Default: disabled. -``` ## Configuration Overrides Any token after the options that contains an equals sign and does not start with a hyphen is treated as a *dotlist override* and merged into the compiled configuration. -Any other token is preserved as a *passthrough argument* for the step's underlying script. +Any other token is preserved as a *passthrough argument* for the step’s underlying script. The split is performed by `nemo_runspec.cli_context.split_unknown_args`. -```{option} .= +--- + +### `=` + +```python +.= +``` A dotlist override that sets a nested key in the compiled YAML configuration. Use dotted paths to reach nested structures, the same way OmegaConf interprets them. Examples: + - `step_scheduler.max_steps=10` + - `model.pretrained_model_name_or_path=mistralai/Mistral-7B-Instruct-v0.3` + - `args.export_quant_cfg=fp8` -``` -```{option} +--- + +### `` -Any token that does not match a known option and does not contain an equals sign is forwarded verbatim to the step's underlying script. +Any token that does not match a known option and does not contain an equals sign is forwarded verbatim to the step’s underlying script. The script applies the token only when its stripped name, with dashes converted to underscores, matches a top-level field in the compiled configuration. Tokens that do not map to a top-level field are silently ignored, so most parameters are set through dotlist overrides instead. -``` ## Configuration Resolution The CLI resolves `--config` in the following order: 1. If the value is an absolute or relative file path that exists, the CLI loads that file. + 2. Otherwise the CLI treats the value as a bare name and looks for `config/.yaml` inside the step directory. -3. If `--config` is omitted, the CLI uses the runspec default declared in the step's `step.py`. + +3. If `--config` is omitted, the CLI uses the runspec default declared in the step’s `step.py`. Each step ships at minimum a `config/default.yaml` file for production-shape runs and a `config/tiny.yaml` file for short validation. Some steps ship additional variants, such as `config/fp8.yaml` for `optimize/modelopt/quantize` and `config/nemo_gym.yaml` for `rl/nemo_rl/rlvr`. @@ -183,12 +196,13 @@ The `--run` and `--batch` options select a profile from an `env.toml` file. The file is found by the following rules: 1. If the `NEMOTRON_ENV_FILE` environment variable is set, the CLI uses that path. + 2. Otherwise the CLI walks upward from the current directory until it finds a file named `env.toml`, stopping at the project root that contains `pyproject.toml`. Each profile is a top-level TOML table. -The table's `executor` field selects `local`, `slurm`, or `lepton` execution. +The table’s `executor` field selects `local`, `slurm`, or `lepton` execution. The remaining fields configure the container image, mounts, resources, and environment variables for that executor. -Refer to [Environment and Executors](../how-to/env-and-executors.md) for the full schema. +Refer to [Environment and Executors](/../how-to/env-and-executors) for the full schema. If you omit both `--run` and `--batch`, the CLI submits the step on the local backend. Remote execution requires `-r` or `-b` together with a profile that exists in the active `env.toml` file. @@ -229,46 +243,51 @@ $ nemotron steps show sft/automodel --json ## Per-Category References -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} Supervised Fine-Tuning Steps -:link: sft/index -:link-type: doc + + The `sft/automodel` and `sft/megatron_bridge` references. -+++ -{bdg-success}`reference` -::: -:::{grid-item-card} Parameter-Efficient Fine-Tuning Steps -:link: peft/index -:link-type: doc +--- + +reference + + + + The `peft/automodel` and `peft/megatron_bridge` references. -+++ -{bdg-success}`reference` -::: -:::{grid-item-card} Reinforcement Learning Steps -:link: rl/index -:link-type: doc +--- + +reference + + + + The `rl/nemo_rl/dpo`, `rl/nemo_rl/rlvr`, and `rl/nemo_rl/rlhf` references. -+++ -{bdg-success}`reference` -::: -:::{grid-item-card} Optimization Steps -:link: optimize/index -:link-type: doc +--- + +reference + + + + The `optimize/modelopt/quantize`, `optimize/modelopt/prune`, and `optimize/modelopt/distill` references. -+++ -{bdg-success}`reference` -::: -:::: +--- + +reference + + + + ## Related Documentation -- [Step Catalog](step-catalog.md) lists every step identifier and its manifest path. -- [Configuration Conventions](config-conventions.md) explains the per-step `config/` layout, dotlist override rules, and the relationship to environment profiles. -- [Environment and Executors](../how-to/env-and-executors.md) explains the `env.toml` schema and profile selection. -- [Execution Through NeMo Run](../../nemo_runspec/nemo-run.md) explains attached and detached execution, image squashing, and remote job directories. +- [Step Catalog](/step-catalog) lists every step identifier and its manifest path. + +- [Configuration Conventions](/config-conventions) explains the per-step `config/` layout, dotlist override rules, and the relationship to environment profiles. + +- [Environment and Executors](/../how-to/env-and-executors) explains the `env.toml` schema and profile selection. + +- [Execution Through NeMo Run](/../../nemo_runspec/nemo-run) explains attached and detached execution, image squashing, and remote job directories. diff --git a/docs/train-models/reference/config-conventions.md b/docs/fern/pages-vnightly/train-models/reference/config-conventions.mdx similarity index 52% rename from docs/train-models/reference/config-conventions.md rename to docs/fern/pages-vnightly/train-models/reference/config-conventions.mdx index f6951b214..7b25d7915 100644 --- a/docs/train-models/reference/config-conventions.md +++ b/docs/fern/pages-vnightly/train-models/reference/config-conventions.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Per-step configuration conventions for Nemotron training steps." -topics: ["Training", "Reference", "Configuration"] -tags: ["Reference", "Configuration", "YAML", "Overrides"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "Configuration Conventions" +slug: "train-models/reference/config-conventions.html" +description: "This page describes the per-step configuration layout, the rules the CLI uses to resolve a configuration name, and the rules it uses to merge command-line overrides. The conventions apply to every ste" --- -# Configuration Conventions - This page describes the per-step configuration layout, the rules the CLI uses to resolve a configuration name, and the rules it uses to merge command-line overrides. The conventions apply to every step registered under `src/nemotron/steps/`. @@ -24,11 +16,11 @@ For a step directory `src/nemotron/steps///`, expect the followi | File | Purpose | | --- | --- | -| `step.toml` | Manifest with the identifier, human-readable title, tags, `[[consumes]]` blocks, `[[produces]]` blocks, `[[parameters]]` blocks, optional `[[strategies]]`, optional `[[errors]]`, and optional `[[models]]` blocks. | -| `step.py` | Entry script that the CLI invokes after configuration compilation. The script also declares the NeMo Run specification. | -| `config/default.yaml` | Primary configuration tuned for production-shape runs. | -| `config/tiny.yaml` | Reduced configuration for short validation runs. | -| `config/.yaml` | Optional configuration variants. Examples include `config/fp8.yaml` and `config/nvfp4.yaml` for `optimize/modelopt/quantize`, and `config/nemo_gym.yaml` for `rl/nemo_rl/rlvr`. | +| step.toml | Manifest with the identifier, human-readable title, tags, [[consumes]] blocks, [[produces]] blocks, [[parameters]] blocks, optional [[strategies]], optional [[errors]], and optional [[models]] blocks. | +| step.py | Entry script that the CLI invokes after configuration compilation. The script also declares the NeMo Run specification. | +| config/default.yaml | Primary configuration tuned for production-shape runs. | +| config/tiny.yaml | Reduced configuration for short validation runs. | +| config/<variant>.yaml | Optional configuration variants. Examples include config/fp8.yaml and config/nvfp4.yaml for optimize/modelopt/quantize, and config/nemo_gym.yaml for rl/nemo_rl/rlvr. | The per-step reference pages list every configuration file that the step ships. @@ -37,8 +29,10 @@ The per-step reference pages list every configuration file that the step ships. The CLI resolves the `-c` and `--config` value in the following order. 1. When the value is an absolute or relative file path that exists on disk, the CLI loads that file directly. + 2. Otherwise the CLI treats the value as a bare name and looks for `config/.yaml` inside the step directory. -3. When the value is omitted, the CLI uses the runspec default declared in the step's `step.py`, typically `default`. + +3. When the value is omitted, the CLI uses the runspec default declared in the step’s `step.py`, typically `default`. The following command resolves the bare name `tiny` to `src/nemotron/steps/sft/automodel/config/tiny.yaml`: @@ -64,37 +58,40 @@ $ nemotron steps run sft/automodel -c default \ ``` The override syntax follows the rules in `nemo_runspec.cli_context.split_unknown_args`. -Refer to the [Nemotron Steps CLI Reference](cli-reference.md) for the full syntax and additional examples. +Refer to the [Nemotron Steps CLI Reference](/cli-reference) for the full syntax and additional examples. ## Passthrough Arguments -Any trailing token that does not match a known option and does not contain an equals sign is preserved as a *passthrough argument* and forwarded to the step's entry script. +Any trailing token that does not match a known option and does not contain an equals sign is preserved as a *passthrough argument* and forwarded to the step’s entry script. The script applies the token only when its stripped name, with dashes converted to underscores, matches a top-level field in the compiled configuration. Tokens that do not map to a top-level field are silently ignored, so most parameters are better set through dotlist overrides. ## Environment Variables in Configurations -Configuration files use the OmegaConf `${oc.env:NAME,default}` resolver to read environment variables at compile time. +Configuration files use the OmegaConf `$\{oc.env:NAME,default\}` resolver to read environment variables at compile time. The default configurations rely on the following environment variables. | Variable | Used By | Purpose | | --- | --- | --- | -| `SFT_OUTPUT_DIR` | `sft/automodel` | Destination directory for SFT checkpoints. Defaults to `./output/automodel-tiny`. | -| `SFT_PACKED_DIR` | `sft/megatron_bridge`, `peft/megatron_bridge` | Source directory for packed Parquet shards produced by `data_prep/sft_packing`. | -| `RL_POLICY_MODEL` | `rl/nemo_rl/dpo`, `rl/nemo_rl/rlhf`, `rl/nemo_rl/rlvr` | Hugging Face identifier or local path for the policy. Defaults to `meta-llama/Llama-3.2-1B-Instruct`. | -| `WANDB_NAME` | All training steps | Weights and Biases run name. | -| `NEMO_RUN_DIR` | `optimize/modelopt/*` | Output root used to derive default destination paths. | +| SFT_OUTPUT_DIR | sft/automodel | Destination directory for SFT checkpoints. Defaults to ./output/automodel-tiny. | +| SFT_PACKED_DIR | sft/megatron_bridge, peft/megatron_bridge | Source directory for packed Parquet shards produced by data_prep/sft_packing. | +| RL_POLICY_MODEL | rl/nemo_rl/dpo, rl/nemo_rl/rlhf, rl/nemo_rl/rlvr | Hugging Face identifier or local path for the policy. Defaults to meta-llama/Llama-3.2-1B-Instruct. | +| WANDB_NAME | All training steps | Weights and Biases run name. | +| NEMO_RUN_DIR | optimize/modelopt/* | Output root used to derive default destination paths. | Set these variables in your shell, in the environment profile, or in an executor `env` block, depending on whether the run is local or remote. ## Environment Profiles Per-cluster environment variables, container images, and startup commands live in `env.toml` at the repository root, not in per-step YAML files. -The active profile is selected with `--run` or `--batch`, and the file is found by the rules described in the [Nemotron Steps CLI Reference](cli-reference.md). +The active profile is selected with `--run` or `--batch`, and the file is found by the rules described in the [Nemotron Steps CLI Reference](/cli-reference). ## Related Documentation -- [Getting Started With Training Steps](../getting-started.md) walks through a first run. -- [Nemotron Steps CLI Reference](cli-reference.md) covers `list`, `show`, and `run` syntax. -- [Step Catalog](step-catalog.md) lists every step identifier and its manifest path. -- [Execution Through NeMo Run](../../nemo_runspec/nemo-run.md) explains profiles, attached and detached execution, and clusters. +- [Getting Started With Training Steps](/../getting-started) walks through a first run. + +- [Nemotron Steps CLI Reference](/cli-reference) covers `list`, `show`, and `run` syntax. + +- [Step Catalog](/step-catalog) lists every step identifier and its manifest path. + +- [Execution Through NeMo Run](/../../nemo_runspec/nemo-run) explains profiles, attached and detached execution, and clusters. diff --git a/docs/train-models/reference/convert/hf-to-megatron.md b/docs/fern/pages-vnightly/train-models/reference/convert/hf-to-megatron.mdx similarity index 70% rename from docs/train-models/reference/convert/hf-to-megatron.md rename to docs/fern/pages-vnightly/train-models/reference/convert/hf-to-megatron.mdx index ea464795b..08ab89bad 100644 --- a/docs/train-models/reference/convert/hf-to-megatron.md +++ b/docs/fern/pages-vnightly/train-models/reference/convert/hf-to-megatron.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the convert/hf_to_megatron step." -topics: ["Training", "Reference", "Checkpoint Conversion"] -tags: ["Reference", "CLI", "Steps", "Hugging Face", "Megatron"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "convert/hf_to_megatron" +slug: "train-models/reference/convert/hf-to-megatron.html" +description: "This step converts a Hugging Face checkpoint or model id into Megatron distributed checkpoint layout. Use it when a downstream Megatron-Bridge step expects checkpoint_megatron but the upstream artifac" --- -# convert/hf_to_megatron - This step converts a Hugging Face checkpoint or model id into Megatron distributed checkpoint layout. Use it when a downstream Megatron-Bridge step expects `checkpoint_megatron` but the upstream artifact is `checkpoint_hf`. @@ -19,13 +11,13 @@ Use it when a downstream Megatron-Bridge step expects `checkpoint_megatron` but ```bash nemotron steps run convert/hf_to_megatron \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ - [...] + [\...] ``` -Refer to the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -36,48 +28,51 @@ The default source model is `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-Base-BF16`, a | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `checkpoint_hf` | Yes | A clean Hugging Face checkpoint directory or model id. | -| Produces | `checkpoint_megatron` | - | A Megatron distributed checkpoint directory. | +| Consumes | checkpoint_hf | Yes | A clean Hugging Face checkpoint directory or model id. | +| Produces | checkpoint_megatron | - | A Megatron distributed checkpoint directory. | ## Parameters -```{option} hf_model_id= +### `hf_model_id=` Hugging Face model id or local checkpoint path to import. Use a clean model directory, not trainer logs, optimizer state, or adapter-only output. Example: `hf_model_id=nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-Base-BF16` -``` -```{option} megatron_path= +--- + +### `megatron_path=` Output directory for the Megatron distributed checkpoint. Keep this path separate from the Hugging Face source path. Example: `megatron_path=/lustre/output/convert/nano3-megatron` -``` -```{option} dtype= +--- + +### `dtype=` Torch dtype used during import. Typical NVIDIA Nemotron checkpoints use `bfloat16`. Choices: `bfloat16`, `float16`, `float32`. Default: `bfloat16`. -``` -```{option} device_map= +--- + +### `device_map=` Optional Transformers `device_map` forwarded during Hugging Face model loading, such as `auto` or `cuda:0`. Leave unset unless the conversion host requires explicit placement. -``` -```{option} trust_remote_code= +--- + +### `trust_remote_code=` Whether to trust Hugging Face custom model code when AutoBridge loads the source model configuration. Default: `true`. -``` ## Command Examples @@ -100,11 +95,15 @@ $ nemotron steps run convert/hf_to_megatron -c default --batch lepton_convert_mo ## Recovery Notes - If the source came from LoRA training, merge the adapter into the original base first with `convert/merge_lora`. + - If tokenizer or model config files are missing, use the original Hugging Face model id as `hf_model_id`. + - If conversion fails, retry into a fresh `megatron_path` instead of reusing a partially written directory. ## Related Documentation -- [Convert Checkpoints Between Training Steps](../../how-to/convert-checkpoints.md) -- [convert/merge_lora](merge-lora.md) +- [Convert Checkpoints Between Training Steps](/../../how-to/convert-checkpoints) + +- [convert/merge_lora](/merge-lora) + - [Megatron-Bridge Documentation](https://docs.nvidia.com/nemo/megatron-bridge/latest/) diff --git a/docs/fern/pages-vnightly/train-models/reference/convert/index.mdx b/docs/fern/pages-vnightly/train-models/reference/convert/index.mdx new file mode 100644 index 000000000..0603c191b --- /dev/null +++ b/docs/fern/pages-vnightly/train-models/reference/convert/index.mdx @@ -0,0 +1,48 @@ +--- +title: "Checkpoint Conversion Steps" +slug: "train-models/reference/convert/index.html" +description: "This section documents the conversion steps registered under src/nemotron/steps/convert/. Use these steps to bridge checkpoint layouts between Hugging Face, Megatron distributed checkpoints, and LoRA " +--- + +This section documents the conversion steps registered under `src/nemotron/steps/convert/`. +Use these steps to bridge checkpoint layouts between Hugging Face, Megatron distributed checkpoints, and LoRA adapter outputs. + +## Steps + + + +Import a Hugging Face checkpoint or model id into Megatron distributed checkpoint layout. + +--- + +reference + + + + +Export a Megatron distributed checkpoint iteration into Hugging Face safetensors layout. + +--- + +reference + + + + +Merge a LoRA adapter with its original base checkpoint to produce a standalone checkpoint. + +--- + +reference + + + + + +## Related Documentation + +- [Convert Checkpoints Between Training Steps](/../../how-to/convert-checkpoints) + +- [Data and Checkpoint Formats](/../../how-to/data-and-checkpoint-formats) + +- [Step Catalog](/../step-catalog) diff --git a/docs/train-models/reference/convert/megatron-to-hf.md b/docs/fern/pages-vnightly/train-models/reference/convert/megatron-to-hf.mdx similarity index 68% rename from docs/train-models/reference/convert/megatron-to-hf.md rename to docs/fern/pages-vnightly/train-models/reference/convert/megatron-to-hf.mdx index 3f83dcfbe..806d79cbe 100644 --- a/docs/train-models/reference/convert/megatron-to-hf.md +++ b/docs/fern/pages-vnightly/train-models/reference/convert/megatron-to-hf.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the convert/megatron_to_hf step." -topics: ["Training", "Reference", "Checkpoint Conversion"] -tags: ["Reference", "CLI", "Steps", "Megatron", "Hugging Face"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "convert/megatron_to_hf" +slug: "train-models/reference/convert/megatron-to-hf.html" +description: "This step converts a Megatron distributed checkpoint into Hugging Face safetensors layout. Use it when a downstream Hugging Face-native consumer expects checkpoint_hf but the upstream artifact is chec" --- -# convert/megatron_to_hf - This step converts a Megatron distributed checkpoint into Hugging Face safetensors layout. Use it when a downstream Hugging Face-native consumer expects `checkpoint_hf` but the upstream artifact is `checkpoint_megatron`. @@ -19,13 +11,13 @@ Use it when a downstream Hugging Face-native consumer expects `checkpoint_hf` bu ```bash nemotron steps run convert/megatron_to_hf \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ - [...] + [\...] ``` -Refer to the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -36,53 +28,57 @@ The default `hf_model_id` is `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-Base-BF16`, | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `checkpoint_megatron` | Yes | A specific Megatron checkpoint directory, normally an `iter_*` directory. | -| Produces | `checkpoint_hf` | - | A Hugging Face safetensors checkpoint directory. | +| Consumes | checkpoint_megatron | Yes | A specific Megatron checkpoint directory, normally an iter_* directory. | +| Produces | checkpoint_hf | - | A Hugging Face safetensors checkpoint directory. | ## Parameters -```{option} megatron_path= +### `megatron_path=` Specific Megatron checkpoint directory to export. Point this at the concrete checkpoint iteration, not the parent training run folder. Example: `megatron_path=/lustre/runs/sft/checkpoints/iter_0000100` -``` -```{option} hf_model_id= +--- + +### `hf_model_id=` Hugging Face model id or config source used by AutoBridge to reconstruct the Hugging Face architecture and tokenizer expectations. Example: `hf_model_id=nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-Base-BF16` -``` -```{option} hf_path= +--- + +### `hf_path=` Output directory for the exported Hugging Face safetensors checkpoint. Example: `hf_path=/lustre/output/convert/sft-hf` -``` -```{option} trust_remote_code= +--- + +### `trust_remote_code=` Whether to trust custom Hugging Face model code while reconstructing the export target. Default: `true`. -``` -```{option} show_progress= +--- + +### `show_progress=` Whether to show Megatron-Bridge export progress output. Default: `true`. -``` -```{option} strict= +--- + +### `strict=` Whether Megatron-Bridge should require source and target checkpoint keys to match strictly. Default: `true`. -``` ## Command Examples @@ -107,11 +103,15 @@ $ nemotron steps run convert/megatron_to_hf -c default --batch lepton_convert_mo ## Recovery Notes - If export fails because the checkpoint is incomplete, wait for async checkpoint save to finish and retry from a complete `iter_*` directory. + - If tokenizer or config reconstruction fails, set `hf_model_id` to the original base model or config source. + - Validate the exported Hugging Face checkpoint with a small generation or evaluation job before deployment. ## Related Documentation -- [Convert Checkpoints Between Training Steps](../../how-to/convert-checkpoints.md) -- [Data and Checkpoint Formats](../../how-to/data-and-checkpoint-formats.md) +- [Convert Checkpoints Between Training Steps](/../../how-to/convert-checkpoints) + +- [Data and Checkpoint Formats](/../../how-to/data-and-checkpoint-formats) + - [Megatron-Bridge Documentation](https://docs.nvidia.com/nemo/megatron-bridge/latest/) diff --git a/docs/train-models/reference/convert/merge-lora.md b/docs/fern/pages-vnightly/train-models/reference/convert/merge-lora.mdx similarity index 65% rename from docs/train-models/reference/convert/merge-lora.md rename to docs/fern/pages-vnightly/train-models/reference/convert/merge-lora.mdx index 6d325bd60..8c9f9ddf5 100644 --- a/docs/train-models/reference/convert/merge-lora.md +++ b/docs/fern/pages-vnightly/train-models/reference/convert/merge-lora.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the convert/merge_lora step." -topics: ["Training", "Reference", "Checkpoint Conversion", "LoRA"] -tags: ["Reference", "CLI", "Steps", "PEFT", "LoRA", "Merge"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "convert/merge_lora" +slug: "train-models/reference/convert/merge-lora.html" +description: "This step merges a LoRA adapter with its original base checkpoint. Use it when a downstream consumer needs a standalone checkpoint instead of an adapter plus base model pair." --- -# convert/merge_lora - This step merges a LoRA adapter with its original base checkpoint. Use it when a downstream consumer needs a standalone checkpoint instead of an adapter plus base model pair. @@ -19,13 +11,13 @@ Use it when a downstream consumer needs a standalone checkpoint instead of an ad ```bash nemotron steps run convert/merge_lora \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ - [...] + [\...] ``` -Refer to the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -38,83 +30,92 @@ Otherwise, `auto` selects the Hugging Face PEFT merge path. | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `checkpoint_lora` | Yes | LoRA adapter weights from a PEFT step. | -| Consumes | `checkpoint_hf` | Yes for `hf_peft` | Original Hugging Face base checkpoint or model/config source. | -| Consumes | `checkpoint_megatron` | Required for `megatron_bridge` | Original dense Megatron checkpoint for Megatron-Bridge adapter merge. | -| Produces | `checkpoint_hf` | - | Merged standalone Hugging Face checkpoint. | -| Produces | `checkpoint_megatron` | Optional | Merged Megatron checkpoint when `backend=megatron_bridge`. | +| Consumes | checkpoint_lora | Yes | LoRA adapter weights from a PEFT step. | +| Consumes | checkpoint_hf | Yes for hf_peft | Original Hugging Face base checkpoint or model/config source. | +| Consumes | checkpoint_megatron | Required for megatron_bridge | Original dense Megatron checkpoint for Megatron-Bridge adapter merge. | +| Produces | checkpoint_hf | - | Merged standalone Hugging Face checkpoint. | +| Produces | checkpoint_megatron | Optional | Merged Megatron checkpoint when backend=megatron_bridge. | ## Parameters -```{option} backend= +### `backend=` Adapter merge backend. `auto` selects `megatron_bridge` when `base_megatron_path` is set, otherwise `hf_peft`. Default: `auto`. -``` -```{option} lora_checkpoint= +--- + +### `lora_checkpoint=` Adapter checkpoint path produced by a PEFT step. -``` -```{option} base_hf_path= +--- + +### `base_hf_path=` Original Hugging Face base checkpoint for `backend=hf_peft`, or Hugging Face config/model source for `backend=megatron_bridge`. Do not substitute a different base. -``` -```{option} base_megatron_path= +--- + +### `base_megatron_path=` Original dense Megatron checkpoint for `backend=megatron_bridge`. Use the base checkpoint that the adapter was trained against. -``` -```{option} hf_model_id= +--- + +### `hf_model_id=` Hugging Face model id or path used to reconstruct architecture when exporting a Megatron-Bridge merge to Hugging Face layout. Example: `hf_model_id=nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-Base-BF16` -``` -```{option} output_hf_path= +--- + +### `output_hf_path=` Directory for the merged standalone Hugging Face checkpoint. -``` -```{option} output_megatron_path= +--- + +### `output_megatron_path=` Directory for the merged Megatron checkpoint when `backend=megatron_bridge`. -``` -```{option} cpu= +--- + +### `cpu=` Merge on CPU when GPU memory is tight or when running outside a training container. Default: `true`. -``` -```{option} tp= +--- + +### `tp=` Tensor parallel size for Megatron-Bridge merge. Default: `1`. -``` -```{option} pp= +--- + +### `pp=` Pipeline parallel size for Megatron-Bridge merge. Default: `1`. -``` -```{option} ep= +--- + +### `ep=` Expert parallel size for Megatron-Bridge merge. Default: `1`. -``` ## Command Examples @@ -143,11 +144,15 @@ $ nemotron steps run convert/merge_lora -c default --batch lepton_convert_model ## Recovery Notes - If scores differ after merge, evaluate the adapter-loaded model and the merged checkpoint separately; do not assume they are identical. + - If merge fails with missing keys or shape mismatch, verify the adapter was trained against the same base checkpoint. + - Write outputs to a fresh directory so a failed merge cannot overwrite the base or adapter. ## Related Documentation -- [Choose a PEFT Backend](../../how-to/choose-peft-backend.md) -- [convert/hf_to_megatron](hf-to-megatron.md) +- [Choose a PEFT Backend](/../../how-to/choose-peft-backend) + +- [convert/hf_to_megatron](/hf-to-megatron) + - [PEFT documentation](https://github.com/huggingface/peft) diff --git a/docs/train-models/reference/env-profile-generator.md b/docs/fern/pages-vnightly/train-models/reference/env-profile-generator.mdx similarity index 67% rename from docs/train-models/reference/env-profile-generator.md rename to docs/fern/pages-vnightly/train-models/reference/env-profile-generator.mdx index 0a0e67746..9e63ebb10 100644 --- a/docs/train-models/reference/env-profile-generator.md +++ b/docs/fern/pages-vnightly/train-models/reference/env-profile-generator.mdx @@ -1,29 +1,21 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the env/env_toml step that generates an environment profile file for every Nemotron training step." -topics: ["Training", "Reference", "Environment Profiles"] -tags: ["Reference", "CLI", "Environment Profile", "Lepton", "Slurm"] -content: - type: "Reference" - difficulty: "Intermediate" - audience: ["ML Engineer", "Developer"] +title: "Env Profile Generator" +slug: "train-models/reference/env-profile-generator.html" +description: "The env/env_toml step generates the environment profile file that every other Nemotron training step reads when it submits a job to a cluster. The generator emits a single Tom’s Obvious Minimal Langua" --- -# Env Profile Generator - The `env/env_toml` step generates the *environment profile* file that every other Nemotron training step reads when it submits a job to a cluster. -The generator emits a single Tom's Obvious Minimal Language (TOML) file with one named profile per step, including data preparation, supervised fine-tuning (SFT), parameter-efficient fine-tuning (PEFT), reinforcement learning (RL), pretraining, optimization, evaluation, synthetic data generation, translation, and curation profiles. +The generator emits a single Tom’s Obvious Minimal Language (TOML) file with one named profile per step, including data preparation, supervised fine-tuning (SFT), parameter-efficient fine-tuning (PEFT), reinforcement learning (RL), pretraining, optimization, evaluation, synthetic data generation, translation, and curation profiles. You typically run this step once, before you submit your first training job to a cluster, and you re-run it only when site values such as the node group, container image, or shared mount path change. ## Syntax ```bash -nemotron steps run env/env_toml -c [= ...] +nemotron steps run env/env_toml -c \ [\=\ ...] ``` The CLI accepts the same dotlist override syntax used by every other step. -Refer to the [Nemotron Steps CLI Reference](cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/cli-reference) for the shared flag set. ## Configuration Files @@ -31,9 +23,9 @@ The step ships three configuration files under `src/nemotron/steps/env/env_toml/ | File | Cluster Shape | | --- | --- | -| `lepton.yaml` | Targets a DGX Cloud Lepton workspace with node-group, fileset mount, and resource-shape placeholders that you override at the command line. | -| `slurm.yaml` | Targets a Slurm cluster reached over SSH, with host, account, partition, and Lustre mount placeholders. | -| `dgxcloud.yaml` | Targets a DGX Cloud Run:AI installation with project, department, and image-pull credential placeholders. | +| lepton.yaml | Targets a DGX Cloud Lepton workspace with node-group, fileset mount, and resource-shape placeholders that you override at the command line. | +| slurm.yaml | Targets a Slurm cluster reached over SSH, with host, account, partition, and Lustre mount placeholders. | +| dgxcloud.yaml | Targets a DGX Cloud Run:AI installation with project, department, and image-pull credential placeholders. | The default configuration is `lepton`. @@ -44,11 +36,11 @@ It produces one `env_toml` artifact, the generated environment profile file. The default `output_path` differs by configuration. -| Configuration | Default `output_path` | +| Configuration | Default output_path | | --- | --- | -| `lepton` | `env.lepton.toml` | -| `slurm` | `env.slurm.toml` | -| `dgxcloud` | `env.dgxcloud.toml` | +| lepton | env.lepton.toml | +| slurm | env.slurm.toml | +| dgxcloud | env.dgxcloud.toml | Override `output_path` to write the file somewhere other than the repository root, for example a per-cluster directory under your quality assurance workspace. @@ -57,7 +49,7 @@ Override `output_path` to write the file somewhere other than the repository roo The step exposes three top-level parameters. Pass each one as a dotlist override after the configuration name. -```{option} output_path= +### `output_path=` Where to write the generated environment profile file. A relative path is resolved against the current working directory. @@ -66,9 +58,10 @@ Keep this value at the repository root for normal use so the CLI can discover th Default: `env.lepton.toml`, `env.slurm.toml`, or `env.dgxcloud.toml`, taken from the selected configuration. Example: `output_path=env.toml` -``` -```{option} force= +--- + +### `force=` Whether to overwrite `output_path` when a file already exists at that location. Set this value to `true` when you re-run the generator with new site overrides and you want the existing file replaced. @@ -77,9 +70,14 @@ Leave the value at the default when you want the existing file preserved so a st Default: `false`. Example: `force=true` -``` -```{option} sections..= +--- + +### `=` + +```python +sections..= +``` A dotlist override that reaches into one of the named profiles emitted by the generator and replaces a specific key. Use this pattern to set site-specific values such as the node group, container image, mount path, or per-profile environment variables without editing the shipped configuration file. @@ -90,9 +88,10 @@ Nested keys, such as a single environment variable, append additional dot segmen Examples: - `sections.lepton_base.node_group=` replaces the node group on the base Lepton profile. + - `sections.lepton_base.env_vars.WANDB_PROJECT=` sets the Weights and Biases project name for every profile that inherits from `lepton_base`. + - `sections.slurm_base.account=` sets the Slurm account on the base Slurm profile. -``` The shipped configurations declare additional document-level keys such as `preamble` and `checks` that drive the generator itself. These keys behave identically to any other dotlist override, but most users only need the three parameters described above. @@ -113,10 +112,10 @@ Generate a Lepton environment profile with site-specific node-group and Weights $ nemotron steps run env/env_toml -c lepton \ output_path=env.lepton.toml \ force=true \ - sections.lepton_base.node_group= \ - sections.lepton_base.env_vars.WANDB_PROJECT= \ - sections.lepton_base.env_vars.WANDB_ENTITY= \ - sections.lepton_base.env_vars.WANDB_NAME= + sections.lepton_base.node_group=\ \ + sections.lepton_base.env_vars.WANDB_PROJECT=\ \ + sections.lepton_base.env_vars.WANDB_ENTITY=\ \ + sections.lepton_base.env_vars.WANDB_NAME=\ ``` Each `sections.lepton_base.*` override replaces the matching key on the `[lepton_base]` profile in the generated file. @@ -126,11 +125,14 @@ Every child profile that extends `lepton_base`, for example `lepton_sft_automode The generated file is a normal TOML document. You can hand-edit any profile after generation, for example to add a one-off mount path or to change a container image for a single profile. -When you need only a small slice of profiles or you want to start from a minimal hand-written file rather than the full set of canonical profiles, follow the manual template walkthrough in the [Quickstart](../getting-started.md). +When you need only a small slice of profiles or you want to start from a minimal hand-written file rather than the full set of canonical profiles, follow the manual template walkthrough in the [Quickstart](/../getting-started). ## Related Documentation -- [Quickstart](../getting-started.md) -- [Nemotron Steps CLI Reference](cli-reference.md) -- [Step Catalog](step-catalog.md) -- [Configuration Conventions](config-conventions.md) +- [Quickstart](/../getting-started) + +- [Nemotron Steps CLI Reference](/cli-reference) + +- [Step Catalog](/step-catalog) + +- [Configuration Conventions](/config-conventions) diff --git a/docs/fern/pages-vnightly/train-models/reference/index.mdx b/docs/fern/pages-vnightly/train-models/reference/index.mdx new file mode 100644 index 000000000..f25c06469 --- /dev/null +++ b/docs/fern/pages-vnightly/train-models/reference/index.mdx @@ -0,0 +1,107 @@ +--- +title: "Training Reference" +slug: "train-models/reference/index.html" +description: "This section provides lookup material for every supervised fine-tuning (SFT), parameter-efficient fine-tuning (PEFT), reinforcement learning (RL), and optimization step packaged under src/nemotron/ste" +--- + +This section provides lookup material for every supervised fine-tuning (SFT), parameter-efficient fine-tuning (PEFT), reinforcement learning (RL), and optimization step packaged under `src/nemotron/steps/`. +Use these pages to find the exact CLI syntax, configuration file layout, parameters, and configuration overrides for each step. + +## Reference Sections + + + +Shared command-line syntax, options, dotlist overrides, and passthrough arguments for the `nemotron steps` command group. + +--- + +lookup + + + + +The packaged `env/env_toml` step that generates the environment profile file every other training step consumes. + +--- + +setup + + + + +Every step identifier, manifest path, and per-step reference link. + +--- + +lookup + + + + +Per-step `config/` layout, CLI configuration resolution, dotlist override rules, and environment-variable expansion. + +--- + +lookup + + + + + +## Per-Category Step References + + + +The `sft/automodel` and `sft/megatron_bridge` references. + +--- + +reference + + + + +The `peft/automodel` and `peft/megatron_bridge` references. + +--- + +reference + + + + +The `rl/nemo_rl/dpo`, `rl/nemo_rl/rlvr`, and `rl/nemo_rl/rlhf` references. + +--- + +reference + + + + +The `optimize/modelopt/quantize`, `optimize/modelopt/prune`, and `optimize/modelopt/distill` references. + +--- + +reference + + + + +The `convert/hf_to_megatron`, `convert/megatron_to_hf`, and `convert/merge_lora` references. + +--- + +reference + + + + + +## Related Documentation + +- [Getting Started With Training Steps](/../getting-started) walks through a first run with the tiny configuration. + +- [Execution Through NeMo Run](/../../nemo_runspec/nemo-run) explains attached and detached execution, environment profiles, and remote job directories. + +- [How-To Guides](/../how-to/index) cover backend choice, data and checkpoint formats, and environment-and-executor setup. diff --git a/docs/train-models/reference/optimize/distill.md b/docs/fern/pages-vnightly/train-models/reference/optimize/distill.mdx similarity index 67% rename from docs/train-models/reference/optimize/distill.md rename to docs/fern/pages-vnightly/train-models/reference/optimize/distill.mdx index e088b02b8..7faede923 100644 --- a/docs/train-models/reference/optimize/distill.md +++ b/docs/fern/pages-vnightly/train-models/reference/optimize/distill.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the optimize/modelopt/distill step." -topics: ["Training", "Reference", "CLI", "Optimization", "Distillation"] -tags: ["Reference", "CLI", "Steps", "Optimization", "Distillation", "Teacher-Student", "ModelOpt", "Megatron-Bridge"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "optimize/modelopt/distill" +slug: "train-models/reference/optimize/distill.html" +description: "This step runs teacher-student distillation by using NVIDIA Model Optimizer through NVIDIA Megatron-Bridge. The step can run as a standalone training job, or as a quality-recovery pass after pruning o" --- -# optimize/modelopt/distill - This step runs teacher-student distillation by using NVIDIA Model Optimizer through NVIDIA Megatron-Bridge. The step can run as a standalone training job, or as a quality-recovery pass after pruning or quantization. Real-data runs consume Megatron `bin/idx` data produced by `data_prep/pretrain_prep`. @@ -21,15 +13,15 @@ The step produces a distilled Megatron distributed checkpoint. ```bash nemotron steps run optimize/modelopt/distill \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ [--force-squash] \ - [...] \ - [...] + [\...] \ + [\...] ``` -Refer to the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -37,8 +29,8 @@ The step ships two configuration files under `src/nemotron/steps/optimize/modelo | File | Purpose | | --- | --- | -| `default.yaml` | Generic teacher-student distillation configuration with `Qwen/Qwen3-8B` as the teacher and `Qwen/Qwen3-4B` as the student. | -| `tiny.yaml` | Short validation run that exercises the distillation pipeline with mock data. | +| default.yaml | Generic teacher-student distillation configuration with Qwen/Qwen3-8B as the teacher and Qwen/Qwen3-4B as the student. | +| tiny.yaml | Short validation run that exercises the distillation pipeline with mock data. | Pass the configuration name with `-c`: @@ -51,46 +43,66 @@ $ nemotron steps run optimize/modelopt/distill -c default | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `checkpoint_hf` | Yes | The teacher and student Hugging Face (HF) checkpoints. | -| Consumes | `binidx` | No | Optional real distillation data from `data_prep/pretrain_prep`. This input is unnecessary when `args.use_mock_data=true`. | -| Produces | `checkpoint_megatron` | — | The distilled Megatron distributed checkpoint. | +| Consumes | checkpoint_hf | Yes | The teacher and student Hugging Face (HF) checkpoints. | +| Consumes | binidx | No | Optional real distillation data from data_prep/pretrain_prep. This input is unnecessary when args.use_mock_data=true. | +| Produces | checkpoint_megatron | — | The distilled Megatron distributed checkpoint. | ## Step Parameters The manifest declares five distillation parameters. Pass them as dotlist overrides. -```{option} args.teacher_hf_path= +### `teacher_hf_path=` + +```python +args.teacher_hf_path= +``` The Hugging Face identifier or local path for the teacher checkpoint. Example: `args.teacher_hf_path=nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` -``` -```{option} args.student_hf_path= +--- + +### `student_hf_path=` + +```python +args.student_hf_path= +``` The Hugging Face identifier or local path for the student checkpoint. Example: `args.student_hf_path=Qwen/Qwen3-4B` -``` -```{option} args.data_paths= +--- + +### `data_paths=` + +```python +args.data_paths= +``` The Megatron data blend, expressed as the upstream command-line sequence in the form `[weight, prefix, weight, prefix, ...]`. Example: `args.data_paths='[0.5, /lustre/data/wiki, 0.5, /lustre/data/c4]'` -``` -```{option} args.use_mock_data= +--- + +### `use_mock_data=` + +```python +args.use_mock_data= +``` When set to `true`, the step runs a validation pass with mock data instead of real Megatron `bin/idx` data. Default: `false`. Example: `args.use_mock_data=true` -``` -```{option} extra_args= +--- + +### `extra_args=` Literal upstream arguments that the step forwards to the distillation script. Use this parameter to pass newly added Model Optimizer flags that do not yet have a dedicated `args.*` entry. @@ -98,37 +110,53 @@ Use this parameter to pass newly added Model Optimizer flags that do not yet hav Default: `[]`. Example: `extra_args=["--hf_export_path", "/lustre/distilled/hf"]` -``` Frequently used dotlist overrides drawn from the default configuration include the following. -```{option} args.tp_size= +--- + +### `tp_size=` + +```python +args.tp_size= +``` The tensor-parallel degree applied during distillation. Example: `args.tp_size=4` -``` -```{option} args.train_iters= +--- + +### `train_iters=` + +```python +args.train_iters= +``` The number of training iterations. Example: `args.train_iters=2000` -``` -```{option} args.seq_length= +--- + +### `seq_length=` + +```python +args.seq_length= +``` The training sequence length. Example: `args.seq_length=4096` -``` ## Strategies The manifest records three operator strategies for `optimize/modelopt/distill`. - When you recover quality after pruning or quantization, set the original BF16 checkpoint as the teacher and the optimized checkpoint as the student. + - When you validate the pipeline, set `args.use_mock_data=true`, `args.seq_length=512`, `args.train_iters=100`, and a small `args.eval_iters` value. + - When you need a Hugging Face checkpoint, set `args.hf_export_path` and `args.student_hf_model`, or convert a saved Megatron iteration after the run completes. ## Command Examples @@ -170,13 +198,18 @@ Run the `nemotron-optimizer-distillation` skill with your agent. ## Related Documentation -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Run Post-Training Optimization](../../how-to/run-optimization.md) explains the ordering of prune and distill, hardware targets, and quality recovery. -- [optimize/modelopt/prune](prune.md) feeds pruned checkpoints into this step. +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Run Post-Training Optimization](/../../how-to/run-optimization) explains the ordering of prune and distill, hardware targets, and quality recovery. + +- [optimize/modelopt/prune](/prune) feeds pruned checkpoints into this step. ### Upstream - [NVIDIA Model Optimizer Repository](https://github.com/NVIDIA/Model-Optimizer) + - [NVIDIA Model Optimizer Documentation](https://nvidia.github.io/Model-Optimizer/) + - [Megatron-Bridge Documentation](https://docs.nvidia.com/nemo/megatron-bridge/0.4.0/) + - [Megatron-Bridge Distillation Guide](https://docs.nvidia.com/nemo/megatron-bridge/0.4.0/training/distillation.html) diff --git a/docs/fern/pages-vnightly/train-models/reference/optimize/index.mdx b/docs/fern/pages-vnightly/train-models/reference/optimize/index.mdx new file mode 100644 index 000000000..91d2fa255 --- /dev/null +++ b/docs/fern/pages-vnightly/train-models/reference/optimize/index.mdx @@ -0,0 +1,48 @@ +--- +title: "Model Optimization Steps" +slug: "train-models/reference/optimize/index.html" +description: "This section documents the model optimization steps registered under src/nemotron/steps/optimize/modelopt/. The three steps wrap NVIDIA Model Optimizer through NVIDIA Megatron-Bridge to quantize, prun" +--- + +This section documents the model optimization steps registered under `src/nemotron/steps/optimize/modelopt/`. +The three steps wrap NVIDIA Model Optimizer through NVIDIA Megatron-Bridge to quantize, prune, and distill trained checkpoints. + +## Steps + + + +Post-training quantization with floating-point recipes such as fp8 and nvfp4, and integer recipes such as int8_sq and int4_awq. + +--- + +reference + + + + +Structured pruning by target parameter budget or explicit architecture. + +--- + +reference + + + + +Teacher-student distillation that recovers quality after pruning or quantization. + +--- + +reference + + + + + +## Related Documentation + +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Run Post-Training Optimization](/../../how-to/run-optimization) explains the ordering of prune and distill, hardware targets, and quality recovery. + +- [Configuration Conventions](/../config-conventions) describes the per-step `config/` layout. diff --git a/docs/train-models/reference/optimize/prune.md b/docs/fern/pages-vnightly/train-models/reference/optimize/prune.mdx similarity index 70% rename from docs/train-models/reference/optimize/prune.md rename to docs/fern/pages-vnightly/train-models/reference/optimize/prune.mdx index 0a23bcffd..b8c22d772 100644 --- a/docs/train-models/reference/optimize/prune.md +++ b/docs/fern/pages-vnightly/train-models/reference/optimize/prune.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the optimize/modelopt/prune step." -topics: ["Training", "Reference", "CLI", "Optimization", "Pruning"] -tags: ["Reference", "CLI", "Steps", "Optimization", "Pruning", "ModelOpt", "Megatron-Bridge"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "optimize/modelopt/prune" +slug: "train-models/reference/optimize/prune.html" +description: "This step runs structured pruning on a Hugging Face (HF) format checkpoint by using NVIDIA Model Optimizer through NVIDIA Megatron-Bridge. The step supports pruning by a target parameter budget that M" --- -# optimize/modelopt/prune - This step runs structured pruning on a Hugging Face (HF) format checkpoint by using NVIDIA Model Optimizer through NVIDIA Megatron-Bridge. The step supports pruning by a target parameter budget that Model Optimizer searches against, or pruning to an explicit architecture that you supply. The step produces a pruned Hugging Face checkpoint that you can pass to `optimize/modelopt/distill` for quality recovery. @@ -20,15 +12,15 @@ The step produces a pruned Hugging Face checkpoint that you can pass to `optimiz ```bash nemotron steps run optimize/modelopt/prune \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ [--force-squash] \ - [...] \ - [...] + [\...] \ + [\...] ``` -Refer to the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -36,8 +28,8 @@ The step ships two configuration files under `src/nemotron/steps/optimize/modelo | File | Purpose | | --- | --- | -| `default.yaml` | Generic structured-pruning configuration for `Qwen/Qwen3-8B` with two-way pipeline parallelism. | -| `tiny.yaml` | Short validation run that exercises the pruning pipeline. | +| default.yaml | Generic structured-pruning configuration for Qwen/Qwen3-8B with two-way pipeline parallelism. | +| tiny.yaml | Short validation run that exercises the pruning pipeline. | Pass the configuration name with `-c`: @@ -50,15 +42,19 @@ $ nemotron steps run optimize/modelopt/prune -c default | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `checkpoint_hf` | Yes | A Hugging Face model identifier or checkpoint to prune. | -| Produces | `checkpoint_hf` | — | The pruned Hugging Face checkpoint. | +| Consumes | checkpoint_hf | Yes | A Hugging Face model identifier or checkpoint to prune. | +| Produces | checkpoint_hf | — | The pruned Hugging Face checkpoint. | ## Step Parameters The manifest declares four pruning parameters. Pass them as dotlist overrides. -```{option} args.prune_target_params= +### `prune_target_params=` + +```python +args.prune_target_params= +``` The target parameter count for the Model Optimizer search. Use scientific notation for billions of parameters. @@ -66,24 +62,35 @@ Use scientific notation for billions of parameters. Default: `6e9`. Example: `args.prune_target_params=4e9` -``` -```{option} args.prune_export_config= +--- + +### `prune_export_config=` + +```python +args.prune_export_config= +``` The explicit target architecture for manual pruning, expressed as a dictionary that maps hyperparameter names such as `hidden_size`, `ffn_hidden_size`, or `num_layers` to integer values. Set this parameter when you want a specific architecture and you set `args.prune_target_params=null`. -Example: `args.prune_export_config='{"hidden_size":4096,"ffn_hidden_size":11008,"num_layers":24}'` -``` +Example: `args.prune_export_config='\{"hidden_size":4096,"ffn_hidden_size":11008,"num_layers":24\}'` + +--- + +### `hparams_to_skip=` -```{option} args.hparams_to_skip= +```python +args.hparams_to_skip= +``` The architecture hyperparameters that the search must leave unchanged. Example: `args.hparams_to_skip=["num_attention_heads"]` -``` -```{option} extra_args= +--- + +### `extra_args=` Literal upstream arguments that the step forwards to the pruning script. Use this parameter to pass newly added Model Optimizer flags that do not yet have a dedicated `args.*` entry. @@ -91,37 +98,53 @@ Use this parameter to pass newly added Model Optimizer flags that do not yet hav Default: `[]`. Example: `extra_args=["--num_layers_in_first_pipeline_stage", "4"]` -``` Frequently used dotlist overrides drawn from the default configuration include the following. -```{option} args.hf_model_name_or_path= +--- + +### `hf_model_name_or_path=` + +```python +args.hf_model_name_or_path= +``` The Hugging Face identifier or local path for the checkpoint to prune. Example: `args.hf_model_name_or_path=meta-llama/Llama-3.1-8B-Instruct` -``` -```{option} args.output_hf_path= +--- + +### `output_hf_path=` + +```python +args.output_hf_path= +``` The destination directory for the pruned Hugging Face checkpoint. Example: `args.output_hf_path=/lustre/runs/pruned/llama-6b` -``` -```{option} args.pp_size= +--- + +### `pp_size=` + +```python +args.pp_size= +``` The pipeline-parallel degree applied during pruning. Example: `args.pp_size=4` -``` ## Strategies The manifest records three operator strategies for `optimize/modelopt/prune`. - When you know the target model budget, set `args.prune_target_params` and leave `args.prune_export_config` unset so Model Optimizer searches candidate architectures. + - When you need a specific architecture, set `args.prune_export_config` to the target dictionary and set `args.prune_target_params=null`. + - When the layer count does not divide the pipeline-parallel size, set `args.num_layers_in_first_pipeline_stage` and `args.num_layers_in_last_pipeline_stage` to balance the partition. ## Command Examples @@ -162,13 +185,18 @@ Run the `nemotron-optimizer-pruning` skill with your agent. ## Related Documentation -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Run Post-Training Optimization](../../how-to/run-optimization.md) explains the ordering of prune and distill, hardware targets, and quality recovery. -- [optimize/modelopt/distill](distill.md) recovers quality after pruning. +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Run Post-Training Optimization](/../../how-to/run-optimization) explains the ordering of prune and distill, hardware targets, and quality recovery. + +- [optimize/modelopt/distill](/distill) recovers quality after pruning. ### Upstream - [NVIDIA Model Optimizer Repository](https://github.com/NVIDIA/Model-Optimizer) + - [NVIDIA Model Optimizer Documentation](https://nvidia.github.io/Model-Optimizer/) + - [Megatron-Bridge Documentation](https://docs.nvidia.com/nemo/megatron-bridge/0.4.0/) + - [Megatron-Bridge Pruning Guide](https://docs.nvidia.com/nemo/megatron-bridge/0.4.0/training/pruning.html) diff --git a/docs/train-models/reference/optimize/quantize.md b/docs/fern/pages-vnightly/train-models/reference/optimize/quantize.mdx similarity index 67% rename from docs/train-models/reference/optimize/quantize.md rename to docs/fern/pages-vnightly/train-models/reference/optimize/quantize.mdx index ff2c535d9..dc48db1fe 100644 --- a/docs/train-models/reference/optimize/quantize.md +++ b/docs/fern/pages-vnightly/train-models/reference/optimize/quantize.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the optimize/modelopt/quantize step." -topics: ["Training", "Reference", "CLI", "Optimization", "Quantization"] -tags: ["Reference", "CLI", "Steps", "Optimization", "Quantization", "ModelOpt", "Megatron-Bridge", "FP8", "NVFP4"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "optimize/modelopt/quantize" +slug: "train-models/reference/optimize/quantize.html" +description: "This step runs post-training quantization (PTQ) on a Hugging Face (HF) format checkpoint by using NVIDIA Model Optimizer through NVIDIA Megatron-Bridge. The step supports every quantization recipe tha" --- -# optimize/modelopt/quantize - This step runs post-training quantization (PTQ) on a Hugging Face (HF) format checkpoint by using NVIDIA Model Optimizer through NVIDIA Megatron-Bridge. The step supports every quantization recipe that the installed Megatron-Bridge quantization script accepts. The step produces a quantized Megatron distributed checkpoint that you can export back to Hugging Face format with the upstream `export.py` script. @@ -20,15 +12,15 @@ The step produces a quantized Megatron distributed checkpoint that you can expor ```bash nemotron steps run optimize/modelopt/quantize \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ [--force-squash] \ - [...] \ - [...] + [\...] \ + [\...] ``` -Refer to the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -36,10 +28,10 @@ The step ships four configuration files under `src/nemotron/steps/optimize/model | File | Purpose | | --- | --- | -| `default.yaml` | Generic post-training quantization configuration with `fp8` selected and `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-Base-BF16` as the input checkpoint. | -| `fp8.yaml` | FP8 quantization configuration tuned for Hopper-class hardware. | -| `nvfp4.yaml` | NVFP4 quantization configuration tuned for Blackwell-class hardware. | -| `tiny.yaml` | Short validation run that exercises the quantization pipeline. | +| default.yaml | Generic post-training quantization configuration with fp8 selected and nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-Base-BF16 as the input checkpoint. | +| fp8.yaml | FP8 quantization configuration tuned for Hopper-class hardware. | +| nvfp4.yaml | NVFP4 quantization configuration tuned for Blackwell-class hardware. | +| tiny.yaml | Short validation run that exercises the quantization pipeline. | Pass the configuration name with `-c`: @@ -54,15 +46,19 @@ $ nemotron steps run optimize/modelopt/quantize -c nvfp4 | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `checkpoint_hf` | Yes | A Hugging Face base or aligned checkpoint to quantize. | -| Produces | `checkpoint_megatron` | — | A quantized Megatron distributed checkpoint. Export the artifact to Hugging Face format with `/opt/Megatron-Bridge/examples/quantization/export.py` when you need a deployable Hugging Face checkpoint. | +| Consumes | checkpoint_hf | Yes | A Hugging Face base or aligned checkpoint to quantize. | +| Produces | checkpoint_megatron | — | A quantized Megatron distributed checkpoint. Export the artifact to Hugging Face format with /opt/Megatron-Bridge/examples/quantization/export.py when you need a deployable Hugging Face checkpoint. | ## Step Parameters The manifest declares three quantization parameters. Pass them as dotlist overrides. -```{option} args.export_quant_cfg= +### `export_quant_cfg=` + +```python +args.export_quant_cfg= +``` The quantization recipe to apply. The supported recipes match the choices that the installed upstream `quantize.py` accepts. @@ -72,18 +68,24 @@ Choices: `int8_sq`, `fp8`, `fp8_blockwise`, `int4_awq`, `w4a8_awq`, `nvfp4`. Default: `fp8`. Example: `args.export_quant_cfg=nvfp4` -``` -```{option} args.calib_size= +--- + +### `calib_size=` + +```python +args.calib_size= +``` The number of calibration samples used to determine quantization scales. Default: `512`. Example: `args.calib_size=1024` -``` -```{option} extra_args= +--- + +### `extra_args=` Literal upstream arguments that the step forwards to the underlying quantization script. Use this parameter to pass newly added Model Optimizer flags that do not yet have a dedicated `args.*` entry. @@ -91,30 +93,41 @@ Use this parameter to pass newly added Model Optimizer flags that do not yet hav Default: `[]`. Example: `extra_args=["--my_new_flag", "value"]` -``` Frequently used dotlist overrides drawn from the default configuration include the following. -```{option} args.hf_model_id= +--- + +### `hf_model_id=` + +```python +args.hf_model_id= +``` The Hugging Face identifier or local path for the checkpoint to quantize. Example: `args.hf_model_id=nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16` -``` -```{option} args.megatron_save_path= +--- + +### `megatron_save_path=` + +```python +args.megatron_save_path= +``` The destination directory for the quantized Megatron distributed checkpoint. Example: `args.megatron_save_path=/lustre/runs/quantized/nano3-fp8` -``` ## Strategies The manifest records three operator strategies for `optimize/modelopt/quantize`. - When the target hardware is Hopper or H100, start from `config/fp8.yaml` and set `args.export_quant_cfg=fp8`. + - When the target hardware is Blackwell or B200, start from `config/nvfp4.yaml` and set `args.export_quant_cfg=nvfp4`. + - When you need a Hugging Face checkpoint, export the produced Megatron checkpoint by using `/opt/Megatron-Bridge/examples/quantization/export.py` after the quantization run completes. ## Command Examples @@ -153,12 +166,16 @@ Run the `nemotron-optimizer-quantization` skill with your agent. ## Related Documentation -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Run Post-Training Optimization](../../how-to/run-optimization.md) explains the ordering of prune and distill, hardware targets, and quality recovery. +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Run Post-Training Optimization](/../../how-to/run-optimization) explains the ordering of prune and distill, hardware targets, and quality recovery. ### Upstream - [NVIDIA Model Optimizer Repository](https://github.com/NVIDIA/Model-Optimizer) + - [NVIDIA Model Optimizer Documentation](https://nvidia.github.io/Model-Optimizer/) + - [Megatron-Bridge Documentation](https://docs.nvidia.com/nemo/megatron-bridge/latest/) + - [Megatron-Bridge Quantization Guide](https://docs.nvidia.com/nemo/megatron-bridge/latest/modelopt/quantization.html) diff --git a/docs/train-models/reference/peft/automodel.md b/docs/fern/pages-vnightly/train-models/reference/peft/automodel.mdx similarity index 66% rename from docs/train-models/reference/peft/automodel.md rename to docs/fern/pages-vnightly/train-models/reference/peft/automodel.mdx index 3ff88d21d..1af49f081 100644 --- a/docs/train-models/reference/peft/automodel.md +++ b/docs/fern/pages-vnightly/train-models/reference/peft/automodel.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the peft/automodel training step." -topics: ["Training", "Reference", "CLI", "PEFT", "LoRA", "AutoModel"] -tags: ["Reference", "CLI", "Steps", "PEFT", "LoRA", "AutoModel", "Hugging Face"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "peft/automodel" +slug: "train-models/reference/peft/automodel.html" +description: "This step trains a low-rank adaptation (LoRA) adapter on top of a Hugging Face (HF) format base model by using the NeMo AutoModel library. The training loop matches sft/automodel, with a LoRA adapter " --- -# peft/automodel - This step trains a low-rank adaptation (LoRA) adapter on top of a Hugging Face (HF) format base model by using the NeMo AutoModel library. The training loop matches `sft/automodel`, with a LoRA adapter wired in by default to keep large base models practical for adapter tuning. The step produces a `checkpoint_lora` artifact that you can merge with the base model by using the `convert/merge_lora` step. @@ -20,15 +12,15 @@ The step produces a `checkpoint_lora` artifact that you can merge with the base ```bash nemotron steps run peft/automodel \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ [--force-squash] \ - [...] \ - [...] + [\...] \ + [\...] ``` -Refer to the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -36,8 +28,8 @@ The step ships two configuration files under `src/nemotron/steps/peft/automodel/ | File | Purpose | | --- | --- | -| `default.yaml` | Full-shape LoRA tuning on `Qwen/Qwen3-30B-A3B` with the AutoModel `TrainFinetuneRecipeForNextTokenPrediction` recipe. | -| `tiny.yaml` | Short validation run with a small dataset slice and a short training schedule. | +| default.yaml | Full-shape LoRA tuning on Qwen/Qwen3-30B-A3B with the AutoModel TrainFinetuneRecipeForNextTokenPrediction recipe. | +| tiny.yaml | Short validation run with a small dataset slice and a short training schedule. | Pass the configuration name with `-c`: @@ -50,8 +42,8 @@ $ nemotron steps run peft/automodel -c default | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `training_jsonl` | Yes | Chat-format JSON Lines with a `messages` field. | -| Produces | `checkpoint_lora` | — | LoRA adapter weights. Merge the adapter with the base model by using `convert/merge_lora` to obtain a deployable Hugging Face checkpoint. | +| Consumes | training_jsonl | Yes | Chat-format JSON Lines with a messages field. | +| Produces | checkpoint_lora | — | LoRA adapter weights. Merge the adapter with the base model by using convert/merge_lora to obtain a deployable Hugging Face checkpoint. | ## Supported Models @@ -60,9 +52,9 @@ Other Hugging Face causal language models that load through `AutoModelForCausalL | Model | Minimum GPUs | Default | Notes | | --- | --- | --- | --- | -| `Qwen/Qwen3-30B-A3B` | 8 | Yes | Mixture-of-experts (MoE) base model used by `config/default.yaml`. | -| `meta-llama/Llama-3.1-8B-Instruct` | 2 | No | Common dense baseline for single-node LoRA tuning. | -| `mistralai/Mistral-7B-Instruct-v0.3` | 1 | No | Strong default for single-GPU LoRA tuning. | +| Qwen/Qwen3-30B-A3B | 8 | Yes | Mixture-of-experts (MoE) base model used by config/default.yaml. | +| meta-llama/Llama-3.1-8B-Instruct | 2 | No | Common dense baseline for single-node LoRA tuning. | +| mistralai/Mistral-7B-Instruct-v0.3 | 1 | No | Strong default for single-GPU LoRA tuning. | Override the base model from the command line: @@ -76,7 +68,11 @@ $ nemotron steps run peft/automodel -c default \ The manifest declares two LoRA-specific parameters. Pass them as dotlist overrides. -```{option} peft.dim= +### `dim=` + +```python +peft.dim= +``` The LoRA rank. Values in the eight-to-thirty-two range work well for most tasks. @@ -85,9 +81,14 @@ Raise the rank when the downstream task is harder than the base task. Default: `16`. Example: `peft.dim=32` -``` -```{option} peft.alpha= +--- + +### `alpha=` + +```python +peft.alpha= +``` The LoRA alpha scaling factor. A value equal to twice the rank works well in practice. @@ -95,53 +96,74 @@ A value equal to twice the rank works well in practice. Default: `32`. Example: `peft.alpha=64` -``` Frequently used dotlist overrides drawn from the AutoModel recipe include the following. -```{option} step_scheduler.max_steps= +--- + +### `max_steps=` + +```python +step_scheduler.max_steps= +``` The maximum number of optimizer steps for the run. Example: `step_scheduler.max_steps=200` -``` -```{option} step_scheduler.global_batch_size= +--- + +### `global_batch_size=` + +```python +step_scheduler.global_batch_size= +``` The global batch size across all data-parallel workers. Example: `step_scheduler.global_batch_size=64` -``` -```{option} dataset.path_or_dataset_id= +--- + +### `path_or_dataset_id=` + +```python +dataset.path_or_dataset_id= +``` The Hugging Face dataset identifier or a local path that resolves to a JSON Lines chat dataset. Example: `dataset.path_or_dataset_id=/data/my-instructions.jsonl` -``` -```{option} peft.dropout= +--- + +### `dropout=` + +```python +peft.dropout= +``` The LoRA dropout rate applied during training. Example: `peft.dropout=0.05` -``` ## Strategies The manifest records two operator strategies for `peft/automodel`. - When the run targets a single GPU or memory is tight, keep `peft.dim` low, in the eight-to-sixteen range, and prefer a Mistral-class base model. + - When the adapter is intended for deployment, run `convert/merge_lora` after training to merge the adapter with the base model and produce a standalone Hugging Face checkpoint. ## Common Errors -```{option} oom +--- + +### `oom` Cause: GPU memory is exhausted during forward or backward passes. Recovery: reduce `peft.dim`, lower `step_scheduler.local_batch_size`, lower the maximum sequence length, or move to a smaller base model. -``` ## Command Examples @@ -181,13 +203,18 @@ Run the `nemotron-peft-automodel` skill with your agent. ## Related Documentation -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Choose a PEFT Backend](../../how-to/choose-peft-backend.md) compares `peft/automodel` and `peft/megatron_bridge`. -- [peft/megatron_bridge](megatron-bridge.md) documents the Megatron-Bridge LoRA step. +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Choose a PEFT Backend](/../../how-to/choose-peft-backend) compares `peft/automodel` and `peft/megatron_bridge`. + +- [peft/megatron_bridge](/megatron-bridge) documents the Megatron-Bridge LoRA step. ### Upstream - [NeMo AutoModel Repository](https://github.com/NVIDIA-NeMo/Automodel) + - [NeMo AutoModel Documentation](https://docs.nvidia.com/nemo/automodel/latest/index.html) + - [NeMo AutoModel PEFT Guide](https://docs.nvidia.com/nemo/automodel/latest/guides/llm/finetune.html) + - [AutoModel Training Script](https://github.com/NVIDIA-NeMo/Automodel/blob/main/nemo_automodel/recipes/llm/train_ft.py) diff --git a/docs/fern/pages-vnightly/train-models/reference/peft/index.mdx b/docs/fern/pages-vnightly/train-models/reference/peft/index.mdx new file mode 100644 index 000000000..70a4ea95f --- /dev/null +++ b/docs/fern/pages-vnightly/train-models/reference/peft/index.mdx @@ -0,0 +1,40 @@ +--- +title: "Parameter-Efficient Fine-Tuning Steps" +slug: "train-models/reference/peft/index.html" +description: "This section documents the parameter-efficient fine-tuning (PEFT) steps registered under src/nemotron/steps/peft/. Each step trains a low-rank adaptation (LoRA) adapter on top of a base model and prod" +--- + +This section documents the parameter-efficient fine-tuning (PEFT) steps registered under `src/nemotron/steps/peft/`. +Each step trains a low-rank adaptation (LoRA) adapter on top of a base model and produces a `checkpoint_lora` artifact. +Merge that artifact with the base model by using the `convert/merge_lora` step when you need a standalone Hugging Face (HF) checkpoint for deployment. + +## Steps + + + +LoRA tuning with the NeMo AutoModel library against Hugging Face base models and JSON Lines chat datasets. + +--- + +reference + + + + +LoRA tuning on top of NVIDIA Megatron-Bridge for distributed training of the Nemotron model family. + +--- + +reference + + + + + +## Related Documentation + +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Choose a PEFT Backend](/../../how-to/choose-peft-backend) compares `peft/automodel` and `peft/megatron_bridge`. + +- [Configuration Conventions](/../config-conventions) describes the per-step `config/` layout. diff --git a/docs/train-models/reference/peft/megatron-bridge.md b/docs/fern/pages-vnightly/train-models/reference/peft/megatron-bridge.mdx similarity index 64% rename from docs/train-models/reference/peft/megatron-bridge.md rename to docs/fern/pages-vnightly/train-models/reference/peft/megatron-bridge.mdx index 8e4b5791b..948ca8f61 100644 --- a/docs/train-models/reference/peft/megatron-bridge.md +++ b/docs/fern/pages-vnightly/train-models/reference/peft/megatron-bridge.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the peft/megatron_bridge training step." -topics: ["Training", "Reference", "CLI", "PEFT", "LoRA", "Megatron Bridge"] -tags: ["Reference", "CLI", "Steps", "PEFT", "LoRA", "Megatron-Bridge"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "peft/megatron_bridge" +slug: "train-models/reference/peft/megatron-bridge.html" +description: "This step trains a low-rank adaptation (LoRA) adapter on top of a Megatron checkpoint by using NVIDIA Megatron-Bridge. Use this step when a full supervised fine-tune does not fit in memory at the targ" --- -# peft/megatron_bridge - This step trains a low-rank adaptation (LoRA) adapter on top of a Megatron checkpoint by using NVIDIA Megatron-Bridge. Use this step when a full supervised fine-tune does not fit in memory at the target model size, but you still need tensor and pipeline parallelism. The step consumes packed Apache Parquet shards produced by `data_prep/sft_packing` together with a base Megatron checkpoint, and produces a `checkpoint_lora` artifact. @@ -20,15 +12,15 @@ The step consumes packed Apache Parquet shards produced by `data_prep/sft_packin ```bash nemotron steps run peft/megatron_bridge \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ [--force-squash] \ - [...] \ - [...] + [\...] \ + [\...] ``` -Refer to the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -36,8 +28,8 @@ The step ships two configuration files under `src/nemotron/steps/peft/megatron_b | File | Purpose | | --- | --- | -| `default.yaml` | Full-shape LoRA tuning on top of the Nano3 Megatron-Bridge finetune recipe with rank thirty-two adapters on `linear_qkv` and `linear_proj`. | -| `tiny.yaml` | Short validation run against packed Parquet shards. | +| default.yaml | Full-shape LoRA tuning on top of the Nano3 Megatron-Bridge finetune recipe with rank thirty-two adapters on linear_qkv and linear_proj. | +| tiny.yaml | Short validation run against packed Parquet shards. | Pass the configuration name with `-c`: @@ -50,16 +42,20 @@ $ nemotron steps run peft/megatron_bridge -c default | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `packed_parquet` | Yes | Packed Parquet shards with `input_ids` and `loss_mask` columns. Produce these shards with `data_prep/sft_packing` first. | -| Consumes | `checkpoint_megatron` | Yes | A pretrained Megatron checkpoint to adapt. | -| Produces | `checkpoint_lora` | — | LoRA adapter weights. Merge the adapter with the base checkpoint by using `convert/merge_lora` to obtain a deployable Hugging Face (HF) checkpoint. | +| Consumes | packed_parquet | Yes | Packed Parquet shards with input_ids and loss_mask columns. Produce these shards with data_prep/sft_packing first. | +| Consumes | checkpoint_megatron | Yes | A pretrained Megatron checkpoint to adapt. | +| Produces | checkpoint_lora | — | LoRA adapter weights. Merge the adapter with the base checkpoint by using convert/merge_lora to obtain a deployable Hugging Face (HF) checkpoint. | ## Step Parameters The manifest declares two LoRA-specific parameters. Pass them as dotlist overrides. -```{option} peft.type= +### `type=` + +```python +peft.type= +``` The parameter-efficient training scheme. Only `lora` is supported today. @@ -69,62 +65,96 @@ Choices: `lora`. Default: `lora`. Example: `peft.type=lora` -``` -```{option} peft.dim= +--- + +### `dim=` + +```python +peft.dim= +``` The LoRA rank. Default: `32`. Example: `peft.dim=16` -``` Frequently used dotlist overrides drawn from the Nano3 finetune recipe include the following. -```{option} recipe.seq_length= +--- + +### `seq_length=` + +```python +recipe.seq_length= +``` The training sequence length applied by the recipe. This value must match the `pack_size` you used in `data_prep/sft_packing`. Example: `recipe.seq_length=8192` -``` -```{option} recipe.tensor_model_parallel_size= +--- + +### `tensor_model_parallel_size=` + +```python +recipe.tensor_model_parallel_size= +``` The tensor-model-parallel degree applied by the Nano3 finetune recipe. Example: `recipe.tensor_model_parallel_size=8` -``` -```{option} recipe.pipeline_model_parallel_size= +--- + +### `pipeline_model_parallel_size=` + +```python +recipe.pipeline_model_parallel_size= +``` The pipeline-model-parallel degree applied by the Nano3 finetune recipe. Example: `recipe.pipeline_model_parallel_size=4` -``` -```{option} train.train_iters= +--- + +### `train_iters=` + +```python +train.train_iters= +``` The number of training iterations. Example: `train.train_iters=2000` -``` -```{option} train.global_batch_size= +--- + +### `global_batch_size=` + +```python +train.global_batch_size= +``` The global batch size for the training loop. Example: `train.global_batch_size=32` -``` -```{option} dataset.nano3_packed_sft_dir= +--- + +### `nano3_packed_sft_dir=` + +```python +dataset.nano3_packed_sft_dir= +``` The directory that contains packed Parquet shards from `data_prep/sft_packing`. The default configuration reads this value from the `SFT_PACKED_DIR` environment variable. Example: `dataset.nano3_packed_sft_dir=/lustre/packed/super3-sft` -``` ## Strategies @@ -134,12 +164,13 @@ The manifest records one operator strategy for `peft/megatron_bridge`. ## Common Errors -```{option} missing_packed_data +--- + +### `missing_packed_data` Cause: the training loop cannot find packed Parquet shards at the configured `dataset.nano3_packed_sft_dir`. Recovery: run `data_prep/sft_packing` first, or override `dataset.nano3_packed_sft_dir` to point at the directory that holds the packed splits. -``` ## Command Examples @@ -179,13 +210,18 @@ Run the `nemotron-peft-megatron-bridge` skill with your agent. ## Related Documentation -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Choose a PEFT Backend](../../how-to/choose-peft-backend.md) compares `peft/megatron_bridge` and `peft/automodel`. -- [peft/automodel](automodel.md) documents the NeMo AutoModel LoRA step. +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Choose a PEFT Backend](/../../how-to/choose-peft-backend) compares `peft/megatron_bridge` and `peft/automodel`. + +- [peft/automodel](/automodel) documents the NeMo AutoModel LoRA step. ### Upstream - [Megatron-Bridge Repository](https://github.com/NVIDIA-NeMo/Megatron-Bridge) + - [Megatron-Bridge Documentation](https://docs.nvidia.com/nemo/megatron-bridge/latest/) + - [Megatron-Bridge PEFT Guide](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/peft.html) + - [Megatron-Bridge Packed Sequences](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/packed-sequences.html) diff --git a/docs/train-models/reference/rl/dpo.md b/docs/fern/pages-vnightly/train-models/reference/rl/dpo.mdx similarity index 64% rename from docs/train-models/reference/rl/dpo.md rename to docs/fern/pages-vnightly/train-models/reference/rl/dpo.mdx index 35574688b..edec9c048 100644 --- a/docs/train-models/reference/rl/dpo.md +++ b/docs/fern/pages-vnightly/train-models/reference/rl/dpo.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the rl/nemo_rl/dpo training step." -topics: ["Training", "Reference", "CLI", "RL", "DPO"] -tags: ["Reference", "CLI", "Steps", "RL", "DPO", "Alignment", "NeMo-RL"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "rl/nemo_rl/dpo" +slug: "train-models/reference/rl/dpo.html" +description: "This step runs direct preference optimization (DPO) alignment on NeMo-RL. The step consumes a preference dataset of chosen-and-rejected response pairs, together with a supervised fine-tuning (SFT) Meg" --- -# rl/nemo_rl/dpo - This step runs direct preference optimization (DPO) alignment on NeMo-RL. The step consumes a preference dataset of chosen-and-rejected response pairs, together with a supervised fine-tuning (SFT) Megatron checkpoint that serves as the warm-start policy. The step produces an aligned `checkpoint_megatron` artifact. @@ -20,15 +12,15 @@ The step produces an aligned `checkpoint_megatron` artifact. ```bash nemotron steps run rl/nemo_rl/dpo \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ [--force-squash] \ - [...] \ - [...] + [\...] \ + [\...] ``` -Refer to the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -36,8 +28,8 @@ The step ships two configuration files under `src/nemotron/steps/rl/nemo_rl/dpo/ | File | Purpose | | --- | --- | -| `default.yaml` | Full-shape DPO with a five-hundred-step training schedule and `meta-llama/Llama-3.2-1B-Instruct` as the policy. | -| `tiny.yaml` | Short validation run with a small dataset slice. | +| default.yaml | Full-shape DPO with a five-hundred-step training schedule and meta-llama/Llama-3.2-1B-Instruct as the policy. | +| tiny.yaml | Short validation run with a small dataset slice. | Pass the configuration name with `-c`: @@ -50,16 +42,20 @@ $ nemotron steps run rl/nemo_rl/dpo -c default | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `training_jsonl` | Yes | Preference JSON Lines with `prompt`, `chosen`, and `rejected` fields. | -| Consumes | `checkpoint_megatron` | Yes | The supervised fine-tuned policy to align. | -| Produces | `checkpoint_megatron` | — | The DPO-aligned policy checkpoint. | +| Consumes | training_jsonl | Yes | Preference JSON Lines with prompt, chosen, and rejected fields. | +| Consumes | checkpoint_megatron | Yes | The supervised fine-tuned policy to align. | +| Produces | checkpoint_megatron | — | The DPO-aligned policy checkpoint. | ## Step Parameters The manifest declares one DPO-specific parameter. Pass it as a dotlist override. -```{option} dpo.reference_policy_kl_penalty= +### `reference_policy_kl_penalty=` + +```python +dpo.reference_policy_kl_penalty= +``` The Kullback-Leibler (KL) penalty between the trained policy and the reference policy. This value corresponds to β in the DPO objective. @@ -68,38 +64,57 @@ Lower values let the policy drift further from the reference; higher values keep Default: `0.05`. Example: `dpo.reference_policy_kl_penalty=0.1` -``` Frequently used dotlist overrides drawn from the NeMo-RL DPO recipe include the following. -```{option} policy.model_name= +--- + +### `model_name=` + +```python +policy.model_name= +``` The Hugging Face identifier or local path for the policy. The default configuration reads this value from the `RL_POLICY_MODEL` environment variable. Example: `policy.model_name=meta-llama/Llama-3.2-3B-Instruct` -``` -```{option} dpo.max_num_steps= +--- + +### `max_num_steps=` + +```python +dpo.max_num_steps= +``` The maximum number of training steps. Example: `dpo.max_num_steps=1000` -``` -```{option} policy.train_global_batch_size= +--- + +### `train_global_batch_size=` + +```python +policy.train_global_batch_size= +``` The global batch size across all data-parallel workers. Example: `policy.train_global_batch_size=64` -``` -```{option} policy.optimizer.lr= +--- + +### `lr=` + +```python +policy.optimizer.lr= +``` The optimizer learning rate. Example: `policy.optimizer.lr=1.0e-6` -``` ## Strategies @@ -144,10 +159,12 @@ Run the `nemotron-rl-nemo-rl-dpo` skill with your agent. ## Related Documentation -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Choose an RL Alignment Step](../../how-to/choose-rl-step.md) compares the three RL steps. +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Choose an RL Alignment Step](/../../how-to/choose-rl-step) compares the three RL steps. ### Upstream - [NeMo-RL DPO Example](https://github.com/NVIDIA-NeMo/RL/blob/main/examples/run_dpo.py) + - [NeMo-RL Repository](https://github.com/NVIDIA-NeMo/RL) diff --git a/docs/fern/pages-vnightly/train-models/reference/rl/index.mdx b/docs/fern/pages-vnightly/train-models/reference/rl/index.mdx new file mode 100644 index 000000000..7cf53cc1a --- /dev/null +++ b/docs/fern/pages-vnightly/train-models/reference/rl/index.mdx @@ -0,0 +1,48 @@ +--- +title: "Reinforcement Learning Steps" +slug: "train-models/reference/rl/index.html" +description: "This section documents the reinforcement learning (RL) alignment steps registered under src/nemotron/steps/rl/nemo_rl/. All three steps run on NeMo-RL, consume a supervised fine-tuning (SFT) Megatron " +--- + +This section documents the reinforcement learning (RL) alignment steps registered under `src/nemotron/steps/rl/nemo_rl/`. +All three steps run on NeMo-RL, consume a supervised fine-tuning (SFT) Megatron checkpoint as the warm-start policy, and produce an aligned `checkpoint_megatron` artifact. + +## Steps + + + +Direct preference optimization with preference pairs. + +--- + +reference + + + + +Reinforcement learning with verifiable rewards via group relative policy optimization. + +--- + +reference + + + + +Reinforcement learning from human feedback with a generative reward model judge. + +--- + +reference + + + + + +## Related Documentation + +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Choose an RL Alignment Step](/../../how-to/choose-rl-step) compares the three RL steps. + +- [Configuration Conventions](/../config-conventions) describes the per-step `config/` layout. diff --git a/docs/train-models/reference/rl/rlhf.md b/docs/fern/pages-vnightly/train-models/reference/rl/rlhf.mdx similarity index 66% rename from docs/train-models/reference/rl/rlhf.md rename to docs/fern/pages-vnightly/train-models/reference/rl/rlhf.mdx index f79589726..8b825994b 100644 --- a/docs/train-models/reference/rl/rlhf.md +++ b/docs/fern/pages-vnightly/train-models/reference/rl/rlhf.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the rl/nemo_rl/rlhf training step." -topics: ["Training", "Reference", "CLI", "RL", "RLHF", "GRPO"] -tags: ["Reference", "CLI", "Steps", "RL", "RLHF", "GRPO", "Reward Model", "GenRM", "NeMo-RL", "NeMo-Gym"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "rl/nemo_rl/rlhf" +slug: "train-models/reference/rl/rlhf.html" +description: "This step runs reinforcement learning from human feedback (RLHF) on top of the NeMo-RL group relative policy optimization (GRPO) training loop, with a generative reward model judge. The step consumes " --- -# rl/nemo_rl/rlhf - This step runs reinforcement learning from human feedback (RLHF) on top of the NeMo-RL group relative policy optimization (GRPO) training loop, with a generative reward model judge. The step consumes a prompt dataset for rollouts, a supervised fine-tuning (SFT) Megatron checkpoint as the warm-start policy, and a Hugging Face (HF) reward model checkpoint that NeMo-Gym serves as the judge. The step produces an aligned `checkpoint_megatron` artifact. @@ -20,15 +12,15 @@ The step produces an aligned `checkpoint_megatron` artifact. ```bash nemotron steps run rl/nemo_rl/rlhf \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ [--force-squash] \ - [...] \ - [...] + [\...] \ + [\...] ``` -Refer to the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -36,8 +28,8 @@ The step ships two configuration files under `src/nemotron/steps/rl/nemo_rl/rlhf | File | Purpose | | --- | --- | -| `default.yaml` | NeMo-Gym RLHF path with GRPO sampling and a generative reward model judge that NeMo-Gym hosts. | -| `tiny.yaml` | Short validation run with a small dataset slice. | +| default.yaml | NeMo-Gym RLHF path with GRPO sampling and a generative reward model judge that NeMo-Gym hosts. | +| tiny.yaml | Short validation run with a small dataset slice. | Pass the configuration name with `-c`: @@ -50,17 +42,21 @@ $ nemotron steps run rl/nemo_rl/rlhf -c default | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `training_jsonl` | Yes | Prompt JSON Lines used for rollouts. | -| Consumes | `checkpoint_megatron` | Yes | The supervised fine-tuned policy to align. | -| Consumes | `checkpoint_hf` | Yes | The reward model checkpoint, in Hugging Face format, served as the generative reward model judge. | -| Produces | `checkpoint_megatron` | — | The RLHF-aligned policy checkpoint. | +| Consumes | training_jsonl | Yes | Prompt JSON Lines used for rollouts. | +| Consumes | checkpoint_megatron | Yes | The supervised fine-tuned policy to align. | +| Consumes | checkpoint_hf | Yes | The reward model checkpoint, in Hugging Face format, served as the generative reward model judge. | +| Produces | checkpoint_megatron | — | The RLHF-aligned policy checkpoint. | ## Step Parameters The manifest declares two NeMo-Gym RLHF parameters. Pass them as dotlist overrides. -```{option} grpo.num_generations_per_prompt= +### `num_generations_per_prompt=` + +```python +grpo.num_generations_per_prompt= +``` The number of rollouts produced per prompt. This value sets the GRPO group size. @@ -68,52 +64,77 @@ This value sets the GRPO group size. Default: `8`. Example: `grpo.num_generations_per_prompt=16` -``` -```{option} env.nemo_gym.genrm_model.responses_api_models.vllm_model.model= +--- + +### `model=` + +```python +env.nemo_gym.genrm_model.responses_api_models.vllm_model.model= +``` The Hugging Face identifier or local path for the generative reward model that NeMo-Gym serves through its responses API. Default: `meta-llama/Llama-3.2-1B-Instruct` (or the value of `RL_REWARD_MODEL` when that variable is set). Example: `env.nemo_gym.genrm_model.responses_api_models.vllm_model.model=nvidia/Nemotron-Reward-Model` -``` Frequently used dotlist overrides drawn from the NeMo-RL GRPO recipe include the following. -```{option} grpo.max_num_steps= +--- + +### `max_num_steps=` + +```python +grpo.max_num_steps= +``` The maximum number of training steps. Example: `grpo.max_num_steps=1000` -``` -```{option} grpo.num_prompts_per_step= +--- + +### `num_prompts_per_step=` + +```python +grpo.num_prompts_per_step= +``` The number of prompts sampled per training step. Example: `grpo.num_prompts_per_step=32` -``` -```{option} data.train.data_path= +--- + +### `data_path=` + +```python +data.train.data_path= +``` The path to the training JSON Lines dataset. Example: `data.train.data_path=/lustre/rlhf/train.jsonl` -``` -```{option} data.validation.data_path= +--- + +### `data_path=` + +```python +data.validation.data_path= +``` The path to the validation JSON Lines dataset. Example: `data.validation.data_path=/lustre/rlhf/val.jsonl` -``` ## Strategies The manifest records two operator strategies for `rl/nemo_rl/rlhf`. - When the reward model saturates or reward hacking appears in rollouts, raise the Kullback-Leibler penalty, lower the learning rate, or add reward clipping. + - When the data follows the Super3 RLHF layout, keep `env.should_use_nemo_gym=true` and point `data.train.data_path` and `data.validation.data_path` at the prepared NeMo-Gym JSON Lines files. ## Command Examples @@ -153,10 +174,12 @@ Run the `nemotron-rl-nemo-rl-rlhf` skill with your agent. ## Related Documentation -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Choose an RL Alignment Step](../../how-to/choose-rl-step.md) compares the three RL steps. +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Choose an RL Alignment Step](/../../how-to/choose-rl-step) compares the three RL steps. ### Upstream - [Super3 RLHF Recipe](https://github.com/NVIDIA-NeMo/Nemotron/tree/main/src/nemotron/recipes/super3/stage2_rl/stage3_rlhf) + - [NeMo-RL Repository](https://github.com/NVIDIA-NeMo/RL) diff --git a/docs/train-models/reference/rl/rlvr.md b/docs/fern/pages-vnightly/train-models/reference/rl/rlvr.mdx similarity index 64% rename from docs/train-models/reference/rl/rlvr.md rename to docs/fern/pages-vnightly/train-models/reference/rl/rlvr.mdx index ec15281b0..bfb842711 100644 --- a/docs/train-models/reference/rl/rlvr.md +++ b/docs/fern/pages-vnightly/train-models/reference/rl/rlvr.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the rl/nemo_rl/rlvr training step." -topics: ["Training", "Reference", "CLI", "RL", "RLVR", "GRPO"] -tags: ["Reference", "CLI", "Steps", "RL", "RLVR", "GRPO", "NeMo-RL", "NeMo-Gym"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "rl/nemo_rl/rlvr" +slug: "train-models/reference/rl/rlvr.html" +description: "This step runs reinforcement learning with verifiable rewards (RLVR) by using group relative policy optimization (GRPO) on NeMo-RL. Use this step when the downstream task has a programmatic reward sig" --- -# rl/nemo_rl/rlvr - This step runs reinforcement learning with verifiable rewards (RLVR) by using group relative policy optimization (GRPO) on NeMo-RL. Use this step when the downstream task has a programmatic reward signal, such as a unit-tested code generation task or a mathematics problem with a ground-truth solution. The step produces an aligned `checkpoint_megatron` artifact. @@ -20,15 +12,15 @@ The step produces an aligned `checkpoint_megatron` artifact. ```bash nemotron steps run rl/nemo_rl/rlvr \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ [--force-squash] \ - [...] \ - [...] + [\...] \ + [\...] ``` -Refer to the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -36,9 +28,9 @@ The step ships three configuration files under `src/nemotron/steps/rl/nemo_rl/rl | File | Purpose | | --- | --- | -| `default.yaml` | Lightweight upstream group relative policy optimization (GRPO) example path. The step delegates to `/opt/nemo-rl/examples/run_grpo.py`. | -| `nemo_gym.yaml` | NeMo-Gym path that mirrors the Super3 RLVR style, using NeMo-Gym JSON Lines and resource-server reward configurations. | -| `tiny.yaml` | Short validation run with a small dataset slice. | +| default.yaml | Lightweight upstream group relative policy optimization (GRPO) example path. The step delegates to /opt/nemo-rl/examples/run_grpo.py. | +| nemo_gym.yaml | NeMo-Gym path that mirrors the Super3 RLVR style, using NeMo-Gym JSON Lines and resource-server reward configurations. | +| tiny.yaml | Short validation run with a small dataset slice. | Pass the configuration name with `-c`: @@ -52,16 +44,20 @@ $ nemotron steps run rl/nemo_rl/rlvr -c nemo_gym | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `training_jsonl` | Yes | Prompt JSON Lines with verifiable answers, such as ground-truth solutions for a mathematics task. | -| Consumes | `checkpoint_megatron` | Yes | The supervised fine-tuned policy to optimize. | -| Produces | `checkpoint_megatron` | — | The RLVR-aligned policy checkpoint. | +| Consumes | training_jsonl | Yes | Prompt JSON Lines with verifiable answers, such as ground-truth solutions for a mathematics task. | +| Consumes | checkpoint_megatron | Yes | The supervised fine-tuned policy to optimize. | +| Produces | checkpoint_megatron | — | The RLVR-aligned policy checkpoint. | ## Step Parameters The manifest declares three group relative policy optimization (GRPO) parameters. Pass them as dotlist overrides. -```{option} grpo.num_generations_per_prompt= +### `num_generations_per_prompt=` + +```python +grpo.num_generations_per_prompt= +``` The number of rollouts produced per prompt. This value sets the GRPO group size. @@ -69,68 +65,103 @@ This value sets the GRPO group size. Default: `8`. Example: `grpo.num_generations_per_prompt=16` -``` -```{option} grpo.normalize_rewards= +--- + +### `normalize_rewards=` + +```python +grpo.normalize_rewards= +``` When set to `true`, the trainer normalizes rewards within each group before computing advantages. Default: `true`. Example: `grpo.normalize_rewards=false` -``` -```{option} env.should_use_nemo_gym= +--- + +### `should_use_nemo_gym=` + +```python +env.should_use_nemo_gym= +``` When set to `true`, the step switches from the upstream generic GRPO example to the NeMo-Gym GRPO runner. Default: `false`. Example: `env.should_use_nemo_gym=true` -``` Frequently used dotlist overrides drawn from the NeMo-RL GRPO recipe include the following. -```{option} grpo.max_num_steps= +--- + +### `max_num_steps=` + +```python +grpo.max_num_steps= +``` The maximum number of training steps. Example: `grpo.max_num_steps=1000` -``` -```{option} grpo.num_prompts_per_step= +--- + +### `num_prompts_per_step=` + +```python +grpo.num_prompts_per_step= +``` The number of prompts sampled per training step. Example: `grpo.num_prompts_per_step=24` -``` -```{option} grpo.use_leave_one_out_baseline= +--- + +### `use_leave_one_out_baseline=` + +```python +grpo.use_leave_one_out_baseline= +``` When set to `true`, the trainer uses a leave-one-out baseline within each group when computing advantages. Example: `grpo.use_leave_one_out_baseline=false` -``` -```{option} data.train.data_path= +--- + +### `data_path=` + +```python +data.train.data_path= +``` The path to the training JSON Lines dataset. Example: `data.train.data_path=/lustre/rlvr/train.jsonl` -``` -```{option} data.validation.data_path= +--- + +### `data_path=` + +```python +data.validation.data_path= +``` The path to the validation JSON Lines dataset. Example: `data.validation.data_path=/lustre/rlvr/val.jsonl` -``` ## Strategies The manifest records two operator strategies for `rl/nemo_rl/rlvr`. - When reward variance is low, raise `grpo.num_generations_per_prompt` and keep the leave-one-out baseline enabled. + - When the data follows the Super3 JSON Lines layout or relies on resource-server rewards, start from `config/nemo_gym.yaml` and set `data.train.data_path`, `data.validation.data_path`, and the NeMo-Gym `env.nemo_gym.config_paths` field. ## Command Examples @@ -170,10 +201,12 @@ Run the `nemotron-rl-nemo-rl-rlvr` skill with your agent. ## Related Documentation -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Choose an RL Alignment Step](../../how-to/choose-rl-step.md) compares the three RL steps. +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Choose an RL Alignment Step](/../../how-to/choose-rl-step) compares the three RL steps. ### Upstream - [NeMo-RL GRPO Example](https://github.com/NVIDIA-NeMo/RL/blob/main/examples/run_grpo.py) + - [NeMo-RL Repository](https://github.com/NVIDIA-NeMo/RL) diff --git a/docs/train-models/reference/sft/automodel.md b/docs/fern/pages-vnightly/train-models/reference/sft/automodel.mdx similarity index 67% rename from docs/train-models/reference/sft/automodel.md rename to docs/fern/pages-vnightly/train-models/reference/sft/automodel.mdx index 0e734e6c0..a13102dee 100644 --- a/docs/train-models/reference/sft/automodel.md +++ b/docs/fern/pages-vnightly/train-models/reference/sft/automodel.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the sft/automodel training step." -topics: ["Training", "Reference", "CLI", "SFT", "AutoModel"] -tags: ["Reference", "CLI", "Steps", "SFT", "AutoModel", "Hugging Face"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "sft/automodel" +slug: "train-models/reference/sft/automodel.html" +description: "This step runs supervised fine-tuning (SFT) on a Hugging Face (HF) format model from a JSON Lines (JSONL) chat dataset, using the NeMo AutoModel library. The same step supports full fine-tuning and lo" --- -# sft/automodel - This step runs supervised fine-tuning (SFT) on a Hugging Face (HF) format model from a JSON Lines (JSONL) chat dataset, using the NeMo AutoModel library. The same step supports full fine-tuning and low-rank adaptation (LoRA) tuning, controlled by the `peft` parameter. @@ -19,15 +11,15 @@ The same step supports full fine-tuning and low-rank adaptation (LoRA) tuning, c ```bash nemotron steps run sft/automodel \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ [--force-squash] \ - [...] \ - [...] + [\...] \ + [\...] ``` -Refer to the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +Refer to the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -35,8 +27,8 @@ The step ships two configuration files under `src/nemotron/steps/sft/automodel/c | File | Purpose | | --- | --- | -| `default.yaml` | Full-shape training on `Qwen/Qwen3-30B-A3B` with the AutoModel `TrainFinetuneRecipeForNextTokenPrediction` recipe. | -| `tiny.yaml` | Short validation run with five training steps and a 64-record dataset slice from `HuggingFaceH4/ultrachat_200k`. | +| default.yaml | Full-shape training on Qwen/Qwen3-30B-A3B with the AutoModel TrainFinetuneRecipeForNextTokenPrediction recipe. | +| tiny.yaml | Short validation run with five training steps and a 64-record dataset slice from HuggingFaceH4/ultrachat_200k. | Pass either name with `-c`: @@ -49,8 +41,8 @@ $ nemotron steps run sft/automodel -c default | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `training_jsonl` | Yes | Instruction data in JSONL with a `messages` field in OpenAI chat format. | -| Produces | `checkpoint_hf` | — | Hugging Face checkpoint directory. The output is a full model checkpoint when `peft=null`, and a LoRA adapter directory when `peft=lora`. | +| Consumes | training_jsonl | Yes | Instruction data in JSONL with a messages field in OpenAI chat format. | +| Produces | checkpoint_hf | — | Hugging Face checkpoint directory. The output is a full model checkpoint when peft=null, and a LoRA adapter directory when peft=lora. | ## Supported Models @@ -59,9 +51,9 @@ Other Hugging Face causal language models that load through `AutoModelForCausalL | Model | Minimum GPUs | Default | Notes | | --- | --- | --- | --- | -| `Qwen/Qwen3-30B-A3B` | 8 | Yes | Mixture-of-experts (MoE) base model used by `config/default.yaml`. | -| `meta-llama/Llama-3.1-8B-Instruct` | 4 | No | Common dense baseline for single-node SFT and LoRA. | -| `mistralai/Mistral-7B-Instruct-v0.3` | 2 | No | Use this model when GPU count is small or iteration speed matters. | +| Qwen/Qwen3-30B-A3B | 8 | Yes | Mixture-of-experts (MoE) base model used by config/default.yaml. | +| meta-llama/Llama-3.1-8B-Instruct | 4 | No | Common dense baseline for single-node SFT and LoRA. | +| mistralai/Mistral-7B-Instruct-v0.3 | 2 | No | Use this model when GPU count is small or iteration speed matters. | Override the base model from the command line: @@ -75,7 +67,7 @@ $ nemotron steps run sft/automodel -c default \ The manifest declares one Nemotron-specific parameter. Pass it as a dotlist override after the options. -```{option} peft=VALUE +### `peft=VALUE` Selects adapter-style training instead of full fine-tuning. Set this value to `lora` to train a LoRA adapter, or to `null` for full SFT. @@ -85,63 +77,87 @@ Choices: `lora`, `null`. Default: `null`. Example: `peft=lora` -``` You can also override any key from the compiled YAML configuration. The frequently used keys include the following. -```{option} step_scheduler.max_steps=N +--- + +### `max_steps=N` + +```python +step_scheduler.max_steps=N +``` The maximum number of optimizer steps for the run. Example: `step_scheduler.max_steps=200` -``` -```{option} step_scheduler.global_batch_size=N +--- + +### `global_batch_size=N` + +```python +step_scheduler.global_batch_size=N +``` The global batch size across all data-parallel workers. Example: `step_scheduler.global_batch_size=64` -``` -```{option} dataset.path_or_dataset_id= +--- + +### `path_or_dataset_id=` + +```python +dataset.path_or_dataset_id= +``` The Hugging Face dataset identifier or a local path that resolves to a JSONL chat dataset. Example: `dataset.path_or_dataset_id=/data/my-instructions.jsonl` -``` -```{option} checkpoint.checkpoint_dir=PATH +--- + +### `checkpoint_dir=PATH` + +```python +checkpoint.checkpoint_dir=PATH +``` The directory where the AutoModel recipe writes checkpoints. Example: `checkpoint.checkpoint_dir=/output/qwen-sft` -``` ## Strategies The manifest records four operator strategies for `sft/automodel`. - When the run has one or two GPUs, or memory is tight, set `peft=lora` and start from a Mistral-class model. + - When the run has three or four GPUs and the chosen model fits comfortably, consider full fine-tuning only when the resulting checkpoint size and iteration speed remain acceptable. + - When the dataset already uses OpenAI chat-format JSONL, skip `data_prep/sft_packing` and train directly from `training_jsonl`. + - When you need an immediately deployable HF checkpoint, keep the safetensors save format and the consolidated HF output layout that `config/default.yaml` sets. ## Common Errors -```{option} chat_template_missing +--- + +### `chat_template_missing` Cause: the tokenizer for the chosen model does not include a chat template, so the AutoModel recipe cannot render the `messages` field into prompt-and-completion form. Recovery: choose a tokenizer with chat-template support, or convert the data to prompt-and-completion format before training. -``` -```{option} oom +--- + +### `oom` Cause: GPU memory is exhausted during forward or backward passes. Recovery: set `peft=lora`, reduce `step_scheduler.global_batch_size`, or move to a smaller model. -``` ## Command Examples @@ -181,13 +197,18 @@ Run the `nemotron-sft-automodel` skill with your agent. ## Related Documentation -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Choose an SFT Backend](../../how-to/choose-sft-backend.md) compares `sft/automodel` to `sft/megatron_bridge`. -- [Configuration Conventions](../config-conventions.md) describes the per-step `config/` layout. +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Choose an SFT Backend](/../../how-to/choose-sft-backend) compares `sft/automodel` to `sft/megatron_bridge`. + +- [Configuration Conventions](/../config-conventions) describes the per-step `config/` layout. ### Upstream - [NeMo AutoModel Repository](https://github.com/NVIDIA-NeMo/Automodel) + - [NeMo AutoModel Documentation](https://docs.nvidia.com/nemo/automodel/latest/index.html) + - [NeMo AutoModel Fine-Tuning Guide](https://docs.nvidia.com/nemo/automodel/latest/guides/llm/finetune.html) + - [AutoModel Training Script](https://github.com/NVIDIA-NeMo/Automodel/blob/main/nemo_automodel/recipes/llm/train_ft.py) diff --git a/docs/fern/pages-vnightly/train-models/reference/sft/index.mdx b/docs/fern/pages-vnightly/train-models/reference/sft/index.mdx new file mode 100644 index 000000000..0c753cad8 --- /dev/null +++ b/docs/fern/pages-vnightly/train-models/reference/sft/index.mdx @@ -0,0 +1,40 @@ +--- +title: "Supervised Fine-Tuning Steps" +slug: "train-models/reference/sft/index.html" +description: "This section documents the supervised fine-tuning (SFT) steps registered under src/nemotron/steps/sft/. The two steps target different training libraries and consume different data formats. Both produ" +--- + +This section documents the supervised fine-tuning (SFT) steps registered under `src/nemotron/steps/sft/`. +The two steps target different training libraries and consume different data formats. +Both produce checkpoints you can use as warm-start policies for reinforcement learning alignment. + +## Steps + + + +Supervised fine-tuning with the NeMo AutoModel library against Hugging Face base models and JSON Lines chat datasets. + +--- + +reference + + + + +Supervised fine-tuning on top of NVIDIA Megatron-Bridge for distributed training of the Nemotron model family. + +--- + +reference + + + + + +## Related Documentation + +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Choose an SFT Backend](/../../how-to/choose-sft-backend) compares `sft/automodel` and `sft/megatron_bridge`. + +- [Configuration Conventions](/../config-conventions) describes the per-step `config/` layout. diff --git a/docs/train-models/reference/sft/megatron-bridge.md b/docs/fern/pages-vnightly/train-models/reference/sft/megatron-bridge.mdx similarity index 66% rename from docs/train-models/reference/sft/megatron-bridge.md rename to docs/fern/pages-vnightly/train-models/reference/sft/megatron-bridge.mdx index 150a91761..affc5ea65 100644 --- a/docs/train-models/reference/sft/megatron-bridge.md +++ b/docs/fern/pages-vnightly/train-models/reference/sft/megatron-bridge.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Command-line reference for the sft/megatron_bridge training step." -topics: ["Training", "Reference", "CLI", "SFT", "Megatron Bridge"] -tags: ["Reference", "CLI", "Steps", "SFT", "Megatron-Bridge", "Distributed Training"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] +title: "sft/megatron_bridge" +slug: "train-models/reference/sft/megatron-bridge.html" +description: "This step runs supervised fine-tuning (SFT) on a Megatron checkpoint by using NVIDIA Megatron-Bridge. It supports tensor, pipeline, and context parallelism for large-scale distributed training of the " --- -# sft/megatron_bridge - This step runs supervised fine-tuning (SFT) on a Megatron checkpoint by using NVIDIA Megatron-Bridge. It supports tensor, pipeline, and context parallelism for large-scale distributed training of the Nemotron model family. The step consumes packed Apache Parquet shards produced by `data_prep/sft_packing`. @@ -20,15 +12,15 @@ The step consumes packed Apache Parquet shards produced by `data_prep/sft_packin ```bash nemotron steps run sft/megatron_bridge \ - [-c ] \ - [-r | -b ] \ + [-c \] \ + [-r \ | -b \] \ [-d] \ [--force-squash] \ - [...] \ - [...] + [\...] \ + [\...] ``` -See the [Nemotron Steps CLI Reference](../cli-reference.md) for the shared flag set. +See the [Nemotron Steps CLI Reference](/../cli-reference) for the shared flag set. ## Configuration Files @@ -36,9 +28,9 @@ The step ships three configuration files under `src/nemotron/steps/sft/megatron_ | File | Purpose | | --- | --- | -| `default.yaml` | Two-node Slurm functional-test configuration. Loads base weights from Hugging Face via AutoBridge with LoRA enabled (`peft: lora`). Not the programmatic default. | -| `nano3.yaml` | Production full-SFT configuration for the Nano3 model (`peft: null`, 1700 training iterations). This is the programmatic default loaded when no `-c` flag is specified. | -| `tiny.yaml` | Short validation run against packed Parquet shards on a two-node Lepton profile. | +| default.yaml | Two-node Slurm functional-test configuration. Loads base weights from Hugging Face via AutoBridge with LoRA enabled (peft: lora). Not the programmatic default. | +| nano3.yaml | Production full-SFT configuration for the Nano3 model (peft: null, 1700 training iterations). This is the programmatic default loaded when no -c flag is specified. | +| tiny.yaml | Short validation run against packed Parquet shards on a two-node Lepton profile. | Pass the configuration name with `-c`: @@ -51,23 +43,23 @@ $ nemotron steps run sft/megatron_bridge -c default | Direction | Artifact Type | Required | Description | | --- | --- | --- | --- | -| Consumes | `packed_parquet` | Yes | Packed SFT Parquet shards with `input_ids` and `loss_mask` columns. Produce these shards with `data_prep/sft_packing` first. | -| Consumes | `checkpoint_megatron` | No | A pretrained Megatron checkpoint or a prior Megatron SFT checkpoint. When this input is absent, the step loads weights from the Hugging Face model declared by `hf_model_path`. | -| Produces | `checkpoint_megatron` | — | A fine-tuned Megatron distributed checkpoint. | +| Consumes | packed_parquet | Yes | Packed SFT Parquet shards with input_ids and loss_mask columns. Produce these shards with data_prep/sft_packing first. | +| Consumes | checkpoint_megatron | No | A pretrained Megatron checkpoint or a prior Megatron SFT checkpoint. When this input is absent, the step loads weights from the Hugging Face model declared by hf_model_path. | +| Produces | checkpoint_megatron | — | A fine-tuned Megatron distributed checkpoint. | ## Supported Models | Model | Minimum GPUs | Default | Notes | | --- | --- | --- | --- | -| `nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` | 8 | Yes | Nemotron 3 Nano with 31.6 billion total and 3.2 billion active parameters. This model is the default Nano3 path. | -| `nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16` | 32 | No | Nemotron 3 Super with 120.6 billion total and 12.7 billion active parameters. Typical runs start at 32 GPUs. | +| nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16 | 8 | Yes | Nemotron 3 Nano with 31.6 billion total and 3.2 billion active parameters. This model is the default Nano3 path. | +| nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16 | 32 | No | Nemotron 3 Super with 120.6 billion total and 12.7 billion active parameters. Typical runs start at 32 GPUs. | ## Step Parameters The manifest declares two Nemotron-specific parameters. Pass them as dotlist overrides. -```{option} seq_length=N +### `seq_length=N` The training sequence length. This value must match the `pack_size` you used in `data_prep/sft_packing`. @@ -77,9 +69,10 @@ Choices: `2048`, `4096`, `8192`, `16384`, `32768`. Default: `4096`. Example: `seq_length=8192` -``` -```{option} peft=VALUE +--- + +### `peft=VALUE` Selects low-rank adaptation (LoRA) tuning instead of full SFT. Set this value to `lora` for adapter tuning, or to `null` for full fine-tuning when the model and optimizer states fit in memory. @@ -89,78 +82,106 @@ Choices: `lora`, `null`. Default: `null` (as set in `nano3.yaml`, the programmatic default config). The `default.yaml` functional-test config sets this to `lora`. Example: `peft=null` -``` Frequently used dotlist overrides drawn from the underlying recipe include the following. -```{option} hf_model_path= +--- + +### `hf_model_path=` The Hugging Face identifier or local path used to load base weights through `AutoBridge` when no Megatron checkpoint is supplied. Example: `hf_model_path=nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16` -``` -```{option} recipe.tensor_model_parallel_size=N +--- + +### `tensor_model_parallel_size=N` + +```python +recipe.tensor_model_parallel_size=N +``` The tensor-model-parallel degree applied by the Nano3 finetune recipe. Example: `recipe.tensor_model_parallel_size=8` -``` -```{option} recipe.pipeline_model_parallel_size=N +--- + +### `pipeline_model_parallel_size=N` + +```python +recipe.pipeline_model_parallel_size=N +``` The pipeline-model-parallel degree applied by the Nano3 finetune recipe. Example: `recipe.pipeline_model_parallel_size=4` -``` -```{option} train.global_batch_size=N +--- + +### `global_batch_size=N` + +```python +train.global_batch_size=N +``` The global batch size for the training loop. Example: `train.global_batch_size=128` -``` -```{option} checkpoint.save=PATH +--- + +### `save=PATH` + +```python +checkpoint.save=PATH +``` The directory where the Megatron-Bridge recipe writes checkpoints. Example: `checkpoint.save=/lustre/runs/nano3-sft/checkpoints` -``` ## Strategies The manifest records the following operator strategies for `sft/megatron_bridge`. - When the dataset has fewer than ten thousand records, lower `train.global_batch_size` and raise the number of training iterations to keep optimizer steps useful. + - When the operator wants LoRA tuning, set `peft=lora` to lower the GPU requirement and shrink the checkpoint footprint. + - When the operator selects the Super3 model, start from a 32-GPU plan with `tp=8`, `pp=4`, `cp=1`, and verify cluster topology before scaling further. + - When `seq_length > 32768`, enable hybrid context parallelism. + - When GPU memory is tight, such as on A100 40 GB hardware, enable activation checkpointing and consider central-processing-unit (CPU) offloading. + - When you want maximum throughput on H100 hardware, keep packed sequences enabled and tune overlap and sequence-packing settings before scaling up. ## Common Errors -```{option} tokenizer_mismatch +--- + +### `tokenizer_mismatch` Cause: the tokenizer used during `data_prep/sft_packing` differs from the tokenizer used for training, so token identifiers do not align. Recovery: set the `data_prep/sft_packing` tokenizer to match the training model and regenerate the packed Parquet shards. -``` -```{option} oom +--- + +### `oom` Cause: GPU memory is exhausted during forward, backward, or optimizer steps. Recovery: reduce `train.global_batch_size`, increase parallelism, or reduce `seq_length`. -``` -```{option} missing_packed_data +--- + +### `missing_packed_data` Cause: the training loop cannot find packed Parquet shards at the configured `dataset.nano3_packed_sft_dir`. Recovery: run `data_prep/sft_packing` first, or override `dataset.nano3_packed_sft_dir` to point at the directory that holds the packed splits. -``` ## Command Examples @@ -200,13 +221,18 @@ Run the `nemotron-sft-megatron-bridge` skill with your agent. ## Related Documentation -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Choose an SFT Backend](../../how-to/choose-sft-backend.md) compares `sft/megatron_bridge` to `sft/automodel`. -- [Configuration Conventions](../config-conventions.md) describes the per-step `config/` layout. +- [Nemotron Steps CLI Reference](/../cli-reference) covers the shared option set, dotlist overrides, and passthrough arguments. + +- [Choose an SFT Backend](/../../how-to/choose-sft-backend) compares `sft/megatron_bridge` to `sft/automodel`. + +- [Configuration Conventions](/../config-conventions) describes the per-step `config/` layout. ### Upstream - [Megatron-Bridge Repository](https://github.com/NVIDIA-NeMo/Megatron-Bridge) + - [Megatron-Bridge Documentation](https://docs.nvidia.com/nemo/megatron-bridge/latest/) + - [Megatron-Bridge Training Entry Points](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/entry-points.html) + - [Megatron-Bridge Packed Sequences](https://docs.nvidia.com/nemo/megatron-bridge/latest/training/packed-sequences.html) diff --git a/docs/fern/pages-vnightly/train-models/reference/step-catalog.mdx b/docs/fern/pages-vnightly/train-models/reference/step-catalog.mdx new file mode 100644 index 000000000..ac33619bc --- /dev/null +++ b/docs/fern/pages-vnightly/train-models/reference/step-catalog.mdx @@ -0,0 +1,59 @@ +--- +title: "Step Catalog" +slug: "train-models/reference/step-catalog.html" +description: "This page catalogs every training step identifier registered under src/nemotron/steps/ in the sft, peft, rl, and optimize directories. Each row gives the step identifier, the on-disk manifest path, an" +--- + +This page catalogs every training step identifier registered under `src/nemotron/steps/` in the `sft`, `peft`, `rl`, and `optimize` directories. +Each row gives the step identifier, the on-disk manifest path, and the per-step reference page. + +Adjacent preparation and conversion steps do not appear in this catalog. +Those step identifiers include `data_prep/sft_packing`, `data_prep/rl_prep`, and `convert/megatron_to_hf`, and they live under different directories with their own manifests. + +## Supervised Fine-Tuning Steps + +| Step Identifier | Manifest Path | Reference | +| --- | --- | --- | +| sft/automodel | src/nemotron/steps/sft/automodel/step.toml | [sft/automodel](/sft/automodel) | +| sft/megatron_bridge | src/nemotron/steps/sft/megatron_bridge/step.toml | [sft/megatron_bridge](/sft/megatron-bridge) | + +## Parameter-Efficient Fine-Tuning Steps + +| Step Identifier | Manifest Path | Reference | +| --- | --- | --- | +| peft/automodel | src/nemotron/steps/peft/automodel/step.toml | [peft/automodel](/peft/automodel) | +| peft/megatron_bridge | src/nemotron/steps/peft/megatron_bridge/step.toml | [peft/megatron_bridge](/peft/megatron-bridge) | + +## Reinforcement Learning Steps + +| Step Identifier | Manifest Path | Reference | +| --- | --- | --- | +| rl/nemo_rl/dpo | src/nemotron/steps/rl/nemo_rl/dpo/step.toml | [rl/nemo_rl/dpo](/rl/dpo) | +| rl/nemo_rl/rlvr | src/nemotron/steps/rl/nemo_rl/rlvr/step.toml | [rl/nemo_rl/rlvr](/rl/rlvr) | +| rl/nemo_rl/rlhf | src/nemotron/steps/rl/nemo_rl/rlhf/step.toml | [rl/nemo_rl/rlhf](/rl/rlhf) | + +## Optimization Steps + +| Step Identifier | Manifest Path | Reference | +| --- | --- | --- | +| optimize/modelopt/quantize | src/nemotron/steps/optimize/modelopt/quantize/step.toml | [optimize/modelopt/quantize](/optimize/quantize) | +| optimize/modelopt/prune | src/nemotron/steps/optimize/modelopt/prune/step.toml | [optimize/modelopt/prune](/optimize/prune) | +| optimize/modelopt/distill | src/nemotron/steps/optimize/modelopt/distill/step.toml | [optimize/modelopt/distill](/optimize/distill) | + +## List Steps from the Command Line + +This catalog covers the `sft`, `peft`, `rl`, and `optimize` step categories. +Running `nemotron steps list` with no filter returns all registered steps, including data preparation, evaluation, conversion, environment, and other categories not listed here. +Use the `--category`, `--consumes`, and `--produces` filters to narrow the results. + +```console +$ nemotron steps list --category sft +$ nemotron steps list --consumes training_jsonl +$ nemotron steps list --produces checkpoint_megatron --json +``` + +## Related Documentation + +- [Nemotron Steps CLI Reference](/cli-reference) covers the `list`, `show`, and `run` subcommands. + +- [Configuration Conventions](/config-conventions) describes the per-step `config/` layout. diff --git a/docs/train-models/using-skill.md b/docs/fern/pages-vnightly/train-models/using-skill.mdx similarity index 59% rename from docs/train-models/using-skill.md rename to docs/fern/pages-vnightly/train-models/using-skill.mdx index 60e18f7f7..e9693b6ce 100644 --- a/docs/train-models/using-skill.md +++ b/docs/fern/pages-vnightly/train-models/using-skill.mdx @@ -1,4 +1,8 @@ -# Tips for Model Training with Agents +--- +title: "Tips for Model Training with Agents" +slug: "train-models/using-skill.html" +description: "You might want to add instruction following, specialize a model on your domain or product voice, align behavior with preferences after supervised fine tuning, or land on a smaller or faster model thro" +--- ## Have a Goal in Mind @@ -25,52 +29,51 @@ The nested lines are example sentences you can paste or adapt; they are not the - Desired outcome in plain language, so the agent can narrow the stage chain and success checks. - :::{div} sd-font-italic sd-font-weight-lighter - - "We want the model to follow our runbook-style instructions on support tickets without drifting into free-form guesses when the ticket is incomplete." - - "After training, reviewers should see fewer policy violations on a fixed red-team prompt set we already use in evaluation." - ::: + - “We want the model to follow our runbook-style instructions on support tickets without drifting into free-form guesses when the ticket is incomplete.” + + - “After training, reviewers should see fewer policy violations on a fixed red-team prompt set we already use in evaluation.” - Rough stage story when you already know it (for example SFT then alignment), or an explicit note that you want a recommendation, so the agent does not guess your pipeline shape. - :::{div} sd-font-italic sd-font-weight-lighter - - "We already ran SFT in another team’s repo; from here we only need alignment on preference data against that checkpoint." - - "We do not know the right order; recommend a minimal path from the catalog given our data and hardware." - ::: + - “We already ran SFT in another team’s repo; from here we only need alignment on preference data against that checkpoint.” + + - “We do not know the right order; recommend a minimal path from the catalog given our data and hardware.” - Where inputs live, paths or Hugging Face Hub datasets, and what you call the starting weights, so manifests and `consumes` edges can line up without invented paths. - :::{div} sd-font-italic sd-font-weight-lighter - - "Training chat lives at `/data/support/train.jsonl` on the shared file system. The evaluation JSONL is next to it under `eval.jsonl`." - - "Base weights are `organization/model-name` on the Hugging Face Hub. We have a local cache under `/scratch/hf-cache`." - ::: + - “Training chat lives at `/data/support/train.jsonl` on the shared file system. The evaluation JSONL is next to it under `eval.jsonl`.” + + - “Base weights are `organization/model-name` on the Hugging Face Hub. We have a local cache under `/scratch/hf-cache`.” - Hardware you schedule against at least at nodes, GPUs per node, and GPU family, so scale and parallelism assumptions stay realistic. - :::{div} sd-font-italic sd-font-weight-lighter - - "We can schedule up to four nodes with eight H100 GPUs per node in Lepton for training; prefer fewer nodes if the step supports it cleanly." - - "Slurm jobs must write checkpoints under `/project/checkpoints/$USER/run-id` so retention policies pick them up." - ::: + - “We can schedule up to four nodes with eight H100 GPUs per node in Lepton for training; prefer fewer nodes if the step supports it cleanly.” + + - “Slurm jobs must write checkpoints under `/project/checkpoints/$USER/run-id` so retention policies pick them up.” You do not need step identifiers or perfect file formats before you start if you are willing to discover those with the agent in the next block. ### Fine to Clarify During the Session -The skill uses an _orient phase_ so that you and the agent can tighten these together. +The skill uses an *orient phase* so that you and the agent can tighten these together. + +- How your data layout lines up with what a chosen step expects, using [Data and Checkpoint Formats](/how-to/data-and-checkpoint-formats) and the step’s `step.toml` as you go. + +- Backend choice inside a family, using [Choose an SFT Backend](/how-to/choose-sft-backend), [Choose a PEFT Backend](/how-to/choose-peft-backend), or [Choose an RL Alignment Step](/how-to/choose-rl-step) when you want a human-readable decision before configs land. -- How your data layout lines up with what a chosen step expects, using [Data and Checkpoint Formats](how-to/data-and-checkpoint-formats.md) and the step’s `step.toml` as you go. -- Backend choice inside a family, using [Choose an SFT Backend](how-to/choose-sft-backend.md), [Choose a PEFT Backend](how-to/choose-peft-backend.md), or [Choose an RL Alignment Step](how-to/choose-rl-step.md) when you want a human-readable decision before configs land. - Whether the first execution should validate end-to-end execution with a short sample run or target production-scale training, so defaults match intent. + - Tokenizer, template, and sequence-length consistency across prep and train when the pipeline touches more than one stage. ### Where to Look When You Are Unsure -Use the [How-To Guides](how-to/index.md) for task-level procedures. -Use [Reference](reference/index.md) for naming and configuration conventions. -Use [Explanation](explanation/index.md) for how artifacts and libraries fit together. +Use the [How-To Guides](/how-to/index) for task-level procedures. +Use [Reference](/reference/index) for naming and configuration conventions. +Use [Explanation](/explanation/index) for how artifacts and libraries fit together. You can also ask the agent to walk a specific step with `nemotron steps show` once you know its name. ## Your Role in the Loop -The skill follows _orient_, _plan_, _act_, and then _verify_. +The skill follows *orient*, *plan*, *act*, and then *verify*. You answer missing constraints, approve the plan before files change, and check that stage outputs line up with the next stage’s inputs. `SKILL.md` spells out each phase, file naming, and verification expectations for the whole catalog, not only training. diff --git a/docs/translation/explanation/faith-evaluation.md b/docs/fern/pages-vnightly/translation/explanation/faith-evaluation.mdx similarity index 76% rename from docs/translation/explanation/faith-evaluation.md rename to docs/fern/pages-vnightly/translation/explanation/faith-evaluation.mdx index 052f64536..f52ee8b85 100644 --- a/docs/translation/explanation/faith-evaluation.md +++ b/docs/fern/pages-vnightly/translation/explanation/faith-evaluation.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "How FAITH integrates into nemotron steps run translate/nemo_curator and interacts with translation backends." -topics: ["Translation", "FAITH"] -tags: ["Explanation", "Quality"] -content: - type: "Explanation" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] +title: "FAITH Evaluation Inside Translation" +slug: "translation/explanation/faith-evaluation.html" +description: "This page explains how optional FAITH scoring behaves when faith_eval.enabled is true inside nemotron steps run translate/nemo_curator. FAITH stands for the five quality dimensions the judge scores ag" --- -# FAITH Evaluation Inside Translation - This page explains how optional FAITH scoring behaves when `faith_eval.enabled` is `true` inside `nemotron steps run translate/nemo_curator`. FAITH stands for the five quality dimensions the judge scores against each translated segment: *Fluency*, *Accuracy*, *Idiomaticity*, *Terminology*, and *Handling of Format*. @@ -22,7 +14,9 @@ FAITH runs in the same `TranslationStage` invocation as translation. There is no FAITH scores translation quality segment-by-segment using a large language model (LLM) judge configured alongside your translation backend: - `faith_eval.threshold` defines the minimum acceptable average score. The starter default is `2.5`, which you should tune per model. See the next section for what the scale means. -- FAITH scoring follows the translated segment pairs produced by Curator's translation stage for long inputs. + +- FAITH scoring follows the translated segment pairs produced by Curator’s translation stage for long inputs. + - `faith_eval.filter_enabled` drops failing rows when `true`, which lets you keep high-confidence shards only. ## Score Scale @@ -51,11 +45,11 @@ A score of `0` means the dimension does not apply to the row, for example Termin A score of `-1` means the judge received no translation to evaluate. The `faith_avg` column is the mean of the dimensions that scored above zero. -Dimensions marked `0` for "not applicable" are excluded from the average, so a translation with no specialized terminology can still earn a perfect `faith_avg` of `5.0`. +Dimensions marked `0` for “not applicable” are excluded from the average, so a translation with no specialized terminology can still earn a perfect `faith_avg` of `5.0`. If every dimension is `0` or `-1`, `faith_avg` is `0.0`. Filtering keeps a row when `faith_avg >= faith_eval.threshold`, with parse failures preserved so reviewers can audit them. -The starter default `2.5` sits between band two, "major grammatical issues," and band three, "generally fluent with a few errors." +The starter default `2.5` sits between band two, “major grammatical issues,” and band three, “generally fluent with a few errors.” Treat `2.5` as a noisy-data floor rather than a quality bar. Raise the threshold when you want a tighter quality gate, for example to `3.5` when you are building a high-confidence parallel corpus. @@ -71,9 +65,10 @@ Even if `backend` is `nmt`, `google`, or `aws`, FAITH still issues LLM calls. Pl ## Related YAML Surface -See `faith_eval` in {doc}`../reference/translate-config` and operational recipes in {doc}`../how-to/run-faith-evaluation`. +See `faith_eval` in [Translation YAML Reference](/../reference/translate-config) and operational recipes in [Run FAITH Evaluation](/../how-to/run-faith-evaluation). ## Related Pages -- Where FAITH sits in the pipeline: {doc}`pipeline-overview` -- Input and output shapes when scores merge or filter: {doc}`../reference/io-format` +- Where FAITH sits in the pipeline: [Pipeline Overview](/pipeline-overview) + +- Input and output shapes when scores merge or filter: [Input and Output Format](/../reference/io-format) diff --git a/docs/fern/pages-vnightly/translation/explanation/index.mdx b/docs/fern/pages-vnightly/translation/explanation/index.mdx new file mode 100644 index 000000000..8017ad4f5 --- /dev/null +++ b/docs/fern/pages-vnightly/translation/explanation/index.mdx @@ -0,0 +1,46 @@ +--- +title: "Concepts" +slug: "translation/explanation/index.html" +description: "Background on how the translation pipeline fits together, how segmentation behaves, and what FAITH measures. Use these pages when how-to steps refer to behavior you want to understand before changing " +--- + +Background on how the translation pipeline fits together, how segmentation behaves, and what FAITH measures. Use these pages when how-to steps refer to behavior you want to understand before changing defaults. + +Concept-focused explanations for `nemotron steps run translate/nemo_curator` and the `translate/nemo_curator` Curator pipeline. + +## Pipeline Processing + + + +Reader to `TranslationStage` to writer, with an optional FAITH branch. + +--- + +architecture + + + + +Coarse versus fine `segmentation_mode` trade-offs. + +--- + +segmentation + + + + + +## Evaluation Inside Translation + + + +What FAITH captures when `faith_eval.enabled` is true. + +--- + +faith + + + + diff --git a/docs/translation/explanation/pipeline-overview.md b/docs/fern/pages-vnightly/translation/explanation/pipeline-overview.mdx similarity index 74% rename from docs/translation/explanation/pipeline-overview.md rename to docs/fern/pages-vnightly/translation/explanation/pipeline-overview.mdx index 4005c9eef..efedb6bc0 100644 --- a/docs/translation/explanation/pipeline-overview.md +++ b/docs/fern/pages-vnightly/translation/explanation/pipeline-overview.mdx @@ -1,22 +1,14 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "How nemotron steps run translate/nemo_curator flows through Curator readers, TranslationStage, writers, and FAITH." -topics: ["Translation", "Pipeline"] -tags: ["Explanation", "Architecture"] -content: - type: "Explanation" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] +title: "Pipeline Overview" +slug: "translation/explanation/pipeline-overview.html" +description: "This page describes how nemotron steps run translate/nemo_curator moves records from input_path into output_dir by using NVIDIA NeMo Curator staging primitives." --- -# Pipeline Overview - This page describes how `nemotron steps run translate/nemo_curator` moves records from `input_path` into `output_dir` by using NVIDIA NeMo Curator staging primitives. ## Architecture -```{mermaid} +```mermaid flowchart LR A[input_path] --> B[Reader] B --> C[TranslationStage] @@ -31,6 +23,7 @@ flowchart LR ## Reader Stage 1. Format detection follows `input_format`, which may be `auto`, `jsonl`, or `parquet`. + 2. Paths may be a single file, a glob, or a homogeneous directory of shards. Never mix JSON Lines (JSONL) and Parquet in one directory when `auto` is active. ## Translation Stage @@ -38,7 +31,9 @@ flowchart LR `TranslationStage` performs backend-specific translation for every location matched by `text_field`, for example `messages.*.content` wildcards inside chat arrays. - `backend` selects `llm`, `nmt`, `google`, or `aws`. + - `segmentation_mode` chooses coarse versus fine segmentation before translation units leave the stage. + - `output_mode` controls whether replaced fields, raw metadata, or both appear on each record. ## Writer Stage @@ -52,11 +47,15 @@ When `faith_eval.enabled` is true the stage keeps an OpenAI-compatible client ev ## Operational Reminders - Translation failures surface as runtime errors from Curator. Rerun with smaller concurrency if providers throttle you. + - Extremely large single files may require an offline splitting stage. Mirror the guardrails codified in `step.toml`. ## Related Pages -- Hands-on first run: {doc}`../getting-started` -- Segmentation behavior: {doc}`segmentation` -- FAITH semantics: {doc}`faith-evaluation` -- YAML keyed to this flow: {doc}`../reference/translate-config` +- Hands-on first run: [Getting Started With Translation](/../getting-started) + +- Segmentation behavior: [Segmentation](/segmentation) + +- FAITH semantics: [FAITH Evaluation Inside Translation](/faith-evaluation) + +- YAML keyed to this flow: [Translation YAML Reference](/../reference/translate-config) diff --git a/docs/fern/pages-vnightly/translation/explanation/segmentation.mdx b/docs/fern/pages-vnightly/translation/explanation/segmentation.mdx new file mode 100644 index 000000000..f5a04e0e0 --- /dev/null +++ b/docs/fern/pages-vnightly/translation/explanation/segmentation.mdx @@ -0,0 +1,44 @@ +--- +title: "Segmentation" +slug: "translation/explanation/segmentation.html" +description: "This page helps you pick segmentation_mode values that keep translations faithful without chopping structured payloads." +--- + +This page helps you pick `segmentation_mode` values that keep translations faithful without chopping structured payloads. + +## Controls + +| YAML key | Meaning | +| --- | --- | +| segmentation_mode | coarse is the default. It balances throughput while respecting code fences and markup boundaries. fine emits smaller linguistic segments when coarse spans truncate meaning. | +| min_segment_chars | Skips extremely short fragments that harm throughput or confuse backends. The default is 0, which disables filtering. | + +## When Coarse Is Enough + +Start with `segmentation_mode: coarse` when records contain JSON-like strings, tool arguments, or fenced code blocks. Coarse mode tracks reconstruction metadata so `TranslationStage` can rebuild the original nesting after translating natural-language spans. + +## When to Switch to Fine + +Move to `segmentation_mode: fine` when you observe clipped sentences, missing trailing punctuation, or uneven translations inside long paragraphs, and you have confirmed the issue disappears after finer segmentation. + +Fine mode increases API calls or neural machine translation (NMT) batches. Budget concurrency by using `max_concurrent_requests` or backend-specific knobs. + +## Interaction With FAITH + +FAITH scoring is part of Curator’s translation stage and follows the translated segment pairs produced by the stage, which keeps thresholds interpretable on long documents. + +## Practical Workflow + +1. Run with `coarse` first. + +2. Inspect a handful of difficult rows such as legal text, mixed Markdown, or multilingual snippets. + +3. If boundaries look wrong, toggle `fine` on a slice before scaling up. + +## Related Pages + +- Step-by-step fine mode: [Use Fine Segmentation](/../how-to/use-fine-segmentation) + +- Pipeline context: [Pipeline Overview](/pipeline-overview) + +- FAITH alignment with segments: [FAITH Evaluation Inside Translation](/faith-evaluation) diff --git a/docs/fern/pages-vnightly/translation/getting-started.mdx b/docs/fern/pages-vnightly/translation/getting-started.mdx new file mode 100644 index 000000000..b195c041d --- /dev/null +++ b/docs/fern/pages-vnightly/translation/getting-started.mdx @@ -0,0 +1,604 @@ +--- +title: "Getting Started With Translation" +slug: "translation/getting-started.html" +description: "You will produce translated JSON Lines (JSONL) shards under an output_dir you choose, with FAITH quality scoring applied in the same run. FAITH is the translation-quality scorer name used in NVIDIA Ne" +--- + + + +You will produce translated JSON Lines (JSONL) shards under an `output_dir` you choose, with FAITH quality scoring applied in the same run. FAITH is the translation-quality scorer name used in NVIDIA NeMo Curator documentation. + +This tutorial runs `nemotron steps run translate/nemo_curator` end to end on a small sample file. You use `src/nemotron/steps/translate/nemo_curator/config/default.yaml` and CLI dotlist overrides. + + +Overview + +1. Export `NVIDIA_API_KEY`. + +2. Download the sample `train_sample.jsonl` chat file. + +3. Run `nemotron steps run translate/nemo_curator -c default` with CLI overrides for paths, languages, and `server.model`. + +4. Inspect `output_dir` for translated records. + + Budget roughly five to fifteen minutes depending on network latency and response time from your provider and on corpus size. +The sample contains about one hundred lines. + + + +## Prerequisites + +- Network access to `https://integrate.api.nvidia.com/v1`. + +- `NVIDIA_API_KEY` exported in your shell. + +- For local `uv run` execution with Curator/Ray, export `RAY_ENABLE_UV_RUN_RUNTIME_ENV=0` +so Ray workers reuse the synchronized project environment. + +## Sample Input File + +This translation tutorial uses `train_sample.jsonl` as a compact multi-turn chat dataset. + +```json startLine={1} +{"messages": [{"role": "system", "content": "You are a helpful assistant with access to weather information."}, {"role": "user", "content": "What's the weather in Tokyo?"}, {"role": "assistant", "tool_calls": [{"id": "weather_5854", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\": \"Tokyo\", \"units\": \"fahrenheit\"}"}}], "content": ""}, {"role": "tool", "tool_call_id": "weather_5854", "content": "{\"temp\": 72, \"condition\": \"sunny\", \"humidity\": 45}"}, {"role": "assistant", "content": "The weather in Tokyo is sunny with a temperature of 72\u00b0F and 45% humidity."}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Get current weather for a location", "parameters": {"type": "object", "properties": {"location": {"type": "string"}, "units": {"type": "string"}}, "required": ["location"]}}}]} +{"messages": [{"role": "system", "content": "You are a database assistant."}, {"role": "user", "content": "Find all users from California"}, {"role": "assistant", "tool_calls": [{"id": "db_2329", "type": "function", "function": {"name": "query_database", "arguments": "{\"query\": \"Find all users from California\"}"}}], "content": ""}, {"role": "tool", "tool_call_id": "db_2329", "content": "[{\"id\": 1, \"name\": \"John Doe\", \"state\": \"CA\"}, {\"id\": 5, \"name\": \"Jane Smith\", \"state\": \"CA\"}]"}, {"role": "assistant", "content": "Here's what I found: [{\"id\": 1, \"name\": \"John Doe\", \"state\": \"CA\"}, {\"id\": 5, \"name\": \"Jane Smith\", \"state\": \"CA\"}]"}], "tools": [{"type": "function", "function": {"name": "query_database", "description": "Query the database", "parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}]} +{"messages": [{"role": "system", "content": "You are a calculator assistant."}, {"role": "user", "content": "What is 156 * 24?"}, {"role": "assistant", "tool_calls": [{"id": "calc_8712", "type": "function", "function": {"name": "calculate", "arguments": "{\"expression\": \"156 * 24\"}"}}], "content": ""}, {"role": "tool", "tool_call_id": "calc_8712", "content": "3744"}, {"role": "assistant", "content": "The result of 156 * 24 is 3744."}], "tools": [{"type": "function", "function": {"name": "calculate", "description": "Perform mathematical calculation", "parameters": {"type": "object", "properties": {"expression": {"type": "string"}}, "required": ["expression"]}}}]} +{"messages": [{"role": "system", "content": "You are a database assistant."}, {"role": "user", "content": "Get product by ID 12345"}, {"role": "assistant", "tool_calls": [{"id": "db_7995", "type": "function", "function": {"name": "query_database", "arguments": "{\"query\": \"Get product by ID 12345\"}"}}], "content": ""}, {"role": "tool", "tool_call_id": "db_7995", "content": "{\"id\": 12345, \"name\": \"Laptop\", \"price\": 999.99}"}, {"role": "assistant", "content": "Here's what I found: {\"id\": 12345, \"name\": \"Laptop\", \"price\": 999.99}"}], "tools": [{"type": "function", "function": {"name": "query_database", "description": "Query the database", "parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}]} +{"messages": [{"role": "system", "content": "You are a helpful assistant with access to weather information."}, {"role": "user", "content": "What's the weather in Dubai?"}, {"role": "assistant", "tool_calls": [{"id": "weather_8882", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\": \"Dubai\", \"units\": \"fahrenheit\"}"}}], "content": ""}, {"role": "tool", "tool_call_id": "weather_8882", "content": "{\"temp\": 55, \"condition\": \"rainy\", \"humidity\": 80}"}, {"role": "assistant", "content": "The weather in Dubai is rainy with a temperature of 55\u00b0F and 80% humidity."}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Get current weather for a location", "parameters": {"type": "object", "properties": {"location": {"type": "string"}, "units": {"type": "string"}}, "required": ["location"]}}}]} +``` + +## Procedure + +1. Clone the repository, if you haven’t already: + + ```console + $ git clone https://github.com/NVIDIA-NeMo/Nemotron && cd Nemotron + ``` + +1. Synchronize the dependencies: + + ```console + $ uv sync --extra translate + ``` + +1. Download `train_sample.jsonl` from the sample file. + + Save the file in the repository root if you want to match the `input_path` below exactly. If you save it elsewhere, change `input_path` in the commands that follow. + +1. Run the translation stage. + + From the repository root, specify the `default.yaml` config and overrides by using CLI arguments. +Set `server.model` to a model your endpoint serves. +Replace `` with your NVIDIA API key value, or set `NVIDIA_API_KEY` in your environment before running the command. + + ```console + $ export NVIDIA_API_KEY="\" + $ export RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 + + $ uv run --no-sync nemotron steps run translate/nemo_curator -c default \ + input_path="$\{PWD\}/train_sample.jsonl" \ + output_dir=./output/translation-getting-started \ + source_language=en \ + target_language=hi \ + server.model=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning \ + faith_eval.enabled=false \ + faith_eval.filter_enabled=false \ + max_concurrent_requests=4 + ``` + + - `input_path` and `output_dir` replace the placeholders in `default.yaml`. + + - `source_language` and `target_language` must be explicit two-letter language codes from the ISO 639-1 standard, which the International Organization for Standardization publishes. + + The starter file leaves them empty on purpose so you choose the pair at run time. + + - `server.model` is required when `backend` is `llm`. + + The default `server.url` in `default.yaml` is `https://integrate.api.nvidia.com/v1`. + +1. Inspect the output. + + The `output_dir` path holds the Curator writer output when `output_format` is `jsonl`, usually several shard files instead of one consolidated JSONL file. +Spot-check one line. + + ```console + $ find ./output/translation-getting-started -name '*.jsonl' | head -n 1 | xargs head -n 1 | python3 -m json.tool --no-ensure-ascii + ``` + + Translated chat payloads match `text_field` set to `messages.*.content`, `output_mode` set to `both`, and `reconstruct_messages` set to `true` in `default.yaml`. + + ```json startLine={1} + { + "messages": [ + { + "role": "system", + "content": "[आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।]" + }, + { + "role": "user", + "content": "[टोक्यो में मौसम कैसा है?]" + }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "weather_5854", + "type": "function", + "function": { + "name": "get_weather", + "arguments": "{\"location\": \"Tokyo\", \"units\": \"fahrenheit\"}" + } + } + ], + "content": "" + }, + { + "role": "tool", + "tool_call_id": "weather_5854", + "content": "{\"temp\": 72, \"condition\": \"sunny\", \"humidity\": 45}" + }, + { + "role": "assistant", + "content": "टोक्यो में मौसम धूपभरा है, 72°F का तापमान और 45% आर्द्रता के साथ।" + } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "get_weather", + "description": "Get current weather for a location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string" + }, + "units": { + "type": "string" + } + }, + "required": [ + "location" + ] + } + } + } + ], + "translation_time": 8.9217984676, + "translation_errors": "", + "translated_text": [ + { + "role": "system", + "content": "[आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।]" + }, + { + "role": "user", + "content": "[टोक्यो में मौसम कैसा है?]" + }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "weather_5854", + "type": "function", + "function": { + "name": "get_weather", + "arguments": "{\"location\": \"Tokyo\", \"units\": \"fahrenheit\"}" + } + } + ], + "content": "" + }, + { + "role": "tool", + "tool_call_id": "weather_5854", + "content": "{\"temp\": 72, \"condition\": \"sunny\", \"humidity\": 45}" + }, + { + "role": "assistant", + "content": "टोक्यो में मौसम धूपभरा है, 72°F का तापमान और 45% आर्द्रता के साथ।" + } + ], + "translation_metadata": "{\"target_lang\": \"hi\", \"translation\": {\"content\": [\"[आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।]\", \"[टोक्यो में मौसम कैसा है?]\", \"\", \"{\\\"temp\\\": 72, \\\"condition\\\": \\\"sunny\\\", \\\"humidity\\\": 45}\", \"टोक्यो में मौसम धूपभरा है, 72°F का तापमान और 45% आर्द्रता के साथ।\"]}, \"segmented_translation\": {\"content\": [{\"src\": \"You are a helpful assistant with access to weather information.\", \"tgt\": \"[आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।]\"}, {\"src\": \"What's the weather in Tokyo?\", \"tgt\": \"[टोक्यो में मौसम कैसा है?]\"}, {\"src\": \"The weather in Tokyo is sunny with a temperature of 72°F and 45% humidity.\", \"tgt\": \"टोक्यो में मौसम धूपभरा है, 72°F का तापमान और 45% आर्द्रता के साथ।\"}]}}", + "translated_messages": "[{\"role\": \"system\", \"content\": \"[आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।]\"}, {\"role\": \"user\", \"content\": \"[टोक्यो में मौसम कैसा है?]\"}, {\"role\": \"assistant\", \"tool_calls\": [{\"id\": \"weather_5854\", \"type\": \"function\", \"function\": {\"name\": \"get_weather\", \"arguments\": \"{\\\"location\\\": \\\"Tokyo\\\", \\\"units\\\": \\\"fahrenheit\\\"}\"}}], \"content\": \"\"}, {\"role\": \"tool\", \"tool_call_id\": \"weather_5854\", \"content\": \"{\\\"temp\\\": 72, \\\"condition\\\": \\\"sunny\\\", \\\"humidity\\\": 45}\"}, {\"role\": \"assistant\", \"content\": \"टोक्यो में मौसम धूपभरा है, 72°F का तापमान और 45% आर्द्रता के साथ।\"}]" + } + { + "messages": [ + { + "role": "system", + "content": "आप एक डेटाबेस सहायक हैं।" + }, + { + "role": "user", + "content": "सभी कैलिफोर्निया से उपयोगकर्ताओं को खोजें" + }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "db_2329", + "type": "function", + "function": { + "name": "query_database", + "arguments": "{\"query\": \"Find all users from California\"}" + } + } + ], + "content": "" + }, + { + "role": "tool", + "tool_call_id": "db_2329", + "content": "[{\"id\": 1, \"name\": \"John Doe\", \"state\": \"CA\"}, {\"id\": 5, \"name\": \"Jane Smith\", \"state\": \"CA\"}]" + }, + { + "role": "assistant", + "content": "यहाँ क्या मिला: [{\"id\": 1, \"name\": \"John Doe\", \"state\": \"CA\"}, {\"id\": 5, \"name\": \"Jane Smith\", \"state\": \"CA\"}]" + } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "query_database", + "description": "Query the database", + "parameters": { + "type": "object", + "properties": { + "query": { + "type": "string" + } + }, + "required": [ + "query" + ] + } + } + } + ], + "translation_time": 18.4458503723, + "translation_errors": "", + "translated_text": [ + { + "role": "system", + "content": "आप एक डेटाबेस सहायक हैं।" + }, + { + "role": "user", + "content": "सभी कैलिफोर्निया से उपयोगकर्ताओं को खोजें" + }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "db_2329", + "type": "function", + "function": { + "name": "query_database", + "arguments": "{\"query\": \"Find all users from California\"}" + } + } + ], + "content": "" + }, + { + "role": "tool", + "tool_call_id": "db_2329", + "content": "[{\"id\": 1, \"name\": \"John Doe\", \"state\": \"CA\"}, {\"id\": 5, \"name\": \"Jane Smith\", \"state\": \"CA\"}]" + }, + { + "role": "assistant", + "content": "यहाँ क्या मिला: [{\"id\": 1, \"name\": \"John Doe\", \"state\": \"CA\"}, {\"id\": 5, \"name\": \"Jane Smith\", \"state\": \"CA\"}]" + } + ], + "translation_metadata": "{\"target_lang\": \"hi\", \"translation\": {\"content\": [\"आप एक डेटाबेस सहायक हैं।\", \"सभी कैलिफोर्निया से उपयोगकर्ताओं को खोजें\", \"\", \"[{\\\"id\\\": 1, \\\"name\\\": \\\"John Doe\\\", \\\"state\\\": \\\"CA\\\"}, {\\\"id\\\": 5, \\\"name\\\": \\\"Jane Smith\\\", \\\"state\\\": \\\"CA\\\"}]\", \"यहाँ क्या मिला: [{\\\"id\\\": 1, \\\"name\\\": \\\"John Doe\\\", \\\"state\\\": \\\"CA\\\"}, {\\\"id\\\": 5, \\\"name\\\": \\\"Jane Smith\\\", \\\"state\\\": \\\"CA\\\"}]\"]}, \"segmented_translation\": {\"content\": [{\"src\": \"You are a database assistant.\", \"tgt\": \"आप एक डेटाबेस सहायक हैं।\"}, {\"src\": \"Find all users from California\", \"tgt\": \"सभी कैलिफोर्निया से उपयोगकर्ताओं को खोजें\"}, {\"src\": \"Here's what I found: [{\\\"id\\\": 1, \\\"name\\\": \\\"John Doe\\\", \\\"state\\\": \\\"CA\\\"}, {\\\"id\\\": 5, \\\"name\\\": \\\"Jane Smith\\\", \\\"state\\\": \\\"CA\\\"}]\", \"tgt\": \"यहाँ क्या मिला: [{\\\"id\\\": 1, \\\"name\\\": \\\"John Doe\\\", \\\"state\\\": \\\"CA\\\"}, {\\\"id\\\": 5, \\\"name\\\": \\\"Jane Smith\\\", \\\"state\\\": \\\"CA\\\"}]\"}]}}", + "translated_messages": "[{\"role\": \"system\", \"content\": \"आप एक डेटाबेस सहायक हैं।\"}, {\"role\": \"user\", \"content\": \"सभी कैलिफोर्निया से उपयोगकर्ताओं को खोजें\"}, {\"role\": \"assistant\", \"tool_calls\": [{\"id\": \"db_2329\", \"type\": \"function\", \"function\": {\"name\": \"query_database\", \"arguments\": \"{\\\"query\\\": \\\"Find all users from California\\\"}\"}}], \"content\": \"\"}, {\"role\": \"tool\", \"tool_call_id\": \"db_2329\", \"content\": \"[{\\\"id\\\": 1, \\\"name\\\": \\\"John Doe\\\", \\\"state\\\": \\\"CA\\\"}, {\\\"id\\\": 5, \\\"name\\\": \\\"Jane Smith\\\", \\\"state\\\": \\\"CA\\\"}]\"}, {\"role\": \"assistant\", \"content\": \"यहाँ क्या मिला: [{\\\"id\\\": 1, \\\"name\\\": \\\"John Doe\\\", \\\"state\\\": \\\"CA\\\"}, {\\\"id\\\": 5, \\\"name\\\": \\\"Jane Smith\\\", \\\"state\\\": \\\"CA\\\"}]\"}]" + } + { + "messages": [ + { + "role": "system", + "content": "[आप एक कैलकुलेटर सहायक हैं।]" + }, + { + "role": "user", + "content": "[क्या 156 * 24 है?]" + }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "calc_8712", + "type": "function", + "function": { + "name": "calculate", + "arguments": "{\"expression\": \"156 * 24\"}" + } + } + ], + "content": "" + }, + { + "role": "tool", + "tool_call_id": "calc_8712", + "content": "3744" + }, + { + "role": "assistant", + "content": "156 * 24 का परिणाम 3744 है।" + } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "calculate", + "description": "Perform mathematical calculation", + "parameters": { + "type": "object", + "properties": { + "expression": { + "type": "string" + } + }, + "required": [ + "expression" + ] + } + } + } + ], + "translation_time": 34.5283660889, + "translation_errors": "", + "translated_text": [ + { + "role": "system", + "content": "[आप एक कैलकुलेटर सहायक हैं।]" + }, + { + "role": "user", + "content": "[क्या 156 * 24 है?]" + }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "calc_8712", + "type": "function", + "function": { + "name": "calculate", + "arguments": "{\"expression\": \"156 * 24\"}" + } + } + ], + "content": "" + }, + { + "role": "tool", + "tool_call_id": "calc_8712", + "content": "3744" + }, + { + "role": "assistant", + "content": "156 * 24 का परिणाम 3744 है।" + } + ], + "translation_metadata": "{\"target_lang\": \"hi\", \"translation\": {\"content\": [\"[आप एक कैलकुलेटर सहायक हैं।]\", \"[क्या 156 * 24 है?]\", \"\", \"3744\", \"156 * 24 का परिणाम 3744 है।\"]}, \"segmented_translation\": {\"content\": [{\"src\": \"You are a calculator assistant.\", \"tgt\": \"[आप एक कैलकुलेटर सहायक हैं।]\"}, {\"src\": \"What is 156 * 24?\", \"tgt\": \"[क्या 156 * 24 है?]\"}, {\"src\": \"The result of 156 * 24 is 3744.\", \"tgt\": \"156 * 24 का परिणाम 3744 है।\"}]}}", + "translated_messages": "[{\"role\": \"system\", \"content\": \"[आप एक कैलकुलेटर सहायक हैं।]\"}, {\"role\": \"user\", \"content\": \"[क्या 156 * 24 है?]\"}, {\"role\": \"assistant\", \"tool_calls\": [{\"id\": \"calc_8712\", \"type\": \"function\", \"function\": {\"name\": \"calculate\", \"arguments\": \"{\\\"expression\\\": \\\"156 * 24\\\"}\"}}], \"content\": \"\"}, {\"role\": \"tool\", \"tool_call_id\": \"calc_8712\", \"content\": \"3744\"}, {\"role\": \"assistant\", \"content\": \"156 * 24 का परिणाम 3744 है।\"}]" + } + { + "messages": [ + { + "role": "system", + "content": "[आप एक डेटाबेस सहायक हैं।]" + }, + { + "role": "user", + "content": "3. Copy the content as-is.\n```python\ndef calculate_sum(a, b):\n return a + b\n```" + }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "db_7995", + "type": "function", + "function": { + "name": "query_database", + "arguments": "{\"query\": \"Get product by ID 12345\"}" + } + } + ], + "content": "" + }, + { + "role": "tool", + "tool_call_id": "db_7995", + "content": "{\"id\": 12345, \"name\": \"Laptop\", \"price\": 999.99}" + }, + { + "role": "assistant", + "content": "यहाँ क्या मिला: {\"id\": 12345, \"name\": \"Laptop\", \"price\": 999.99}" + } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "query_database", + "description": "Query the database", + "parameters": { + "type": "object", + "properties": { + "query": { + "type": "string" + } + }, + "required": [ + "query" + ] + } + } + } + ], + "translation_time": 39.8996043205, + "translation_errors": "", + "translated_text": [ + { + "role": "system", + "content": "[आप एक डेटाबेस सहायक हैं।]" + }, + { + "role": "user", + "content": "3. Copy the content as-is.\n```python\ndef calculate_sum(a, b):\n return a + b\n```" + }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "db_7995", + "type": "function", + "function": { + "name": "query_database", + "arguments": "{\"query\": \"Get product by ID 12345\"}" + } + } + ], + "content": "" + }, + { + "role": "tool", + "tool_call_id": "db_7995", + "content": "{\"id\": 12345, \"name\": \"Laptop\", \"price\": 999.99}" + }, + { + "role": "assistant", + "content": "यहाँ क्या मिला: {\"id\": 12345, \"name\": \"Laptop\", \"price\": 999.99}" + } + ], + "translation_metadata": "{\"target_lang\": \"hi\", \"translation\": {\"content\": [\"[आप एक डेटाबेस सहायक हैं।]\", \"3. Copy the content as-is.\\n```python\\ndef calculate_sum(a, b):\\n return a + b\\n```\", \"\", \"{\\\"id\\\": 12345, \\\"name\\\": \\\"Laptop\\\", \\\"price\\\": 999.99}\", \"यहाँ क्या मिला: {\\\"id\\\": 12345, \\\"name\\\": \\\"Laptop\\\", \\\"price\\\": 999.99}\"]}, \"segmented_translation\": {\"content\": [{\"src\": \"You are a database assistant.\", \"tgt\": \"[आप एक डेटाबेस सहायक हैं।]\"}, {\"src\": \"Get product by ID 12345\", \"tgt\": \"3. Copy the content as-is.\\n```python\\ndef calculate_sum(a, b):\\n return a + b\\n```\"}, {\"src\": \"Here's what I found: {\\\"id\\\": 12345, \\\"name\\\": \\\"Laptop\\\", \\\"price\\\": 999.99}\", \"tgt\": \"यहाँ क्या मिला: {\\\"id\\\": 12345, \\\"name\\\": \\\"Laptop\\\", \\\"price\\\": 999.99}\"}]}}", + "translated_messages": "[{\"role\": \"system\", \"content\": \"[आप एक डेटाबेस सहायक हैं।]\"}, {\"role\": \"user\", \"content\": \"3. Copy the content as-is.\\n```python\\ndef calculate_sum(a, b):\\n return a + b\\n```\"}, {\"role\": \"assistant\", \"tool_calls\": [{\"id\": \"db_7995\", \"type\": \"function\", \"function\": {\"name\": \"query_database\", \"arguments\": \"{\\\"query\\\": \\\"Get product by ID 12345\\\"}\"}}], \"content\": \"\"}, {\"role\": \"tool\", \"tool_call_id\": \"db_7995\", \"content\": \"{\\\"id\\\": 12345, \\\"name\\\": \\\"Laptop\\\", \\\"price\\\": 999.99}\"}, {\"role\": \"assistant\", \"content\": \"यहाँ क्या मिला: {\\\"id\\\": 12345, \\\"name\\\": \\\"Laptop\\\", \\\"price\\\": 999.99}\"}]" + } + { + "messages": [ + { + "role": "system", + "content": "आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।" + }, + { + "role": "user", + "content": "[दुबई में मौसम कैसा है?]" + }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "weather_8882", + "type": "function", + "function": { + "name": "get_weather", + "arguments": "{\"location\": \"Dubai\", \"units\": \"fahrenheit\"}" + } + } + ], + "content": "" + }, + { + "role": "tool", + "tool_call_id": "weather_8882", + "content": "{\"temp\": 55, \"condition\": \"rainy\", \"humidity\": 80}" + }, + { + "role": "assistant", + "content": "दुबई में मौसम बारिश के साथ है, तापमान 55°F और 80% आर्द्रता के साथ।" + } + ], + "tools": [ + { + "type": "function", + "function": { + "name": "get_weather", + "description": "Get current weather for a location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string" + }, + "units": { + "type": "string" + } + }, + "required": [ + "location" + ] + } + } + } + ], + "translation_time": 50.0045132637, + "translation_errors": "", + "translated_text": [ + { + "role": "system", + "content": "आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।" + }, + { + "role": "user", + "content": "[दुबई में मौसम कैसा है?]" + }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "weather_8882", + "type": "function", + "function": { + "name": "get_weather", + "arguments": "{\"location\": \"Dubai\", \"units\": \"fahrenheit\"}" + } + } + ], + "content": "" + }, + { + "role": "tool", + "tool_call_id": "weather_8882", + "content": "{\"temp\": 55, \"condition\": \"rainy\", \"humidity\": 80}" + }, + { + "role": "assistant", + "content": "दुबई में मौसम बारिश के साथ है, तापमान 55°F और 80% आर्द्रता के साथ।" + } + ], + "translation_metadata": "{\"target_lang\": \"hi\", \"translation\": {\"content\": [\"आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।\", \"[दुबई में मौसम कैसा है?]\", \"\", \"{\\\"temp\\\": 55, \\\"condition\\\": \\\"rainy\\\", \\\"humidity\\\": 80}\", \"दुबई में मौसम बारिश के साथ है, तापमान 55°F और 80% आर्द्रता के साथ।\"]}, \"segmented_translation\": {\"content\": [{\"src\": \"You are a helpful assistant with access to weather information.\", \"tgt\": \"आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।\"}, {\"src\": \"What's the weather in Dubai?\", \"tgt\": \"[दुबई में मौसम कैसा है?]\"}, {\"src\": \"The weather in Dubai is rainy with a temperature of 55°F and 80% humidity.\", \"tgt\": \"दुबई में मौसम बारिश के साथ है, तापमान 55°F और 80% आर्द्रता के साथ।\"}]}}", + "translated_messages": "[{\"role\": \"system\", \"content\": \"आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।\"}, {\"role\": \"user\", \"content\": \"[दुबई में मौसम कैसा है?]\"}, {\"role\": \"assistant\", \"tool_calls\": [{\"id\": \"weather_8882\", \"type\": \"function\", \"function\": {\"name\": \"get_weather\", \"arguments\": \"{\\\"location\\\": \\\"Dubai\\\", \\\"units\\\": \\\"fahrenheit\\\"}\"}}], \"content\": \"\"}, {\"role\": \"tool\", \"tool_call_id\": \"weather_8882\", \"content\": \"{\\\"temp\\\": 55, \\\"condition\\\": \\\"rainy\\\", \\\"humidity\\\": 80}\"}, {\"role\": \"assistant\", \"content\": \"दुबई में मौसम बारिश के साथ है, तापमान 55°F और 80% आर्द्रता के साथ।\"}]" + } + ``` + +1. Optional: Print the merged configuration without running the stage. + + Pass `--dry-run` or `-d` so Curator does not execute the pipeline. + + ```console + $ export RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 + + $ uv run --no-sync nemotron steps run translate/nemo_curator -d -c default \ + input_path=./train_sample.jsonl \ + output_dir=./output/translation-getting-started \ + source_language=en \ + target_language=hi \ + server.model=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning + ``` + +## Next Steps + +- Deeper behavior of FAITH in this pipeline: [FAITH Evaluation Inside Translation](/explanation/faith-evaluation) + +- Backend tuning: [Run LLM Translation](/how-to/run-llm-translation) + +- Field wiring and `output_mode`: [Configure Fields and Output](/how-to/configure-fields-and-output) + +- FAITH thresholds and filtering: [Run FAITH Evaluation](/how-to/run-faith-evaluation) + +- CLI flags and overrides: [CLI Reference for Translation](/reference/cli-translation) diff --git a/docs/fern/pages-vnightly/translation/how-to/configure-fields-and-output.mdx b/docs/fern/pages-vnightly/translation/how-to/configure-fields-and-output.mdx new file mode 100644 index 000000000..b2c34ea43 --- /dev/null +++ b/docs/fern/pages-vnightly/translation/how-to/configure-fields-and-output.mdx @@ -0,0 +1,49 @@ +--- +title: "Configure Fields and Output" +slug: "translation/how-to/configure-fields-and-output.html" +description: "Use this guide when you need to align text_field, output_mode, reconstruction flags, and formats with your dataset schema before or after a first run." +--- + +Use this guide when you need to align `text_field`, `output_mode`, reconstruction flags, and formats with your dataset schema before or after a first run. + +For a guided first invocation, see [Getting Started With Translation](/../getting-started). + +## Choosing `text_field` + +- Chat corpora in OpenAI layout typically use `messages.*.content` so every message `content` entry is translated consistently. + +- Plain documents might use a single column such as `article_body`. Omit wildcards when the schema is flat. + +## Outputs + +| YAML key | Behavior | +| --- | --- | +| output_field / translation_column | Control column names used when emitting translated strings. The default is translated_text. | +| output_mode | replaced overwrites source strings, raw preserves originals plus metadata, and both keeps audit trails. The starter default is both. | +| merge_scores | Keeps FAITH outputs adjacent to translations when scoring runs. | +| reconstruct_messages, messages_field, messages_content_field | Enable faithful reconstructions of chat arrays. These default to true for standard messages and content layouts. | + +## Formats + +Set `input_format` when automatic probing cannot distinguish ambiguous globs. Align `output_format` with downstream packing expectations; values are `jsonl` or `parquet`. + +## CLI Overrides + +You can override any YAML key with dotlists: + +```bash +uv run nemotron steps run translate/nemo_curator -c default \ + text_field=messages.*.content \ + output_mode=both \ + reconstruct_messages=true \ + input_path=/path/to/chat.jsonl \ + output_dir=/path/to/out \ + source_language=en \ + target_language=fr +``` + +## Related Pages + +- Schema patterns: [Input and Output Format](/../reference/io-format) + +- Segmentation interactions: [Use Fine Segmentation](/use-fine-segmentation) diff --git a/docs/fern/pages-vnightly/translation/how-to/index.mdx b/docs/fern/pages-vnightly/translation/how-to/index.mdx new file mode 100644 index 000000000..9ec7136a6 --- /dev/null +++ b/docs/fern/pages-vnightly/translation/how-to/index.mdx @@ -0,0 +1,91 @@ +--- +title: "How-To Guides" +slug: "translation/how-to/index.html" +description: "This section has task-focused procedures for changing backends, wiring fields, tuning segmentation, and adjusting FAITH." +--- + +This section has task-focused procedures for changing backends, wiring fields, tuning segmentation, and adjusting FAITH. + +For copy-paste prompts and habits when you work with a coding agent, read [Tips for Translation With Agents](/../using-skills) first. +Start with [Getting Started With Translation](/../getting-started) if you have not run the step yet. + +Focused procedures for `nemotron steps run translate/nemo_curator`. + +## Run Translation + + + +OpenAI-compatible servers, hosted or on-prem. + +--- + +backend=llm + + + + +Self-hosted `POST /translate` microservices. + +--- + +backend=nmt + + + + +Managed cloud translation APIs. + +--- + +backend=google|aws + + + + + +## Configure and Tune + + + +Wildcards, `output_mode`, chat reconstruction. + +--- + +schema + + + + +Switch `segmentation_mode` deliberately. + +--- + +segmentation + + + + + +## FAITH Quality Gates + + + +Thresholds, filtering, model overrides. + +--- + +faith + + + + + +```mermaid +graph LR + A[Prepare YAML + env] --> B[nemotron steps run translate/nemo_curator] + B --> C{Need FAITH?} + C -->|yes| D[Tune faith_eval] + C -->|no| E[Disable faith_eval] + D --> B + E --> B +``` diff --git a/docs/fern/pages-vnightly/translation/how-to/run-faith-evaluation.mdx b/docs/fern/pages-vnightly/translation/how-to/run-faith-evaluation.mdx new file mode 100644 index 000000000..af1e8915b --- /dev/null +++ b/docs/fern/pages-vnightly/translation/how-to/run-faith-evaluation.mdx @@ -0,0 +1,59 @@ +--- +title: "Run FAITH Evaluation" +slug: "translation/how-to/run-faith-evaluation.html" +description: "Use this guide when you need to tune thresholds, filtering, or scorer models for FAITH inside nemotron steps run translate/nemo_curator without a separate evaluation command." +--- + +Use this guide when you need to tune thresholds, filtering, or scorer models for FAITH inside `nemotron steps run translate/nemo_curator` without a separate evaluation command. + +FAITH runs inside `TranslationStage` whenever `faith_eval.enabled` is `true`. The `default.yaml` starter profile ships with FAITH enabled. For how FAITH couples to non-LLM backends, see [FAITH Evaluation Inside Translation](/../explanation/faith-evaluation). + +## Essential Knobs + +| YAML path | Purpose | +| --- | --- | +| faith_eval.enabled | Master toggle. Set false when you only need raw translation. | +| faith_eval.threshold | Average score floor. Rows failing the threshold are dropped when filter_enabled is true. | +| faith_eval.filter_enabled | Enables or disables removing low-scoring rows. | +| faith_eval.model_name | Overrides server.model for scoring-only workloads. | +| faith_eval.generation_config | Optional OpenAI-compatible generation settings for the FAITH scorer. | +| faith_eval.max_concurrent_requests | Optional scorer-side concurrency limit. | + +## LLM Credentials + +FAITH always requires the OpenAI-compatible `server` configuration. Set `NVIDIA_API_KEY` first, for example by replacing `` below. + +```bash +export NVIDIA_API_KEY="\" +uv run nemotron steps run translate/nemo_curator -c default \ + faith_eval.enabled=true \ + faith_eval.threshold=3.0 \ + faith_eval.filter_enabled=true \ + server.model=YOUR_LLM_MODEL_ID \ + input_path=/path/to/chat.jsonl \ + output_dir=/path/to/out \ + source_language=en \ + target_language=hi +``` + +FAITH scoring is part of Curator’s translation stage and is aligned to the translated segments produced by the stage. There is no separate `faith_eval.segment_level` switch in this Nemotron config. + +## Disable FAITH Temporarily + +```bash +uv run nemotron steps run translate/nemo_curator -c default \ + faith_eval.enabled=false \ + input_path=/path/to/chat.jsonl \ + output_dir=/path/to/out \ + source_language=en \ + target_language=hi \ + server.model=YOUR_LLM_MODEL_ID +``` + +Even with FAITH off, `backend=llm` still needs `server.model` for translation itself. + +## Related Pages + +- Concept primer: [FAITH Evaluation Inside Translation](/../explanation/faith-evaluation) + +- Full YAML reference: [Translation YAML Reference](/../reference/translate-config) diff --git a/docs/translation/how-to/run-google-aws-translation.md b/docs/fern/pages-vnightly/translation/how-to/run-google-aws-translation.mdx similarity index 71% rename from docs/translation/how-to/run-google-aws-translation.md rename to docs/fern/pages-vnightly/translation/how-to/run-google-aws-translation.mdx index 1574c7918..19cf00821 100644 --- a/docs/translation/how-to/run-google-aws-translation.md +++ b/docs/fern/pages-vnightly/translation/how-to/run-google-aws-translation.mdx @@ -1,23 +1,17 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Use backend=google or backend=aws with nemotron steps run translate/nemo_curator." -topics: ["Translation", "Cloud"] -tags: ["How-To", "Translation"] -content: - type: "How-To" - difficulty: "Intermediate" - audience: ["ML Engineer", "Data Scientist"] +title: "Run Google or AWS Translation" +slug: "translation/how-to/run-google-aws-translation.html" +description: "Use this guide when backend is google or aws and you want managed cloud translation with credentials supplied outside YAML files." --- -# Run Google or AWS Translation - Use this guide when `backend` is `google` or `aws` and you want managed cloud translation with credentials supplied outside YAML files. ## Shared Practices - Inject credentials through provider-standard environment variables or instance roles. Do not paste secrets into `default.yaml`. + - Keep `google.project_id`, `google.location`, and `google.api_version` aligned with your Google Cloud Platform (GCP) setup. API version `v3` requires project metadata. + - Pin `aws.region` near your data residency requirements on Amazon Web Services (AWS). ## Google Example Skeleton @@ -52,5 +46,6 @@ Cloud backends still pair with the FAITH LLM client. Keep `server` populated whe ## Related Pages -- YAML keys: {doc}`../reference/translate-config` -- FAITH tuning: {doc}`run-faith-evaluation` +- YAML keys: [Translation YAML Reference](/../reference/translate-config) + +- FAITH tuning: [Run FAITH Evaluation](/run-faith-evaluation) diff --git a/docs/translation/how-to/run-llm-translation.md b/docs/fern/pages-vnightly/translation/how-to/run-llm-translation.mdx similarity index 67% rename from docs/translation/how-to/run-llm-translation.md rename to docs/fern/pages-vnightly/translation/how-to/run-llm-translation.mdx index ef47dda1e..24f7b4f73 100644 --- a/docs/translation/how-to/run-llm-translation.md +++ b/docs/fern/pages-vnightly/translation/how-to/run-llm-translation.mdx @@ -1,27 +1,21 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Use backend=llm with nemotron steps run translate/nemo_curator and NVIDIA_API_KEY." -topics: ["Translation", "LLM"] -tags: ["How-To", "Translation"] -content: - type: "How-To" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] +title: "Run LLM Translation" +slug: "translation/how-to/run-llm-translation.html" +description: "Use this guide when backend must stay llm and you need to point nemotron steps run translate/nemo_curator at an OpenAI-compatible chat-completions endpoint and model." --- -# Run LLM Translation - Use this guide when `backend` must stay `llm` and you need to point `nemotron steps run translate/nemo_curator` at an OpenAI-compatible chat-completions endpoint and model. ## Prerequisites - Set `NVIDIA_API_KEY` in your shell when relying on the default `server.api_key_env`, for example `export NVIDIA_API_KEY=""`. + - Confirm `server.url` matches your deployment. The `default.yaml` file targets the NVIDIA integrate API. ## Procedure 1. Start from `default.yaml` with `-c default`. + 2. Override model and languages: ```bash @@ -42,5 +36,6 @@ Hosted catalogs retire models frequently. Pin to identifiers your tenant current ## Related Pages -- FAITH requirements when enabled: {doc}`run-faith-evaluation` -- Full YAML reference: {doc}`../reference/translate-config` +- FAITH requirements when enabled: [Run FAITH Evaluation](/run-faith-evaluation) + +- Full YAML reference: [Translation YAML Reference](/../reference/translate-config) diff --git a/docs/translation/how-to/run-nmt-translation.md b/docs/fern/pages-vnightly/translation/how-to/run-nmt-translation.mdx similarity index 75% rename from docs/translation/how-to/run-nmt-translation.md rename to docs/fern/pages-vnightly/translation/how-to/run-nmt-translation.mdx index 47fb0a251..2c4a1513f 100644 --- a/docs/translation/how-to/run-nmt-translation.md +++ b/docs/fern/pages-vnightly/translation/how-to/run-nmt-translation.mdx @@ -1,23 +1,16 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Use backend=nmt with nemotron steps run translate/nemo_curator and a local HTTP translation service." -topics: ["Translation", "NMT"] -tags: ["How-To", "Translation"] -content: - type: "How-To" - difficulty: "Intermediate" - audience: ["ML Engineer", "Data Scientist"] +title: "Run NMT Translation" +slug: "translation/how-to/run-nmt-translation.html" +description: "Use this guide when translation should run against backend: nmt and your own HTTP microservice that performs neural machine translation (NMT)." --- -# Run NMT Translation - Use this guide when translation should run against `backend: nmt` and your own HTTP microservice that performs *neural machine translation (NMT)*. ## Prerequisites - A running NMT service reachable at the URL you pass as `nmt.server_url`, implementing the contract in the next section. -- If `faith_eval.enabled` is `true`, LLM credentials for FAITH remain required; see {doc}`run-faith-evaluation`. + +- If `faith_eval.enabled` is `true`, LLM credentials for FAITH remain required; see [Run FAITH Evaluation](/run-faith-evaluation). ## Service Contract @@ -49,7 +42,7 @@ On error, return a non-2xx HTTP status with a JSON body containing an `"error"` Curator also sends `GET /health` at startup as an optional liveness check. Return any 2xx to pass; if the endpoint is absent, Curator logs a warning and continues. -Tune `nmt.batch_size`, `nmt.timeout`, and `nmt.max_concurrent_requests` once you understand your server's throughput. +Tune `nmt.batch_size`, `nmt.timeout`, and `nmt.max_concurrent_requests` once you understand your server’s throughput. ## Procedure @@ -69,5 +62,6 @@ If `faith_eval.enabled` stays `true` as in the default `default.yaml`, you must ## Related Pages -- Field wiring: {doc}`configure-fields-and-output` -- YAML reference for the `nmt` block: {doc}`../reference/translate-config` +- Field wiring: [Configure Fields and Output](/configure-fields-and-output) + +- YAML reference for the `nmt` block: [Translation YAML Reference](/../reference/translate-config) diff --git a/docs/translation/how-to/use-fine-segmentation.md b/docs/fern/pages-vnightly/translation/how-to/use-fine-segmentation.mdx similarity index 57% rename from docs/translation/how-to/use-fine-segmentation.md rename to docs/fern/pages-vnightly/translation/how-to/use-fine-segmentation.mdx index 0df3d8928..cee2a78a2 100644 --- a/docs/translation/how-to/use-fine-segmentation.md +++ b/docs/fern/pages-vnightly/translation/how-to/use-fine-segmentation.mdx @@ -1,24 +1,17 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Switch segmentation_mode between coarse and fine modes for nemotron steps run translate/nemo_curator." -topics: ["Translation", "Segmentation"] -tags: ["How-To", "Translation"] -content: - type: "How-To" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] +title: "Use Fine Segmentation" +slug: "translation/how-to/use-fine-segmentation.html" +description: "Use this guide when segmentation_mode=coarse mishandles long prose and you want to try fine on a sample before scaling." --- -# Use Fine Segmentation - Use this guide when `segmentation_mode=coarse` mishandles long prose and you want to try `fine` on a sample before scaling. -Conceptual background lives in {doc}`../explanation/segmentation`. +Conceptual background lives in [Segmentation](/../explanation/segmentation). ## Procedure 1. Reproduce an issue with `segmentation_mode=coarse`, which is the default in `default.yaml`. + 2. Retry on a slice with `segmentation_mode=fine`: ```bash @@ -39,5 +32,6 @@ Raise `min_segment_chars` modestly to skip trivial whitespace-only fragments if ## Related Pages -- Conceptual background: {doc}`../explanation/segmentation` -- YAML keys: {doc}`../reference/translate-config` +- Conceptual background: [Segmentation](/../explanation/segmentation) + +- YAML keys: [Translation YAML Reference](/../reference/translate-config) diff --git a/docs/fern/pages-vnightly/translation/index.mdx b/docs/fern/pages-vnightly/translation/index.mdx new file mode 100644 index 000000000..e54008b6d --- /dev/null +++ b/docs/fern/pages-vnightly/translation/index.mdx @@ -0,0 +1,155 @@ +--- +title: "Translation With Nemotron" +slug: "translation/index.html" +description: "The nemotron steps run translate/nemo_curator command translates selected fields in JSONL or Apache Parquet files. You can use a large language model (LLM) with an OpenAI-compatible endpoint, a neural" +--- + + + +The `nemotron steps run translate/nemo_curator` command translates selected fields in JSONL or Apache Parquet files. +You can use a large language model (LLM) with an OpenAI-compatible endpoint, a neural machine translation (NMT) HTTP server, Google Cloud Translation, or Amazon Translate. +Optionally, you can also run *FAITH* evaluation with an LLM after translation to score translation quality. + + +New here? Read [Tips for Translation With Agents](/using-skills) if you plan to drive the work from a coding agent, then start [Getting Started With Translation](/getting-started) and use this page as the map to deeper topics. + + + +## When to Use + +Use `nemotron steps run translate/nemo_curator` when you need: + +- Localized training or synthetic corpora from translating natural-language fields while preserving structured payloads such as chat turns, tool payloads, and fenced code blocks. +Field paths, `output_mode`, and segmentation interact with that behavior; see [Configure Fields and Output](/how-to/configure-fields-and-output) and [Segmentation](/explanation/segmentation). + +- Optional FAITH evaluation with configurable thresholds and filtering, without a separate evaluation CLI. + +- Repeatable configuration by using the checked-in `default.yaml` plus CLI overrides. + +## Pipeline Summary + +```mermaid +flowchart LR + A[Input JSONL or Parquet] --> B[Curator reader] + B --> C[TranslationStage] + C --> D[Curator writer] + D --> E[Output shards under output_dir] + C --> F{FAITH enabled?} + F -->|yes| G[LLM scores segments] + F -->|no| E + G --> E +``` + +## Documentation Series + + + +Run `nemotron steps run translate/nemo_curator` end-to-end using `default.yaml` and a sample chat JSONL file. + +--- + +hands-on + + + + +Copy-paste session prompts for supervised fine-tuning (SFT) data or exploratory FAITH scoring, plus habits for a short chat. + +--- + +newcomer + + + + +Backends, fields and outputs, segmentation, FAITH tuning. + +--- + +task-based + + + + +Pipeline architecture, segmentation, FAITH behavior. + +--- + +learn + + + + +YAML parameters and `nemotron steps run translate/nemo_curator` CLI. + +--- + +lookup + + + + + +## All Documentation + + + + +| Guide | What you do | +| --- | --- | +| [Tips for Translation With Agents](/using-skills) | Paste starter prompts for an agent and keep a translation session on the rails | +| [Getting Started With Translation](/getting-started) | Run translation and FAITH using default.yaml and sample JSONL | + + + + +| Guide | Focus | +| --- | --- | +| [Run LLM Translation](/how-to/run-llm-translation) | backend: llm | +| [Run NMT Translation](/how-to/run-nmt-translation) | backend: nmt | +| [Run Google or AWS Translation](/how-to/run-google-aws-translation) | backend: google / aws | +| [Configure Fields and Output](/how-to/configure-fields-and-output) | Field paths and output_mode | +| [Use Fine Segmentation](/how-to/use-fine-segmentation) | segmentation_mode | +| [Run FAITH Evaluation](/how-to/run-faith-evaluation) | faith_eval block | + + + + +| Guide | Topic | +| --- | --- | +| [Pipeline Overview](/explanation/pipeline-overview) | End-to-end flow | +| [Segmentation](/explanation/segmentation) | Coarse versus fine | +| [FAITH Evaluation Inside Translation](/explanation/faith-evaluation) | FAITH semantics | + + + + +| Guide | Content | +| --- | --- | +| [Translation YAML Reference](/reference/translate-config) | default.yaml field reference | +| [CLI Reference for Translation](/reference/cli-translation) | nemotron steps run translate/nemo_curator syntax | +| [Input and Output Format](/reference/io-format) | Input and output shapes | + + + + + +## Limitations and Considerations + +- Cost and rate limits: Hosted and cloud LLM backends incur usage; throttle with `max_concurrent_requests` and your provider’s guidance. + +- Remote execution: use `--run ` or `--batch ` with an environment profile such as `lepton_translate`. + +- Overrides: Use `key=value` dotlist syntax after global flags, not passthrough script arguments. + +- Mixed folders: Do not point `input_path` at one directory that contains both `.jsonl` and `.parquet` shards unless you split formats first. + +## Quick Paths + +1. Agent-first prompts: [Tips for Translation With Agents](/using-skills) + +2. First run: [Getting Started With Translation](/getting-started) + +3. Swap backend: [How-To Guides](/how-to/index) + +4. Lookup flags: [CLI Reference for Translation](/reference/cli-translation) diff --git a/docs/fern/pages-vnightly/translation/reference/cli-translation.mdx b/docs/fern/pages-vnightly/translation/reference/cli-translation.mdx new file mode 100644 index 000000000..6462c06d4 --- /dev/null +++ b/docs/fern/pages-vnightly/translation/reference/cli-translation.mdx @@ -0,0 +1,72 @@ +--- +title: "CLI Reference for Translation" +slug: "translation/reference/cli-translation.html" +description: "Syntax, global flags, and merge rules for nemotron steps run translate/nemo_curator. Pair this page with Translation YAML Reference for YAML field meanings." +--- + +Syntax, global flags, and merge rules for `nemotron steps run translate/nemo_curator`. Pair this page with [Translation YAML Reference](/translate-config) for YAML field meanings. + +## Synopsis + +```bash +uv run nemotron steps run translate/nemo_curator [GLOBAL OPTIONS] [-c CONFIG] [DOTLIST_OVERRIDES...] +``` + +## Global Options + +These flags mirror other Nemotron commands: + +| Flag | Purpose | +| --- | --- | +| -c NAME, --config NAME | Select NAME.yaml inside src/nemotron/steps/translate/nemo_curator/config/ or pass an explicit *.yaml path. | +| -d, --dry-run | Print the merged OmegaConf YAML without executing TranslationStage. | +| -r, --run PROFILE | Run attached through an environment profile such as lepton_translate or a Slurm profile. | +| -b, --batch PROFILE | Submit detached through an environment profile such as lepton_translate or a Slurm profile. | + +Invocation without `-c` loads `default` automatically through `parse_config`. + +For local Curator execution through `uv run`, set: + +```bash +export RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 +``` + +This keeps Ray workers on the synchronized project environment instead of +letting Ray ask uv to create a separate worker environment. + +## Dotlist Overrides + +Anything after the global flags that matches `key=value` merges into the YAML dictionary loaded from `default.yaml`. Nested keys use dotted paths: + +```bash +uv run nemotron steps run translate/nemo_curator -c default \ + faith_eval.threshold=3.1 \ + server.model=YOUR_MODEL \ + input_path=/data/text.jsonl \ + output_dir=/data/translated \ + source_language=en \ + target_language=ar +``` + +## Restrictions Specific to Translation + +- Passthrough arguments are not supported. + +- For remote execution, use a normal Nemotron env profile with `-r` or `-b`, such as `lepton_translate`. + +## Artifact Overrides + +The current translation step reads `input_path` directly from YAML and dotlist overrides. + +## Exit Codes + +| Code | Meaning | +| --- | --- | +| 0 | Dry-run printed or translation finished successfully. | +| 1 | Validation failures such as missing languages, illegal backend configuration, unsupported CLI mode, or missing API keys. | + +## Related Pages + +- YAML keys: [Translation YAML Reference](/translate-config) + +- Tutorial invocation: [Getting Started With Translation](/../getting-started) diff --git a/docs/fern/pages-vnightly/translation/reference/index.mdx b/docs/fern/pages-vnightly/translation/reference/index.mdx new file mode 100644 index 000000000..e6e0d905b --- /dev/null +++ b/docs/fern/pages-vnightly/translation/reference/index.mdx @@ -0,0 +1,39 @@ +--- +title: "Reference for Translation" +slug: "translation/reference/index.html" +description: "Lookup pages for YAML keys, CLI flags, and file shapes. Prefer the tutorial and how-to guides for procedures; use this section when you need exact parameters or syntax." +--- + +Lookup pages for YAML keys, CLI flags, and file shapes. Prefer the tutorial and how-to guides for procedures; use this section when you need exact parameters or syntax. + +Specifications for `nemotron steps run translate/nemo_curator`. + + + +Anchored on `config/default.yaml` plus FAITH semantics. + +--- + +yaml + + + + +Global recipe flags and translation-specific constraints. + +--- + +cli + + + + +How `input_path` layouts map to `output_dir` shards. + +--- + +jsonl + + + + diff --git a/docs/translation/reference/io-format.md b/docs/fern/pages-vnightly/translation/reference/io-format.mdx similarity index 67% rename from docs/translation/reference/io-format.md rename to docs/fern/pages-vnightly/translation/reference/io-format.mdx index 395afcbe6..a88d72490 100644 --- a/docs/translation/reference/io-format.md +++ b/docs/fern/pages-vnightly/translation/reference/io-format.mdx @@ -1,17 +1,9 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Input and output expectations for nemotron steps run translate/nemo_curator." -topics: ["Translation", "Schema"] -tags: ["Reference", "JSONL"] -content: - type: "Reference" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] +title: "Input and Output Format" +slug: "translation/reference/io-format.html" +description: "Expectations for input_path layouts, shard layout under output_dir, output_mode, chat reconstruction, and FAITH columns." --- -# Input and Output Format - Expectations for `input_path` layouts, shard layout under `output_dir`, `output_mode`, chat reconstruction, and FAITH columns. ## Inputs @@ -19,6 +11,7 @@ Expectations for `input_path` layouts, shard layout under `output_dir`, `output_ Supported layouts include JSON Lines (JSONL), with one JSON object per line, or Apache Parquet columnar files. - JSONL records contain arbitrary JSON objects per line. The `text_field` setting selects which strings `TranslationStage` visits. Wildcards expand across arrays such as `messages` items. + - Parquet inputs share the same logical schema. The Curator `ParquetReader` partitions row groups according to `files_per_partition` and `blocksize` overrides. Avoid pointing `input_path` at directories that mix `.jsonl` and `.parquet` shards when `input_format=auto`. The reader raises an error instead of guessing. @@ -30,10 +23,10 @@ The `JsonlWriter` and `ParquetWriter` emit multiple shards under `output_dir` be ### `output_mode` | Mode | Producer behavior | -|------|-------------------| -| `replaced` | Source strings at `text_field` are overwritten with translations suitable for immediate training. | -| `raw` | Original strings remain. Translations and metadata appear in auxiliary columns defined by `TranslationStage`. | -| `both` | Emits replaced views and retains intermediate structures. This is the starter default for auditing. | +| --- | --- | +| replaced | Source strings at text_field are overwritten with translations suitable for immediate training. | +| raw | Original strings remain. Translations and metadata appear in auxiliary columns defined by TranslationStage. | +| both | Emits replaced views and retains intermediate structures. This is the starter default for auditing. | ### Chat Reconstruction @@ -53,5 +46,6 @@ find ./output_dir -name '*.jsonl' | head -n 1 | xargs head -n 1 | python3 -m jso ## Related Pages -- Field tuning guide: {doc}`../how-to/configure-fields-and-output` -- YAML defaults: {doc}`translate-config` +- Field tuning guide: [Configure Fields and Output](/../how-to/configure-fields-and-output) + +- YAML defaults: [Translation YAML Reference](/translate-config) diff --git a/docs/fern/pages-vnightly/translation/reference/translate-config.mdx b/docs/fern/pages-vnightly/translation/reference/translate-config.mdx new file mode 100644 index 000000000..4731beacf --- /dev/null +++ b/docs/fern/pages-vnightly/translation/reference/translate-config.mdx @@ -0,0 +1,159 @@ +--- +title: "Translation YAML Reference" +slug: "translation/reference/translate-config.html" +description: "The translate/nemo_curator step ships src/nemotron/steps/translate/nemo_curator/config/default.yaml as the canonical starter profile. This page lists top-level keys you can override with nemotron step" +--- + +The `translate/nemo_curator` step ships `src/nemotron/steps/translate/nemo_curator/config/default.yaml` as the canonical starter profile. This page lists top-level keys you can override with `nemotron steps run translate/nemo_curator key=value` dotlists, grouped by concern, with the full baseline file inlined below. + +## Default Configuration File + +```yaml startLine={1} +# Starter config for NeMo Curator corpus translation. + +run: + env: + mounts: + - ${auto_mount:git+https://github.com/NVIDIA-NeMo/Curator.git@d10cd6ffe9f5ac4cbb176d7b3ada698f22633aea,/opt/Curator} + +input_path: /path/to/filtered_data.jsonl +output_dir: ./output/translated + +# Required. Ask the user; do not infer silently. +source_language: ??? +target_language: ??? + +input_format: auto # auto | jsonl | parquet +output_format: jsonl # jsonl | parquet +backend: llm # llm | nmt | google | aws + +text_field: messages.*.content +output_field: translated_text +translation_column: translated_text +output_mode: both # replaced | raw | both +merge_scores: true +reconstruct_messages: true +messages_field: messages +messages_content_field: content + +segmentation_mode: coarse # coarse | fine +min_segment_chars: 0 +max_concurrent_requests: 64 +generation_config: null # Optional OpenAI-compatible translation generation settings. +skip_translated: false +files_per_partition: null +blocksize: null + +server: + url: https://integrate.api.nvidia.com/v1 + model: "" # Required for backend=llm and used by FAITH unless faith_eval.model_name is set. + api_key_env: NVIDIA_API_KEY + api_key: "" + +faith_eval: + enabled: true + threshold: 2.5 + model_name: "" + filter_enabled: true + max_concurrent_requests: 64 + generation_config: + max_tokens: 2048 + temperature: 0.0 + +nmt: + server_url: http://localhost:5000 + batch_size: 32 + timeout: 120 + max_concurrent_requests: 32 + +google: + project_id: "" + location: global + api_version: v2 + max_concurrent_requests: 32 + +aws: + region: us-east-2 + max_concurrent_requests: 32 +``` + +## Keys Grouped by Concern + +### Paths and Formats + +| Key | Description | +| --- | --- | +| input_path | File, glob, or homogeneous directory consumed by JsonlReader or ParquetReader. | +| output_dir | Directory passed to JsonlWriter or ParquetWriter in overwrite mode. | +| input_format | auto, jsonl, or parquet. | +| output_format | jsonl or parquet. | + +### Languages and Backend + +| Key | Description | +| --- | --- | +| source_language / target_language | Required ISO 639-1 codes. Empty placeholders remind operators to set values explicitly. | +| backend | llm, nmt, google, or aws. | + +### Translation Semantics + +| Key | Description | +| --- | --- | +| text_field | Dot or wildcard path describing strings to translate. The default is messages.*.content. | +| output_field, translation_column | Destination columns for translated text and downstream merges. | +| output_mode | replaced, raw, or both. | +| merge_scores | Attach FAITH outputs adjacent to translations when enabled. | +| reconstruct_messages, messages_field, messages_content_field | Chat reconstruction switches. | +| segmentation_mode, min_segment_chars | Segmenter behavior. Values include coarse and fine. | +| max_concurrent_requests, skip_translated, files_per_partition, blocksize | Throughput and partitioning controls surfaced to Curator readers and clients. | + +### LLM Fields + +Used whenever `backend=llm` or FAITH needs an OpenAI-compatible judge. + +| Key | Description | +| --- | --- | +| server.url | Chat-completions compatible base URL. | +| server.model | Model identifier. Required for llm translation and for FAITH unless you override the scorer model. | +| server.api_key_env | Environment variable housing the API secret. The default is NVIDIA_API_KEY. | +| server.api_key | Inline secret. Discouraged for shared repositories. | + +### FAITH Evaluation + +| Key | Description | +| --- | --- | +| enabled | Turns FAITH scoring on. The starter YAML sets this to true. | +| threshold | Minimum acceptable faith_avg on a one-to-five scale. The starter default 2.5 is a permissive noisy-data floor. See [FAITH Evaluation Inside Translation](/../explanation/faith-evaluation) for the full rubric. | +| model_name | Optional scorer-only model. Defaults to server.model. | +| filter_enabled | Drop failing rows when true. | +| max_concurrent_requests | Optional scorer-side concurrency limit. | +| generation_config | Optional OpenAI-compatible generation settings for the scorer. | + +### Backend-Specific Blocks + +| Block | When needed | +| --- | --- | +| nmt | HTTP microservice URL, batching, timeouts. | +| google | Project metadata and API version. Version v3 requires project_id. | +| aws | Region plus concurrency limits. | + +## Overrides + +OmegaConf dotlists merge last: + +```bash +uv run nemotron steps run translate/nemo_curator -c default \ + backend=nmt \ + nmt.server_url=http://localhost:5000 \ + faith_eval.enabled=false \ + input_path=/data/chat.jsonl \ + output_dir=/data/out \ + source_language=en \ + target_language=hi +``` + +## Related Pages + +- CLI merge rules and flags: [CLI Reference for Translation](/cli-translation) + +- Record shapes and writers: [Input and Output Format](/io-format) diff --git a/docs/fern/pages-vnightly/translation/reference/troubleshooting.mdx b/docs/fern/pages-vnightly/translation/reference/troubleshooting.mdx new file mode 100644 index 000000000..3792d9ebd --- /dev/null +++ b/docs/fern/pages-vnightly/translation/reference/troubleshooting.mdx @@ -0,0 +1,58 @@ +--- +title: "Troubleshooting" +slug: "translation/reference/troubleshooting.html" +description: "This page lists common symptoms when you run nemotron steps run translate/nemo_curator and shows the field, flag, or environment variable to inspect first. Each table pairs a symptom with a concrete r" +--- + +{/* Reference: symptom-to-remedy tables for nemotron steps run translate/nemo_curator runs across all four backends and FAITH evaluation. */} + +This page lists common symptoms when you run `nemotron steps run translate/nemo_curator` and shows the field, flag, or environment variable to inspect first. +Each table pairs a symptom with a concrete remedy. +For stage flow and design rationale, see the explanation pages linked from [Concepts](/../explanation/index). + +## Authentication and Credentials + +| Symptom | What to do | +| --- | --- | +| HTTP 401 or 403 from the chat-completions endpoint, or a Curator log line about a missing API key | Confirm the variable named in server.api_key_env is exported in the shell that launches the run. The starter default.yaml expects NVIDIA_API_KEY; export it with export NVIDIA_API_KEY="<api-key>" and rerun. See [Run LLM Translation](/../how-to/run-llm-translation). | +| FAITH scoring fails with a credentials error even though backend is nmt, google, or aws | FAITH always uses the large language model (LLM) client under server. Keep server.api_key_env populated whenever faith_eval.enabled is true, or set faith_eval.enabled=false for a diagnostic run. See [Run FAITH Evaluation](/../how-to/run-faith-evaluation). | +| Google backend rejects the request with a permission or project error | Confirm application default credentials are present in the environment that runs the step. Do not paste secrets into default.yaml. See [Run Google or AWS Translation](/../how-to/run-google-aws-translation). | + +## Model and Endpoint Configuration + +| Symptom | What to do | +| --- | --- | +| HTTP 404 or a “model not found” message from the LLM endpoint | Hosted catalogs retire identifiers frequently. List the models your tenant currently exposes and pin server.model to one of them before large batch jobs. See [Run LLM Translation](/../how-to/run-llm-translation). | +| Google translation rejects the request because project_id is missing | API version v3 requires project metadata. Set both google.project_id and google.api_version=v3, or downgrade google.api_version to a release that does not require the project. See [Run Google or AWS Translation](/../how-to/run-google-aws-translation). | +| NMT requests time out before the service responds | Raise nmt.timeout to match observed server latency, lower nmt.batch_size so each request returns sooner, and confirm nmt.server_url resolves from the host that runs the step. See [Run NMT Translation](/../how-to/run-nmt-translation). | + +## Throttling and Concurrency + +| Symptom | What to do | +| --- | --- | +| HTTP 429 responses, bursty failures, or sustained slowdowns from a hosted LLM endpoint | Lower max_concurrent_requests in your YAML and rerun on a smaller slice of data. Confirm your tenant quota covers the planned batch size. See [Translation YAML Reference](/translate-config). | +| A self-hosted NMT service returns errors under load | Reduce nmt.max_concurrent_requests and nmt.batch_size together, then raise them only after the service reports healthy throughput. See [Run NMT Translation](/../how-to/run-nmt-translation). | + +## Inputs and Output Layout + +| Symptom | What to do | +| --- | --- | +| Reader errors about mixed file types when input_path points at a directory containing both JSONL and Parquet files | Curator readers expect one record format per directory. Split the inputs into separate directories for JSON Lines (JSONL) and Parquet, or set input_path to a single file. See [Input and Output Format](/io-format). | +| Ray worker logs show Creating virtual environment at: .venv followed by ModuleNotFoundError: No module named 'ray' | Export RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 before running local uv run --no-sync nemotron steps run translate/nemo_curator .... This keeps Ray workers in the synchronized Nemotron environment. | +| Empty JSONL input fails with No data read from files in task file_group_0 | The reader found no records. Treat the run as an empty-input validation failure, confirm the input path is correct, and rerun with a non-empty file or directory. | +| Output shards do not appear under output_dir after the run reports success | The writer emits partitioned files, not a single merged file. Inspect the shard pattern under output_dir and confirm output_format matches what downstream consumers expect. See [Input and Output Format](/io-format). | + +## FAITH Evaluation + +| Symptom | What to do | +| --- | --- | +| Every translated row is dropped after FAITH runs | The faith_eval.threshold value may be too strict for the chosen scorer model. Lower the threshold, set faith_eval.filter_enabled=false while you tune, or override the scorer with faith_eval.model_name. See [Run FAITH Evaluation](/../how-to/run-faith-evaluation). | +| FAITH scores look inconsistent across runs of the same data | Pin both server.model and faith_eval.model_name to specific identifiers so scorer drift does not move the threshold under you. See [FAITH Evaluation Inside Translation](/../explanation/faith-evaluation). | + +## Related Reference + +- Translation YAML fields: [Translation YAML Reference](/translate-config) + +- CLI syntax: [CLI Reference for Translation](/cli-translation) + +- Input and output shapes: [Input and Output Format](/io-format) diff --git a/docs/translation/using-skills.md b/docs/fern/pages-vnightly/translation/using-skills.mdx similarity index 64% rename from docs/translation/using-skills.md rename to docs/fern/pages-vnightly/translation/using-skills.mdx index f57817279..2534aab36 100644 --- a/docs/translation/using-skills.md +++ b/docs/fern/pages-vnightly/translation/using-skills.mdx @@ -1,20 +1,13 @@ --- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Sample prompts and a short guide for productive agent-assisted sessions with nemotron steps run translate/nemo_curator." -topics: ["Translation", "FAITH", "NeMo Curator"] -tags: ["Translation", "Documentation"] -content: - type: "How-To" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] +title: "Tips for Translation With Agents" +slug: "translation/using-skills.html" +description: "This page is for you if you want a productive session with a coding agent without a long back-and-forth. The mechanics of the nemotron steps run translate/nemo_curator are shown in Getting Started Wit" --- -(translation-using-skills)= -# Tips for Translation With Agents + This page is for you if you want a productive session with a coding agent without a long back-and-forth. -The mechanics of the `nemotron steps run translate/nemo_curator` are shown in {doc}`getting-started` and the how-to guides. +The mechanics of the `nemotron steps run translate/nemo_curator` are shown in [Getting Started With Translation](/getting-started) and the how-to guides. ## Sample Prompts You Can Paste @@ -44,7 +37,10 @@ Please: ## Next Steps -- First hands-on run: {doc}`getting-started` -- Field paths and `output_mode`: {doc}`how-to/configure-fields-and-output` -- FAITH tuning after exploration: {doc}`how-to/run-faith-evaluation` -- Full CLI: {doc}`reference/cli-translation` \ No newline at end of file +- First hands-on run: [Getting Started With Translation](/getting-started) + +- Field paths and `output_mode`: [Configure Fields and Output](/how-to/configure-fields-and-output) + +- FAITH tuning after exploration: [Run FAITH Evaluation](/how-to/run-faith-evaluation) + +- Full CLI: [CLI Reference for Translation](/reference/cli-translation) diff --git a/docs/fern/versions/vnightly.yml b/docs/fern/versions/vnightly.yml new file mode 100644 index 000000000..9c1a33b0b --- /dev/null +++ b/docs/fern/versions/vnightly.yml @@ -0,0 +1,392 @@ +navigation: + - section: Contents + contents: + - page: "Nemotron Training Recipes" + path: ../pages-vnightly/index.mdx + - section: "Nemotron" + contents: + - page: "Application Examples" + path: ../pages-vnightly/application-examples.mdx + - page: "Deployment Guides" + path: ../pages-vnightly/deployment-guides.mdx + - section: "Nemotron Step Basics" + contents: + - page: "About" + path: ../pages-vnightly/steps/index.mdx + - page: "Basics" + path: ../pages-vnightly/steps/basics.mdx + - page: "Getting Started" + path: ../pages-vnightly/steps/getting-started.mdx + - page: "Airgap Environment" + path: ../pages-vnightly/steps/airgap.mdx + - section: "Data Curation" + contents: + - page: "About" + path: ../pages-vnightly/curate/index.mdx + - page: "Getting Started" + path: ../pages-vnightly/curate/getting-started.mdx + - section: "Tasks" + path: ../pages-vnightly/curate/how-to/index.mdx + contents: + - page: "Run Curation on Local JSONL" + path: ../pages-vnightly/curate/how-to/run-local-jsonl.mdx + - page: "Use a Hugging Face Snapshot" + path: ../pages-vnightly/curate/how-to/use-huggingface-snapshot.mdx + - page: "Enable Curation Filters" + path: ../pages-vnightly/curate/how-to/enable-filters.mdx + - section: "Reference" + path: ../pages-vnightly/curate/reference/index.mdx + contents: + - page: "curate/nemo_curator CLI" + path: ../pages-vnightly/curate/reference/cli-curate.mdx + - page: "curate/nemo_curator Configuration" + path: ../pages-vnightly/curate/reference/curate-config.mdx + - page: "Curation Input and Output Format" + path: ../pages-vnightly/curate/reference/io-format.mdx + - page: "Curation Troubleshooting" + path: ../pages-vnightly/curate/reference/troubleshooting.mdx + - section: "Synthetic Data Generation" + contents: + - page: "About" + path: ../pages-vnightly/sdg/index.mdx + - page: "Getting Started" + path: ../pages-vnightly/sdg/getting-started.mdx + - page: "Tips for Using Agents" + path: ../pages-vnightly/sdg/using-skills.mdx + - page: "Planning" + path: ../pages-vnightly/sdg/planning.mdx + - section: "Tasks" + path: ../pages-vnightly/sdg/how-to/index.mdx + contents: + - page: "Create a Domain Dataset" + path: ../pages-vnightly/sdg/how-to/create-domain-dataset.mdx + - page: "Create Tool-Calling Dataset" + path: ../pages-vnightly/sdg/how-to/tool-call-data.mdx + - page: "Generate Preference Data for DPO" + path: ../pages-vnightly/sdg/how-to/preference-data.mdx + - page: "Dispatch SDG to a Cluster" + path: ../pages-vnightly/sdg/how-to/dispatch-to-cluster.mdx + - page: "Tips for the Data Generation Pipeline" + path: ../pages-vnightly/sdg/how-to/run.mdx + - section: "Reference" + path: ../pages-vnightly/sdg/reference/index.mdx + contents: + - page: "Config Schema" + path: ../pages-vnightly/sdg/reference/config-schema.mdx + - page: "CLI Reference" + path: ../pages-vnightly/sdg/reference/cli-reference.mdx + - page: "Output Projections" + path: ../pages-vnightly/sdg/reference/output-projections.mdx + - page: "Troubleshooting" + path: ../pages-vnightly/sdg/reference/troubleshooting.mdx + - section: "Translation" + contents: + - page: "About" + path: ../pages-vnightly/translation/index.mdx + - page: "Getting Started" + path: ../pages-vnightly/translation/getting-started.mdx + - page: "Tips for Using Agents" + path: ../pages-vnightly/translation/using-skills.mdx + - section: "Concepts" + path: ../pages-vnightly/translation/explanation/index.mdx + contents: + - page: "Pipeline Overview" + path: ../pages-vnightly/translation/explanation/pipeline-overview.mdx + - page: "Segmentation" + path: ../pages-vnightly/translation/explanation/segmentation.mdx + - page: "FAITH Evaluation Inside Translation" + path: ../pages-vnightly/translation/explanation/faith-evaluation.mdx + - section: "Tasks" + path: ../pages-vnightly/translation/how-to/index.mdx + contents: + - page: "Run LLM Translation" + path: ../pages-vnightly/translation/how-to/run-llm-translation.mdx + - page: "Run NMT Translation" + path: ../pages-vnightly/translation/how-to/run-nmt-translation.mdx + - page: "Run Google or AWS Translation" + path: ../pages-vnightly/translation/how-to/run-google-aws-translation.mdx + - page: "Configure Fields and Output" + path: ../pages-vnightly/translation/how-to/configure-fields-and-output.mdx + - page: "Use Fine Segmentation" + path: ../pages-vnightly/translation/how-to/use-fine-segmentation.mdx + - page: "Run FAITH Evaluation" + path: ../pages-vnightly/translation/how-to/run-faith-evaluation.mdx + - section: "Reference" + path: ../pages-vnightly/translation/reference/index.mdx + contents: + - page: "Translation YAML Reference" + path: ../pages-vnightly/translation/reference/translate-config.mdx + - page: "CLI Reference for Translation" + path: ../pages-vnightly/translation/reference/cli-translation.mdx + - page: "Input and Output Format" + path: ../pages-vnightly/translation/reference/io-format.mdx + - page: "Troubleshooting" + path: ../pages-vnightly/translation/reference/troubleshooting.mdx + - section: "Build MCQ Benchmarks" + contents: + - page: "About" + path: ../pages-vnightly/build-benchmarks/index.mdx + - page: "Getting Started" + path: ../pages-vnightly/build-benchmarks/getting-started.mdx + - section: "Concepts" + path: ../pages-vnightly/build-benchmarks/explanation/index.mdx + contents: + - page: "Pipeline Overview" + path: ../pages-vnightly/build-benchmarks/explanation/pipeline-overview.mdx + - page: "Data Preparation" + path: ../pages-vnightly/build-benchmarks/explanation/data-preparation.mdx + - page: "Get the Right Questions" + path: ../pages-vnightly/build-benchmarks/explanation/get-right-questions.mdx + - page: "Question Generation" + path: ../pages-vnightly/build-benchmarks/explanation/question-generation.mdx + - page: "Quality Validation" + path: ../pages-vnightly/build-benchmarks/explanation/quality-validation.mdx + - page: "Easiness and Hallucination Filtering" + path: ../pages-vnightly/build-benchmarks/explanation/filtering.mdx + - page: "Translation" + path: ../pages-vnightly/build-benchmarks/explanation/translation.mdx + - section: "Tasks" + path: ../pages-vnightly/build-benchmarks/how-to/index.mdx + contents: + - page: "Prepare Data" + path: ../pages-vnightly/build-benchmarks/how-to/prepare-data.mdx + - page: "Use Your Domain Data" + path: ../pages-vnightly/build-benchmarks/how-to/domain-data.mdx + - page: "Model Endpoints" + path: ../pages-vnightly/build-benchmarks/how-to/custom-model-endpoints.mdx + - page: "Tune Prompts" + path: ../pages-vnightly/build-benchmarks/how-to/prompt-tuning.mdx + - page: "Skip Stages" + path: ../pages-vnightly/build-benchmarks/how-to/skip-stages.mdx + - section: "Reference" + path: ../pages-vnightly/build-benchmarks/reference/index.mdx + contents: + - page: "Supported Hugging Face Benchmarks" + path: ../pages-vnightly/build-benchmarks/reference/benchmarks.mdx + - page: "Output Files" + path: ../pages-vnightly/build-benchmarks/reference/output-files.mdx + - page: "Generation Configuration Reference" + path: ../pages-vnightly/build-benchmarks/reference/generate-config.mdx + - page: "Translation Configuration Reference" + path: ../pages-vnightly/build-benchmarks/reference/translation-config.mdx + - page: "Troubleshooting" + path: ../pages-vnightly/build-benchmarks/reference/troubleshooting.mdx + - section: "Model Training" + contents: + - page: "About" + path: ../pages-vnightly/train-models/index.mdx + - page: "Getting Started" + path: ../pages-vnightly/train-models/getting-started.mdx + - page: "Tips for Using Agents" + path: ../pages-vnightly/train-models/using-skill.mdx + - section: "Concepts" + path: ../pages-vnightly/train-models/explanation/index.mdx + contents: + - page: "Training Basics" + path: ../pages-vnightly/train-models/explanation/basics.mdx + - page: "Artifact Graph" + path: ../pages-vnightly/train-models/explanation/artifact-graph.mdx + - page: "Training Libraries" + path: ../pages-vnightly/train-models/explanation/training-libraries.mdx + - section: "Tasks" + path: ../pages-vnightly/train-models/how-to/index.mdx + contents: + - page: "Run SFT with AutoModel on Custom Data" + path: ../pages-vnightly/train-models/how-to/run-sft-automodel.mdx + - page: "Choose an SFT Backend" + path: ../pages-vnightly/train-models/how-to/choose-sft-backend.mdx + - page: "Choose a PEFT Backend" + path: ../pages-vnightly/train-models/how-to/choose-peft-backend.mdx + - page: "Choose an RL Alignment Step" + path: ../pages-vnightly/train-models/how-to/choose-rl-step.mdx + - page: "Run Post-Training Optimization" + path: ../pages-vnightly/train-models/how-to/run-optimization.mdx + - page: "Environment Profiles and Executors" + path: ../pages-vnightly/train-models/how-to/env-and-executors.mdx + - page: "Data and Checkpoint Formats" + path: ../pages-vnightly/train-models/how-to/data-and-checkpoint-formats.mdx + - page: "Convert Checkpoints" + path: ../pages-vnightly/train-models/how-to/convert-checkpoints.mdx + - section: "Reference" + path: ../pages-vnightly/train-models/reference/index.mdx + contents: + - page: "Nemotron Steps CLI Reference" + path: ../pages-vnightly/train-models/reference/cli-reference.mdx + - page: "Env Profile Generator" + path: ../pages-vnightly/train-models/reference/env-profile-generator.mdx + - page: "Step Catalog" + path: ../pages-vnightly/train-models/reference/step-catalog.mdx + - page: "Configuration Conventions" + path: ../pages-vnightly/train-models/reference/config-conventions.mdx + - section: "SFT Steps" + path: ../pages-vnightly/train-models/reference/sft/index.mdx + contents: + - page: "sft/automodel" + path: ../pages-vnightly/train-models/reference/sft/automodel.mdx + - page: "sft/megatron_bridge" + path: ../pages-vnightly/train-models/reference/sft/megatron-bridge.mdx + - section: "PEFT Steps" + path: ../pages-vnightly/train-models/reference/peft/index.mdx + contents: + - page: "peft/automodel" + path: ../pages-vnightly/train-models/reference/peft/automodel.mdx + - page: "peft/megatron_bridge" + path: ../pages-vnightly/train-models/reference/peft/megatron-bridge.mdx + - section: "RL Steps" + path: ../pages-vnightly/train-models/reference/rl/index.mdx + contents: + - page: "rl/nemo_rl/dpo" + path: ../pages-vnightly/train-models/reference/rl/dpo.mdx + - page: "rl/nemo_rl/rlvr" + path: ../pages-vnightly/train-models/reference/rl/rlvr.mdx + - page: "rl/nemo_rl/rlhf" + path: ../pages-vnightly/train-models/reference/rl/rlhf.mdx + - section: "Optimization Steps" + path: ../pages-vnightly/train-models/reference/optimize/index.mdx + contents: + - page: "optimize/modelopt/quantize" + path: ../pages-vnightly/train-models/reference/optimize/quantize.mdx + - page: "optimize/modelopt/prune" + path: ../pages-vnightly/train-models/reference/optimize/prune.mdx + - page: "optimize/modelopt/distill" + path: ../pages-vnightly/train-models/reference/optimize/distill.mdx + - section: "Checkpoint Conversion Steps" + path: ../pages-vnightly/train-models/reference/convert/index.mdx + contents: + - page: "convert/hf_to_megatron" + path: ../pages-vnightly/train-models/reference/convert/hf-to-megatron.mdx + - page: "convert/megatron_to_hf" + path: ../pages-vnightly/train-models/reference/convert/megatron-to-hf.mdx + - page: "convert/merge_lora" + path: ../pages-vnightly/train-models/reference/convert/merge-lora.mdx + - section: "Model Evaluation" + contents: + - page: "About" + path: ../pages-vnightly/model-eval/index.mdx + - page: "Getting Started" + path: ../pages-vnightly/model-eval/getting-started.mdx + - page: "Tips for Using Agents" + path: ../pages-vnightly/model-eval/using-skills.mdx + - section: "Concepts" + path: ../pages-vnightly/model-eval/explanation/index.mdx + contents: + - page: "Pipeline Overview" + path: ../pages-vnightly/model-eval/explanation/pipeline-overview.mdx + - page: "Endpoint Types And Task Families" + path: ../pages-vnightly/model-eval/explanation/endpoint-types-and-benchmarks.mdx + - page: "Tokenizer Alignment" + path: ../pages-vnightly/model-eval/explanation/tokenizer-alignment.mdx + - section: "Tasks" + path: ../pages-vnightly/model-eval/how-to/index.mdx + contents: + - page: "Discover The Model Evaluation Step" + path: ../pages-vnightly/model-eval/how-to/discover-the-step.mdx + - page: "Run A Hosted Evaluation" + path: ../pages-vnightly/model-eval/how-to/run-hosted-evaluation.mdx + - page: "Evaluate A Deployed Checkpoint" + path: ../pages-vnightly/model-eval/how-to/evaluate-deployed-checkpoint.mdx + - section: "Reference" + path: ../pages-vnightly/model-eval/reference/index.mdx + contents: + - page: "Configuration Reference" + path: ../pages-vnightly/model-eval/reference/config-schema.mdx + - page: "CLI Reference" + path: ../pages-vnightly/model-eval/reference/cli-reference.mdx + - page: "Output Artifacts" + path: ../pages-vnightly/model-eval/reference/output-artifacts.mdx + - page: "Tasks Catalog" + path: ../pages-vnightly/model-eval/reference/benchmarks-catalog.mdx + - page: "Troubleshooting" + path: ../pages-vnightly/model-eval/reference/troubleshooting.mdx + - section: "Training Recipes" + contents: + - section: "Nemotron 3 Nano" + path: ../pages-vnightly/nemotron/nano3/README.mdx + contents: + - page: "Stage 0: Pretraining" + path: ../pages-vnightly/nemotron/nano3/pretrain.mdx + - page: "Stage 1: Supervised Fine-Tuning (SFT)" + path: ../pages-vnightly/nemotron/nano3/sft.mdx + - page: "Stage 2: Reinforcement Learning (RL)" + path: ../pages-vnightly/nemotron/nano3/rl.mdx + - page: "Stage 3: Evaluation" + path: ../pages-vnightly/nemotron/nano3/evaluate.mdx + - page: "Importing Models and Data" + path: ../pages-vnightly/nemotron/nano3/import.mdx + - section: "Nemotron 3 Omni" + path: ../pages-vnightly/nemotron/omni3/README.mdx + contents: + - page: "Stage 0: Supervised Fine-Tuning (SFT)" + path: ../pages-vnightly/nemotron/omni3/sft.mdx + - page: "Stage 1: Reinforcement Learning (RL)" + path: ../pages-vnightly/nemotron/omni3/rl.mdx + - page: "RL Data Preparation" + path: ../pages-vnightly/nemotron/omni3/rl/data-prep.mdx + - page: "Nemotron 3 Nano Omni — Architecture" + path: ../pages-vnightly/nemotron/omni3/architecture.mdx + - page: "Nemotron 3 Nano Omni — Inference & Deployment" + path: ../pages-vnightly/nemotron/omni3/inference.mdx + - section: "Nemotron 3 Super" + path: ../pages-vnightly/nemotron/super3/README.mdx + contents: + - page: "Stage 0: Pretraining" + path: ../pages-vnightly/nemotron/super3/pretrain.mdx + - page: "Stage 1: Supervised Fine-Tuning (SFT)" + path: ../pages-vnightly/nemotron/super3/sft.mdx + - section: "Stage 2: Reinforcement Learning (RL)" + path: ../pages-vnightly/nemotron/super3/rl/index.mdx + contents: + - page: "Multi-Environment RLVR (Stages 1.1–1.3)" + path: ../pages-vnightly/nemotron/super3/rl/rlvr.mdx + - page: "SWE-RL (Stages 2.1–2.2)" + path: ../pages-vnightly/nemotron/super3/rl/swe.mdx + - page: "RLHF (Stage 3)" + path: ../pages-vnightly/nemotron/super3/rl/rlhf.mdx + - page: "RL Data Preparation" + path: ../pages-vnightly/nemotron/super3/rl/data-prep.mdx + - page: "Stage 4: Evaluation" + path: ../pages-vnightly/nemotron/super3/evaluate.mdx + - page: "Stage 3: Quantization" + path: ../pages-vnightly/nemotron/super3/quantization.mdx + - page: "Llama Nemotron Embed" + path: ../pages-vnightly/nemotron/embed/README.mdx + - page: "Artifact Types & Lineage" + path: ../pages-vnightly/nemotron/artifacts.mdx + - section: "Nemotron Kit" + contents: + - page: "Nemotron Kit" + path: ../pages-vnightly/nemotron/kit.mdx + - page: "NVIDIA AI Stack" + path: ../pages-vnightly/nemotron/nvidia-stack.mdx + - page: "nemo_runspec Package" + path: ../pages-vnightly/nemo_runspec/package-readme.mdx + - page: "Execution through NeMo-Run" + path: ../pages-vnightly/nemo_runspec/nemo-run.mdx + - page: "OmegaConf Configuration System" + path: ../pages-vnightly/nemo_runspec/omegaconf.mdx + - page: "Artifact Tracking" + path: ../pages-vnightly/nemo_runspec/artifacts.mdx + - page: "Weights & Biases Integration" + path: ../pages-vnightly/nemotron/wandb.mdx + - page: "CLI Framework" + path: ../pages-vnightly/nemotron/cli.mdx + - page: "Data Preparation Module" + path: ../pages-vnightly/nemotron/data-prep.mdx + - page: "Xenna Pipeline Observability" + path: ../pages-vnightly/nemotron/xenna-observability.mdx + - section: "Data Recipes" + contents: + - page: "Nemotron-CC Data Curation" + path: ../pages-vnightly/nemotron/data/curation/nemotron-cc.mdx + - page: "Long-Document SDG" + path: ../pages-vnightly/nemotron/data/sdg/long-document.mdx + - section: "Architecture" + contents: + - page: "Nemotron Architecture" + path: ../pages-vnightly/architecture/README.mdx + - page: "Design Philosophy" + path: ../pages-vnightly/architecture/design-philosophy.mdx + - page: "CLI Architecture" + path: ../pages-vnightly/architecture/cli-architecture.mdx + - page: "Runspec: [tool.runspec] Specification" + path: ../pages-vnightly/runspec/v1/spec.mdx diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index a4102ca4b..000000000 --- a/docs/index.md +++ /dev/null @@ -1,363 +0,0 @@ - -# Nemotron Training Recipes - -**Open and efficient models for agentic AI.** Reproducible training pipelines with transparent data, techniques, and weights. - -
- -
- -## Quick Start - -
- -```console -// Install the Nemotron training recipes -$ git clone https://github.com/NVIDIA-NeMo/Nemotron -$ cd Nemotron && uv sync - -// Run a tiny SFT job on your cluster -$ uv run nemotron steps run sft/automodel -c tiny --run YOUR-CLUSTER - -// Run the Nano3 pipeline stage by stage -$ uv run nemotron nano3 data prep pretrain --run YOUR-CLUSTER -$ uv run nemotron nano3 pretrain --run YOUR-CLUSTER -$ uv run nemotron nano3 data prep sft --run YOUR-CLUSTER -$ uv run nemotron nano3 sft --run YOUR-CLUSTER -$ uv run nemotron nano3 data prep rl --run YOUR-CLUSTER -$ uv run nemotron nano3 rl --run YOUR-CLUSTER -``` - -
- -> **Note**: The `--run YOUR-CLUSTER` flag submits jobs to your configured Slurm cluster via [NeMo-Run](nemo_runspec/nemo-run.md). See [Execution through NeMo-Run](nemo_runspec/nemo-run.md) for setup instructions. - -## Sample Deployments and Applications - -::::{grid} 1 2 2 2 -:gutter: 3 - -:::{grid-item-card} Deployment Guides -:link: deployment-guides -:link-type: doc - -Deployment guides for Nemotron models: TensorRT-LLM, vLLM, SGLang, NIM, and Hugging Face. -::: - -:::{grid-item-card} Sample Applications -:link: application-examples -:link-type: doc - -End-to-end applications: RAG agents, ML agents, and multi-agent systems. -::: - -:::: - -## Customization Workflows with Nemotron Steps - -::::{grid} 1 2 2 2 -:gutter: 3 - -:::{grid-item-card} Translation -:link: translation/index -:link-type: doc - -Translate JSONL or Parquet corpora with `translate/nemo_curator`, NeMo Curator -backends, and optional FAITH quality scoring. -::: - -:::{grid-item-card} Build MCQ Benchmarks -:link: build-benchmarks/index -:link-type: doc - -Generate and translate custom multiple-choice benchmarks with `byob/mcq`. -::: - -:::{grid-item-card} Data Curation -:link: curate/index -:link-type: doc - -Filter JSONL text with `curate/nemo_curator` before translation or training data preparation. -::: - -:::{grid-item-card} Synthetic Data Generation -:link: sdg/index -:link-type: doc - -Use `sdg/data_designer` to produce SFT, tool-use, and preference datasets. -::: - -:::{grid-item-card} Model Evaluation -:link: model-eval/index -:link-type: doc - -Evaluate hosted endpoints or checkpoints with `eval/model_eval`. -::: - -:::: - -## Training Recipes - -::::{grid} 1 2 2 2 -:gutter: 3 - -:::{grid-item-card} Nemotron 3 Nano -:link: nemotron/nano3/README -:link-type: doc - -31.6B total / 3.6B active parameters, 25T tokens, up to 1M context. Hybrid Mamba-Transformer with sparse MoE. - -**Stages:** Pretraining → SFT → RL -::: - -:::{grid-item-card} Nemotron 3 Omni -:link: nemotron/omni3/README -:link-type: doc - -GA-checkpoint multimodal post-training recipe with stage-local container builds and a three-step RL stack. - -**Stages:** SFT → RL MPO → RL text → RL vision → Eval -::: - -:::{grid-item-card} Embedding Fine-Tuning -:link: nemotron/embed/README -:link-type: doc - -Fine-tune Llama-Nemotron-Embed-1B-v2 on domain-specific data with synthetic data generation, evaluation, and NIM deployment. - -**Stages:** SDG → Data Prep → Finetune → Eval → Export → Deploy -::: - -:::{grid-item-card} Reranking Fine-Tuning -:link: nemotron/rerank/README -:link-type: doc - -Fine-tune Llama-Nemotron-Rerank-1B-v2 cross-encoders for domain-specific reranking with synthetic data generation, evaluation, export, and NIM deployment. - -**Stages:** SDG → Data Prep → Finetune → Eval → Export → Deploy -::: - -:::: - -## Recipe Layout - -Nemotron keeps **data-producing recipes** separate from **model-family training recipes**: - -| Path | Purpose | Example | -|------|---------|---------| -| `src/nemotron/recipes/data/curation/` | Filter, dedup, and curate existing corpora | [Nemotron-CC](nemotron/data/curation/nemotron-cc.md) | -| `src/nemotron/recipes/data/sdg/` | Generate synthetic datasets that can feed multiple families | [Long-document SDG](nemotron/data/sdg/long-document.md) feeding [Omni3 SFT](nemotron/omni3/sft.md) | -| `src/nemotron/recipes//` | Family-specific training, RL, evaluation, and model lifecycle commands | [Nano3](nemotron/nano3/README.md), [Omni3](nemotron/omni3/README.md) | - -## Training Pipeline - -Each recipe family has its own stage layout, and all of them can be tracked through [artifact lineage](nemotron/artifacts.md): - -| Family | Stage layout | -|--------|--------------| -| [Nano3](nemotron/nano3/README.md) | Pretraining → SFT → RL | -| [Omni3](nemotron/omni3/README.md) | SFT → RL MPO → RL text → RL vision → Eval | -| [Super3](nemotron/super3/README.md) | Pretraining → SFT → RL → Quantization → Eval | -| [Embed](nemotron/embed/README.md) | SDG → Data Prep → Finetune → Eval → Export → Deploy | -| [Rerank](nemotron/rerank/README.md) | SDG → Data Prep → Finetune → Eval → Export → Deploy | - -## Why Nemotron? - -| | | -|---|---| -| **Open Models** | Transparent training data, techniques, and weights for community innovation | -| **Compute Efficiency** | Model pruning enabling higher throughput via TensorRT-LLM | -| **High Accuracy** | Built on frontier open models with human-aligned reasoning | -| **Flexible Deployment** | Deploy anywhere: edge, single GPU, or data center with NIM | - -## Features - -- **End-to-end pipelines** from raw data to deployment-ready models -- **[Artifact lineage](nemotron/artifacts.md)** via [W&B](nemotron/wandb.md) from data to model -- **Built on [NVIDIA's NeMo stack](nemotron/nvidia-stack.md)** (Megatron-Bridge, NeMo-RL) -- **Reproducible** with versioned configs, data blends, and checkpoints - -## Resources - -- [Tech Report](https://research.nvidia.com/labs/nemotron/files/NVIDIA-Nemotron-3-Nano-Technical-Report.pdf) – Nemotron 3 Nano methodology -- [Model Weights](https://huggingface.co/collections/nvidia/nvidia-nemotron-v3) – pre-trained checkpoints on HuggingFace -- [Pre-training Datasets](https://huggingface.co/collections/nvidia/nemotron-pre-training-datasets) – open pre-training data -- [Post-training Datasets](https://huggingface.co/collections/nvidia/nemotron-post-training-v3) – SFT and RL data -- [Artifact Lineage](nemotron/artifacts.md) – W&B integration guide -- [Model training steps](train-models/index.md) – SFT, PEFT, RL, and optimization with `nemotron step run` - -```{toctree} -:caption: Nemotron -:hidden: - -Home -application-examples.md -deployment-guides.md -``` - -```{toctree} -:caption: Nemotron Step Basics -:hidden: - -About -Basics -Getting Started -Airgap Environment -``` - -```{toctree} -:caption: Data Curation -:hidden: - -About -Getting Started -Tasks -Reference -``` - -```{toctree} -:caption: Synthetic Data Generation -:hidden: - -About -Getting Started -Tips for Using Agents -Planning -Tasks -Reference -``` - -```{toctree} -:caption: Translation -:hidden: - -About -Getting Started -Tips for Using Agents -translation/explanation/index.md -Tasks -Reference -``` - -```{toctree} -:caption: Build MCQ Benchmarks -:hidden: - -About -Getting Started -Concepts -Tasks -Reference -``` - -```{toctree} -:caption: Model Training -:hidden: - -About -Getting Started -Tips for Using Agents -Concepts -Tasks -Reference -``` - -```{toctree} -:caption: Model Evaluation -:hidden: - -About -Getting Started -Tips for Using Agents -Concepts -Tasks -Reference -``` - -```{toctree} -:caption: Training Recipes -:hidden: - -Nemotron 3 Nano -Nemotron 3 Omni -Nemotron 3 Super -Llama Nemotron Embed -Llama Nemotron Rerank -nemotron/artifacts.md -``` - -```{toctree} -:caption: Nano3 Stages -:hidden: - -nemotron/nano3/pretrain.md -nemotron/nano3/sft.md -nemotron/nano3/rl.md -nemotron/nano3/evaluate.md -nemotron/nano3/import.md -``` - -```{toctree} -:caption: Omni3 Stages -:hidden: - -nemotron/omni3/README.md -nemotron/omni3/sft.md -nemotron/omni3/rl.md -nemotron/omni3/rl/data-prep.md -nemotron/omni3/architecture.md -nemotron/omni3/inference.md -``` - -```{toctree} -:caption: Super3 Stages -:hidden: - -nemotron/super3/README.md -nemotron/super3/pretrain.md -nemotron/super3/sft.md -nemotron/super3/rl/index.md -nemotron/super3/rl/rlvr.md -nemotron/super3/rl/swe.md -nemotron/super3/rl/rlhf.md -nemotron/super3/rl/data-prep.md -nemotron/super3/evaluate.md -nemotron/super3/quantization.md -``` - -```{toctree} -:caption: Nemotron Kit -:hidden: - -nemotron/kit.md -nemotron/nvidia-stack.md -nemo_runspec/package-readme.md -nemo_runspec/nemo-run.md -nemo_runspec/omegaconf.md -nemo_runspec/artifacts.md -nemotron/wandb.md -nemotron/cli.md -nemotron/data-prep.md -nemotron/xenna-observability.md -``` - -```{toctree} -:caption: Data Recipes -:hidden: - -nemotron/data/curation/nemotron-cc.md -nemotron/data/sdg/long-document.md -``` - -```{toctree} -:caption: Architecture -:hidden: - -architecture/README.md -architecture/design-philosophy.md -architecture/cli-architecture.md -runspec/v1/spec.md -``` diff --git a/docs/model-eval/explanation/endpoint-types-and-benchmarks.md b/docs/model-eval/explanation/endpoint-types-and-benchmarks.md deleted file mode 100644 index 8ed4a16e7..000000000 --- a/docs/model-eval/explanation/endpoint-types-and-benchmarks.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Why eval/model_eval couples endpoint type to NeMo Evaluator Launcher task family." -topics: ["Model Evaluation", "Endpoints"] -tags: ["Explanation", "Model Evaluation"] -content: - type: "Explanation" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] ---- - -(model-eval-endpoint-types-and-benchmarks)= -# Endpoint Types And Task Families - -`eval/model_eval` passes endpoint and task configuration to NeMo Evaluator Launcher. -The endpoint type must match the selected task family. - -## Endpoint Fields - -Hosted endpoint runs use: - -```text -target.api_endpoint.url -target.api_endpoint.model_id -target.api_endpoint.api_key_name -target.api_endpoint.type -``` - -The `type` value is usually `chat` or `completions`. -The URL path should agree with that value. - -## Task Families - -- Chat and instruction tasks issue chat-completions requests and score generated answers. -- Log-probability tasks need a completions endpoint with logprobs support and a tokenizer that matches the served model. - -## Decision Table - -| Task family | Required endpoint type | Extra requirements | -| --- | --- | --- | -| Hosted chat smoke tests | `chat` | A chat-completions URL and a valid API key. | -| Instruction/chat tasks | `chat` | Generation parameters appropriate for the model and task. | -| Log-probability tasks | `completions` | A completions endpoint with logprobs support and a matching tokenizer. | - -The repository smoke-test config, `tiny_chat.yaml`, uses `mmlu_instruct` with `target.api_endpoint.type=chat`. -The checkpoint config, `default.yaml`, includes launcher tasks for Megatron checkpoint evaluation; verify endpoint and tokenizer requirements before changing those tasks. - -## Related Pages - -- {doc}`tokenizer-alignment` for the tokenizer side of log-probability tasks. -- {doc}`pipeline-overview` for where endpoint config enters the run. -- {doc}`../how-to/evaluate-deployed-checkpoint` for choosing the hosted or checkpoint path. -- {doc}`../reference/benchmarks-catalog` for task identifiers. diff --git a/docs/model-eval/explanation/index.md b/docs/model-eval/explanation/index.md deleted file mode 100644 index f0b2a94a1..000000000 --- a/docs/model-eval/explanation/index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Concept pages for nemotron eval/model_eval: pipeline architecture, endpoint and benchmark families, and tokenizer alignment." -topics: ["Model Evaluation", "Concepts"] -tags: ["Explanation", "Model Evaluation"] -content: - type: "Explanation" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] ---- - -# Concepts - -The pages in this section cover the design rules behind `eval/model_eval`. -Read them when you want to understand why the how-to pages take the actions they do, before you change a configuration default or adapt a recipe to a new deployment. - -```{toctree} -:maxdepth: 1 -:hidden: - -pipeline-overview -endpoint-types-and-benchmarks -tokenizer-alignment -``` - -## Pipeline And Architecture - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`graph;1.5em;sd-mr-1` Pipeline Overview -:link: pipeline-overview -:link-type: doc -Artifact flow from a checkpoint or hosted endpoint, through `eval/model_eval`, into `eval_results` on disk. -+++ -{bdg-secondary}`architecture` -::: - -:::: - -## Deployment Contract - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`plug;1.5em;sd-mr-1` Endpoint Types And Benchmark Families -:link: endpoint-types-and-benchmarks -:link-type: doc -Chat versus completions endpoints, and which benchmark families match each one. -+++ -{bdg-secondary}`endpoint` -::: - -:::{grid-item-card} {octicon}`package;1.5em;sd-mr-1` Tokenizer Alignment -:link: tokenizer-alignment -:link-type: doc -Why log-probability benchmarks need a tokenizer that matches the served model. -+++ -{bdg-secondary}`tokenizer` -::: - -:::: diff --git a/docs/model-eval/getting-started.md b/docs/model-eval/getting-started.md deleted file mode 100644 index e02470b43..000000000 --- a/docs/model-eval/getting-started.md +++ /dev/null @@ -1,123 +0,0 @@ - - -(model-eval-getting-started)= -# Getting Started With Model Evaluation - -::::{grid} 2 - -:::{grid-item-card} -:columns: 8 - -**What You'll Build**: one NeMo Evaluator Launcher result directory for a single hosted chat smoke-test task, written by the `eval/model_eval` step. - -^^^ - -**In this tutorial, you will**: - -1. Discover the `eval/model_eval` step from the local catalog. -1. Inspect the hosted-endpoint sample config, `tiny_chat.yaml`. -1. Run a one-sample hosted chat evaluation. -1. List the result files on disk. - -{octicon}`clock;1.5em;sd-mr-1` This tutorial requires between 15 and 30 minutes to complete, depending on endpoint latency. -::: - -:::{grid-item-card} {octicon}`flame;1.5em;sd-mr-1` **Sample Prompt** -:columns: 4 - -Run a one-sample hosted chat evaluation with `eval/model_eval` and `tiny_chat.yaml`, then show me the launcher config and result files. -::: -:::: - -## Prerequisites - -- Run all commands from the repository root. -- Install the evaluator extra: - - ```console - $ uv sync --extra evaluator - ``` - -- A reachable OpenAI-compatible chat-completions endpoint. -- A model identifier advertised by that endpoint. -- A bearer token exported as the environment variable referenced by `target.api_endpoint.api_key_name`. - -## About The Sample Configuration - -The hosted chat sample file is at `src/nemotron/steps/eval/model_eval/config/tiny_chat.yaml`. -It sets `deployment.type: none`, points NeMo Evaluator Launcher at `target.api_endpoint`, and runs the chat-compatible `mmlu_instruct` task with `limit_samples: 1`. - -```{literalinclude} ../../src/nemotron/steps/eval/model_eval/config/tiny_chat.yaml -:language: yaml -``` - -## Procedure - -1. Clone the repository, if you haven't already: - - ```console - $ git clone https://github.com/NVIDIA-NeMo/Nemotron && cd Nemotron - ``` - -1. Synchronize dependencies: - - ```console - $ uv sync --extra evaluator - ``` - -1. Export the endpoint values. - `EVAL_ROOT` is a directory you choose; it is the parent of the per-run `output_dir`. - - ```console - $ export NVIDIA_API_KEY="" - $ export NEMO_EVALUATOR_MODEL_URL="" - $ export NEMO_EVALUATOR_MODEL_ID="" - $ export NEMO_EVALUATOR_ENDPOINT_TYPE=chat - $ export EVAL_ROOT="$(pwd)/output/eval-getting-started" - ``` - -1. Confirm that the local catalog exposes `eval/model_eval`. - - ```console - $ uv run --no-sync nemotron steps show eval/model_eval - ``` - -1. Run the hosted chat smoke test. - - ```console - $ uv run --no-sync nemotron steps run eval/model_eval \ - -c tiny_chat \ - output_dir="$EVAL_ROOT/results-tiny-chat" \ - target.api_endpoint.url="$NEMO_EVALUATOR_MODEL_URL" \ - target.api_endpoint.model_id="$NEMO_EVALUATOR_MODEL_ID" \ - target.api_endpoint.api_key_name=NVIDIA_API_KEY \ - target.api_endpoint.type=chat \ - evaluation.nemo_evaluator_config.config.params.limit_samples=1 - ``` - - The step writes the launcher config path to stdout. - If NeMo Evaluator Launcher returns an invocation id, the step also prints `status_command` and `logs_command` values that you can run to inspect the job. - Treat those commands as part of the run: wait until the launcher reports a - terminal status before expecting final metric artifacts. - - To inspect the merged Nemotron job config without invoking the launcher, add `--dry-run`. - To pass NeMo Evaluator Launcher's own dry-run flag, use the config override `dry_run=true`. - -1. List the files written under the output directory after the launcher job - reaches a terminal status. - - ```console - $ find "$EVAL_ROOT/results-tiny-chat" -maxdepth 5 -type f | sort - ``` - - The exact file names are owned by NeMo Evaluator Launcher and can vary by task version. - -## Next Steps - -- Run the standard checkpoint-evaluation config: {doc}`how-to/evaluate-deployed-checkpoint`. -- Look up the full YAML schema: {doc}`reference/config-schema`. -- Drive the step from a coding agent: {doc}`using-skills`. -- Run hosted evaluations with custom task settings: {doc}`how-to/run-hosted-evaluation`. diff --git a/docs/model-eval/how-to/discover-the-step.md b/docs/model-eval/how-to/discover-the-step.md deleted file mode 100644 index 43200fdcc..000000000 --- a/docs/model-eval/how-to/discover-the-step.md +++ /dev/null @@ -1,75 +0,0 @@ - - -(model-eval-discover-the-step)= -# Discover The Model Evaluation Step - -This guide shows how to find `eval/model_eval` in the step catalog, how to read its contract, and how to decide whether it applies. - -## Prerequisites - -- The Nemotron repository is synced. -- A local checkout is sufficient; discovery reads local `step.toml` files only. - -## List Eval-Category Steps - -```bash -uv run --no-sync nemotron steps list --category eval --json -``` - -The response includes `eval/model_eval`, the step that wraps NeMo Evaluator Launcher. - -## Inspect The Step Contract - -```bash -uv run --no-sync nemotron steps show eval/model_eval --json -``` - -The response contains the fields declared in `src/nemotron/steps/eval/model_eval/step.toml`. - -| Field | What It Tells You | -| --- | --- | -| `consumes` | Optional input artifact type. This step accepts `checkpoint_megatron`. | -| `produces` | Output artifact type. This step produces `eval_results`. | -| `parameters` | Documented knobs such as `target.api_endpoint.*`, `deployment.checkpoint_path`, `task_filters`, and launcher params. | -| `strategies` | Rules for hosted smoke tests, checkpoint evaluation, endpoint/task pairing, and task-name selection. | -| `errors` | Named failure modes and recovery guidance. | -| `reference` | Upstream NeMo Evaluator Launcher references. | - -## Read The Sample Files - -The step provides two config files under `src/nemotron/steps/eval/model_eval/config/`. - -```{literalinclude} ../../../src/nemotron/steps/eval/model_eval/config/tiny_chat.yaml -:language: yaml -``` - -`tiny_chat.yaml` is the hosted chat smoke-test config. -It sets `deployment.type: none`, reads `target.api_endpoint.*` from environment variables, and runs `mmlu_instruct` with `limit_samples: 1`. - -```{literalinclude} ../../../src/nemotron/steps/eval/model_eval/config/default.yaml -:language: yaml -``` - -`default.yaml` is the Megatron Bridge checkpoint evaluation config. -It uses NeMo Evaluator Launcher deployment and evaluates the configured `tasks` entries. - -## Decide Whether It Applies - -`eval/model_eval` applies when the following statements are true. - -- The model is already available as an OpenAI-compatible endpoint, or NeMo Evaluator Launcher can deploy the checkpoint from the selected config. -- The tasks you need are implemented by the installed NeMo Evaluator Launcher stack. -- The endpoint type matches the selected task family. - -`eval/model_eval` is not the right step when the evaluation needs a custom scorer that NeMo Evaluator Launcher does not implement. -Write a dedicated evaluation step in that case, modeled on the contract layout under `src/nemotron/steps/`. - -## Related - -- `src/nemotron/steps/eval/model_eval/step.toml` for the full step contract. -- {doc}`run-hosted-evaluation` for the first procedural walk-through after discovery. -- {doc}`../reference/config-schema` for field-by-field YAML reference. -- {doc}`../reference/cli-reference` for the flag and override surface. diff --git a/docs/model-eval/how-to/index.md b/docs/model-eval/how-to/index.md deleted file mode 100644 index a0cc678d8..000000000 --- a/docs/model-eval/how-to/index.md +++ /dev/null @@ -1,51 +0,0 @@ - - -(model-eval-how-to-index)= -# Model Evaluation How-To Guides - -This section provides task-focused procedures for running `eval/model_eval`. -For your first run, start with {doc}`../getting-started`. -For agent-driven sessions, read {doc}`../using-skills` first. - -## Choose A Guide - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`search;1.5em;sd-mr-1` Discover The Step -:link: discover-the-step -:link-type: doc -List the step, read its contract, and decide whether it applies to the task. -+++ -{bdg-secondary}`discovery` -::: - -:::{grid-item-card} {octicon}`play;1.5em;sd-mr-1` Run A Hosted Evaluation -:link: run-hosted-evaluation -:link-type: doc -Run benchmarks against an already-running, OpenAI-compatible endpoint. -+++ -{bdg-secondary}`hosted-endpoint` -::: - -:::{grid-item-card} {octicon}`server;1.5em;sd-mr-1` Evaluate A Deployed Checkpoint -:link: evaluate-deployed-checkpoint -:link-type: doc -Choose a deployment path, deploy the endpoint, and point the step at it. -+++ -{bdg-secondary}`deployment` -::: - -:::: - -```{toctree} -:hidden: -:maxdepth: 1 - -discover-the-step -run-hosted-evaluation -evaluate-deployed-checkpoint -``` diff --git a/docs/model-eval/index.md b/docs/model-eval/index.md deleted file mode 100644 index 711e23073..000000000 --- a/docs/model-eval/index.md +++ /dev/null @@ -1,170 +0,0 @@ - - -(model-eval-index)= -# About Model Evaluation - -The `eval/model_eval` Nemotron step is a wrapper around NeMo Evaluator Launcher. -It runs launcher tasks against either an existing OpenAI-compatible endpoint or a launcher-managed Megatron Bridge checkpoint deployment, then writes an `eval_results` artifact to disk. - -:::{tip} -New to model evaluation or the Nemotron CLI? -Read {doc}`using-skills` for a short guide to productive agent sessions, then start the {doc}`getting-started` tutorial to run one benchmark on one sample against a hosted endpoint. -::: - -## When To Use - -Use `eval/model_eval` when the work matches one of the following. - -- Score a trained checkpoint with NeMo Evaluator Launcher tasks. -- Compare a new training run against a baseline by running the same task set against both, with generation parameters and endpoint type held constant. -- Perform a sample run against a hosted endpoint, to confirm the URL, credential, and model id before scaling up. -- Pair this step with a baseline evaluation before training to capture before-and-after measurements around a training change, by following {ref}`model-eval-comparing-runs`. - -## Pipeline At A Glance - -```{mermaid} -%%{init: {'theme': 'base', 'themeVariables': { 'primaryBorderColor': '#333333', 'lineColor': '#333333', 'primaryTextColor': '#333333', 'clusterBkg': '#ffffff', 'clusterBorder': '#333333'}}}%% -flowchart LR - ckpt["Hugging Face or
Megatron Bridge checkpoint"] --> deploy["OpenAI-compatible
endpoint"] - hosted["Hosted endpoint"] --> deploy - deploy --> step["eval/model_eval
(NeMo Evaluator)"] - step --> results["eval_results
per-benchmark subdirs"] -``` - -NeMo Evaluator Launcher owns task execution and result files under `output_dir`. -For the contract and the on-disk layout, refer to {doc}`reference/output-artifacts`. - -## How It Works - -The runner reads a single YAML document, applies command-line overrides, removes Nemotron-only keys, saves the resolved launcher config, and calls `nemo_evaluator_launcher.api.functional.run_eval`. - -The endpoint type must match the benchmark family. -Chat and instruction benchmarks need a *chat* endpoint. -*Log-probability* tasks, such as HellaSwag, need a *completions* endpoint with `logprobs` support and a tokenizer that matches the served model. - -The hosted smoke-test config is `tiny_chat.yaml`. -The checkpoint-evaluation config is `default.yaml`. -Generation settings live under `evaluation.nemo_evaluator_config.config.params`. - -For the full concept set behind these design rules, refer to {doc}`explanation/index`. - -## Documentation - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`rocket;1.5em;sd-mr-1` Getting Started -:link: getting-started -:link-type: doc -Run one benchmark on one sample against a hosted endpoint, end to end. -+++ -{bdg-success}`15-30 min` {bdg-secondary}`tutorial` -::: - -:::{grid-item-card} {octicon}`heart;1.5em;sd-mr-1` Use The Model Evaluation Skill With Confidence -:link: using-skills -:link-type: doc -Run a productive agent session: opening brief, four required inputs, and how `SKILL.md` keeps the session focused. -+++ -{bdg-success}`10 min read` {bdg-secondary}`newcomer` -::: - -:::{grid-item-card} {octicon}`checklist;1.5em;sd-mr-1` How-To Guides -:link: how-to/index -:link-type: doc -Discover the step, run a hosted evaluation, and evaluate a deployed checkpoint. -+++ -{bdg-success}`3 guides` {bdg-secondary}`task-focused` -::: - -:::{grid-item-card} {octicon}`list-unordered;1.5em;sd-mr-1` Reference -:link: reference/index -:link-type: doc -YAML schema, command-line flags, output artifact layout, benchmark catalog, and troubleshooting. -+++ -{bdg-success}`5 references` {bdg-secondary}`lookup` -::: - -:::{grid-item-card} {octicon}`book;1.5em;sd-mr-1` Concepts -:link: explanation/index -:link-type: doc -Architecture, endpoint and benchmark families, and tokenizer alignment. -+++ -{bdg-success}`3 pages` {bdg-secondary}`explanation` -::: - -:::: - -## All Documentation - -````{tab-set} - -```{tab-item} Getting Started - -| Guide | What You Will Do | Time | -|---|---|---| -| {doc}`getting-started` | Run a one-sample evaluation against a hosted endpoint | 15-30 min | -| {doc}`using-skills` | Drive `eval/model_eval` from a coding agent | 10 min read | - -``` - -```{tab-item} How-To Guides - -| Guide | What You Will Do | -|---|---| -| {doc}`how-to/discover-the-step` | List the step, read its contract, and decide whether it applies | -| {doc}`how-to/run-hosted-evaluation` | Run benchmarks against an already-running endpoint | -| {doc}`how-to/evaluate-deployed-checkpoint` | Pick a deployment path, then point the step at the endpoint | - -``` - -```{tab-item} Reference - -| Reference | What You Will Find | -|---|---| -| {doc}`reference/config-schema` | YAML field reference for `default.yaml` and `tiny_chat.yaml` | -| {doc}`reference/cli-reference` | Flags and Hydra overrides for `nemotron steps run eval/model_eval` | -| {doc}`reference/output-artifacts` | `eval_results` contract and on-disk layout | -| {doc}`reference/benchmarks-catalog` | NeMo Evaluator Launcher task identifiers grouped by family | -| {doc}`reference/troubleshooting` | Named error modes from `step.toml`, with cause and recovery | - -``` - -```{tab-item} Concepts - -| Concept | What You Will Learn | -|---|---| -| {doc}`explanation/index` | Map of the concept pages and how they relate | -| {doc}`explanation/pipeline-overview` | Artifact flow from checkpoint through `eval/model_eval` into `eval_results` | -| {doc}`explanation/endpoint-types-and-benchmarks` | Chat versus completions endpoints, and which benchmark families match each one | -| {doc}`explanation/tokenizer-alignment` | Why log-probability benchmarks need a tokenizer that matches the served model | - -``` - -```` - -## Before You Start - -- The Nemotron repository is synced and `uv sync` is complete. -- A bearer token is exported as the environment variable named in `target.api_endpoint.api_key_name`. - Hosted smoke tests usually use `NVIDIA_API_KEY`. -- A reachable evaluation endpoint URL and a model identifier the endpoint advertises. -- A tokenizer that matches the served model when running log-probability tasks. - The hosted chat smoke test does not require a tokenizer override. - -## Limitations And Considerations - -- Cost: every benchmark sample issues at least one request to the endpoint, and hosted endpoints incur per-token cost. -- Rate limits: hosted endpoints throttle concurrent requests, so set `evaluation.nemo_evaluator_config.config.params.parallelism` to a value the endpoint can serve. -- Deployment: `tiny_chat.yaml` targets an already-deployed endpoint; `default.yaml` uses launcher-managed deployment for a Megatron Bridge checkpoint. -- Comparability: scores are comparable when the endpoint type, task version, tokenizer, and generation parameters are held constant across runs. - The {ref}`model-eval-comparing-runs` section explains the framing. - -## Related Documentation - -- The full `step.toml` contract: `src/nemotron/steps/eval/model_eval/step.toml` in the repository. -- The before-and-after evaluation framing: {ref}`model-eval-comparing-runs`. -- Upstream NeMo Evaluator quick-start: . diff --git a/docs/model-eval/reference/benchmarks-catalog.md b/docs/model-eval/reference/benchmarks-catalog.md deleted file mode 100644 index b2cc53fee..000000000 --- a/docs/model-eval/reference/benchmarks-catalog.md +++ /dev/null @@ -1,70 +0,0 @@ - - -(model-eval-benchmarks-catalog)= -# Tasks Catalog - -This page catalogs task identifiers used by `eval/model_eval`. -NeMo Evaluator Launcher owns the authoritative task list. -Use this page as a quick map, then verify exact names with the installed launcher. - -```bash -nemo-evaluator-launcher ls tasks -nemo-evaluator-launcher ls task -``` - -## Naming Rule - -Use the exact task id listed by NeMo Evaluator Launcher. -Do not prepend a harness name unless the launcher lists that exact dotted id. - -## Repository Starting Points - -| Config | Task entries | When to use | -| --- | --- | --- | -| `tiny_chat.yaml` | `mmlu_instruct` | Hosted chat smoke test. | -| `default.yaml` | `adlr_mmlu`, `hellaswag` | Launcher-managed Megatron checkpoint evaluation. | - -## Chat And Instruction Tasks - -These tasks use a chat endpoint. -The hosted smoke-test config uses this family. - -| Identifier | Notes | -| --- | --- | -| `mmlu_instruct` | Chat/instruction smoke task used by `tiny_chat.yaml`. | -| `adlr_mmlu` | Configured by `default.yaml`; verify endpoint requirements in the installed launcher. | - -## Log-Probability Tasks - -These tasks generally need a completions endpoint with logprobs support and a tokenizer that matches the served model. - -| Identifier | Notes | -| --- | --- | -| `hellaswag` | Configured by `default.yaml`; requires endpoint/tokenizer compatibility for meaningful scores. | - -Configure tokenizer values under: - -```text -evaluation.nemo_evaluator_config.config.params.extra.tokenizer -evaluation.nemo_evaluator_config.config.params.extra.tokenizer_backend -``` - -## Choosing Tasks - -Ask three questions before changing the task list. - -1. Does the installed launcher list the task id exactly? -1. Does the endpoint type match the task family? -1. Is this a smoke test or a production comparison? - -For production comparisons, keep the same task list, endpoint type, tokenizer, and generation parameters across baseline and post-training runs. - -## Related - -- {doc}`config-schema` for the `tasks` section and evaluator params. -- {doc}`output-artifacts` for result layout expectations. -- {doc}`../explanation/endpoint-types-and-benchmarks` for endpoint/task pairing. -- {ref}`model-eval-comparing-runs` for before-and-after evaluation framing. diff --git a/docs/model-eval/reference/cli-reference.md b/docs/model-eval/reference/cli-reference.md deleted file mode 100644 index c57f77681..000000000 --- a/docs/model-eval/reference/cli-reference.md +++ /dev/null @@ -1,111 +0,0 @@ - - -(model-eval-cli-reference)= -# CLI Reference - -This page documents the CLI surface for `nemotron steps run eval/model_eval`. -The flags are shared by every Nemotron step. -The override examples are specific to the `eval/model_eval` YAML schema. - -## Syntax - -```bash -uv run nemotron steps run eval/model_eval [FLAGS] [HYDRA_OVERRIDES...] -``` - -Run the command from the repository root after `uv sync --extra evaluator`. -Pass the configuration name with `-c`, per-step overrides as `key=value` dotlists, and optional execution flags. - -## Flags - -| Flag | Long form | Purpose | -| --- | --- | --- | -| `-c` | `--config` | Config name inside `src/nemotron/steps/eval/model_eval/config/`, such as `default` or `tiny_chat`. Accepts a path to a YAML file. | -| `-r` | `--run` | Attached execution by using an environment profile defined in `env.toml`. | -| `-b` | `--batch` | Detached execution by using an environment profile defined in `env.toml`. | -| `-d` | `--dry-run` | Compile the Nemotron job config and exit without dispatching. | -| | `--force-squash` | Force re-squash of the container image when the selected backend builds one. | - -Invoking the command without `-c` resolves the runspec default, `default.yaml`. - -## Common Overrides - -| Override | Purpose | -| --- | --- | -| `output_dir=` | Base output directory. The runtime also writes this into `execution.output_dir` before calling NeMo Evaluator Launcher. | -| `dry_run=true` | Pass dry-run mode to NeMo Evaluator Launcher. This is different from CLI `--dry-run`, which only compiles the Nemotron job. | -| `task_filters=[,...]` | Optional subset of configured task names passed to NeMo Evaluator Launcher. | -| `target.api_endpoint.url=` | OpenAI-compatible endpoint URL for hosted evaluation when `deployment.type=none`. | -| `target.api_endpoint.model_id=` | Exact model id advertised by the hosted endpoint. | -| `target.api_endpoint.api_key_name=` | Name of the environment variable holding the bearer token. This is the variable name, not the secret. | -| `target.api_endpoint.type=` | Endpoint type expected by the selected task. | -| `evaluation.nemo_evaluator_config.config.params.limit_samples=` | Per-task sample cap for smoke tests. | -| `evaluation.nemo_evaluator_config.config.params.parallelism=` | Concurrent requests issued by the evaluator where supported. | -| `evaluation.nemo_evaluator_config.config.params.request_timeout=` | Per-request timeout in seconds. | -| `evaluation.nemo_evaluator_config.config.params.extra.tokenizer=` | Tokenizer used by log-probability tasks such as HellaSwag. | -| `deployment.checkpoint_path=` | Megatron Bridge checkpoint path used by `default.yaml` launcher deployment. | -| `deployment.image=` | Container image used by the launcher deployment in `default.yaml`. | - -## Discovery Commands - -```bash -uv run --no-sync nemotron steps list --category eval --json -uv run --no-sync nemotron steps show eval/model_eval --json -``` - -`nemotron steps show eval/model_eval --json` prints the full step contract, including `consumes`, `produces`, `parameters`, `strategies`, and `errors`. - -## Examples - -### Hosted Chat Smoke Test - -```bash -: "${NVIDIA_API_KEY:?Set NVIDIA_API_KEY}" -: "${NEMO_EVALUATOR_MODEL_URL:?Set the chat-completions endpoint URL}" -: "${NEMO_EVALUATOR_MODEL_ID:?Set the endpoint model id}" - -uv run --no-sync nemotron steps run eval/model_eval \ - -c tiny_chat \ - output_dir=./output/eval-tiny-chat \ - target.api_endpoint.url="$NEMO_EVALUATOR_MODEL_URL" \ - target.api_endpoint.model_id="$NEMO_EVALUATOR_MODEL_ID" \ - target.api_endpoint.api_key_name=NVIDIA_API_KEY \ - target.api_endpoint.type=chat \ - evaluation.nemo_evaluator_config.config.params.limit_samples=1 -``` - -### Megatron Checkpoint Evaluation Config - -Use `default.yaml` when NeMo Evaluator Launcher should deploy a Megatron Bridge checkpoint and then run the configured tasks. - -```bash -uv run --no-sync nemotron steps run eval/model_eval \ - -c default \ - output_dir=./output/eval-megatron \ - deployment.checkpoint_path=/path/to/checkpoint/iter_0001000 \ - evaluation.nemo_evaluator_config.config.params.limit_samples=1 -``` - -### Compile Without Dispatching - -```bash -uv run --no-sync nemotron steps run eval/model_eval -d -c tiny_chat \ - target.api_endpoint.url="$NEMO_EVALUATOR_MODEL_URL" \ - target.api_endpoint.model_id="$NEMO_EVALUATOR_MODEL_ID" -``` - -### Launcher Dry Run - -```bash -uv run --no-sync nemotron steps run eval/model_eval -c tiny_chat dry_run=true -``` - -## Related - -- {doc}`config-schema` for the YAML schema accepted by `-c` and dotlist overrides. -- {doc}`output-artifacts` for the on-disk layout produced under `output_dir`. -- {doc}`../how-to/run-hosted-evaluation` for a procedural walk-through. -- {doc}`../how-to/discover-the-step` for the step-contract discovery commands. diff --git a/docs/model-eval/reference/config-schema.md b/docs/model-eval/reference/config-schema.md deleted file mode 100644 index c26c4105c..000000000 --- a/docs/model-eval/reference/config-schema.md +++ /dev/null @@ -1,122 +0,0 @@ - - -(model-eval-config-schema)= -# Configuration Reference - -This page documents the YAML schema consumed by `nemotron steps run eval/model_eval`. -The step is a thin wrapper around NeMo Evaluator Launcher: it loads a YAML config, applies Hydra-style overrides, removes Nemotron-only keys, saves a launcher config, and calls `nemo_evaluator_launcher.api.functional.run_eval`. - -## Sample Configs - -| Config | Purpose | -| --- | --- | -| `tiny_chat.yaml` | Hosted chat endpoint smoke test. Uses `deployment.type: none`, `target.api_endpoint.*`, and one configured task, `mmlu_instruct`. | -| `default.yaml` | Megatron Bridge checkpoint evaluation through NeMo Evaluator Launcher. Uses launcher-managed `execution`, `deployment`, `evaluation`, and `tasks` sections. | - -## Top-Level Keys - -```{literalinclude} ../../../src/nemotron/steps/eval/model_eval/config/tiny_chat.yaml -:language: yaml -:class: scrollable -``` - -```{literalinclude} ../../../src/nemotron/steps/eval/model_eval/config/default.yaml -:language: yaml -:class: scrollable -``` - -| Key | Used By | Purpose | -| --- | --- | --- | -| `dry_run` | Nemotron runtime | Passed to NeMo Evaluator Launcher as `run_eval(..., dry_run=...)`. | -| `output_dir` | Nemotron runtime | Copied into `execution.output_dir` before launcher dispatch. | -| `task_filters` | Nemotron runtime | Optional task-name subset passed to launcher. | -| `run` | Nemotron runtime | Nemotron-side artifact, environment, and W&B interpolation. Removed before launcher dispatch. | -| `execution` | NeMo Evaluator Launcher | Where and how launcher execution runs. | -| `deployment` | NeMo Evaluator Launcher | How the evaluated model is deployed, or `type: none` for an existing endpoint. | -| `target` | NeMo Evaluator Launcher | Existing API endpoint metadata for hosted evaluation. | -| `evaluation` | NeMo Evaluator Launcher | Evaluator config, generation params, logging, caching, and adapter settings. | -| `tasks` | NeMo Evaluator Launcher | Exact task entries to run. Each entry has a `name`. | -| `export` | NeMo Evaluator Launcher | Optional export settings, such as W&B export. | - -## Hosted Endpoint Fields - -Use these fields with `tiny_chat.yaml` or any config that sets `deployment.type: none`. - -| Field | Purpose | -| --- | --- | -| `target.api_endpoint.model_id` | Exact model id advertised by the endpoint. | -| `target.api_endpoint.url` | Full OpenAI-compatible endpoint URL, including `/v1/chat/completions` or `/v1/completions`. | -| `target.api_endpoint.api_key_name` | Environment variable name that holds the bearer token. Never put the secret value in config. | -| `target.api_endpoint.type` | Endpoint type, usually `chat` for hosted chat smoke tests. | - -The `tiny_chat.yaml` file reads these values from `NEMO_EVALUATOR_MODEL_ID`, `NEMO_EVALUATOR_MODEL_URL`, `NEMO_EVALUATOR_API_KEY_NAME`, and `NEMO_EVALUATOR_ENDPOINT_TYPE`. - -## Evaluation Params - -Generation and evaluator controls live under: - -```text -evaluation.nemo_evaluator_config.config.params -``` - -Common fields are: - -| Field | Purpose | -| --- | --- | -| `temperature` | Sampling temperature for generation tasks. | -| `top_p` | Top-p nucleus sampling. | -| `max_new_tokens` | Maximum generated tokens for chat/instruction tasks. | -| `max_retries` | Request retry count. | -| `parallelism` | Request concurrency where supported. | -| `request_timeout` | Per-request timeout in seconds. | -| `limit_samples` | Optional per-task sample cap. Use `1` for smoke tests. | -| `extra.tokenizer` | Tokenizer path or Hugging Face id required by log-probability tasks. | -| `extra.tokenizer_backend` | Tokenizer backend, usually `huggingface`. | - -## Tasks - -Tasks are NeMo Evaluator Launcher task entries. -Use exact task IDs from the installed launcher, for example: - -```bash -nemo-evaluator-launcher ls tasks -nemo-evaluator-launcher ls task mmlu_instruct -``` - -The sample configs define these starting points. - -| Config | Tasks | -| --- | --- | -| `tiny_chat.yaml` | `mmlu_instruct` | -| `default.yaml` | `adlr_mmlu`, `hellaswag` | - -Do not prepend a harness name unless the launcher lists that exact dotted task id. - -## Checkpoint Deployment Fields - -The `default.yaml` config uses launcher-managed deployment for a Megatron Bridge checkpoint. -The most common override is: - -```bash -deployment.checkpoint_path=/path/to/iter_0001000 -``` - -Use the concrete `iter_*` checkpoint directory, not just the parent training output directory. -For log-probability tasks, keep the tokenizer aligned with the deployed checkpoint through `evaluation.nemo_evaluator_config.config.params.extra.tokenizer`. - -## Validation Behavior - -Nemotron does not implement a separate benchmark loop for this step. -It validates only enough to build the launcher config and import NeMo Evaluator Launcher. -Endpoint checks, task validation, result writing, and launcher invocation state are owned by NeMo Evaluator Launcher. - -## Related - -- {doc}`cli-reference` for command-line flags and Hydra override syntax. -- {doc}`benchmarks-catalog` for task identifiers grouped by endpoint family. -- {doc}`output-artifacts` for the `eval_results` contract and the on-disk layout. -- {doc}`troubleshooting` for common launcher and config failures. -- `src/nemotron/steps/eval/model_eval/step.toml` for the full step contract. diff --git a/docs/model-eval/reference/index.md b/docs/model-eval/reference/index.md deleted file mode 100644 index b484972c0..000000000 --- a/docs/model-eval/reference/index.md +++ /dev/null @@ -1,67 +0,0 @@ - - -(model-eval-reference-index)= -# Model Evaluation Reference - -Lookup pages for `eval/model_eval`. -For the section overview, refer to {doc}`../index`. -For procedural walk-throughs, refer to {doc}`../how-to/index`. - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`file-code;1.5em;sd-mr-1` Configuration Reference -:link: config-schema -:link-type: doc -YAML schema for `default.yaml` and `tiny_chat.yaml`, field by field. -+++ -{bdg-secondary}`yaml` -::: - -:::{grid-item-card} {octicon}`terminal;1.5em;sd-mr-1` CLI Reference -:link: cli-reference -:link-type: doc -`nemotron steps run eval/model_eval` flags and Hydra overrides. -+++ -{bdg-secondary}`cli` -::: - -:::{grid-item-card} {octicon}`archive;1.5em;sd-mr-1` Output Artifacts -:link: output-artifacts -:link-type: doc -The `eval_results` contract and the on-disk directory layout. -+++ -{bdg-secondary}`artifacts` -::: - -:::{grid-item-card} {octicon}`list-unordered;1.5em;sd-mr-1` Benchmarks Catalog -:link: benchmarks-catalog -:link-type: doc -Benchmark identifiers grouped by family, with endpoint-type guidance. -+++ -{bdg-secondary}`tasks` -::: - -:::{grid-item-card} {octicon}`alert;1.5em;sd-mr-1` Troubleshooting -:link: troubleshooting -:link-type: doc -Named error modes from `step.toml`, with the most common cause and the recovery for each. -+++ -{bdg-secondary}`errors` -::: - -:::: - -```{toctree} -:hidden: -:maxdepth: 1 - -config-schema -cli-reference -output-artifacts -benchmarks-catalog -troubleshooting -``` diff --git a/docs/nemo_runspec/package-readme.md b/docs/nemo_runspec/package-readme.md deleted file mode 100644 index 0f3c01fe2..000000000 --- a/docs/nemo_runspec/package-readme.md +++ /dev/null @@ -1,6 +0,0 @@ -# nemo_runspec Package - -The following content is pulled from the package source for convenience. The canonical source file in the repository is `src/nemo_runspec/README.md`. - -```{include} ../../src/nemo_runspec/README.md -``` diff --git a/docs/nemotron/data/curation/nemotron-cc.md b/docs/nemotron/data/curation/nemotron-cc.md deleted file mode 100644 index ac9bba4cd..000000000 --- a/docs/nemotron/data/curation/nemotron-cc.md +++ /dev/null @@ -1,51 +0,0 @@ -# Nemotron-CC Data Curation - -The Nemotron-CC recipe curates high-quality pretraining data from [Common Crawl](https://commoncrawl.org/), producing datasets similar to [nvidia/Nemotron-CC-v2](https://huggingface.co/datasets/nvidia/Nemotron-CC-v2). It serves as a reference for running these curation steps on your own data. - -Built on [NeMo Curator](https://github.com/NVIDIA/NeMo-Curator) and [Ray](https://ray.io/), the pipeline scales from a single machine to large GPU clusters. - -## Pipeline - -The recipe is a four-step pipeline that progressively refines raw web data into curated text and synthetic training data: - -``` -Common Crawl → Extract & Clean → Deduplicate → Quality Classify → Synthetic Data Generation -``` - -| Step | Script | Description | Resources | -|------|--------|-------------|-----------| -| 1 | `step_1-download_extract.py` | Download, extract, language ID, Unicode cleanup | CPU-only | -| 2a | `step_2a-exact_dedup.py` | GPU-accelerated exact deduplication | GPU (identify), CPU (remove) | -| 2b | `step_2b-fuzzy_dedup.py` | MinHash + LSH fuzzy deduplication | GPU (identify), CPU (remove) | -| 2c | `step_2c-substring_dedup/` | Exact substring deduplication using suffix arrays | CPU-only | -| 3 | `step_3-quality_classification.py` | Ensemble quality scoring into 20 buckets | GPU (classify), CPU (ensemble) | -| 4 | `step_4-sdg.py` | LLM-based synthetic data generation on top-quality data | GPU (local inference server, default) or CPU + external LLM endpoint (with `--no-serve-model`) | - -Steps 1–3 progressively filter and annotate the data. Step 4 generates synthetic training data (diverse QA, distillation, knowledge extraction, knowledge lists) from the highest-quality documents (buckets 18–19). - -## Getting Started - -The recipe scripts live in: - -``` -src/nemotron/recipes/data/curation/nemotron-cc/ -``` - -See the recipe README at `src/nemotron/recipes/data/curation/nemotron-cc/README.md` for detailed per-step documentation, resource recommendations, and usage examples. - -## Prerequisites - -- [NeMo Curator](https://github.com/NVIDIA/NeMo-Curator) 1.2.0 (26.04 release) or newer, installed with Ray support -- GPU(s) for steps 2a, 2b, and 3 (deduplication and classification) -- For step 4, one of: GPU(s) to host a local inference server (default), an OpenAI-compatible endpoint (self-hosted vLLM/NIM or cloud, via `--no-serve-model`), or an [NVIDIA Build](https://build.nvidia.com/) API key - -## After Curation - -Once curated, the output can be tokenized and used for downstream model training. - -## Further Reading - -- [Nemotron-CC paper](https://arxiv.org/abs/2412.02595) — methodology and evaluation -- [nvidia/Nemotron-CC-v2](https://huggingface.co/datasets/nvidia/Nemotron-CC-v2) — released dataset on Hugging Face -- [NeMo Curator](https://github.com/NVIDIA/NeMo-Curator) — the underlying data curation library -- [Data Preparation](../../data-prep.md) — last-mile processing for training diff --git a/docs/nemotron/data/sdg/long-document.md b/docs/nemotron/data/sdg/long-document.md deleted file mode 100644 index 9dd9e73ee..000000000 --- a/docs/nemotron/data/sdg/long-document.md +++ /dev/null @@ -1,129 +0,0 @@ -# Long-Document SDG - -The long-document SDG recipe generates synthetic VLM training data from PDF documents — improving long-document understanding capabilities measured against [MMLongBench-Doc](https://arxiv.org/abs/2407.01523). Output is a corpus of question/answer pairs grounded in real document images, optionally judged for quality by a frontier model. - -Built as nine PEP-723 `uv run`-able scripts that double as Nemotron CLI commands (`nemotron data sdg long-document `), and dispatchable to Slurm via [NeMo-Run](../../../nemo_runspec/nemo-run.md). Each producer stage can also auto-deploy its required vLLM endpoint via `--serve` — see below. - -## Pipeline - -``` -01 seed ──┬─ 02 ocr ──── 03 text-qa ─────┐ - ├─ 04 classify ── 05 visual-qa ┤ - ├─ 06 single-page-qa ──────────┤── 09 judge - ├─ 07 windowed-qa ─────────────┤ - └─ 08 whole-doc-qa ────────────┘ -``` - -| Stage | Description | Model | -|---|---|---| -| `seed` | Download PDFs from FinePDFs, render pages to PNG, produce per-page / windowed / whole-document seed parquets | CPU-only | -| `ocr` | OCR with text + bbox metadata via Nemotron-Parse | `nvidia/NVIDIA-Nemotron-Parse-v1.1` | -| `text-qa` | QA pairs from OCR-transcribed text | `openai/gpt-oss-120b` | -| `page-classification` | Page-type and reasoning-complexity classification | `Qwen/Qwen3-VL-30B-A3B-Instruct` | -| `visual-qa` | Visual QA grounded in page images | `Qwen/Qwen3-VL-235B-A22B-Thinking-FP8` | -| `single-page-qa` | Anchored single-page QA across Text/Table/Chart/Image/Layout | same | -| `windowed-qa` | Multi-page sliding-window QA | same | -| `whole-document-qa` | Whole-document cross-page QA | same | -| `judge` | LLM-as-a-judge scoring of any QA output | any OpenAI-compatible frontier endpoint | - -Stages 02–08 are CPU clients to a vLLM endpoint; stage 01 is CPU-only; stage 09 hits a third-party frontier API. Output of every stage is a parquet file consumable by downstream training recipes. - -## Two ways to run a stage - -Each stage works in two modes: - -1. **Standalone via `uv`** — drop into any environment with `uv` and a vLLM endpoint: - - ```bash - uv run --no-project 02-nemotron-parse-ocr-sdg.py \ - --config config/02-ocr.yaml \ - vllm_endpoint=http://localhost:8000/v1 \ - seed_path=./seed_data/seed_per_page.parquet \ - num_records=100 - ``` - -2. **Through the Nemotron CLI** — same recipes, dispatched on Slurm: - - ```bash - nemotron data sdg long-document ocr --batch -c 02-ocr \ - vllm_endpoint=http://compute-node:8000/v1 \ - seed_path=/lustre/.../seed.parquet \ - num_records=100 - ``` - -Configuration is YAML + Hydra-style `key=value` overrides validated by a Pydantic `Config` class — `nemotron data sdg long-document --help` renders the full field table. - -## Auto-deploy with `--serve` - -Producer stages (`ocr`, `text-qa`, `page-classification`, `visual-qa`, `single-page-qa`, `windowed-qa`, `whole-document-qa`) accept `--serve`. When passed, the CLI composes a multi-task NeMo-Run experiment: - -- A **serve task** on a GPU partition brings vLLM up, picks a free TCP port at runtime, polls both `/health` and `/v1/models` to confirm the served model is registered, then publishes its endpoint to a sentinel file on shared storage. -- A **client task** (the recipe) waits on the sentinel, injects `vllm_endpoint=` into its config, runs the recipe, and on exit signals the serve task to clean up. - -```bash -# OCR — auto-deploys nvidia/NVIDIA-Nemotron-Parse-v1.1 on a GPU node, -# runs the recipe against it, tears the deployment down on exit. -nemotron data sdg long-document ocr --batch prep --serve \ - -c 02-ocr \ - seed_path=/lustre/.../seed_per_page.parquet \ - num_records=100 -``` - -Override the default deployment with `--serve-config ` (configs live in `recipes/data/sdg/long-document/deployment/`). - -`--serve` is not offered for `seed` (CPU-only, no model) or `judge` (frontier endpoint, third-party hosted). - -## Cluster operational guidance - -The `seed` stage and the `--serve` *client* tasks are CPU-only. On clusters whose default partitions require GPUs (e.g. NVIDIA's dlw cluster, where `interactive` and `batch` reject CPU-only jobs), use a profile that extends the cluster profile with CPU partitions. dlw ships `[prep]`: - -```toml -[prep] -extends = "dlw" -run_partition = "cpu" -batch_partition = "cpu" -``` - -Use `--batch prep` / `--run prep` for these recipes: - -```bash -nemotron data sdg long-document seed --batch prep -c 01-seed ... -nemotron data sdg long-document ocr --batch prep --serve -c 02-ocr ... -``` - -The serve task always lands on a GPU partition (the cluster's `sdg_serve_partition` from `env.toml`, defaulting to `interactive`); the client task uses the env profile's regular `run_partition` / `batch_partition`. - -## Getting Started - -The recipe scripts live in: - -``` -src/nemotron/recipes/data/sdg/long-document/ -``` - -Refer to the [recipe README](https://github.com/NVIDIA-NeMo/Nemotron/tree/main/src/nemotron/recipes/data/sdg/long-document) for full per-stage documentation, deployment-config schema, troubleshooting, and full-pipeline examples (both manual-vLLM and `--serve` styles). - -## Prerequisites - -- `uv` installed (recipes resolve PEP 723 inline deps at run time). -- For producers (02–08): an OpenAI-compatible vLLM endpoint serving the recipe's required model — either operator-launched, or auto-deployed by `--serve`. -- For the judge (09): an OpenAI-compatible frontier endpoint with a valid API key in an env var. -- For Slurm dispatch: the [`nemotron-evaluator-launcher`-style env.toml profile](../../../nemo_runspec/nemo-run.md) for your cluster. - -## After SDG - -Once the pipeline runs, the resulting parquet files can be: - -- Published to Hugging Face Hub as a public dataset. -- Stored in internal Lustre and registered as a Nemotron / W&B artifact. -- Consumed directly by training recipes via `dataset.path` or HF-dataset-id config. - -The recipe README has copy-pasteable templates for both publish paths. - -## Further Reading - -- [Recipe README](https://github.com/NVIDIA-NeMo/Nemotron/tree/main/src/nemotron/recipes/data/sdg/long-document) — comprehensive per-stage docs, config schemas, troubleshooting. -- [Deployment config schema](https://github.com/NVIDIA-NeMo/Nemotron/tree/main/src/nemotron/recipes/data/sdg/long-document/deployment) — `--serve` deployment YAML reference. -- [MMLongBench-Doc paper](https://arxiv.org/abs/2407.01523) — the benchmark this dataset targets. -- [Nemotron-CC](../curation/nemotron-cc.md) — the sibling pretraining-data curation recipe. -- [Execution through NeMo-Run](../../../nemo_runspec/nemo-run.md) — how the `--run` / `--batch` dispatch works. diff --git a/docs/project.json b/docs/project.json deleted file mode 100644 index ea29b6c11..000000000 --- a/docs/project.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "name": "nemotron", - "version": "nightly" -} diff --git a/docs/sdg/_snippets/input/greenteme.yaml b/docs/sdg/_snippets/input/greenteme.yaml deleted file mode 100644 index d4f88c796..000000000 --- a/docs/sdg/_snippets/input/greenteme.yaml +++ /dev/null @@ -1,75 +0,0 @@ -output_dir: ${oc.env:SDG_OUTPUT_DIR,${oc.env:NEMO_RUN_DIR,${oc.env:PWD}/output}/sdg} -output_path: ${output_dir}/greenteme_sft.jsonl -num_records: 100 - -seed_dataset: - path: ${oc.env:PWD}/src/nemotron/steps/sdg/data_designer/data/greenteme_inquiry_seeds.jsonl - strategy: shuffle - fields: [scenario] - -models: - - alias: nvidia-text - model: nvidia/nemotron-3-nano-30b-a3b - provider: nvidia - skip_health_check: true - inference_parameters: - temperature: 0.8 - top_p: 1.0 - max_tokens: 1200 - -columns: - - name: traveler_segment - type: category - values: - - frequent_flyer - - business_traveler - - family_with_children - - first_time_international - - elite_loyalty_member - - leisure_couple - - - name: inquiry_type - type: category - values: - - rebooking - - baggage_issue - - refund_request - - loyalty_status - - fare_rules - - flight_status - - - name: channel - type: category - values: [chat, phone, app] - - - name: user_query - type: llm_text - model_alias: nvidia-text - prompt: | - You are role-playing a {{ traveler_segment }} contacting Greenteme Airlines - via {{ channel }} about a {{ inquiry_type }}. The scenario is: - "{{ scenario }}" - - Write the customer's first message. Keep it natural, 1-3 sentences. - Do not reference any real airline name, real flight number, or real - loyalty program. - - - name: assistant_response - type: llm_text - model_alias: nvidia-text - prompt: | - You are a customer-service agent at Greenteme Airlines, a fictional airline. - Reply to this customer message: - - "{{ user_query }}" - - Provide a concise, professional, compliant response, 2-4 sentences. Stay - realistic and grounded in standard airline policy. Do not invent real - airline names, real flight numbers, real PNR codes, or real loyalty - program details. No markdown. - -output_projection: - type: openai_messages - user_field: user_query - assistant_field: assistant_response - metadata_fields: [traveler_segment, inquiry_type, channel, scenario] diff --git a/docs/sdg/_snippets/input/greenteme_inquiry_seeds.jsonl b/docs/sdg/_snippets/input/greenteme_inquiry_seeds.jsonl deleted file mode 100644 index a20321e1e..000000000 --- a/docs/sdg/_snippets/input/greenteme_inquiry_seeds.jsonl +++ /dev/null @@ -1,12 +0,0 @@ -{"scenario": "Connecting flight cancelled due to weather; customer needs to arrive at destination by tomorrow morning for a wedding."} -{"scenario": "Checked baggage missing on arrival; flight landed two hours ago and the bag did not appear at the carousel."} -{"scenario": "Customer wants a refund on a non-refundable ticket due to a documented medical emergency."} -{"scenario": "Customer is unsure why their loyalty status was downgraded this year and wants to understand the qualifying criteria."} -{"scenario": "Customer wants to change a fare class on an existing booking and needs to know the fare difference and any change fees."} -{"scenario": "Flight is showing a four-hour delay and the customer wants to know whether they will make their connection."} -{"scenario": "Customer was double-charged for a seat upgrade and wants the duplicate charge reversed."} -{"scenario": "Customer needs to add a service animal to an upcoming international flight and wants to know what documentation is required."} -{"scenario": "Bag damaged in transit; customer needs to file a claim and wants the timeline and required documentation."} -{"scenario": "Customer rebooked through self-service and is now seated apart from a travel companion; they want to be reseated together."} -{"scenario": "Customer wants to use a travel credit from a previous cancellation but cannot find the credit number in their account."} -{"scenario": "Customer's payment method was declined when trying to complete a booking and they want to know what to do."} diff --git a/docs/sdg/_snippets/input/step-with-person-datetime.py b/docs/sdg/_snippets/input/step-with-person-datetime.py deleted file mode 100644 index cde4f083b..000000000 --- a/docs/sdg/_snippets/input/step-with-person-datetime.py +++ /dev/null @@ -1,327 +0,0 @@ -#!/usr/bin/env python3 -# /// script -# [tool.runspec] -# schema = "1" -# name = "steps/sdg/data_designer" -# -# [tool.runspec.run] -# launch = "python" -# -# [tool.runspec.config] -# dir = "./config" -# default = "default" -# format = "omegaconf" -# -# [tool.runspec.resources] -# nodes = 1 -# gpus_per_node = 0 -# /// - -# Copyright (c) 2025, NVIDIA CORPORATION. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -"""Generate synthetic SFT or RL preference data with NeMo Data Designer. - -Mirrors the upstream NVIDIA-NeMo/DataDesigner Python SDK: build a -``DataDesignerConfigBuilder`` from a declarative YAML column spec, then call -``client.preview(builder)`` (fast iteration) or ``client.create(builder, …)`` -(full dataset). - -Two configs ship out of the box: - - ``default.yaml`` — SFT chat data (sampler ``persona`` × seed ``topic`` + - LLM-generated ``user_query`` / ``assistant_response``). - - ``rl_pref.yaml`` — DPO preference data (two LLM-generated responses + an - LLM judge to label chosen / rejected). - -Generation uses a remote inference endpoint, so this step needs no GPUs of its -own — only network access to the configured model service. Customisation lives -entirely in YAML. -""" - -from __future__ import annotations - -import json -from pathlib import Path -from typing import Any - -from omegaconf import OmegaConf - -from nemotron.kit.train_script import ( - apply_hydra_overrides, - load_omegaconf_yaml, - parse_config_and_overrides, -) - -DEFAULT_CONFIG = Path(__file__).parent / "config" / "default.yaml" - - -def build_columns(builder: Any, columns: list[dict[str, Any]], dd: Any) -> None: - """Translate declarative column specs into typed Data Designer column configs. - - Supported ``type``s: - - ``category`` — pick uniformly from a fixed list of values. - - ``person`` — Census-grounded persona profile via the person sampler. - - ``datetime`` — random datetime within a start/end range. - - ``seed`` — surface a column from the seed dataset by name. - - ``llm_text`` — generate free text via an LLM. - - ``llm_structured`` — generate structured JSON via an LLM (provide ``output_format``). - - ``llm_judge`` — alias for ``llm_structured``. - """ - for spec in columns: - kind = spec["type"] - name = spec["name"] - - if kind == "category": - builder.add_column( - dd.SamplerColumnConfig( - name=name, - sampler_type=dd.SamplerType.CATEGORY, - params=dd.CategorySamplerParams(values=spec["values"]), - ) - ) - - elif kind == "person": - builder.add_column( - dd.SamplerColumnConfig( - name=name, - sampler_type=dd.SamplerType.PERSON, - params=dd.PersonSamplerParams( - locale=spec.get("locale", "en_US"), - age_range=spec.get("age_range"), - with_synthetic_personas=spec.get("with_synthetic_personas", True), - ), - ) - ) - - elif kind == "datetime": - builder.add_column( - dd.SamplerColumnConfig( - name=name, - sampler_type=dd.SamplerType.DATETIME, - params=dd.DatetimeSamplerParams( - start=spec["start"], - end=spec["end"], - ), - ) - ) - - elif kind == "seed": - # The column name must match the field in the seed dataset. - builder.add_column(dd.SeedDatasetColumnConfig(name=name)) - - elif kind == "llm_text": - builder.add_column( - dd.LLMTextColumnConfig( - name=name, - model_alias=spec.get("model_alias", "nvidia-text"), - prompt=spec["prompt"], - ) - ) - - elif kind in ("llm_structured", "llm_judge"): - builder.add_column( - dd.LLMStructuredColumnConfig( - name=name, - model_alias=spec.get("model_alias", "nvidia-text"), - prompt=spec["prompt"], - output_format=spec["output_format"], - ) - ) - - else: - raise ValueError(f"Unknown column type: {kind!r}") - - -def project_records(records: list[dict[str, Any]], projection: dict[str, Any] | None) -> list[dict[str, Any]]: - """Project Data Designer records into training-ready JSONL schemas.""" - if not projection: - return records - - kind = projection.get("type") - if kind == "structured_messages": - source_field = projection.get("source_field", "conversation") - messages_field = projection.get("messages_field", "messages") - tools_field = projection.get("tools_field", "tools") - metadata_fields = projection.get("metadata_fields") or [] - projected = [] - for record in records: - source = record[source_field] - if isinstance(source, str): - source = json.loads(source) - if not isinstance(source, dict): - raise ValueError(f"{source_field!r} must be a mapping or JSON object string") - - item = {"messages": source[messages_field]} - if tools_field in source: - item["tools"] = source[tools_field] - for field in metadata_fields: - if field in record: - item[field] = record[field] - projected.append(item) - return projected - - if kind == "openai_messages": - user_field = projection.get("user_field", "user_query") - assistant_field = projection.get("assistant_field", "assistant_response") - metadata_fields = projection.get("metadata_fields") or [] - projected = [] - for record in records: - item = { - "messages": [ - {"role": "user", "content": record[user_field]}, - {"role": "assistant", "content": record[assistant_field]}, - ] - } - for field in metadata_fields: - if field in record: - item[field] = record[field] - projected.append(item) - return projected - - if kind == "dpo_preference": - prompt_field = projection.get("prompt_field", "prompt") - response_a_field = projection.get("response_a_field", "response_a") - response_b_field = projection.get("response_b_field", "response_b") - judge_field = projection.get("judge_field", "judge") - winner_field = projection.get("winner_field", "winner") - projected = [] - for record in records: - judge = record.get(judge_field) - if isinstance(judge, str): - judge = json.loads(judge) - if not isinstance(judge, dict): - raise ValueError(f"{judge_field!r} must be a mapping or JSON object string") - - winner = str(judge.get(winner_field, "")).upper() - if winner == "A": - chosen = record[response_a_field] - rejected = record[response_b_field] - elif winner == "B": - chosen = record[response_b_field] - rejected = record[response_a_field] - else: - raise ValueError(f"Unsupported preference winner {winner!r}; expected 'A' or 'B'") - - projected.append( - { - "prompt": record[prompt_field], - "chosen": chosen, - "rejected": rejected, - } - ) - return projected - - raise ValueError(f"Unknown output_projection type: {kind!r}") - - -def records_from_designer_result(result: Any) -> list[dict[str, Any]]: - """Extract records from either preview or dataset-creation results.""" - if hasattr(result, "load_dataset"): - dataset = result.load_dataset() - elif hasattr(result, "dataset"): - dataset = result.dataset - else: - raise TypeError( - "Data Designer result must expose either `load_dataset()` " - "or an in-memory `dataset` attribute" - ) - - if dataset is None: - raise ValueError("Data Designer returned an empty dataset result") - - if isinstance(dataset, list): - return dataset - - if hasattr(dataset, "to_pandas"): - dataset = dataset.to_pandas() - - if hasattr(dataset, "to_dict"): - return dataset.to_dict(orient="records") - - raise TypeError(f"Unsupported Data Designer dataset type: {type(dataset).__name__}") - - -def main() -> None: - config_path, cli_overrides = parse_config_and_overrides(default_config=DEFAULT_CONFIG) - raw = apply_hydra_overrides(load_omegaconf_yaml(config_path), cli_overrides) - cfg = OmegaConf.to_container(raw, resolve=True) - - columns = cfg.get("columns") - if not columns: - raise ValueError(f"{config_path}: config must declare a non-empty `columns:` list") - - output_path = Path(cfg["output_path"]) - output_path.parent.mkdir(parents=True, exist_ok=True) - - # Deferred imports keep the module importable on dev hosts without - # data_designer installed. - import data_designer.config as dd - from data_designer.interface import DataDesigner - - builder = dd.DataDesignerConfigBuilder() - - # Models — translate the YAML `models:` list into typed ModelConfig objects. - # The builder ships with default model aliases; replace them when the YAML - # declares the same alias so our endpoint / parameters win. - for spec in cfg.get("models") or []: - alias = spec["alias"] - try: - builder.delete_model_config(alias) - except Exception: - pass # alias not yet registered — fine, just add it. - - params = spec.get("inference_parameters") or {} - builder.add_model_config( - dd.ModelConfig( - alias=alias, - model=spec["model"], - provider=spec.get("provider"), - skip_health_check=spec.get("skip_health_check", False), - inference_parameters=dd.ChatCompletionInferenceParams(**params), - ) - ) - - seed = cfg.get("seed_dataset") - if seed: - strategy_name = seed.get("strategy", "shuffle").upper() - builder.with_seed_dataset( - dd.LocalFileSeedSource(path=seed["path"]), - sampling_strategy=dd.SamplingStrategy[strategy_name], - ) - - build_columns(builder, columns, dd) - - client = DataDesigner() - - if cfg.get("preview", False): - result = client.preview(builder, num_records=cfg["num_records"]) - verb = "Preview" - else: - result = client.create( - builder, - num_records=cfg["num_records"], - ) - verb = "Generated" - - records = records_from_designer_result(result) - records = project_records(records, cfg.get("output_projection")) - - with output_path.open("w") as f: - for record in records: - f.write(json.dumps(record) + "\n") - print(f"{verb} {len(records)} records → {output_path}") - - -if __name__ == "__main__": - main() diff --git a/docs/sdg/_snippets/output/greenteme_preview.jsonl b/docs/sdg/_snippets/output/greenteme_preview.jsonl deleted file mode 100644 index 72ae5482e..000000000 --- a/docs/sdg/_snippets/output/greenteme_preview.jsonl +++ /dev/null @@ -1,32 +0,0 @@ -{ - "messages": [ - { - "role": "user", - "content": "Hi! I'm traveling internationally for the first time soon and need to add a service animal to my booking. Could you let me know what documentation I need to provide?" - }, - { - "role": "assistant", - "content": "Thank you for contacting Greenteme Airlines. Please provide a valid government-issued health certificate and a signed service animal relief form for your destination country. You can upload these documents through the Manage Booking section of our website at least 48 hours before departure." - } - ], - "traveler_segment": "first_time_international", - "inquiry_type": "rebooking", - "channel": "app", - "scenario": "Customer needs to add a service animal to an upcoming international flight and wants to know what documentation is required." -} -{ - "messages": [ - { - "role": "user", - "content": "\"Hi, I just rebooked my flight online and realized my companion and I are now seated in different rows. Is there any way you can help us get seats together?\"" - }, - { - "role": "assistant", - "content": "Hello, thank you for reaching out to Greenteme Airlines. Please provide your booking reference, and we will check for available adjacent seats to move you and your companion together. Note that depending on your fare class, a seat selection fee may apply." - } - ], - "traveler_segment": "first_time_international", - "inquiry_type": "refund_request", - "channel": "phone", - "scenario": "Customer rebooked through self-service and is now seated apart from a travel companion; they want to be reseated together." -} diff --git a/docs/sdg/_snippets/output/preview.txt b/docs/sdg/_snippets/output/preview.txt deleted file mode 100644 index be6c61d98..000000000 --- a/docs/sdg/_snippets/output/preview.txt +++ /dev/null @@ -1,87 +0,0 @@ - -Compiled Configuration - -╭──────────────────────────────────────── run ────────────────────────────────────────╮ -│ mode: local │ -│ profile: null │ -│ env: {} │ -│ cli: │ -│ argv: │ -│ - preview=true │ -│ - num_records=2 │ -│ dotlist: │ -│ - preview=true │ -│ - num_records=2 │ -│ passthrough: [] │ -│ config: default │ -│ recipe: │ -│ name: steps/sdg/data_designer │ -│ script: /local/var/tmp/nvidia/nemotron/src/nemotron/steps/sdg/data_designer/step.py │ -╰─────────────────────────────────────────────────────────────────────────────────────╯ - -╭─────────────────────────────────────── config ────────────────────────────────────────╮ -│ output_dir: ${oc.env:SDG_OUTPUT_DIR,${oc.env:NEMO_RUN_DIR,${oc.env:PWD}/output}/sdg} │ -│ output_path: ${output_dir}/sft.jsonl │ -│ num_records: 2 │ -│ seed_dataset: │ -│ path: ${oc.env:PWD}/src/nemotron/steps/sdg/data_designer/data/sft_topic_seeds.jsonl │ -│ strategy: shuffle │ -│ fields: │ -│ - topic │ -│ models: │ -│ - alias: nvidia-text │ -│ model: nvidia/nemotron-3-nano-30b-a3b │ -│ provider: nvidia │ -│ skip_health_check: true │ -│ inference_parameters: │ -│ temperature: 0.8 │ -│ top_p: 1.0 │ -│ max_tokens: '******' │ -│ columns: │ -│ - name: persona │ -│ type: category │ -│ values: │ -│ - teacher │ -│ - engineer │ -│ - student │ -│ - researcher │ -│ - support_agent │ -│ - name: user_query │ -│ type: llm_text │ -│ model_alias: nvidia-text │ -│ prompt: 'Write a single user message for a {{ persona }} asking about: {{ topic │ -│ }}. │ -│ │ -│ Keep it natural, 1-3 sentences. │ -│ │ -│ ' │ -│ - name: assistant_response │ -│ type: llm_text │ -│ model_alias: nvidia-text │ -│ prompt: 'Helpful assistant reply to: "{{ user_query }}". │ -│ │ -│ Style: concise, factual, no markdown. │ -│ │ -│ ' │ -│ output_projection: │ -│ type: openai_messages │ -│ user_field: user_query │ -│ assistant_field: assistant_response │ -│ metadata_fields: │ -│ - persona │ -│ - topic │ -│ preview: true │ -╰───────────────────────────────────────────────────────────────────────────────────────╯ - - - -╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ -│ Job Submission │ -│ ├── configs │ -│ │ ├── job: /local/var/tmp/nvidia/nemotron/.nemotron/jobs/20260509-133530-steps-sdg-data_designer/job.yaml │ -│ │ └── train: /local/var/tmp/nvidia/nemotron/.nemotron/jobs/20260509-133530-steps-sdg-data_designer/train.yaml │ -│ └── mode: local │ -╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ - -Executing: /local/var/tmp/nvidia/nemotron/.venv/bin/python3 /local/var/tmp/nvidia/nemotron/src/nemotron/steps/sdg/data_designer/step.py --config /local/var/tmp/nvidia/nemotron/.nemotron/jobs/20260509-133530-steps-sdg-data_designer/train.yaml -Preview 2 records → /local/var/tmp/nvidia/nemotron/output/sdg/sft.jsonl diff --git a/docs/sdg/_snippets/output/sft_first_record.jsonl b/docs/sdg/_snippets/output/sft_first_record.jsonl deleted file mode 100644 index 1344d109f..000000000 --- a/docs/sdg/_snippets/output/sft_first_record.jsonl +++ /dev/null @@ -1,14 +0,0 @@ -{ - "messages": [ - { - "role": "user", - "content": "Could you explain how reducing latency affects the quality of the model’s responses? I’m trying to understand the trade‑offs involved." - }, - { - "role": "assistant", - "content": "Reducing latency shortens the time the model takes to generate a response, which often means it has less computational budget or fewer inference steps. With fewer steps or a tighter budget, the model may:\n\n- Produce shorter, less nuanced outputs \n- Miss subtle contextual cues or deeper reasoning \n- Rely more on surface‑level patterns rather than elaborate context \n- Be more prone to errors or hallucinations that would be filtered out with additional processing \n\nThe trade‑off is speed versus depth: faster responses can be less thorough, less coherent, or lower in quality, especially for tasks that benefit from extended reasoning or detailed elaboration. Balancing the two involves choosing an acceptable latency target while preserving enough inference capacity to maintain the desired response quality." - } - ], - "persona": "teacher", - "topic": "tradeoffs between model latency and response quality" -} diff --git a/docs/sdg/getting-started.md b/docs/sdg/getting-started.md deleted file mode 100644 index c2be733d6..000000000 --- a/docs/sdg/getting-started.md +++ /dev/null @@ -1,146 +0,0 @@ - - -(sdg-getting-started)= -# Generate Your First Synthetic Dataset - -::::{grid} 2 - -:::{grid-item-card} -:columns: 8 - -**What You'll Build**: a small supervised fine-tuning (SFT) chat dataset in OpenAI message format. -The dataset contains five records grounded in the `sft_topic_seeds.jsonl` seed file in the repository. -Data Designer generates the records against an NVIDIA-hosted large language model (LLM) endpoint. - -^^^ - -**In this tutorial, you will**: - -1. Set up prerequisites: the repository and an NVIDIA API key. -1. Read the default pipeline configuration. -1. Run a preview to verify the pipeline and model. -1. Generate a small dataset of five records. -1. Locate and inspect the output JSON Lines (JSONL) file. - -{octicon}`clock;1.5em;sd-mr-1` This tutorial requires between 5 and 10 minutes to complete. -::: - -:::{grid-item-card} {octicon}`flame;1.5em;sd-mr-1` **Sample Prompt** -:columns: 4 - -Run a 2-record preview of the default synthetic data generation (SDG) pipeline, then generate 5 records and show me the first output record. - -::: -:::: - -## Prerequisites - -- Run all commands from the repository root. -- An `NVIDIA_API_KEY` for the default model, `nvidia/nemotron-3-nano-30b-a3b`. - Data generation runs against an NVIDIA-hosted endpoint, so you can complete this tutorial on any machine with network access. - -## How the Default Pipeline Works - -The default pipeline at `src/nemotron/steps/sdg/data_designer/config/default.yaml` combines two sources of variation for each record. -A *seed topic* is sampled from `sft_topic_seeds.jsonl`, for example a topic on safe deployment of AI assistants in enterprise support workflows. -A *persona category*, such as teacher or engineer, is sampled from a fixed category set. -Together they anchor a user prompt. -The pipeline generates a matching assistant response and projects the result into OpenAI chat-format messages. - -```{literalinclude} ../../src/nemotron/steps/sdg/data_designer/config/default.yaml -:language: yaml -:lines: 15- -:class: scrollable -``` - -## Procedure - -1. Clone the repository, if you have not already done so: - - ```console - $ git clone https://github.com/NVIDIA-NeMo/Nemotron && cd Nemotron - ``` - -1. Install the dependencies for synthetic data generation: - - ```console - $ uv sync --extra data-sdg - ``` - -1. Set your NVIDIA API key: - - ```console - $ export NVIDIA_API_KEY="" - ``` - -1. Run a 2-record preview to verify the model alias, prompts, and column mappings before generating at scale. - - ```console - $ uv run nemotron steps run sdg/data_designer -c default preview=true num_records=2 - ``` - - The pipeline registers the model alias, generates two rows, and prints a summary: - - ````{dropdown} Example Output - :icon: code-square - - ```{literalinclude} _snippets/output/preview.txt - :language: text - ``` - ```` - -1. Generate the five-record dataset: - - ```console - $ uv run nemotron steps run sdg/data_designer -c default num_records=5 - ``` - - The default output path is `./output/sdg/sft.jsonl`. - To change the path, set the `SDG_OUTPUT_DIR` environment variable or pass `output_path=...` on the command line. - -1. Inspect the output. - Each line of `sft.jsonl` is one chat record. - The `openai_messages` projection emits a `messages` array along with the seed `topic` and sampled `persona` as metadata for traceability. - The following sample shows one record from the `sft.jsonl` file. - - ```{literalinclude} _snippets/output/sft_first_record.jsonl - :language: json - ``` - -## Summary - -In this tutorial, you completed the following tasks: - -- Ran a 2-record preview to verify the pipeline and model. -- Generated a 5-record SFT chat dataset with `default.yaml`. -- Located the OpenAI-format JSONL output. - -As you scale this workflow up, keep two principles in mind: - -- Run a preview first. - The `preview=true num_records=N` form runs the same pipeline against a small record count, so you can iterate on column specifications and prompts before scaling `num_records` up. -- The output format matches the trainer. - The `openai_messages` projection emits records ready for `data_prep/sft_packing` or AutoModel SFT. - -## Next Steps - -- Adapt the pipeline to a specific domain: {doc}`how-to/create-domain-dataset`. -- Preview, generate, and customize output: {doc}`how-to/run`. -- Generate preference pairs for direct preference optimization (DPO): {doc}`how-to/preference-data`. -- Dispatch to a cluster: {doc}`how-to/dispatch-to-cluster` describes env.toml profiles and container images. -- Look up flags and config fields: {doc}`reference/cli-reference`, {doc}`reference/config-schema`. diff --git a/docs/sdg/how-to/create-domain-dataset.md b/docs/sdg/how-to/create-domain-dataset.md deleted file mode 100644 index 332ecfdc3..000000000 --- a/docs/sdg/how-to/create-domain-dataset.md +++ /dev/null @@ -1,130 +0,0 @@ - - -(sdg-create-greenteme-airlines-dataset)= -# Create a Domain Dataset for Airlines Customer Service - -::::{grid} 2 - -:::{grid-item-card} -:columns: 8 - -**What You'll Build**: A domain-adapted SFT chat dataset modeled on fictional airlines customer-service conversations. - -^^^ - -**In this how-to guide, you will**: - -1. Create an airline-domain pipeline config. -2. Create a seed file of airline inquiry scenarios. -3. Swap the category columns for three airline-relevant dimensions. -4. Rewrite the LLM prompts for the airline domain. -5. Update the output projection and output path. -6. Run a preview to verify, then generate 100 records. - -{octicon}`clock;1.5em;sd-mr-1` This guide requires between 20 and 30 minutes to complete. -::: - -:::{grid-item-card} -:columns: 4 - -{octicon}`flame;1.5em;sd-mr-1` **Sample Prompt** - -^^^ - -Adapt the default SDG pipeline for Greenteme Airlines customer service with three category dimensions, run a 2-record preview, then generate 100 records and show me one output record. - -::: -:::: - -## Prerequisites - -- ✅ Completed {doc}`../getting-started` — at least one successful preview and full run of `default.yaml` so you know the pipeline works end-to-end. -- ✅ `NVIDIA_API_KEY` set in your environment. - -## How This Differs From the Default Pipeline - -The default pipeline mixes a single category dimension, `persona`, with seed topics. -This example adds category dimensions, `traveler_segment`, `inquiry_type`, and `channel`, on top of seed scenarios so that diversity comes from explicit, controllable values. - -## Procedure - -1. Create a `src/nemotron/steps/sdg/data_designer/config/greenteme.yaml` ([download](../_snippets/input/greenteme.yaml)) file like the following example: - - ```{literalinclude} ../_snippets/input/greenteme.yaml - :language: yaml - :class: scrollable - ``` - - The key differences from the default pipeline: - - The variation for traveler segment, inquiry type, and channel are all provided by category-type columns. - - The variation for the scenarios is provided by the seed JSONL file from the next step. - - The system-style instruction lives at the top of each prompt rather than as a separate field. The LLM text columns take a single prompt that includes the role for the LLM to assume. - - The `output_projection` field includes the new metadata fields. - -2. Create a seed file, `src/nemotron/steps/sdg/data_designer/data/greenteme_inquiry_seeds.jsonl`, ([download](../_snippets/input/greenteme_inquiry_seeds.jsonl)) like the following example: - - ```{literalinclude} ../_snippets/input/greenteme_inquiry_seeds.jsonl - :language: json - :class: scrollable - ``` - -1. Run a preview by specifying `preview=true num_records=2` to verify the pipeline before scaling: - - ```console - $ nemotron steps run sdg/data_designer -c greenteme preview=true num_records=2 - ``` - - ````{dropdown} Example Output - :icon: code-square - - ```{literalinclude} ../_snippets/output/greenteme_preview.jsonl - :language: json - ``` - ```` - -1. Generate the dataset by raising `num_records` after the preview output looks correct: - - ```console - $ nemotron steps run sdg/data_designer -c greenteme num_records=100 - ``` - -## Going Further - -**Locale-aware persona profiles.** The current YAML schema supports category, seed, and LLM column types. To replace the static `traveler_segment` category with Census-grounded persona profiles using Data Designer's [person sampler](https://nvidia-nemo.github.io/DataDesigner/latest/concepts/person_sampling/), you can include locale, age range, and synthetic-personas integration. - -**Multi-turn conversations.** The example shows a single user and assistant exchange. -For multi-turn dialogue, follow the `customer_support_tools.yaml` pattern: ask one `llm_text` column to return a JSON object with `messages` and optional `tools`, then use the `structured_messages` output projection to write training-ready JSONL. - -**Dispatch to a cluster.** Generation runs locally against the NVIDIA-hosted endpoint by default. To run on Lepton or Slurm, see {doc}`dispatch-to-cluster` — env.toml profiles, container images, and the gotchas that bite first-time cluster runs. - -## Schema and Downstream Use - -The `openai_messages` projection emits records with a `messages` array plus the metadata fields you list. These flow directly into: - -- `data_prep/sft_packing` for Megatron-Bridge-style training, or -- AutoModel SFT, which consumes the chat format directly. - -For a full reference of available projection shapes, see {doc}`../reference/output-projections`. - -## Next Steps - -- **Generate preference pairs for DPO**: {doc}`preference-data` — the `rl_pref.yaml` pattern. -- **Generate tool-calling SFT data**: {doc}`tool-call-data` — multi-turn `messages` and `tools` with `structured_messages`. -- **CLI flags and overrides**: {doc}`../reference/cli-reference`. -- **Config schema**: {doc}`../reference/config-schema` — full reference for column types, samplers, and projections. -- **Pipeline overview**: {doc}`../index`. diff --git a/docs/sdg/how-to/index.md b/docs/sdg/how-to/index.md deleted file mode 100644 index 9b459de6f..000000000 --- a/docs/sdg/how-to/index.md +++ /dev/null @@ -1,80 +0,0 @@ - - -(sdg-how-to-index)= -# Synthetic Data How-To Guides - -This section provides task-focused guides for common SDG workflows. -For your first run, start with {doc}`../getting-started`. - -If you are new to model training or want a calmer on-ramp before tasks, read {doc}`../using-skills` for how to run a productive session with a coding agent. - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`play;1.5em;sd-mr-1` Run the Pipeline -:link: run -:link-type: doc -Preview, generate, and customize output path and projection. -+++ -{bdg-success}`10 min` {bdg-secondary}`intermediate` -::: - -:::{grid-item-card} {octicon}`briefcase;1.5em;sd-mr-1` Create a Domain Dataset -:link: create-domain-dataset -:link-type: doc -Adapt the pipeline to a custom domain with a seed file and multiple category dimensions. -+++ -{bdg-success}`20 min` {bdg-secondary}`intermediate` -::: - -:::{grid-item-card} {octicon}`tools;1.5em;sd-mr-1` Generate Tool-Call Data -:link: tool-call-data -:link-type: doc -Generate multi-turn conversations with OpenAI-style tool calls for tool-use SFT. -+++ -{bdg-success}`15 min` {bdg-secondary}`intermediate` -::: - -:::{grid-item-card} {octicon}`git-compare;1.5em;sd-mr-1` Generate Preference Data -:link: preference-data -:link-type: doc -Generate DPO preference pairs (prompt / chosen / rejected) from `rl_pref.yaml`. -+++ -{bdg-success}`15 min` {bdg-secondary}`intermediate` -::: - -:::{grid-item-card} {octicon}`server;1.5em;sd-mr-1` Dispatch to a Cluster -:link: dispatch-to-cluster -:link-type: doc -Configure an env.toml profile and run SDG on Lepton or Slurm. -+++ -{bdg-success}`30 min` {bdg-secondary}`intermediate` -::: - -:::: - -```{toctree} -:hidden: -:maxdepth: 1 - -Create a Domain Dataset -Create Tool-Calling Dataset -preference-data -dispatch-to-cluster -run -``` diff --git a/docs/sdg/how-to/preference-data.md b/docs/sdg/how-to/preference-data.md deleted file mode 100644 index db5df7b64..000000000 --- a/docs/sdg/how-to/preference-data.md +++ /dev/null @@ -1,93 +0,0 @@ - - -(sdg-preference-data)= -# Generate Preference Data for DPO - -This example shows how to use the `rl_pref.yaml` configuration file. -The example generates _prompt_, _chosen_, and _rejected_ triples for direct preference optimization (DPO) training. -Output flows directly into `data_prep/rl_prep` and then `rl/nemo_rl/dpo`. - -## How It Works - -The `rl_pref.yaml` file registers two model aliases at different temperatures: -a high-temperature creative model and a low-temperature precise model. -The goal is to produce two responses per prompt that are distinct: - -```{literalinclude} ../../../src/nemotron/steps/sdg/data_designer/config/rl_pref.yaml -:language: yaml -:lines: 15- -:class: scrollable -``` - -For each seed prompt the pipeline: - -1. Generates `response_a` (high temperature) and `response_b` (low temperature) independently. -2. Asks a third LLM call (`judge` column, `llm_judge` type) to compare them and return `{"winner": "A"}` or `{"winner": "B"}`. -3. The `dpo_preference` projection maps winner → chosen / rejected and writes `{"prompt": "...", "chosen": "...", "rejected": "..."}`. - -## Prerequisites - -- `NVIDIA_API_KEY` set in your environment. -- A seed file with one `prompt` field per line. The bundled `rl_pref_prompt_seeds.jsonl` contains general reasoning prompts. Replace it with domain-specific prompts for targeted preference data. - -## Procedure - -1. Preview two records to verify the judge returns valid `winner` values: - - ```console - $ nemotron steps run sdg/data_designer -c rl_pref preview=true num_records=2 - ``` - -2. Generate the dataset. The checked-in `rl_pref.yaml` default is 100 records: - - ```console - $ nemotron steps run sdg/data_designer -c rl_pref num_records=500 - ``` - - Output is written to `./output/sdg/rl_pref.jsonl`. - - Inspect the output. Each line is a preference triple: - - ```json - {"prompt": "Explain why retrieval-augmented generation can reduce hallucinations.", "chosen": "RAG grounds the model in retrieved documents, so claims are tied to specific passages rather than purely to weights.", "rejected": "RAG is better because it uses more data and is generally smarter than standard models."} - ``` - -## Adapt the Seed File - -Swap `seed_dataset.path` to point at your own prompt seed file. Each line must be valid JSON with a `prompt` field: - -```json -{"prompt": "Describe the tradeoffs between batch and streaming inference for real-time applications."} -``` - -Keep seed prompts representative of the target capability and diverse across difficulty levels. -The judge performs better when the two responses have a clear quality difference--consider widening the temperature gap between the two model aliases if the judge returns many ties or unexpected results. - -## Downstream Pipeline - -```text -rl_pref.jsonl → data_prep/rl_prep → rl/nemo_rl/dpo -``` - -`data_prep/rl_prep` tokenizes and prepares preference pairs. `rl/nemo_rl/dpo` consumes the prepared dataset. Verify the `prompt`, `chosen`, and `rejected` fields are present in every record before handing off. - -## Next Steps - -- **Output projection reference**: {doc}`../reference/output-projections` — `dpo_preference` schema. -- **Config schema**: {doc}`../reference/config-schema` — `llm_judge` column type and `dpo_preference` projection fields. -- **Dispatch to a cluster**: {doc}`dispatch-to-cluster`. diff --git a/docs/sdg/how-to/tool-call-data.md b/docs/sdg/how-to/tool-call-data.md deleted file mode 100644 index b6fd3f17d..000000000 --- a/docs/sdg/how-to/tool-call-data.md +++ /dev/null @@ -1,122 +0,0 @@ - - -(sdg-tool-call-data)= -# Generate Tool-Calling Data for SFT - -Use this guide when you need multi-turn chat JSONL where the assistant issues OpenAI-style `tool_calls` and a `tool` role returns structured results, suitable for supervised fine-tuning (SFT) with a `tools` definition array. - -You will use the sample config `customer_support_tools.yaml`, which produces ecommerce-style support threads. Each output row includes a `messages` array (with tool turns) and a `tools` array, ready for packing and training. - -## Outcomes - -- Understand how the shipped config asks one `llm_text` column to emit a full JSON multi-turn trace in a single model call. -- Preview, generate, and validate records before training. -- Know how to retarget seeds, prompts, and schema for your own domain. - -## How It Works - -Compared with single-turn configs such as `default.yaml`, this setup drives the whole conversation from one `llm_text` column. -The prompt tells the model to return a JSON object with `tools` and `messages` keys. -The `structured_messages` output projection parses that JSON object, extracts `messages` and `tools`, adds metadata, and serializes nested tool payload objects into OpenAI-compatible string fields. - -```{literalinclude} ../../../src/nemotron/steps/sdg/data_designer/config/customer_support_tools.yaml -:language: yaml -:lines: 15- -:class: scrollable -``` - -Each seed row supplies five anchor fields the prompt interpolates: `customer_name`, `issue`, `order_id`, `product`, and `policy_hint`. Two extra category columns (`urgency`, `channel`) add variety without multiplying seed rows for every combination. - -## Prerequisites - -- Nemotron CLI available and working; if this is your first SDG run, complete {doc}`../getting-started`. -- `NVIDIA_API_KEY` set in the environment. -- The bundled seed file `data/customer_support_tool_seeds.jsonl` (shipped with the step). Add rows, or point the config at your own JSONL. - -## Procedure - -1. Preview two records so structured output matches the schema: - - ```console - $ nemotron steps run sdg/data_designer -c customer_support_tools preview=true num_records=2 - ``` - - In the preview, confirm: - - - Exactly one assistant message with `tool_calls`. - - Exactly one `tool` message whose `tool_call_id` matches the call. - - `function.arguments` and tool-message `content` are JSON strings after projection. - - The assistant’s closing turn references the tool result (not a generic reply). - - No markdown in message `content` if your trainer expects plain text. - -2. Generate the dataset: - - ```console - $ nemotron steps run sdg/data_designer -c customer_support_tools num_records=200 - ``` - - Output path: `./output/sdg/customer_support_tool_sft.jsonl`. - Spot-check a few lines. Each record exposes top-level `messages` and `tools` plus metadata, like the following example: - - ```text - { - "messages": [ - {"role": "system", "content": "You are a helpful ecommerce support agent..."}, - {"role": "user", "content": "Hi, I haven't received my headphones yet..."}, - {"role": "assistant", "content": "I'd be happy to help. Could you share your order number?"}, - {"role": "user", "content": "It's ORD-10492."}, - {"role": "assistant", "content": "", "tool_calls": [{"id": "call_001", "type": "function", "function": {"name": "lookup_order", "arguments": "{\"order_id\":\"ORD-10492\"}"}}]}, - {"role": "tool", "tool_call_id": "call_001", "name": "lookup_order", "content": "{\"status\":\"delayed\",\"eta\":\"tomorrow\"}"}, - {"role": "assistant", "content": "Your order is delayed and should arrive tomorrow. Per our policy, I can arrange an expedited replacement if you prefer."} - ], - "tools": [{"type": "function", "function": {"name": "lookup_order", "description": "...", "parameters": {...}}}], - "customer_name": "Priya", "issue": "late delivery", "urgency": "frustrated", "channel": "web_chat" - } - ``` - -## Adapt to Your Domain - -1. Replace or extend the seed file so rows cover your entities. You may rename the five anchor fields as long as the prompt and YAML refer to the same names. -2. Update `seed_dataset.fields` in the YAML to match those names. -3. Rewrite the `prompt` for your scenario and tool surface. -4. Adjust the JSON schema described in the prompt if the message layout changes, for example multiple tool calls per conversation. - -Keep `output_projection` as `structured_messages` so the step extracts `messages` and `tools` from the structured column and merges category metadata onto each record. - -## Validation Checklist - -Before training, sample at least 50 records and verify: - -- [ ] Every `tool_calls` block has a matching `tool` message with the same `tool_call_id`. -- [ ] `function.arguments` and tool-message `content` values are JSON strings in the projected JSONL. -- [ ] The assistant’s final reply uses the tool result (not a canned answer that ignores it). -- [ ] No unexpected markdown in `content` if the trainer assumes plain text. -- [ ] `tools` is present and non-empty on every record. - -## Downstream Use - -```text -customer_support_tool_sft.jsonl → data_prep/sft_packing → SFT training -``` - -The `structured_messages` projection writes `messages` and `tools` at the top level, matching formats common to AutoModel-style SFT and Megatron-Bridge-style workflows. Run `data_prep/sft_packing` in dry-run mode before a large training job to confirm the packer accepts your file. - -## Next Steps - -- Output projection reference: {doc}`../reference/output-projections` to learn the `structured_messages` schema. -- Config schema: {doc}`../reference/config-schema` for column types and output projections. diff --git a/docs/sdg/reference/config-schema.md b/docs/sdg/reference/config-schema.md deleted file mode 100644 index 4ffa0924c..000000000 --- a/docs/sdg/reference/config-schema.md +++ /dev/null @@ -1,213 +0,0 @@ - - -(sdg-config-schema)= -# Config Schema - -This page provides the reference information for the YAML config file consumed by `sdg/data_designer`. - -## Simple Fields - -| Field | Type | Required | Description | -|---|---|---|---| -| `output_dir` | string | no | Base output directory. Supports OmegaConf env-var interpolation. Default resolves `$SDG_OUTPUT_DIR`, then `$NEMO_RUN_DIR/sdg`, then `./output/sdg`. | -| `output_path` | string | yes | Full path for the output JSONL file. Typically `${output_dir}/my-dataset.jsonl`. | -| `num_records` | int | yes | Number of records to generate (`client.create`) or preview (`client.preview`). | -| `preview` | bool | no | When `true`, calls `client.preview()` instead of `client.create()`. Default: `false`. Prefer setting this as a CLI override (`preview=true`) rather than in the YAML. | - -## seed_dataset - -Optional top-level field. -When present, Data Designer samples one row per generated record from the seed file and makes the fields available to column prompts by using Jinja2. - -| Field | Type | Required | Description | -|---|---|---|---| -| `path` | string | yes | Path to a JSONL file. Each line is a JSON object. | -| `strategy` | string | no | `shuffle` (default) or `ordered`. | -| `fields` | list[string] | yes | Column names to expose. Must match keys in the seed JSONL objects. These become available as `{{ field_name }}` in prompts without being declared in `columns`. | - -## models - -A required top-level field. -The field specifies a list of model configurations. -Each entry defines one alias that column specs reference by name. - -| Field | Type | Required | Description | -|---|---|---|---| -| `alias` | string | yes | Short name referenced by `model_alias` in column specs. | -| `model` | string | yes | Model identifier such as `nvidia/nemotron-3-nano-30b-a3b` and `openai/gpt-oss-20b`. | -| `provider` | string | no | Provider name, such as `nvidia` or `anthropic`. | -| `skip_health_check` | bool | no | Skip the startup probe against the model provider. Useful for local or offline endpoints. Default: `false`. | -| `inference_parameters.temperature` | float | no | Sampling temperature. | -| `inference_parameters.top_p` | float | no | Top-p nucleus sampling. | -| `inference_parameters.max_tokens` | int | no | Maximum output tokens per call. | - -## columns - -A required top-level field. -This field is an ordered list of column specs. -Each column has a `name`, a `type`, and type-specific fields. -Columns can reference earlier columns and seed fields in prompts by using Jinja2 syntax like `{{ column_name }}`. - -### Categorical Columns - -Samples uniformly from a fixed list of string or numeric values like the following example. - -```yaml -- name: persona - type: category - values: [teacher, engineer, student, researcher] -``` - -| Field | Required | Description | -|---|---|---| -| `name` | yes | Column name. | -| `values` | yes | List of values to sample from. | - -### Seed Columns - -Provides a named field from the seed dataset as a column. -Use this column type when a seed field needs to appear in `metadata_fields` or must be referenced in a way that requires it to be an explicit column. - -```yaml -- name: topic - type: seed -``` - -| Field | Required | Description | -|---|---|---| -| `name` | yes | Must match a field name in `seed_dataset.fields`. | - -Seed fields declared in `seed_dataset.fields` are available directly in prompts without this column type. -Use `seed` only when you need the field as a named column in the output schema. - -### LLM Text Columns - -Generates free-form text using an LLM call. -These columns can references earlier specified columns and seed fields in `prompt` by using Jinja2 syntax. - -```yaml -- name: user_query - type: llm_text - model_alias: nvidia-text - prompt: | - Write a message from a {{ persona }} asking about: {{ topic }}. -``` - -| Field | Required | Description | -|---|---|---| -| `name` | yes | Column name. | -| `model_alias` | no | Alias from `models`. Default: `nvidia-text`. | -| `prompt` | yes | Jinja2 template. Reference any earlier column or seed field with `{{ name }}`. | - -### LLM Structured Columns - -This column type generates structured JSON by making an LLM call. -The column definition instructs the model to return JSON matching `output_format`. -Use this column type for multi-turn conversations, preference judges, and any output that must conform to a schema. - -```yaml -- name: conversation - type: llm_structured - model_alias: nvidia-text - prompt: | - Generate a support conversation for customer {{ customer_name }}... - output_format: - type: object - properties: - messages: - type: array - ... - required: [messages] -``` - -| Field | Required | Description | -|---|---|---| -| `name` | yes | Column name. | -| `model_alias` | no | Alias from `models`. Default: `nvidia-text`. | -| `prompt` | yes | Jinja2 template. | -| `output_format` | yes | JSON Schema dict describing the expected output structure. | - -### LLM Judge Columns - -This type is an alias for `llm_structured`. -This type is typically used for columns that compare or evaluate other columns. - -```yaml -- name: judge - type: llm_judge - model_alias: nvidia-text - prompt: | - Compare response A and B for: {{ prompt }} - A: {{ response_a }} - B: {{ response_b }} - output_format: - type: object - properties: - winner: - type: string - enum: [A, B] - required: [winner] -``` - -## output_projection - -This top-level field maps raw Data Designer records into the schema expected by downstream steps. -Refer to {doc}`output-projections` for full field tables and annotated JSONL examples for each type. - -| `type` | Use for | Downstream | -|---|---|---| -| `openai_messages` | Single-turn SFT chat | `data_prep/sft_packing`, AutoModel SFT | -| `dpo_preference` | Preference pairs | `data_prep/rl_prep`, `rl/nemo_rl/dpo` | -| `structured_messages` | Multi-turn with tool calls | `data_prep/sft_packing`, AutoModel SFT | - -## Extending the Schema: `person` and `datetime` Samplers - -The current `step.py` supports the column types above. To use Data Designer's locale-aware person sampler or datetime sampler, `step.py`'s `build_columns()` function must be extended with `person` and `datetime` branches. A reference implementation showing both additions is in: - -```{literalinclude} ../_snippets/input/step-with-person-datetime.py -:language: python -:start-at: " elif kind == \"person\":" -:end-before: " elif kind == \"seed\":" -``` - -Once merged, configs can declare: - -```yaml -- name: traveler - type: person - locale: en_US - age_range: [22, 75] - with_synthetic_personas: true - -- name: booking_date - type: datetime - start: "2024-01-01" - end: "2025-12-31" -``` - -Download personas for the locale before running: - -```console -$ data-designer download personas --locale en_US -``` - -## Related Information - -- {doc}`output-projections` — projection field reference and JSONL examples. -- {doc}`cli-reference` — flags and hydra override syntax. -- {doc}`../how-to/run` — preview and generate workflow. diff --git a/docs/sdg/reference/index.md b/docs/sdg/reference/index.md deleted file mode 100644 index 2e4becd39..000000000 --- a/docs/sdg/reference/index.md +++ /dev/null @@ -1,68 +0,0 @@ - - -(sdg-reference-index)= -# SDG Reference - -Complete specifications for the SDG pipeline. For pipeline overview and when to use it, refer to {doc}`../index`. - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`file-code;1.5em;sd-mr-1` Config Schema -:link: config-schema -:link-type: doc -All YAML fields: top-level settings, seed dataset, model aliases, column types, and output projections. -+++ -{bdg-secondary}`lookup` -::: - -:::{grid-item-card} {octicon}`terminal;1.5em;sd-mr-1` CLI Reference -:link: cli-reference -:link-type: doc -`nemotron steps run sdg/data_designer` flags and hydra override syntax. -+++ -{bdg-secondary}`lookup` -::: - -:::{grid-item-card} {octicon}`arrow-switch;1.5em;sd-mr-1` Output Projections -:link: output-projections -:link-type: doc -The three projection shapes with annotated JSONL examples. -+++ -{bdg-secondary}`lookup` -::: - -:::{grid-item-card} {octicon}`alert;1.5em;sd-mr-1` Troubleshooting -:link: troubleshooting -:link-type: doc -Failure modes for local runs and cluster dispatch. -+++ -{bdg-secondary}`lookup` -::: - -:::: - -```{toctree} -:hidden: -:maxdepth: 1 - -config-schema -cli-reference -output-projections -troubleshooting -``` diff --git a/docs/train-models/_snippets/input/env.tmpl b/docs/train-models/_snippets/input/env.tmpl deleted file mode 100644 index 0b0a10c53..000000000 --- a/docs/train-models/_snippets/input/env.tmpl +++ /dev/null @@ -1,29 +0,0 @@ -[lepton_base] -executor = "lepton" -container_image = "nvcr.io/nvidia/nemo:25.11.nemotron_3_nano" -node_group = "" -nemo_run_dir = "/mnt/lustre-shared//experiments" -remote_job_dir = "/mnt/lustre-shared//output/functional" -workspace = "/mnt/lustre-shared" -ray_version = "2.48.0" -shared_memory_size = 65536 -pip_extras = ["typer", "rich", "pydantic-settings"] -mounts = [ - { from = "node-nfs:", path = "", mount_path = "/mnt/lustre-shared" } -] -env_vars = { - HF_TOKEN = "${oc.env:HF_TOKEN,''}", - HF_HOME = "/mnt/lustre-shared/hf", - WANDB_API_KEY = "${oc.env:WANDB_API_KEY,''}", - WANDB_PROJECT = "", - NVIDIA_API_KEY = "${oc.env:NVIDIA_API_KEY,''}", - RAY_DEDUP_LOGS = "0", - RAY_GRAFANA_IFRAME_HOST = "" -} - -[lepton_sft_automodel] -extends = "lepton_base" -container_image = "nvcr.io/nvidia/nemo-automodel:26.04" -resource_shape = "gpu.8xa100-80gb" -nodes = 2 -pip_extras = ["typer", "rich", "pydantic-settings", "omegaconf"] diff --git a/docs/train-models/_snippets/input/sample-messages.jsonl b/docs/train-models/_snippets/input/sample-messages.jsonl deleted file mode 100644 index f9db43000..000000000 --- a/docs/train-models/_snippets/input/sample-messages.jsonl +++ /dev/null @@ -1,16 +0,0 @@ -{ - "messages": [ - { - "role": "system", - "content": "You answer arithmetic questions in one sentence." - }, - { - "role": "user", - "content": "What is twelve times seven?" - }, - { - "role": "assistant", - "content": "Twelve times seven is eighty-four." - } - ] -} diff --git a/docs/train-models/_snippets/output/gs-show.txt b/docs/train-models/_snippets/output/gs-show.txt deleted file mode 100644 index afa515dfb..000000000 --- a/docs/train-models/_snippets/output/gs-show.txt +++ /dev/null @@ -1,22 +0,0 @@ -──────────────────────────── sft/automodel — SFT Training (AutoModel) ──────────────────────────── -~/nemotron/src/nemotron/steps/sft/automodel - -Supervised fine-tuning with the AutoModel stack for HF-format models and JSONL -datasets that already use OpenAI chat-format messages. Supports full SFT and -LoRA-style adapter tuning from the same step. - -Consumes - • training_jsonl — Instruction data in JSONL with a messages field - -Produces - • checkpoint_hf — HuggingFace checkpoint directory (full model or adapter-style PEFT output) - -Parameters - • peft (default=null) — Use 'lora' for adapter tuning, or 'null' for full fine-tuning. - -Runspec - launcher: torchrun - image: - - resources: nodes=1 gpus_per_node=4 - config dir: ~/nemotron/src/nemotron/steps/sft/automodel/config - default config: default diff --git a/docs/train-models/explanation/index.md b/docs/train-models/explanation/index.md deleted file mode 100644 index cdcc11177..000000000 --- a/docs/train-models/explanation/index.md +++ /dev/null @@ -1,50 +0,0 @@ - - -(train-models-explanation-index)= -# Training Concepts - -This section provides conceptual material for training with Nemotron steps. -{doc}`basics` introduces fine-tuning approaches, tokenizers, the chat dataset format, and checkpoint layouts. -For the step, configuration, and environment profile model that every Nemotron command shares, see {doc}`../../steps/basics`. -The remaining pages explain how artifacts relate to one another and how the training libraries differ. - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`book;1.5em;sd-mr-1` Training Basics -:link: basics -:link-type: doc -Defines supervised fine-tuning, parameter-efficient fine-tuning, reinforcement learning alignment, quantization, tokenizers, the chat dataset format, and checkpoints. -+++ -{bdg-secondary}`concepts` -::: - -:::{grid-item-card} {octicon}`workflow;1.5em;sd-mr-1` Artifact Graph -:link: artifact-graph -:link-type: doc -Explains how steps declare typed inputs and outputs and what common training and alignment paths look like. -+++ -{bdg-secondary}`concepts` -::: - -:::{grid-item-card} {octicon}`package;1.5em;sd-mr-1` Training Libraries -:link: training-libraries -:link-type: doc -Explains which library backs each step and how that choice determines data format, checkpoint layout, and parallelism. -+++ -{bdg-secondary}`concepts` -::: - -:::: - -```{toctree} -:hidden: -:maxdepth: 1 - -basics -artifact-graph -training-libraries -``` diff --git a/docs/train-models/getting-started.md b/docs/train-models/getting-started.md deleted file mode 100644 index c7933d257..000000000 --- a/docs/train-models/getting-started.md +++ /dev/null @@ -1,120 +0,0 @@ -# Getting Started with Training Steps - -This page walks through one supervised fine tuning (SFT) run on DGX Cloud Lepton using the *tiny* configuration. -The tiny configuration lives in `src/nemotron/steps/sft/automodel/config/tiny.yaml` and is meant for short validation before you scale work. -The goal is to validate end-to-end execution, NeMo Run, and your environment profile on real multi-node hardware. - -## Prerequisites - -- You need access to DGX Cloud Lepton with GPU nodes. - This path assumes two nodes with eight A100 80 GB GPUs per node, matching the `run.env` block in `src/nemotron/steps/sft/automodel/config/tiny.yaml`. -- You set the following environment variables: - - `HF_TOKEN` - - `WANDB_API_KEY` - - `NVIDIA_API_KEY` -- You ran `lep login` after syncronizing dependencies and are logged into Lepton. - -The preceding list applies to the steps on this page. -Refer to [](./index.md#limitations-and-restrictions) for information about supported environments. - -## Procedure - -1. Clone the repository, if you haven't already: - - ```console - $ git clone https://github.com/NVIDIA-NeMo/Nemotron && cd Nemotron - ``` - -1. Set the dependencies: - - ```console - $ uv sync - ``` - -1. Create an `env.toml` at the root of the repository like the following example: - - ```{literalinclude} _snippets/input/env.tmpl - :language: text - ``` - - ```{dropdown} Summary of the Config File - - The `[lepton_base]` table defines cluster fundamentals that every profile inherits: the executor, the base container image, the node group, shared-storage paths, the Ray runtime version, the shared-memory size, the Python package extras the Nemotron CLI needs, the cluster mount, and an `env_vars` block whose `${oc.env:VAR,''}` entries pull credentials from your shell at submit time. - The `[lepton_sft_automodel]` table extends the base and adds the AutoModel container image, the resource shape needed for full-parameter SFT, the node count, and the additional Python package extras the AutoModel runtime expects. - - Contact your cluster administrator for the values that replace the placeholders. - - - ``: The Lepton node group identifier for the cluster you have access to. - - ``: A directory you own on the shared mount where NeMo Run records each experiment. - - ``: The alias of the Lepton storage fileset that each container mounts. - - ``: The host path the fileset exposes. - - ``: The Weights & Biases project name the run reports to. - ``` - - Export `HF_TOKEN`, `WANDB_API_KEY`, and `NVIDIA_API_KEY` in your shell before submitting; the env file pulls them in without writing the values to disk. - - If you would rather generate a complete env file with every Nemotron training profile pre-wired, run the bundled environment profile generator instead of writing the file by hand. - - ```console - $ uv run nemotron steps run env/env_toml -c lepton output_path=env.toml force=true - ``` - - The generator emits every canonical profile the training steps expect, including data-prep, SFT, PEFT, RL, and pretrain variants. - -1. View the step manifest and run specification: - - ```console - $ uv run nemotron steps show sft/automodel - ``` - - ````{dropdown} Example Output - :icon: code-square - - ```{literalinclude} _snippets/output/gs-show.txt - ``` - ```` - -1. Compile the job against your Lepton profile without submitting it. - The profile name `lepton_sft_automodel` must match a table in your root `env.toml`. - - ```console - $ uv run nemotron steps run sft/automodel --config tiny --run lepton_sft_automodel --dry-run - ``` - - ````{dropdown} Partial Output - ```text - Compiled Configuration - - ╭─────────────────────────────────────────── run ───────────────────────────────────────────╮ - │ env: │ - │ nodes: 2 │ - │ gpus_per_node: 8 │ - │ nprocs_per_node: 8 │ - │ executor: lepton │ - │ container_image: nvcr.io/nvidia/nemo-automodel:26.04 │ - │ node_group: az-sat-lepton-001 │ - │ resource_shape: gpu.8xa100-80gb │ - │ remote_job_dir: /mnt/lustre-shared/user/nemotron/.nemotron-jobs - ... - ``` - ```` - -1. Submit the sample SFT job: - - ```console - $ uv run nemotron steps run sft/automodel -c tiny -r lepton_sft_automodel - ``` - -The sample `tiny` config sets small training and validation splits. -To specify the output path for checkpoints, set `SFT_OUTPUT_DIR` before running or specify the `checkpoint.checkpoint_dir` CLI override. - -## Success Checks - -- The command `nemotron steps show ` lists `consumes` and `produces` artifact types. Those types must line up with your pipeline when you chain steps. -- A finished sample run leaves logs and job metadata where NeMo Run is configured to write them. See [Execution through NeMo Run](../nemo_runspec/nemo-run.md) for experiment layout. -- If you change tokenizer, template, or sequence length, keep them consistent across every step that touches the same model line. The [Artifact Graph](explanation/artifact-graph.md) page explains why consistency matters. - -## Next Steps - -- Follow [Run SFT with AutoModel on Custom Data](how-to/run-sft-automodel.md) when you need to point `tiny.yaml` at your own data or change the base model. -- Read [Choose an SFT Backend](how-to/choose-sft-backend.md) when you need Megatron Bridge instead of AutoModel. diff --git a/docs/train-models/how-to/index.md b/docs/train-models/how-to/index.md deleted file mode 100644 index fae4390c0..000000000 --- a/docs/train-models/how-to/index.md +++ /dev/null @@ -1,95 +0,0 @@ - - -(train-models-how-to-index)= -# Model Training How-To Guides - -This section provides task-focused guides for common training workflows. -For your first run, start with {doc}`../getting-started`. - -If you are new to fine-tuning concepts, read {doc}`../explanation/index` for definitions of fine-tuning approaches, data formats, and checkpoints before working through these tasks. - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`play;1.5em;sd-mr-1` Run SFT with AutoModel on Custom Data -:link: run-sft-automodel -:link-type: doc -Configure `tiny.yaml` for your own JSONL data, run the step, verify the checkpoint output, and resolve common issues. -+++ -{bdg-success}`30 min` {bdg-secondary}`beginner` -::: - -:::{grid-item-card} {octicon}`rocket;1.5em;sd-mr-1` Choose an SFT Backend -:link: choose-sft-backend -:link-type: doc -Pick between `sft/automodel` and `sft/megatron_bridge` based on checkpoint format and scale. -+++ -{bdg-secondary}`intermediate` -::: - -:::{grid-item-card} {octicon}`tools;1.5em;sd-mr-1` Choose a PEFT Backend -:link: choose-peft-backend -:link-type: doc -Pick between `peft/automodel` and `peft/megatron_bridge` based on base checkpoint format and data path. -+++ -{bdg-secondary}`intermediate` -::: - -:::{grid-item-card} {octicon}`milestone;1.5em;sd-mr-1` Choose an RL Alignment Step -:link: choose-rl-step -:link-type: doc -Pick between DPO, RLVR, and RLHF based on how the reward signal enters training. -+++ -{bdg-secondary}`intermediate` -::: - -:::{grid-item-card} {octicon}`zap;1.5em;sd-mr-1` Run Post-Training Optimization -:link: run-optimization -:link-type: doc -Apply quantization, pruning, or distillation with Model Optimizer after a trained model passes your quality bar. -+++ -{bdg-secondary}`intermediate` -::: - -:::{grid-item-card} {octicon}`server;1.5em;sd-mr-1` Environment Profiles and Executors -:link: env-and-executors -:link-type: doc -Configure NeMo Run environment profiles for local, Slurm, and Lepton execution. -+++ -{bdg-secondary}`intermediate` -::: - -:::{grid-item-card} {octicon}`database;1.5em;sd-mr-1` Data and Checkpoint Formats -:link: data-and-checkpoint-formats -:link-type: doc -Understand the JSONL, Parquet, and checkpoint types that training steps declare in `step.toml`. -+++ -{bdg-secondary}`intermediate` -::: - -:::{grid-item-card} {octicon}`git-compare;1.5em;sd-mr-1` Convert Checkpoints Between Training Steps -:link: convert-checkpoints -:link-type: doc -Run a conversion step when one step produces a checkpoint layout that the next step cannot consume directly. -+++ -{bdg-secondary}`intermediate` -::: - -:::: - -```{toctree} -:hidden: -:maxdepth: 1 - -Run SFT with AutoModel on Custom Data -Choose an SFT Backend -Choose a PEFT Backend -Choose an RL Alignment Step -Run Post-Training Optimization -Environment Profiles and Executors -Data and Checkpoint Formats -Convert Checkpoints -``` diff --git a/docs/train-models/index.md b/docs/train-models/index.md deleted file mode 100644 index 2a7342926..000000000 --- a/docs/train-models/index.md +++ /dev/null @@ -1,90 +0,0 @@ -# Model Training with Nemotron Steps - -This section documents how to run supervised fine-tuning (SFT), parameter-efficient fine-tuning (PEFT), reinforcement learning (RL) alignment, and post-training optimization with Nemotron *steps*. -Each step packages a training approach, configuration files, and entry logic that you invoke through the `nemotron steps` CLI. -For the definitions of *step*, *configuration*, and *environment profile* that apply across every domain, see [Nemotron Steps Basics](../steps/basics.md). -If you are new to fine-tuning, start with [Training Basics](explanation/basics.md), which defines the training-specific terms the rest of this section uses. - -## Capabilities at a Glance - -| Area | Step Names | Role | -|------|-------------------------------|------| -| SFT | `sft/automodel`, `sft/megatron_bridge` | Supervised fine tuning from chat-formatted JSON Lines (JSONL) or packed Apache Parquet | -| PEFT | `peft/automodel`, `peft/megatron_bridge` | Adapter training with a smaller trainable surface | -| RL | `rl/nemo_rl/dpo`, `rl/nemo_rl/rlvr`, `rl/nemo_rl/rlhf` | Alignment after a supervised fine tuning (SFT) policy exists | -| Optimize | `optimize/modelopt/quantize`, `optimize/modelopt/prune`, `optimize/modelopt/distill` | Compression and quality recovery | - -## Limitations and Restrictions - -The Nemotron steps for data preparation and model training do not support local training, such as on a developer workstation. - -These steps require access to at least two nodes, each equipped with 8 x NVIDIA A100 80 GB or better GPUs. -These steps support the following environments: - -- Slurm -- NVIDIA DGX Cloud Lepton -- NVIDIA Run:ai - -For assistance with configuring access to one of the supported computing environments, refer to [](./reference/env-profile-generator.md) or run the `nemotron-env-toml` skill with your agent. - -## Learning Path - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} Training Basics -:link: explanation/basics -:link-type: doc -This page defines supervised fine-tuning, parameter-efficient fine-tuning, reinforcement learning alignment, quantization, tokenizers, the chat dataset format, and checkpoints. -+++ -`Beginner Level` -::: - -:::{grid-item-card} Getting Started -:link: getting-started -:link-type: doc -This guide covers installation expectations, the environment profile, and how to run your first sample job with the `tiny` configuration. -+++ -`Beginner` -::: - -:::{grid-item-card} How-To Guides -:link: how-to/index -:link-type: doc -These guides are task-focused. They explain how to pick a backend, wire data, and run optimization steps. -+++ -`Intermediate` -::: - -:::{grid-item-card} Explanation -:link: explanation/index -:link-type: doc -This material explains the basics, the artifact graph, and how the training libraries differ. -+++ -`Concepts` -::: - -:::{grid-item-card} Reference -:link: reference/index -:link-type: doc -This material is for lookup. It lists the step catalog, parameters, and configuration conventions. -+++ -`Lookup` -::: - -:::{grid-item-card} Model Training with Agents -:link: using-skill -:link-type: doc -Use the customize skill with a YAML-first plan: repo steps, then configs, then code only for gaps. -+++ -`Workflow` -::: - -:::: - -## Quick Links - -- [Model Training with Agents](using-skill.md) describes how to work with the `nemotron-customize` skill for multi-stage training plans and YAML-first deliverables. -- [Getting Started](getting-started.md) describes how to verify the CLI and run a tiny configuration. -- [Execution through NeMo Run](../nemo_runspec/nemo-run.md) describes profiles, attached and detached runs, and clusters. -- [Nemotron CLI Overview](../nemotron/cli.md) describes how the wider CLI relates to configuration and overrides. diff --git a/docs/train-models/reference/convert/index.md b/docs/train-models/reference/convert/index.md deleted file mode 100644 index 51bb4e27c..000000000 --- a/docs/train-models/reference/convert/index.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Reference pages for Nemotron checkpoint conversion steps." -topics: ["Training", "Reference", "Checkpoint Conversion"] -tags: ["Reference", "Steps", "Checkpoints", "Conversion"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] ---- - -# Checkpoint Conversion Steps - -This section documents the conversion steps registered under `src/nemotron/steps/convert/`. -Use these steps to bridge checkpoint layouts between Hugging Face, Megatron distributed checkpoints, and LoRA adapter outputs. - -## Steps - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} convert/hf_to_megatron -:link: hf-to-megatron -:link-type: doc -Import a Hugging Face checkpoint or model id into Megatron distributed checkpoint layout. -+++ -{bdg-success}`reference` -::: - -:::{grid-item-card} convert/megatron_to_hf -:link: megatron-to-hf -:link-type: doc -Export a Megatron distributed checkpoint iteration into Hugging Face safetensors layout. -+++ -{bdg-success}`reference` -::: - -:::{grid-item-card} convert/merge_lora -:link: merge-lora -:link-type: doc -Merge a LoRA adapter with its original base checkpoint to produce a standalone checkpoint. -+++ -{bdg-success}`reference` -::: - -:::: - -## Related Documentation - -- [Convert Checkpoints Between Training Steps](../../how-to/convert-checkpoints.md) -- [Data and Checkpoint Formats](../../how-to/data-and-checkpoint-formats.md) -- [Step Catalog](../step-catalog.md) - -```{toctree} -:hidden: -:maxdepth: 1 - -hf-to-megatron -megatron-to-hf -merge-lora -``` diff --git a/docs/train-models/reference/index.md b/docs/train-models/reference/index.md deleted file mode 100644 index f4e645023..000000000 --- a/docs/train-models/reference/index.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Reference index for Nemotron training steps, configuration conventions, and the CLI." -topics: ["Training", "Reference"] -tags: ["Reference", "CLI", "Configuration", "Steps"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] ---- - -# Training Reference - -This section provides lookup material for every supervised fine-tuning (SFT), parameter-efficient fine-tuning (PEFT), reinforcement learning (RL), and optimization step packaged under `src/nemotron/steps/`. -Use these pages to find the exact CLI syntax, configuration file layout, parameters, and configuration overrides for each step. - -## Reference Sections - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`terminal;1.5em;sd-mr-1` Nemotron Steps CLI Reference -:link: cli-reference -:link-type: doc -Shared command-line syntax, options, dotlist overrides, and passthrough arguments for the `nemotron steps` command group. -+++ -{bdg-success}`lookup` -::: - -:::{grid-item-card} {octicon}`gear;1.5em;sd-mr-1` Env Profile Generator -:link: env-profile-generator -:link-type: doc -The packaged `env/env_toml` step that generates the environment profile file every other training step consumes. -+++ -{bdg-success}`setup` -::: - -:::{grid-item-card} {octicon}`list-unordered;1.5em;sd-mr-1` Step Catalog -:link: step-catalog -:link-type: doc -Every step identifier, manifest path, and per-step reference link. -+++ -{bdg-success}`lookup` -::: - -:::{grid-item-card} {octicon}`file-code;1.5em;sd-mr-1` Configuration Conventions -:link: config-conventions -:link-type: doc -Per-step `config/` layout, CLI configuration resolution, dotlist override rules, and environment-variable expansion. -+++ -{bdg-success}`lookup` -::: - -:::: - -## Per-Category Step References - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`rocket;1.5em;sd-mr-1` Supervised Fine-Tuning Steps -:link: sft/index -:link-type: doc -The `sft/automodel` and `sft/megatron_bridge` references. -+++ -{bdg-success}`reference` -::: - -:::{grid-item-card} {octicon}`tools;1.5em;sd-mr-1` Parameter-Efficient Fine-Tuning Steps -:link: peft/index -:link-type: doc -The `peft/automodel` and `peft/megatron_bridge` references. -+++ -{bdg-success}`reference` -::: - -:::{grid-item-card} {octicon}`milestone;1.5em;sd-mr-1` Reinforcement Learning Steps -:link: rl/index -:link-type: doc -The `rl/nemo_rl/dpo`, `rl/nemo_rl/rlvr`, and `rl/nemo_rl/rlhf` references. -+++ -{bdg-success}`reference` -::: - -:::{grid-item-card} {octicon}`zap;1.5em;sd-mr-1` Optimization Steps -:link: optimize/index -:link-type: doc -The `optimize/modelopt/quantize`, `optimize/modelopt/prune`, and `optimize/modelopt/distill` references. -+++ -{bdg-success}`reference` -::: - -:::{grid-item-card} {octicon}`git-compare;1.5em;sd-mr-1` Checkpoint Conversion Steps -:link: convert/index -:link-type: doc -The `convert/hf_to_megatron`, `convert/megatron_to_hf`, and `convert/merge_lora` references. -+++ -{bdg-success}`reference` -::: - -:::: - -## Related Documentation - -- [Getting Started With Training Steps](../getting-started.md) walks through a first run with the tiny configuration. -- [Execution Through NeMo Run](../../nemo_runspec/nemo-run.md) explains attached and detached execution, environment profiles, and remote job directories. -- [How-To Guides](../how-to/index.md) cover backend choice, data and checkpoint formats, and environment-and-executor setup. - -```{toctree} -:hidden: -:maxdepth: 2 - -cli-reference -env-profile-generator -step-catalog -config-conventions -SFT Steps -PEFT Steps -RL Steps -Optimization Steps -Checkpoint Conversion Steps -``` diff --git a/docs/train-models/reference/optimize/index.md b/docs/train-models/reference/optimize/index.md deleted file mode 100644 index d695733fc..000000000 --- a/docs/train-models/reference/optimize/index.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Reference pages for the model optimization steps." -topics: ["Training", "Reference", "Optimization", "Quantization", "Pruning", "Distillation"] -tags: ["Reference", "Steps", "Optimization", "ModelOpt", "Megatron-Bridge"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] ---- - -# Model Optimization Steps - -This section documents the model optimization steps registered under `src/nemotron/steps/optimize/modelopt/`. -The three steps wrap NVIDIA Model Optimizer through NVIDIA Megatron-Bridge to quantize, prune, and distill trained checkpoints. - -## Steps - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} optimize/modelopt/quantize -:link: quantize -:link-type: doc -Post-training quantization with floating-point recipes such as fp8 and nvfp4, and integer recipes such as int8_sq and int4_awq. -+++ -{bdg-success}`reference` -::: - -:::{grid-item-card} optimize/modelopt/prune -:link: prune -:link-type: doc -Structured pruning by target parameter budget or explicit architecture. -+++ -{bdg-success}`reference` -::: - -:::{grid-item-card} optimize/modelopt/distill -:link: distill -:link-type: doc -Teacher-student distillation that recovers quality after pruning or quantization. -+++ -{bdg-success}`reference` -::: - -:::: - -## Related Documentation - -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Run Post-Training Optimization](../../how-to/run-optimization.md) explains the ordering of prune and distill, hardware targets, and quality recovery. -- [Configuration Conventions](../config-conventions.md) describes the per-step `config/` layout. - -```{toctree} -:hidden: -:maxdepth: 1 - -quantize -prune -distill -``` diff --git a/docs/train-models/reference/peft/index.md b/docs/train-models/reference/peft/index.md deleted file mode 100644 index 7c9f2de32..000000000 --- a/docs/train-models/reference/peft/index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Reference pages for the parameter-efficient fine-tuning training steps." -topics: ["Training", "Reference", "PEFT", "LoRA"] -tags: ["Reference", "Steps", "PEFT", "LoRA"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] ---- - -# Parameter-Efficient Fine-Tuning Steps - -This section documents the parameter-efficient fine-tuning (PEFT) steps registered under `src/nemotron/steps/peft/`. -Each step trains a low-rank adaptation (LoRA) adapter on top of a base model and produces a `checkpoint_lora` artifact. -Merge that artifact with the base model by using the `convert/merge_lora` step when you need a standalone Hugging Face (HF) checkpoint for deployment. - -## Steps - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} peft/automodel -:link: automodel -:link-type: doc -LoRA tuning with the NeMo AutoModel library against Hugging Face base models and JSON Lines chat datasets. -+++ -{bdg-success}`reference` -::: - -:::{grid-item-card} peft/megatron_bridge -:link: megatron-bridge -:link-type: doc -LoRA tuning on top of NVIDIA Megatron-Bridge for distributed training of the Nemotron model family. -+++ -{bdg-success}`reference` -::: - -:::: - -## Related Documentation - -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Choose a PEFT Backend](../../how-to/choose-peft-backend.md) compares `peft/automodel` and `peft/megatron_bridge`. -- [Configuration Conventions](../config-conventions.md) describes the per-step `config/` layout. - -```{toctree} -:hidden: -:maxdepth: 1 - -automodel -megatron-bridge -``` diff --git a/docs/train-models/reference/rl/index.md b/docs/train-models/reference/rl/index.md deleted file mode 100644 index 8369dc329..000000000 --- a/docs/train-models/reference/rl/index.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Reference pages for the reinforcement learning training steps." -topics: ["Training", "Reference", "RL", "DPO", "RLVR", "RLHF"] -tags: ["Reference", "Steps", "RL", "DPO", "RLVR", "RLHF", "NeMo-RL"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] ---- - -# Reinforcement Learning Steps - -This section documents the reinforcement learning (RL) alignment steps registered under `src/nemotron/steps/rl/nemo_rl/`. -All three steps run on NeMo-RL, consume a supervised fine-tuning (SFT) Megatron checkpoint as the warm-start policy, and produce an aligned `checkpoint_megatron` artifact. - -## Steps - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} rl/nemo_rl/dpo -:link: dpo -:link-type: doc -Direct preference optimization with preference pairs. -+++ -{bdg-success}`reference` -::: - -:::{grid-item-card} rl/nemo_rl/rlvr -:link: rlvr -:link-type: doc -Reinforcement learning with verifiable rewards via group relative policy optimization. -+++ -{bdg-success}`reference` -::: - -:::{grid-item-card} rl/nemo_rl/rlhf -:link: rlhf -:link-type: doc -Reinforcement learning from human feedback with a generative reward model judge. -+++ -{bdg-success}`reference` -::: - -:::: - -## Related Documentation - -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Choose an RL Alignment Step](../../how-to/choose-rl-step.md) compares the three RL steps. -- [Configuration Conventions](../config-conventions.md) describes the per-step `config/` layout. - -```{toctree} -:hidden: -:maxdepth: 1 - -dpo -rlvr -rlhf -``` diff --git a/docs/train-models/reference/sft/index.md b/docs/train-models/reference/sft/index.md deleted file mode 100644 index df3f3bcff..000000000 --- a/docs/train-models/reference/sft/index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Reference pages for the supervised fine-tuning training steps." -topics: ["Training", "Reference", "SFT"] -tags: ["Reference", "Steps", "SFT", "AutoModel", "Megatron-Bridge"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] ---- - -# Supervised Fine-Tuning Steps - -This section documents the supervised fine-tuning (SFT) steps registered under `src/nemotron/steps/sft/`. -The two steps target different training libraries and consume different data formats. -Both produce checkpoints you can use as warm-start policies for reinforcement learning alignment. - -## Steps - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} sft/automodel -:link: automodel -:link-type: doc -Supervised fine-tuning with the NeMo AutoModel library against Hugging Face base models and JSON Lines chat datasets. -+++ -{bdg-success}`reference` -::: - -:::{grid-item-card} sft/megatron_bridge -:link: megatron-bridge -:link-type: doc -Supervised fine-tuning on top of NVIDIA Megatron-Bridge for distributed training of the Nemotron model family. -+++ -{bdg-success}`reference` -::: - -:::: - -## Related Documentation - -- [Nemotron Steps CLI Reference](../cli-reference.md) covers the shared option set, dotlist overrides, and passthrough arguments. -- [Choose an SFT Backend](../../how-to/choose-sft-backend.md) compares `sft/automodel` and `sft/megatron_bridge`. -- [Configuration Conventions](../config-conventions.md) describes the per-step `config/` layout. - -```{toctree} -:hidden: -:maxdepth: 1 - -automodel -megatron-bridge -``` diff --git a/docs/train-models/reference/step-catalog.md b/docs/train-models/reference/step-catalog.md deleted file mode 100644 index 24c8c50ef..000000000 --- a/docs/train-models/reference/step-catalog.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Catalog of every Nemotron training step identifier, manifest path, and per-step reference link." -topics: ["Training", "Reference", "Steps", "Catalog"] -tags: ["Reference", "Steps", "Catalog"] -content: - type: "Reference" - difficulty: "All Levels" - audience: ["ML Engineer", "Developer"] ---- - -# Step Catalog - -This page catalogs every training step identifier registered under `src/nemotron/steps/` in the `sft`, `peft`, `rl`, and `optimize` directories. -Each row gives the step identifier, the on-disk manifest path, and the per-step reference page. - -Adjacent preparation and conversion steps do not appear in this catalog. -Those step identifiers include `data_prep/sft_packing`, `data_prep/rl_prep`, and `convert/megatron_to_hf`, and they live under different directories with their own manifests. - -## Supervised Fine-Tuning Steps - -| Step Identifier | Manifest Path | Reference | -| --- | --- | --- | -| `sft/automodel` | `src/nemotron/steps/sft/automodel/step.toml` | [sft/automodel](sft/automodel.md) | -| `sft/megatron_bridge` | `src/nemotron/steps/sft/megatron_bridge/step.toml` | [sft/megatron_bridge](sft/megatron-bridge.md) | - -## Parameter-Efficient Fine-Tuning Steps - -| Step Identifier | Manifest Path | Reference | -| --- | --- | --- | -| `peft/automodel` | `src/nemotron/steps/peft/automodel/step.toml` | [peft/automodel](peft/automodel.md) | -| `peft/megatron_bridge` | `src/nemotron/steps/peft/megatron_bridge/step.toml` | [peft/megatron_bridge](peft/megatron-bridge.md) | - -## Reinforcement Learning Steps - -| Step Identifier | Manifest Path | Reference | -| --- | --- | --- | -| `rl/nemo_rl/dpo` | `src/nemotron/steps/rl/nemo_rl/dpo/step.toml` | [rl/nemo_rl/dpo](rl/dpo.md) | -| `rl/nemo_rl/rlvr` | `src/nemotron/steps/rl/nemo_rl/rlvr/step.toml` | [rl/nemo_rl/rlvr](rl/rlvr.md) | -| `rl/nemo_rl/rlhf` | `src/nemotron/steps/rl/nemo_rl/rlhf/step.toml` | [rl/nemo_rl/rlhf](rl/rlhf.md) | - -## Optimization Steps - -| Step Identifier | Manifest Path | Reference | -| --- | --- | --- | -| `optimize/modelopt/quantize` | `src/nemotron/steps/optimize/modelopt/quantize/step.toml` | [optimize/modelopt/quantize](optimize/quantize.md) | -| `optimize/modelopt/prune` | `src/nemotron/steps/optimize/modelopt/prune/step.toml` | [optimize/modelopt/prune](optimize/prune.md) | -| `optimize/modelopt/distill` | `src/nemotron/steps/optimize/modelopt/distill/step.toml` | [optimize/modelopt/distill](optimize/distill.md) | - -## List Steps from the Command Line - -This catalog covers the `sft`, `peft`, `rl`, and `optimize` step categories. -Running `nemotron steps list` with no filter returns all registered steps, including data preparation, evaluation, conversion, environment, and other categories not listed here. -Use the `--category`, `--consumes`, and `--produces` filters to narrow the results. - -```console -$ nemotron steps list --category sft -$ nemotron steps list --consumes training_jsonl -$ nemotron steps list --produces checkpoint_megatron --json -``` - -## Related Documentation - -- [Nemotron Steps CLI Reference](cli-reference.md) covers the `list`, `show`, and `run` subcommands. -- [Configuration Conventions](config-conventions.md) describes the per-step `config/` layout. diff --git a/docs/translation/_snippets/input/train_sample.jsonl b/docs/translation/_snippets/input/train_sample.jsonl deleted file mode 100644 index 191463602..000000000 --- a/docs/translation/_snippets/input/train_sample.jsonl +++ /dev/null @@ -1,5 +0,0 @@ -{"messages": [{"role": "system", "content": "You are a helpful assistant with access to weather information."}, {"role": "user", "content": "What's the weather in Tokyo?"}, {"role": "assistant", "tool_calls": [{"id": "weather_5854", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\": \"Tokyo\", \"units\": \"fahrenheit\"}"}}], "content": ""}, {"role": "tool", "tool_call_id": "weather_5854", "content": "{\"temp\": 72, \"condition\": \"sunny\", \"humidity\": 45}"}, {"role": "assistant", "content": "The weather in Tokyo is sunny with a temperature of 72\u00b0F and 45% humidity."}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Get current weather for a location", "parameters": {"type": "object", "properties": {"location": {"type": "string"}, "units": {"type": "string"}}, "required": ["location"]}}}]} -{"messages": [{"role": "system", "content": "You are a database assistant."}, {"role": "user", "content": "Find all users from California"}, {"role": "assistant", "tool_calls": [{"id": "db_2329", "type": "function", "function": {"name": "query_database", "arguments": "{\"query\": \"Find all users from California\"}"}}], "content": ""}, {"role": "tool", "tool_call_id": "db_2329", "content": "[{\"id\": 1, \"name\": \"John Doe\", \"state\": \"CA\"}, {\"id\": 5, \"name\": \"Jane Smith\", \"state\": \"CA\"}]"}, {"role": "assistant", "content": "Here's what I found: [{\"id\": 1, \"name\": \"John Doe\", \"state\": \"CA\"}, {\"id\": 5, \"name\": \"Jane Smith\", \"state\": \"CA\"}]"}], "tools": [{"type": "function", "function": {"name": "query_database", "description": "Query the database", "parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}]} -{"messages": [{"role": "system", "content": "You are a calculator assistant."}, {"role": "user", "content": "What is 156 * 24?"}, {"role": "assistant", "tool_calls": [{"id": "calc_8712", "type": "function", "function": {"name": "calculate", "arguments": "{\"expression\": \"156 * 24\"}"}}], "content": ""}, {"role": "tool", "tool_call_id": "calc_8712", "content": "3744"}, {"role": "assistant", "content": "The result of 156 * 24 is 3744."}], "tools": [{"type": "function", "function": {"name": "calculate", "description": "Perform mathematical calculation", "parameters": {"type": "object", "properties": {"expression": {"type": "string"}}, "required": ["expression"]}}}]} -{"messages": [{"role": "system", "content": "You are a database assistant."}, {"role": "user", "content": "Get product by ID 12345"}, {"role": "assistant", "tool_calls": [{"id": "db_7995", "type": "function", "function": {"name": "query_database", "arguments": "{\"query\": \"Get product by ID 12345\"}"}}], "content": ""}, {"role": "tool", "tool_call_id": "db_7995", "content": "{\"id\": 12345, \"name\": \"Laptop\", \"price\": 999.99}"}, {"role": "assistant", "content": "Here's what I found: {\"id\": 12345, \"name\": \"Laptop\", \"price\": 999.99}"}], "tools": [{"type": "function", "function": {"name": "query_database", "description": "Query the database", "parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}]} -{"messages": [{"role": "system", "content": "You are a helpful assistant with access to weather information."}, {"role": "user", "content": "What's the weather in Dubai?"}, {"role": "assistant", "tool_calls": [{"id": "weather_8882", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\": \"Dubai\", \"units\": \"fahrenheit\"}"}}], "content": ""}, {"role": "tool", "tool_call_id": "weather_8882", "content": "{\"temp\": 55, \"condition\": \"rainy\", \"humidity\": 80}"}, {"role": "assistant", "content": "The weather in Dubai is rainy with a temperature of 55\u00b0F and 80% humidity."}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Get current weather for a location", "parameters": {"type": "object", "properties": {"location": {"type": "string"}, "units": {"type": "string"}}, "required": ["location"]}}}]} diff --git a/docs/translation/_snippets/output/translated.jsonl b/docs/translation/_snippets/output/translated.jsonl deleted file mode 100644 index f98d07f2e..000000000 --- a/docs/translation/_snippets/output/translated.jsonl +++ /dev/null @@ -1,466 +0,0 @@ -{ - "messages": [ - { - "role": "system", - "content": "[आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।]" - }, - { - "role": "user", - "content": "[टोक्यो में मौसम कैसा है?]" - }, - { - "role": "assistant", - "tool_calls": [ - { - "id": "weather_5854", - "type": "function", - "function": { - "name": "get_weather", - "arguments": "{\"location\": \"Tokyo\", \"units\": \"fahrenheit\"}" - } - } - ], - "content": "" - }, - { - "role": "tool", - "tool_call_id": "weather_5854", - "content": "{\"temp\": 72, \"condition\": \"sunny\", \"humidity\": 45}" - }, - { - "role": "assistant", - "content": "टोक्यो में मौसम धूपभरा है, 72°F का तापमान और 45% आर्द्रता के साथ।" - } - ], - "tools": [ - { - "type": "function", - "function": { - "name": "get_weather", - "description": "Get current weather for a location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string" - }, - "units": { - "type": "string" - } - }, - "required": [ - "location" - ] - } - } - } - ], - "translation_time": 8.9217984676, - "translation_errors": "", - "translated_text": [ - { - "role": "system", - "content": "[आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।]" - }, - { - "role": "user", - "content": "[टोक्यो में मौसम कैसा है?]" - }, - { - "role": "assistant", - "tool_calls": [ - { - "id": "weather_5854", - "type": "function", - "function": { - "name": "get_weather", - "arguments": "{\"location\": \"Tokyo\", \"units\": \"fahrenheit\"}" - } - } - ], - "content": "" - }, - { - "role": "tool", - "tool_call_id": "weather_5854", - "content": "{\"temp\": 72, \"condition\": \"sunny\", \"humidity\": 45}" - }, - { - "role": "assistant", - "content": "टोक्यो में मौसम धूपभरा है, 72°F का तापमान और 45% आर्द्रता के साथ।" - } - ], - "translation_metadata": "{\"target_lang\": \"hi\", \"translation\": {\"content\": [\"[आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।]\", \"[टोक्यो में मौसम कैसा है?]\", \"\", \"{\\\"temp\\\": 72, \\\"condition\\\": \\\"sunny\\\", \\\"humidity\\\": 45}\", \"टोक्यो में मौसम धूपभरा है, 72°F का तापमान और 45% आर्द्रता के साथ।\"]}, \"segmented_translation\": {\"content\": [{\"src\": \"You are a helpful assistant with access to weather information.\", \"tgt\": \"[आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।]\"}, {\"src\": \"What's the weather in Tokyo?\", \"tgt\": \"[टोक्यो में मौसम कैसा है?]\"}, {\"src\": \"The weather in Tokyo is sunny with a temperature of 72°F and 45% humidity.\", \"tgt\": \"टोक्यो में मौसम धूपभरा है, 72°F का तापमान और 45% आर्द्रता के साथ।\"}]}}", - "translated_messages": "[{\"role\": \"system\", \"content\": \"[आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।]\"}, {\"role\": \"user\", \"content\": \"[टोक्यो में मौसम कैसा है?]\"}, {\"role\": \"assistant\", \"tool_calls\": [{\"id\": \"weather_5854\", \"type\": \"function\", \"function\": {\"name\": \"get_weather\", \"arguments\": \"{\\\"location\\\": \\\"Tokyo\\\", \\\"units\\\": \\\"fahrenheit\\\"}\"}}], \"content\": \"\"}, {\"role\": \"tool\", \"tool_call_id\": \"weather_5854\", \"content\": \"{\\\"temp\\\": 72, \\\"condition\\\": \\\"sunny\\\", \\\"humidity\\\": 45}\"}, {\"role\": \"assistant\", \"content\": \"टोक्यो में मौसम धूपभरा है, 72°F का तापमान और 45% आर्द्रता के साथ।\"}]" -} -{ - "messages": [ - { - "role": "system", - "content": "आप एक डेटाबेस सहायक हैं।" - }, - { - "role": "user", - "content": "सभी कैलिफोर्निया से उपयोगकर्ताओं को खोजें" - }, - { - "role": "assistant", - "tool_calls": [ - { - "id": "db_2329", - "type": "function", - "function": { - "name": "query_database", - "arguments": "{\"query\": \"Find all users from California\"}" - } - } - ], - "content": "" - }, - { - "role": "tool", - "tool_call_id": "db_2329", - "content": "[{\"id\": 1, \"name\": \"John Doe\", \"state\": \"CA\"}, {\"id\": 5, \"name\": \"Jane Smith\", \"state\": \"CA\"}]" - }, - { - "role": "assistant", - "content": "यहाँ क्या मिला: [{\"id\": 1, \"name\": \"John Doe\", \"state\": \"CA\"}, {\"id\": 5, \"name\": \"Jane Smith\", \"state\": \"CA\"}]" - } - ], - "tools": [ - { - "type": "function", - "function": { - "name": "query_database", - "description": "Query the database", - "parameters": { - "type": "object", - "properties": { - "query": { - "type": "string" - } - }, - "required": [ - "query" - ] - } - } - } - ], - "translation_time": 18.4458503723, - "translation_errors": "", - "translated_text": [ - { - "role": "system", - "content": "आप एक डेटाबेस सहायक हैं।" - }, - { - "role": "user", - "content": "सभी कैलिफोर्निया से उपयोगकर्ताओं को खोजें" - }, - { - "role": "assistant", - "tool_calls": [ - { - "id": "db_2329", - "type": "function", - "function": { - "name": "query_database", - "arguments": "{\"query\": \"Find all users from California\"}" - } - } - ], - "content": "" - }, - { - "role": "tool", - "tool_call_id": "db_2329", - "content": "[{\"id\": 1, \"name\": \"John Doe\", \"state\": \"CA\"}, {\"id\": 5, \"name\": \"Jane Smith\", \"state\": \"CA\"}]" - }, - { - "role": "assistant", - "content": "यहाँ क्या मिला: [{\"id\": 1, \"name\": \"John Doe\", \"state\": \"CA\"}, {\"id\": 5, \"name\": \"Jane Smith\", \"state\": \"CA\"}]" - } - ], - "translation_metadata": "{\"target_lang\": \"hi\", \"translation\": {\"content\": [\"आप एक डेटाबेस सहायक हैं।\", \"सभी कैलिफोर्निया से उपयोगकर्ताओं को खोजें\", \"\", \"[{\\\"id\\\": 1, \\\"name\\\": \\\"John Doe\\\", \\\"state\\\": \\\"CA\\\"}, {\\\"id\\\": 5, \\\"name\\\": \\\"Jane Smith\\\", \\\"state\\\": \\\"CA\\\"}]\", \"यहाँ क्या मिला: [{\\\"id\\\": 1, \\\"name\\\": \\\"John Doe\\\", \\\"state\\\": \\\"CA\\\"}, {\\\"id\\\": 5, \\\"name\\\": \\\"Jane Smith\\\", \\\"state\\\": \\\"CA\\\"}]\"]}, \"segmented_translation\": {\"content\": [{\"src\": \"You are a database assistant.\", \"tgt\": \"आप एक डेटाबेस सहायक हैं।\"}, {\"src\": \"Find all users from California\", \"tgt\": \"सभी कैलिफोर्निया से उपयोगकर्ताओं को खोजें\"}, {\"src\": \"Here's what I found: [{\\\"id\\\": 1, \\\"name\\\": \\\"John Doe\\\", \\\"state\\\": \\\"CA\\\"}, {\\\"id\\\": 5, \\\"name\\\": \\\"Jane Smith\\\", \\\"state\\\": \\\"CA\\\"}]\", \"tgt\": \"यहाँ क्या मिला: [{\\\"id\\\": 1, \\\"name\\\": \\\"John Doe\\\", \\\"state\\\": \\\"CA\\\"}, {\\\"id\\\": 5, \\\"name\\\": \\\"Jane Smith\\\", \\\"state\\\": \\\"CA\\\"}]\"}]}}", - "translated_messages": "[{\"role\": \"system\", \"content\": \"आप एक डेटाबेस सहायक हैं।\"}, {\"role\": \"user\", \"content\": \"सभी कैलिफोर्निया से उपयोगकर्ताओं को खोजें\"}, {\"role\": \"assistant\", \"tool_calls\": [{\"id\": \"db_2329\", \"type\": \"function\", \"function\": {\"name\": \"query_database\", \"arguments\": \"{\\\"query\\\": \\\"Find all users from California\\\"}\"}}], \"content\": \"\"}, {\"role\": \"tool\", \"tool_call_id\": \"db_2329\", \"content\": \"[{\\\"id\\\": 1, \\\"name\\\": \\\"John Doe\\\", \\\"state\\\": \\\"CA\\\"}, {\\\"id\\\": 5, \\\"name\\\": \\\"Jane Smith\\\", \\\"state\\\": \\\"CA\\\"}]\"}, {\"role\": \"assistant\", \"content\": \"यहाँ क्या मिला: [{\\\"id\\\": 1, \\\"name\\\": \\\"John Doe\\\", \\\"state\\\": \\\"CA\\\"}, {\\\"id\\\": 5, \\\"name\\\": \\\"Jane Smith\\\", \\\"state\\\": \\\"CA\\\"}]\"}]" -} -{ - "messages": [ - { - "role": "system", - "content": "[आप एक कैलकुलेटर सहायक हैं।]" - }, - { - "role": "user", - "content": "[क्या 156 * 24 है?]" - }, - { - "role": "assistant", - "tool_calls": [ - { - "id": "calc_8712", - "type": "function", - "function": { - "name": "calculate", - "arguments": "{\"expression\": \"156 * 24\"}" - } - } - ], - "content": "" - }, - { - "role": "tool", - "tool_call_id": "calc_8712", - "content": "3744" - }, - { - "role": "assistant", - "content": "156 * 24 का परिणाम 3744 है।" - } - ], - "tools": [ - { - "type": "function", - "function": { - "name": "calculate", - "description": "Perform mathematical calculation", - "parameters": { - "type": "object", - "properties": { - "expression": { - "type": "string" - } - }, - "required": [ - "expression" - ] - } - } - } - ], - "translation_time": 34.5283660889, - "translation_errors": "", - "translated_text": [ - { - "role": "system", - "content": "[आप एक कैलकुलेटर सहायक हैं।]" - }, - { - "role": "user", - "content": "[क्या 156 * 24 है?]" - }, - { - "role": "assistant", - "tool_calls": [ - { - "id": "calc_8712", - "type": "function", - "function": { - "name": "calculate", - "arguments": "{\"expression\": \"156 * 24\"}" - } - } - ], - "content": "" - }, - { - "role": "tool", - "tool_call_id": "calc_8712", - "content": "3744" - }, - { - "role": "assistant", - "content": "156 * 24 का परिणाम 3744 है।" - } - ], - "translation_metadata": "{\"target_lang\": \"hi\", \"translation\": {\"content\": [\"[आप एक कैलकुलेटर सहायक हैं।]\", \"[क्या 156 * 24 है?]\", \"\", \"3744\", \"156 * 24 का परिणाम 3744 है।\"]}, \"segmented_translation\": {\"content\": [{\"src\": \"You are a calculator assistant.\", \"tgt\": \"[आप एक कैलकुलेटर सहायक हैं।]\"}, {\"src\": \"What is 156 * 24?\", \"tgt\": \"[क्या 156 * 24 है?]\"}, {\"src\": \"The result of 156 * 24 is 3744.\", \"tgt\": \"156 * 24 का परिणाम 3744 है।\"}]}}", - "translated_messages": "[{\"role\": \"system\", \"content\": \"[आप एक कैलकुलेटर सहायक हैं।]\"}, {\"role\": \"user\", \"content\": \"[क्या 156 * 24 है?]\"}, {\"role\": \"assistant\", \"tool_calls\": [{\"id\": \"calc_8712\", \"type\": \"function\", \"function\": {\"name\": \"calculate\", \"arguments\": \"{\\\"expression\\\": \\\"156 * 24\\\"}\"}}], \"content\": \"\"}, {\"role\": \"tool\", \"tool_call_id\": \"calc_8712\", \"content\": \"3744\"}, {\"role\": \"assistant\", \"content\": \"156 * 24 का परिणाम 3744 है।\"}]" -} -{ - "messages": [ - { - "role": "system", - "content": "[आप एक डेटाबेस सहायक हैं।]" - }, - { - "role": "user", - "content": "3. Copy the content as-is.\n```python\ndef calculate_sum(a, b):\n return a + b\n```" - }, - { - "role": "assistant", - "tool_calls": [ - { - "id": "db_7995", - "type": "function", - "function": { - "name": "query_database", - "arguments": "{\"query\": \"Get product by ID 12345\"}" - } - } - ], - "content": "" - }, - { - "role": "tool", - "tool_call_id": "db_7995", - "content": "{\"id\": 12345, \"name\": \"Laptop\", \"price\": 999.99}" - }, - { - "role": "assistant", - "content": "यहाँ क्या मिला: {\"id\": 12345, \"name\": \"Laptop\", \"price\": 999.99}" - } - ], - "tools": [ - { - "type": "function", - "function": { - "name": "query_database", - "description": "Query the database", - "parameters": { - "type": "object", - "properties": { - "query": { - "type": "string" - } - }, - "required": [ - "query" - ] - } - } - } - ], - "translation_time": 39.8996043205, - "translation_errors": "", - "translated_text": [ - { - "role": "system", - "content": "[आप एक डेटाबेस सहायक हैं।]" - }, - { - "role": "user", - "content": "3. Copy the content as-is.\n```python\ndef calculate_sum(a, b):\n return a + b\n```" - }, - { - "role": "assistant", - "tool_calls": [ - { - "id": "db_7995", - "type": "function", - "function": { - "name": "query_database", - "arguments": "{\"query\": \"Get product by ID 12345\"}" - } - } - ], - "content": "" - }, - { - "role": "tool", - "tool_call_id": "db_7995", - "content": "{\"id\": 12345, \"name\": \"Laptop\", \"price\": 999.99}" - }, - { - "role": "assistant", - "content": "यहाँ क्या मिला: {\"id\": 12345, \"name\": \"Laptop\", \"price\": 999.99}" - } - ], - "translation_metadata": "{\"target_lang\": \"hi\", \"translation\": {\"content\": [\"[आप एक डेटाबेस सहायक हैं।]\", \"3. Copy the content as-is.\\n```python\\ndef calculate_sum(a, b):\\n return a + b\\n```\", \"\", \"{\\\"id\\\": 12345, \\\"name\\\": \\\"Laptop\\\", \\\"price\\\": 999.99}\", \"यहाँ क्या मिला: {\\\"id\\\": 12345, \\\"name\\\": \\\"Laptop\\\", \\\"price\\\": 999.99}\"]}, \"segmented_translation\": {\"content\": [{\"src\": \"You are a database assistant.\", \"tgt\": \"[आप एक डेटाबेस सहायक हैं।]\"}, {\"src\": \"Get product by ID 12345\", \"tgt\": \"3. Copy the content as-is.\\n```python\\ndef calculate_sum(a, b):\\n return a + b\\n```\"}, {\"src\": \"Here's what I found: {\\\"id\\\": 12345, \\\"name\\\": \\\"Laptop\\\", \\\"price\\\": 999.99}\", \"tgt\": \"यहाँ क्या मिला: {\\\"id\\\": 12345, \\\"name\\\": \\\"Laptop\\\", \\\"price\\\": 999.99}\"}]}}", - "translated_messages": "[{\"role\": \"system\", \"content\": \"[आप एक डेटाबेस सहायक हैं।]\"}, {\"role\": \"user\", \"content\": \"3. Copy the content as-is.\\n```python\\ndef calculate_sum(a, b):\\n return a + b\\n```\"}, {\"role\": \"assistant\", \"tool_calls\": [{\"id\": \"db_7995\", \"type\": \"function\", \"function\": {\"name\": \"query_database\", \"arguments\": \"{\\\"query\\\": \\\"Get product by ID 12345\\\"}\"}}], \"content\": \"\"}, {\"role\": \"tool\", \"tool_call_id\": \"db_7995\", \"content\": \"{\\\"id\\\": 12345, \\\"name\\\": \\\"Laptop\\\", \\\"price\\\": 999.99}\"}, {\"role\": \"assistant\", \"content\": \"यहाँ क्या मिला: {\\\"id\\\": 12345, \\\"name\\\": \\\"Laptop\\\", \\\"price\\\": 999.99}\"}]" -} -{ - "messages": [ - { - "role": "system", - "content": "आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।" - }, - { - "role": "user", - "content": "[दुबई में मौसम कैसा है?]" - }, - { - "role": "assistant", - "tool_calls": [ - { - "id": "weather_8882", - "type": "function", - "function": { - "name": "get_weather", - "arguments": "{\"location\": \"Dubai\", \"units\": \"fahrenheit\"}" - } - } - ], - "content": "" - }, - { - "role": "tool", - "tool_call_id": "weather_8882", - "content": "{\"temp\": 55, \"condition\": \"rainy\", \"humidity\": 80}" - }, - { - "role": "assistant", - "content": "दुबई में मौसम बारिश के साथ है, तापमान 55°F और 80% आर्द्रता के साथ।" - } - ], - "tools": [ - { - "type": "function", - "function": { - "name": "get_weather", - "description": "Get current weather for a location", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string" - }, - "units": { - "type": "string" - } - }, - "required": [ - "location" - ] - } - } - } - ], - "translation_time": 50.0045132637, - "translation_errors": "", - "translated_text": [ - { - "role": "system", - "content": "आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।" - }, - { - "role": "user", - "content": "[दुबई में मौसम कैसा है?]" - }, - { - "role": "assistant", - "tool_calls": [ - { - "id": "weather_8882", - "type": "function", - "function": { - "name": "get_weather", - "arguments": "{\"location\": \"Dubai\", \"units\": \"fahrenheit\"}" - } - } - ], - "content": "" - }, - { - "role": "tool", - "tool_call_id": "weather_8882", - "content": "{\"temp\": 55, \"condition\": \"rainy\", \"humidity\": 80}" - }, - { - "role": "assistant", - "content": "दुबई में मौसम बारिश के साथ है, तापमान 55°F और 80% आर्द्रता के साथ।" - } - ], - "translation_metadata": "{\"target_lang\": \"hi\", \"translation\": {\"content\": [\"आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।\", \"[दुबई में मौसम कैसा है?]\", \"\", \"{\\\"temp\\\": 55, \\\"condition\\\": \\\"rainy\\\", \\\"humidity\\\": 80}\", \"दुबई में मौसम बारिश के साथ है, तापमान 55°F और 80% आर्द्रता के साथ।\"]}, \"segmented_translation\": {\"content\": [{\"src\": \"You are a helpful assistant with access to weather information.\", \"tgt\": \"आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।\"}, {\"src\": \"What's the weather in Dubai?\", \"tgt\": \"[दुबई में मौसम कैसा है?]\"}, {\"src\": \"The weather in Dubai is rainy with a temperature of 55°F and 80% humidity.\", \"tgt\": \"दुबई में मौसम बारिश के साथ है, तापमान 55°F और 80% आर्द्रता के साथ।\"}]}}", - "translated_messages": "[{\"role\": \"system\", \"content\": \"आप एक उपयोगी सहायक हैं जिसके पास मौसम की जानकारी तक पहुँच है।\"}, {\"role\": \"user\", \"content\": \"[दुबई में मौसम कैसा है?]\"}, {\"role\": \"assistant\", \"tool_calls\": [{\"id\": \"weather_8882\", \"type\": \"function\", \"function\": {\"name\": \"get_weather\", \"arguments\": \"{\\\"location\\\": \\\"Dubai\\\", \\\"units\\\": \\\"fahrenheit\\\"}\"}}], \"content\": \"\"}, {\"role\": \"tool\", \"tool_call_id\": \"weather_8882\", \"content\": \"{\\\"temp\\\": 55, \\\"condition\\\": \\\"rainy\\\", \\\"humidity\\\": 80}\"}, {\"role\": \"assistant\", \"content\": \"दुबई में मौसम बारिश के साथ है, तापमान 55°F और 80% आर्द्रता के साथ।\"}]" -} diff --git a/docs/translation/explanation/index.md b/docs/translation/explanation/index.md deleted file mode 100644 index 399ea3525..000000000 --- a/docs/translation/explanation/index.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Concept pages for nemotron steps run translate/nemo_curator: pipeline flow, segmentation, FAITH." -topics: ["Translation", "Concepts"] -tags: ["Explanation", "Translation"] -content: - type: "Explanation" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] ---- - -# Concepts - -Background on how the translation pipeline fits together, how segmentation behaves, and what FAITH measures. Use these pages when how-to steps refer to behavior you want to understand before changing defaults. - -```{toctree} -:maxdepth: 1 -:hidden: - -pipeline-overview -segmentation -faith-evaluation -``` - -Concept-focused explanations for `nemotron steps run translate/nemo_curator` and the `translate/nemo_curator` Curator pipeline. - -## Pipeline Processing - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`graph;1.5em;sd-mr-1` Pipeline overview -:link: pipeline-overview -:link-type: doc -Reader to `TranslationStage` to writer, with an optional FAITH branch. -+++ -{bdg-secondary}`architecture` -::: - -:::{grid-item-card} {octicon}`package;1.5em;sd-mr-1` Segmentation -:link: segmentation -:link-type: doc -Coarse versus fine `segmentation_mode` trade-offs. -+++ -{bdg-secondary}`segmentation` -::: - -:::: - -## Evaluation Inside Translation - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`checklist;1.5em;sd-mr-1` FAITH evaluation -:link: faith-evaluation -:link-type: doc -What FAITH captures when `faith_eval.enabled` is true. -+++ -{bdg-secondary}`faith` -::: - -:::: diff --git a/docs/translation/explanation/segmentation.md b/docs/translation/explanation/segmentation.md deleted file mode 100644 index 90a40ae45..000000000 --- a/docs/translation/explanation/segmentation.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Segmentation modes for nemotron steps run translate/nemo_curator: coarse and fine modes, plus min_segment_chars." -topics: ["Translation", "Segmentation"] -tags: ["Explanation", "Translation"] -content: - type: "Explanation" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] ---- - -# Segmentation - -This page helps you pick `segmentation_mode` values that keep translations faithful without chopping structured payloads. - -## Controls - -| YAML key | Meaning | -|----------|---------| -| `segmentation_mode` | `coarse` is the default. It balances throughput while respecting code fences and markup boundaries. `fine` emits smaller linguistic segments when coarse spans truncate meaning. | -| `min_segment_chars` | Skips extremely short fragments that harm throughput or confuse backends. The default is `0`, which disables filtering. | - -## When Coarse Is Enough - -Start with `segmentation_mode: coarse` when records contain JSON-like strings, tool arguments, or fenced code blocks. Coarse mode tracks reconstruction metadata so `TranslationStage` can rebuild the original nesting after translating natural-language spans. - -## When to Switch to Fine - -Move to `segmentation_mode: fine` when you observe clipped sentences, missing trailing punctuation, or uneven translations inside long paragraphs, and you have confirmed the issue disappears after finer segmentation. - -Fine mode increases API calls or neural machine translation (NMT) batches. Budget concurrency by using `max_concurrent_requests` or backend-specific knobs. - -## Interaction With FAITH - -FAITH scoring is part of Curator's translation stage and follows the translated segment pairs produced by the stage, which keeps thresholds interpretable on long documents. - -## Practical Workflow - -1. Run with `coarse` first. -2. Inspect a handful of difficult rows such as legal text, mixed Markdown, or multilingual snippets. -3. If boundaries look wrong, toggle `fine` on a slice before scaling up. - -## Related Pages - -- Step-by-step fine mode: {doc}`../how-to/use-fine-segmentation` -- Pipeline context: {doc}`pipeline-overview` -- FAITH alignment with segments: {doc}`faith-evaluation` diff --git a/docs/translation/getting-started.md b/docs/translation/getting-started.md deleted file mode 100644 index 1bc1414f7..000000000 --- a/docs/translation/getting-started.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Run nemotron steps run translate/nemo_curator end-to-end with config/default.yaml and sample chat JSONL." -topics: ["Translation", "Tutorial"] -tags: ["Tutorial", "Translation"] -content: - type: "Tutorial" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] ---- - -(getting-started-translation)= -# Getting Started With Translation - -You will produce translated JSON Lines (JSONL) shards under an `output_dir` you choose, with FAITH quality scoring applied in the same run. FAITH is the translation-quality scorer name used in NVIDIA NeMo Curator documentation. - -This tutorial runs `nemotron steps run translate/nemo_curator` end to end on a small sample file. You use `src/nemotron/steps/translate/nemo_curator/config/default.yaml` and CLI dotlist overrides. - -:::{card} -What You Will Produce - -Translation shards sit under a writable `output_dir`, with filtering governed by `faith_eval` in the same run. - -^^^ - -Overview - -1. Export `NVIDIA_API_KEY`. -2. Download the sample `train_sample.jsonl` chat file. -3. Run `nemotron steps run translate/nemo_curator -c default` with CLI overrides for paths, languages, and `server.model`. -4. Inspect `output_dir` for translated records. - -{octicon}`clock;1em;sd-mr-1` Budget roughly five to fifteen minutes depending on network latency and response time from your provider and on corpus size. -The sample contains about one hundred lines. -::: - -## Prerequisites - -- Network access to `https://integrate.api.nvidia.com/v1`. -- `NVIDIA_API_KEY` exported in your shell. -- For local `uv run` execution with Curator/Ray, export `RAY_ENABLE_UV_RUN_RUNTIME_ENV=0` - so Ray workers reuse the synchronized project environment. - -## Sample Input File - -This translation tutorial uses `train_sample.jsonl` as a compact multi-turn chat dataset. - -```{literalinclude} _snippets/input/train_sample.jsonl -:language: json -:class: scrollable -``` - -## Procedure - -1. Clone the repository, if you haven't already: - - ```console - $ git clone https://github.com/NVIDIA-NeMo/Nemotron && cd Nemotron - ``` - -1. Synchronize the dependencies: - - ```console - $ uv sync --extra translate - ``` - -1. Download `train_sample.jsonl` from the [sample file](_snippets/input/train_sample.jsonl). - - Save the file in the repository root if you want to match the `input_path` below exactly. If you save it elsewhere, change `input_path` in the commands that follow. - -1. Run the translation stage. - - From the repository root, specify the `default.yaml` config and overrides by using CLI arguments. - Set `server.model` to a model your endpoint serves. - Replace `` with your NVIDIA API key value, or set `NVIDIA_API_KEY` in your environment before running the command. - - ```console - $ export NVIDIA_API_KEY="" - $ export RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 - - $ uv run --no-sync nemotron steps run translate/nemo_curator -c default \ - input_path="${PWD}/train_sample.jsonl" \ - output_dir=./output/translation-getting-started \ - source_language=en \ - target_language=hi \ - server.model=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning \ - faith_eval.enabled=false \ - faith_eval.filter_enabled=false \ - max_concurrent_requests=4 - ``` - - - `input_path` and `output_dir` replace the placeholders in `default.yaml`. - - `source_language` and `target_language` must be explicit two-letter language codes from the ISO 639-1 standard, which the International Organization for Standardization publishes. - - The starter file leaves them empty on purpose so you choose the pair at run time. - - `server.model` is required when `backend` is `llm`. - - The default `server.url` in `default.yaml` is `https://integrate.api.nvidia.com/v1`. - -1. Inspect the output. - - The `output_dir` path holds the Curator writer output when `output_format` is `jsonl`, usually several shard files instead of one consolidated JSONL file. - Spot-check one line. - - ```console - $ find ./output/translation-getting-started -name '*.jsonl' | head -n 1 | xargs head -n 1 | python3 -m json.tool --no-ensure-ascii - ``` - - Translated chat payloads match `text_field` set to `messages.*.content`, `output_mode` set to `both`, and `reconstruct_messages` set to `true` in `default.yaml`. - - ```{literalinclude} _snippets/output/translated.jsonl - :language: json - :class: scrollable - ``` - -1. Optional: Print the merged configuration without running the stage. - - Pass `--dry-run` or `-d` so Curator does not execute the pipeline. - - ```console - $ export RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 - - $ uv run --no-sync nemotron steps run translate/nemo_curator -d -c default \ - input_path=./train_sample.jsonl \ - output_dir=./output/translation-getting-started \ - source_language=en \ - target_language=hi \ - server.model=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning - ``` - -## Next Steps - -- Deeper behavior of FAITH in this pipeline: {doc}`explanation/faith-evaluation` -- Backend tuning: {doc}`how-to/run-llm-translation` -- Field wiring and `output_mode`: {doc}`how-to/configure-fields-and-output` -- FAITH thresholds and filtering: {doc}`how-to/run-faith-evaluation` -- CLI flags and overrides: {doc}`reference/cli-translation` diff --git a/docs/translation/how-to/configure-fields-and-output.md b/docs/translation/how-to/configure-fields-and-output.md deleted file mode 100644 index 437d10d6b..000000000 --- a/docs/translation/how-to/configure-fields-and-output.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Configure text_field, output_mode, reconstruct_messages, and writer formats." -topics: ["Translation", "Configuration"] -tags: ["How-To", "Translation"] -content: - type: "How-To" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] ---- - -# Configure Fields and Output - -Use this guide when you need to align `text_field`, `output_mode`, reconstruction flags, and formats with your dataset schema before or after a first run. - -For a guided first invocation, see {doc}`../getting-started`. - -## Choosing `text_field` - -- Chat corpora in OpenAI layout typically use `messages.*.content` so every message `content` entry is translated consistently. -- Plain documents might use a single column such as `article_body`. Omit wildcards when the schema is flat. - -## Outputs - -| YAML key | Behavior | -|----------|----------| -| `output_field` / `translation_column` | Control column names used when emitting translated strings. The default is `translated_text`. | -| `output_mode` | `replaced` overwrites source strings, `raw` preserves originals plus metadata, and `both` keeps audit trails. The starter default is `both`. | -| `merge_scores` | Keeps FAITH outputs adjacent to translations when scoring runs. | -| `reconstruct_messages`, `messages_field`, `messages_content_field` | Enable faithful reconstructions of chat arrays. These default to `true` for standard `messages` and `content` layouts. | - -## Formats - -Set `input_format` when automatic probing cannot distinguish ambiguous globs. Align `output_format` with downstream packing expectations; values are `jsonl` or `parquet`. - -## CLI Overrides - -You can override any YAML key with dotlists: - -```bash -uv run nemotron steps run translate/nemo_curator -c default \ - text_field=messages.*.content \ - output_mode=both \ - reconstruct_messages=true \ - input_path=/path/to/chat.jsonl \ - output_dir=/path/to/out \ - source_language=en \ - target_language=fr -``` - -## Related Pages - -- Schema patterns: {doc}`../reference/io-format` -- Segmentation interactions: {doc}`use-fine-segmentation` diff --git a/docs/translation/how-to/index.md b/docs/translation/how-to/index.md deleted file mode 100644 index 7c8680653..000000000 --- a/docs/translation/how-to/index.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Task guides for nemotron steps run translate/nemo_curator backends and configuration." -topics: ["Translation", "How-To"] -tags: ["How-To", "Translation"] -content: - type: "How-To" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] ---- - -# How-To Guides - -This section has task-focused procedures for changing backends, wiring fields, tuning segmentation, and adjusting FAITH. - -For copy-paste prompts and habits when you work with a coding agent, read {doc}`../using-skills` first. -Start with {doc}`../getting-started` if you have not run the step yet. - -```{toctree} -:maxdepth: 1 -:hidden: - -run-llm-translation -run-nmt-translation -run-google-aws-translation -configure-fields-and-output -use-fine-segmentation -run-faith-evaluation -``` - -Focused procedures for `nemotron steps run translate/nemo_curator`. - -## Run Translation - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`cpu;1.5em;sd-mr-1` LLM backend -:link: run-llm-translation -:link-type: doc -OpenAI-compatible servers, hosted or on-prem. -+++ -{bdg-secondary}`backend=llm` -::: - -:::{grid-item-card} {octicon}`server;1.5em;sd-mr-1` NMT HTTP service -:link: run-nmt-translation -:link-type: doc -Self-hosted `POST /translate` microservices. -+++ -{bdg-secondary}`backend=nmt` -::: - -:::{grid-item-card} {octicon}`cloud;1.5em;sd-mr-1` Google or AWS -:link: run-google-aws-translation -:link-type: doc -Managed cloud translation APIs. -+++ -{bdg-secondary}`backend=google|aws` -::: - -:::: - -## Configure and Tune - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`file-directory;1.5em;sd-mr-1` Fields and outputs -:link: configure-fields-and-output -:link-type: doc -Wildcards, `output_mode`, chat reconstruction. -+++ -{bdg-secondary}`schema` -::: - -:::{grid-item-card} {octicon}`package;1.5em;sd-mr-1` Segmentation -:link: use-fine-segmentation -:link-type: doc -Switch `segmentation_mode` deliberately. -+++ -{bdg-secondary}`segmentation` -::: - -:::: - -## FAITH Quality Gates - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`checklist;1.5em;sd-mr-1` FAITH evaluation -:link: run-faith-evaluation -:link-type: doc -Thresholds, filtering, model overrides. -+++ -{bdg-secondary}`faith` -::: - -:::: - -```{mermaid} -graph LR - A[Prepare YAML + env] --> B[nemotron steps run translate/nemo_curator] - B --> C{Need FAITH?} - C -->|yes| D[Tune faith_eval] - C -->|no| E[Disable faith_eval] - D --> B - E --> B -``` diff --git a/docs/translation/how-to/run-faith-evaluation.md b/docs/translation/how-to/run-faith-evaluation.md deleted file mode 100644 index 0ffeb085c..000000000 --- a/docs/translation/how-to/run-faith-evaluation.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Tune faith_eval inside nemotron steps run translate/nemo_curator runs." -topics: ["Translation", "FAITH"] -tags: ["How-To", "Translation"] -content: - type: "How-To" - difficulty: "Intermediate" - audience: ["ML Engineer", "Data Scientist"] ---- - -# Run FAITH Evaluation - -Use this guide when you need to tune thresholds, filtering, or scorer models for FAITH inside `nemotron steps run translate/nemo_curator` without a separate evaluation command. - -FAITH runs inside `TranslationStage` whenever `faith_eval.enabled` is `true`. The `default.yaml` starter profile ships with FAITH enabled. For how FAITH couples to non-LLM backends, see {doc}`../explanation/faith-evaluation`. - -## Essential Knobs - -| YAML path | Purpose | -|-----------|---------| -| `faith_eval.enabled` | Master toggle. Set `false` when you only need raw translation. | -| `faith_eval.threshold` | Average score floor. Rows failing the threshold are dropped when `filter_enabled` is `true`. | -| `faith_eval.filter_enabled` | Enables or disables removing low-scoring rows. | -| `faith_eval.model_name` | Overrides `server.model` for scoring-only workloads. | -| `faith_eval.generation_config` | Optional OpenAI-compatible generation settings for the FAITH scorer. | -| `faith_eval.max_concurrent_requests` | Optional scorer-side concurrency limit. | - -## LLM Credentials - -FAITH always requires the OpenAI-compatible `server` configuration. Set `NVIDIA_API_KEY` first, for example by replacing `` below. - -```bash -export NVIDIA_API_KEY="" -uv run nemotron steps run translate/nemo_curator -c default \ - faith_eval.enabled=true \ - faith_eval.threshold=3.0 \ - faith_eval.filter_enabled=true \ - server.model=YOUR_LLM_MODEL_ID \ - input_path=/path/to/chat.jsonl \ - output_dir=/path/to/out \ - source_language=en \ - target_language=hi -``` - -FAITH scoring is part of Curator's translation stage and is aligned to the translated segments produced by the stage. There is no separate `faith_eval.segment_level` switch in this Nemotron config. - -## Disable FAITH Temporarily - -```bash -uv run nemotron steps run translate/nemo_curator -c default \ - faith_eval.enabled=false \ - input_path=/path/to/chat.jsonl \ - output_dir=/path/to/out \ - source_language=en \ - target_language=hi \ - server.model=YOUR_LLM_MODEL_ID -``` - -Even with FAITH off, `backend=llm` still needs `server.model` for translation itself. - -## Related Pages - -- Concept primer: {doc}`../explanation/faith-evaluation` -- Full YAML reference: {doc}`../reference/translate-config` diff --git a/docs/translation/index.md b/docs/translation/index.md deleted file mode 100644 index 90f3c9e75..000000000 --- a/docs/translation/index.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Translate JSON Lines or Parquet corpora with nemotron steps run translate/nemo_curator, NeMo Curator backends, and optional FAITH scoring." -topics: ["Translation", "FAITH", "NeMo Curator"] -tags: ["Translation", "Documentation"] -content: - type: "Explanation" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] ---- - -(translation-index)= -# Translation With Nemotron - -The `nemotron steps run translate/nemo_curator` command translates selected fields in JSONL or Apache Parquet files. -You can use a large language model (LLM) with an OpenAI-compatible endpoint, a neural machine translation (NMT) HTTP server, Google Cloud Translation, or Amazon Translate. -Optionally, you can also run *FAITH* evaluation with an LLM after translation to score translation quality. - -:::{tip} -New here? Read {doc}`using-skills` if you plan to drive the work from a coding agent, then start {doc}`getting-started` and use this page as the map to deeper topics. -::: - -## When to Use - -Use `nemotron steps run translate/nemo_curator` when you need: - -- Localized training or synthetic corpora from translating natural-language fields while preserving structured payloads such as chat turns, tool payloads, and fenced code blocks. - Field paths, `output_mode`, and segmentation interact with that behavior; see {doc}`how-to/configure-fields-and-output` and {doc}`explanation/segmentation`. -- Optional FAITH evaluation with configurable thresholds and filtering, without a separate evaluation CLI. -- Repeatable configuration by using the checked-in `default.yaml` plus CLI overrides. - -## Pipeline Summary - -```{mermaid} -flowchart LR - A[Input JSONL or Parquet] --> B[Curator reader] - B --> C[TranslationStage] - C --> D[Curator writer] - D --> E[Output shards under output_dir] - C --> F{FAITH enabled?} - F -->|yes| G[LLM scores segments] - F -->|no| E - G --> E -``` - -## Documentation Series - -::::{grid} 1 2 2 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`book;1.5em;sd-mr-1` Tutorial -:link: getting-started -:link-type: doc -Run `nemotron steps run translate/nemo_curator` end-to-end using `default.yaml` and a sample chat JSONL file. -+++ -{bdg-secondary}`hands-on` -::: - -:::{grid-item-card} {octicon}`comment-discussion;1.5em;sd-mr-1` Use translation with an agent -:link: using-skills -:link-type: doc -Copy-paste session prompts for supervised fine-tuning (SFT) data or exploratory FAITH scoring, plus habits for a short chat. -+++ -{bdg-secondary}`newcomer` -::: - -:::{grid-item-card} {octicon}`tools;1.5em;sd-mr-1` How-to guides -:link: how-to/index -:link-type: doc -Backends, fields and outputs, segmentation, FAITH tuning. -+++ -{bdg-secondary}`task-based` -::: - -:::{grid-item-card} {octicon}`light-bulb;1.5em;sd-mr-1` Concepts -:link: explanation/index -:link-type: doc -Pipeline architecture, segmentation, FAITH behavior. -+++ -{bdg-secondary}`learn` -::: - -:::{grid-item-card} {octicon}`list-unordered;1.5em;sd-mr-1` Reference -:link: reference/index -:link-type: doc -YAML parameters and `nemotron steps run translate/nemo_curator` CLI. -+++ -{bdg-secondary}`lookup` -::: - -:::: - -## All Documentation - -````{tab-set} - -```{tab-item} Tutorial - -| Guide | What you do | -|-------|-------------| -| {doc}`using-skills` | Paste starter prompts for an agent and keep a translation session on the rails | -| {doc}`getting-started` | Run translation and FAITH using `default.yaml` and sample JSONL | - -``` - -```{tab-item} How-to guides - -| Guide | Focus | -|-------|-------| -| {doc}`how-to/run-llm-translation` | `backend: llm` | -| {doc}`how-to/run-nmt-translation` | `backend: nmt` | -| {doc}`how-to/run-google-aws-translation` | `backend: google` / `aws` | -| {doc}`how-to/configure-fields-and-output` | Field paths and `output_mode` | -| {doc}`how-to/use-fine-segmentation` | `segmentation_mode` | -| {doc}`how-to/run-faith-evaluation` | `faith_eval` block | - -``` - -```{tab-item} Concepts - -| Guide | Topic | -|-------|-------| -| {doc}`explanation/pipeline-overview` | End-to-end flow | -| {doc}`explanation/segmentation` | Coarse versus fine | -| {doc}`explanation/faith-evaluation` | FAITH semantics | - -``` - -```{tab-item} Reference - -| Guide | Content | -|-------|---------| -| {doc}`reference/translate-config` | `default.yaml` field reference | -| {doc}`reference/cli-translation` | `nemotron steps run translate/nemo_curator` syntax | -| {doc}`reference/io-format` | Input and output shapes | - -``` - -```` - -## Limitations and Considerations - -- Cost and rate limits: Hosted and cloud LLM backends incur usage; throttle with `max_concurrent_requests` and your provider’s guidance. -- Remote execution: use `--run ` or `--batch ` with an environment profile such as `lepton_translate`. -- Overrides: Use `key=value` dotlist syntax after global flags, not passthrough script arguments. -- Mixed folders: Do not point `input_path` at one directory that contains both `.jsonl` and `.parquet` shards unless you split formats first. - -## Quick Paths - -1. Agent-first prompts: {doc}`using-skills` -2. First run: {doc}`getting-started` -3. Swap backend: {doc}`how-to/index` -4. Lookup flags: {doc}`reference/cli-translation` diff --git a/docs/translation/reference/cli-translation.md b/docs/translation/reference/cli-translation.md deleted file mode 100644 index 286d96173..000000000 --- a/docs/translation/reference/cli-translation.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "CLI reference for nemotron steps run translate/nemo_curator." -topics: ["Translation", "CLI"] -tags: ["Reference", "CLI"] -content: - type: "Reference" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] ---- - -# CLI Reference for Translation - -Syntax, global flags, and merge rules for `nemotron steps run translate/nemo_curator`. Pair this page with {doc}`translate-config` for YAML field meanings. - -## Synopsis - -```bash -uv run nemotron steps run translate/nemo_curator [GLOBAL OPTIONS] [-c CONFIG] [DOTLIST_OVERRIDES...] -``` - -## Global Options - -These flags mirror other Nemotron commands: - -| Flag | Purpose | -|------|---------| -| `-c NAME`, `--config NAME` | Select `NAME.yaml` inside `src/nemotron/steps/translate/nemo_curator/config/` or pass an explicit `*.yaml` path. | -| `-d`, `--dry-run` | Print the merged OmegaConf YAML without executing `TranslationStage`. | -| `-r`, `--run PROFILE` | Run attached through an environment profile such as `lepton_translate` or a Slurm profile. | -| `-b`, `--batch PROFILE` | Submit detached through an environment profile such as `lepton_translate` or a Slurm profile. | - -Invocation without `-c` loads `default` automatically through `parse_config`. - -For local Curator execution through `uv run`, set: - -```bash -export RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 -``` - -This keeps Ray workers on the synchronized project environment instead of -letting Ray ask uv to create a separate worker environment. - -## Dotlist Overrides - -Anything after the global flags that matches `key=value` merges into the YAML dictionary loaded from `default.yaml`. Nested keys use dotted paths: - -```bash -uv run nemotron steps run translate/nemo_curator -c default \ - faith_eval.threshold=3.1 \ - server.model=YOUR_MODEL \ - input_path=/data/text.jsonl \ - output_dir=/data/translated \ - source_language=en \ - target_language=ar -``` - -## Restrictions Specific to Translation - -- Passthrough arguments are not supported. -- For remote execution, use a normal Nemotron env profile with `-r` or `-b`, such as `lepton_translate`. - -## Artifact Overrides - -The current translation step reads `input_path` directly from YAML and dotlist overrides. - -## Exit Codes - -| Code | Meaning | -|------|---------| -| `0` | Dry-run printed or translation finished successfully. | -| `1` | Validation failures such as missing languages, illegal backend configuration, unsupported CLI mode, or missing API keys. | - -## Related Pages - -- YAML keys: {doc}`translate-config` -- Tutorial invocation: {doc}`../getting-started` diff --git a/docs/translation/reference/index.md b/docs/translation/reference/index.md deleted file mode 100644 index 9c407fdfa..000000000 --- a/docs/translation/reference/index.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Reference index for nemotron steps run translate/nemo_curator YAML, CLI, and input and output shapes." -topics: ["Translation", "Reference"] -tags: ["Reference", "Translation"] -content: - type: "Reference" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] ---- - -# Reference for Translation - -Lookup pages for YAML keys, CLI flags, and file shapes. Prefer the tutorial and how-to guides for procedures; use this section when you need exact parameters or syntax. - -```{toctree} -:maxdepth: 1 -:hidden: - -translate-config -cli-translation -io-format -troubleshooting -``` - -Specifications for `nemotron steps run translate/nemo_curator`. - -::::{grid} 1 1 1 2 -:gutter: 1 1 1 2 - -:::{grid-item-card} {octicon}`gear;1.5em;sd-mr-1` Translation YAML -:link: translate-config -:link-type: doc -Anchored on `config/default.yaml` plus FAITH semantics. -+++ -{bdg-secondary}`yaml` -::: - -:::{grid-item-card} {octicon}`terminal;1.5em;sd-mr-1` CLI syntax -:link: cli-translation -:link-type: doc -Global recipe flags and translation-specific constraints. -+++ -{bdg-secondary}`cli` -::: - -:::{grid-item-card} {octicon}`file-code;1.5em;sd-mr-1` I/O format -:link: io-format -:link-type: doc -How `input_path` layouts map to `output_dir` shards. -+++ -{bdg-secondary}`jsonl` -::: - -:::: diff --git a/docs/translation/reference/translate-config.md b/docs/translation/reference/translate-config.md deleted file mode 100644 index 77a348390..000000000 --- a/docs/translation/reference/translate-config.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "YAML reference for translate/nemo_curator aligned with config/default.yaml." -topics: ["Translation", "Configuration"] -tags: ["Reference", "YAML"] -content: - type: "Reference" - difficulty: "Intermediate" - audience: ["ML Engineer", "Data Scientist"] ---- - -# Translation YAML Reference - -The `translate/nemo_curator` step ships `src/nemotron/steps/translate/nemo_curator/config/default.yaml` as the canonical starter profile. This page lists top-level keys you can override with `nemotron steps run translate/nemo_curator key=value` dotlists, grouped by concern, with the full baseline file inlined below. - -## Default Configuration File - -```{literalinclude} ../../../src/nemotron/steps/translate/nemo_curator/config/default.yaml -:language: yaml -:class: scrollable -``` - -## Keys Grouped by Concern - -### Paths and Formats - -| Key | Description | -|-----|-------------| -| `input_path` | File, glob, or homogeneous directory consumed by `JsonlReader` or `ParquetReader`. | -| `output_dir` | Directory passed to `JsonlWriter` or `ParquetWriter` in overwrite mode. | -| `input_format` | `auto`, `jsonl`, or `parquet`. | -| `output_format` | `jsonl` or `parquet`. | - -### Languages and Backend - -| Key | Description | -|-----|-------------| -| `source_language` / `target_language` | Required ISO 639-1 codes. Empty placeholders remind operators to set values explicitly. | -| `backend` | `llm`, `nmt`, `google`, or `aws`. | - -### Translation Semantics - -| Key | Description | -|-----|-------------| -| `text_field` | Dot or wildcard path describing strings to translate. The default is `messages.*.content`. | -| `output_field`, `translation_column` | Destination columns for translated text and downstream merges. | -| `output_mode` | `replaced`, `raw`, or `both`. | -| `merge_scores` | Attach FAITH outputs adjacent to translations when enabled. | -| `reconstruct_messages`, `messages_field`, `messages_content_field` | Chat reconstruction switches. | -| `segmentation_mode`, `min_segment_chars` | Segmenter behavior. Values include `coarse` and `fine`. | -| `max_concurrent_requests`, `skip_translated`, `files_per_partition`, `blocksize` | Throughput and partitioning controls surfaced to Curator readers and clients. | - -### LLM Fields - -Used whenever `backend=llm` or FAITH needs an OpenAI-compatible judge. - -| Key | Description | -|-----|-------------| -| `server.url` | Chat-completions compatible base URL. | -| `server.model` | Model identifier. Required for `llm` translation and for FAITH unless you override the scorer model. | -| `server.api_key_env` | Environment variable housing the API secret. The default is `NVIDIA_API_KEY`. | -| `server.api_key` | Inline secret. Discouraged for shared repositories. | - -### FAITH Evaluation - -| Key | Description | -|-----|-------------| -| `enabled` | Turns FAITH scoring on. The starter YAML sets this to `true`. | -| `threshold` | Minimum acceptable `faith_avg` on a one-to-five scale. The starter default `2.5` is a permissive noisy-data floor. See {doc}`../explanation/faith-evaluation` for the full rubric. | -| `model_name` | Optional scorer-only model. Defaults to `server.model`. | -| `filter_enabled` | Drop failing rows when `true`. | -| `max_concurrent_requests` | Optional scorer-side concurrency limit. | -| `generation_config` | Optional OpenAI-compatible generation settings for the scorer. | - -### Backend-Specific Blocks - -| Block | When needed | -|-------|-------------| -| `nmt` | HTTP microservice URL, batching, timeouts. | -| `google` | Project metadata and API version. Version `v3` requires `project_id`. | -| `aws` | Region plus concurrency limits. | - -## Overrides - -OmegaConf dotlists merge last: - -```bash -uv run nemotron steps run translate/nemo_curator -c default \ - backend=nmt \ - nmt.server_url=http://localhost:5000 \ - faith_eval.enabled=false \ - input_path=/data/chat.jsonl \ - output_dir=/data/out \ - source_language=en \ - target_language=hi -``` - -## Related Pages - -- CLI merge rules and flags: {doc}`cli-translation` -- Record shapes and writers: {doc}`io-format` diff --git a/docs/translation/reference/troubleshooting.md b/docs/translation/reference/troubleshooting.md deleted file mode 100644 index 93a2350f7..000000000 --- a/docs/translation/reference/troubleshooting.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -license: Apache-2.0 -copyright: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -description: "Symptom-to-remedy tables for nemotron steps run translate/nemo_curator across the LLM, NMT, Google, and AWS backends." -topics: ["Translation", "Reference"] -tags: ["Reference", "Translation", "Troubleshooting"] -content: - type: "Reference" - difficulty: "Beginner" - audience: ["ML Engineer", "Data Scientist"] ---- - - - -# Troubleshooting - -This page lists common symptoms when you run `nemotron steps run translate/nemo_curator` and shows the field, flag, or environment variable to inspect first. -Each table pairs a symptom with a concrete remedy. -For stage flow and design rationale, see the explanation pages linked from {doc}`../explanation/index`. - -## Authentication and Credentials - -| Symptom | What to do | -| --- | --- | -| HTTP 401 or 403 from the chat-completions endpoint, or a Curator log line about a missing API key | Confirm the variable named in `server.api_key_env` is exported in the shell that launches the run. The starter `default.yaml` expects `NVIDIA_API_KEY`; export it with `export NVIDIA_API_KEY=""` and rerun. See {doc}`../how-to/run-llm-translation`. | -| FAITH scoring fails with a credentials error even though `backend` is `nmt`, `google`, or `aws` | FAITH always uses the large language model (LLM) client under `server`. Keep `server.api_key_env` populated whenever `faith_eval.enabled` is `true`, or set `faith_eval.enabled=false` for a diagnostic run. See {doc}`../how-to/run-faith-evaluation`. | -| Google backend rejects the request with a permission or project error | Confirm application default credentials are present in the environment that runs the step. Do not paste secrets into `default.yaml`. See {doc}`../how-to/run-google-aws-translation`. | - -## Model and Endpoint Configuration - -| Symptom | What to do | -| --- | --- | -| HTTP 404 or a "model not found" message from the LLM endpoint | Hosted catalogs retire identifiers frequently. List the models your tenant currently exposes and pin `server.model` to one of them before large batch jobs. See {doc}`../how-to/run-llm-translation`. | -| Google translation rejects the request because `project_id` is missing | API version `v3` requires project metadata. Set both `google.project_id` and `google.api_version=v3`, or downgrade `google.api_version` to a release that does not require the project. See {doc}`../how-to/run-google-aws-translation`. | -| NMT requests time out before the service responds | Raise `nmt.timeout` to match observed server latency, lower `nmt.batch_size` so each request returns sooner, and confirm `nmt.server_url` resolves from the host that runs the step. See {doc}`../how-to/run-nmt-translation`. | - -## Throttling and Concurrency - -| Symptom | What to do | -| --- | --- | -| HTTP 429 responses, bursty failures, or sustained slowdowns from a hosted LLM endpoint | Lower `max_concurrent_requests` in your YAML and rerun on a smaller slice of data. Confirm your tenant quota covers the planned batch size. See {doc}`translate-config`. | -| A self-hosted NMT service returns errors under load | Reduce `nmt.max_concurrent_requests` and `nmt.batch_size` together, then raise them only after the service reports healthy throughput. See {doc}`../how-to/run-nmt-translation`. | - -## Inputs and Output Layout - -| Symptom | What to do | -| --- | --- | -| Reader errors about mixed file types when `input_path` points at a directory containing both JSONL and Parquet files | Curator readers expect one record format per directory. Split the inputs into separate directories for JSON Lines (JSONL) and Parquet, or set `input_path` to a single file. See {doc}`io-format`. | -| Ray worker logs show `Creating virtual environment at: .venv` followed by `ModuleNotFoundError: No module named 'ray'` | Export `RAY_ENABLE_UV_RUN_RUNTIME_ENV=0` before running local `uv run --no-sync nemotron steps run translate/nemo_curator ...`. This keeps Ray workers in the synchronized Nemotron environment. | -| Empty JSONL input fails with `No data read from files in task file_group_0` | The reader found no records. Treat the run as an empty-input validation failure, confirm the input path is correct, and rerun with a non-empty file or directory. | -| Output shards do not appear under `output_dir` after the run reports success | The writer emits partitioned files, not a single merged file. Inspect the shard pattern under `output_dir` and confirm `output_format` matches what downstream consumers expect. See {doc}`io-format`. | - -## FAITH Evaluation - -| Symptom | What to do | -| --- | --- | -| Every translated row is dropped after FAITH runs | The `faith_eval.threshold` value may be too strict for the chosen scorer model. Lower the threshold, set `faith_eval.filter_enabled=false` while you tune, or override the scorer with `faith_eval.model_name`. See {doc}`../how-to/run-faith-evaluation`. | -| FAITH scores look inconsistent across runs of the same data | Pin both `server.model` and `faith_eval.model_name` to specific identifiers so scorer drift does not move the threshold under you. See {doc}`../explanation/faith-evaluation`. | - -## Related Reference - -- Translation YAML fields: {doc}`translate-config` -- CLI syntax: {doc}`cli-translation` -- Input and output shapes: {doc}`io-format` diff --git a/docs/versions1.json b/docs/versions1.json deleted file mode 100644 index 446491702..000000000 --- a/docs/versions1.json +++ /dev/null @@ -1,12 +0,0 @@ -[ - { - "version": "nightly", - "url": "https://docs.nvidia.com/nemotron/nightly/" - }, - { - "name": "0.1.0 (latest)", - "version": "0.1.0", - "url": "https://docs.nvidia.com/nemotron/latest/", - "preferred": true - } -]