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 解决方案的核心部分，包括临时工作区和稳定方法的对比，以及安全警告。

{/* 临时工作区：仅在测试环境使用！ */}
**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

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.

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

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.

**片段二：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` |

评论区精华

• 模型路径质疑：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 硬件的文档覆盖，体现了对多硬件后端的支持投入。