ascend-assistant · diff
git:20260823.4193ab3 to v2.0.0
101 added, 79 removed. Audit A to A.
---
name: ascend-assistant
- description: 昇腾服务器助手 —— 帮助用户在本地用 AI 直接操作、查询、排障华为昇腾（Ascend/NPU）智算服务器。覆盖环境检测与排障、命令生成与建议、部署脚本引导、性能调优建议四类能力。当用户遇到昇腾装机、驱动/CANN/框架报错、想生成安装/推理/调优命令，或需要把昇腾服务器跑起来时使用。与其配套的完整手册是 AscendMate（昇腾之家）。
+ description: >
+ 昇腾服务器助手 —— 让 AI 直接帮你操作、查询、排障华为昇腾（Ascend/NPU）智算服务器。
+ 覆盖四类能力：环境检测与排障、命令生成与建议、部署脚本引导、性能调优建议。
+ 当用户遇到昇腾装机、驱动/CANN/框架报错、想生成安装/推理/调优命令、需要把昇腾服务器跑起来，
+ 或需要性能调优时使用。与 AscendMate（昇腾之家）手册深度联动。
+ keywords:
+ - 昇腾
+ - Ascend
+ - NPU
+ - npu-smi
+ - CANN
+ - torch_npu
+ - MindSpore
+ - 环境检测
+ - 排障
+ - 部署
+ - 推理
+ - 性能调优
+ - Profiling
+ - 智算服务器
+ - Atlas
license: MIT
+ metadata:
+ author: AscendLA
+ version: "2.0.0"
+ skill-type: orchestration
+ allowed-tools: Bash(*) Python3(*) Read(*) Edit(*)
---
# Ascend Assistant · 昇腾服务器助手
- 让 AI Agent 帮助用户操作昇腾智算服务器的一套技能（Skill）。它不是一个独立的程序，而是**给 AI 助手的操作指南**：当用户对着一台昇腾服务器提问时，触发本 Skill 后，AI 能安全、准确地帮你检测环境、定位报错、生成命令、引导部署、给出调优建议。
+ 让 AI Agent 帮助用户操作昇腾智算服务器的一套技能（Skill）。当用户对着一台昇腾服务器提问时，AI 依据本 Skill 安全、准确地帮你：检测环境、定位报错、生成命令、引导部署、给出调优建议。
- 本 Skill 与 **[AscendMate（昇腾之家）](https://github.com/RevolutionLA/AscendMate)** 深度配套：AscendMate 是完整手册（环境搭建/训练/推理/算子/工具链/FAQ），本 Skill 负责"遇到具体问题时怎么一步步操作"，两者互相引用。
+ **本 Skill 是"混合模式"**：
+ - **内建完成**四类通用能力（覆盖绝大多数日常提问）；
+ - 遇到**专项深度任务**（复杂 profiling 分析、驱动自动安装、算子代码生成等），**路由到昇腾官方 `agent-skills` 中的成熟 skill**，避免重复造轮子。
+ 配套完整手册：**[AscendMate（昇腾之家）](https://github.com/RevolutionLA/AscendMate)** —— AscendMate 负责"为什么、完整怎么做"；本 Skill 负责"你手头这台机器、现在就帮我做"。
+
---
## 触发场景
- 当用户的**意图**匹配下面任一情况时，应主动激活本 Skill：
+ 用户意图匹配如下任一情况即触发：
- - 想查看昇腾服务器当前环境：设备/驱动/CANN/框架是否装好、可用性检查。
+ - 查看昇腾服务器当前环境：设备/驱动/CANN/框架是否装好、可用性检查。
- 遇到报错：`npu-smi` 无输出、驱动装不上、CANN 环境变量报错、`torch_npu`/`MindSpore` 起不来、推理 OOM、训练失败等。
- 想生成/确认命令：安装命令、启动推理服务命令、微调脚本、性能采集命令等。
- 想从裸机一步步把昇腾服务器跑起来（部署引导）。
- 想对推理/训练做性能调优。
- > 何时不触发：纯硬件采购选型、商务问题，应引导到 [AscendMate 硬件选型](/hardware/)。
-
- ---
-
- ## 核心原则
-
- 1. **先检测，再建议**：先让用户跑关键命令（如 `npu-smi info`）拿到真实状态，基于输出定位，不凭空猜。
- 2. **安全第一**：涉及 `dd`、驱动升级、清空、重装等高风险操作，一律先解释风险、给确认步骤，不默认执行。
- 3. **版本配套是前提**：昇腾最大的坑是版本不配套（驱动/CANN/框架/OS 互相匹配）。任何方案先确认配套表。
- 4. **给可照做的命令**：给出命令的同时给"怎么验证成功"和"失败往哪查"。
- 5. **诚实**：不确定的版本/命令标注"以官方发布为准"，不编造参数字段。
- 6. **联动手册**：具体步骤/完整教程指向 AscendMate 对应章节，避免本 Skill 重复长文。
+ > 不触发：纯硬件采购选型、商务问题 → 引导到 [AscendMate 硬件选型](/hardware/)。
---
- ## 四类能力
+ ## 四类内建能力
### 能力一：环境检测与排障
- **目标**：让用户知道服务器现在是什么状态、问题出在哪。
+ **目标**：让用户知道服务器当前状态、问题出在哪。
**标准检测流程**（让用户按序粘贴输出，AI 逐项解读）：
```bash
- # 1. 设备与驱动
- npu-smi info # 是否列出设备、Driver 版本、NPU 健康状态
- # 2. 驱动内核模块
- lsmod | grep npu
- # 3. CANN 环境
+ npu-smi info # 设备与驱动
+ lsmod | grep npu # 驱动内核模块
echo $ASCEND_HOME; cat /usr/local/Ascend/ascend-toolkit/latest/version.cfg
- # 4. 框架可用性
python -c "import torch; import torch_npu; print(torch.npu.device_count())"
python -c "import mindspore; mindspore.set_device('Ascend'); mindspore.run_check()"
- # 5. 系统
uname -a; cat /etc/os-release
```
- **排障映射**（报错 → 常见方向）：
+ **分层确定性语言（本 Skill 硬性要求）**：
+ - **事实层**：设备有无、驱动版本、报错文本 —— 用断言语调。
+ - **归因层**：问题可能原因 —— 用 `可能 / probable`；证据不足 → `insufficient_evidence`，明说"需进一步验证"。
+ - 绝不用确定性语气描述未经证实的原因。
- | 现象/报错 | 优先排查 | AscendMate 章节 |
- |---|---|---|
- | `npu-smi: command not found` / 无设备 | 驱动是否装、内核模块是否加载、是否 root | [固件驱动](/setup/firmware-driver) |
- | `driver not initialized` | 版本配套、驱动 vs 内核 | [环境搭建类问题](/faq/setup-issues) |
- | `source ...set_env.sh` 路径错 | `ascend-toolkit` vs `ascend_toolkit` 拼写/路径 | [CANN 安装](/setup/cann-install) |
- | `import torch_npu` 失败 | torch 与 torch_npu 版本配套 | [torch_npu 安装](/setup/torch-npu-install) |
- | 推理 OOM / 起不来 | batch/seq/KV 显存策略 | [推理类问题](/faq/inference-issues) |
- | 训练 loss NaN / 精度不对 | 混合精度、随机种子 | [性能与精度问题](/faq/perf-precision-issues) |
+ **排障映射**（报错 → 方向 → 手册章节）：见 [references/troubleshooting-map.md](references/troubleshooting-map.md)。
- > 详细 FAQ 与自检清单见 [AscendMate 问题定位 /faq/](/faq/) 与 [环境自检清单](/setup/checklist)。
+ > 详细 FAQ 见 [AscendMate /faq/](/faq/)，自检清单见 [环境自检清单](/setup/checklist)。
### 能力二：命令生成与建议
- **目标**：根据用户真实目标，给出可直接复制的命令，并解释。
+ **目标**：按用户真实目标给出可直接复制命令，并解释。
- - **安装类**：根据操作系统/架构/CANN 版本，生成固件驱动、CANN Toolkit/Kernels、torch_npu、MindSpore 的安装命令与脚本。
- - **推理类**：生成 MindIE / vLLM-Ascend / SGLang 拉起推理服务的命令。
- - **微调类**：生成 LLaMA-Factory 的微调命令（LoRA/QLoRA/全参、单机/多机）。
- - **运行类**：转译用户想法为可执行 shell/python。
+ 生成命令固定给三段：
+ 1. **前置**：需已装什么/变量。
+ 2. **命令**：含可替换占位符。
+ 3. **验证 + 报错往哪查**。
- 生成命令时固定给出三段：
- 1. 前置（需已装什么 / 变量）
- 2. 命令本身（含可替换占位符）
- 3. 验证（如何确认成功）+ 报错往哪查
+ 常见命令库见 [references/command-reference.md](references/command-reference.md)。
- **示例**（装 torch_npu 前的配套确认）：
+ ### 能力三：部署脚本引导
- ```bash
- # 先确认 CANN 版本
- cat /usr/local/Ascend/ascend-toolkit/latest/version.cfg
- # 再对照官方 torch_npu 配套表选对应 torch 版本（以官方发布为准）
- ```
+ **目标**：从裸机到可用分步引导，按用户回答逐步推进。
- > 完整命令参考见 [AscendMate](/training/llama-factory)、[推理](/inference/)。
+ 按 [AscendMate 7 步走](/guide/seven-steps) 的 `上电与规划 → 操作系统 → 固件驱动 → CANN → AI框架 → 业务接入 → 自检` 逐阶段推进。原则：一次只推进一步；每步让用户贴命令输出再进入下一步；选路（PyTorch vs MindSpore、在线 vs 离线）先问清。
- ### 能力三：部署脚本引导
+ 完整工作流模板见 [references/deployment-workflow.md](references/deployment-workflow.md)。
- **目标**：从裸机到可用的分步引导，让 AI 按用户回答逐步推进。
+ ### 能力四：性能调优建议
- 按 **[AscendMate 7 步走](/guide/seven-steps)** 逐阶段引导，每步先询问、再给命令、再验证：
+ **目标**：基于 profiling 数据/现象给可操作方向。
- ```
- 上电与规划 → 操作系统 → 固件驱动 → CANN → AI框架 → 业务接入 → 自检
- ```
+ - 引导用 **Profiling** 采集，关注：算子耗时占比、通信占比、HBM 利用率、显存。
+ - 现象 → 建议方向表见 [references/perf-tuning.md](references/perf-tuning.md)。
+ - 完整工具说明见 [AscendMate 性能调优](/tools/profiling)。
- 引导原则：一次只推进一步；每步结束让用户贴关键命令输出再进入下一步；遇到岔路（选 PyTorch 还是 MindSpore、在线还是离线）先问清。
+ ---
- ### 能力四：性能调优建议
+ ## 官方 skill 路由表（混合模式）
- **目标**：基于 profiling 数据/现象给出可操作建议。
+ 当用户请求命中以下**专项深度任务**时，应优先**调用/引导到昇腾官方 `agent-skills`**（<https://github.com/Ascend/agent-skills>）中的对应 skill，而非在本 Skill 内重复实现：
- - 引导用户用 **Profiling** 采集（见 [AscendMate 性能调优](/tools/profiling)），关注：算子耗时占比、通信占比、HBM 利用率、显存。
- - 按现象给方向：
+ | 专项场景 | 官方 skill | 备注 |
+ |---|---|---|
+ | 复杂 profiling 异常分析 / 性能 bottle-neck 归因 | `ascend-profiling-anomaly` | 深度推理，带 references/rulebook + 脚本 |
+ | NPU/固件自动安装 | `ascend-npu-driver-install` | 端到端自动化 + 脚本 |
+ | 设备管理命令大全 | `npu-smi` | health/temp/power/memory/ECC/虚拟化/证书 |
+ | vLLM-Ascend 服务部署 | `vllm-ascend-deploy` | 推理部署专项 |
+ | Docker 跑昇腾容器 | `ascend-docker` | 容器环境 |
+ | AscendC / Triton 算子开发 | `ascendc-operator-*` / `triton-operator-*` | 算子全流程 |
+ | ATB 加速 / 算子迁移 | `ascend-transformer-boost` | index skill 编排子 skills |
- | 现象 | 建议方向 |
- |---|---|
- | 单算子慢 | 换融合算子、Ascend C 自研、核对并行策略 |
- | 通信占比高 | 调张量/流水并行、减小通信、HCCL |
- | HBM/显存不足 | 减 batch、重计算、优化器切分、KV 策略 |
- | 推理吞吐低 | 连续批处理、增大并发、KV cache 调优 |
- | 精度不对 | 先 fp32 对比、固定随机种子、精度调试工具 |
+ **路由规则**：
+ 1. 用户请求属于上表专项 → 明确告知用户"这属于官方 `Ascend/agent-skills` 的 `X` skill 能力"，并给出仓库路径与触发方式；若用户的环境已装该 skill，直接按该 skill 执行。
+ 2. 其余通用请求（日常环境检测、基础排障、命令确认、整体部署引导、基础调优建议）→ 由本 Skill 内建能力完成，并联动 AscendMate。
+ 3. 拿不准 × 通用性问题 → 先做环境检测（能力一），拿到事实后再决定是否路由。
- > 详见 [AscendMate 性能与精度问题](/faq/perf-precision-issues)。
+ ---
+ ## Reference files 使用
+
+ | 文件 | 何时读 |
+ |---|---|
+ | [references/troubleshooting-map.md](references/troubleshooting-map.md) | 排障（能力一）时，查报错映射 |
+ | [references/command-reference.md](references/command-reference.md) | 命令生成时，查常用命令库 |
+ | [references/deployment-workflow.md](references/deployment-workflow.md) | 部署引导时，查 7 段工作流模板 |
+ | [references/perf-tuning.md](references/perf-tuning.md) | 性能调优时，查现象→方向表 |
+
---
- ## 参考文件
+ ## 与 AscendMate 手册的联动
- 本 Skill 用到的昇腾资料索引（避免重复大段搬运，统一指向权威源）：
+ 本 Skill 尽量少重复长文，具体教程/完整命令统一指向 AscendMate 对应章节：
- - **AscendMate（昇腾之家）**：一站式中文章节手册 → <https://github.com/RevolutionLA/AscendMate>
- - 昇腾文档中心：<https://www.hiascend.com/document>
- - 昇腾软件/驱动/CANN 下载：<https://www.hiascend.com/developer/download>
- - 兼容性查询：<https://www.hiascend.com/hardware/compatibility>
+ | 能力 | 联动章节 |
+ |---|---|
+ | 环境检测 / 自检 | [环境自检清单](/setup/checklist) |
+ | 排障 | [/faq/ 问题定位](/faq/) |
+ | 命令生成 | [训练](/training/) · [推理](/inference/) |
+ | 部署引导 | [7 步走](/guide/seven-steps) |
+ | 性能调优 | [性能调优 Profiling](/tools/profiling) |
- ## 许可 & 免责
+ ---
- MIT。本 Skill 基于公开资料整理，命令与版本以官方发布为准。高风险操作请谨慎并自行担责。
+ ## 安全与免责
+
+ - 高风险操作（驱动升级、`dd`、清空、重装、固件）**必须先解释风险、给确认步骤，不默认执行**。
+ - 版本配套是前提；不确定的版本/字段标注"以官方发布为准"，不编造。
+ - 本 Skill 基于公开资料整理，命令以官方发布为准；操作风险由使用者自行确认与承担。