# Qwen3-Next：本地运行指南

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

<a href="#run-qwen3-next-tutorials" class="button secondary">运行 Qwen3-Next Instruct</a><a href="#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 以提升性能。

思考模型使用 `temperature = 0.6`, 但指令模型使用 `temperature = 0.7`\
思考模型使用 `top_p = 0.95`, 但指令模型使用 `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 默认将其关闭，但为减少重复可以使用此项）  |

**适当的输出长度**: 对于大多数查询，思考变体请使用输出长度为 `32,768` tokens，而指令变体则为 `16,384` 。如果必要，你可以为思考模型增加最大输出长度。

适用于思考（thinking 包含 `<think></think>`) 和指令的聊天模板如下：

```
<|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

鉴于这是一个非思考模型，模型不会生成 `<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` tokens 以减少内存占用

#### :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

该模型仅原生支持思考模式和 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` tokens 以减少内存占用

#### :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>

如果你有更多显存，可以尝试卸载更多 MoE 层，或将整个层本身卸载（offload）。

通常， `-ot ".ffn_.*_exps.=CPU"` 会将所有 MoE 层卸载到 CPU！这实际上允许你将所有非 MoE 层放在一块 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 缓存量化为 4 bit** 以减少 VRAM / RAM 的移动，这也可以使生成过程更快。 [下一节](#how-to-fit-long-context-256k-to-1m) 讨论了 KV 缓存量化。

### 📐 如何适配长上下文 <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 缓存进行量化，但你需要 **在编译 llama.cpp 时启用 Flash Attention 支持** 通过 `-DGGML_CUDA_FA_ALL_QUANTS=ON`，并使用 `--flash-attn` 来启用它。安装 Flash Attention 之后，你就可以使用 `--cache-type-v q4_1`

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fgit-blob-be34c101c627020c7a6cfb6cd249f2462587d235%2Fqwen33%20mascot.png?alt=media" 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.