# PR #30223 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Add Hunyuan3 On Ascend Doc
- 合并时间：2026-08-11 21:20
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/30223

---

# 执行摘要

- 一句话：新增 Hy3 模型在昇腾 NPU 上的部署文档
- 推荐动作：值得作为 Ascend NPU 模型部署教程的参考模板精读，尤其适合关注多节点 PD 混合部署、投机解码参数和镜像版本策略的读者。文档在 review 中经历了从 daily build 到稳定镜像的务实收敛，体现了“文档必须与实际可运行版本绑定”的维护原则。

# 功能与动机

PR body 说明 Hunyuan3（Hy3）已正式在 Hugging Face 与 ModelScope 发布，需要为 Ascend 硬件提供官方部署示例。同时作者在 Accuracy Tests 中说明，在 PR#29909 修复之后 GPQA-Diamond 达到 87.8%，表明该文档配套了实际的正确性验证。

# 实现拆解

1. **新增教程页面**：创建 `docs/docs/hardware-platforms/ascend-npus/model-deployment/tutorials/hy3.mdx`（388 行），内容包括 Hy3 模型规格（295B 总参数、21B 激活参数、192 experts top-8、GQA 64/8/128、256K 上下文）、支持特性表格（TP、NPU Graph、EAGLE 投机解码、Overlap Schedule、reasoning_effort、tool calling）、环境准备（Docker 镜像拉取与容器启动，区分 A3/A2 两个 Tab）、单节点 A3 在线部署（16 逻辑 NPU、性能调优环境变量、CANN 配置）和多节点 A2 PD 混合部署（含 HCCL_SOCKET_IFNAME 等网络接口占位提示）。
2. **注册导航条目**：在 `docs/docs.json` 的 Ascend NPU Model Tutorials 列表中加入 `docs/hardware-platforms/ascend-npus/model-deployment/tutorials/hy3` 一行，使新页面进入文档站导航。
3. **review 迭代与结构调整**：早期版本曾放入旧的 `docs_new/` 目录并包含 multimodal 描述，review 要求确认多模态与 FP8 支持后，移除了多模态说明、删除了单独的 best-practice 页面、修正内部链接与 MTP 参数（对齐官方文档），最终把镜像从 daily build 换成稳定的 `v0.5.16` 标签。
4. **测试与验证**：PR 本身无单元测试（纯文档变更），但作者在 PR body 中给出 GPQA-Diamond 87.8% 的准确率验证，依赖同仓 PR#29909 的修复；CI 通过 `sglang-npu-bot` 的 `/tag-and-rerun-ci` 触发并通过。

关键文件：
- `docs/docs/hardware-platforms/ascend-npus/model-deployment/tutorials/hy3.mdx`（模块 文档教程；类别 docs；类型 entrypoint）: PR 核心内容，388 行完整部署教程，覆盖 A3/A2 单多节点、投机解码、环境变量调优等。
- `docs/docs.json`（模块 文档导航；类别 config；类型 configuration）: 将 hy3 页面注册到文档导航的 Model Tutorials 分组，确保新页面可被访问。

关键符号：未识别


# 评论区精华

Review 评论主要来自 `amote-i`，围绕文档准确性与可执行性展开：
- “1. please make sure fp8 quantization can run 2. if unnecessary, keep only the modelscope link” —— 要求确认 FP8 量化可用并精简下载链接。
- “make sure multimodal requests are supported on hy3” —— 要求确认多模态支持；最终文档删除了多模态描述。
- “Make sure all file path is valid” 与 “Unnecessary blank line” —— 要求核对内部链接并清理 docs.json 空行。
- “Does the stable version of SGLang have any issues with hy3?” —— 询问稳定版兼容性；作者随后把镜像从 daily build 切换为稳定版 v0.5.16。
- “Add a comment block at the start to remind the user to change this value. HCCL_SOCKET_IFNAME，GLOO_SOCKET_IFNAME” —— 要求对多节点网络环境变量增加提醒注释，已在最终提交中处理。

- 确认 FP8 量化可用性并精简模型链接 (question): 文档最终只保留 ModelScope 链接，且未在特性表中宣称 FP8 支持。
- 多模态支持确认 (question): 最终文档删除多模态描述，只保留文本推理与投机解码相关特性。
- 稳定版镜像与 daily build 的取舍 (design): 作者将 A3/A2 镜像标签切换为稳定版 v0.5.16，并移除 daily-build 注释。
- 多节点网络环境变量提醒 (documentation): 已添加 reminder 注释，并在后续提交中清理冗余占位符。
- 内部链接有效性与格式清理 (documentation): 作者更新了内部链接到新 docs 路径，并移除了 docs.json 的空行。

# 风险与影响

- 风险：纯文档变更，无代码回归风险。主要风险是文档内容与真实环境脱节：镜像标签（`cann9.0.0-a3-v0.5.16` / `cann9.0.0-910b-v0.5.16`）若后续版本变化可能过期；多节点部署涉及的 `HCCL_SOCKET_IFNAME` 等环境变量是占位提醒，用户若不修改会踩坑；文档中 `--tp-size 16`、`--cuda-graph-bs` 等配置依赖特定硬件拓扑（A3 8 卡 × 2 dies），在 A2 上需另行调整。
- 影响：对用户：为中文社区与 Ascend 用户提供了 Hy3 的可用部署路径，降低 295B 大模型在 NPU 上的上手成本；对团队：文档站新增一个教程页面，导航结构无破坏性变更；对系统：无运行时影响，仅 `docs/docs.json` 一行配置。
- 风险标记：文档镜像版本可能过期 , 多节点占位参数需用户自改 , 无自动化文档验证

# 关联脉络

- PR #29909 fix related to Hy3 accuracy on Ascend: PR body 明确提到 87.8% GPQA-Diamond 准确率依赖此修复，是本文档准确率验证的前提。