> This page is for version 0.5.0 · 26.06.
> For other versions, use one of these documentation indexes:
> - Nightly (default): https://docs.nvidia.com/nemo/automodel/nightly/llms.txt
> - Latest: https://docs.nvidia.com/nemo/automodel/latest/llms.txt
> - 0.5.0 · 26.06: https://docs.nvidia.com/nemo/automodel/v0.5/llms.txt
> - 0.4.0 · 26.04: https://docs.nvidia.com/nemo/automodel/v0.4/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/automodel/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/automodel/_mcp/server.

# nemo_automodel.components.models.qwen3_next.state_dict_adapter

## Module Contents

### Classes

| Name                                                                                                                     | Description                                                                      |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| [`Qwen3NextStateDictAdapter`](#nemo_automodel-components-models-qwen3_next-state_dict_adapter-Qwen3NextStateDictAdapter) | Converts between HF Qwen3Next checkpoints and our grouped-experts native format. |

### Data

[`logger`](#nemo_automodel-components-models-qwen3_next-state_dict_adapter-logger)

### API

```python
class nemo_automodel.components.models.qwen3_next.state_dict_adapter.Qwen3NextStateDictAdapter(
    config: typing.Any,
    moe_config: nemo_automodel.components.moe.config.MoEConfig,
    backend: nemo_automodel.components.models.common.BackendConfig,
    dtype: torch.dtype = torch.float32
)
```

**Bases:** [MoESplitExpertsStateDictMixin](/nemo-automodel/nemo_automodel/components/moe/state_dict_mixin#nemo_automodel-components-moe-state_dict_mixin-MoESplitExpertsStateDictMixin), [StateDictAdapter](/nemo-automodel/nemo_automodel/components/checkpoint/state_dict_adapter#nemo_automodel-components-checkpoint-state_dict_adapter-StateDictAdapter)

Converts between HF Qwen3Next checkpoints and our grouped-experts native format.

Qwen3Next HF experts use keys:
model.layers.\{L}.mlp.experts.\{E}.gate\_proj.weight
model.layers.\{L}.mlp.experts.\{E}.up\_proj.weight
model.layers.\{L}.mlp.experts.\{E}.down\_proj.weight

Our native format groups them into:
model.layers.\{L}.mlp.experts.gate\_and\_up\_projs  # \[n\_experts, dim, 2\*moe\_inter\_dim]
model.layers.\{L}.mlp.experts.down\_projs         # \[n\_experts, moe\_inter\_dim, dim]

Qwen3Next HF shared experts use keys:
model.layers.\{L}.mlp.shared\_expert.gate\_proj.weight
model.layers.\{L}.mlp.shared\_expert.up\_proj.weight
model.layers.\{L}.mlp.shared\_expert.down\_proj.weight

Our native format uses:
model.layers.\{L}.mlp.shared\_experts.gate\_proj.weight  # Note: plural "shared\_experts"
model.layers.\{L}.mlp.shared\_experts.up\_proj.weight
model.layers.\{L}.mlp.shared\_experts.down\_proj.weight

**`hf_to_internal_map`** `= {'.mlp.shared_expert.': '.mlp.shared_experts.'}`

---

**`internal_to_hf_map`**

---

```python
nemo_automodel.components.models.qwen3_next.state_dict_adapter.Qwen3NextStateDictAdapter._apply_key_mapping(
    state_dict: dict[str, typing.Any],
    mapping: dict[str, str]
) -> dict[str, typing.Any]
```

Apply key substring mappings to state dict keys.

**Parameters:**

**`state_dict`** `dict[str, Any]`

State dict to apply mappings to

---

**`mapping`** `dict[str, str]`

Dictionary mapping substrings to replace them with

---

**Returns:** `dict[str, Any]`

New state dict with mapped keys

```python
nemo_automodel.components.models.qwen3_next.state_dict_adapter.Qwen3NextStateDictAdapter.convert_single_tensor_to_hf(
    fqn: str,
    tensor: typing.Any,
    kwargs = {}
) -> list[tuple[str, typing.Any]]
```

Convert a single tensor from native format to HuggingFace format.

**Parameters:**

**`fqn`** `str`

Fully qualified name of the tensor in native format

---

**`tensor`** `Any`

The tensor to convert

---

**`**kwargs`** — default: \{}

Additional arguments for conversion

---

**Returns:** `list[tuple[str, Any]]`

List of (fqn, tensor) tuples in HuggingFace format

```python
nemo_automodel.components.models.qwen3_next.state_dict_adapter.Qwen3NextStateDictAdapter.forced_hf_dtype_mapping(
    state_dict: dict[str, typing.Any]
) -> dict[str, str]
```

Return HF export dtype overrides for intrinsically-fp32 GDN tensors.

```python
nemo_automodel.components.models.qwen3_next.state_dict_adapter.Qwen3NextStateDictAdapter.from_hf(
    hf_state_dict: dict[str, typing.Any],
    device_mesh: typing.Optional[torch.distributed.device_mesh.DeviceMesh] = None,
    kwargs = {}
) -> dict[str, typing.Any]
```

```python
nemo_automodel.components.models.qwen3_next.state_dict_adapter.Qwen3NextStateDictAdapter.to_hf(
    state_dict: dict[str, typing.Any],
    exclude_key_regex: str | None = None,
    quantization: bool = False,
    kwargs = {}
) -> dict[str, typing.Any]
```

```python
nemo_automodel.components.models.qwen3_next.state_dict_adapter.logger = logging.getLogger(__name__)
```