> 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-coder-how-to-run-locally.md). # Qwen3-Coder：如何本地运行 使用 Unsloth Dynamic 量化版本本地运行 Qwen3-Coder-30B-A3B-Instruct 和 480B-A35B。 Qwen3-Coder 是 Qwen 全新的编程代理模型系列，提供 30B（**Qwen3-Coder-Flash**）和 480B 参数。 **Qwen3-480B-A35B-Instruct** 在编码性能上达到 SOTA，可与 Claude Sonnet-4、GPT-4.1 以及 [Kimi K2](/docs/zh/mo-xing/tutorials/kimi-k2-thinking-how-to-run-locally.md)，在 Aider Polygot 上取得 61.8%，并支持 256K（可扩展至 1M）token 上下文。 我们也上传了原生 **1M 上下文长度** 并通过 YaRN 扩展，以及全精度 8bit 和 16bit 版本。 [Unsloth](https://github.com/unslothai/unsloth) 现在还支持微调和 [RL](/docs/zh/kuai-su-kai-shi/reinforcement-learning-rl-guide.md) 的 Qwen3-Coder。 {% hint style="success" %} [**更新：** 我们修复了 Qwen3-Coder 的工具调用！ ](#tool-calling-fixes)现在你可以在 llama.cpp、Ollama、LMStudio、Open WebUI、Jan 等中无缝使用工具调用。这个问题是通用的，影响了所有上传内容（不只是 Unsloth），我们也已就我们的修复与 Qwen 团队沟通！ [阅读更多](#tool-calling-fixes) {% endhint %} 运行 30B-A3B运行 480B-A35B {% hint style="success" %} **是否** [**Unsloth 动态量化**](/docs/zh/ji-chu-zhi-shi/dynamic-3.0-ggufs.md) **有效吗？** 是的，而且效果非常好。在第三方对 Aider Polyglot 基准的测试中， **UD-Q4\_K\_XL（276GB）** 动态量化几乎达到了 **完整 bf16（960GB）** Qwen3-coder 模型的表现，得分 60.9%，对比 61.8%。 [更多详情见此处。](https://huggingface.co/unsloth/Qwen3-Coder-480B-A35B-Instruct-GGUF/discussions/8) {% endhint %} #### **Qwen3 Coder - Unsloth Dynamic 2.0 GGUF 文件**: | Dynamic 2.0 GGUF（用于运行） | 1M 上下文 Dynamic 2.0 GGUF | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | | ## 🖥️ **运行 Qwen3-Coder** 下面是该 [**30B-A3B**](#run-qwen3-coder-30b-a3b-instruct) 和 [**480B-A35B**](#run-qwen3-coder-480b-a35b-instruct) 模型的变体。 ### :gear: 推荐设置 Qwen 建议这两个模型使用以下推理设置： `temperature=0.7`, `top_p=0.8`, `top_k=20`, `repetition_penalty=1.05` * **温度为 0.7** * Top\_K 为 20 * Min\_P 设为 0.00（可选，但 0.01 效果也不错，llama.cpp 默认值是 0.1） * Top\_P 为 0.8 * **重复惩罚为 1.05** * 聊天模板： ``` <|im_start|>user 嘿！<|im_end|> <|im_start|>assistant 1+1 等于多少？<|im_end|> <|im_start|>user 2<|im_end|> <|im_start|>assistant ``` * 推荐的上下文输出：65,536 个 token（可增加）。详情见此处。 **未渲染换行符的聊天模板/提示格式** {% code overflow="wrap" %} ``` <|im_start|>user\nHey there!<|im_end|>\n<|im_start|>assistant\nWhat is 1+1?<|im_end|>\n<|im_start|>user\n2<|im_end|>\n<|im_start|>assistant\n ``` {% endcode %} **用于工具调用的聊天模板** （获取旧金山当前温度）。有关如何格式化工具调用的更多详情见此处。 ``` <|im_start|>user 现在旧金山的温度是多少？那明天呢？<|im_end|> <|im_start|>assistant \n\n\nSan Francisco, CA, USA \n\n<|im_end|> <|im_start|>user {"temperature": 26.1, "location": "San Francisco, CA, USA", "unit": "celsius"} \n<|im_end|> ``` {% hint style="info" %} 提醒一下，这个模型仅支持非思考模式，并且不会生成 `` 块输出。同时，指定 `enable_thinking=False` 已不再需要。 {% endhint %} ### 运行 Qwen3-Coder-30B-A3B-Instruct： 为了让我们的动态 4-bit 量化达到每秒 6+ token 的推理速度，至少需要 **18GB 的统一内存** （合并的 VRAM 和 RAM）或 **18GB 的系统内存** 即可。一般来说，可用内存应与所用模型的大小相当或更高。例如，UD\_Q8\_K\_XL 量化版（全精度）大小为 32.5GB，至少需要 **33GB 的统一内存** （VRAM + RAM）或 **33GB 的内存** 才能获得最佳性能。 **注意：** 模型可以在少于其总大小的内存上运行，但这会降低推理速度。只有为了获得最快速度才需要最大内存。 鉴于这是一个非思考型模型，无需设置 `thinking=False` 并且模型不会生成 ` ` 块。 {% hint style="info" %} 遵循 [**上面的最佳实践**](#recommended-settings)。它们与 480B 模型相同。 {% endhint %} #### 🦙 Ollama：运行 Qwen3-Coder-30B-A3B-Instruct 教程 1. 安装 `ollama` 如果你还没有安装的话！你只能运行参数规模不超过 32B 的模型。 ```bash apt-get update apt-get install pciutils -y curl -fsSL https://ollama.com/install.sh | sh ``` 2. 运行模型！注意，如果失败，你可以在另一个终端中调用 `ollama serve`！我们把所有修复和建议参数（温度等）都包含在 `params` 中，位于我们上传到 Hugging Face 的文件里！ ```bash ollama run hf.co/unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF:UD-Q4_K_XL ``` #### :sparkles: Llama.cpp：运行 Qwen3-Coder-30B-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-Coder-30B-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 --repeat-penalty 1.05 ``` 3. 通过以下方式下载模型（在安装 `pip install huggingface_hub hf_transfer` ）。你可以选择 UD\_Q4\_K\_XL 或其他量化版本。如果下载卡住，请参见 [Hugging Face Hub、XET 调试](/docs/zh/ji-chu-zhi-shi/troubleshooting-and-faqs/hugging-face-hub-xet-debugging.md) ```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-Coder-30B-A3B-Instruct-GGUF", local_dir = "unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF", allow_patterns = ["*UD-Q4_K_XL*"], ) ``` ### 运行 Qwen3-Coder-480B-A35B-Instruct： 为了让我们的 1-bit 量化达到每秒 6+ token 的推理速度，我们建议至少使用 **150GB 的统一内存** （合并的 VRAM 和 RAM）或 **150GB 的系统内存** 即可。一般来说，可用内存应与所用模型的大小相当或更高。例如，Q2\_K\_XL 量化版大小为 180GB，至少需要 **180GB 统一内存** （VRAM + RAM）或 **180GB RAM** 才能获得最佳性能。 **注意：** 模型可以在少于其总大小的内存上运行，但这会降低推理速度。只有为了获得最快速度才需要最大内存。 {% hint style="info" %} 遵循 [**上面的最佳实践**](#recommended-settings)。它们与 30B 模型相同。 {% endhint %} #### 📖 Llama.cpp：运行 Qwen3-Coder-480B-A35B-Instruct 教程 对于 Coder-480B-A35B，我们将专门使用 Llama.cpp 进行优化推理，并提供丰富的选项。 {% hint style="success" %} 如果你想要一个 **完整精度、未量化版本**，请使用我们的 `Q8_K_XL, Q8_0` 或 `BF16` 版本！ {% endhint %} 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. 你可以直接使用 llama.cpp 下载模型，但我通常建议使用 `huggingface_hub` 要直接使用 llama.cpp，请执行： ```bash ./llama.cpp/llama-cli \\ -hf unsloth/Qwen3-Coder-480B-A35B-Instruct-GGUF:Q2_K_XL \ --ctx-size 16384 \ --n-gpu-layers 99 \ -ot ".ffn_.*_exps.=CPU" \\ --temp 0.7 \\ --min-p 0.0 \ --top-p 0.8 \ --top-k 20 \ --repeat-penalty 1.05 ``` 3. 或者，在安装 `pip install huggingface_hub hf_transfer` ）。你可以选择 UD-Q2\_K\_XL，或其他量化版本。。 ```python # !pip install huggingface_hub hf_transfer import os os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "0" # 有时可能会触发速率限制，因此将其设为 0 以禁用 from huggingface_hub import snapshot_download snapshot_download( repo_id = "unsloth/Qwen3-Coder-480B-A35B-Instruct-GGUF", local_dir = "unsloth/Qwen3-Coder-480B-A35B-Instruct-GGUF", allow_patterns = ["*UD-Q2_K_XL*"], ) ``` 4. 在对话模式下运行模型并尝试任何提示。 5. 编辑 `--threads -1` CPU 线程数， `--ctx-size` 262114 作为上下文长度， `--n-gpu-layers 99` 用于 GPU 卸载的层数。如果你的 GPU 显存不足，请尝试调整它。如果你只使用 CPU 推理，也请将其移除。 {% hint style="success" %} 使用 `-ot ".ffn_.*_exps.=CPU"` 将所有 MoE 层卸载到 CPU！这实际上使你能够在 1 张 GPU 上容纳所有非 MoE 层，从而提升生成速度。如果你有更多 GPU 容量，可以自定义正则表达式以容纳更多层。更多选项如下所述 [这里](#improving-generation-speed). {% endhint %} {% code overflow="wrap" %} ```bash ./llama.cpp/llama-cli \\ --model unsloth/Qwen3-Coder-480B-A35B-Instruct-GGUF/UD-Q2_K_XL/Qwen3-Coder-480B-A35B-Instruct-UD-Q2_K_XL-00001-of-00004.gguf \ --ctx-size 16384 \ --n-gpu-layers 99 \ -ot ".ffn_.*_exps.=CPU" \\ --temp 0.7 \\ --min-p 0.0 \ --top-p 0.8 \ --top-k 20 \ --repeat-penalty 1.05 ``` {% endcode %} {% hint style="success" %} 也别忘了新的 Qwen3 更新。运行 [**Qwen3-235B-A22B-Instruct-2507**](/docs/zh/mo-xing/tutorials/qwen3-next.md) 并在本地使用 llama.cpp。 {% endhint %} #### :tools: 提升生成速度 如果你有更多 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 数据传输，这也可以让生成过程更快。 #### :triangular\_ruler:如何容纳长上下文（256K 到 1M） 要容纳更长的上下文，你可以使用 **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` 你也可以量化 V 缓存，但你需要 **通过以下方式编译支持 Flash Attention 的 llama.cpp** 支持，方法是使用 `-DGGML_CUDA_FA_ALL_QUANTS=ON`，并使用 `--flash-attn` 以启用它。 我们也通过 YaRN 缩放上传了 100 万上下文长度的 GGUF [这里](https://huggingface.co/unsloth/Qwen3-Coder-480B-A35B-Instruct-1M-GGUF). ## :toolbox: 工具调用修复 我们已通过以下方式修复工具调用： `llama.cpp --jinja` 专门用于通过 `llama-server`！如果你正在下载我们的 30B-A3B 量化版，无需担心，因为这些已包含我们的修复。对于 480B-A35B 模型，请： 1. 从 下载 UD-Q2\_K\_XL 的第一个文件，并替换你当前的文件 2. 使用 `snapshot_download` ，照常按 中所示操作，它会自动覆盖旧文件 3. 通过以下方式使用新的聊天模板： `--chat-template-file`。参见 [GGUF 聊天模板](https://huggingface.co/unsloth/Qwen3-Coder-480B-A35B-Instruct-GGUF?chat_template=default) 或 [chat\_template.jinja](https://huggingface.co/unsloth/Qwen3-Coder-480B-A35B-Instruct/raw/main/chat_template.jinja) 4. 此外，我们还制作了一个单独的 150GB UD-IQ1\_M 文件（这样 Ollama 就能工作），地址为 这应该能解决如下问题： ### 使用工具调用 为了格式化工具调用的提示，我们用一个示例来展示。 我创建了一个名为 `get_current_temperature` 它是一个应该获取某个地点当前温度的函数。暂时我们创建了一个占位函数，它总会返回 21.6 摄氏度。你应该把它改成真正的函数！！ {% code overflow="wrap" %} ```python def get_current_temperature(location: str, unit: str = "celsius"): """获取某个地点的当前温度。 参数： location：要获取温度的地点，格式为“城市，州，国家”。 unit：返回温度所使用的单位。默认值为“celsius”。（可选值：["celsius", "fahrenheit"]） 返回： 以字典形式返回温度、地点和单位 """ return { "temperature": 26.1, # 预先配置 -> 你来修改它！ "location": location, "unit": unit, } ``` {% endcode %} 然后使用 tokenizer 来创建完整提示： {% code overflow="wrap" %} ```python from transformers import AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("unsloth/Qwen3-Coder-480B-A35B-Instruct") messages = [ {'role': 'user', 'content': "What's the temperature in San Francisco now? How about tomorrow?"}, {'content': "", 'role': 'assistant', 'function_call': None, 'tool_calls': [ {'id': 'ID', 'function': {'arguments': {"location": "San Francisco, CA, USA"}, 'name': 'get_current_temperature'}, 'type': 'function'}, ]}, {'role': 'tool', 'content': '{"temperature": 26.1, "location": "San Francisco, CA, USA", "unit": "celsius"}', 'tool_call_id': 'ID'}, ] prompt = tokenizer.apply_chat_template(messages, tokenize = False) ``` {% endcode %} ## :bulb:性能基准 {% hint style="info" %} 这些官方基准适用于完整的 BF16 检查点。要使用它，只需使用 `Q8_K_XL, Q8_0, BF16` 我们上传的检查点——你仍然可以对这些版本使用 MoE 卸载等技巧！ {% endhint %} 以下是 480B 模型的基准： #### 代理式编码
基准Qwen3‑Coder 480B‑A35B‑InstructKimi‑K2DeepSeek‑V3-0324Claude 4 SonnetGPT‑4.1
Terminal‑Bench37.530.02.535.525.3
SWE‑bench Verified w/ OpenHands (500 turns)69.6––70.4–
SWE‑bench Verified w/ OpenHands (100 turns)67.065.438.868.048.6
SWE‑bench Verified w/ Private Scaffolding–65.8–72.763.8
SWE‑bench Live26.322.313.027.7–
SWE‑bench Multilingual54.747.313.053.331.5
Multi‑SWE‑bench mini25.819.87.524.8–
Multi‑SWE‑bench flash27.020.7–25.0–
Aider‑Polyglot61.860.056.956.452.4
Spider231.125.212.831.116.5
#### 代理式浏览器使用
基准Qwen3‑Coder 480B‑A35B‑InstructKimi‑K2DeepSeek‑V3 0324Claude Sonnet‑4GPT‑4.1
WebArena49.947.440.051.144.3
Mind2Web55.842.736.047.449.6
#### 代理式工具使用
基准Qwen3‑Coder 480B‑A35B‑InstructKimi‑K2DeepSeek‑V3 0324Claude Sonnet‑4GPT‑4.1
BFCL‑v368.765.256.973.362.9
TAU‑Bench 零售77.570.759.180.5–
TAU‑Bench 航空60.053.540.060.0–
--- # 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-coder-how-to-run-locally.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.