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

## Module Contents

### Classes

| Name                                                                                                                               | Description                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`Qwen3OmniMoeStateDictAdapter`](#nemo_automodel-components-models-qwen3_omni_moe-state_dict_adapter-Qwen3OmniMoeStateDictAdapter) | Converts between HF Qwen3OmniMoe checkpoints and grouped-experts native format. |

### Data

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

### API

```python
class nemo_automodel.components.models.qwen3_omni_moe.state_dict_adapter.Qwen3OmniMoeStateDictAdapter(
    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 Qwen3OmniMoe checkpoints and grouped-experts native format.

```python
nemo_automodel.components.models.qwen3_omni_moe.state_dict_adapter.Qwen3OmniMoeStateDictAdapter._add_thinker_prefix(
    key: str
) -> str
```

staticmethod

Namespace a native key the way the HF omni checkpoint expects.

PEFT adapter keys keep their `base_model.model.` outer prefix, so for
those the `thinker.` namespace goes inside it — matching how PEFT
names modules on the actual HF omni model.

```python
nemo_automodel.components.models.qwen3_omni_moe.state_dict_adapter.Qwen3OmniMoeStateDictAdapter._strip_thinker_prefix(
    key: str
) -> str
```

staticmethod

Remove the omni checkpoint's `thinker.` namespace.

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

```python
nemo_automodel.components.models.qwen3_omni_moe.state_dict_adapter.Qwen3OmniMoeStateDictAdapter.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_omni_moe.state_dict_adapter.Qwen3OmniMoeStateDictAdapter.map_peft_target_module_to_hf(
    name: str,
    v4_compatible: bool = False
) -> str
```

Give target\_modules the same namespace the exported tensors get.

`from_hf` records whether the base checkpoint nests the text tower under
`thinker.`; `to_hf` and `convert_single_tensor_to_hf` both honor that
flag, so target\_modules has to honor it too. Otherwise the two halves of one
checkpoint name different modules and PEFT cannot match them up.

On the full omni layout the namespace is required: PEFT suffix-matches
target\_modules against the receiving model, so an entry without it also hits
the talker's identically named modules, which then get adapters the checkpoint
has no weights for and stay randomly initialized. On a standalone-thinker base
the namespace does not exist on the receiving model at all, and adding it makes
PEFT reject the adapter with "Target modules ... not found".

**Parameters:**

**`name`** `str`

A target-module name in native layout.

---

**`v4_compatible`** `bool` — default: False

Legacy export selection; omni uses one module layout for both.

---

**Returns:** `str`

Target-module name in the layout the exported tensors use.

```python
nemo_automodel.components.models.qwen3_omni_moe.state_dict_adapter.Qwen3OmniMoeStateDictAdapter.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_omni_moe.state_dict_adapter.logger = logging.getLogger(__name__)
```