执行摘要

• 一句话：新增 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 准确率依赖此修复，是本文档准确率验证的前提。