> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/kimi-k2.md).

# Kimi K2.5

在 Clore.ai GPU 上部署 Moonshot AI 的 Kimi K2.5（1T MoE 多模态）

Kimi K2.5，由 Moonshot AI 于 2026 年 1 月 27 日发布，是一款 **拥有 1 万亿参数的混合专家（Mixture-of-Experts）多模态模型** ，每个 token 有 320 亿个激活参数。它在 Kimi-K2-Base 之上，通过约 15 万亿个混合视觉和文本 token 的持续预训练构建而成，原生理解文本、图像和视频。K2.5 引入了 **Agent Swarm** 技术——可同时协调多达 100 个专门化 AI 代理——并在代码（76.8% SWE-bench Verified）、视觉和代理任务上达到前沿级性能。可在 HuggingFace 上以 **开放权重许可证** 下获取。

## 主要特性

* **总计 1T / 320 亿激活** —— 384 专家 MoE 架构，采用 MLA 注意力和 SwiGLU
* **原生多模态** —— 预训练于视觉-语言 token；可理解图像、视频和文本
* **Agent Swarm** —— 通过动态生成的代理将复杂任务分解为并行子任务
* **256K 上下文窗口** —— 处理整个代码库、长文档和视频转录文本
* **混合推理** —— 支持即时模式（快速）和思考模式（深度推理）
* **强大的编程能力** —— 76.8% SWE-bench Verified，73.0% SWE-bench Multilingual

## 需求

Kimi K2.5 是一个超大型模型——FP8 检查点约 630GB。自托管需要强大的硬件。

| 组件   | 量化版（GGUF Q2）           | FP8 完整版       |
| ---- | ---------------------- | ------------- |
| GPU  | 1× RTX 4090 + 256GB 内存 | 8× H200 141GB |
| 显存   | 24GB + CPU 卸载          | 1,128GB       |
| 内存   | 256GB+                 | 256GB         |
| 磁盘   | 400GB SSD              | 700GB NVMe    |
| CUDA | 12.8+                  | 12.8+         |

**Clore.ai 推荐**：如需全精度服务，请租用 8× H200（[裸机](https://clore.ai/bare-metal)）。对于量化本地推理，单张 H100 80GB 甚至 RTX 4090 加大量 CPU 卸载也可运行，但速度会降低。

## 使用 llama.cpp 快速开始（量化版）

在本地运行 K2.5 最易上手的方式——使用 Unsloth 的 GGUF 量化：

```bash
# 克隆并构建 llama.cpp
git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp
cmake -B build -DGGML_CUDA=ON && cmake --build build --config Release -j

# 下载量化模型（Q2_K_XL — 375GB，质量/体积平衡较好）
huggingface-cli download unsloth/Kimi-K2.5-GGUF \\
  Kimi-K2.5-UD-Q2_K_XL-00001-of-00005.gguf \\
  Kimi-K2.5-UD-Q2_K_XL-00002-of-00005.gguf \\
  Kimi-K2.5-UD-Q2_K_XL-00003-of-00005.gguf \\
  Kimi-K2.5-UD-Q2_K_XL-00004-of-00005.gguf \\
  Kimi-K2.5-UD-Q2_K_XL-00005-of-00005.gguf \\
  --local-dir ./models

# 运行推理（根据你的 VRAM 调整 --n-gpu-layers）
./build/bin/llama-server \\
  -m ./models/Kimi-K2.5-UD-Q2_K_XL-00001-of-00005.gguf \\
  --n-gpu-layers 10 \\
  --threads 32 \\
  --ctx-size 16384 \\
  --host 0.0.0.0 --port 8080
```

> **注意**：K2.5 的 GGUF/llama.cpp 目前尚不支持视觉功能。要使用多模态特性，请使用 vLLM。

## vLLM 设置（生产环境——完整模型）

用于支持完整多模态的生产部署：

```bash
# 安装 vLLM nightly（K2.5 需要最新版本）
pip install -U vllm --pre \\
  --extra-index-url https://wheels.vllm.ai/nightly/cu129 \\
  --extra-index-url https://download.pytorch.org/whl/cu128 \\
  --index-strategy unsafe-best-match
```

### 在 8× H200 GPU 上提供服务

```bash
vllm serve moonshotai/Kimi-K2.5 \\
  -tp 8 \\
  --mm-encoder-tp-mode data \\
  --tool-call-parser kimi_k2 \\
  --reasoning-parser kimi_k2 \\
  --trust-remote-code \\
  --gpu-memory-utilization 0.90
```

### 文本查询

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")

response = client.chat.completions.create(
    model="moonshotai/Kimi-K2.5",
    messages=[
        {"role": "system", "content": "你是 Kimi，由 Moonshot AI 创建的 AI 助手。"},
        {"role": "user", "content": "编写一个支持 WebSocket 的 FastAPI 实时聊天服务"}
    ],
    temperature=0.6,
    max_tokens=4096
)
print(response.choices[0].message.content)
```

### 图像查询（多模态）

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY", timeout=3600)

response = client.chat.completions.create(
    model="moonshotai/Kimi-K2.5",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image_url",
                "image_url": {"url": "https://example.com/diagram.png"}
            },
            {
                "type": "text",
                "text": "详细描述这张图，并提取其中所有文字。"
            }
        ]
    }],
    max_tokens=2048
)
print(response.choices[0].message.content)
```

## API 访问（无需 GPU）

如果自托管过于复杂，可以使用 Moonshot 的官方 API：

```python
from openai import OpenAI

# Moonshot 平台——兼容 OpenAI 的 API
client = OpenAI(
    api_key="your-moonshot-api-key",
    base_url="https://api.moonshot.ai/v1"
)

response = client.chat.completions.create(
    model="kimi-k2.5",
    messages=[
        {"role": "user", "content": "解释 Kimi K2.5 中的 Agent Swarm 架构"}
    ],
    temperature=0.6,
    max_tokens=2048
)
print(response.choices[0].message.content)
```

## 工具调用

K2.5 在代理式工具使用方面表现出色：

```python
import json
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")

tools = [{
    "type": "function",
    "function": {
        "name": "search_code",
        "description": "在代码库中搜索相关文件和函数",
        "parameters": {
            "type": "object",
            "required": ["query"],
            "properties": {
                "query": {"type": "string", "description": "搜索查询"}
            }
        }
    }
}]

response = client.chat.completions.create(
    model="moonshotai/Kimi-K2.5",
    messages=[{"role": "user", "content": "找出项目中所有与身份验证相关的代码"}],
    tools=tools,
    tool_choice="auto",
    temperature=0.6
)

for tool_call in response.choices[0].message.tool_calls:
    print(f"Function: {tool_call.function.name}")
    print(f"Args: {json.loads(tool_call.function.arguments)}")
```

## Docker 快速开始

```bash
# 使用带 8 张 GPU 的 vLLM Docker
docker run --gpus all -p 8000:8000 \\
  --ipc=host \
  -v ~/.cache/huggingface:/root/.cache/huggingface \\
  vllm/vllm-openai:latest \
  --model moonshotai/Kimi-K2.5 \\
  --tensor-parallel-size 8 \\
  --mm-encoder-tp-mode data \\
  --tool-call-parser kimi_k2 \\
  --reasoning-parser kimi_k2 \\
  --trust-remote-code
```

## 给 Clore.ai 用户的建议

* **API 与自托管的取舍**：完整 K2.5 需要 8× H200， [裸机](https://clore.ai/bare-metal)。Moonshot 的 API 提供免费层或按 token 付费——用于探索时请用 API，持续生产负载则建议自托管。
* **单 GPU 量化运行**：Unsloth GGUF Q2\_K\_XL（约 375GB）可通过 CPU 卸载在 RTX 4090（$0.14–0.42/小时）和 256GB 内存上运行——预计约 5–10 tok/s。足够个人使用和开发。
* **适合预算型配置的纯文本 K2**：如果你不需要视觉功能， `moonshotai/Kimi-K2-Instruct` 就是仅文本的前代模型——同样是 1T MoE，但部署更轻量（没有视觉编码器开销）。
* **正确设置 temperature**：使用 `temperature=0.6` 用于即时模式， `temperature=1.0` 用于思考模式。错误的 temperature 会导致重复或不连贯。
* **用于提升吞吐量的专家并行**：在多节点环境中，使用 `--enable-expert-parallel` 可在 vLLM 中获得更高吞吐量。请查看 vLLM 文档了解 EP 配置。

## 故障排查

| 问题                        | 解决方案                                                                       |
| ------------------------- | -------------------------------------------------------------------------- |
| `OutOfMemoryError` 配合完整模型 | 需要 8× H200（总计 1128GB）。使用 FP8 权重，设置 `--gpu-memory-utilization 0.90`.        |
| GGUF 推理非常慢                | 确保有足够的内存以容纳量化尺寸。Q2\_K\_XL 需要约 375GB 的 RAM+VRAM 总和。                         |
| llama.cpp 中视觉功能无法工作       | K2.5 GGUF 的视觉支持目前尚不可用——请使用 vLLM 进行多模态。                                     |
| 输出重复                      | 设置 `temperature=0.6` （即时）或 `1.0` （思考）。添加 `min_p=0.01`.                     |
| 模型下载要等很久                  | 约 630GB 的 FP8 检查点。使用 `huggingface-cli download` 使用 `--resume-download`.    |
| 工具调用未被解析                  | 在 `--tool-call-parser kimi_k2 --enable-auto-tool-choice` 到 vLLM serve 命令中。 |

## 延伸阅读

* [HuggingFace 上的 Kimi K2.5](https://huggingface.co/moonshotai/Kimi-K2.5)
* [Kimi K2.5 技术博客](https://www.kimi.com/blog/kimi-k2-5.html)
* [Kimi K2.5 论文](https://arxiv.org/abs/2602.02276)
* [vLLM K2.5 配方](https://docs.vllm.ai/projects/recipes/en/latest/moonshotai/Kimi-K2.5.html)
* [Unsloth GGUF 量化](https://huggingface.co/unsloth/Kimi-K2.5-GGUF)
* [Moonshot API 平台](https://platform.moonshot.ai)
* [Kimi K2 GitHub](https://github.com/MoonshotAI/Kimi-K2)


---

# 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://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/kimi-k2.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.