> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/mo-xing/tutorials/qwen3-next.md). # Qwen3-Next：本地运行指南 在你的设备上本地运行 Qwen3-Next-80B-A3B-Instruct 和 Thinking 版本！ 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 倍。 运行 Qwen3-Next Instruct运行 Qwen3-Next Thinking Qwen3-Next-80B-A3B 动态 GGUF： [**指令**](https://huggingface.co/unsloth/Qwen3-Next-80B-A3B-Instruct-GGUF) **•** [**思考**](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： | | ----------------------------------------------------------------- | ----------------------------------------------------------------- | | `Temperature = 0.7` | `Temperature = 0.6` | | `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，而 instruct 版使用 `16,384` 。如果有必要，你可以增加 thinking 模型的最大输出大小。 两种模式的聊天模板（thinking 额外有 ``），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-qwen3-next-80b-a3b-thinking) 和 [指令](#instruct-qwen3-next-80b-a3b-instruct) 模型版本的指南。 ### Instruct：Qwen3-Next-80B-A3B-Instruct 由于这是一个非思考模型，模型不会生成 ` ` 块。 #### ⚙️最佳实践 为达到最佳性能，Qwen 建议使用以下设置： * 我们建议使用 `temperature=0.7, top_p=0.8, top_k=20, and 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，以减少 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 该模型原生仅支持思考模式和 256K 上下文窗口。默认聊天模板会自动添加 `` ，因此你可能在输出中只看到一个结尾的 `` 标签。 #### ⚙️最佳实践 为达到最佳性能，Qwen 建议使用以下设置： * 我们建议使用 `temperature=0.6, top_p=0.95, top_k=20, and 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，以减少 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*"], ) ``` ### 🛠️ 提升生成速度 如果你有更多 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 缓存量化为 4 位** 例如可减少 VRAM / RAM 之间的数据移动，这也能让生成过程更快。 [下一节](#how-to-fit-long-context-256k-to-1m) 将介绍 KV 缓存量化。 ### 📐如何适配长上下文 要容纳更长的上下文，你可以使用 **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`
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://unsloth.ai/docs/zh/mo-xing/tutorials/qwen3-next.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.