mbridge

0.15.1 verified Mon Apr 27 auth: no python

A bridge library to convert and connect Megatron-Core checkpoints to Hugging Face format and support Reinforcement Learning workflows. Current version 0.15.1, with frequent releases matching Megatron-Core versions. Supports LLMs and VLMs including DeepSeek v3, GLM-4.5, Gemma 3, InternVL3.

pip install mbridge

Common errors

error ModuleNotFoundError: No module named 'mbridge' ↓

cause mbridge is not installed or installed in a different Python environment.

fix

Run pip install mbridge in the correct environment.

error ValueError: num_layers must be positive integer ↓

cause num_layers argument is missing or non-integer.

fix

Provide a positive integer for num_layers (e.g., 32 for Llama-7B).

Warnings

breaking From v0.15.0, `tie_embedding_weights` handling changed. Checkpoints converted with older versions may have mismatched embedding layers. ↓

fix Re-run conversion with v0.15.0+ and set `tie_word_embedding=True` if needed.

gotcha Tensor and pipeline parallelism settings must match the Megatron-Core training configuration. Mismatched settings can cause silent shape errors. ↓

fix Ensure `tensor_parallel` and `pipeline_parallel` are identical to the values used during training.

deprecated The `--model-parallel-size` argument has been deprecated in favor of `--tensor-model-parallel-size` and `--pipeline-model-parallel-size`. ↓

fix Use `tensor_parallel` and `pipeline_parallel` parameters in the BridgeConverter API.

Imports

BridgeConverter
wrong
```
import BridgeConverter
```
correct
```
from mbridge import BridgeConverter
```
BridgeConverter is not a top-level module; it must be imported from the mbridge package.
convert_checkpoint
wrong
```
from mbridge.utils import convert_checkpoint
```
correct
```
from mbridge import convert_checkpoint
```
convert_checkpoint is exposed at the top level, not under utils.

Quickstart

Basic usage of BridgeConverter to convert between Hugging Face and Megatron-Core formats.

from mbridge import BridgeConverter

converter = BridgeConverter(
    hf_model_path="path/to/hf/model",
    mc_model_path="/path/to/mcore/model",
    model_type="llama",
    num_layers=32,
    hidden_size=4096,
    num_attention_heads=32,
    tensor_parallel=1,
    pipeline_parallel=1
)
# Convert Hugging Face to Megatron-Core
converter.hf_to_mc()
# Convert Megatron-Core to Hugging Face
converter.mc_to_hf()