# Qwen3-Next：本地运行指南

Qwen 于 2025 年 9 月发布了 Qwen3-Next，它们是 80B MoE，具有 Thinking 和 Instruct 两个模型变体， [Qwen3](/docs/zh/mo-xing/tutorials/qwen3-how-to-run-and-fine-tune.md)。在 256K 上下文下，Qwen3-Next 采用了全新架构设计（MoE 与 Gated DeltaNet + Gated Attention 的混合），专门针对更长上下文长度上的快速推理进行了优化。Qwen3-Next 的推理速度比 Qwen3-32B 快 10 倍。

<a href="/pages/8db617b6a4600d935dc1abb0de60011e111d55ff#run-qwen3-next-tutorials" class="button secondary">运行 Qwen3-Next Instruct</a><a href="/pages/8db617b6a4600d935dc1abb0de60011e111d55ff#thinking-qwen3-next-80b-a3b-thinking" class="button secondary">运行 Qwen3-Next Thinking</a>

Qwen3-Next-80B-A3B 动态 GGUF： [**Instruct**](https://huggingface.co/unsloth/Qwen3-Next-80B-A3B-Instruct-GGUF) **•** [**Thinking**](https://huggingface.co/unsloth/Qwen3-Next-80B-A3B-Thinking-GGUF)

### ⚙️ 使用指南

{% hint style="success" %}
截至 2025 年 12 月 6 日更新：Unsloth Qwen3-Next 现已使用 iMatrix 更新，以提升性能。

thinking 模型使用 `temperature = 0.6`，而 instruct 模型使用 `temperature = 0.7`\
thinking 模型使用 `top_p = 0.95`，而 instruct 模型使用 `top_p = 0.8`
{% endhint %}

为获得最佳性能，Qwen 建议使用以下设置：

| Instruct：                                                            | Thinking：                                                            |
| -------------------------------------------------------------------- | -------------------------------------------------------------------- |
| <mark style="background-color:blue;">`Temperature = 0.7`</mark>      | <mark style="background-color:blue;">`Temperature = 0.6`</mark>      |
| `Min_P = 0.00` （llama.cpp 的默认值是 0.1）                                 | `Min_P = 0.00` （llama.cpp 的默认值是 0.1）                                 |
| `Top_P = 0.80`                                                       | `Top_P = 0.95`                                                       |
| `TopK = 20`                                                          | `TopK = 20`                                                          |
| `presence_penalty = 0.0 到 2.0` （llama.cpp 默认会将其关闭，但为了减少重复，你可以使用这个设置） | `presence_penalty = 0.0 到 2.0` （llama.cpp 默认会将其关闭，但为了减少重复，你可以使用这个设置） |

**足够的输出长度**：对于大多数查询，thinking 变体使用 `32,768` 个 token，而 instruct 变体使用 `16,384` 个 token。如有必要，你可以增加 thinking 模型的最大输出大小。

两者的聊天模板（thinking 有 `<think></think>`）和 Instruct 如下：

```
<|im_start|>user
嘿！<|im_end|>
<|im_start|>assistant
1+1 等于多少？<|im_end|>
<|im_start|>user
2<|im_end|>
<|im_start|>assistant
```

## 📖 运行 Qwen3-Next 教程

以下是针对该模型 [Thinking](#thinking-qwen3-next-80b-a3b-thinking) 和 [Instruct](#instruct-qwen3-next-80b-a3b-instruct) 各版本的指南。

### Instruct: Qwen3-Next-80B-A3B-Instruct

鉴于这是一个非 thinking 模型，模型不会生成 `<think> </think>` 块。

#### ⚙️最佳实践

为获得最佳性能，Qwen 建议采用以下设置：

* 我们建议使用 `temperature=0.7, top_p=0.8, top_k=20, 以及 min_p=0.0` `presence_penalty` 在 0 到 2 之间，如果框架支持，以减少无尽重复。
* **`temperature = 0.7`**
* `top_k = 20`
* `min_p = 0.00` （llama.cpp 的默认值是 0.1）
* **`top_p = 0.80`**
* `presence_penalty = 0.0 到 2.0` （llama.cpp 默认会将其关闭，但为了减少重复，你可以使用这个设置）例如可以试试 1.0。
* 支持最多 `262,144` 个上下文，原生支持，但你可以将其设置为 `32,768` 个 token，以减少 RAM 使用

#### :sparkles: Llama.cpp：运行 Qwen3-Next-80B-A3B-Instruct 教程

1. 获取最新的 `llama.cpp` 在 [GitHub 这里](https://github.com/ggml-org/llama.cpp)。你也可以按照下面的构建说明操作。将 `-DGGML_CUDA=ON` 改为 `-DGGML_CUDA=OFF` 如果你没有 GPU，或者只想进行 CPU 推理。 **对于 Apple Mac / Metal 设备**，设置 `-DGGML_CUDA=OFF` 然后照常继续——Metal 支持默认开启。

```bash
apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp
```

2. 你可以直接通过 HuggingFace 拉取：

   ```bash
   ./llama.cpp/llama-cli \
       -hf unsloth/Qwen3-Next-80B-A3B-Instruct-GGUF:Q4_K_XL \\
       --jinja -ngl 99 --ctx-size 32768 \\
       --temp 0.7 --min-p 0.0 --top-p 0.80 --top-k 20 --presence-penalty 1.0
   ```
3. 通过以下方式下载模型（在安装 `pip install huggingface_hub hf_transfer` 之后）。你可以选择 `UD_Q4_K_XL` 或其他量化版本。

```python
# !pip install huggingface_hub hf_transfer
import os
os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id = "unsloth/Qwen3-Next-80B-A3B-Instruct-GGUF",
    local_dir = "Qwen3-Next-80B-A3B-Instruct-GGUF",
    allow_patterns = ["*UD-Q4_K_XL*"],
)
```

### Thinking: Qwen3-Next-80B-A3B-Thinking

此模型仅支持 thinking 模式，并原生支持 256K 上下文窗口。默认聊天模板会自动添加 `<think>` ，因此你在输出中可能只会看到一个结尾的 `</think>` 标签。

#### ⚙️最佳实践

为获得最佳性能，Qwen 建议采用以下设置：

* 我们建议使用 `temperature=0.6, top_p=0.95, top_k=20, 以及 min_p=0.0` `presence_penalty` 在 0 到 2 之间，如果框架支持，以减少无尽重复。
* **`temperature = 0.6`**
* `top_k = 20`
* `min_p = 0.00` （llama.cpp 的默认值是 0.1）
* **`top_p = 0.95`**
* `presence_penalty = 0.0 到 2.0` （llama.cpp 默认会将其关闭，但为了减少重复，你可以使用这个设置）例如可以试试 1.0。
* 支持最多 `262,144` 个上下文，原生支持，但你可以将其设置为 `32,768` 个 token，以减少 RAM 使用

#### :sparkles: Llama.cpp：运行 Qwen3-Next-80B-A3B-Thinking 教程

1. 获取最新的 `llama.cpp` 在 [GitHub 这里](https://github.com/ggml-org/llama.cpp)。你也可以按照下面的构建说明操作。将 `-DGGML_CUDA=ON` 改为 `-DGGML_CUDA=OFF` 如果你没有 GPU，或者只想进行 CPU 推理。

```bash
apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp
```

2. 你可以通过以下方式直接从 Hugging Face 拉取：

   ```bash
   ./llama.cpp/llama-cli \
       -hf unsloth/Qwen3-Next-80B-A3B-Thinking-GGUF:Q4_K_XL \\
       --jinja -ngl 99 --ctx-size 32768 \\
       --temp 0.6 --min-p 0.0 --top-p 0.95 --top-k 20 --presence-penalty 1.0
   ```
3. 通过以下方式下载模型（在安装 `pip install huggingface_hub hf_transfer` 之后）。你可以选择 `UD_Q4_K_XL` 或其他量化版本。

```python
# !pip install huggingface_hub hf_transfer
import os
os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id = "unsloth/Qwen3-Next-80B-A3B-Thinking-GGUF",
    local_dir = "Qwen3-Next-80B-A3B-Thinking-GGUF",
    allow_patterns = ["*UD-Q4_K_XL*"],
)
```

### 🛠️ 提升生成速度 <a href="#improving-generation-speed" id="improving-generation-speed"></a>

如果你有更多 VRAM，可以尝试卸载更多 MoE 层，或直接卸载整个层。

通常， `-ot ".ffn_.*_exps.=CPU"` 会将所有 MoE 层卸载到 CPU！这实际上允许你将所有非 MoE 层放到 1 张 GPU 上，从而提高生成速度。如果你有更多 GPU 容量，可以自定义正则表达式以适配更多层。

如果你的 GPU 内存再多一些，尝试 `-ot ".ffn_(up|down)_exps.=CPU"` 这会卸载上、下投影 MoE 层。

再试试 `-ot ".ffn_(up)_exps.=CPU"` 如果你的 GPU 内存更多一些。这样只会卸载上投影 MoE 层。

你也可以自定义正则表达式，例如 `-ot "\.(6|7|8|9|[0-9][0-9]|[0-9][0-9][0-9])\.ffn_(gate|up|down)_exps.=CPU"` 表示从第 6 层开始卸载 gate、up 和 down MoE 层。

最新的 [llama.cpp 版本](https://github.com/ggml-org/llama.cpp/pull/14363) 还引入了高吞吐模式。使用 `llama-parallel`。了解更多 [这里](https://github.com/ggml-org/llama.cpp/tree/master/examples/parallel)。你还可以 **将 KV 缓存量化为 4bits** 例如可以减少 VRAM / RAM 之间的数据移动，这也能让生成过程更快。 [下一节](#how-to-fit-long-context-256k-to-1m) 将介绍 KV cache 量化。

### 📐如何适配长上下文 <a href="#how-to-fit-long-context-256k-to-1m" id="how-to-fit-long-context-256k-to-1m"></a>

要适配更长上下文，你可以使用 **KV 缓存量化** 将 K 和 V 缓存量化到更低位数。由于减少了 RAM / VRAM 数据移动，这也可以提高生成速度。允许的 K 量化选项（默认是 `f16`）如下。

`--cache-type-k f32, f16, bf16, q8_0, q4_0, q4_1, iq4_nl, q5_0, q5_1`

你应该使用 `_1` 这些变体，以略微提高准确率，尽管会稍慢一些。例如 `q4_1, q5_1` 所以试试 `--cache-type-k q4_1`

你也可以量化 V 缓存，但你需要 **通过以下方式编译带有 Flash Attention 支持的 llama.cpp** ： `-DGGML_CUDA_FA_ALL_QUANTS=ON`，并使用 `--flash-attn` 来启用它。安装 Flash Attention 后，你还可以使用 `--cache-type-v q4_1`

<figure><img src="/files/f56f40f82df1b77a9dbe4b824cfe5643a41cdc4f" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://unsloth.ai/docs/zh/mo-xing/tutorials/qwen3-next.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.