🌙Kimi K2 Thinking：本地运行指南

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

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

我们还与 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 GGUFs 在以下方面的表现： 编码基准测试.

运行 Thinking运行 Instruct

⚙️ 推荐配置要求

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

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

1.8-bit（UD-TQ1_0）量化可以装入 1 块 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 tokens/秒，现在不到 1 个 token。

我们建议使用我们的 UD-Q2_K_XL（360GB） 量化，以平衡大小和精度！

为了获得最佳性能，请确保你的 VRAM + RAM 总和 = 你下载的量化模型大小。否则，它仍可通过磁盘卸载运行，只是会更慢！

💭Kimi-K2-Thinking 指南

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

要以全精度运行该模型，你只需使用 4-bit 或 5-bit Dynamic GGUFs（例如 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|>你是由 Moonshot AI 创建的 AI 助手 Kimi。<|im_end|><|im_user|>user<|im_middle|>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（381GB）使用 "*UD-Q2_K_XL*"
)

如果你发现下载卡在 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"

🤔没有思考标签？

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

在你的 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)

🔍分词器怪癖和 bug 修复

2025 年 11 月 7 日：我们已通知 Kimi 团队，并修复了 你是 Kimi，一个由 Moonshot AI 创建的 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 的 tokenizer regex 与 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 的 tokenizer 在这方面处理得更多。 这个 PR 由 https://github.com/gabriellarson 在一些 这里的讨论.

我们还发现正确的 EOS token 不应是 [EOS]，而应是 <|im_end|>，我们也已在模型转换中修复这一点。

🌝Kimi-K2-Instruct 指南

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

🌙 官方推荐设置：

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

• 将 temperature 0.6 设为较低值，以减少重复和不连贯。

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

  你是一个有帮助的助手

• （可选）Moonshot 还建议以下系统提示词：

  你是 Kimi，一个由 Moonshot AI 创建的 AI 助手。

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

🔢 聊天模板和提示格式

Kimi Chat 确实使用 BOS（句首 token）。系统、用户和助手角色都用 <|im_middle|> 包裹起来，这很有意思，而且每个角色都有各自的 token <|im_system|>、<|im_user|>、<|im_assistant|>.

<|im_system|>system<|im_middle|>你是一个有帮助的助手<|im_end|><|im_user|>user<|im_middle|>1+1 等于多少？<|im_end|><|im_assistant|>assistant<|im_middle|>2<|im_end|>

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

<|im_system|>system<|im_middle|>你是一个有帮助的助手<|im_end|>
<|im_user|>user<|im_middle|>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 来测试动态量化，该测试会考察模型创建一个基本物理引擎，以模拟球体在一个移动的封闭七边形形状中旋转。

目标是让七边形旋转，并且其中的球应该移动。提示如下：

编写一个 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 文件中。