> 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 - 如何本地运行

Moonshot AI 的 Kimi K3 是一个 2.8T 参数的开放权重模型（104B 活跃参数），专为最先进的编程、智能体、长上下文和聊天工作负载打造。它是 **最强的开源模型** 迄今为止，可与 Claude 4.8 Opus 和 GPT-5.6 相媲美。Kimi K3 具备原生视觉能力、100万 token 的上下文窗口，并使用 MXFP4。全精度推理需要 1.56 TB 存储，而 1 位 Kimi K3 [Unsloth](https://github.com/unslothai/unsloth) 动态 GGUF 需要 **594 GB（减少 62%）**.

{% columns %}
{% column %}
动态 1 位（见右）达到 **\~78.9%** top-1 准确率，同时 **缩小 62%**。动态 2 位 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 位为 553.2 GiB）。

<a href="/pages/5b05e4653b1bff8c668dedc50b55c1adb50beb16" class="button primary">运行 Kimi K3 教程</a><a href="/pages/5b05e4653b1bff8c668dedc50b55c1adb50beb16#usage-guide" class="button secondary">量化结果</a>
{% endcolumn %}

{% column %}

<figure><img src="/files/21c74ffdc484c220cf92c5b01b6de7ff27c8b4f2" alt=""><figcaption><p>1 位 Kimi K3 GGUF vs Claude 5 vs GPT 5.6</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

**表：硬件需求** （单位 = 总内存：RAM + VRAM，或统一内存）

| 动态 1 位 S | 动态 1 位 M | 动态 2 位 XXS | 动态 2 位 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) 进行了构建，其中包含视觉支持和一些错误修复。

1. mmproj / vision tower 与 Kimi-K2.5 的 tower 类似，但使用了 RMSNorm、没有偏置、非方形融合 QKV（qkv 宽度 != n\_embd）以及一个后归一化 projector。
2. 我们发现，在运行 llama.cpp 时， `n_tokens * 40` 预算在大 batch size 下失效，因此我们不得不提高到 `n_tokens * 160`&#x20;
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` 类似，只是其余部分的一些张量（除 norm 等之外）是 `Q8_0`，因此它接近全精度，并需要 1.56 TB RAM/VRAM。 `UD-Q8_K_XL` 相较于 MXFP4 完整 safetensors 版本，它是真正的“无损”。

<table><thead><tr><th width="119.20001220703125">量化</th><th width="71.60000610351562" align="right">GB</th><th width="124.800048828125" align="right">平均 KLD</th><th width="104.9998779296875" align="right">PPL(q)</th><th width="188.79998779296875" align="right">top-1 一致率 %</th><th width="140.20001220703125" align="right">RMS dp %</th></tr></thead><tbody><tr><td><code>UD-IQ1_S</code></td><td align="right">594.0</td><td align="right">0.5645</td><td align="right">2.5789</td><td align="right">78.875 +/- 0.107</td><td align="right">36.495</td></tr><tr><td><code>UD-IQ1_M</code></td><td align="right">648.9</td><td align="right">0.4789</td><td align="right">2.3639</td><td align="right">81.219 +/- 0.103</td><td align="right">33.629</td></tr><tr><td><code>UD-IQ2_XXS</code></td><td align="right">711.1</td><td align="right">0.3784</td><td align="right">2.1266</td><td align="right">84.127 +/- 0.096</td><td align="right">29.826</td></tr><tr><td><code>UD-Q2_K_XL</code></td><td align="right">861.3</td><td align="right">0.1779</td><td align="right">1.7359</td><td align="right">90.390 +/- 0.077</td><td align="right">19.862</td></tr><tr><td><code>UD-Q4_K_XL</code></td><td align="right">1,510</td><td align="right"></td><td align="right">1.4579</td><td align="right"></td><td align="right"></td></tr><tr><td><code>UD-Q8_K_XL</code></td><td align="right">1,560</td><td align="right"></td><td align="right">1.4581</td><td align="right"></td><td align="right"></td></tr></tbody></table>

在 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 位量化，但其困惑度飙升到 54.56——差 21 倍。相同的模式也适用于 `IQ2_XXS`：725 GB 时 PPL 为 96，而我们的 711 GB 仅为 2.12 PPL——差 45 倍，这意味着他们的 2 位表现甚至比 1 位还差。这凸显了动态量化 + 正确校准的重要性。

**我们还提供 Top-1% 准确率、KLD 图：**

<div><figure><img src="/files/8b44449397a21175a7fcbf0fe77c1c54d8749637" alt=""><figcaption></figcaption></figure> <figure><img src="/files/4b8a698cf0b51e9c0520b1eb7df6847e7f999730" alt=""><figcaption></figcaption></figure> <figure><img src="/files/6ce8db4bc376d874c08571c721bed7a120648840" alt=""><figcaption></figcaption></figure></div>

### :gear: 使用指南

Kimi K3 是 **仅思考**，并且 **`preserve_thinking` 始终启用** 和 **最大** 默认开启思考。不支持即时模式。思考强度通过 `reasoning_effort` 请求字段进行配置，且 K3 支持 `"低"`, `"高"`，以及 `"最大"` 种思考强度。

| 默认                | 智能体               |
| ----------------- | ----------------- |
| temperature = 1.0 | temperature = 1.0 |
| top\_p = 0.95     | top\_p = 1.0      |

* 上下文长度 = 最多可达 `1,048,576`
* 低、高、最大思考可在 Unsloth 中切换

如果模型能装下，使用 B200 时你会得到约 20 token/s 的生成速度，以及 >120 token/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)。我们将使用 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) 参数调优（temp、top-p 等）
* 通过 llama.cpp 实现快速 CPU + GPU 推理
* [训练 LLM](/docs/zh/xin/studio.md#no-code-training) 速度提升 2 倍，VRAM 减少 70%
  {% endcolumn %}

{% column %}

<figure><img src="/files/d9bdf80905cb5e7edbce0a01521e71d9a20801a3" alt=""><figcaption></figcaption></figure>
{% 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).

<a href="https://unsloth.ai/download" class="button primary" data-icon="down-to-bracket">下载 Unsloth</a>

* <i class="fa-apple">:apple:</i> [下载 macOS 版](https://unsloth.ai/download/mac)
* <i class="fa-windows">:windows:</i> [下载 Windows 版](https://unsloth.ai/download/windows)
* <i class="fa-linux">:linux:</i> [下载 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** 在搜索栏中下载你想要的模型和量化版本。请确保你有足够的计算资源来运行该模型。

<figure><img src="/files/8219b138541e0fe7c279bcfdb875208fad0d4999" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**运行 Kimi K3**

使用 Unsloth Studio 时，推理参数应会自动设置，不过你仍可手动更改。你还可以切换 **低、高或最大思考**，编辑上下文长度、聊天模板和其他设置。

如需更多信息，你可以查看我们的 [Unsloth Studio 推理指南](/docs/zh/xin/studio/chat.md).

<figure><img src="/files/d9bdf80905cb5e7edbce0a01521e71d9a20801a3" alt=""><figcaption><p>在 Unsloth 的 Canvas 中运行 1 位 Kimi-K3 的示例</p></figcaption></figure>
{% 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 %}
获取以下 SPECIFIC 的 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 %}

<figure><img src="/files/99e6294684309cf45754d5010bc1bff5c7da4548" alt="" width="188"><figcaption></figcaption></figure>

我们来获取第二张图片 [这里](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 %}

<figure><img src="/files/dfadcc899fed5f74e2966aa94681fc7f2b43caa2" alt="" width="188"><figcaption></figcaption></figure>
{% 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/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 %}
然后你将看到：

<figure><img src="/files/6f0237c197411d19d5e7a24fa6a4c504ca178a70" alt=""><figcaption></figcaption></figure>

然后我问：“-1 的平方根是什么”：

<figure><img src="/files/aa488548f6732e5b3dbcee81402969535ac42642" alt=""><figcaption></figcaption></figure>

Kimi K3 也支持图像，例如加载 Unsloth 图片：

<figure><img src="/files/f823b4dbf3438bf4738867c456efde7aaca6f270" alt=""><figcaption></figcaption></figure>

然后我们使用树懒图片，并询问它与什么相关：

<figure><img src="/files/5b3bc969d39f3091b5ccbb393c4de10c2643f063" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

### 📊 基准测试

你可以在下方查看表格式基准：

<div><figure><img src="/files/07594148f90cfef9505cab6b75cef5ea6fd4c642" alt=""><figcaption></figcaption></figure> <figure><img src="/files/2bc708c978e53ce651276e4a8c79d19d804fd96d" alt=""><figcaption></figcaption></figure></div>

|         基准         | Kimi K3&#xA;(最大) | Claude Fable 5&#xA;(最大) | GPT-5.6 Sol&#xA;(最大) | Claude Opus 4.8&#xA;(最大) | GPT-5.5&#xA;(xhigh) | GLM-5.2&#xA;(最大) |
| :----------------: | :--------------: | :---------------------: | :------------------: | :----------------------: | :-----------------: | :--------------: |
|      **推理与知识**     |                  |                         |                      |                          |                     |                  |
|    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 表现非常高效！

<figure><img src="/files/ade206849cf2a7e91a3c1c5fc221a76f60f7aff0" alt=""><figcaption></figcaption></figure>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://unsloth.ai/docs/zh/mo-xing/kimi-k3.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.