# PR #22499 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Update HiSparse's user-guide
- 合并时间：2026-04-10 15:06
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/22499

---

## 执行摘要
本次 PR 更新了 HiSparse（高性能稀疏注意力）功能的用户指南文档，主要调整了配置参数示例（`device_buffer_size` 从 4096 改为 6144，`host_to_device_ratio` 从 5 改为 10），移除了 `--page-size 64` 参数，并新增了基准测试命令示例。这些变更旨在提供更准确的部署指导，特别是针对大规模内存配置场景，对系统运行无直接影响。

## 功能与动机
PR body 中未明确说明具体动机，但从变更内容推断，是为了反映 HiSparse 功能的最新配置实践。文档更新包括参数调整和新增基准测试示例，目的是帮助用户更有效地部署和测试 HiSparse 功能。例如，在配置建议中补充了根据主机内存大小（如 1TB 或 2TB）设置 `host_to_device_ratio` 的指导。

## 实现拆解
仅修改了 `docs/advanced_features/hisparse_guide.md` 文件，具体变更如下：
1. **配置参数更新**：
 - 将示例中的 `device_buffer_size` 从 4096 调整为 6144
 - 将 `host_to_device_ratio` 从 5 调整为 10
2. **部署命令优化**：
 - 从两个 `python3 -m sglang.launch_server` 命令中移除了 `--page-size 64` 参数
3. **新增基准测试示例**：
   ```bash
   python3 -m sglang.bench_serving \
     --backend sglang \
     --dataset-path /path/to/ShareGPT_V3_unfiltered_cleaned_split.json \
     --dataset-name random \
     --random-input 40000 \
     --random-output 20000 \
     --num-prompts 200 \
     --max-concurrency 200 \
     --request-rate 40 \
     --random-range-ratio 1.0 \
     --host 127.0.0.1 \
     --port 20000 \
     --model /path/to/model \
     --flush-cache
   ```
4. **补充配置建议**：明确 `host_to_device_ratio` 应根据主机可用内存设置，如 ~1TB 内存对应 5，~2TB 内存对应 10。
5. **添加致谢部分**：感谢 SGLang 团队和社区贡献者。

## 评论区精华
Review 过程中仅有一名审核者（xiezhq-hermann）批准，无具体评论。提交历史显示作者进行了三次提交（'Update command'、'upd'、'upd'），表明可能对文档内容进行了细微调整，但无公开的技术讨论记录。

## 风险与影响
**风险分析**：
- 文档变更本身无技术风险，但配置参数调整可能未同步更新代码中的默认值或注释，存在文档与代码不一致的潜在风险。
- 移除 `--page-size 64` 参数未提供说明，可能使用户困惑该参数是否仍需要或默认值已变化。

**影响分析**：
- 仅影响文档用户，提供更准确的部署指导，特别是基准测试示例有助于用户评估性能。
- 对系统功能、性能或安全性无直接影响。

## 关联脉络
从近期历史 PR 看，HiSparse 相关功能在仓库中持续演进，但本次 PR 为纯文档更新，未发现直接关联的代码变更 PR。文档更新可能基于实际部署经验或内部测试结果，反映了 HiSparse 功能的最佳实践调整。