# PR #29501 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[NPU] [DOC] Fix and update Ascend NPU docs
- 合并时间：2026-06-27 18:23
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/29501

---

# PR 分析报告：修复并更新 Ascend NPU 文档

## 执行摘要

本 PR 集中修复了 Ascend NPU 文档中由自动化工具发现的若干错误，并同步更新了对新特性的支持描述。变更涉及 9 个文档文件，其中 `ascend_npu_accuracy_evaluation.mdx` 改动最大（+25/-5），增加了 SSL 证书错误的稳定解决方案。整体变更纯属文档范畴，不涉及代码逻辑，改进后能有效降低用户在使用 NPU 部署时的困惑。

## 功能与动机

根据 PR 描述，作者通过自动化 skill 工具扫描发现文档中存在多处不准确或过时的内容。主要动机为：

- 修复文档中的事实性错误（如环境变量描述、路径样例）
- 更新 NPU 后端已支持的新特性（如 DeepEP 长序列流水线、GLM-5.2 部署示例）
- 增强文档的可用性和安全性提示（如 SSL 解决方案）

## 实现拆解

1. **安全性改进（accuracy_evaluation.mdx）**：
 - 保留原有的临时 SSL 关闭方案，但新增 **Warning**警告组件，明确提示用户该操作会全局禁用证书验证，仅限测试环境。
 - 新增稳定的解决方案：通过设置 `REQUESTS_CA_BUNDLE` 环境变量指定代理 CA 证书。
2. **环境变量描述修正（environment_variables.mdx）**：
 - 将三个 DeepEP 相关变量的描述从错误的 "ant-moving" 更正为准确的 "long-sequence token pipelining"。
3. **GLM-5.2 示例文档完善（glm5.2_examples.mdx）**：
 - 添加 YAML frontmatter 提供页面标题和描述。
 - 修正量化工具 `msmodelslim` 的拼写。
 - 将代码块标记从 `{code-block} bash` 改为标准的 `bash`。
 - 将文档引用从相对路径改为绝对路径（`/docs/...`）。
4. **安装指南改进（ascend_npu.mdx）**：
 - 添加 `description` 元数据。
 - 修复模型路径，增加了 `Qwen/` 命名空间。
 - 优化措辞（如 "roaring" → "operating at optimal performance"）。
5. **其余小修**：
 - FAQ 中修正了代码块语言标记（`text → python/shell`）。
 - 性能测试、profiling、量化、特性支持等页面进行了标点和格式微调。

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

该文件变更量最大，新增了 SSL 证书错误的稳定解决方案和临时工作区说明，并增加了 Warning 和 Note 组件，显著提升了文档实用性和安全性提示。

以下片段展示了 SSL 解决方案的核心部分，包括临时工作区和稳定方法的对比，以及安全警告。
```mdx
{/* 临时工作区：仅在测试环境使用！ */}
**Temporary workaround (test only):**
Navigate to your Python environment's `site-packages/requests/sessions.py`,
find the `class Session` definition, and set `self.verify = False`.

<Warning>
This **disables TLS certificate validation globally** for the Python `requests` library.
Use it **only as a temporary diagnostic step** in isolated test environments —
never in production.
</Warning>

{/* 稳定解决方案：指定代理的 CA 证书 */}
**Stable solution:**
The error is caused by a corporate TLS proxy injecting a self-signed certificate.
Point `requests` to the proxy's CA bundle:

```shell
# Obtain the CA certificate from your network administrator
# Then set the environment variable:
export REQUESTS_CA_BUNDLE=/path/to/your-proxy-ca-bundle.crt
```

<Note>
This is a common workaround for corporate proxy environments. If it does not resolve
your issue, consult your IT department — proxy configurations vary across organizations.
</Note>
```

# Obtain the CA certificate from your network administrator
# Then set the environment variable:
export REQUESTS_CA_BUNDLE=/path/to/your-proxy-ca-bundle.crt
```

<Note>
This is a common workaround for corporate proxy environments. If it does not resolve
your issue, consult your IT department — proxy configurations vary across organizations.
</Note>
```

**片段二：DeepEP 环境变量描述修正（ascend_npu_environment_variables.mdx）**
```mdx
| `<code>DEEPEP_NORMAL_LONG_SEQ_PER_ROUND_TOKENS</code>` | Enable long-sequence token pipelining in dispatch stage. Indicates the number of tokens transmitted per round on each rank. | `8192` |
| `<code>DEEPEP_NORMAL_LONG_SEQ_ROUND</code>` | Enable long-sequence token pipelining in dispatch stage. Indicates the number of rounds transmitted on each rank. | `1` |
| `<code>DEEPEP_NORMAL_COMBINE_ENABLE_LONG_SEQ</code>` | Enable long-sequence token pipelining in combine stage. The value `0` means disabled. | `0` |
```
（旧描述均使用 "ant-moving" 的不准确表述。）

## 评论区精华

- **模型路径质疑**：gemini-code-assist[bot] 认为 `Qwen/Qwen3-VL-30B-A3B-Instruct` 可能不存在，但作者回复“Not a problem”。
- **Python 路径泛化**：机器人建议将固定版本路径改为通用描述，作者认为路径可从 trace 日志中找到，保持原样。
- **绝对链接 vs 相对链接**：机器人建议将 `/docs/...` 改为相对路径以兼容 GitHub 渲染和 Docusaurus 构建，但作者未回应，最终 PR 保留了绝对路径。这个决策值得后续关注，因为绝对路径在不同部署环境下可能断裂。

## 风险与影响

- **事实性风险**：模型路径是否可用仍需验证，但作者表示已知晓。
- **兼容性风险**：绝对路径在 Docusaurus 中需要 `baseUrl` 正确配置，否则可能会出现 404。
- **影响范围**：仅限于 NPU 文档的读者，属于纯文档改进，无代码侧影响。

## 关联脉络

本 PR 与 #29486（GLM-5.2 cookbook 更新）、#29466（GLM-5.2 NVFP4 配置更新）有间接关联，都是 GLM-5.2 部署文档的持续完善。整体上，SGLang 项目在持续完善对 Ascend NPU 硬件的文档覆盖，体现了对多硬件后端的支持投入。