# `vllm_mlx.patches.qwen3_next_mtp`

Runtime MTP (Multi-Token Prediction) support for Qwen3-Next models.

[View the complete module source at #L1-L261](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L1-L261).

## API details

Each callable below includes its exact signature, type annotations, inputs, defaults, return contract, documented exceptions, implementation source, and parsed docstring sections when the source provides them.

::: vllm_mlx.patches.qwen3_next_mtp
    options:
      members:
        - logger
        - inject_mtp_support
        - validate_mtp_support
      filters: []
      show_if_no_docstring: true

## Complete contract reference

Expand any definition for its exact inputs, annotations, defaults, return contract, directly raised exceptions, source-grounded behavior, and immutable line link. This section includes private and nested definitions that ordinary API generators omit.

<details class="api-contract" id="contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support" markdown="1">
<summary><code>vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support</code> · function</summary>

```python
vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support(model: Any, model_path, config: dict) -> bool
```

Inject MTP module into a loaded Qwen3-Next model.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model` | `Any` | `yes` | `none` | A model loaded via mlx_lm (strict=False, MTP weights ignored) |
| `model_path` | `not annotated` | `yes` | `none` | Path to model directory (contains model-mtp.safetensors) |
| `config` | `dict` | `yes` | `none` | Parsed config.json dict |

**Returns**

- Type: `bool`
- Direct return expressions: `False`; `True`

**Exceptions and behavior**

Function `inject_mtp_support` calls `config.get`, `logger.info`, `Path`, `mtp_file.exists`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L27-L181](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L27-L181).

</details>

<details class="api-contract" id="contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._MTPModule" markdown="1">
<summary><code>vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._MTPModule</code> · nested class</summary>

```python
vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._MTPModule(args, n_layers)
```

Nested Class `inject_mtp_support._MTPModule` derives from `nn.Module` and declares 1 direct member(s).

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `args` | `not annotated` | `yes` | `none` | Required positional or keyword input. |
| `n_layers` | `not annotated` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Constructs: `vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._MTPModule`

**Exceptions and behavior**

Nested Class `inject_mtp_support._MTPModule` derives from `nn.Module` and declares 1 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L68-L83](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L68-L83).

</details>

<details class="api-contract" id="contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._MTPModule.__init__" markdown="1">
<summary><code>vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._MTPModule.__init__</code> · nested function</summary>

```python
vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._MTPModule.__init__(args, n_layers) -> not annotated
```

Nested Function `inject_mtp_support._MTPModule.__init__` updates `self.pre_fc_norm_hidden`, `self.pre_fc_norm_embedding`, `self.fc`, `self.layers`; calls `super().__init__`, `super`, `nn.RMSNorm`, `nn.Linear`.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `args` | `not annotated` | `yes` | `none` | Required positional or keyword input. |
| `n_layers` | `not annotated` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `not annotated`

**Exceptions and behavior**

Nested Function `inject_mtp_support._MTPModule.__init__` updates `self.pre_fc_norm_hidden`, `self.pre_fc_norm_embedding`, `self.fc`, `self.layers`; calls `super().__init__`, `super`, `nn.RMSNorm`, `nn.Linear`.
No direct `raise` statement appears in this definition.

[View source #L69-L83](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L69-L83).

</details>

<details class="api-contract" id="contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._mtp_quant_pred" markdown="1">
<summary><code>vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._mtp_quant_pred</code> · nested function</summary>

```python
vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._mtp_quant_pred(path, module) -> not annotated
```

Nested Function `inject_mtp_support._mtp_quant_pred` calls `isinstance`, `path.endswith`; has 3 explicit return paths.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `path` | `not annotated` | `yes` | `none` | Required positional or keyword input. |
| `module` | `not annotated` | `yes` | `none` | Required positional or keyword input. |

**Returns**

- Type: `not annotated`
- Direct return expressions: `False`; `{'group_size': 64, 'bits': 8}`; `True`

**Exceptions and behavior**

Nested Function `inject_mtp_support._mtp_quant_pred` calls `isinstance`, `path.endswith`; has 3 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L93-L103](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L93-L103).

</details>

<details class="api-contract" id="contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP" markdown="1">
<summary><code>vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP</code> · nested class</summary>

```python
vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP()
```

Qwen3-Next with MTP support (injected at runtime).

**Parameters**

This callable has no explicit inputs.

**Returns**

- Constructs: `vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP`

**Exceptions and behavior**

Nested Class `inject_mtp_support._Qwen3NextMTP` derives from `original_class` and declares 3 direct member(s).
No direct `raise` statement appears in this definition.

[View source #L125-L177](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L125-L177).

</details>

<details class="api-contract" id="contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP.__call__" markdown="1">
<summary><code>vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP.__call__</code> · nested function</summary>

```python
vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP.__call__(inputs, cache = None, return_hidden: bool = False) -> not annotated
```

Nested Function `inject_mtp_support._Qwen3NextMTP.__call__` calls `inner.embed_tokens`, `len`, `create_attention_mask`, `create_ssm_mask`; has 2 explicit return paths.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `inputs` | `not annotated` | `yes` | `none` | Required positional or keyword input. |
| `cache` | `not annotated` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |
| `return_hidden` | `bool` | `no` | `False` | Optional positional or keyword input; defaults to `False`. |

**Returns**

- Type: `not annotated`
- Direct return expressions: `(out, hidden_states)`; `out`

**Exceptions and behavior**

Nested Function `inject_mtp_support._Qwen3NextMTP.__call__` calls `inner.embed_tokens`, `len`, `create_attention_mask`, `create_ssm_mask`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L128-L150](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L128-L150).

</details>

<details class="api-contract" id="contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP.mtp_forward" markdown="1">
<summary><code>vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP.mtp_forward</code> · nested function</summary>

```python
vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP.mtp_forward(hidden_states, next_token_ids, cache = None, mtp_cache = None) -> not annotated
```

Run MTP head: predict token n+2 from hidden states + token n+1.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `hidden_states` | `not annotated` | `yes` | `none` | Required positional or keyword input. |
| `next_token_ids` | `not annotated` | `yes` | `none` | Required positional or keyword input. |
| `cache` | `not annotated` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |
| `mtp_cache` | `not annotated` | `no` | `None` | Optional positional or keyword input; defaults to `None`. |

**Returns**

- Type: `not annotated`
- Direct return expressions: `self.model.embed_tokens.as_linear(x)`; `self.lm_head(x)`

**Exceptions and behavior**

Nested Function `inject_mtp_support._Qwen3NextMTP.mtp_forward` calls `self.model.embed_tokens`, `self.mtp.pre_fc_norm_hidden`, `self.mtp.pre_fc_norm_embedding`, `self.mtp.fc`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L152-L171](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L152-L171).

</details>

<details class="api-contract" id="contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP.make_mtp_cache" markdown="1">
<summary><code>vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP.make_mtp_cache</code> · nested function</summary>

```python
vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP.make_mtp_cache() -> not annotated
```

Create KV cache for MTP layers.

**Parameters**

This callable has no explicit inputs.

**Returns**

- Type: `not annotated`
- Direct return expressions: `None`; `[KVCache() for _ in self.mtp.layers]`

**Exceptions and behavior**

Nested Function `inject_mtp_support._Qwen3NextMTP.make_mtp_cache` calls `KVCache`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L173-L177](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L173-L177).

</details>

<details class="api-contract" id="contract-vllm_mlx.patches.qwen3_next_mtp.validate_mtp_support" markdown="1">
<summary><code>vllm_mlx.patches.qwen3_next_mtp.validate_mtp_support</code> · function</summary>

```python
vllm_mlx.patches.qwen3_next_mtp.validate_mtp_support(model: Any) -> bool
```

Validate that a loaded model has working MTP support.

**Parameters**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model` | `Any` | `yes` | `none` | A model loaded via mlx_lm.load() |

**Returns**

- Type: `bool`
- Direct return expressions: `False`; `True`

**Exceptions and behavior**

Function `validate_mtp_support` calls `getattr`, `logger.warning`, `logger.info`, `inspect.signature`; has 2 explicit return paths.
No direct `raise` statement appears in this definition.

[View source #L184-L261](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L184-L261).

</details>

## Complete symbol map

This map also includes private definitions and nested helpers. The signature column exposes every explicit input even when an internal helper has no dedicated parameter prose.

| Symbol | Kind | Signature and inputs | What it does | Source |
| --- | --- | --- | --- | --- |
| [`inject_mtp_support`](#contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support) | function | `inject_mtp_support(model: Any, model_path, config: dict) -> bool` | Inject MTP module into a loaded Qwen3-Next model. | [#L27-L181](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L27-L181) |
| [`inject_mtp_support._MTPModule`](#contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._MTPModule) | nested class | `inject_mtp_support._MTPModule(args, n_layers)` | Nested Class `inject_mtp_support._MTPModule` derives from `nn.Module` and declares 1 direct member(s). | [#L68-L83](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L68-L83) |
| [`inject_mtp_support._MTPModule.__init__`](#contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._MTPModule.__init__) | nested function | `inject_mtp_support._MTPModule.__init__(args, n_layers) -> not annotated` | Nested Function `inject_mtp_support._MTPModule.__init__` updates `self.pre_fc_norm_hidden`, `self.pre_fc_norm_embedding`, `self.fc`, `self.layers`; calls `super().__init__`, `super`, `nn.RMSNorm`, `nn.Linear`. | [#L69-L83](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L69-L83) |
| [`inject_mtp_support._mtp_quant_pred`](#contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._mtp_quant_pred) | nested function | `inject_mtp_support._mtp_quant_pred(path, module) -> not annotated` | Nested Function `inject_mtp_support._mtp_quant_pred` calls `isinstance`, `path.endswith`; has 3 explicit return paths. | [#L93-L103](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L93-L103) |
| [`inject_mtp_support._Qwen3NextMTP`](#contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP) | nested class | `inject_mtp_support._Qwen3NextMTP()` | Qwen3-Next with MTP support (injected at runtime). | [#L125-L177](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L125-L177) |
| [`inject_mtp_support._Qwen3NextMTP.__call__`](#contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP.__call__) | nested function | `inject_mtp_support._Qwen3NextMTP.__call__(inputs, cache = None, return_hidden: bool = False) -> not annotated` | Nested Function `inject_mtp_support._Qwen3NextMTP.__call__` calls `inner.embed_tokens`, `len`, `create_attention_mask`, `create_ssm_mask`; has 2 explicit return paths. | [#L128-L150](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L128-L150) |
| [`inject_mtp_support._Qwen3NextMTP.mtp_forward`](#contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP.mtp_forward) | nested function | `inject_mtp_support._Qwen3NextMTP.mtp_forward(hidden_states, next_token_ids, cache = None, mtp_cache = None) -> not annotated` | Run MTP head: predict token n+2 from hidden states + token n+1. | [#L152-L171](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L152-L171) |
| [`inject_mtp_support._Qwen3NextMTP.make_mtp_cache`](#contract-vllm_mlx.patches.qwen3_next_mtp.inject_mtp_support._Qwen3NextMTP.make_mtp_cache) | nested function | `inject_mtp_support._Qwen3NextMTP.make_mtp_cache() -> not annotated` | Create KV cache for MTP layers. | [#L173-L177](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L173-L177) |
| [`validate_mtp_support`](#contract-vllm_mlx.patches.qwen3_next_mtp.validate_mtp_support) | function | `validate_mtp_support(model: Any) -> bool` | Validate that a loaded model has working MTP support. | [#L184-L261](https://github.com/waybarrios/vllm-mlx/blob/a69d47912bcb21d8fe04d48f75fa896b620ffcfa/vllm_mlx/patches/qwen3_next_mtp.py#L184-L261) |