F6 开源模型部署上架：从拿权重到 API 上线

编制：观澜｜日期：2026-10-09｜级别：T2 标准级 层级：F 层 · 场景实战（F 层第 6 课；前接 A–E 全部零件课与 F1 模型迁移）素材来源：昇腾官方文档——MindIE 3.1.0《MindIE 视图生成推理快速入门》、vLLM Ascend 官方文档《安装指南》《模型教程（Qwen3-Dense）》《使用 MindIE-Motor 部署 vLLM-Ascend》、《MindIE Motor · 接口说明》《MindSpeed 快速入门》、《Hello，ModelZoo》本课定位：F1 讲的是「代码/训练脚本怎么从 GPU 搬到昇腾」。　　　　　本课讲的是另一件事：模型与权重怎么落到服务器上，并对外提供能力——从一个模型名字开始，到外部能用接口调到它为止。　　　　　本课同时覆盖两条线：大语言模型（LLM）与开源视频生成模型——两者流程一样，判据与资源差得很远。

第一段章前定位

到这里，机器已经能用、脚本也能迁了。剩下的问题是最后一个，也是最像「交付」的那个：

我手里只有一个模型名字（比如 Qwen3-32B、Wan2.1），怎么让它变成别人能调用的服务？

这件事在真实交付里出现的频率极高，且跨了 L0～L4 全部四层：

L0/L1  卡与驱动、CANN 就位吗          ← 本课只做「一句话确认」，装法回 A/B 层
L2     框架认得卡吗                    ← 回 C1
L3     服务层：vLLM / MindIE           ← 机制在 D2、D3，本课只取「最短可照抄命令」
L4     模型/权重/量化/服务对外         ← ★ 本课主体

先划清分工，避免重复（重复课比缺课更浪费你的时间）：

本课不讲（去别处看）	去哪
vLLM Ascend 是什么、镜像里有什么、机制与单卡起服务	D2《vLLM Ascend》
MindIE Motor 的五组件、控制面/数据面、端口千位段规律	D3《MindIE Motor》
训练脚本从 GPU 迁到昇腾（`transfer_to_npu`、迁移报告）	F1《模型迁移》
信创环境（架构/OS/内核配对）	F5《国产算力适配》
容器与 `--device` 基础、驱动在宿主机	B5《装进容器》
推理服务挂了怎么保持不挂、健康与调优	D5《可用性、健康与调优》

本课只讲一件事：把这四层里跟「模型与权重」有关的那一段，从选型一路做到上线 checklist。

第二段学习目标

学完这一课，你应该能：

✅ 说出「部署完成态」的判据，并据此反推该下几卡、下哪一档量化——而不是先把权重下完再想办法
✅ 从官方渠道把权重（模型库/权重库/开源社区）和镜像（昇腾镜像仓库/quay.io）拿到本机，并下完先校验
✅ 在容器/租用环境里把权重与虚拟环境落到数据盘，并把文件权限配对（否则服务读不到权重）
✅ 照抄最短的起服务命令——LLM（vLLM Ascend v0.23.0）与视频模型（MindIE SD）各一条，并说清每个参数
✅ 用两条不同的判据验收：LLM 是「空补全不算推理成功」，视频模型是「产出可播放文件」
✅ 说出显存不足 / 权重格式不对 / 网络隔离 / 权限 / 驱动或 CANN 未就位这五类问题各回哪一层

第三段全景原理：先定「完成态」，再反推

3.1 两条线，「完成态」不一样

这是本课的第一条纪律：不要先问「装什么」，要先问「什么样算装好了」。

线	完成态（可验证）	验证方式
LLM	① 端口在听 ② 接口返回非空内容 ③ `/v1/models` 能列出模型名	`ss` / `curl`
视频生成模型	① 推理跑完不报错 ② 产出可播放的文件 ③ 时长/分辨率/帧率符合预期 ④ 重复跑结果稳定	看输出文件 + 播放器 / `ffprobe`

为什么先做这一步：这两条线的完成态根本不同——LLM 的产物是「一段文字」，视频模型的产物是「一个文件」。如果你拿 LLM 的判据（「接口有返回就算成」）去验收视频，会得出完全错误的结论。 后面每一段都会提醒你两条线的差别。

3.2 九步流程主线（本课的骨架）

① 选型与完成态     ← 先定「做到什么样算完」，据此算资源
② 拿权重           ← 官方渠道 + 下完先校验
③ 落盘             ← 数据盘 + 权限（容器根盘小，权限不对服务读不到）
④ 起服务           ← vLLM Ascend / MindIE SD 的最短命令
⑤ 验证             ← ★ 本课最关键：LLM「非空补全」/ 视频「可播放文件」
⑥ 对外提供 API     ← OpenAI 兼容端点 + 鉴权 + 并发
⑦ 多模型与版本切换/回滚
⑧ 上线前 checklist  ← N 条全过 = 完工
⑨ 排障             ← 五类问题回哪一层

顺序不能反。最常见的错法是「先把权重下下来（几十 GB、几小时），才发现卡数不够、量化档选错」。 先定完成态、算好资源，再动手下权重——这是本课替你省时间的关键一步。

3.3 两条线的差异总表（贴墙上）

维度	LLM	开源视频生成模型
权重体量	数 GB ～数十 GB	数十 GB 起，明显更大
显存/卡数需求	小模型单卡可起步	高得多；官方快速开始示例用8 卡
单次推理时长	毫秒～秒级，流式返回	分/秒级，一次性生成
并发	高（`--max-num-seqs` 可调）	低（一次生成占满全部卡）
输出形态	token 流	文件（视频），需落盘与下载
对外接口	OpenAI 兼容（`/v1/chat/completions` 等）	官方快速开始给的是脚本推理；服务化接口见 4.7 说明
验收判据	非空补全	可播放文件 + 时长/分辨率/帧率

⭐ 记法：LLM 交付一个「接口」，视频模型交付一个「文件加接口」。 前者验收看返回值，后者验收看产物。

第四段【如果我来做】——每件负责什么 + 我从哪里下手

这段是本课的核心。前三段讲「流程长什么样」，这一段讲：如果现在把这件事交给我，我从哪一步开始、每步凭什么判断。

4.0 先亮结论：我会按这个顺序做

摸底（不装任何东西先查事实）：卡、驱动、CANN、盘、网络——把不可返工的事在这里查出来
定档：先定「完成态」，再按官方分模型推荐卡数表选模型与量化档，不默认上最大的
拿权重：走官方渠道，下完立刻校验（用 sha256sum）
落盘：权重与虚拟环境放数据盘，按官方要求配对权限
起服务：LLM 用 vllm serve，视频用 torchrun generate.py——每步立刻验，不攒着
验证：LLM 看非空补全；视频看可播放文件——这两条是本课的验收线
收口：对外暴露 OpenAI 端点、配密钥与并发；留下证据
诚实：官方没给的地方（显存通用公式、视频落盘路径、视频 REST 接口）明说「这里要自己查」

4.1 每件负责什么 + 「不装/没做会怎样」

这张表是本课的「零件职责表」——出问题时对着它回层。

件	属于哪层	负责什么	没做到会怎样
卡 + 驱动 + 固件	L0	系统认得设备	容器里看不到设备，`torch.npu` 不可用
CANN（Toolkit + ops）	L1	提供运行时与算子	`ASCEND_HOME_PATH` 为空，框架导入失败
框架（PyTorch + TorchNPU）	L2	框架认得卡	`import torch_npu` 报错
服务层（vLLM / MindIE SD）	L3	起服务、跑推理	端口无监听、curl 连不上
模型权重	L4	服务的「内容」	起得来但空补全 / 无文件产出
量化档（W8A8 等）	L4	降显存、提吞吐	显存不足起不来
容器镜像	跨层（打包了 CANN+框架+服务）	一次给齐软件栈	版本不配套，一跑就错
权重权限	L4 + OS	服务进程能读到文件	起服务时报读不到文件 / 权限拒绝

⭐ 一句关键区分：「服务起得来」和「模型答得对」是两件事。 前者是 L3 的事，后者是 L4 的事。本课 90% 的价值在第 ⑤ 步的验证上——因为绝大多数人验证不到位。

4.2 第 1 步：定档（先算资源，再下权重）

为什么放第一步：权重一下就是几小时、几十 GB，改主意的成本全是重下。

我会按官方给的「模型 × 硬件」对照表来选。以 vLLM Ascend 官方 Qwen3-Dense 教程为例（原文数值）：

模型变体	量化方式	官方给出的推荐配置
Qwen3-0.6B / 1.7B / 4B / 8B / 14B / 32B（BF16）	—	1 台 Atlas A3 推理产品（64GB × 16）或 1 台 Atlas A2 推理产品（64GB × 8）
Qwen3-32B-W8A8	W8A8	1 台 Atlas A3（64GB × 16）或 1 台 Atlas A2（64GB × 8）
Qwen3-32B-W4A4	W4A4	1 台 Atlas A3（64GB × 16）或 1 台 Atlas A2（64GB × 8）
Qwen3-8B-W8A8SC / 14B-W8A8SC	W8A8SC	Atlas 300I DUO（TP1）
Qwen3-32B-W8A8SC	W8A8SC	Atlas 300I DUO（TP4）

官方在同一处注明：「这些是推荐的卡数，可根据实际情况进行调整。」 —— 别把它当成硬门槛，它是已验证过的配置，不是唯一解。

视频模型这边，官方快速开始给的原文配置是：Wan2.1-T2V-14B / I2V-14B-480P / I2V-14B-720P 三个变体，示例均使用 8 卡推理（torchrun --nproc_per_node=8）。支持 1/2/4/8 卡。

⚠️ 数据纪律：官方未给出「显存用量 = 参数量 × 系数」这类通用估算公式。官方给的是分模型的推荐卡数表——用表选，不要用公式猜。你自己算的那条公式，出了问题是没人能背书的。 ⚠️ 别搞混一件事：官方确有一个 KV Cache 的计算公式，用在服务化参数配置里（MindIE 服务化参数的显存分配上限那一项）。它是"KV Cache 能占多少显存"的分配式，不是"权重占用 ≈ 参数量 × 系数"的估算式——两者用途完全不同，前后课引用时不要混为一谈。

4.3 第 2 步：拿权重（先校验，再解压）

官方可获得的渠道，一共三类：

渠道	官方入口	拿到什么
模型库 / 权重库	ModelZoo 模型库 `https://www.hiascend.com/software/modelzoo/models`；权重库 `https://www.hiascend.com/software/modelzoo/datasets`	昇腾适配过的模型与全量开源昇腾模型文件
开源社区	Hugging Face / ModelScope（国内推荐）；视频模型另有 Modelers（魔乐社区）	上游原始权重
镜像	昇腾官方镜像仓库 `https://www.hiascend.com/developer/ascendhub`；vLLM Ascend 镜像 `quay.io/ascend/vllm-ascend:<TAG>`	打包好 CANN+框架+服务的运行环境

LLM 权重怎么下（官方给的方式，两种择一）： - Hugging Face：wget https://huggingface.co/Qwen/Qwen3-8B/resolve/main/... - ModelScope（国内推荐）：wget https://www.modelscope.cn/models/Qwen/Qwen3-8B/resolve/master/...

⭐ 下完第一件事是校验——官方明写：「利用 sha256sum 计算 sha256 数值校验权重文件正确性和完整性」。 sha256 的值从哪来：官方指路——打开模型文件的明细页就能看到（HF 的文件页 / ModelScope 的文件查看页）。

视频模型权重：官方快速开始只给出 Wan2.1 系列三个变体的 HF 链接（https://huggingface.co/Wan-AI/Wan2.1-T2V-14B 等）， 权重路径需用户自行设置（官方示例：/home/{用户名}/example/Wan2.1-T2V-14B）。代码仓用 git clone https://modelers.cn/MindIE/Wan2.1.git 取（来自 Modelers 魔乐社区）。

⚠️ 官方未给出：推理服务化侧的完整「开源视频生成模型 × 昇腾」清单——《MindIE 视图生成推理快速入门》只以 Wan2.1 系列为例。 但训练与量化侧官方是有清单的（别按"官方啥都没有"处理）： ① MindSpeed 26.1.0《MM 模型支持列表》列出 OpenSoraPlan / CogVideoX / HunyuanVideo / Wan2.1 / Wan2.2 等（含参数量、集群、精度）； ② msModelSlim《多模态模型支持列表》的多模态生成行给出 SD3-Medium / Open-Sora-Plan v1.2 / FLUX.1-dev / HunyuanVideo / Wan2.1 / Wan2.2。 正确姿势：拿这两份官方清单查"这个模型官方适配过没有"，再回到推理侧文档确认服务化路径，不要外推。

4.4 第 3 步：落盘（容器根盘小，权重必须外挂）

这是租用/容器环境里最容易出问题、也最容易被忽略的一步。

官方口径（容器挂载）：

官方示例里的挂载	含义	出处
`-v /path-to-weights:/path-to-weights:ro`	权重目录挂进容器（只读）	MindIE SD 快速开始
`-v $MODEL_CACHE:/root/.cache`（`MODEL_CACHE=${HOME}/.cache`）	模型缓存目录挂进容器	vLLM Ascend 安装指南
`-v /usr/local/Ascend/driver:...:ro` 等	驱动/工具只读挂载	同上

⭐ 一条部署实践观察（非官方原文，标注在此避免误引）：租用容器环境的根文件系统通常很小，实测 overlay 只有 60G 量级——几十 GB 的权重放根盘一定爆。所以：权重、虚拟环境、日志、SDK 一律落到数据盘，再挂进容器。

权限：MindIE SD 官方对权重与配置文件有明确权限要求（原文）：

模型权重文件、配置文件：三组权限不得超过 640，且需要与执行用户的所属组和权限保持一致；
权重与配置文件所在的文件夹：三组权限不得超过 750，同样要与执行用户一致。

为什么这条要单独讲：官方明写「MindIE SD 接口会对传入的文件或文件夹做权限安全校验」—— 权限不对，服务不是跑错，而是读不到。这是「文件明明在那里却报读不到」的根因。

4.5 第 4 步：起服务（最短可照抄命令）

LLM 线：vLLM Ascend。 官方 Qwen3 教程给的单节点示例（基于 vLLM Ascend v0.23.0）：

export HCCL_OP_EXPANSION_MODE="AIV"
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve your_model_path \
  --served-model-name qwen3 \
  --trust-remote-code \
  --quantization ascend \
  --distributed-executor-backend "mp" \
  --tensor-parallel-size 4 \
  --max-model-len 5500 \
  --max-num-batched-tokens 40960 \
  --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}' \
  --port <port> \
  --gpu-memory-utilization 0.9

关键点：ASCEND_RT_VISIBLE_DEVICES 必须和 --tensor-parallel-size 对得上（示例是 4 卡对 TP=4）。 起服务前先在容器里验环境（输出要含 vLLM Ascend environment: OK）——这是 D2 讲过的判据，本课只引用。

视频线：MindIE SD。 官方快速开始给的是脚本推理（不是常驻服务），以 8 卡为例：

model_base="/home/{用户名}/example/Wan2.1-T2V-14B"
torchrun --nproc_per_node=8 generate.py \
      --task t2v-14B \
      --size 1280*720 \
      --ckpt_dir ${model_base} \
      --dit_fsdp \
      --t5_fsdp \
      --sample_steps 50 \
      --ulysses_size 8 \
      --vae_parallel \
      --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage." \
      --use_attentioncache \
      --start_step 20 \
      --attentioncache_interval 2 \
      --end_step 47

参数约束（官方原文）：ulysses_size * cfg_size = nproc_per_node——两个并行数相乘必须等于卡数，配错起不来。 use_attentioncache 官方明说是「有损优化」——要开就必须同时给 start_step / attentioncache_interval / end_step；不开就三个都别写。

4.6 第 5 步：验证（本课最关键的一步）

LLM 线：判据是「非空补全」。

接口返回 200 只说明「服务在」，不说明「推理成功」；
官方判据：返回内容为空（空补全）不算推理成功（见 D2）；
所以要同时验三样：端口在听、/v1/models 有你的模型名、/v1/chat/completions content 非空。

视频线：判据是「可播放文件」。

推理跑完不报错 ≠ 成功——可能产出的是一段花屏/黑屏/零字节文件；
所以要验四样：文件存在且非零字节、能被播放器打开、时长/分辨率/帧率符合 --size/--frame_num 预期、重复跑结果稳定。

⚠️ 官方未给出：视频模型输出文件的默认落盘路径（《快速开始》未写明输出目录）。 这里要自己看运行打印确认——明说「官方未给出，需按实际环境确认」，不编一个路径给你。

4.7 第 6 步：对外提供 API（LLM 是主角，视频线另说）

官方给出的对外接口（LLM 线）——OpenAI 兼容，端点原文：

接口	路径	出处
对话补全	`/v1/chat/completions`	MindIE Motor《接口说明》
文本补全	`/v1/completions`	同上
模型列表	`/v1/models`	同上

鉴权与限流（MindIE Motor 官方原文）：

API Key：对 /v1/completions、/v1/chat/completions 生效； Header 名称 = api_key_config.header_name（默认 Authorization），前缀 = api_key_config.key_prefix（默认 Bearer）；
限流（可选）：rate_limit_config.enable_rate_limit=true 时启用，超限返回 429；
TLS：infer_tls_config.enable_tls 为 true 时推理接口走 https。

vLLM Ascend 侧：官方模型教程中出现了 --api-key 参数（OpenAI 兼容服务自带），用法以 vLLM 官方 CLI 为准。

并发：LLM 侧由 --max-num-seqs（并发序列数）、--max-num-batched-tokens、--gpu-memory-utilization 一起决定； 视频线并发极低——一次生成就占满全部卡，不能当在线并发服务用。

⚠️ 官方快速开始（视频线）走的是脚本推理：MindIE SD《快速开始》给的是 torchrun 脚本，没有在那一页给 OpenAI 兼容的 REST 服务端点。 但服务化并非没有官方路径，两条要看： ① MindIE SD《架构设计》里列了 examples/service（服务化样例） 与 examples/cache； ② 《MindIE SD 安装指导》里另有一条镜像安装（vLLM-Omni）路径可作服务化入口。 具体接口以官方对应文档为准，本课不代它写——记住结论：视频线的默认姿势是"任务式调用"，不是"常驻并发服务"。

4.8 第 7 步：多模型与版本切换 / 回滚

多模型并存：同一台机器起多个实例，各占一个 --port（vLLM）；或按 MindIE Motor 的 image_name + weight_mount_path 各配一套。

版本切换 / 回滚，三条纪律：

不要随意混用不同发布版本的组件——vLLM Ascend 官方原文：「上表中的版本和要求作为一个兼容性集合进行验证。请勿随意混用不同发布版本的组件。」要换版本，就从「版本策略 > 发布兼容性矩阵」里选完整的一行；
镜像 tag 就是你的版本开关：quay.io/ascend/vllm-ascend:v0.23.0 → 换 tag 即换版本； 回滚 = 把上一个 tag 拉回来重起；
容器重建会丢掉容器内装的东西——所以镜像 tag 与权重目录都要留档，这才是能回滚的前提。

4.9 第 8 步：上线前 checklist（N 条全过 = 完工）

#	检查项	判据
1	卡与驱动就位	`npu-smi info` 有输出
2	CANN 环境生效	`echo $ASCEND_HOME_PATH` 有值
3	权重落数据盘	权重不在根盘，`df -h` 有富余
4	权重完整性	`sha256sum` 与官方值一致
5	权重权限	文件 ≤640、目录 ≤750，属组与执行用户一致（MindIE SD）
6	服务环境自检	`vLLM Ascend environment: OK`
7	端口在听	`ss -lntp` 能看到该端口
8	接口可列模型	`curl --fail .../v1/models` 返回模型名
9	推理非空	`/v1/chat/completions` 的 content 非空（LLM）
10	视频可播放	产出非零字节文件 + 播放器可打开 + 时长/分辨率符合预期（视频线）
11	鉴权与限流	密钥 header 生效；不需要限流则明确知晓未开
12	版本可回滚	旧镜像 tag 与旧权重目录都留着

第五段怎么确认就位（可复制命令 + 期望输出）

这一段只给命令与判据；每条命令按「含义 / 拆解 / 用法 / 期望 / 不过会怎样」五件套解释。

命令　npu-smi info

含义：查昇腾设备信息——整个流程的第 0 步，先确认卡在不在拆解：npu-smi（昇腾设备管理工具，随驱动包一起装，见 A1）＋ info（查信息的子命令）用法：直接敲；要看设备号用 npu-smi info -l 期望：打印一张表，列出各卡的型号、温度、显存、进程 不过会怎样：命令不存在 → 驱动没装（回 A1）；有输出但列不出卡 → 硬件或权限问题（回 A1）

命令　echo $ASCEND_HOME_PATH

含义：确认 CANN 环境变量是否已加载——判断 CANN「装完并 source 了吗」的最快判据 拆解：echo（打印）＋ $ASCEND_HOME_PATH（CANN 安装根路径变量，见 B1）用法：新开终端要先 source /usr/local/Ascend/cann/set_env.sh（root）再敲期望：打印出一个非空路径 不过会怎样：打印空白 → CANN 没装或没 source（回 B1/B3）；此后所有框架导入失败多半源于此

命令　df -h /path-to-weights

含义：确认权重要落的那个目录还有没有空间 拆解：df（disk free，看磁盘占用）＋ -h（人类可读单位）＋目标路径用法：把 /path-to-weights 换成你实际的数据盘挂载点期望：Avail 一列有明显大于权重体积的富余 不过会怎样：Avail 很小或落在 overlay 根盘上 → 权重必须先换到数据盘（回 4.4）

命令　sha256sum ./model-00001-of-00005.safetensors

含义：算权重文件的 sha256，与官方明细页的值比对——下完先校验拆解：sha256sum（算 SHA-256 摘要）＋单个权重分片文件用法：对每个分片各跑一次（model-00001-of-00005 … -00005-of-00005 都要）期望：输出的摘要与官方文件明细页显示的值逐位一致 不过会怎样：不一致 → 文件不完整或下坏了：重下该分片，别硬上（残缺权重报错极难查）

命令　ls -l /path-to-weights/Wan2.1-T2V-14B

含义：看权重文件与目录的权限位是否满足官方 640 / 750 要求拆解：ls -l（长格式，含权限、属主、属组）用法：对着 4.4 的权限要求逐行核对；不符就用 chmod/chgrp 调整（属主要与执行用户一致）期望：文件三组权限不超过 -rw-r-----（640），目录不超过 drwxr-x---（750） 不过会怎样：权限过大或属组不符 → MindIE SD 的权限安全校验直接拒，服务报读不到权重（回 4.4）

命令　vllm serve your_model_path --served-model-name qwen3 --trust-remote-code --quantization ascend --tensor-parallel-size 4 --max-model-len 5500 --port 8000

含义：用 vLLM Ascend 起一个 OpenAI 兼容的推理服务（基于 vLLM Ascend v0.23.0）拆解：vllm serve（起服务）＋ your_model_path（本地权重目录，不是模型 ID）＋ --served-model-name qwen3（对外模型名）＋ --quantization ascend（用昇腾量化档）＋ --tensor-parallel-size 4（4 卡张量并行，要与 ASCEND_RT_VISIBLE_DEVICES 对齐）＋ --port 8000 用法：单卡小模型可去掉 --tensor-parallel-size；起服务前先导出 ASCEND_RT_VISIBLE_DEVICES 与 PYTORCH_NPU_ALLOC_CONF=expandable_segments:True 期望：日志出现服务启动完成，端口进入监听 不过会怎样：报显存不足 → 换更小模型或降量化档（回 4.2）；报权重格式/加载失败 → 查权重是否残缺、--quantization 与权重档是否匹配（回 4.3）；报设备不可用 → 回 L0/L1

命令　ss -lntp | grep 8000

含义：确认服务端口确实在监听——「起了服务」和「端口在听」不是一回事拆解：ss（看 socket）＋ -l（只看 listening）＋ -n（端口用数字）＋ -t（TCP）＋ -p（显示进程）用法：把 8000 换成你 --port 给的端口期望：有一行 LISTEN，进程名是你的服务 不过会怎样：无输出 → 服务没起来或崩了：看服务日志定位（这是 D3 日志章节的活）

命令　curl --fail http://localhost:8000/v1/models

含义：验服务接口是否真的可访问（不是只看端口在听）拆解：curl（发 HTTP 请求）＋ --fail（4xx/5xx 直接返回非零退出码）＋ /v1/models（模型列表接口）用法：curl --fail -s .../v1/models | python3 -m json.tool 格式化看期望：返回 JSON，data 里有你的 --served-model-name 不过会怎样：Failed to connect → 服务没起或端口不对；--fail 报 4xx/5xx → 接口有错（不加 --fail 时 404 也看着像成功）

命令　curl --fail http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"qwen3","messages":[{"role":"user","content":"who are you?"}],"max_tokens":32}'

含义：发一次真实推理请求——本课 LLM 线的最终验收动作 拆解：/v1/chat/completions（对话补全）＋ "model"（填 --served-model-name）＋ messages（消息数组）＋ max_tokens（生成上限）用法：想流式加 "stream": true；有密钥时加 -H "Authorization: Bearer <你的密钥>" 期望：返回 JSON，choices[0] 里有非空生成内容 不过会怎样：返回 200 但内容是空的 → 官方判据：空补全不算推理成功（回 4.6）；{"detail":"Service is not available"} → 不是端口错，是服务没就绪（回 D3）

命令　torchrun --nproc_per_node=8 generate.py --task t2v-14B --size 1280*720 --ckpt_dir ${model_base} --dit_fsdp --t5_fsdp --sample_steps 50 --ulysses_size 8 --vae_parallel --prompt "a cat on a surfboard"

含义：用 MindIE SD 跑一次文生视频（基于 MindIE 3.1.0 / MindIE SD）——本课视频线的最终验收动作 拆解：torchrun --nproc_per_node=8（8 卡起）＋ generate.py（推理入口）＋ --task t2v-14B（任务类型）＋ --size 1280*720（分辨率）＋ --ckpt_dir（权重路径）＋ --sample_steps 50（扩散迭代步数）＋ --ulysses_size 8（并行数）用法：ulysses_size × cfg_size 必须等于 nproc_per_node（官方约束）；图生视频换 --task i2v-14B 并加 --image 期望：跑完且不报错；但真正判据在下一步——看产出文件 不过会怎样：报 OOM/显存不足 → 降分辨率或减卡（回 4.2）；报读不到权重 → 先查权限（回 4.4）；报并行数不匹配 → 核对 ulysses_size × cfg_size

命令　ls -lh <输出目录> | grep -E '\.(mp4|avi|mov)$'

含义：检查视频推理的产物——LLM 看返回值，视频模型看文件拆解：ls -lh（长格式含大小）＋按视频扩展名过滤用法：<输出目录> 官方未给出默认落盘路径，需按运行打印确认（见 4.6）期望：有非零字节的视频文件；再用播放器或 ffprobe 核对时长/分辨率/帧率符合 --size/--frame_num 预期 不过会怎样：无文件 → 推理其实没产出（回 4.5）；文件 0 字节或打不开 → 生成失败，别当成成功（回 4.6）

第六段判据与验收

验收的锚：不是「没报错」，而是「完成态达成」。两条线的完成态不同，判据也不同。

6.1 LLM 线判据

#	判据	验证方式	不过说明问题在
①	端口在听	`ss -lntp` 有 LISTEN	L3 服务层没起
②	接口可访问	`curl --fail .../v1/models` 返回 200	L3 路由/端口
③	模型名正确	`/v1/models` 列出 `--served-model-name`	启动参数
④	推理非空	`/v1/chat/completions` 的 content 非空	L4 模型/权重/量化
⑤	能定位到层	给一个报错能判断属于哪层	体系的灵魂（见 A0）

6.2 视频线判据

#	判据	验证方式	不过说明问题在
①	推理跑完不报错	看运行日志	L3/L4
②	产出非零字节文件	`ls -lh` 看大小	生成失败
③	能被播放器打开	本地播放器 / `ffprobe`	文件损坏或格式不对
④	时长/分辨率/帧率符合预期	对照 `--size`、`--frame_num`	参数没生效
⑤	重复跑结果稳定	同参数再跑一次对比	显存/并行配置不稳

⭐ 一条最容易错过的判据：「跑完没报错」在视频线里常常是假阳性—— 进程正常退出，但产物是零字节或黑屏。所以视频线的判据必须落到「文件」上，不能落到「退出码」上。

第七段出问题怎么查

排障原则：先定「卡在哪一步」，再看技术细节。 本课的九步流程本身就是排查地图。

现象	大概是什么	先查什么	回哪一层/哪一步
显存不足 / OOM	模型或量化档选大了、卡数不够	官方分模型推荐卡数表；`--gpu-memory-utilization`	4.2 定档（L4）
权重格式不对 / 加载失败	权重残缺、量化档与 `--quantization` 不匹配	`sha256sum` 校验；权重档（W8A8/W4A4/W8A8SC）与参数是否一致	4.3 拿权重（L4）
网络隔离、权重下不下来	外网不可达（HF 连不上）	换 ModelScope；或走离线包/镜像	4.3 拿权重
权限拒绝 / 读不到权重	文件权限过大或属组不符；容器 `--device` 权限不足	`ls -l` 对 640/750；容器 `--device` 用 `rwm`	4.4 落盘（L4/OS）
驱动或 CANN 未就位	卡不认得 / 环境变量为空	`npu-smi info`；`echo $ASCEND_HOME_PATH`	L0/L1（回 A1/B1）
服务起得来但答不出东西	L4 问题，不是 L3	LLM 看是否空补全；视频看产物文件	4.6 验证（L4）
返回 `Service is not available`	服务没就绪（不是端口错）	看服务日志	回 D3

⭐ 一个判断法：

报错发生在「起服务之前」  →  环境/资源问题（L0/L1/L2 + 4.2/4.3/4.4）
报错发生在「起服务之后」  →  服务/模型问题（L3 + 4.6/4.7）

⭐ 按「五类点名问题」排的排查顺序：

① 显存不足     → 先回 4.2 重新定档（换小模型/更低量化档/加卡），不要去改服务参数硬撑
② 权重格式不对 → 先 sha256sum 校验完整性，再核对 --quantization 与权重档是否匹配
③ 网络隔离     → 换 ModelScope 镜像源，或改用离线包/预置镜像
④ 权限         → ls -l 对 640/750；容器 --device 用 rwm；属主与执行用户一致
⑤ 驱动/CANN    → npu-smi info + echo $ASCEND_HOME_PATH，回 A1/B1

第八段常见报错清单

下表按现象给排查方向；报错案例编号取自昇腾官方案例库（https://www.hiascend.com/document/caselibrary/detail/<案例编号>）。 检索技巧（E1 讲过）：按报错里的稳定特征词检索（错误码、函数名、库名），不要按「部署上架」这种大词检索。

报错 / 现象	大概属于	先查什么	官方案例编号
`RuntimeError: malloc:/.../NPUCachingAllocator.cpp NPU error, error code is 500000`	显存/内存	5XXXXX 属设备侧异常：先降批量/降档，收日志	`topic_0000001589894849`
提示显存不足：`Sum of total mem_offset ... greater than memory manager malloc max size`	显存不足	按推荐卡数表重新定档；不要硬撑	`topic_0000002176651049`
`npu-smi info` 查看显存时发现 Python 进程残留	进程未清理	上一次服务没退干净，先清理进程再起服务	`topic_0000001589894865`
加载大模型时耗时过长	权重加载	确认是否只是加载慢，或权重路径/格式不对	`topic_0000002214923358`
`ModuleNotFoundError: No module named 'torch_npu'`（跨平台加载模型）	环境	TorchNPU 没装好或环境变量没加载（回 C1）	`topic_0000001589732149`
应用程序权限不足导致 AscendCL 初始化报错	权限	执行用户权限 / 目录权限（回 4.4）	`aclcase_0019`
容器内执行命令报 `Operation not permitted`	容器权限	`--device` 权限、能力集（回 B5）	`case_9277`
压测/推理中进程被 killed	资源超限	显存/系统内存被耗尽，降档或加资源	`toolboxcase_0066`
用 MindIE Benchmark 或脚本发请求时出现超时	服务/网络	请求超时：看服务是否就绪、并发是否过高	`topic_0000002215083154`
`No space left on device` / 报磁盘空间不足	落盘	权重别放根盘，换数据盘（回 4.4）	`topic_0000001382525429`

⚠️ 一条诚实提醒：官方现有案例库中，没有收录「vLLM Ascend 服务启动类」与「视频模型权重格式类」的成文案例（这两类我按特征词检索，返回 0 条）。 所以这两类报错请按「服务日志 + 官方最新 FAQ」现场定位，不要指望有一个现成编号可以对。

第九段小结与下一课

这一课要带走的三句话：

先定「部署完成态」，再反推资源与选型——顺序反了，下完权重才发现卡不够，代价是重下。
LLM 与视频模型的验收判据不同：LLM 是「空补全不算推理成功」；视频模型是「产出可播放文件」。拿错判据，会验收出一个假的成功。
五类问题各有归处：显存 → 4.2 定档；权重格式 → 4.3 校验；网络 → 4.3 换源/离线；权限 → 4.4 配对；驱动/CANN → L0/L1。

上线前一句话：12 条 checklist 全过，才算「上架」（见 4.9）。

部署出来能干什么（业务视角）

具体业务落地详见 F7，这里只点方向，不铺细节。

LLM 侧：

内网问答与文档助手（把模型接口接进内部系统，数据不出域）
批量文本加工（摘要、分类、抽取——走 /v1/completions 批处理）
代码/工单辅助（嵌入研发或运维工具链）
作为 RAG 的底座模型（知识库检索 + 模型生成，见 G 层）

视频模型侧：

按文案批量生成短视频素材（营销/内容生产）
图生视频：把已有图片做成动态短片
广告/宣传片的分镜预演

⭐ 两条线的业务节奏完全不同：LLM 可以高并发在线；视频模型一次生成占满卡、以分/秒计—— 所以视频线更适合离线批量排队，不适合做实时接口。这个判断在方案阶段就要做出来。

下一课预告（F7）：把这一课部署出来的服务接到真实业务里—— 从「有个能调的接口」到「业务真的在用」，讲清落地路径与验收口径。

附录 A · 本课引用的官方出处

内容	来源文档
部署完成态的两条线、九步流程、两条线差异总表、checklist	本课整理（方法层面归纳，非官方术语）
Qwen3-Dense 模型变体/量化方式/推荐卡数表、「推荐卡数可根据实际情况调整」	vLLM Ascend《模型教程 · Qwen3-Dense》（基于 vLLM Ascend v0.23.0）
`vllm serve` 单节点示例、`ASCEND_RT_VISIBLE_DEVICES` / `HCCL_OP_EXPANSION_MODE` / `PYTORCH_NPU_ALLOC_CONF`、`--api-key`	同上
兼容性集合与「请勿随意混用不同发布版本组件」、镜像名（`quay.io/ascend/vllm-ascend:v0.23.0` 及 `-a3/-310p/-a5/-openeuler`）、镜像加速源、容器启动与管理缓存挂载、`vLLM Ascend environment: OK` 判据、已验证软硬件版本集合（Python 3.12 / HDK 26.0.RC1 / CANN 9.1.0 / NNAL 9.1.0 / PyTorch 2.10.0 / TorchNPU 2.10.0.post4 / Triton Ascend 3.2.2 / vLLM 0.23.0 / vLLM Ascend 0.23.0）	vLLM Ascend《安装指南》
「使用 MindIE-Motor 部署 vLLM-Ascend」入口（PD 分离/聚合）	vLLM Ascend《使用 MindIE-Motor 部署 vLLM-Ascend》
视频模型（Wan2.1 三变体）权重链接、权重路径自设、8 卡 `torchrun generate.py` 示例与参数表、`ulysses_size × cfg_size = nproc_per_node`、`use_attentioncache` 为有损优化、容器启动与权重只读挂载、权重/配置文件权限 640 / 文件夹 750、镜像组件安装路径	MindIE 3.1.0《MindIE 视图生成推理快速入门》
OpenAI 兼容端点（`/v1/chat/completions`、`/v1/completions`、`/v1/models`）、API Key 配置（`header_name` 默认 `Authorization`、`key_prefix` 默认 `Bearer`）、限流 `rate_limit_config.enable_rate_limit` 超限返回 `429`、TLS 开关	《MindIE Motor · 接口说明》
权重下载两种方式（Hugging Face / ModelScope 的 `wget` 命令）、`sha256sum` 校验完整性	MindSpeed 26.1.0《快速入门》
ModelZoo 模块（模型库、权重库、大模型、工具库/镜像仓库）、`modelzoo/datasets` 权重库入口	《Hello，ModelZoo》
官方案例编号（`topic_0000001589894849` 等 10 条）	昇腾官方案例库

本课未展开的部分（避免越界）：

未给任何性能/并发数字——官方文档与本课素材中未出现可直接引用的通用性能指标，故不编造。
未给「显存用量估算公式」——官方给的是分模型推荐卡数表，无通用公式；本课据此明说「用表选」。
未写视频模型的默认输出路径——官方《快速开始》未给出，已按数据纪律标注「需按实际环境确认」。
未写视频模型的 REST 服务接口——官方快速开始给的是脚本推理；服务化入口仅提到 vLLM-Omni 镜像安装路径，细节以其官方文档为准。
未列「开源视频生成模型 × 昇腾」完整支持清单——官方快速开始仅以 Wan2.1 系列为例。

附录 B · 命令与代码逐条详解

B.1 部署链路三连（第 0 步，一条命令拆三层）

命令	验的是哪一层	期望	不过会怎样
`npu-smi info`	L0 硬件 + 驱动	有卡表输出	命令不存在 → 驱动没装（A1）
`echo $ASCEND_HOME_PATH`	L1 CANN 环境	非空路径	空 → 没 source 或没装（B1）
`python3 -c "import torch, torch_npu; print(torch.npu.is_available())"`	L2 框架	打印 `True`	`False` → 框架没认出卡（C1）

B.2 权重获取与校验

命令	含义	出处
`wget https://huggingface.co/Qwen/Qwen3-8B/resolve/main/config.json`	从 Hugging Face 按文件逐个下	MindSpeed 快速入门
`wget https://www.modelscope.cn/models/Qwen/Qwen3-8B/resolve/master/config.json`	从 ModelScope 下（国内推荐）	同上
`sha256sum ./model-00001-of-00005.safetensors`	算权重分片 sha256，与明细页比对	同上
`git clone https://modelers.cn/MindIE/Wan2.1.git`	取视频模型推理代码仓（Modelers 魔乐社区）	MindIE SD 快速入门

权重文件不止一个 safetensors：config.json、tokenizer.json、vocab.json、merges.txt、 generation_config.json、model.safetensors.index.json 都是模型运行必需的——少一个都可能加载失败。

B.3 落盘与挂载（官方示例里的三个挂载含义）

挂载项	含义	出处
`-v /path-to-weights:/path-to-weights:ro`	权重与数据集目录挂进容器（只读）	MindIE SD 快速入门
`-v ${HOME}/.cache:/root/.cache`	模型缓存目录挂进容器	vLLM Ascend 安装指南
`-v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro`	驱动目录只读挂载	MindIE SD 快速入门

B.4 `--device` 权限为什么必须是 `rwm`

官方原文：Atlas 800I A2 场景下，若挂载权限设为 rw，可以进容器、也能用 npu-smi 看占用，但若该卡上有其它任务占用，npu-smi 会报错，且无法运行任务（torch.npu.set_device() 失败）。 所以官方要求权限写 rwm，而不是权限更小的 rw 或 r。

挂载的设备	是什么
`/dev/davinciX`	NPU 设备（X 是 ID 号）
`/dev/davinci_manager`	davinci 相关管理设备
`/dev/hisi_hdc`	hdc 相关管理设备
`/dev/devmm_svm`	内存管理相关设备

查本机设备个数与名称：ll /dev/ | grep davinci（官方给的查询方式）。

B.5 `vllm serve` 核心参数速记

参数	作用	易错点
`your_model_path`	本地权重目录路径	传的是路径，不是模型 ID（除非走缓存源）
`--served-model-name`	对外暴露的模型名	请求里的 `"model"` 必须与它一致
`--trust-remote-code`	允许加载模型自带代码	部分模型不加会加载失败
`--quantization ascend`	启用昇腾量化档	与权重的量化档（W8A8/W4A4）必须匹配
`--tensor-parallel-size`	张量并行卡数	要与 `ASCEND_RT_VISIBLE_DEVICES` 的卡数对齐
`--max-model-len`	最大上下文长度	设太大吃显存
`--max-num-seqs`	最大并发序列数	直接影响并发能力与显存
`--max-num-batched-tokens`	批处理 token 上限	与吞吐/显存权衡
`--gpu-memory-utilization`	显存占比	设太高容易 OOM
`--port`	服务端口	多模型并存时各占一个
`--api-key`	接口鉴权密钥	关掉即无鉴权，内网也要评估风险

B.6 视频模型 `generate.py` 关键参数（官方参数表择要）

参数	含义	官方取值/约束
`--task`	任务类型	`t2v-14B`（文生视频）/ `i2v-14B`（图生视频）
`--size`	分辨率（宽*高）	t2v 默认 `1280*720`；i2v-480P 默认 `[832,480]`/`[720,480]`
`--frame_num`	生成视频帧数	默认 `81`
`--sample_steps`	扩散迭代步数	t2v 默认 `50`；i2v 默认 `40`
`--ckpt_dir`	权重路径	用户自设
`--nproc_per_node`	并行卡数	Wan2.1 支持 `1/2/4/8`
`--ulysses_size`	ulysses 并行数	默认 `1`；`ulysses_size × cfg_size = nproc_per_node`
`--cfg_size`	cfg 并行数	默认 `1`
`--dit_fsdp` / `--t5_fsdp`	DiT/T5 使用 FSDP	分片并行开关
`--vae_parallel`	VAE 并行	并行策略开关
`--use_attentioncache`	使能注意力缓存优化	官方注明为有损优化；需配 `start_step`/`attentioncache_interval`/`end_step`

B.7 两次「验证」的区别（本课最该记住的一张表）

	LLM	视频模型
验什么	返回值内容	产出文件
命令	`curl .../v1/chat/completions`	`ls -lh <输出目录>` + 播放器/`ffprobe`
成功长什么样	`choices[0]` 内容非空	非零字节、可播放、时长/分辨率符合预期
最容易误判的假成功	返回 200 但空补全	进程正常退出但零字节/黑屏文件
判据出处	D2（「空补全不算推理成功」）	本课整理（官方快速开始未给出输出文件判据）