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

State-dict adapter for Kimi Linear MoE checkpoints.

## Module Contents

### Classes

| Name                                                                                                                              | Description                                                        |
| --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [`KimiLinear48BStateDictAdapter`](#nemo_automodel-components-models-kimi_linear-state_dict_adapter-KimiLinear48BStateDictAdapter) | Convert Kimi Linear HF split experts to Automodel grouped experts. |

### Functions

| Name                                                                                                                      | Description                                                            |
| ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [`_hf_moe_key_to_native`](#nemo_automodel-components-models-kimi_linear-state_dict_adapter-_hf_moe_key_to_native)         | Rewrite a checkpoint MoE key onto the decoder block's `mlp` submodule. |
| [`_native_moe_key_to_hf`](#nemo_automodel-components-models-kimi_linear-state_dict_adapter-_native_moe_key_to_hf)         | Inverse of :func:`_hf_moe_key_to_native`.                              |
| [`_route_kda_fp32_holder`](#nemo_automodel-components-models-kimi_linear-state_dict_adapter-_route_kda_fp32_holder)       | -                                                                      |
| [`_strip_kda_fp32_holder`](#nemo_automodel-components-models-kimi_linear-state_dict_adapter-_strip_kda_fp32_holder)       | -                                                                      |
| [`_upcast_fp32_state_tensor`](#nemo_automodel-components-models-kimi_linear-state_dict_adapter-_upcast_fp32_state_tensor) | -                                                                      |

### Data

[`_FP32_KEY_PARTS`](#nemo_automodel-components-models-kimi_linear-state_dict_adapter-_FP32_KEY_PARTS)

[`_GENERIC_TO_HF_EXPERT_PROJ`](#nemo_automodel-components-models-kimi_linear-state_dict_adapter-_GENERIC_TO_HF_EXPERT_PROJ)

[`_HF_TO_GENERIC_EXPERT_PROJ`](#nemo_automodel-components-models-kimi_linear-state_dict_adapter-_HF_TO_GENERIC_EXPERT_PROJ)

[`_KDA_FP32_HOLDER`](#nemo_automodel-components-models-kimi_linear-state_dict_adapter-_KDA_FP32_HOLDER)

[`_KDA_FP32_PARAM_NAMES`](#nemo_automodel-components-models-kimi_linear-state_dict_adapter-_KDA_FP32_PARAM_NAMES)

[`_MOE_CHILD_SEGMENTS`](#nemo_automodel-components-models-kimi_linear-state_dict_adapter-_MOE_CHILD_SEGMENTS)

### API

```python
class nemo_automodel.components.models.kimi_linear.state_dict_adapter.KimiLinear48BStateDictAdapter(
    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)

Convert Kimi Linear HF split experts to Automodel grouped experts.

HF stores routed experts as per-expert Kimi names:

* `block_sparse_moe.experts.{E}.w1.weight`: SwiGLU gate projection, shape \[inter, hidden].
* `block_sparse_moe.experts.{E}.w3.weight`: SwiGLU up projection, shape \[inter, hidden].
* `block_sparse_moe.experts.{E}.w2.weight`: down projection, shape \[hidden, inter].

Automodel stores grouped experts as:

* `mlp.experts.gate_and_up_projs` with shape \[experts, hidden, 2 \* inter].
* `mlp.experts.down_projs` with shape \[experts, inter, hidden].

The decoder block names both its dense and its MoE feed-forward `mlp` (the
naming the custom-MoE parallelizer looks for), so the checkpoint's
`block_sparse_moe` path segment is translated here in both directions.

**`_expert_path_segment`** `str`

---

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter.KimiLinear48BStateDictAdapter._map_generic_expert_key_to_hf(
    key: str
) -> str
```

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter.KimiLinear48BStateDictAdapter._map_hf_expert_key_to_generic(
    key: str
) -> str
```

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter.KimiLinear48BStateDictAdapter._split_experts_weights(
    weight: torch.Tensor,
    n_experts: int
) -> list[torch.Tensor]
```

Split grouped experts, tolerating DTensors whose mesh dim is not named `ep`.

**Parameters:**

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

Grouped routed-expert tensor of shape \[experts, ...]. May be a plain tensor or a DTensor
sharded or replicated over the expert axis; for Shard(0), the local shard covers this rank's
expert slice.

---

**`n_experts`** `int`

Global number of routed experts.

---

**Returns:** `list[torch.Tensor]`

List of per-expert tensors of shape \[...] for the experts local to this rank.

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

Convert one Automodel tensor to one or more Kimi HF tensors.

**Parameters:**

**`fqn`** `str`

Fully qualified native tensor name.

---

**`tensor`** `Any`

Native tensor. Grouped routed expert tensors use \[experts, hidden, 2 \* inter]
for gate/up and \[experts, inter, hidden] for down.

---

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

Adapter options forwarded by checkpoint save/load.

---

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

HF key/tensor pairs. Split expert tensors use Kimi `w1`/`w2`/`w3` names.

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

Convert Kimi HF checkpoint keys to Automodel native keys.

**Parameters:**

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

HF state dict whose routed expert tensors use split Kimi names.

---

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

Optional EP/FSDP mesh used to load only local expert shards.

---

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

Adapter options forwarded by checkpoint load.

---

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

Native state dict with grouped routed expert tensors.

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

Convert Automodel native tensors to Kimi HF checkpoint keys.

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter._hf_moe_key_to_native(
    key: str
) -> str
```

Rewrite a checkpoint MoE key onto the decoder block's `mlp` submodule.

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter._native_moe_key_to_hf(
    key: str
) -> str
```

Inverse of :func:`_hf_moe_key_to_native`.

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter._route_kda_fp32_holder(
    key: str
) -> str
```

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter._strip_kda_fp32_holder(
    key: str
) -> str
```

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter._upcast_fp32_state_tensor(
    key: str,
    value: typing.Any
) -> typing.Any
```

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter._FP32_KEY_PARTS = ('A_log', 'dt_bias', 'e_score_correction_bias')
```

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter._GENERIC_TO_HF_EXPERT_PROJ = {value: key for key, value in (_HF_TO_GENERIC_EXPERT_PROJ.items())}
```

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter._HF_TO_GENERIC_EXPERT_PROJ = {'w1': 'gate_proj', 'w2': 'down_proj', 'w3': 'up_proj'}
```

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter._KDA_FP32_HOLDER = re.compile('(\\.self_attn)\\._fp32_params\\.')
```

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter._KDA_FP32_PARAM_NAMES = ('A_log', 'dt_bias')
```

```python
nemo_automodel.components.models.kimi_linear.state_dict_adapter._MOE_CHILD_SEGMENTS = ('gate.', 'shared_experts.')
```