> 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/kimi-k3.md). # Kimi K3 - 如何在本地运行 在你的本地环境中运行 Kimi K3 量化模型指南。 月之暗面 Moonshot AI 推出的 Kimi K3 是一款 2.8T 参数的开放权重模型（104B 激活），专为最先进（SOTA）的代码、Agent、长上下文和聊天工作负载而构建。它是 **最强的开源模型** 迄今为止，可与 Claude 4.8 Opus 和 GPT-5.6 抗衡。Kimi K3 原生支持视觉，拥有 100 万 token 的上下文窗口，并使用 MXFP4。全精度推理需要 1.56 TB 存储，而 1-bit Kimi K3 [Unsloth](https://github.com/unslothai/unsloth) 动态 GGUF 需要 **594 GB（减少 62%）**. {% columns %} {% column %} 动态 1-bit（见右）可达到 **\~78.9%** top-1 准确率，同时 **小 62%**. 动态 2-bit 861.3GB 可达到 **\~90%** 的准确率，同时体积缩小 **缩小 45%**. 运行 [**Kimi-K3-GGUF**](https://huggingface.co/unsloth/Kimi-K3-GGUF) 通过 [Unsloth Studio](/docs/zh/xin/studio.md) 或 llama.cpp。Kimi K3 可以运行在 NVIDIA DGX Station 上，或连接到 128GB RAM 设备的 Mac Studio 上。 对于 **无损** Kimi K3，请使用 Q8（`UD-Q8_K_XL`），它比 **大 50GB** 比 Q4（`UD-Q4_K_XL`）。我们仍在研究是否能在不损坏模型的情况下将其压到 512GiB 以下（动态 1-bit 为 553.2 GiB）。 Kimi K3 运行教程量化结果 {% endcolumn %} {% column %}

1-bit Kimi K3 GGUF 对比 Claude 5 和 GPT 5.6

{% endcolumn %} {% endcolumns %} **表：硬件要求** （单位 = 总内存：RAM + VRAM，或统一内存） | 动态 1-bit S | 动态 1-bit M | 动态 2-bit XXS | 动态 2-bit XL | Q8（无损） | | ---------- | ---------- | ------------ | ----------- | ------ | | 610 GB | 665 GB | 726 GB | 880 GB | 1.6 TB | ### Kimi K3 GGUF 实现细节 我们基于 [llama.cpp 的 PR](https://github.com/ggml-org/llama.cpp/pull/26185) 替换为 [我们的分支](https://github.com/unslothai/llama.cpp/pull/48) 其中包含视觉支持和一些 bug 修复。 1. mmproj / 视觉塔与 Kimi-K2.5 的塔类似，但采用 RMSNorm、无偏置、非方阵融合 QKV（qkv 宽度 != n\_embd）以及 post-norm 投影器。 2. 我们发现，在运行 llama.cpp 时， `n_tokens * 40` 预算在大批量大小下失效，因此我们不得不提升到 `n_tokens * 160` 3. 我们还不得不将 Kimi 聊天模板转换为 jinja 格式。 4. 我们尽可能进行了测试以覆盖所有情况。Kimi 默认训练时采用了 **开启了保留思考**，因此所有思考轨迹都不会被删除，而是会保留。 ### 📊 量化分析 像 Kimi [K2.6](/docs/zh/mo-xing/kimi-k2.6.md) 和 [K2.7](/docs/zh/mo-xing/kimi-k2.7-code.md)一样，K3 的 `UD-Q8_K_XL` 是无损的，因为 Kimi 对 MoE 权重使用 MXFP4，对其他所有部分使用 BF16，并且 `Q8_K_XL` 完全遵循这一点。 `UD-Q4_K_XL` 与此类似，只是其余部分的一些张量（除 norms 等之外）是 `Q8_0`，因此接近全精度，并且需要 1.56 TB 的 RAM/VRAM。 `UD-Q8_K_XL` 相较于 MXFP4 完整 safetensors 版本，这是“真正无损”的。
量化GB平均 KLDPPL(q)top-1 一致率 %RMS dp %
UD-IQ1_S594.00.56452.578978.875 +/- 0.10736.495
UD-IQ1_M648.90.47892.363981.219 +/- 0.10333.629
UD-IQ2_XXS711.10.37842.126684.127 +/- 0.09629.826
UD-Q2_K_XL861.30.17791.735990.390 +/- 0.07719.862
UD-Q4_K_XL1,5101.4579
UD-Q8_K_XL1,5601.4581
在生成 imatrix 和量化时，我们使用了 1.56 TB 的无损 `UD-Q8_K_XL` 版本进行全程校准；其困惑度为 1.4581。我们的 Dynamic-1bit 量化困惑度达到 2.58，top-1 准确率为 79%，使其出人意料地可用。 其他社区量化版本体积更大，但退化得更严重。例如，有一个 618.9 GB 的量化 `IQ1_M` 超过了我们的 594 GB 1-bit 量化，但其困惑度飙升至 54.56——差了 21 倍。相同的模式也适用于 `IQ2_XXS`：725 GB 时 PPL 为 96，而我们的 711 GB 时 PPL 为 2.12——差了 45 倍，这意味着他们的 2-bit 表现甚至比 1-bit 还差。这凸显了动态量化 + 正确校准的重要性。 **我们还提供 Top-1% 准确率、KLD 图：**
### :gear: 使用指南 Kimi K3 是 **仅思考**，并且 **`preserve_thinking` 始终启用** 和 **最大** 思考默认开启。不支持即时模式。思考强度通过 `reasoning_effort` 请求字段进行配置，且 K3 支持 `“low”`, `“high”`，以及 `“max”` 种思考强度。 | 默认值 | 智能体 | | ----------------- | ----------------- | | temperature = 1.0 | temperature = 1.0 | | top\_p = 0.95 | top\_p = 1.0 | * 上下文长度 = 最多 `1,048,576` * 在 Unsloth 中可切换 Low、High、Max Thinking 如果模型能放得下，使用 B200 时生成速度约为 \~20 tokens/s，吞吐量可超过 120 tokens/s。我们推荐 [`UD-IQ1_S`](https://huggingface.co/unsloth/Kimi-K3-GGUF?show_file_info=UD-IQ1_S%2FKimi-K3-UD-IQ1_S-00001-of-00015.gguf) （594GB）作为尺寸/质量平衡的良好选择。最经验法则：RAM+VRAM ≈ 量化大小；否则它仍然能工作，只是由于磁盘卸载会慢得多。 ## Kimi K3 运行指南 你现在可以在 [llama.cpp](#run-in-llama.cpp) 和 [Unsloth Desktop](https://unsloth.ai/docs/zh/mo-xing/pages/986f178fb44971bd081c36c351922d60469ba3ee#run-glm-5.2-in-unsloth-studio)中运行 Kimi K3。我们将使用 594GB [`UD-IQ1_S`](https://huggingface.co/unsloth/Kimi-K3-GGUF?show_file_info=UD-IQ1_S%2FKimi-K3-UD-IQ1_S-00001-of-00015.gguf) 的量化版本，以在可访问性和准确性方面获得最佳结果，并且至少需要 610GB RAM。可随意更改量化类型。GGUF： [**Kimi-K3-GGUF**](https://huggingface.co/unsloth/Kimi-K3-GGUF) ### 🦥 在 Unsloth 中运行 Kimi-K3 Kimi K3 可以运行在 [Unsloth Desktop](/docs/zh/desktop.md)，一个用于本地 AI 的开源桌面 UI。 **Unsloth Desktop 会自动卸载到 RAM，并检测多 GPU 配置**。使用 Unsloth Studio，你可以在本地运行模型 **MacOS、Windows**、Linux 以及： {% columns %} {% column %} * 搜索、下载、 [运行 GGUF](/docs/zh/xin/studio.md#run-models-locally) 和 safetensor 模型 * [**自修复** 工具调用](/docs/zh/xin/studio.md#execute-code--heal-tool-calling) + **网页搜索** * [**代码执行**](/docs/zh/xin/studio.md#run-models-locally) （Python、Bash） * [自动推理](https://unsloth.ai/docs/desktop#feature-deep-dive) 参数调优（温度、top-p 等） * 通过 llama.cpp 实现快速 CPU + GPU 推理 * [训练 LLM](/docs/zh/xin/studio.md#no-code-training) 速度快 2 倍，VRAM 占用减少 70% {% endcolumn %} {% column %}
{% endcolumn %} {% endcolumns %} {% stepper %} {% step %} **安装并启动 Unsloth** 最简单的上手方式是下载 [Unsloth Desktop 应用](/docs/zh/desktop.md)。支持 [macOS](/docs/zh/kuai-su-kai-shi/install/mac.md), [Windows](/docs/zh/kuai-su-kai-shi/install/windows-installation.md)，以及 [Linux](/docs/zh/kuai-su-kai-shi/install/linux.md). 下载 Unsloth * :apple: [下载 macOS 版](https://unsloth.ai/download/mac) * :windows: [下载 Windows 版](https://unsloth.ai/download/windows) * :linux: [下载 Linux 版](https://unsloth.ai/download/linux) 或者，如果你更喜欢手动安装： MacOS、Linux、WSL： ```bash curl -fsSL https://unsloth.ai/install.sh | sh ``` Windows PowerShell： ```bash irm https://unsloth.ai/install.ps1 | iex ``` **启动 Unsloth** MacOS、Linux、WSL 和 Windows： ```bash unsloth studio ``` 然后打开 `http://127.0.0.1:8888` （或你的特定 URL）在浏览器中打开。 **通过 HTTPS 和 Cloudflare 安全启动 Unsloth** **新！** Unsloth 现在通过免费的 Cloudflare 隧道，提供通过 HTTPS 安全启动 Unsloth 的方式。请使用下面的方法（适用于 Windows、Mac 和 Linux）： ```bash unsloth studio --secure ``` {% endstep %} {% step %} **搜索并下载 Kimi K3** Unsloth Studio 会自动卸载到 RAM，并检测多 GPU 配置。首次启动时，你需要创建一个密码来保护你的账户，并在之后重新登录。 然后前往 Model hub 标签页并搜索 **Kimi K3** ，然后在搜索栏中下载你想要的模型和量化版本。请确保你有足够的算力来运行该模型。
{% endstep %} {% step %} **运行 Kimi K3** 使用 Unsloth Studio 时推理参数应会自动设置，不过你仍然可以手动更改。你也可以切换 **low、high 或 max thinking**，编辑上下文长度、聊天模板和其他设置。 更多信息请查看我们的 [Unsloth Studio 推理指南](/docs/zh/xin/studio/chat.md).

1-bit Kimi-K3 使用 Unsloth Canvas 运行的示例

{% endstep %} {% endstepper %} ### 🦙 在 llama.cpp 中运行 Kimi K3 在这些教程中，我们将使用 [llama.cpp](https://github.com/ggml-org/llama.cpp) 进行快速本地推理，尤其是如果你有 CPU。我们 [创建了一个分支](https://github.com/unslothai/llama.cpp/pull/48) 专门用于支持 Kimi K3 视觉。因此，这建立在另一个 [llama.cpp 的 PR](https://github.com/ggml-org/llama.cpp/pull/26185). {% stepper %} {% step %} 获取以下的特定 Unsloth 分支 `llama.cpp` 在 [**GitHub 上获取**](https://github.com/unslothai/llama.cpp/pull/48) 以启用视觉支持。你也可以按照下面的构建说明操作。更改 `-DGGML_CUDA=ON` 改为 `-DGGML_CUDA=OFF` 如果你没有 GPU，或者只想使用 CPU 推理。 **对于 Apple Mac / Metal 设备**，设置 `-DGGML_CUDA=OFF` 然后按常规继续——Metal 支持默认开启。 ```bash git clone https://github.com/unslothai/llama.cpp cd llama.cpp git fetch origin pull/48/head:kimi-k3-fullsize-vision git checkout kimi-k3-fullsize-vision cd .. cmake llama.cpp -B llama.cpp/build \\ -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split cp llama.cpp/build/bin/llama-* llama.cpp ``` {% endstep %} {% step %} **先来获取一张图片！** 你也可以上传图片。我们将使用 [这张图片](https://raw.githubusercontent.com/unslothai/unsloth/refs/heads/main/images/unsloth%20made%20with%20love.png)，这只是我们的迷你标志，展示微调是如何借助 Unsloth 制作的： {% code overflow="wrap" %} ```bash wget https://raw.githubusercontent.com/unslothai/unsloth/refs/heads/main/images/unsloth%20made%20with%20love.png -O unsloth.png ``` {% endcode %}
让我们获取第二张图片 [这里](https://files.worldwildlife.org/wwfcmsprod/images/Sloth_Sitting_iStock_3_12_2014/story_full_width/8l7pbjmj29_iStock_000011145477Large_mini__1_.jpg) {% code overflow="wrap" %} ```bash wget https://files.worldwildlife.org/wwfcmsprod/images/Sloth_Sitting_iStock_3_12_2014/story_full_width/8l7pbjmj29_iStock_000011145477Large_mini__1_.jpg -O picture.png ``` {% endcode %}
{% endstep %} {% step %} 你现在可以使用 `llama.cpp` 直接加载和下载模型，就像 `ollama run`。首先，选择你想要的量化类型，例如 `IQ1_S`。同时使用 `export LLAMA_CACHE="folder"` 来强制 `llama.cpp` 保存到特定位置。 **请注意，此下载过程可能会非常慢**，因此最好使用下一节中的手动下载流程。 ```bash export LLAMA_CACHE="unsloth/Kimi-K3-GGUF" ./llama.cpp/llama-cli \\ -hf unsloth/Kimi-K3-GGUF:UD-IQ1_S \\ --temp 1.0 \\ --top-p 0.95 ``` {% endstep %} {% step %} 如果你想手动下载模型，我们可以通过下面的代码下载模型（在安装 `pip install huggingface_hub`）。如果下载卡住，请参见： [Hugging Face Hub、XET 调试](/docs/zh/ji-chu-zhi-shi/troubleshooting-and-faqs/hugging-face-hub-xet-debugging.md) ```bash hf download unsloth/Kimi-K3-GGUF \\ --local-dir unsloth/Kimi-K3-GGUF \\ --include "*mmproj-BF16*" \\ --include "*UD-IQ1_S*" # 全精度请使用 "*UD-Q8_K_XL*" ``` {% endstep %} {% step %} 然后在对话模式下运行模型： {% code overflow="wrap" %} ```bash ./llama.cpp/llama-cli \\ --model unsloth/Kimi-K3-GGUF/UD-IQ1_S/Kimi-K3-UD-IQ1_S-00001-of-00014.gguf \\ --mmproj unsloth/Kimi-K3-GGUF/mmproj-BF16.gguf \\ --temp 1.0 \\ --top-p 0.95 ``` {% endcode %} {% endstep %} {% step %} 然后你会看到：
然后我问：“-1 的平方根是多少”：
Kimi K3 也支持图片，例如加载 Unsloth 图片：
然后我们使用那张 sloth 图片并询问它有什么关联：
{% endstep %} {% endstepper %} ### 📊 基准测试 你可以在下方以表格形式查看更多基准测试：
| 基准 | Kimi K3 （max） | Claude Fable 5 （max） | GPT-5.6 Sol （max） | Claude Opus 4.8 （max） | GPT-5.5 （xhigh） | GLM-5.2 （max） | | :----------------: | :---------------: | :----------------------: | :-------------------: | :-----------------------: | :-----------------: | :---------------: | | **推理与知识** | | | | | | | | GPQA Diamond | 93.5 | 92.6 | **94.1** | 91.0 | 93.5 | 91.2 | | HLE-Full | 43.5 / 56.0 | **53.3 / 63.0** | 44.5 / 58.0 | 49.8 / 57.9 | 41.4 / 52.2 | — | | **编码** | | | | | | | | DeepSWE | 67.5 | 70.0 | **73.0** | 59.0 | 67.0 | 46.2 | | Terminal-Bench 2.1 | 88.3 | 88.0 | **88.8** | 84.6 | 83.4 | 82.7 | | **智能体** | | | | | | | | BrowseComp | **91.2** | 88.0 | 90.4 | 84.3 | 84.4 | — | | GDPval-AA v2（Elo） | 1686 | **1747** | 1736 | 1593 | 1491 | 1510 | | OSWorld 2.0 | 58.3 | **66.1** | 62.6 | 55.7 | 49.5 | — | | **视觉** | | | | | | | | MMMU-Pro | 81.6 / 83.4 | 81.2 / **86.5** | **83.0** / 84.6 | 78.9 / 82.7 | 81.2 / 83.2 | — | | MathVision | 94.3 / 97.8 | 94.8 / **98.6** | **95.8** / 97.8 | 86.7 / 97.1 | 92.2 / 96.8 | — | DeepSWE 基准显示 Kimi-K3 表现非常高效！
--- # 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/kimi-k3.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.