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

State dict adapter for DeepSeek V4.1.

The released `deepseek-ai/DeepSeek-V4.1-Flash` safetensors follow the
reference inference module tree.  On-disk layout (from the shard headers):

* FP8 E4M3 projections with `float8_e8m0fnu` scales over **32x32** blocks
  (`attn.{wq_a,wq_b,wkv,wo_a,wo_b}`, `attn.indexer.wq_b`,
  `ffn.shared_experts.w{1,2,3}`, `engram.wkv`). Initialization uses this
  fixed 32-column layout rather than DeepSeek V4's 128x128 blocks.
* FP4 E2M1 routed experts packed two per `int8` with per-row / 32-column
  `e8m0` scales.
* Engram tables: FP8 E4M3 `[rows, 256]` with per-row / 32-column `e8m0`
  scales `[rows, 8]`.
* BF16 / FP32 for everything else (norms, gate, hyper-connection mixers,
  compressor, indexer keys, attention sink, embeddings, head).

Key mapping (HF -> internal):
embed.weight                           -> model.embed\_tokens.weight
norm.weight                            -> model.norm.weight
head.weight                            -> lm\_head.weight
layers.\{i}.attn\_norm.weight            -> model.layers.\{i}.attn\_norm.weight
layers.\{i}.ffn\_norm.weight             -> model.layers.\{i}.ffn\_norm.weight
layers.\{i}.attn.attn\_sink              -> model.layers.\{i}.attn.sinks\_param.weight
layers.\{i}.attn.\*                      -> model.layers.\{i}.attn.\*   (compressor.*, indexer.* keep their names)
layers.\{i}.ffn.gate.bias               -> model.layers.\{i}.ffn.gate.e\_score\_correction\_bias
layers.\{i}.ffn.gate.weight             -> model.layers.\{i}.ffn.gate.weight
layers.\{i}.ffn.shared\_experts.w1/w3/w2 -> model.layers.\{i}.ffn.shared\_experts.gate\_proj/up\_proj/down\_proj
layers.\{i}.ffn.experts.\{j}.w1/w3/w2    -> stacked into model.layers.\{i}.ffn.experts.gate\_and\_up\_projs / down\_projs
layers.\{i}.hc\_attn\_\{fn,base,scale}     -> model.layers.\{i}.attn\_hc.\{fn,base,scale}
layers.\{i}.hc\_ffn\_\{fn,base,scale}      -> model.layers.\{i}.ffn\_hc.\{fn,base,scale}
layers.\{i}.engram.\*                    -> model.layers.\{i}.engram.\*
layers.\{i}.ffn.gate.bias\_vl             -> model.layers.\{i}.ffn.gate.bias\_vl
vision.\* / aligner.\*                   -> model.vision.\* / model.aligner.\*
image\_\{start,end,newline}              -> model.image\_\{start,end,newline}

The `mtp.*` DSpark draft is excluded. Eager loading also excludes layers
beyond the configured backbone and experts assigned to other ranks before
dequantization. Other checkpoint keys are not filtered by optional-tower
configuration.

## Module Contents

### Classes

| Name                                                                                                                           | Description                                                          |
| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| [`DeepseekV41StateDictAdapter`](#nemo_automodel-components-models-deepseek_v41-state_dict_adapter-DeepseekV41StateDictAdapter) | Convert released V4.1 checkpoint layouts for DCP loading and export. |

### Functions

| Name                                                                                                                             | Description                                                              |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`_local_offsets`](#nemo_automodel-components-models-deepseek_v41-state_dict_adapter-_local_offsets)                             | Locate a contiguous DTensor shard without gathering its values.          |
| [`_native_key`](#nemo_automodel-components-models-deepseek_v41-state_dict_adapter-_native_key)                                   | -                                                                        |
| [`_released_key`](#nemo_automodel-components-models-deepseek_v41-state_dict_adapter-_released_key)                               | -                                                                        |
| [`dequantize_checkpoint_weight`](#nemo_automodel-components-models-deepseek_v41-state_dict_adapter-dequantize_checkpoint_weight) | Decode released FP8 or packed FP4 weights with bounded FP32 temporaries. |

### Data

[`_ENGRAM_EMBED_PATTERN`](#nemo_automodel-components-models-deepseek_v41-state_dict_adapter-_ENGRAM_EMBED_PATTERN)

### API

```python
class nemo_automodel.components.models.deepseek_v41.state_dict_adapter.DeepseekV41StateDictAdapter(
    config: nemo_automodel.components.models.deepseek_v41.config.DeepseekV41Config,
    moe_config: nemo_automodel.components.moe.config.MoEConfig,
    backend: nemo_automodel.components.models.common.BackendConfig,
    dtype: torch.dtype = torch.bfloat16
)
```

**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)

Convert released V4.1 checkpoint layouts for DCP loading and export.

Floating DCP initialization uses shared MoE views and skips rebuilding
experts already written into model storage. Quantized load targets use the
released V4.1 layout; floating export uses the shared expert splitter.

**`_engram_rows`**

---

**`_expert_path_segment`** `str`

---

```python
nemo_automodel.components.models.deepseek_v41.state_dict_adapter.DeepseekV41StateDictAdapter._dequantize(
    state_dict: dict[str, typing.Any]
) -> dict[str, typing.Any]
```

Dequantize paired weights and require scales for retained packed tensors.

**Parameters:**

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

Mutated released-name mapping. Dense FP8 matrices have
shape \[rows, columns] with scales \[ceil(rows / 32), ceil(columns / 32)].
FP4 experts have shape \[rows, columns / 2] with scales \[rows, columns / 32].
FP8 Engram tables have shape \[rows, channels] with scales \[rows, channels / 32].
DTensors retain their global shape and mesh placements, including
uneven row owners and inner-axis expert shards. Other tensors
retain their registered shapes.

---

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

The same mapping with consumed scale entries and dequantized weights

**Raises:**

* `ValueError`: A packed INT8 or FP8 E4M3 weight has no companion scale.

```python
nemo_automodel.components.models.deepseek_v41.state_dict_adapter.DeepseekV41StateDictAdapter._engram_checkpoint_tensor(
    tensor: torch.Tensor,
    layer_id: int
) -> torch.Tensor
```

Expose logical checkpoint rows without gathering owner storage.

**Parameters:**

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

Table of global shape \[padded\_rows, channels], either a
complete local tensor or a DTensor with placement Shard(0) on
a one-dimensional owner mesh. Each owner stores equal rows.

---

**`layer_id`** `int`

Decoder layer identifying the logical checkpoint row count.

---

**Returns:** `torch.Tensor`

Aliasing view of shape \[rows, channels]. A DTensor preserves its

```python
nemo_automodel.components.models.deepseek_v41.state_dict_adapter.DeepseekV41StateDictAdapter._quantized_load_targets(
    key: str,
    value: torch.Tensor
) -> list[tuple[str, torch.Tensor]]
```

staticmethod

Allocate rank-local destinations matching the original quantized dump.

**Parameters:**

**`key`** `str`

Released checkpoint matrix name.

---

**`value`** `torch.Tensor`

Dequantized matrix \[rows, columns], possibly a DTensor. Row
scales retain row sharding; FP4 column shards must start and
end on 32-column block boundaries.

---

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

Packed INT8 \[rows, columns / 2] or FP8 \[rows, columns] weight and

```python
nemo_automodel.components.models.deepseek_v41.state_dict_adapter.DeepseekV41StateDictAdapter._restore_engram_padding(
    tensor: torch.Tensor,
    layer_id: int
) -> torch.Tensor
```

Restore equal owner storage after reading logical checkpoint rows.

**Parameters:**

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

Table of global shape \[rows, channels], optionally a DTensor
with placement Shard(0) on a one-dimensional owner mesh and
uneven local shape \[local\_rows, channels].

---

**`layer_id`** `int`

Decoder layer identifying the logical checkpoint row count.

---

**Returns:** `torch.Tensor`

Tensor unchanged for a local table. Distributed tables have global

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

Convert one internal tensor to HF keys, optionally emitting on-disk quantized placeholders.

With `quantization=True` the placeholders mirror the released layout so
DCP can validate shapes / dtypes before the adapter dequantizes on load.
These uninitialized targets require `for_checkpoint_load=True`;
trained weights must be exported without quantization.

**Parameters:**

**`fqn`** `str`

Internal parameter name.

---

**`tensor`** `Any`

Parameter in its model layout. Grouped experts have shape
\[experts, hidden, 2 \* intermediate] or \[experts, intermediate,
hidden], with optional DTensor sharding of the expert and inner
matrix axes. Engram tables have global shape \[padded\_rows,
channels], optionally placement Shard(0) on a one-dimensional
owner mesh with equal local row counts. Other tensors retain
their arbitrary registered shapes.

---

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

Checkpoint protocol options, including quantization,
exclude\_key\_regex and for\_checkpoint\_load.

---

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

Released-name tensor pairs, with split experts in \[output, input]

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

Preserve full-precision parameters when checkpoint export casts weights.

**Parameters:**

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

Native parameter/buffer tensors with arbitrary registered
shapes and layouts. Values are inspected only for their dtype.

---

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

Released checkpoint keys that must remain float32, including mHC,

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

Convert the released HF checkpoint to the internal format.

Steps: discard DSpark draft tensors, unconstructed layers and non-local
experts before dequantization, restore Engram owner padding, rename,
and merge experts not already loaded through views into model storage.

**Parameters:**

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

Consumed mapping of released-name tensors. Per-expert
projections have shape \[output, input], with FP4 input columns
packed two per byte before dequantization. Engram tables have
logical shape \[rows, channels]
and optionally placement Shard(0) on a one-dimensional owner
mesh, with uneven local shape \[local\_rows, channels]. Other
tensors retain the layouts documented in this module.

---

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

Optional expert mesh selecting local expert IDs and
retaining any inner-axis expert FSDP sharding.

---

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

Additional checkpoint protocol arguments.

---

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

Internal-name tensors. Engram DTensors have global shape

**Raises:**

* `ValueError`: A retained quantized weight has no scale, a scale has
  no weight, or multiple released keys map to one native key.
* `RuntimeError`: A retained expert layer lacks a required local projection.

```python
nemo_automodel.components.models.deepseek_v41.state_dict_adapter.DeepseekV41StateDictAdapter.get_hf_state_dict_keys(
    state_dict: dict[str, typing.Any]
) -> list[str]
```

Return global checkpoint names without inspecting owner-local values.

**Parameters:**

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

Native model mapping, including pre-distribution local
Engram parameters and meta tensors of arbitrary shapes.

---

**Returns:** `list[str]`

Rank-independent released names. Grouped expert keys expand over

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

Export native tensors under the released checkpoint's key names.

**Parameters:**

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

Native tensor mapping, including grouped expert tensors
\[experts, hidden, 2 \* intermediate] and \[experts, intermediate,
hidden]. Other values retain their registered shapes. DTensors
may shard the expert axis and an inner matrix axis; Engram
tables have global shape \[padded\_rows, channels] with Shard(0)
on a one-dimensional owner mesh.

---

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

Optional regular expression for excluded HF keys.

---

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

Whether initialization needs packed checkpoint targets.

---

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

Compatibility options from checkpointing, including
for\_checkpoint\_load for destinations overwritten by DCP.

---

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

Released mapping with split expert matrices \[output, input]. DTensor

```python
nemo_automodel.components.models.deepseek_v41.state_dict_adapter._local_offsets(
    tensor: torch.distributed.tensor.DTensor
) -> tuple[int, ...]
```

Locate a contiguous DTensor shard without gathering its values.

**Parameters:**

**`tensor`** `DTensor`

DTensor of arbitrary global shape, with Shard or Replicate
placements. Repeated sharding on the same axis is supported.

---

**Returns:** `tuple[int, ...]`

Global offsets of this rank's local shard along each tensor dimension.

```python
nemo_automodel.components.models.deepseek_v41.state_dict_adapter._native_key(
    key: str
) -> str
```

```python
nemo_automodel.components.models.deepseek_v41.state_dict_adapter._released_key(
    key: str
) -> str
```

```python
nemo_automodel.components.models.deepseek_v41.state_dict_adapter.dequantize_checkpoint_weight(
    weight: torch.Tensor,
    scale: torch.Tensor,
    dtype: torch.dtype = torch.bfloat16,
    rowwise: bool = False
) -> torch.Tensor
```

Decode released FP8 or packed FP4 weights with bounded FP32 temporaries.

**Parameters:**

**`weight`** `torch.Tensor`

FP8 tensor of shape \[rows, columns], or packed INT8 tensor of
shape \[rows, columns / 2]. Packed E2M1 stores the even column in
the low nibble and the odd column in the high nibble. A DTensor
preserves its global shape and Shard/Replicate placements.

---

**`scale`** `torch.Tensor`

Tensor of shape \[ceil(rows / 32), ceil(columns / 32)] for dense
FP8, or \[rows, ceil(columns / 32)] for FP4 and Engram FP8. A plain
scale may cover the global matrix or exactly this rank's blocks;
a DTensor scale must cover the weight shard at matching offsets.

---

**`dtype`** `torch.dtype` — default: torch.bfloat16

Dequantized floating-point storage dtype.

---

**`rowwise`** `bool` — default: False

Use per-row scales for FP8 Engram tables. FP4 always uses them.

---

**Returns:** `torch.Tensor`

Independent tensor of shape \[rows, columns] in `dtype`; DTensor

```python
nemo_automodel.components.models.deepseek_v41.state_dict_adapter._ENGRAM_EMBED_PATTERN = re.compile('^layers\\.(\\d+)\\.engram\\.embed\\.weight$')
```