> This page is for version Latest.
> 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.step5.state_dict_adapter

Step-5 FP8 loading, interleaved QKV mapping and native expert conversion.

## Module Contents

### Classes

| Name                                                                                                        | Description                                                               |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [`Step5StateDictAdapter`](#nemo_automodel-components-models-step5-state_dict_adapter-Step5StateDictAdapter) | Preserve Step-family expert conversion and add Step-5 attention mappings. |

### Data

[`_DECODER_LAYER`](#nemo_automodel-components-models-step5-state_dict_adapter-_DECODER_LAYER)

[`_INDEXER_NAMES`](#nemo_automodel-components-models-step5-state_dict_adapter-_INDEXER_NAMES)

### API

```python
class nemo_automodel.components.models.step5.state_dict_adapter.Step5StateDictAdapter(
    config: nemo_automodel.components.models.step5.configuration.Step5Config,
    moe_config: nemo_automodel.components.moe.config.MoEConfig,
    backend: nemo_automodel.components.models.common.BackendConfig,
    dtype: torch.dtype
)
```

**Bases:** [Step3p5StateDictAdapter](/nemo-automodel/nemo_automodel/components/models/step3p5/state_dict_adapter#nemo_automodel-components-models-step3p5-state_dict_adapter-Step3p5StateDictAdapter)

Preserve Step-family expert conversion and add Step-5 attention mappings.

Loading needs bounded per-projection conversion storage, so the adapter does
not advertise the DCP direct-destination fast path.

**`_load_fp8_experts`** `= quantization is not None`

---

**`_unquantized_expert_modules`** `= frozenset(excluded)`

---

```python
nemo_automodel.components.models.step5.state_dict_adapter.Step5StateDictAdapter._iter_checkpoint_load_parts(
    model_state_dict: dict[str, torch.Tensor],
    device_mesh: torch.distributed.device_mesh.DeviceMesh | None = None
) -> collections.abc.Iterator[nemo_automodel.components.checkpoint.state_dict_adapter.CheckpointLoadPart]
```

Load mixed FP8/BF16 expert projections into final BF16 storage.

**Parameters:**

**`model_state_dict`** `dict[str, torch.Tensor]`

Final native storage: fused gate/up tensors
\[experts, hidden, 2 \* intermediate], down tensors
\[experts, intermediate, hidden], and other native model tensors.
DTensors shard experts over ep and input dimensions over ep_shard.

---

**`device_mesh`** `DeviceMesh | None` — default: None

Optional expert mesh used for native/HF conversion.

---

```python
nemo_automodel.components.models.step5.state_dict_adapter.Step5StateDictAdapter.convert_single_tensor_to_hf(
    fqn: str,
    tensor: torch.Tensor,
    exclude_key_regex: str | None = None,
    quantization: bool = False,
    kwargs: nemo_automodel.components.models.step5.configuration.ConfigValue = {}
) -> list[tuple[str, torch.Tensor]]
```

Export native attention and expert tensors to checkpoint names.

**Parameters:**

**`fqn`** `str`

Native tensor name.

---

**`tensor`** `torch.Tensor`

Tensor with the native layout documented by from_hf.

---

**`exclude_key_regex`** `str | None` — default: None

Optional exported-name exclusion regex.

---

**`quantization`** `bool` — default: False

Whether quantized export is requested (unsupported).

---

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

Checkpointer options forwarded to the base adapter.

---

**Returns:** `list[tuple[str, torch.Tensor]]`

Named source tensors with \[out, in] projections or \[experts, out, in] experts.

```python
nemo_automodel.components.models.step5.state_dict_adapter.Step5StateDictAdapter.from_hf(
    hf_state_dict: dict[str, torch.Tensor],
    device_mesh: torch.distributed.device_mesh.DeviceMesh | None = None,
    kwargs: nemo_automodel.components.models.step5.configuration.ConfigValue = {}
) -> dict[str, torch.Tensor]
```

Load source tensors into trainable, interleaved native storage.

**Parameters:**

**`hf_state_dict`** `dict[str, torch.Tensor]`

Mapping to source tensors. Experts have layout
\[experts, out, in]; Q/K/V have layout \[heads \* head_dim, hidden].

---

**`device_mesh`** `DeviceMesh | None` — default: None

Optional expert mesh handled by the Step-family adapter.

---

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

Checkpointer options forwarded to the base adapter.

---

**Returns:** `dict[str, torch.Tensor]`

Mapping to native tensors. QKV has layout

```python
nemo_automodel.components.models.step5.state_dict_adapter.Step5StateDictAdapter.iter_checkpoint_load_parts(
    model_state_dict: dict[str, torch.Tensor],
    device_mesh: torch.distributed.device_mesh.DeviceMesh | None = None
) -> collections.abc.Iterator[nemo_automodel.components.checkpoint.state_dict_adapter.CheckpointLoadPart] | None
```

Load in bounded parts unless this rank holds only part of the decoder.

Every rank issues one load collective per part. Pipeline stages own
different decoder layers, so their part counts differ; such ranks use
the ordinary checkpoint load instead.

**Parameters:**

**`model_state_dict`** `dict[str, torch.Tensor]`

Final native storage; see `_iter_checkpoint_load_parts`.

---

**`device_mesh`** `DeviceMesh | None` — default: None

Optional expert mesh used for native/HF conversion.

---

**Returns:** `Iterator[CheckpointLoadPart] | None`

Checkpoint load parts, or `None` on a distributed rank whose state

```python
nemo_automodel.components.models.step5.state_dict_adapter._DECODER_LAYER = re.compile('^model\\.layers\\.(\\d+)\\.')
```

```python
nemo_automodel.components.models.step5.state_dict_adapter._INDEXER_NAMES = {'sparse_indexer_q': 'indexer.q_proj', 'sparse_indexer_k': 'indexer.k_proj', 'sp...
```