从零到交付：昇腾大模型项目交付全流程

副题：一个 FDE（前沿部署工程师）岗位视角的实操手册 版本基准：CANN 9.2.0-beta.2 ／ HDK 26.1.x ／ MindIE 3.1.0 ／ MindSDK（RAG SDK）26.1.0 写法说明：本文所有命令、参数、路径、包名均来自昇腾官方文档（出处见附录 A）。每条命令按「含义 / 拆解 / 用法 / 期望 / 不过会怎样」五件套写 —— 有命令必须有结果。

〇、这个岗位要什么：能力要求与技能共性

0.1 FDE 是什么

FDE = Field / Forward Deployed Engineer，国内常见译名「前沿部署工程师」，也有写成「前置驻场交付工程师」的。

这个岗位的实质，用一句话说清：

把 AI 产品在客户自己的环境里真正落地 —— 它不是一个研发岗，也不是一个售前岗，而是"连接产品与客户现场"的那个角色。

关键词	含义
端到端交付	不是只负责某一段，是从接触到验收全程
在客户场景中落地	不是做产品研发，是在别人的环境里把它跑起来
连接研发与客户	两头都要懂 —— 这是它最难的地方

0.1.1 这个岗位的职责范围（按能力要求归纳）

把真实岗位的职责描述归并同类项，得到五条主线：

#	职责	具体做什么
1	客户现场部署	AI 产品在客户现场的上线部署、集成调试与效果调优，保障核心场景的交付效果
2	私有化与算力适配	私有化部署方案选型，确保模型在国产算力（如华为昇腾）上的适配表现
3	算力底座搭建	昇腾系列 NPU 算力集群的环境搭建、驱动安装、固件适配、CANN 工具链部署与调试
4	模型的现场适配	把客户已有的模型/脚本迁到目标算力上，并调到可用
5	业务落地与交付	把模型接到客户的业务上（如企业知识库），并交付文档、培训与验收材料

⭐ 一句话概括：从"服务器还没装系统"一路干到"客户能自己用"，中间每一段都要能自己顶上。

0.2 昇腾方向的具体要求

昇腾方向的 FDE，技术侧被明确点名的就是"算力底座"那一串动作：

负责 昇腾系列 NPU 算力集群的环境搭建、驱动安装、固件适配、 CANN 工具链部署与调试，熟练完成昇腾算力底座环境全流程搭建。

落地部署协同：协调研发进行私有化部署方案选型，确保模型在国产算力（如华为昇腾）上的适配表现。

这两句话值得逐字读一遍 —— 它把昇腾方向的交付范围画得很清楚：

它要求的	对应本体系的哪些内容
环境搭建	A0–A3（硬件与驱动）、服务器配置
驱动安装、固件适配	A1 驱动与固件
CANN 工具链部署与调试	B1–B5
模型在国产算力上的适配	C 层（框架）、F1（模型迁移）
私有化部署	G1
业务落地	G2–G9（企业知识库等）

⭐ 也就是说：这条岗位要求，几乎是把本体系的 A→G 逐条点了名。

0.3 ⭐ 技能共性：这个岗位到底要什么

三层结构，时间占比差别很大：

层	内容	从哪里来
A 业务侧	需求澄清、业务结构化、对一号位讲价值、利益相关方管理、现场应变、行业理解	约占 70% 时间
B 技术侧	私有化部署、国产算力适配、Agent 平台、全栈与云原生、模型选型与成本、数据接入、模型能力边界、LLM 推理逻辑	约占 30%
C 元能力	判断能不能沉淀复用、判断自己能力与需求是否匹配、接受"技术不难、难在人"	全篇的底色

⭐ 共性里最值得注意的四条（多条岗位重复出现）：

「端到端」是高频词 —— 要求一个人能走完全程，不是只会一段；
「私有化 + 国产算力适配」是昇腾方向的专有要求 —— 这条直接把昇腾技能变成刚需技能；
「现场」两个字反复出现 —— 客户机房不是你的实验室，不确定性和约束都在现场；
「调优」「效果」反复出现 —— 交付不是"装完就走"，是"跑出效果才算完"。

0.4 ⭐ 由此推出的交付全流程（本文的骨架）

把上面四条共性落到昇腾场景，交付全流程就是八段：

① 接单与澄清      ← 业务侧，决定后面全部
② 现场摸底        ← 把"不可返工的事"查清楚
③ 算力底座搭建    ← 驱动 → 固件 → CANN（招聘原文点名的三件事）
④ 框架与服务      ← PyTorch/TorchNPU 或 vLLM Ascend / MindIE Motor
⑤ 模型迁移与适配  ← 把客户的模型真正跑起来
⑥ 业务落地        ← RAG 私有知识库（企业最常见的第二个需求）
⑦ 验收与交付      ← 出证据、交文档、做培训
⑧ 上线后          ← 运维、复盘、沉淀复用（这是 FDE 与外包的分界线）

⭐ 这个顺序不是按技术难度排的，是按"手伸进去的顺序"排的：先要知道给谁做（①）→ 再看有什么（②）→ 再搭地基（③）→ 再起服务（④⑤） → 再做业务（⑥）→ 再证明做成了（⑦）→ 再让它活下去（⑧）。

一、第 ① 段：接单与澄清（业务侧，但决定技术方案）

1.1 为什么这一段排第一

因为 70% 的时间和失败都在这儿。

从业者访谈里反复出现的一句话是：「过去难的是技术；现在难的是人」。真实情况是：客户自己都说不清要什么 —— 采购说"要 AI"，市场说"要能写文案"，财务说"要能算账"，IT 说"别给我添麻烦"。

而技术方案的每一个选择都依赖这里的答案：

你问出来的答案	决定什么技术选择
「这台机器几个人用？」	要不要做多租户隔离（vNPU 切分）
「数据能不能出内网？」	要不要走全离线部署
「模型是你们的核心资产吗？」	要不要开模型混淆（PMCC）
「要它答哪一类问题？」	用 RAG 还是微调还是纯提示词
「多少人用、多快算快？」	几张卡、要不要做 PD 分离

1.2 澄清清单（我会问的问题，按顺序）

⭐ 顺序很重要：先问业务，再问约束，最后才问技术。

第一组 · 业务（决定做什么）

你要它解决哪个具体问题？（要一个场景，不要"提效"这种词）
现在这个问题是怎么解决的？（人工？外包？没解决？）
做成了谁最开心？做砸了谁最难受？（找一号位和阻力方）

第二组 · 约束（决定能不能做）

数据能不能出内网？（决定离线/在线）
有现成的卡吗？什么型号？几台？（决定后面全部）
操作系统是什么版本？（⚠️ 决定能不能用虚拟化实例 —— 这是不可返工的一项）
有没有运维人员能接手？（决定要不要交付文档+培训）

第三组 · 目标（决定怎么验收）

怎么算做成了？（要一个可验证的标准，不是"好用"）
给多长时间？（决定做 demo 还是一步到位）
上线后谁来管？（决定交付物形态）

1.3 这一段的可交付物

一份《需求与约束确认单》 —— 至少含：

项	内容
场景	一句话说清要解决什么
验收标准	可验证的（如"回答准确率 ≥ X%，用 N 条测试集"）
硬约束	内网/离线、卡型号与数量、操作系统版本
不做的事	明确写清这次不做什么（防止范围蔓延）

⭐ 为什么"不做的事"要写进去：现场最常见的事故是范围蔓延 —— 一开始说"做个问答"，做到一半变成"顺便把排班也做了"。 写清不做的事，是保护交付质量，也是保护你自己。

二、第 ② 段：现场摸底与服务器配置（先查，再配）

2.1 为什么先摸底

因为在现场，"以为"是最贵的东西。

三条铁律： 1. 不可返工的事必须在这一步查出来（操作系统版本 → 决定能不能做虚拟化）； 2. 摸完了再动手，动手了就不再问"是不是"； 3. 每一项都要留记录（客户签字的现场记录 = 后面扯皮的证据）。

2.2 摸底命令（五条，逐条带期望）

命令　npu-smi info

含义：查 NPU 设备信息 —— 现场摸底的第一条 拆解：npu-smi（昇腾设备管理工具）＋ info（子命令：查信息）用法：npu-smi info 期望：一张表，列出每张卡的型号、温度、显存、进程；Health 为 OK 不过会怎样：命令不存在 → 驱动没装（"驱动包 = 驱动 & npu-smi 工具包"）；有输出但列不出卡 → 权限或硬件问题

命令　npu-smi info -l

含义：列出所有 NPU 设备拆解：-l（list，列出）用法：npu-smi info -l 期望：列出 NPU ID 及各 NPU 信息 不过会怎样：无输出 → 驱动/权限问题 ⭐ 记下 NPU ID —— 后面所有命令的 -i 参数填的就是它

命令　npu-smi info -m

含义：查芯片映射信息（芯片 ID 与逻辑 ID 的对应）拆解：-m（查映射）用法：npu-smi info -m 期望：NPU ID / Chip ID / Chip Logic ID 对照表 不过会怎样：列表为空 → 驱动没正常挂载，后面所有 -c 参数都无从填起 ⭐ 记下 Chip ID —— 后面命令的 -c 参数填的就是它

命令　npu-smi info -t board -i 0

含义：查 0 号设备的板卡信息，顺带读出驱动版本和固件版本 拆解：-t board（查什么：板卡信息）＋ -i 0（查哪台：设备 0）用法：npu-smi info -t board -i 0 期望：输出里 Software Version = 驱动版本；Firmware Version = 固件版本 不过会怎样：报设备不存在 → 先 npu-smi info -l 看有哪些设备 ⭐ 把版本号抄进现场记录 —— 后面选安装包全靠它

命令　ls /dev/davinci*

含义：列出昇腾芯片设备节点拆解：ls（列出）＋通配符 * 用法：ls /dev/davinci0（只看某一个）期望：打印设备节点路径，如 /dev/davinci0 不过会怎样：报 No such file or directory → 驱动没装或没识别 ⭐ 设备节点尾数 = 芯片物理 ID（phy_id） —— 算 vNPU 取值范围时要用

2.3 ⚠️ 摸底时必查、但最容易漏的一项

操作系统版本是否支持虚拟化实例功能。

官方要求：查看对应产品的驱动固件安装指南中「算力分组场景下的安装 > 安装前必读」章节，了解支持虚拟化实例功能的操作系统版本。

为什么放这里：如果版本不支持，就得重装系统 —— 装完 CANN、配完环境再发现，全部要重来。

2.4 现场记录表模板

项	记录值	谁提供的
卡型号 / 数量 / 设备 ID / 芯片 ID		现场
驱动版本 / 固件版本		现场
操作系统版本与架构		现场
★ 系统是否支持虚拟化实例		官方文档核对
能否上外网		现场
磁盘可用空间		现场
现有软件版本（CANN/Python 等）		现场
客户对接人 / 决策人		客户

2.5 起：服务器配置（摸完底之后才动手）

⭐ 顺序不能反：先摸底（上一节）→ 再配置。因为配置方案取决于摸底结果 —— 卡是什么型号、系统版本对不对、客户网络怎么划，都是配之前才知道的。

官方对这一步的定位：驱动固件安装指南里有一章叫「算力分组场景下的安装 > 安装前必读」—— "安装前必读"就是这一段要做的事。

2.5 装操作系统

先选版本，再装机 —— 选错的代价是重装。

① 官方给的 OS 安装参考文档（按架构选）

物理机操作系统	架构	官方参考文档
Ubuntu 20.04	x86 / Arm	《Atlas 服务器 Ubuntu 20.04 操作系统安装指南》
Ubuntu 22.04	Arm	《Atlas 服务器 Ubuntu 22.04 操作系统安装指南（Arm）》
openEuler 22.03 LTS	x86 / Arm	《Atlas 服务器 openEuler 22.03 LTS 操作系统安装指南》
openEuler 22.03 LTS SP4	Arm	《Atlas 服务器 openEuler 22.03 LTS SP4 操作系统安装指南（Arm）》

装法（官方提到的一种）：通过 BMC 挂载光盘方式安装操作系统。

② ⚠️ 如果要用虚拟化实例（AVI），OS 要先过这一关

官方对 AVI 的定义（全称值得记）：

昇腾虚拟化实例（全称 Ascend Virtual Instance，简称 AVI）：指通过资源虚拟化技术将 1 个 NPU 切分成若干个 vNPU（虚拟 NPU）实例挂载到虚拟机或容器中使用，使得 1 个 NPU 同时支持多个计算调度任务。 AVI 通过算力资源切分的方式，实现了资源虚拟化复用并保证了资源的安全隔离，大大降低了用户使用 NPU 算力的门槛和成本，并且支持多租户按需进行资源申请或回收管理。

⭐ 它解决的就是"一台机器给几个部门用"这个问题 —— 而前提是系统版本支持。

官方在《安装前必读 · OS 兼容性列表》里给的是"物理机 OS × 虚拟机 OS"的配对表，例如：

硬件形态	物理机操作系统	虚拟机操作系统
Atlas 800 训练服务器（9000）	openEuler 20.03 LTS	Ubuntu 20.04 ／ openEuler 20.03 LTS ／ CentOS 8.2
Atlas 800 训练服务器（9010）	openEuler 20.03 LTS	Ubuntu 20.04 ／ openEuler 20.03 LTS ／ CentOS 8.2
Atlas 800 推理服务器（3000）+ Atlas 300V Pro	UOS V20（1050e）	UOS V20（1050e）

⚠️ 上表只是官方表里的几行示例。实际配置前必须去查你那台硬件形态对应的完整表 —— 这一步查错的后果是重装系统，属于"不可返工的事"。

③ 一条只有踩过才知道的内核要求（官方原文）

A200T A3 Box8 系列硬件产品的 NPU 直通虚拟机功能，需要在 OS 内核中增加 NPU 设备的复位机制，且需要配套 Ascend HDK 25.2.0 及以后版本的 NPU 固件。修改方式参见《修改 Linux 内核中 PCIe 设备的复位模块》章节。

这条的用法：如果你的场景是"NPU 直通到虚拟机"，那么装完 OS 还不能直接装驱动 —— 要先按这一节改内核。这属于"装之前先读安装前必读"的典型例子。

2.6 磁盘与分区规划（经验部分，官方未给成文清单）

⚠️ 官方没有给"磁盘该怎么分区"的成文规范。以下是我按交付实践归纳的原则， 请结合你的实际情况调整。

按"用途分开"的原则划：

放什么	特点	规划建议
操作系统 + CANN/驱动	装完基本不变	独立分区，按官方安装指南给的容量留
模型权重	单个体积大、几乎只读	单独目录/盘；换模型 = 换这个目录
数据集 / 知识库文档	体积大、可能频繁读写	单独盘（读带宽敏感 —— 见 2.7 存储面）
日志	持续增长，最容易撑爆根分区	单独分区并设轮转（官方给的日志路径见附录 B）
容器镜像	体积大、易积压	单独盘；规划好清理策略

为什么日志要单独分区：官方的日志目录有好几处（安装日志 ~/log/mxRag/deployment.log、应用日志 ${HOME}/ascend/log、MindIE 日志 ~/mindie/log）， 任何一个持续增长都会把根分区写满，而根分区满了会让服务以一种很难查的方式挂掉。

⭐ 一条现场必做的检查：

命令　df -h

含义：看各分区的容量与使用率（disk free，human-readable）拆解：df（磁盘剩余空间）＋ -h（用 GB/MB 这种人类可读单位显示）用法：df -h 期望：每个挂载点都有足够余量；根分区至少留出模型体积的 2 倍以上 不过会怎样：根分区快满 → 先清日志（而不是删模型），再考虑扩容 ⭐ 装机当天就要跑一遍并记进现场记录表

2.7 网络规划（⭐ 官方给了三个"网络平面"的定义）

官方（MindCluster《环境依赖》）对网络平面的划分：

网络平面	官方说明	实际要连谁
业务面	用于 K8s 集群业务管理（管理节点和计算节点之间连接）	你办公网进来的那一路
存储面	用于从存储节点读取训练用的数据集。因为对带宽有要求，所以建议使用单独的网络平面和网络端口，将训练节点和存储节点连通	存模型/数据的那一路
参数面	用于分布式训练时训练节点之间的参数交换	多机训练时机器之间那一路

⭐ 这一段对交付的直接意义：

不要把所有流量都挤在一个网口上 —— 官方明确说存储面"对带宽有要求，建议单独平面和端口"；
做多机（分布式训练 / PD 分离）时，"参数面"的质量直接决定能不能跑起来 —— KV Cache 要在节点之间搬，这条网不通，服务就是起不来（D4 讲的分离开销就在这里）；
客户网络团队通常不让你乱动网络 —— 所以这三条平面必须在方案阶段和客户网络组对齐，而不是到了现场再问"这个口能不能用"。

⚠️ 官方还提到组网要看《Ascend Training Solution 组网指南》 —— 具体组网拓扑以那份为准，本文只给"有三个平面"这个骨架。

装机时的网络检查：

命令　ip -br addr

含义：简洁地列出所有网卡及其 IP 地址（brief 模式）拆解：ip（网络配置工具）＋ -br（brief，只给一行摘要）＋ addr（地址）用法：ip -br addr 期望：每个网口一行，能看到 up/down 状态和 IP 不过会怎样：某块网卡没起来 → 查网线、查交换机口、查客户是否已放通 ⭐ 记下每块网卡对应哪个平面（业务/存储/参数），后面配服务时要用

2.8 基础软件依赖（含一条很实用的版本下限）

官方提到的一条具体约束（原文）：

低版本 Docker 出于安全管控会限制 clone 系统调用，但其拦截策略过于严苛， 会误拦截正常线程创建行为。Volcano 内部 CGO 程序依赖原生线程能力， 一旦线程创建被拦截将直接引发进程崩溃。因此，使用 openEuler 作为基础镜像构建 Volcano 组件镜像时，Docker 版本需不低于 20.10.10。

⭐ 这条为什么值得单独拎出来：它是"版本配对"问题的典型案例 —— 报错看起来是"组件崩溃"（线程创建被拦），根因却在 Docker 版本。 这也是"报错的位置 ≠ 问题的位置"的一个真实例子。

其余基础依赖（按你要用的组件装）： - Python 3.11（RAG SDK 官方要求） - Docker / 容器运行时（用容器路线时） - K8s 与 Volcano（用集群调度时） - pip 内网源或离线包（内网环境）

2.9 安全加固（官方只给底线，具体按客户策略）

CANN《加固须知》官方原话：

本文中列出的安全加固措施为基本的加固建议项。用户应根据自身业务，重新审视整个系统的网络安全加固措施。 用户应按照所在组织的安全策略进行相关配置，包括但不限于软件版本、口令复杂度要求、安全配置（协议、加密套件、密钥长度等）、权限配置、防火墙设置等。

读法（两层）： 1. 官方给的是"底线"，不是"全套" —— 它明确说自己只是"基本的加固建议项"； 2. 最终责任在使用方 —— "应根据自身业务重新审视"、"按照所在组织的安全策略"。

⭐ 所以这一段在交付里的正确做法是：拿客户的安全基线文档来对齐，而不是拿官方那份"基本建议"当验收标准。

2.10 服务器配置完成后的自检清单

配置完、装驱动前，先过一遍这十项：

#	检查项	怎么验
1	OS 版本在官方支持列表里	对照官方《OS 兼容性列表》/ 安装指南
2	若用虚拟化：确认系统支持 AVI	对照《安装前必读 · OS 兼容性列表》
3	若 NPU 直通虚拟机：内核复位机制已改	对照《修改 Linux 内核中 PCIe 设备的复位模块》
4	磁盘余量够（≥ 模型体积 2 倍）	`df -h`
5	日志目录已独立/已设轮转	看挂载点
6	三块网络平面已对齐客户网络组	`ip -br addr` + 客户确认
7	Python 版本符合要求	`python3 -V`
8	Docker 版本符合下限	`docker --version`
9	加固按客户基线做完	客户安全基线文档
10	现场记录表已填完	见上一节的模板

⭐ 第 10 项最容易被跳过 —— 但它是后面所有扯皮的依据。 装机当天花十分钟填完，能省掉后面几天的解释。

三、第 ③ 段：算力底座搭建（驱动 → 固件 → CANN）

这一段就是招聘原文那句「驱动安装、固件适配、CANN 工具链部署与调试」。

3.1 为什么顺序是"驱动 → 固件"（首次装）

首次安装的顺序：先驱动，后固件。 覆盖升级的顺序反过来：先固件，后驱动。（这条在 A1 讲过，是最容易搞反的一处。）

3.2 安装前先校验包（现场必做）

命令　./<安装包>.run --check

含义：只校验不安装，检查安装包完整性和一致性（SHA256 校验）拆解：./（执行当前目录下这个文件）＋ --check（校验模式）用法：./Ascend-hdk-<型号>-npu-driver_x.x.x_linux-<架构>.run --check 期望：校验通过（RAG SDK 那份文档给的期望输出是 Verifying archive integrity... 100% SHA256 checksums are OK. All good.） 不过会怎样：校验不过就重新获取安装包，不要硬装 —— 现场常用 U 盘/跳板机搬运，这一步必做

3.3 安装（含一个非 root 用户必加的选项）

命令　./<安装包>.run --full [--install-path=<路径>]

含义：完整安装（--full 是完整安装模式；--install-path 指定装到哪）拆解：--full（完整安装）／--install-path（可选，安装根目录，须 / 或 ~ 开头）用法：./<驱动包名>.run --full --install-path=/usr/local/Ascend 期望：出现安装进度，最后提示安装成功 不过会怎样：常见是磁盘不够、权限不足（要 root）、架构不匹配（x86 包装到 ARM 机器上）

命令　./<驱动包名>.run --full --install-for-all

含义：让非 root 用户也能使用驱动 拆解：--install-for-all（给所有用户开权限）用法：./Ascend-hdk-<型号>-npu-driver_x.x.x_linux-<arch>.run --full --install-for-all 期望：安装成功；之后普通用户也能跑 npu-smi 不过会怎样：不加这个选项，非 root 用户用不了驱动 —— 而生产环境又不该用 root 跑服务，两头一夹就卡住了（官方明确提到这个选项）

装完立刻验（不要攒着一起验）：

命令　npu-smi info

含义：确认驱动装上了（同 2.2，这里是"装完立刻验"那一次）期望：每张卡 Health 为 OK 不过会怎样：命令不存在 → 驱动没装上（"驱动包 = 驱动 & npu-smi 工具包"）

3.4 CANN 安装与环境变量

CANN 装的是两个包：Toolkit 包 + ops 包（ops 包按产品型号分发，装错型号会"找不到算子"）。

命令　source /usr/local/Ascend/ascend-toolkit/set_env.sh

含义：加载 CANN 环境变量（source 在当前终端执行，变量会留在当前窗口）拆解：source（在当前 shell 里执行，不新开进程）用法：source /usr/local/Ascend/ascend-toolkit/set_env.sh ⚠️ root 与非 root 路径不同：root 是 /usr/local/Ascend/cann/set_env.sh，非 root 是 ${HOME}/Ascend/cann/set_env.sh；本课用的是 ascend-toolkit 那个路径， 按实际安装为准 期望：无输出（成功即沉默）；随后 echo $ASCEND_HOME_PATH 应打印出 CANN 路径 不过会怎样：报 No such file or directory → 路径不对； echo $ASCEND_HOME_PATH 仍为空 → 变量名与预期不同，直接打开脚本看内容

命令　cat /etc/ascend_install.info

含义：读安装信息文件 —— 判断装的是驱动侧还是 CANN 侧拆解：cat（打印文件内容，原意 concatenate）用法：cat /etc/ascend_install.info（驱动/固件侧）　　　cat /etc/Ascend/ascend_cann_install.info（CANN 侧）期望：打印出版本与安装路径信息 不过会怎样：文件不存在 → 那一侧没装 ⭐ 记法：带 cann 的是 CANN 侧，不带的是驱动侧

3.5 底座的"一行验四层"（全流程里最有用的一条命令）

命令　python3 -c "import torch; import torch_npu; a = torch.randn(3,4).npu(); print(a + a)"

含义：一条命令验证四件事 —— ① Python 能跑 ② 框架装上了 ③ TorchNPU 插件生效 ④ 卡能真算拆解：import torch（框架）→ import torch_npu（昇腾插件）→ .npu()（把张量搬到卡上）→ print(a + a)（真算一次）用法：直接执行（前提是先 source 过 CANN 环境变量）期望：打印一个 3×4 的数字矩阵 不过会怎样（按失败的步骤定位层）： - import torch 失败 → 框架层（C 层） - import torch_npu 失败 → 插件没装或版本不配套 - .npu() 失败 → 卡/驱动/CANN 有问题（L0/L1） - print(a+a) 出错 → 算子或版本配套问题

⭐ 这是整套交付里最有现场价值的一条命令：报错的位置就是该查的层。

3.6 这一段出问题怎么查

现象	先归到哪	先查什么
装包里报缺少依赖	包	离线包不全 → 对照外网同版本机器的安装清单
装完没有 `npu-smi`	驱动	驱动包没装上（"驱动包 = 驱动 & npu-smi 工具包"）
非 root 用不了卡	权限	装驱动时漏了 `--install-for-all`
`import torch` 成功、`import torch_npu` 失败	插件	PyTorch 版本与 TorchNPU 不配套（TorchNPU 是插件，PyTorch 要用 `+cpu` 版）
`.npu()` 失败	L0/L1	先看 `npu-smi info` 有没有卡，再看 `echo $ASCEND_HOME_PATH`
报"找不到算子"	L1	ops 包装错型号了（ops 包按产品型号分发）

⭐ 检索技巧（现场必用）：报错要去掉具体化信息 —— 不要搜"我们公司内网装不上"，要搜报错原文里的稳定特征词（错误码、库名、函数名）。

四、第 ④ 段：框架与推理服务

4.1 先选路线（这一步不能猜）

你要做的事	装几个包	走哪条路
训练/微调（PyTorch 生态）	2 个	PyTorch + TorchNPU（插件路线）
训练/微调（MindSpore 生态）	1 个	MindSpore（原生路线，包名带 `-ascend`）
推理服务（社区生态）	2 个	vLLM + vLLM Ascend
推理服务（官方套件）	0 个	MindIE Motor

⭐ 「装几个包」是分辨所有路线的唯一那把尺子。

⚠️ 一条必须知道的官方路线变更：

MindIE LLM 组件将暂停后续功能演进，现有功能维持维护状态，不再支持新特性和新模型。 推荐使用 MindIE Motor + vLLM Ascend 部署推理服务。

网上大量教程基于维护线（MindIE LLM），会出现"照着做但官方文档找不到对应章节"。

4.2 起推理服务（vLLM Ascend 路线）

关键判据（必须看到）：启动日志里出现 vLLM Ascend environment: OK。

⭐ D2 的一条重要判据：「空补全不算推理成功」 —— 即：不要用"服务起来了、返回 200"当成功标准，要发一个真实请求，看返回的正文有没有内容。

验证服务的命令（通用做法）：

命令　ss -lntp

含义：看服务有没有真的在监听端口拆解：ss（socket statistics）＋ -l（只看 listening）＋ -n（端口用数字）＋ -t（只看 TCP）＋ -p（显示进程）用法：ss -lntp 期望：看到你的推理服务端口处于 LISTEN，且有对应进程 不过会怎样：ss 不存在 → 装 iproute2；端口不在 → 服务没起来（看日志）

命令　curl http://127.0.0.1:<端口>/<接口路径>

含义：真正发一次请求，看返回内容拆解：curl（发一次 HTTP 请求并看返回）用法：curl -s --max-time 10 http://127.0.0.1:<端口>/<接口路径> 期望：返回里有实际内容（不是空） 不过会怎样：超时 → 服务没就绪或端口不对； ⚠️ 返回 200 但内容是空的 → 不算成功（这就是"空补全"那条判据）

4.3 这一段出问题怎么查

现象	先归到哪	先查什么
服务起不来	L3	先 `source` 环境变量了没；模型路径对不对
端口不监听	L3	看启动日志的第一条报错（不是最后一条）
返回 200 但内容空	L3	模型路径/权重没加载成功 —— 空补全不算成功
日志里有 `Service is not available`	L3	官方说：多为 P/D 或 Coordinator 尚未完全就绪（等，不是坏）
容器里找不到设备	容器	驱动在宿主机；容器要 `--device`，权限必须是 `rwm` 不是 `rw`

五、第 ⑤ 段：模型迁移与适配（把客户的模型真正跑起来）

5.1 为什么这段最容易翻车

因为客户给的脚本，是在 GPU 上跑过的 —— 而"跑过"和"能跑通"是两回事。

官方 CAUTION（原文）：

⚠️ 迁移前要保证该脚本能在 GPU 或 CPU 上运行。

这句话的意思是：迁移是"换执行设备"，不是"修 bug"。 一份本来就跑不通的脚本，迁过来只会以一种你更不熟悉的方式跑不通 —— 而且你分不清是「迁移引入的」还是「脚本本来就有的」。

5.2 三种迁移方式（判据只有一个：转换发生在什么时候）

方式	转换时机	一句话记住	官方推荐
自动迁移	边训练边转换	脚本里导一行库，跑起来它自己换	⭐ 推荐
工具迁移	先转换脚本，再训练	跑个工具，产出改好的脚本 + 迁移报告	次选
手工迁移	人自己改	对比 GPU/NPU 接口逐个动手	最后手段

自动迁移怎么用：训练脚本里加一行 from torch_npu.contrib import transfer_to_npu （PyTorch 2.4.0 及之前版本，加在 import torch_npu 之后）。

⚠️ 三条约束，一条都不能漏：

约束	说明
① `channel_last` 暂不支持	建议用 `contiguous` 代替
② `nccl` 会被自动替换，但字符串判断不会	`if backend == 'nccl'`、`assert backend in ['gloo','nccl']` 要手动把字符串改成 `hccl`
③ `torch.jit.script` 会冲突	必须用它就只能走工具迁移 ← 这是选方式的硬判据

工具迁移的最大价值是「迁移报告」，含三样：

报告内容	能回答什么
脚本转换日志	改了哪些文件、有没有报错
不支持算子的列表	⭐ 哪些算子昇腾上没有（迁移后最容易出问题的地方）
脚本修改记录	一共动了多少处（可审计）

⭐ 一个很好用的官方细节：工具迁移的输出目录名 不带 _multi = 单卡、带 _multi = 多卡，跑完不用猜结果在哪。

5.3 这一段出问题怎么查

现象	先归到哪	先查什么
迁移后精度不对	算子	先用工具迁移拿到「不支持算子列表」，逐个替换
单卡能跑、多卡挂	通信	通信方式没换成 HCCL（手工迁移的两个必改点之一）
报 `torch.jit.script` 冲突	方式选错	走工具迁移
报 backend 相关错误	字符串	代码里的 `'nccl'` 字符串没手动改（自动迁移改不了它）
结果与参考平台不一致	精度	用 CANN 侧的精度调试工具做比对

六、第 ⑥ 段：业务落地（企业最常见的就是 RAG 私有知识库）

6.1 为什么交付阶段经常要做这个

模型跑起来 ≠ 业务能用。

模型的三个毛病（官方原文）：准确性不足、知识更新速度慢、答案透明度欠缺。 RAG 用"接入外部知识库"一次性绕过 ——

「RAG 技术能够以较低成本将基础大模型转换为领域专用大模型，成为提升大模型「最后一公里」落地应用效果的关键技术。」

官方对应物：RAG SDK（属 MindSDK 知识增强）。

6.2 ⭐ 先判断该不该用 RAG（不要急着装东西）

问客户一句话：

「你要的答案，有原文可查吗？」

有原文 → RAG 对路（把原文找出来给模型看）

没有（是种习惯/能力/风格） → 不是 RAG 的问题，别硬上

⭐ 并且：先上 RAG，不够再微调 —— 因为 RAG 便宜、可回退、可解释（官方说 RAG 是"较低成本"那条路）。

6.3 装 RAG SDK（官方十步，摘关键几条）

依赖：NPU 驱动固件 + CANN（Toolkit + ops 包）／ Index SDK 检索软件包 Ascend-mindxsdk-mxindex_<version>_linux-<arch>.run（配套 26.1.0）／ Python 3.11。

命令　chmod u+x <安装包>

含义：给安装包加"属主可执行"权限拆解：chmod（改权限）＋ u（属主 user）＋ +x（加执行）用法：chmod u+x Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run 期望：无输出（Linux 惯例：成功即沉默） 不过会怎样：不加就 ./ 执行会报 Permission denied

命令　./<安装包>.run --install [--install-path=<路径>]

含义：执行安装拆解：--install（安装模式）／--install-path（可选，路径须 / 或 ~ 开头，合法字符 a-zA-Z0-9_/-）／--quiet（静默）／--whitelist（白名单特性，取值 operator 或 whl）用法：./Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run --install --install-path=/home/work/RAG_SDK 　　　跳过许可交互：echo y | ./Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run --install 期望：出现 Do you accept the LICENSE...? [Y/N] → 输 Y → 最后出现 Install package successfully 不过会怎样：输入非 Y → 停止安装并退出；报路径非法 → 对照上面的字符和开头要求 ⚠️ 官方明确：不建议在 /tmp 路径下安装（重启会清、权限空间不稳定）

命令　pip3 install -r <安装路径>/mxRag/requirements.txt

含义：装 RAG SDK 的依赖包拆解：pip3（Python 包管理器）＋ install＋ -r（按文件里列的清单）用法：见上；遇到 distutils 报错时加 --ignore-installed 期望：逐条安装，最后 Successfully installed ... 不过会怎样：官方收录过这个报错 —— ERROR: Cannot uninstall 'xxx'. It is a distutils installed project... → 处置方式就是加 --ignore-installed 重跑

命令　pip3 list | grep mxRag

含义：验证依赖装上了拆解：pip3 list（列包）＋ |（管道）＋ grep（筛含关键词的行）用法：pip3 list | grep mxRag 期望：出现 mxRag 相关的包名和版本 不过会怎样：没有输出 → 依赖没装上

装完配置环境变量（官方示例含三个 source）： CANN（ascend-toolkit/set_env.sh）→ NNAL/ATB 加速库（nnal/atb/set_env.sh） → RAG SDK 自己（<安装路径>/mxRag/script/set_env.sh）。 配完必须 source ~/.bashrc。

命令　source ~/.bashrc

含义：让刚加进 .bashrc 的环境变量在当前终端立刻生效拆解：source（在当前 shell 里执行，不新开进程）用法：source ~/.bashrc 期望：无输出 不过会怎样：不执行 → 刚加的 export 在当前终端不生效（新开终端才会读） ⭐ 这是"我明明配了环境变量为什么还说找不到"的头号原因

6.4 验证（两条命令）

命令　python3 -c "import mxRag; print('RAG SDK import: OK')"

含义：验证 RAG SDK 能被导入 —— 跑任何代码前第一道门拆解：python3 -c（不写文件，直接执行后面这串代码）用法：直接执行期望：打印 RAG SDK import: OK 不过会怎样：报 ModuleNotFoundError → 没装或环境变量没生效 ⚠️ 注意：这条只证明"能 import"，不证明能在卡上跑

命令　ls <embedding模型路径>

含义：确认 embedding 模型文件真的在这台机器上拆解：ls（列出目录内容）用法：ls /path/to/model（路径对应环境变量 MX_INDEX_MODELPATH）期望：列出模型文件；目录不为空 不过会怎样：报 No such file or directory → 模型没搬进来（私有化环境高发）；目录是空的 → 只建了目录没放模型

6.5 ⭐ 怎么知道"RAG 真的起作用了"（这是验收的核心）

问法	期望	说明
用文档里的原句问	返回的 context 里含那段原文	验证链路通了
换一种说法问同一件事	也返回那段	验证不是靠关键词硬匹配
问一个只有这份文档能答的问题	答对	⭐ 这才证明 RAG 起作用
问一个文档里完全没有的事	应该答"不知道"	验证没有编（幻觉控制）
让客户的人来问	也答得对	⭐ 验收的灵魂条

⭐ 最后两行是最容易被忽略的两条： "问文档外的事，看它会不会编" —— 是检验幻觉控制； "让客户的人来问" —— 因为只有你自己能问出来的效果不算效果。

6.6 这一段出问题怎么查

现象	先归到哪	先查什么
传了文档，chunk 数是 0	解析/切分	解析器或切分器没注册齐全（实际支持格式是两者的交集）
chunk 有，向量库是空的	向量化	embedding 模型加载了没（它要单独配路径）
检索总是返回不相关的	检索	三个调点：查询改写 → 近似检索 → reranker 精排
检索对的但排在后面	精排	reranker 没开
检索对、答案还是编的	组装	prompt 组装 —— context 有没有真的塞进去
`upload_files` 不报错但没进去	上传	⭐ 它的返回值是"失败列表"，空列表才算全成功
换了 embedding 模型后检索变差	参数	`x_dim` 忘了跟着改
反复跑同一个问题结果不稳定	缓存	缓存没配（配上能稳定 + 省算力）

七、第 ⑦ 段：验收与交付（出证据，不是"我觉得"）

7.1 验收的七条判据

#	判据	拿什么当证据
①	硬件认得	`npu-smi info` 输出，`Health` 为 `OK`
②	底座就位	`cat /etc/ascend_install.info` 与 `ascend_cann_install.info` 输出
③	框架认得卡	那条"一行验四层"命令的输出
④	服务起得来	端口 LISTEN + 一次真实请求有内容返回（不是空）
⑤	业务跑得通	客户的人用真实问题问，答对
⑥	数据不出内网	断网跑完整流程的记录 + `ss -ntp` 输出（无公网连接）
⑦	能说清每一路数据的去向	一张表，逐条列出

第 ⑥⑦ 条是私有化项目的验收口径：不是"防火墙配了"，而是"真去连一下、连不上，把这个结果记下来"。 这就是"反面证据"—— 证明它确实拦住了，比证明它没报错更有力。

7.2 交付物清单（FDE 的交付不是"装完就走"）

#	交付物	为什么必须有
1	现场记录表（摸底结果）	后面扯皮的依据
2	架构图（这台机器上装了什么、端口怎么规划）	客户运维接手的前提
3	环境清单（版本、路径、包名）	出问题时的第一份资料
4	启动/停止/巡检脚本	让客户能自己重启（否则半夜找你）
5	验收报告（七条判据 + 证据）	项目结项依据
6	常见问题手册（现象 → 先查什么）	降低后续支持成本
7	培训记录（谁听过、讲了什么）	交付完成的证明
8	明确的服务边界（哪些不归你管）	防止范围蔓延

7.3 离场前的三件事

当着客户的面跑一遍验收（不要只给文档）；
让客户的人自己重启一次服务（能独立操作才算交付）；
留一个"出问题先看这里"的单页（现象 → 先查什么 → 找谁）。

八、第 ⑧ 段：上线后（这一段区分 FDE 和外包）

8.1 上线后要盯什么

时段	盯什么	怎么盯
首 24 小时	服务是否稳定、有没有静默故障	⚠️ 静默故障 = 进程卡死但服务看似无问题 —— 光看端口在不在不够，要真发请求
首一周	真实使用中的问题	让客户记录"答得不对"的案例
首一月	效果与容量	多少人用、多快算慢、要不要调

8.2 ⭐ 复盘：这次的东西能不能沉淀复用

这是从业者访谈里给 FDE 与外包划的那条线：

能沉淀成通用能力 = FDE；每次都要从头做 = 外包。

复盘要回答三个问题： 1. 这次哪些是"这个客户特有的"？（下次不能照搬） 2. 哪些是"所有客户都会遇到的"？（应沉淀成标准动作） 3. 哪些卡了很久但其实有标准答案？（应沉淀成手册）

8.3 ⭐ 三个元能力（不在技能清单里，但是这一行的底色）

能力	含义
判断这次能不能沉淀复用	上面那条 —— FDE 与外包的分界
判断自己的能力与需求是否匹配	有些需求不该接，接了也做不好；早说比晚说好
接受"技术不难、难在人"	访谈全篇的结论：过去难的是技术，现在难的是人

九、技能对照：这套流程和课件体系的对应关系

FDE 技能要求 → 本体系哪一课（做交付时按这个查漏）：

FDE 技能（招聘要求里的）	对应课件
驱动安装、固件适配	A1 驱动与固件
产品与卡型号识别	A2 产品线与形态
HDK / 工具集	A3 HDK 到底指什么
CANN 工具链部署与调试	B1–B5（是什么/算子包/版本/七种装法/容器）
框架（PyTorch/TorchNPU）	C1–C3
推理服务部署	D1–D5（服务层/vLLM Ascend/MindIE Motor/PD 分离/可用性与调优）
报错定位	E1 报错定位法
模型迁移与适配	F1 模型迁移
私有化部署 + 国产算力适配	G1 企业私有化部署
模型能力边界认知	G2 RAG 基础
数据接入 / 知识库	G3 知识库搭建（＋后续 G4–G9）
LLM 推理逻辑	D 层 + G 层
全栈与云原生（Docker/K8s）	B5 装进容器 + G 层
微调	H 层（计划中）

⭐ 一句话：这套课件覆盖的是 FDE 技能栈里的「技术侧 30%」；业务侧那 70%（需求澄清、利益相关方、现场应变）不在课件里，在本文的第一段里。

附录 A 官方出处

#	内容	官方出处
1	驱动包命名 `Ascend-hdk-<型号>-npu-driver_x.x.x_linux-{arch}.run`；固件包同理；「驱动包 = 驱动 & npu-smi 工具包」；首次装驱动→固件、覆盖升级固件→驱动	A1《驱动与固件》
2	`--check` 校验、`--full` 完整安装、`--install-path` 指定路径、`--install-for-all`（非 root 用户可用驱动）	CANN《安装指南》/ RAG SDK《安装部署》
3	`npu-smi info` / `-l` / `-m` / `-t board -i` 用法与字段；`Health` 为 `OK`	HDK / A3
4	`set_env.sh` 路径（root 与非 root 不同）；`/etc/ascend_install.info`（驱动侧）与 `/etc/Ascend/ascend_cann_install.info`（CANN 侧）	B1 / D2
5	ops 包按产品型号分发	B2
6	TorchNPU 是插件（装两个包、PyTorch 用 `+cpu` 版）	C1
7	MindIE 路线变更：MindIE LLM 暂停功能演进，推荐 MindIE Motor + vLLM Ascend	D1《MindIE 是什么》
8	vLLM Ascend 判据 `vLLM Ascend environment: OK`；「空补全不算推理成功」；A3 双 DIE 需两个设备节点	D2
9	MindIE Motor 端口段规律（Coordinator 1xxx / Controller 2xxx / Prefill 3xxx / Decode 4xxx）	D3
10	Prefill 计算密集 / Decode 访存密集；必须传 KV Cache	D4
11	官方默认开六项能力；静默故障 = 进程卡死但服务看似无问题；`{"detail":"Service is not available"}` 多为 P/D 或 Coordinator 尚未完全就绪	D5
12	模型迁移：官方 CAUTION（迁移前须能在 GPU 或 CPU 上运行）；三种迁移方式与推荐；自动迁移三条约束；工具迁移报告三样；输出目录 `_multi` 命名规律	F1 / ModelZoo《迁移方式比较》等
13	私有化：PMCC 模型混淆（TrustZone / 混淆因子 / 动态掩码）、`aclnnObfuscationSetup`/`aclnnObfuscationCalculate`/`aclnnCrypto`、950PR/950DT 不支持 `aclnnObfuscationCalculate`	G1 / CANN《Ras 类算子列表》
14	AVI 虚拟化实例：硬件/软件虚拟化、最大切分 7 个实例、`npu-smi set -t create-vnpu` 等命令与 vnpu_id 取值范围	G1 / 《昇腾虚拟化实例（AVI）用户指南》
15	RAG SDK：三个毛病、两条主线八步、双库一一对应、检索三个调点、安装十步、环境变量、`upload_files` 返回失败列表、`x_dim` 约束	G2 / G3 / MindSDK 26.1.0
16	「运行阶段请使用 root 用户执行相关用例」（⚠️ 跑用例要求，不等于生产该用 root）	G3 / RAG SDK《开发流程》
17	RAG SDK 接口必须在 try/except 内调用；Cache 数据库未做加密存储，个人数据请勿存放	RAG SDK《接口参考 · 使用说明》
18	OS 安装参考文档表（Ubuntu 20.04 x86/Arm、Ubuntu 22.04 Arm、openEuler 22.03 LTS x86/Arm、openEuler 22.03 LTS SP4 Arm）；通过 BMC 挂载光盘方式安装操作系统	《Atlas 服务器 …操作系统安装指南》系列 / Atlas 200I A2《虚拟机配置指南 · 物理机安装 OS》
19	A200T A3 Box8 系列的 NPU 直通虚拟机需在 OS 内核中增加 NPU 设备复位机制，且需配套 Ascend HDK 25.2.0 及以后版本的 NPU 固件 → 参见《修改 Linux 内核中 PCIe 设备的复位模块》	Atlas 200I A2《虚拟机配置指南》
20	AVI 官方全称与定义：昇腾虚拟化实例（Ascend Virtual Instance，简称 AVI）——将 1 个 NPU 切分成若干个 vNPU 实例挂载到虚拟机或容器使用；实现资源虚拟化复用并保证资源的安全隔离，支持多租户按需申请或回收；物理机+虚拟机场景通过 npu-smi 工具或 DCMI API 划分 vNPU；单个 vNPU 只能分配给单个虚拟机，但单个虚拟机可以挂载多个 vNPU	《虚拟机配置指南 · 安装前必读 · 物理机+虚拟机 AVI 场景 OS 兼容性》
21	虚拟机 OS 兼容性表（物理机+虚拟机 AVI 场景）：含 Atlas 800 训练服务器 9000/9010（物理机 openEuler 20.03 LTS）、Atlas 800 推理服务器 3000 + Atlas 300V Pro（UOS V20）等	同上
22	三个网络平面的官方划分：业务面（K8s 集群业务管理）／存储面（读取训练数据集，对带宽有要求，建议使用单独的网络平面和网络端口）／参数面（分布式训练时训练节点之间的参数交换）	MindCluster 26.1.0《安装指南 · 环境依赖》（组网要求）
23	Docker 版本下限：使用 openEuler 作为基础镜像构建 Volcano 组件镜像时，Docker 版本需不低于 20.10.10（低版本 Docker 会误拦截线程创建 → Volcano 内部 CGO 崩溃）	同上
24	组网拓扑以《Ascend Training Solution 组网指南》为准	同上
25	FDE 岗位职责与技能要求（职责描述与能力共性）	公开招聘信息与从业者访谈的归纳（2026 年）

⚠️ 属于「归纳/方法」而非官方原文的部分，已在文中标明： - 第 ① 段的澄清清单与《需求与约束确认单》模板； - 第 ⑧ 段的复盘三问与三个元能力； - 第七段交付物清单（这是实践归纳，官方没有对应的成文清单）； - 第九段的技能→课程对照表（我的归纳）。

附录 B 命令详解（汇总本文出现的命令）

B.1 摸底（第 ② 段）

命令：npu-smi info
含义：查 NPU 设备信息
拆解：npu-smi（昇腾设备管理工具）＋ info（子命令：查信息）
用法：npu-smi info
期望：一张表，列出每张卡的型号、温度、显存、进程；Health 为 OK
不过会怎样：命令不存在 → 驱动没装；有输出但列不出卡 → 权限或硬件问题

命令：npu-smi info -l     命令：npu-smi info -m
含义：-l 列出所有 NPU 设备；-m 查芯片映射信息
拆解：-l（list，列出）／-m（查映射）
用法：见上
期望：-l 给出 NPU ID 及各 NPU 信息；-m 给出 NPU ID / Chip ID / Chip Logic ID 对照表
不过会怎样：列表为空 → 驱动没正常挂载，后面所有 -i/-c 参数都无从填起
⚠️ 记住：info -l 查出的 NPU ID = 命令里的 -i；info -m 查出的 Chip ID = 命令里的 -c

命令：npu-smi info -t board -i 0
含义：查 0 号设备的板卡信息，顺带读出驱动版本和固件版本
拆解：-t board（查什么：板卡信息）＋ -i 0（查哪台：设备 0）
用法：见上
期望：输出里 Software Version = 驱动版本；Firmware Version = 固件版本
不过会怎样：报设备不存在 → 先 npu-smi info -l 看有哪些设备

命令：ls /dev/davinci*
含义：列出昇腾芯片设备节点
拆解：ls（列出）＋ 通配符 *
用法：ls /dev/davinci0
期望：打印设备节点路径
不过会怎样：报 No such file or directory → 驱动没装或没识别
⭐ 设备节点尾数 = 芯片物理 ID（phy_id）

命令：cat <文件>
含义：打印文件内容
拆解：cat（原意 concatenate 拼接，现在主要用来"看文件"）
用法：cat /etc/ascend_install.info          # 驱动/固件侧
      cat /etc/Ascend/ascend_cann_install.info  # CANN 侧
期望：打印版本与安装路径信息
不过会怎样：文件不存在 → 那一侧没装

B.2 安装与校验（第 ③⑥ 段）

命令：chmod u+x <安装包>
含义：给安装包加"属主可执行"权限
拆解：chmod（change mode，改权限）＋ u（属主 user）＋ +x（加执行）
用法：chmod u+x Ascend-hdk-<型号>-npu-driver_x.x.x_linux-{arch}.run
期望：无输出（Linux 惯例：成功即沉默）
不过会怎样：不加就 ./ 执行会报 Permission denied

命令：./<安装包>.run --check
含义：只校验不安装，检查安装包完整性和一致性
拆解：./（执行当前目录下这个文件）＋ --check（校验模式）
用法：见上
期望：Verifying archive integrity...  100%   SHA256 checksums are OK. All good.
不过会怎样：校验不过 → 包在下载或搬运中损坏，重新获取，不要硬装

命令：./<安装包>.run --full [--install-for-all] [--install-path=<路径>]
含义：完整安装；--install-for-all 让非 root 用户也能用驱动
拆解：--full（完整安装）／--install-for-all（给所有用户开权限）／--install-path（须 / 或 ~ 开头）
用法：./<驱动包名>.run --full --install-for-all --install-path=/usr/local/Ascend
期望：安装进度 → 安装成功提示
不过会怎样：磁盘不够/权限不足/架构不匹配；漏了 --install-for-all 则非 root 用不了卡

命令：./<安装包>.run --install [--install-path=<路径>] [--quiet] [--whitelist=operator,whl]
含义：安装（RAG SDK 用的形式）
拆解：--install（安装）／--quiet（静默）／--whitelist（白名单特性）
用法：./Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run --install --install-path=/home/work/RAG_SDK
      echo y | ./Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run --install
期望：Do you accept the LICENSE...? [Y/N] → 输 Y → Install package successfully
不过会怎样：输入非 Y → 停止安装并退出；/tmp 路径官方不建议装

命令：pip3 install -r <requirements文件> [--ignore-installed]
含义：按清单一次装齐 Python 依赖
拆解：pip3（包管理器）＋ install ＋ -r（按文件清单）
用法：pip3 install -r <安装路径>/mxRag/requirements.txt
期望：逐条安装，最后 Successfully installed ...
不过会怎样：ERROR: Cannot uninstall 'xxx'. It is a distutils installed project...
            → 加 --ignore-installed 重跑（官方给的处置方式）

命令：pip3 install [--force-reinstall] [--no-deps] <wheel>
含义：安装单个 wheel 包
拆解：--force-reinstall（已装过也强装）／--no-deps（只装它，不动依赖）
用法：pip3 install --force-reinstall --no-deps /path/to/ragsdk-1.0.0-py3-none-any.whl
期望：Successfully installed ...
不过会怎样：不加 --no-deps 时 pip 会按 wheel 声明重装依赖，可能改掉你已调好的版本

命令：pip3 list | grep mxRag
含义：验证依赖装上了
拆解：pip3 list（列包）＋ |（管道）＋ grep（筛含关键词的行）
用法：见上
期望：出现 mxRag 相关的包名和版本
不过会怎样：没有输出 → 依赖没装上

B.3 环境变量

命令：source <脚本>
含义：在当前终端执行脚本 —— 脚本里设的环境变量会留在当前窗口
拆解：source（在当前 shell 里执行，不新开进程）
用法：source /usr/local/Ascend/ascend-toolkit/set_env.sh
      source ~/.bashrc
期望：无输出（成功即沉默）
不过会怎样：不执行 → 环境变量在"当前终端"不生效（新开终端才读 .bashrc）
⭐ 这是"我明明配了环境变量为什么还说找不到"的头号原因

命令：echo $<变量名>
含义：打印某个环境变量的值
拆解：echo（把值打印到屏幕）＋ $（取这个变量的值）
用法：echo $ASCEND_HOME_PATH
期望：打印出 CANN 的安装路径
不过会怎样：打印空行 → 变量没生效（source 了没？变量名对不对？）

B.4 验证（第 ③④⑥ 段）

命令：python3 -c "import torch; import torch_npu; a = torch.randn(3,4).npu(); print(a + a)"
含义：一行验证四层 —— Python、框架、TorchNPU 插件、卡能真算
拆解：import torch（框架）→ import torch_npu（插件）→ .npu()（搬张量到卡）→ print(a+a)（真算一次）
用法：直接执行（前提：已 source CANN 环境变量）
期望：打印一个 3×4 的数字矩阵
不过会怎样（按失败步骤定位层）：
  · import torch 失败 → 框架层
  · import torch_npu 失败 → 插件没装/版本不配套
  · .npu() 失败 → 卡/驱动/CANN
  · print(a+a) 出错 → 算子或版本配套
⭐ 报错的位置就是该查的层（整套交付里最有现场价值的一条命令）

命令：python3 -c "import mxRag; print('RAG SDK import: OK')"
含义：验证 RAG SDK 能被导入
拆解：python3 -c（不写文件直接执行代码）＋ import mxRag
用法：见上
期望：打印 RAG SDK import: OK
不过会怎样：ModuleNotFoundError → 没装或环境变量没生效
⚠️ 只证明"能 import"，不证明能在卡上跑

命令：ss -lntp     命令：ss -ntp
含义：ss = socket statistics，看套接字状态（不是昇腾命令，是 Linux 系统工具）
拆解：-l 只看 listening／-n 端口用数字／-t 只看 TCP／-p 显示进程
      -l 不加（即 ss -ntp）= 只看已建立的连接
用法：ss -lntp   # 我这机器开了哪些门（监听）
      ss -ntp    # 我正和谁通着话（已建立）
期望：-lntp 列出监听端口+进程；-ntp 列出 ESTABLISHED 连接+进程
      ⭐ 私有化环境的关键判据：-ntp 输出里不该出现公网地址
不过会怎样：命令不存在 → 系统太精简，装 iproute2

命令：curl -s --max-time 10 <地址>
含义：发一次 HTTP 请求看返回
拆解：-s（静默，不显示进度）／--max-time（最多等几秒，超时放弃）
用法：curl -s --max-time 10 http://127.0.0.1:<端口>/<路径>
      curl -s --max-time 5 https://www.hiascend.com    # 测公网（私有化环境应超时）
期望：内网服务有返回内容；公网请求超时/被拒
不过会怎样：⚠️ 返回 200 但内容是空的 → 不算成功（"空补全"那条判据）

命令：find <目录> -maxdepth N -type d
含义：在目录下找文件/目录，限制往下几层
拆解：-maxdepth N（最多往下 N 层）／-type d（只要目录）
用法：find /usr/local/Ascend -maxdepth 2 -type d
期望：打印目录结构
不过会怎样：什么都没有 → 路径不对，用 echo $ASCEND_HOME_PATH 确认
⭐ 离线搬迁备料时用它记录"装完之后多出来了什么"

附录 C 交付全流程一页速查

① 接单与澄清 ── 问十三个问题 → 出《需求与约束确认单》（含"不做的事"）
② 摸底+配服务器 ─ npu-smi info/-l/-m/-t board · ls /dev/davinci* · df -h · ip -br addr
                 ├ 摸底：卡型号 / 驱动固件版本 / 系统版本 / 能否上网
                 ├ 装 OS：按官方《OS 安装指南》选版本
                 ├ ⚠️ 必查：系统是否支持 AVI（虚拟化实例）—— 查错要重装系统
                 ├ ⚠️ NPU 直通虚拟机：先改内核 PCIe 复位模块（需 HDK 25.2.0+）
                 ├ 网络：业务面 / 存储面 / 参数面 三平面与客户网络组对齐
                 └ 加固：按客户安全基线，而非官方那份基本建议
③ 算力底座 ──── --check 校验 → --full [--install-for-all] → CANN(Toolkit+ops)
                 → source set_env.sh → 一行验四层
④ 框架与服务 ── 按"装几个包"选路线 → vLLM Ascend / MindIE Motor
                 → 判据：vLLM Ascend environment: OK；空补全不算成功
⑤ 模型迁移 ──── 先确认脚本能在 GPU/CPU 跑通 → 自动迁移 → 工具迁移 → 手工
                 ⚠️ 三条约束：channel_last / 字符串 nccl / torch.jit.script
⑥ 业务落地 ──── 先问"有原文可查吗" → RAG SDK 十步装 → 建库灌数据
                 ⚠️ upload_files 返回失败列表；x_dim 必须跟着模型变
⑦ 验收交付 ──── 七条判据出证据（含"反面证据"）→ 八件交付物 → 离场前三件事
⑧ 上线后 ────── 首 24h 盯静默故障 → 复盘三问 → 沉淀复用（FDE 与外包的分界）

贯穿全程的两条：
  · 报错的位置 ≠ 问题的位置
  · 官方没给答案的地方，明说"这里要自己查"，不编

B.5 服务器配置相关（第 ② 段）

命令：df -h
含义：看各分区的容量与使用率
拆解：df（disk free，磁盘剩余空间）＋ -h（human-readable，用 GB/MB 显示）
用法：df -h
期望：每个挂载点都有足够余量；根分区至少留出模型体积的 2 倍以上
不过会怎样：根分区快满 → 先清日志（而不是删模型），再考虑扩容
⭐ 装机当天就要跑一遍并记进现场记录表

命令：ip -br addr
含义：简洁列出所有网卡及其 IP（brief 模式）
拆解：ip（网络配置工具）＋ -br（brief，一行摘要）＋ addr（地址）
用法：ip -br addr
期望：每个网口一行，能看到 up/down 状态和 IP
不过会怎样：某块网卡没起来 → 查网线、交换机口、客户是否放通
⭐ 记下每块网卡对应哪个平面（业务/存储/参数）

命令：python3 -V
含义：查 Python 版本（RAG SDK 官方要求 3.11）
拆解：-V（version，大写；小写 -v 是啰嗦模式）
用法：python3 -V
期望：Python 3.11.x
不过会怎样：版本不对 → 先解决 Python，再动后面所有步骤

命令：docker --version
含义：查 Docker 版本
拆解：--version（打印机版本）
用法：docker --version
期望：用 openEuler 做 Volcano 镜像时，版本需 ≥ 20.10.10
不过会怎样：低于下限 → 会出现"看着像组件崩溃、其实根因在 Docker"的怪问题