🌙Kimi K2 Thinking：本地运行指南

关于在你自己的本地设备上运行 Kimi-K2-Thinking 和 Kimi-K2 的指南！

Kimi-K2-Thinking 已发布。阅读我们的 Thinking 指南 或访问 这里的 GGUF.

我们还与 Kimi 团队合作修复了 系统提示词修复 ，用于 Kimi-K2-Thinking。

Kimi-K2 和 Kimi-K2-Thinking 在知识、推理、编码和智能体任务上实现了 SOTA 表现。Moonshot AI 的完整 1T 参数模型需要 1.09TB 磁盘空间，而量化后的 Unsloth Dynamic 1.8-bit 版本将其减少到仅 230GB（体积缩小 80%）: Kimi-K2-GGUF

你现在还可以运行我们的 Kimi-K2-Thinking GGUF.

所有上传都使用 Unsloth Dynamic 2.0 ，以获得 SOTA Aider Polyglot 以及 5-shot MMLU 的表现。看看我们的 Dynamic 1–2 bit GGUF 在 编码基准测试中的表现.

运行 Thinking运行 Instruct

⚙️ 推荐要求

你需要 247GB 磁盘空间 来运行 1bit 量化！

唯一的要求是 磁盘空间 + RAM + VRAM ≥ 247GB。这意味着你不需要拥有那么多的 RAM 或 VRAM（GPU）来运行模型，但速度会慢很多。

1.8-bit（UD-TQ1_0）量化可以放入一张 24GB GPU 中（所有 MoE 层卸载到系统 RAM 或高速磁盘）。如果你还有额外的 256GB RAM，则在这种配置下预计速度约为 1-2 tokens/s。完整的 Kimi K2 Q8 量化大小为 1.09TB，至少需要 8 张 H200 GPU。

为了获得最佳性能，你至少需要 247GB 统一内存或 247GB 的 RAM+VRAM 总和 才能达到 5+ tokens/s。如果你的 RAM+VRAM 总和少于 247GB，那么模型速度肯定会受到影响。

如果你没有 247GB 的 RAM+VRAM，也没关系！ llama.cpp 天生支持 磁盘卸载，因此通过 mmap，它仍然可以工作，只是会更慢——例如以前你可能能达到每秒 5 到 10 个 token，现在则低于 1 个 token。

我们建议使用我们的 UD-Q2_K_XL（360GB） 量化，以平衡体积和准确性！

为了获得最佳性能，请让你的 VRAM + RAM 总和 = 你下载的量化版本大小。如果不满足，它仍然可以通过磁盘卸载运行，只是会更慢！

💭Kimi-K2-Thinking 指南

Kimi-K2-Thinking 通常应遵循与 Instruct 模型相同的说明，但有几个关键差异，尤其是在设置和聊天模板方面。

要以完全精度运行模型，你只需要使用 4-bit 或 5-bit 的 Dynamic GGUF（例如 UD_Q4_K_XL），因为该模型最初就是以 INT4 格式发布的。

你也可以选择更高位宽的量化，以防量化差异很小而更稳妥，但在大多数情况下这是不必要的。

🌙 官方推荐设置：

根据 Moonshot AI，以下是 Kimi-K2-Thinking 推理的推荐设置：

• 将 temperature 1.0 以减少重复和不连贯。

• 建议上下文长度 = 98,304（最高可达 256K）

• 注意：使用不同工具可能需要不同设置

我们建议将 min_p 设为 0.01 ，以抑制低概率、不太可能出现的 token。

例如，给定用户消息“1+1 等于多少？”，我们得到：

<|im_system|>system<|im_middle|>You are Kimi, an AI assistant created by Moonshot AI.<|im_end|><|im_user|>user<|im_middle|>What is 1+1?<|im_end|><|im_assistant|>assistant<|im_middle|>

✨ 在 llama.cpp 中运行 Kimi K2 Thinking

你现在可以使用最新更新的 llama.cpp 来运行模型：

1. 获取最新的 llama.cpp 在 GitHub 这里。你也可以按照下面的构建说明操作。将 -DGGML_CUDA=ON 改为 -DGGML_CUDA=OFF 如果你没有 GPU，或者只想进行 CPU 推理。 对于 Apple Mac / Metal 设备，设置 -DGGML_CUDA=OFF 然后照常继续——Metal 支持默认开启。

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-quantize llama-cli llama-gguf-split llama-mtmd-cli
cp llama.cpp/build/bin/llama-* llama.cpp

1. 如果你想使用 llama.cpp 直接加载模型，你可以使用下面的方法：（:UD-TQ1_0）是量化类型。你也可以通过 Hugging Face 下载（见第 3 点）。这与以下方式类似 ollama run 。使用 export LLAMA_CACHE="folder" 来强制 llama.cpp 用于保存到特定位置。

export LLAMA_CACHE="unsloth/Kimi-K2-Thinking-GGUF"
./llama.cpp/llama-cli \
    -hf unsloth/Kimi-K2-Thinking-GGUF:UD-TQ1_0 \\
    --n-gpu-layers 99 \\
    --temp 1.0 \
    --min-p 0.01 \
    --ctx-size 16384 \
    --seed 3407 \
    -ot ".ffn_.*_exps.=CPU"

1. 以上将使用大约 8GB 的 GPU 内存。如果你有大约 360GB 的 GPU 总内存，请移除 -ot ".ffn_.*_exps.=CPU" 以获得最大速度！

请试试 -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 ".ffn_.*_exps.=CPU" 这使用的 VRAM 最少。

你也可以自定义正则表达式，例如 -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 层。

1. 通过以下方式下载模型（在安装 pip install huggingface_hub hf_transfer ）。我们建议使用我们的 2bit 动态量化 UD-Q2_K_XL 来平衡体积和准确性。所有版本见： huggingface.co/unsloth/Kimi-K2-Thinking-GGUF

# !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/Kimi-K2-Thinking-GGUF",
    local_dir = "unsloth/Kimi-K2-Thinking-GGUF",
    allow_patterns = ["*UD-TQ1_0*"], # 动态 2bit 请使用 "*UD-Q2_K_XL*"（381GB）
)

如果你发现下载卡在 90% 到 95% 左右，请查看 https://docs.unsloth.ai/basics/troubleshooting-and-faqs#downloading-gets-stuck-at-90-to-95

1. 运行任意提示词。

2. 编辑 --threads -1 用于指定 CPU 线程数（默认设置为 CPU 的最大线程数）， --ctx-size 16384 来设置上下文长度， --n-gpu-layers 99 用于 GPU 卸载的层数。将其设为 99，并配合 MoE CPU 卸载，以获得最佳性能。如果你的 GPU 显存不足，请尝试调整它。如果你只进行 CPU 推理，也请移除它。

./llama.cpp/llama-cli \
    --model unsloth/Kimi-K2-Thinking-GGUF/UD-TQ1_0/Kimi-K2-Thinking-UD-TQ1_0-00001-of-00006.gguf \\
    --n-gpu-layers 99 \\
    --temp 1.0 \
    --min-p 0.01 \
    --ctx-size 16384 \
    --seed 3407 \
    -ot ".ffn_.*_exps.=CPU"

🤔没有 Thinking 标签？

你可能会注意到，在运行模型时没有 thinking 标签。这是正常且预期的行为。

在你的 llama.cpp 脚本中，请确保在命令的最后添加 --special 标志。一旦这样做，你就会看到 <think> token 如预期出现。

你也可能会看到每个回答都以 <|im_end|>结尾。这是正常的，因为 <|im_end|> 是一个特殊 token，在打印特殊 token 时会出现。如果你想隐藏它，可以在设置中将 <|im_end|> 设为停止字符串。

✨ 使用 llama-server 和 OpenAI 的 completion 库进行部署

按照 Kimi K2 Thinking安装 llama.cpp 后，你可以使用下面的方法启动一个兼容 OpenAI 的服务器：

./llama.cpp/llama-server \
    --model unsloth/Kimi-K2-Thinking-GGUF/UD-TQ1_0/Kimi-K2-Thinking-UD-TQ1_0-00001-of-00006.gguf \\
    --alias "unsloth/Kimi-K2-Thinking" \\
    -fa on \\
    --n-gpu-layers 999 \
    -ot ".ffn_.*_exps.=CPU" \\
    --min-p 0.01 \
    --ctx-size 16384 \
    --port 8001 \
    --jinja

然后在以下命令之后使用 OpenAI 的 Python 库 pip install openai :

from openai import OpenAI
openai_client = OpenAI(
    base_url = "http://127.0.0.1:8001/v1",
    api_key = "sk-no-key-required",
)
completion = openai_client.chat.completions.create(
    model = "unsloth/Kimi-K2-Thinking",
    messages = [{"role": "user", "content": "2+2 等于多少？"},],
)
print(completion.choices[0].message.content)

🔍分词器的怪癖与修复

2025 年 11 月 7 日：我们通知了 Kimi 团队，并修复了 You are Kimi, an AI assistant created by Moonshot AI. 没有出现在第一个用户提示词中！ 查看 https://huggingface.co/moonshotai/Kimi-K2-Thinking/discussions/12

非常感谢 Moonshot Kimi 团队对我们问题的超快响应，以及尽快修复了该问题！

2025 年 7 月 16 日：Kimi K2 更新了他们的分词器，以支持多次工具调用 ，根据 https://x.com/Kimi_Moonshot/status/1945050874067476962

2025 年 7 月 18 日：我们修复了一个系统提示词——Kimi 也在这里发了关于我们修复的推文： https://x.com/Kimi_Moonshot/status/1946130043446690030。该修复也在这里说明： https://huggingface.co/moonshotai/Kimi-K2-Instruct/discussions/28

如果你已经下载了旧检查点——不用担心——只需下载第一个被更改的 GGUF 分片即可。或者，如果你不想下载任何新文件，可以执行：

wget https://huggingface.co/unsloth/Kimi-K2-Instruct/raw/main/chat_template.jinja
./llama.cpp ... --chat-template-file /dir/to/chat_template.jinja

Kimi K2 的分词器玩起来很有意思—— 它的工作方式与 GPT-4o 的分词器大体相似！我们首先在 tokenization_kimi.py 文件中看到 Kimi K2 使用的以下正则表达式（regex）：

pat_str = "|".join(
    [
        r"""[\p{Han}]+""",
        r"""[^\r\n\p{L}\p{N}]?[\p{Lu}\p{Lt}\p{Lm}\p{Lo}\p{M}&&[^\p{Han}]]*[\p{Ll}\p{Lm}\p{Lo}\p{M}&&[^\p{Han}]]+(?i:'s|'t|'re|'ve|'m|'ll|'d)?""",
        r"""[^\r\n\p{L}\p{N}]?[\p{Lu}\p{Lt}\p{Lm}\p{Lo}\p{M}&&[^\p{Han}]]+[\p{Ll}\p{Lm}\p{Lo}\p{M}&&[^\p{Han}]]*(?i:'s|'t|'re|'ve|'m|'ll|'d)?""",
        r"""\p{N}{1,3}""",
        r""" ?[^\s\p{L}\p{N}]+[\r\n]*""",
        r"""\s*[\r\n]+""",
        r"""\s+(?!\S)""",
        r"""\s+""",
    ]
)

经过仔细检查，我们发现 Kimi K2 与 GPT-4o 的分词器正则表达式几乎完全相同，可在 llama.cpp 的源代码中找到.

[^\r\n\p{L}\p{N}]?[\p{Lu}\p{Lt}\p{Lm}\p{Lo}\p{M}]*[\p{Ll}\p{Lm}\p{Lo}\p{M}]+(?i:'s|'t|'re|'ve|'m|'ll|'d)?|[^\r\n\p{L}\p{N}]?[\p{Lu}\p{Lt}\p{Lm}\p{Lo}\p{M}]+[\p{Ll}\p{Lm}\p{Lo}\p{M}]*(?i:'s|'t|'re|'ve|'m|'ll|'d)?|\p{N}{1,3}| ?[^\s\p{L}\p{N}]+[\r\n/]*|\s*[\r\n]+|\s+(?!\S)|\s+

两者都会将数字分组成 1 到 3 位一组（9、99、999），并使用相似的模式。唯一的差异似乎在于对“Han”或中文字符的处理，Kimi 的分词器对此处理得更多一些。 该 PR 由 https://github.com/gabriellarson 在经过一些 这里的讨论.

后很好地处理了这些差异。我们还发现正确的 EOS token 不应是 [EOS]，而应是 <|im_end|>，我们也已在模型转换中修复了这一点。

🌝Kimi-K2-Instruct 指南

逐步指南：运行 Kimi K2 Instruct 模型，包括 Kimi K2 0905——9 月 5 日更新。

🌙 官方推荐设置：

根据 Moonshot AI，以下是 Kimi K2 推理的推荐设置：

• 将 温度设为 0.6 以减少重复和不连贯。

• 原始默认系统提示词是：

  你是一个有帮助的助手

• （可选）Moonshot 还建议将下面这句作为系统提示词：

  You are Kimi, an AI assistant created by Moonshot AI.

我们建议将 min_p 设为 0.01 ，以抑制低概率、不太可能出现的 token。

🔢 聊天模板与提示词格式

Kimi Chat 确实使用了 BOS（句子开头 token）。系统、用户和助手角色都被包裹在 <|im_middle|> 之中，这很有意思，并且每个角色都有其各自的 token <|im_system|>、<|im_user|>、<|im_assistant|>.

<|im_system|>system<|im_middle|>You are a helpful assistant<|im_end|><|im_user|>user<|im_middle|>What is 1+1?<|im_end|><|im_assistant|>assistant<|im_middle|>2<|im_end|>

为了分隔对话边界（你必须移除每个换行），我们得到：

<|im_system|>system<|im_middle|>You are a helpful assistant<|im_end|>
<|im_user|>user<|im_middle|>What is 1+1?<|im_end|>
<|im_assistant|>assistant<|im_middle|>2<|im_end|>

💾 模型上传

我们所有的上传 - 包括那些非 imatrix 基础或非动态版本，使用我们的校准数据集，该数据集专门针对对话、编码和推理任务进行了优化。

MoE 比特数	类型 + 链接	磁盘大小	详情
1.66bit	UD-TQ1_0	245GB	1.92/1.56bit
1.78bit	UD-IQ1_S	281GB	2.06/1.56bit
1.93bit	UD-IQ1_M	304GB	2.5/2.06/1.56
2.42bit	UD-IQ2_XXS	343GB	2.5/2.06bit
2.71bit	UD-Q2_K_XL	381GB	3.5/2.5bit
3.12bit	UD-IQ3_XXS	417GB	3.5/2.06bit
3.5bit	UD-Q3_K_XL	452GB	4.5/3.5bit
4.5bit	UD-Q4_K_XL	588GB	5.5/4.5bit
5.5bit	UD-Q5_K_XL	732GB	6.5/5.5bit

我们还上传了 BF16 格式.

✨ 在 llama.cpp 中运行 Instruct

1. 获取最新的 llama.cpp 在 GitHub 这里。你也可以按照下面的构建说明操作。将 -DGGML_CUDA=ON 改为 -DGGML_CUDA=OFF 如果你没有 GPU，或者只想进行 CPU 推理。

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-quantize llama-cli llama-gguf-split llama-mtmd-cli
cp llama.cpp/build/bin/llama-* llama.cpp

1. 如果你想使用 llama.cpp 直接加载模型，你可以使用下面的方法：（:UD-IQ1_S）是量化类型。你也可以通过 Hugging Face 下载（见第 3 点）。这与以下方式类似 ollama run 。使用 export LLAMA_CACHE="folder" 来强制 llama.cpp 用于保存到特定位置。 要运行该模型 2025 年 9 月的新更新，请将模型名称从 'Kimi-K2-Instruct' 改为 'Kimi-K2-Instruct-0905'。

请试试 -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 ".ffn_.*_exps.=CPU" 这使用的 VRAM 最少。

你也可以自定义正则表达式，例如 -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 层。

export LLAMA_CACHE="unsloth/Kimi-K2-Instruct-GGUF"
./llama.cpp/llama-cli \
    -hf unsloth/Kimi-K2-Instruct-GGUF:TQ1_0 \\
    --n-gpu-layers 99 \\
    --temp 0.6 \\
    --min-p 0.01 \
    --ctx-size 16384 \
    --seed 3407 \
    -ot ".ffn_.*_exps.=CPU"

1. 通过以下方式下载模型（在安装 pip install huggingface_hub hf_transfer 之后）。你可以选择 UD-TQ1_0（动态 1.8bit 量化）或其他量化版本，例如 Q2_K_XL 。我们 建议使用我们的 2bit 动态量化 UD-Q2_K_XL 以平衡大小和准确率。更多版本见： huggingface.co/unsloth/Kimi-K2-Instruct-GGUF

# !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/Kimi-K2-Instruct-GGUF",
    local_dir = "unsloth/Kimi-K2-Instruct-GGUF",
    allow_patterns = ["*UD-TQ1_0*"], # 动态 1bit（281GB）请使用 "*UD-Q2_K_XL*" 作为动态 2bit（381GB）
)

如果你发现下载卡在 90% 到 95% 左右，请查看 https://docs.unsloth.ai/basics/troubleshooting-and-faqs#downloading-gets-stuck-at-90-to-95

1. 运行任意提示词。

2. 编辑 --threads -1 用于指定 CPU 线程数（默认设置为 CPU 的最大线程数）， --ctx-size 16384 来设置上下文长度， --n-gpu-layers 99 用于 GPU 卸载的层数。将其设为 99，并配合 MoE CPU 卸载，以获得最佳性能。如果你的 GPU 显存不足，请尝试调整它。如果你只进行 CPU 推理，也请移除它。

./llama.cpp/llama-cli \
    --model unsloth/Kimi-K2-Instruct-GGUF/UD-TQ1_0/Kimi-K2-Instruct-UD-TQ1_0-00001-of-00005.gguf \\
    --n-gpu-layers 99 \\
    --temp 0.6 \\
    --min-p 0.01 \
    --ctx-size 16384 \
    --seed 3407 \
    -ot ".ffn_.*_exps.=CPU"

🐦 Flappy Bird + 其他测试

当我们提供 DeepSeek R1 的 1.58bit 量化版本时，我们引入了 Flappy Bird 测试。我们发现 Kimi K2 是少数能够一次性完成包括这一项在内的所有任务的模型之一， Heptagon 以及其他测试，即使在 2-bit 下也是如此。目标是让 LLM 创建一个 Flappy Bird 游戏，但要遵循一些特定说明：

使用 Python 创建一个 Flappy Bird 游戏。你必须包含以下内容：
1. 你必须使用 pygame。
2. 背景颜色应随机选择，并且是浅色。以浅蓝色开始。
3. 多次按下 SPACE 会加速小鸟。
4. 小鸟的形状应随机选择为正方形、圆形或三角形。颜色应随机选择为深色。
5. 在底部放一些随机选择为深棕色或黄色的地面。
6. 在右上角显示分数。如果你通过管道且没有撞上它们，分数就增加。
7. 随机间隔生成足够空隙的管道。将它们随机设为深绿色、浅棕色或深灰色。
8. 当你失败时，显示最高分。让文字显示在屏幕内。按 q 或 Esc 退出游戏。重新开始时再次按 SPACE。
最终游戏应放在 Python 的 markdown 区块中。在最终 markdown 区块之前检查你的代码是否有错误并修复它们。

你也可以按照 r/Localllama 中的方式，通过 Heptagon 测试来测试动态量化版本，该测试会要求模型创建一个基础物理引擎，以模拟球体在一个移动的封闭六边形中旋转。（原文如此）

目标是让六边形旋转，并且六边形中的球应当移动。提示词如下：

编写一个 Python 程序，显示 20 个球在一个旋转的七边形中弹跳：\n- 所有球的半径相同。\n- 所有球上都标有 1 到 20 的数字。\n- 所有球在开始时都从七边形中心落下。\n- 颜色为：#f8b862, #f6ad49, #f39800, #f08300, #ec6d51, #ee7948, #ed6d3d, #ec6800, #ec6800, #ee7800, #eb6238, #ea5506, #ea5506, #eb6101, #e49e61, #e45e32, #e17b34, #dd7a56, #db8449, #d66a35\n- 球应受到重力和摩擦力影响，并且必须真实地从旋转的墙壁上弹开。球与球之间也应发生碰撞。\n- 所有球的材质决定其碰撞后的弹跳高度不会超过七边形的半径，但要高于球半径。\n- 所有球都带有摩擦旋转，球上的数字可用于表示球的旋转。\n- 七边形围绕其中心旋转，旋转速度为每 5 秒 360 度。\n- 七边形大小应足够大，能容纳所有球。\n- 不要使用 pygame 库；请自行实现碰撞检测算法和碰撞响应等。允许使用以下 Python 库：tkinter、math、numpy、dataclasses、typing、sys。\n- 所有代码应放在单个 Python 文件中。