# PR #29303 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[NPU] fix best practicce docs
- 合并时间：2026-06-26 11:17
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/29303

---

# 执行摘要

- 一句话：修复 Ascend NPU 最佳实践文档中的命令示例和环境变量引用问题
- 推荐动作：该 PR 是一次标准的文档维护，适合需要了解 NPU 平台最佳实践的用户参考。对于开发者来说，改动很直观，无需深入审查。

# 功能与动机

PR 标题和描述表明是为了修复最佳实践文档中的问题，提高文档质量。根据 patch 内容，具体包括补充页面导航链接、修复 shell 命令和变量语法、清理过期参数。

# 实现拆解

1. **添加页面导航链接**：在 `kimi_k2_6.mdx`、`qwen3_30b_a3b.mdx` 等 12 个文档的开头，将原本直接描述页面内容的句子替换为 `<Note>` 块，提示读者本页聚焦配置与基准结果，并链接到对应的模型教程页面。
2. **修正 JSON 参数引号**：在 `kimi_k2_6.mdx` 的多个启动命令示例中，将 `--model-loader-extra-config {"enable_multithread_load": true}` 改为 `--model-loader-extra-config '{"enable_multithread_load": true}'`，确保 JSON 字符串被正确引号包裹，避免 shell 解析错误。
3. **修正环境变量引用**：在 `qwen3_30b_a3b.mdx` 中，将 `export HCCL_ALGO=level0:NA;level1:ring` 改为 `export HCCL_ALGO="level0:NA;level1:ring"`，防止分号被 shell 解释为命令分隔符。
4. **移除无用参数**：在 `qwen3_235b_a22b.mdx` 中，删除了启动命令中的 `--init-expert-location` 参数，该参数已不再需要。

关键文件：
- `docs_new/docs/hardware-platforms/ascend-npus/best_practice/kimi_k2_6.mdx`（模块 文档；类别 other；类型 core-logic）: 改动最大（+7/-5），包含添加 Note 链接和修正多条命令中的 JSON 引号，是本次 PR 的核心文件。
- `docs_new/docs/hardware-platforms/ascend-npus/best_practice/qwen3_30b_a3b.mdx`（模块 文档；类别 other；类型 core-logic）: 修正了环境变量 HCCL_ALGO 的引号，并添加 Note 链接。
- `docs_new/docs/hardware-platforms/ascend-npus/best_practice/qwen3_235b_a22b.mdx`（模块 文档；类别 other；类型 core-logic）: 移除了不再需要的 --init-expert-location 参数，并添加 Note 链接。
- `docs_new/docs/hardware-platforms/ascend-npus/best_practice/deepseek_r1.mdx`（模块 文档；类别 other；类型 core-logic）: 添加 Note 链接，与 PR 主题一致。
- `docs_new/docs/hardware-platforms/ascend-npus/best_practice/deepseek_v3_2.mdx`（模块 文档；类别 other；类型 core-logic）: 添加 Note 链接。
- `docs_new/docs/hardware-platforms/ascend-npus/best_practice/glm5_1.mdx`（模块 文档；类别 other；类型 core-logic）: 添加 Note 链接。
- `docs_new/docs/hardware-platforms/ascend-npus/best_practice/minimax_m2_5.mdx`（模块 文档；类别 other；类型 core-logic）: 添加 Note 链接。
- `docs_new/docs/hardware-platforms/ascend-npus/best_practice/qwen3-8b.mdx`（模块 文档；类别 other；类型 core-logic）: 添加 Note 链接。
- `docs_new/docs/hardware-platforms/ascend-npus/best_practice/qwen3_32b.mdx`（模块 文档；类别 other；类型 core-logic）: 添加 Note 链接。
- `docs_new/docs/hardware-platforms/ascend-npus/best_practice/qwen3_5_397b.mdx`（模块 文档；类别 other；类型 core-logic）: 添加 Note 链接。
- `docs_new/docs/hardware-platforms/ascend-npus/best_practice/qwen3_6_27b.mdx`（模块 文档；类别 other；类型 core-logic）: 添加 Note 链接。
- `docs_new/docs/hardware-platforms/ascend-npus/best_practice/qwen3_6_35b_a3b.mdx`（模块 文档；类别 other；类型 core-logic）: 添加 Note 链接。

关键符号：未识别

## 关键源码片段

### `docs_new/docs/hardware-platforms/ascend-npus/best_practice/kimi_k2_6.mdx`

改动最大（+7/-5），包含添加 Note 链接和修正多条命令中的 JSON 引号，是本次 PR 的核心文件。

```mdx
---
metatags:
  description: "Best Practice for Kimi-K2.6 on Ascend NPU"
---

<Note>
This page focuses on optimal configuration and benchmark results for Kimi-K2.6 on the Ascend NPU. For environment setup, model weight download, feature configuration, and deployment instructions, etc., see the [Kimi-K2.6 Model Tutorial](/docs/hardware-platforms/ascend-npus/model-tutorials/kimi_k2_6).
</Note>

### Low Latency
...
python3 -m sglang.launch_server \
  --host 127.0.0.1 --port 6688 \
  --quantization modelslim \
  --dtype bfloat16 \
  --model-loader-extra-config '{"enable_multithread_load": true}' \  # 修正：添加单引号包裹 JSON
  --trust-remote-code \
  --device npu \
  --attention-backend ascend \
```

# 评论区精华

没有人工 review 讨论。Gemini Code Assist 自动评论确认改动正确，无需要解决的问题。

- 暂无高价值评论线程

# 风险与影响

- 风险：本次变更为纯文档修改，不涉及代码逻辑变更。风险极低，唯一的潜在风险是文档中的链接可能失效，但链接指向的是同仓库内的模型教程页面，相对路径正确。
- 影响：影响范围为所有阅读 Ascend NPU 最佳实践文档的用户。修正后的命令示例和环境变量设置避免了复制粘贴时的语法错误，降低了用户部署时的困惑。对系统性能和稳定性无影响。
- 风险标记：纯文档变更 , 无回归风险

# 关联脉络

- PR #29293 [NPU] [DOC] Add environment prerequisites to model tutorials: 同为 NPU 平台文档更新，与本 PR 都是围绕 Ascend NPU 文档质量改进，具有相同主题。
- PR #29313 [AMD] [GLM5] Mark EAGLE verified on MI300X/MI325X (gfx942) in GLM-5.1 cookbook: 也是文档更新，但涉及 AMD 而非 NPU，不过同属平台文档维护。