执行摘要

• 一句话：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/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/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(): 同为通过环境变量/参数暴露内部配置的改进，可作类似模式参考。