# PR #25120 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[env] Make max KV chunk capacity configurable via `SGLANG_MAX_KV_CHUNK_CAPACITY`
- 合并时间：2026-05-13 13:37
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/25120

---

# 执行摘要

- 一句话：KV chunk 容量可环境变量配置
- 推荐动作：值得快速合并。作为将硬编码参数环境变量化的模板，未来可参考此模式将其他待定参数（如 SGLANG_CHUNKED_PREFIX_CACHE_THRESHOLD）也统一管理。建议后续补充单元测试以验证环境变量解析和边界值。

# 功能与动机

PR body 明确指出要 "change hardcoded value in `get_max_chunk_capacity` into an env var knob"。原代码中硬编码的 128*1024 数值带有 TODO 注释（“Should be changed to a better value, maybe passed through server args”），说明团队早已计划将其参数化。

# 实现拆解

1. **环境变量注册**：在 `python/sglang/srt/environ.py` 的 `Envs` 类中新增 `SGLANG_MAX_KV_CHUNK_CAPACITY = EnvInt(128 * 1024)`，默认值保持与原来一致。
2. **使用点替换**：在 `python/sglang/srt/model_executor/forward_batch_deepseek_mha_mixin.py` 中，`get_max_chunk_capacity()` 方法原本直接 `return 128 * 1024`，现在改为 `return envs.SGLANG_MAX_KV_CHUNK_CAPACITY.get()`；同时添加了 `from sglang.srt.environ import envs` 导入。
3. **文档注释同步**：在 `python/sglang/srt/models/deepseek_common/attention_forward_methods/forward_mha.py` 的头部注释中，将 `max_kv_chunk_capacity` 的描述更新为可被 `SGLANG_MAX_KV_CHUNK_CAPACITY` 更改。
4. **用户文档更新**：在两个文档文件（`docs_new/docs/references/environment_variables.mdx` 和 `docs/references/environment_variables.md`）中新增了该环境变量的说明表格行。

关键文件：
- `python/sglang/srt/environ.py`（模块 环境配置；类别 source；类型 configuration）: 注册环境变量 `SGLANG_MAX_KV_CHUNK_CAPACITY` 的核心位置，定义了默认值 128*1024。
- `python/sglang/srt/model_executor/forward_batch_deepseek_mha_mixin.py`（模块 MHA 前向；类别 source；类型 core-logic；符号 get_max_chunk_capacity）: 使用环境变量的关键位置，修改了 get_max_chunk_capacity() 方法。
- `python/sglang/srt/models/deepseek_common/attention_forward_methods/forward_mha.py`（模块 MHA 前向；类别 source；类型 documentation）: 注释文档更新，帮助开发者了解参数可用性。
- `docs_new/docs/references/environment_variables.mdx`（模块 文档；类别 docs；类型 documentation）: Mintlify 文档新增环境变量说明行。
- `docs/references/environment_variables.md`（模块 文档；类别 docs；类型 documentation）: 旧版 Markdown 文档中新增环境变量条目。

关键符号：get_max_chunk_capacity

## 关键源码片段

### `python/sglang/srt/environ.py`

注册环境变量 `SGLANG_MAX_KV_CHUNK_CAPACITY` 的核心位置，定义了默认值 128*1024。

```python
# python/sglang/srt/environ.py 中 Envs 类的相关代码片段

class Envs:
    # ... 其他配置 ...

    # DeepSeek MHA Optimization 块
    SGLANG_CHUNKED_PREFIX_CACHE_THRESHOLD = EnvInt(8192)
    # 新增：每个 KV chunk 的最大 token 数，默认 128*1024（131072）
    SGLANG_MAX_KV_CHUNK_CAPACITY = EnvInt(128 * 1024)

    # DeepEP 配置块 ...

```

### `python/sglang/srt/model_executor/forward_batch_deepseek_mha_mixin.py`

使用环境变量的关键位置，修改了 get_max_chunk_capacity() 方法。

```python
# python/sglang/srt/model_executor/forward_batch_deepseek_mha_mixin.py 中的相关方法

from sglang.srt.environ import envs

class ForwardBatchDeepSeekMHAMixin:
    # ... 其他属性 ...

    def get_max_chunk_capacity(self):
        # 以前硬编码为 128*1024，现在通过环境变量配置
        # 用户可通过 SGLANG_MAX_KV_CHUNK_CAPACITY 调整 chunk 大小
        return envs.SGLANG_MAX_KV_CHUNK_CAPACITY.get()

    # ... 其他方法 ...

```

# 评论区精华

该 PR 没有实质性 review 讨论，仅有 Fridge003 的 Approval 和 bot 自动评论。说明变更简单明确，已获维护者认可。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险极低。默认值与原硬编码值完全一致（128*1024），不改变任何当前行为。唯一风险是用户设置不合理数值可能导致注意力计算中的 chunk 大小异常，但该参数直接控制分块数量，影响的是计算粒度和显存使用。
- 影响：对现有用户无影响（默认行为不变）。对 DeepSeek 模型部署团队是有意义的改进，可针对不同硬件配置或序列长度分布调优 chunk 容量，以平衡注意力计算的分块数量与单次计算量。影响范围仅限于 DeepSeek MHA 分块前缀缓存路径。
- 风险标记：无相关风险

# 关联脉络

- PR #24874 Reject repetition_penalty=0 in SamplingParams.verify(): 同为通过环境变量 / 参数暴露内部配置的改进，可作类似模式参考。