执行摘要

• 一句话：更新 Ascend vLLM 最佳实践文档，新增详细指南
• 推荐动作：对于希望在 Ascend 上使用 vLLM 的开发者，建议精读此文档并参考其中的脚本。对于团队维护者，该 PR 展示了文档 Review 中应关注的示例可运行性要点。

功能与动机

从 PR 标题和 body 可知，目的是更新 Ascend vLLM 最佳实践文档，补充环境构建、训练、评测等步骤，帮助用户在 Ascend 硬件上快速上手 vLLM。关联的实践脚本和参考链接表明本次更新源于用户实际部署经验总结。

实现拆解

1. 新增核心文档：创建 docs/ascend_tutorial/model_support/examples/ascend_vllm_best_practices.rst，包含环境安装、模型下载与转换、训练（单节点/多节点）、性能采集等内容。
2. 更新文档索引：在 docs/ascend_tutorial/index.rst 的 toctree 中添加该文档的引用。
3. 修复文件尾格式：在 ascend_sglang_best_practices.rst 末尾添加缺失的换行符。

关键文件：

• docs/ascend_tutorial/model_support/examples/ascend_vllm_best_practices.rst（模块 文档；类别 docs；类型 documentation）: 这是本次 PR 的核心变更，新增了 306 行详细的 Ascend vLLM 最佳实践指南，包括环境配置、数据准备、单节点/多节点训练脚本及性能采集方法。
• docs/ascend_tutorial/index.rst（模块 文档；类别 docs；类型 documentation）: 更新文档目录索引，将新增的最佳实践文档加入 toctree，确保在文档站点中可见。
• docs/ascend_tutorial/model_support/examples/ascend_sglang_best_practices.rst（模块 文档；类别 docs；类型 documentation）: 修正文件末尾缺失的换行符，属于格式清理。

关键符号：未识别

关键源码片段

docs/ascend_tutorial/model_support/examples/ascend_vllm_best_practices.rst

这是本次 PR 的核心变更，新增了 306 行详细的 Ascend vLLM 最佳实践指南，包括环境配置、数据准备、单节点/多节点训练脚本及性能采集方法。

# 设置镜像端点以下载模型
export HF_ENDPOINT=https://hf-mirror.com
​
# 下载 Qwen3-30B 模型权重，--local-dir 替换为实际路径
huggingface-cli download --resume-download Qwen/Qwen3-30B-A3B-Base --local-dir /path/to/local_dir
​
# 下载 GSM8K 数据集
git clone https://www.modelscope.cn/datasets/modelscope/gsm8k.git
​
# 可选：将 HuggingFace 权重转换为 Megatron 格式（MoE 模型需 --use_cpu_initialization）
python scripts/converter_hf_to_mcore.py \
    --hf_model_path Qwen/Qwen3-30B-A3B-Base \
    --output_path Qwen/Qwen3-30B-A3B-Base-mcore \
    --use_cpu_initialization

评论区精华

Review 中主要关注文档示例代码的准确性和健壮性。关键问题包括：

1) 网络接口变量硬编码，应使用变量引用；
2) ASCEND_RT_VISIBLE_DEVICES 指定了 9 个设备但节点只有 8 个；
3) ifconfig 命令在现代容器中不可用，应替换为 ip 命令；
4) Worker 节点使用 sleep 600 会导致训练中途退出，建议改为 sleep infinity；
5) vLLM 参数 --distributed_executor_backend 应使用连字符 --distributed-executor-backend。这些建议大部分被采纳并体现在最终提交中。

• 网络接口变量硬编码 (correctness): 已被接受并修正，最终版本中改用了变量引用。
• vLLM 参数连字符格式 (correctness): 已修正为连字符格式，确保 vLLM 能正确识别。
• Worker 节点超时设置 (correctness): 已采纳，最终版本中改为 sleep infinity。

风险与影响

• 风险：主要风险在于文档中的示例代码如果直接复制使用可能失败。例如硬编码的变量、错误的设备数量、不兼容的命令等，会导致用户部署受阻。Review 已暴露这些问题并得到修正，但若用户使用中间版本可能遇到问题。此外，文档依赖特定 commit 版本，未来可能过时。
• 影响：影响范围限于 Ascend NPU 用户。为这类用户提供了清晰、可复现的最佳实践，降低了上手门槛。对系统其他模块无影响，仅文档变更。
• 风险标记：示例代码硬编码变量, vLLM 参数格式错误, 设备数量配置错误

关联脉络

• PR #6667 [doc] feat: update Qwen3.5 NPU guide: 同为 Ascend 文档更新，完善模型支持文档，与该 PR 共同丰富 Ascend 文档体系。
• PR #6657 [veomni] fix: add veomni backend docs for ascend: 新增 VeOmni Ascend 后端文档，同样属于 Ascend 文档增强。