> 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_vl_moe.state_dict_adapter

## Module Contents

### Classes

| Name                                                                                                                         | Description                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`Qwen3VLMoeStateDictAdapter`](#nemo_automodel-components-models-qwen3_vl_moe-state_dict_adapter-Qwen3VLMoeStateDictAdapter) | Converts between HF Qwen3-VL-MoE checkpoints and grouped-experts native format. |

### API

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

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

Converts between HF Qwen3-VL-MoE checkpoints and grouped-experts native format.

HF checkpoint keys (already stacked, no .weight suffix):
model.language\_model.layers.\{L}.mlp.experts.gate\_up\_proj  \[n\_experts, dim, 2\*inter]
model.language\_model.layers.\{L}.mlp.experts.down\_proj     \[n\_experts, inter, dim]

Native format (identical shapes, different key names):
model.language\_model.layers.\{L}.mlp.experts.gate\_and\_up\_projs
model.language\_model.layers.\{L}.mlp.experts.down\_projs

Loading paths:
DCP path:  to\_hf renames native→HF, DCP loads into DTensors, from\_hf renames HF→native.
Tensors are DTensors throughout — just rename keys, no tensor ops.
Init path: from\_hf receives plain tensors from safetensors, slices to local EP
shard, and wraps in DTensor via create\_dtensor\_from\_local.

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

Rename a single native key to HF format. Tensor passed through as-is.

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

Rename HF keys to native keys.

DTensors (DCP path): just rename, no tensor ops.
Plain tensors (init path): slice to local EP shard, create DTensor.

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

Rename native keys to HF keys. Tensors passed through as-is (no comms).