🌙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 位 GGUF 在 编码基准上的表现在此.

运行 Thinking运行 Instruct

⚙️ 推荐要求

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

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

1.8-bit (UD-TQ1_0) 量化可在 1×24GB GPU 上运行（所有 MoE 层卸载到系统内存或快速磁盘）。如果您还有额外 256GB 内存，使用该配置预计约 ~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（此处）。您也可以按照下面的构建说明。若没有 GPU 或仅想用 CPU 推理，请将 -DGGML_CUDA=ON 改为 -DGGML_CUDA=OFF 。

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 卸载时设置多少层。将其与 MoE CPU 卸载结合设置为 99 以获得最佳性能。如果 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> 标记出现。

您也可能会看到每个答案以 <|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（句首标记）。system、user 和 assistant 角色都被 <|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（此处）。您也可以按照下面的构建说明。若没有 GPU 或仅想用 CPU 推理，请将 -DGGML_CUDA=ON 改为 -DGGML_CUDA=OFF 。

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 卸载时设置多少层。将其与 MoE CPU 卸载结合设置为 99 以获得最佳性能。如果 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 区块之前检查并修复代码错误。

您还可以按照以下方式通过 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 文件中。