# Qwen3-Coder：如何本地运行 Qwen3-Coder 是 Qwen 的新一代编码代理模型系列，提供 30B（**Qwen3-Coder-Flash**）和 480B 参数。 **Qwen3-480B-A35B-Instruct** 在编码性能上达到了与 Claude Sonnet-4、GPT-4.1 相媲美的最新水平，和 [Kimi K2](https://unsloth.ai/docs/zh/mo-xing/tutorials/kimi-k2-thinking-how-to-run-locally)，在 Aider Polyglot 上得分 61.8%，并支持 256K（可扩展到 1M）的上下文长度。 我们还上传了具有原生 **1M 上下文长度** 由 YaRN 扩展的 Qwen3-Coder 以及全精度的 8bit 和 16bit 版本。 [Unsloth](https://github.com/unslothai/unsloth) 现在也支持微调和 [强化学习](https://unsloth.ai/docs/zh/kai-shi-shi-yong/reinforcement-learning-rl-guide) 的 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 动态量化**](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/unsloth-dynamic-2.0-ggufs) **有效？** 是的，而且效果很好。在第三方对 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 动态 2.0 GGUFs**: | 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 令牌（可增加）。详情见此处。 **聊天模板/提示格式（换行未渲染）** {% 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 位量化实现 6+ 令牌/秒 的推理速度，至少需要 **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`我们在 Hugging Face 上传中包含了所有修复和建议参数（如 temperature 等），位于 `params` 中！ ```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-debugging](https://unsloth.ai/docs/zh/ji-chu-zhi-shi/troubleshooting-and-faqs/hugging-face-hub-xet-debugging "mention") ```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 位量化达到 6+ 令牌/秒 的推理速度，我们建议至少具备 **150GB 的统一内存** （合并的 VRAM 和 RAM）或 **单独 150GB 的系统内存** 作为经验法则，你的可用内存应与所使用模型的大小相当或更大。例如，Q2\_K\_XL 量化为 180GB，将至少需要 **180GB 的统一内存** （VRAM + RAM）或 **180GB 的内存** 以获得最佳性能。 **注意：** 模型可以在低于其总大小的内存下运行，但这会降低推理速度。只有在追求最快速度时才需要最大内存。 {% 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！这实际上允许你将所有非 MoE 层放到 1 张 GPU 上，从而提高生成速度。如果你有更多 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**](https://unsloth.ai/docs/zh/mo-xing/tutorials/qwen3-next) 在本地使用 llama.cpp。 {% endhint %} #### :tools: "content": \[{"type": "text", "text": "用 Python 创建一个 Fibonacci 函数并求 fib(20)。"}], 如果你有更多显存，可以尝试卸载更多 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** 将 KV 缓存量化为 4 位 #### :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 缓存进行量化，但你需要 **在编译 llama.cpp 时启用 Flash Attention 支持** 通过 `-DGGML_CUDA_FA_ALL_QUANTS=ON`，并使用 `--flash-attn` 以启用它。 我们还通过 YaRN 缩放上传了 1 百万上下文长度的 GGUF 文件 [这里](https://app.gitbook.com/o/HpyELzcNe0topgVLGCZY/s/xhOjnexMCB3dmuQFQ2Zq/). ## :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` 的 Python 函数，该函数应获取某地的当前温度。目前我们创建了一个占位函数，会始终返回 21.6 摄氏度。你应将其更改为真实函数！！ {% code overflow="wrap" %} ```python def get_current_temperature(location: str, unit: str = "celsius"): """获取某地的当前温度。 参数： location：要获取温度的地点，格式为 "City, State, Country"。 unit：返回温度的单位。默认是 "celsius"。（选项：["celsius", "fahrenheit"]） 返回： 以字典形式返回温度、地点和单位 """ return { "temperature": 26.1, # 预配置 -> 你可以更改它！ "location": location, "unit": unit, } ``` {% endcode %} 然后使用分词器创建整个提示： {% 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 已通过 OpenHands 验证（500 回合）69.6––70.4–
SWE‑bench 已通过 OpenHands 验证（100 回合）67.065.438.868.048.6
SWE‑bench 已通过私有支撑验证–65.8–72.763.8
SWE‑bench 实时26.322.313.027.7–
SWE‑bench 多语种54.747.313.053.331.5
Multi‑SWE‑bench 迷你25.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–