# Kimi K2.5

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

## 要求

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.0+                  | 12.0+         |

**Clore.ai 建议**：对于全精度推理，租用 8× H200（约 $24–48/天）。对于量化的本地推理，单个 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

# 运行推理（根据你的显存调整 --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 夜间构建版（K2.5 需要最新版）
pip install -U vllm --pre \
  --extra-index-url https://wheels.vllm.ai/nightly/cu129 \
  --extra-index-url https://download.pytorch.org/whl/cu129 \
  --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，约 $24–48/天。Moonshot 的 API 提供免费额度或按 token 计费——用于探索请使用 API，长期生产负载建议自托管。
* **单 GPU 上的量化**：Unsloth 的 GGUF Q2\_K\_XL（约 375GB）可在 RTX 4090（$0.5–2/天）上通过 CPU 卸载和 256GB 内存运行——预期约 \~5–10 token/s。对于个人使用和开发足够。
* **面向预算的纯文本 K2**：如果你不需要视觉功能， `moonshotai/Kimi-K2-Instruct` 是纯文本的前身——相同的 1T MoE，但部署更轻便（无视觉编码器开销）。
* **正确设置温度**：使用 `temperature=0.6` 用于即时模式， `temperature=1.0` 用于思考模式。错误的温度会导致重复或不连贯。
* **为吞吐量使用专家并行**：在多节点部署上，使用 `--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 命令中。 |

## 延伸阅读

* [Kimi K2.5 在 HuggingFace](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: 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:

```
GET https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/kimi-k2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.