# PR #28201 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[Docs] Add fp8 kv cache for tokenspeed mla docs
- 合并时间：2026-06-18 12:42
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/28201

---

# 分析报告：Kimi 部署文档 FP8 KV cache 修复

## 执行摘要

该 PR 修复了 Kimi K2.5/K2.6/K2.7 Code 部署文档中 `tokenspeed_mla` 后端缺少 `--kv-cache-dtype fp8_e4m3` 的问题。通过引入 `usesTokenspeedMla` 变量统一 Blackwell 硬件判定，并扩展 FP8 KV cache 的触发条件，确保文档生成的命令在后端强校验下能够正常启动。

## 功能与动机

PR body 明确指出，Kimi cookbook 中启用 `tokenspeed_mla` 的命令未设置 `--kv-cache-dtype fp8_e4m3`，而 `server_args.py` 第 3090-3094 行的校验逻辑显示，`tokenspeed_mla` 后端要求 KV cache dtype 必须为 `fp8_e4m3`，默认 `auto` 值会导致启动失败。该变更将阻止用户按照文档配置时遭遇错误。

## 实现拆解

1. **提取共用变量**：在三份 JSX 文件中，将多次出现的 `hardware === 'b300' || hardware === 'gb300'` 条件抽取为 `usesTokenspeedMla` 常量，减少代码重复。
2. **调整 `--kv-cache-dtype` 条件**：原来仅在 AMD 平台时添加 `--kv-cache-dtype fp8_e4m3`，现在改为 `isAMD || usesTokenspeedMla`，确保 Blackwall 硬件启用 `tokenspeed_mla` 时也会自动设置正确的 KV cache dtype。
3. **一致性维护**：三份文档片段（K2.5、K2.6、K2.7 Code）采用完全相同的逻辑模式，便于后续维护。

### `docs_new/src/snippets/autoregressive/kimi-k25-deployment.jsx`

Kimi K2.5 部署代码片段，引入 usesTokenspeedMla 变量并扩展 FP8 KV cache 条件。

```jsx
// kimi-k25-deployment.jsx — 构建 sglang serve 命令的片段
// 提取 Blackwell 硬件检测，确保 tokenspeed_mla 后端必须配合 fp8 KV cache 使用
const usesTokenspeedMla = hardware === 'b300' || hardware === 'gb300';

// Blackwell (B300/GB300): tokenspeed MLA attention backend
if (usesTokenspeedMla) {
  cmd += ' \\
  --attention-backend tokenspeed_mla';
}

// FP8 KV cache for AMD memory efficiency and tokenspeed MLA compatibility
// 原条件仅为 isAMD，现在覆盖所有需要 tokenspeed_mla 的场景
if (isAMD || usesTokenspeedMla) {
  cmd += ' \\
  --kv-cache-dtype fp8_e4m3';
}

```

## 评论区精华

无实质性讨论。gemini-code-assist[bot] 自动总结变更内容，两名维护者（kpham-sgl、zijiexia）直接批准，表明变更明确且无争议。

## 风险与影响

**风险**：风险极低。变更仅涉及文档代码片段的条件逻辑，不修改任何后端运行时代码。若未来新增 Kimi 系列文档片段，需要同样模式维护。

**影响**：直接修复 Blackwell 硬件用户运行 `tokenspeed_mla` 后端时的启动问题。AMD 用户行为不变。

## 关联脉络

该 PR 与后端 `server_args.py` 中 `tokenspeed_mla` 对 KV cache dtype 的验证规则紧密相关，是文档与后端规则同步的典型案例。近期没有直接相关的其他 PR。