🌙Kimi K2 Thinking：本地运行指南

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

Kimi-K2-Thinking 已发布。阅读我们的 Thinking 指南 或访问 在此获取 GGUFs.

我们还与 Kimi 团队合作了 系统提示修复 针对 Kimi-K2-Thinking。

Kimi-K2 和 Kimi-K2-Thinking 在知识、推理、编码和代理任务中达到 SOTA 性能。Moonshot AI 的完整 1T 参数模型需要 1.09TB 的磁盘空间，而量化后的 Unsloth 动态 1.8 位 版本将其减少到仅 230GB（减小 80%）: Kimi-K2-GGUF

你现在也可以运行我们的 Kimi-K2-Thinking GGUFs.

所有上传均使用 Unsloth Dynamic 2.0 用于 SOTA Aider Polyglot 和 5-shot MMLU 性能。查看我们的动态 1–2 位 GGUFs 在 编码基准上的表现在此.

运行 Thinking运行 Instruct

⚙️ 推荐要求

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

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

1.8 位（UD-TQ1_0）量化将在 1x 24GB GPU（所有 MoE 层卸载到系统 RAM 或快速磁盘）上适配。如果你同时还有额外 256GB RAM，预计此设置下速率约为 ~1-2 令牌/秒。完整的 Kimi K2 Q8 量化大小为 1.09TB，至少需要 8 个 H200 GPU。

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

如果你没有 247GB 的 RAM+VRAM，也别担心！ llama.cpp 本质上具有 磁盘卸载，因此通过 mmap，它仍然可以工作，只是会更慢 — 例如之前你可能得到每秒 5 到 10 个令牌，现在不到 1 个令牌。

我们建议使用我们的 UD-Q2_K_XL（360GB） 量化以在大小和准确性之间达到平衡！

为了获得最佳性能，使你的 VRAM + RAM 总和等于你下载的量化文件大小。如果不满足，仍可通过磁盘卸载工作，只是会更慢！

💭Kimi-K2-Thinking 指南

Kimi-K2-Thinking 通常应遵循与 Instruct 模型相同的说明，但在某些关键方面有一些差别，特别是在设置和聊天模板等方面。

要以全精度运行模型，你只需使用 4 位或 5 位动态 GGUF（例如 UD_Q4_K_XL），因为模型最初以 INT4 格式发布。

你可以选择更高位的量化以防止小的量化差异，但在大多数情况下这是没有必要的。

🌙 官方推荐设置：

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

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

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

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

我们建议将 min_p 设置为 0.01 以抑制低概率不太可能出现的令牌的发生。

例如，给定用户消息“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 层放在一块 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 ）。我们建议使用我们的 2 位动态量化 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*"], # 使用 "*UD-Q2_K_XL*" 来选择动态 2 位（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 标签？

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

在你的 llama.cpp 脚本中，确保在命令的最末尾包含 --special 标志。一旦添加，你将按预期看到 <think> 令牌出现。

你可能还会看到每个回答以 <|im_end|>结尾。这是正常的，因为 <|im_end|> 是打印特殊令牌时出现的特殊令牌。如果你想隐藏它，可以在设置中将 <|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

然后在 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": "What is 2+2?"},],
)
print(completion.choices[0].message.content)

🔍分词器的怪癖与错误修复

2025 年 11 月 7 日：我们已通知 Kimi 团队，并修复了默认系统提示 You are Kimi, an AI assistant created by Moonshot AI. 未在第一次用户提示时出现的问题！ GLM 4.7 的工具调用 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 令牌不应该是 [EOS]，而是 <|im_end|>，我们也在模型转换中修复了这一点。

🌝Kimi-K2-Instruct 指南

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

🌙 官方推荐设置：

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

• 设置 temperature 0.6 以减少重复和不连贯。

• 原始默认系统提示为：

  You are a helpful assistant

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

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

我们建议将 min_p 设置为 0.01 以抑制低概率不太可能出现的令牌的发生。

🔢 聊天模板和提示格式

Kimi 聊天确实使用 BOS（句首令牌）。系统、用户和助手角色都用 <|im_middle|> 包裹，这很有趣，并且每个角色都有各自的令牌 <|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.66 位	UD-TQ1_0	245GB	1.92/1.56 位
1.78 位	UD-IQ1_S	281GB	2.06/1.56 位
1.93 位	UD-IQ1_M	304GB	2.5/2.06/1.56
2.42 位	UD-IQ2_XXS	343GB	2.5/2.06 位
2.71 位	UD-Q2_K_XL	381GB	3.5/2.5 位
3.12 位	UD-IQ3_XXS	417GB	3.5/2.06 位
3.5 位	UD-Q3_K_XL	452GB	4.5/3.5 位
4.5 位	UD-Q4_K_XL	588GB	5.5/4.5 位
5.5 位	UD-Q5_K_XL	732GB	6.5/5.5 位

我们还上传了 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 层放在一块 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.8 位量化）或其他量化版本如 Q2_K_XL 。我们 建议使用我们的 2 位动态量化 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*"], # 动态 1 位（281GB） 使用 "*UD-Q2_K_XL*" 可选 动态 2 位（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.58 位量化时，引入了 Flappy Bird 测试。我们发现 Kimi K2 是为数不多能一次性完成我们所有任务（包括此任务）的模型之一， Heptagon 以及其他测试即使在 2 位下也能通过。目标是要求 LLM 创建一个 Flappy Bird 游戏，但需遵循一些特定说明：

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

你也可以按照以下方式通过 Heptagon 测试来测试动态量化： 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 文件中。