# nvidia-nemo/megatron-bridge architecture

> Architecture diagram of the GitHub repository nvidia-nemo/megatron-bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia-nemo/megatron-bridge
- Repository: https://github.com/nvidia-nemo/megatron-bridge

## Overview

NeMo Megatron Bridge is a model-development library for converting model checkpoints and configuring large-scale LLM, multimodal, and diffusion workloads. The principal user workflow is to bring a Hugging Face model into Megatron-compatible form, configure and train or fine-tune it, then save or convert checkpoints for inference. The graph also preserves inference, data preparation, PEFT, and diffusion as distinct capabilities. Most runtime relationships are not exposed in the excerpts, so edges are limited to documented capabilities or indexed source references; unsampled implementation links are omitted.

Main entry points: [`src/megatron/bridge/models/conversion/auto_bridge.py`](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/conversion/auto_bridge.py) (AutoBridge), [`src/megatron/bridge/training/model_load_save.py`](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/training/model_load_save.py) (Model load and save), [`src/megatron/bridge/models/model_provider.py`](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/model_provider.py) (Model providers), [`src/megatron/bridge/training/config.py`](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/training/config.py) (Training configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversion["Model conversion"]
  node_auto_bridge["AutoBridge<br/>[auto_bridge.py]"]
  node_model_bridge["Model bridge<br/>[model_bridge.py]"]
  node_param_mapping["Parameter mapping<br/>[param_mapping.py]"]
  node_mapping_registry["Mapping registry"]
  node_hf_state["HF checkpoint state<br/>[state.py]"]
  node_peft_bridge["PEFT conversion<br/>[peft_bridge.py]"]
  node_mimo_conversion["MiMo conversion<br/>[orchestrator.py]"]
end

subgraph group_training["Training and data"]
  node_model_provider["Model providers<br/>[model_provider.py]"]
  node_gpt_provider["GPT provider<br/>[gpt_provider.py]"]
  node_data_pipeline["Training data"]
  node_training_config["Training configuration<br/>[config.py]"]
  node_model_load_save["Model load and save<br/>[model_load_save.py]"]
  node_checkpointing["Checkpointing<br/>[checkpointing.py]"]
  node_train_launcher["Training launcher<br/>[run_recipe.py]"]
end

subgraph group_inference["Inference"]
  node_text_inference["Text generation<br/>[text_generation.py]"]
  node_vlm_controller["VLM controller"]
  node_vlm_engine["VLM engine<br/>[vlm_engine.py]"]
  node_inference_cli["Inference scripts"]
end

subgraph group_diffusion["Diffusion"]
  node_flow_training["Flow training"]
  node_flux_inference["FLUX inference"]
  node_wan_inference["WAN inference"]
  node_diffusion_recipes["Diffusion recipes"]
end

node_user(("Model engineer"))
node_external_hf(("Hugging Face"))

node_user -->|"convert models"| node_auto_bridge
node_external_hf -.->|"load checkpoint"| node_auto_bridge
node_auto_bridge -->|"uses bridge"| node_model_bridge
node_auto_bridge -->|"uses mappings"| node_param_mapping
node_auto_bridge -->|"loads state"| node_hf_state
node_mapping_registry -->|"registers mappings"| node_param_mapping
node_auto_bridge -->|"supports PEFT"| node_peft_bridge
node_user -->|"launch training"| node_train_launcher
node_train_launcher -.->|"configures run"| node_training_config
node_training_config -->|"loads model"| node_model_load_save
node_model_load_save -->|"uses checkpointing"| node_checkpointing
node_model_load_save -->|"builds model"| node_model_provider
node_model_provider -.->|"selects provider"| node_gpt_provider
node_user -->|"prepare data"| node_data_pipeline
node_user -->|"run inference"| node_inference_cli
node_inference_cli -.->|"serves text"| node_text_inference
node_vlm_engine -->|"schedules requests"| node_vlm_controller
node_vlm_controller -.->|"extends generation"| node_text_inference
node_user -->|"run diffusion"| node_diffusion_recipes
node_diffusion_recipes -.->|"configures training"| node_flow_training
node_user -.->|"generate images"| node_flux_inference
node_user -.->|"generate video"| node_wan_inference
node_mimo_conversion -->|"extends conversion"| node_auto_bridge

click node_auto_bridge "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/conversion/auto_bridge.py"
click node_model_bridge "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/conversion/model_bridge.py"
click node_param_mapping "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/conversion/param_mapping.py"
click node_mapping_registry "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/conversion/mapping_registry.py"
click node_hf_state "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/hf_pretrained/state.py"
click node_peft_bridge "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/conversion/peft_bridge.py"
click node_mimo_conversion "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/megatron_mimo/conversion/orchestrator.py"
click node_model_provider "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/model_provider.py"
click node_gpt_provider "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/gpt_provider.py"
click node_data_pipeline "https://github.com/nvidia-nemo/megatron-bridge/tree/main/src/megatron/bridge/data"
click node_training_config "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/training/config.py"
click node_model_load_save "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/training/model_load_save.py"
click node_checkpointing "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/training/checkpointing.py"
click node_train_launcher "https://github.com/nvidia-nemo/megatron-bridge/blob/main/scripts/training/run_recipe.py"
click node_text_inference "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/inference/text_generation.py"
click node_vlm_controller "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/inference/vlm/vlm_inference_controller.py"
click node_vlm_engine "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/inference/vlm/vlm_engine.py"
click node_inference_cli "https://github.com/nvidia-nemo/megatron-bridge/tree/main/scripts/inference"
click node_flow_training "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/diffusion/common/flow_matching/flow_matching_pipeline.py"
click node_flux_inference "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/diffusion/models/flux/flow_matching/flux_inference_pipeline.py"
click node_wan_inference "https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/diffusion/models/wan/flow_matching/flow_inference_pipeline.py"
click node_diffusion_recipes "https://github.com/nvidia-nemo/megatron-bridge/tree/main/src/megatron/bridge/diffusion/recipes"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auto_bridge,node_model_bridge,node_param_mapping,node_mapping_registry,node_hf_state,node_peft_bridge,node_mimo_conversion toneBlue
class node_model_provider,node_gpt_provider,node_data_pipeline,node_training_config,node_model_load_save,node_checkpointing,node_train_launcher toneAmber
class node_text_inference,node_vlm_controller,node_vlm_engine,node_inference_cli toneMint
class node_flow_training,node_flux_inference,node_wan_inference,node_diffusion_recipes toneRose
class node_user,node_external_hf toneIndigo
```

## Components

### Model conversion

- [AutoBridge](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/conversion/auto_bridge.py): `src/megatron/bridge/models/conversion/auto_bridge.py`
- [Model bridge](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/conversion/model_bridge.py): `src/megatron/bridge/models/conversion/model_bridge.py`
- [Parameter mapping](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/conversion/param_mapping.py): `src/megatron/bridge/models/conversion/param_mapping.py`
- [Mapping registry](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/conversion/mapping_registry.py): `src/megatron/bridge/models/conversion/mapping_registry.py`
- [HF checkpoint state](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/hf_pretrained/state.py): `src/megatron/bridge/models/hf_pretrained/state.py`
- [PEFT conversion](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/conversion/peft_bridge.py): `src/megatron/bridge/models/conversion/peft_bridge.py`
- [MiMo conversion](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/megatron_mimo/conversion/orchestrator.py): `src/megatron/bridge/models/megatron_mimo/conversion/orchestrator.py`

### Training and data

- [Model providers](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/model_provider.py): `src/megatron/bridge/models/model_provider.py`
- [GPT provider](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/models/gpt_provider.py): `src/megatron/bridge/models/gpt_provider.py`
- [Training data](https://github.com/nvidia-nemo/megatron-bridge/tree/main/src/megatron/bridge/data): `src/megatron/bridge/data`
- [Training configuration](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/training/config.py): `src/megatron/bridge/training/config.py`
- [Model load and save](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/training/model_load_save.py): `src/megatron/bridge/training/model_load_save.py`
- [Checkpointing](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/training/checkpointing.py): `src/megatron/bridge/training/checkpointing.py`
- [Training launcher](https://github.com/nvidia-nemo/megatron-bridge/blob/main/scripts/training/run_recipe.py): `scripts/training/run_recipe.py`

### Inference

- [Text generation](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/inference/text_generation.py): `src/megatron/bridge/inference/text_generation.py`
- [VLM controller](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/inference/vlm/vlm_inference_controller.py): `src/megatron/bridge/inference/vlm/vlm_inference_controller.py`
- [VLM engine](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/inference/vlm/vlm_engine.py): `src/megatron/bridge/inference/vlm/vlm_engine.py`
- [Inference scripts](https://github.com/nvidia-nemo/megatron-bridge/tree/main/scripts/inference): `scripts/inference`

### Diffusion

- [Flow training](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/diffusion/common/flow_matching/flow_matching_pipeline.py): `src/megatron/bridge/diffusion/common/flow_matching/flow_matching_pipeline.py`
- [FLUX inference](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/diffusion/models/flux/flow_matching/flux_inference_pipeline.py): `src/megatron/bridge/diffusion/models/flux/flow_matching/flux_inference_pipeline.py`
- [WAN inference](https://github.com/nvidia-nemo/megatron-bridge/blob/main/src/megatron/bridge/diffusion/models/wan/flow_matching/flow_inference_pipeline.py): `src/megatron/bridge/diffusion/models/wan/flow_matching/flow_inference_pipeline.py`
- [Diffusion recipes](https://github.com/nvidia-nemo/megatron-bridge/tree/main/src/megatron/bridge/diffusion/recipes): `src/megatron/bridge/diffusion/recipes`

### Other components

- **Model engineer**
- **Hugging Face**

## Connections

- Model engineer → AutoBridge: convert models
- Hugging Face → AutoBridge: load checkpoint
- AutoBridge → Model bridge: uses bridge (evidence: `src/megatron/bridge/models/conversion/auto_bridge.py`)
- AutoBridge → Parameter mapping: uses mappings (evidence: `src/megatron/bridge/models/conversion/auto_bridge.py`)
- AutoBridge → HF checkpoint state: loads state (evidence: `src/megatron/bridge/models/conversion/auto_bridge.py`)
- Mapping registry → Parameter mapping: registers mappings (evidence: `src/megatron/bridge/models/conversion/mapping_registry.py`)
- AutoBridge → PEFT conversion: supports PEFT (evidence: `src/megatron/bridge/models/conversion/auto_bridge.py`)
- Model engineer → Training launcher: launch training
- Training launcher → Training configuration: configures run
- Training configuration → Model load and save: loads model (evidence: `src/megatron/bridge/training/model_load_save.py`)
- Model load and save → Checkpointing: uses checkpointing (evidence: `src/megatron/bridge/training/model_load_save.py`)
- Model load and save → Model providers: builds model (evidence: `src/megatron/bridge/training/model_load_save.py`)
- Model providers → GPT provider: selects provider
- Model engineer → Training data: prepare data
- Model engineer → Inference scripts: run inference
- Inference scripts → Text generation: serves text
- VLM engine → VLM controller: schedules requests (evidence: `src/megatron/bridge/inference/vlm/vlm_engine.py`)
- VLM controller → Text generation: extends generation
- Model engineer → Diffusion recipes: run diffusion
- Diffusion recipes → Flow training: configures training
- Model engineer → FLUX inference: generate images
- Model engineer → WAN inference: generate video
- MiMo conversion → AutoBridge: extends conversion (evidence: `src/megatron/bridge/models/megatron_mimo/conversion/orchestrator.py`)
