本仓库交付部署物料:部署指导(本文档 README.md)与两个昇腾必需补丁(patches/)。权重、推理镜像、容器等运行依赖请按下文步骤准备,均无需从本仓库获取。
qwen-image-2.1-deploy/
├── README.md ← 本文档(部署指导正本,含全部启动命令)
└── patches/
├── patch_rope.py ← 补丁①:QwenImage21Rope 频率表返回 (cos,sin)
└── patch_rope3.py ← 补丁②+③:apply_rotary 多头 float 分支 + prefix 切片| 文件 | 类型 | 说明 |
|---|---|---|
README.md | 文档 | 部署指导(本文档,服务启动命令均直接内嵌于正文) |
patches/patch_rope.py | 补丁 | 补丁①(1965B,md5 31ff6ceff8b54b04d67f401b62de885e):QwenImage21Rope.forward 不再返回 complex64 频率表,改为返回 (torch.cos(angles), torch.sin(angles)),规避 torch_npu 的 DT_COMPLEX64 indexing(error 161002) |
patches/patch_rope3.py | 补丁 | 补丁②+③(2750B,md5 485b9c13968435a07b5a9143b22ba64e):apply_rotary_emb_qwen 增加多头 float 分支(cos.unsqueeze(1)=[S,1,D_pair] 广播 + 实虚部 = 复乘的浮点等价),并用 prefix 切片适配 tuple 返回 |
当前补丁:v1(2026-09-24,patches/patch_rope.py + patches/patch_rope3.py,2 文件,按序应用)。
| 版本 | 提交记录 | 补丁规模 | 更新内容 |
|---|---|---|---|
| v1 | 2026-09-24 首发 | 2 文件 1965B + 2750B | RoPE float 化 + 多头广播修复(完整替代官方 complex 路径,数值与复乘逐位等价): ① QwenImage21Rope.forward 返回 (cos,sin) float 表;② apply_rotary_emb_qwen 对 tuple 输入走多头 float 分支:x.reshape(...,-1,2).unbind(-1) + real=xr·cos−xi·sin / imag=xi·cos+xr·sin,stack.flatten(-2);③ prefix 切片 rotary_emb = (rotary_emb[0][prefix_len:], rotary_emb[1][prefix_len:]) |
补丁重放说明:补丁为 diffusers 纯源码直接改(不是 git apply,vllm-omni 镜像内 diffusers 无 git 仓库),无需重新编译。重装 diffusers 后按顺序重放即可(顺序不可换):
docker exec vllm-omni-qwen-image21 python /tmp/patch_rope.py→/tmp/patch_rope3.py,验证grep -c "npu patch"(transformer_qwenimage21.py内)应输出 5。
| 步骤 | 执行位置 | 说明 |
|---|---|---|
| 1 | 宿主机 | 拉取镜像,下载权重(见「获取权重」),创建容器(见「第一步」) |
| 2 | 容器内 | diffusers@main(git 源码安装)+ transformers==5.17.0 + 补丁 v1(按序两张,验证 grep -c=5) |
| 3 | 容器内 | 执行启动命令(见「第三步」:TP=1 / 端口 8091 / adapter 加载) |
| 4 | 任意 | curl http://<API_HOST>:8091/health 应 200;发请求出图(见「发请求测试」) |
| 组件 | 版本 / 说明 |
|---|---|
| vllm-omni | tag v0.28.0(quay.io/ascend/vllm-omni:v0.28.0;国内网络建议用南京镜像站副本 quay.nju.edu.cn/ascend/vllm-omni:v0.28.0) |
| diffusion 引擎 | vllm-omni 内置(diffusion/ 子命令族,CLI 前缀即 --diffusion-*);镜像不含 QwenImage21 原生 registry 支持,经 DiffusersAdapterPipeline 托管官方 diffusers 管线 |
| diffusers | 0.41.0.dev0(git main 源码安装) |
| transformers | 5.17.0(pip -U 覆盖镜像内置,官方要求 ≥5.17) |
| torch / torch_npu | torch 2.10.0+cpu + torch_npu(镜像自带,CANN 8.2.RC1 环境) |
| CANN | 8.2.RC1(ASCEND_HOME_PATH=/usr/local/Ascend/ascend-toolkit/8.2.RC1;容器内按需手工 export) |
| 驱动 / npu-smi | 宿主机驱动挂载,核对用原始 npu-smi info(HBM-Usage 列) |
选用 vLLM-Omni 官方镜像(境外 quay.io 拉不动时用南大镜像站):
docker pull quay.io/ascend/vllm-omni:v0.28.0 # 或:quay.nju.edu.cn/ascend/vllm-omni:v0.28.0| 项目 | 参数 |
|---|---|
| 机型 | 1× Atlas 800T A2 |
| NPU | 1× Ascend910B3(64GB HBM);部署前用 npu-smi info 核对目标卡 HBM 余量 ≥ 45G |
| 模型 | Qwen-Image-2.1(文生图 DiT),bf16,权重 33.13 GB / 29 文件 |
| 张量并行 | TP=1(adapter 加载形态在单卡载全量模型完成整条推理,单卡 HBM 占用 ~37-41G) |
| API 端口 | 8091(host 网络,宿主机即容器) |
| 实测吞吐 | 512×512/30 步 3.9s(≈0.26 QPS);1024×1024/30 步 13.9s |
| 组件 | 参数 |
|---|---|
| 模型类型 | 文生图 Diffusion Transformer(DiT,非 MLLM),官方量级约 20B(含文本端) |
| patchify | patch_size=1 / causal-condition transformer(Qwen-Image-2.1 换代架构) |
| 文本编码 | Qwen3-VL-8B 文本端(text_encoder/,4 分片 ~17.5 GB,bf16) |
| 主模型 | DiT transformer(transformer/,2 分片 ~14.2 GB,bf16) |
| VAE | 自研残差 VAE(vae/,1 文件 1.35 GB) |
| 位置编码 | RoPE(QwenImage21Rope)——910B 必须走补丁 v1 的 float 路径 |
| 支持尺寸 | 512×512 / 1024×1024 / 2048×2048 均实测通过;默认 30 步采样 |
# modelscope download(推荐)
modelscope download --model Qwen/Qwen-Image-2.1 --local_dir /opt/data/models/Qwen-Image-2.1
# 或 resolve 直链模板(逐文件下载):
# https://modelscope.cn/models/Qwen/Qwen-Image-2.1/resolve/master/<仓库相对路径>权重 33.13 GB / 29 文件(
text_encoder/4 分片、transformer/2 分片、vae/、processor/、scheduler/、assets/),落宿主机后挂载进容器(见「第一步」)。
在服务节点宿主机上执行(HOST_MODEL_PATH 指向实际权重路径):
export IMAGE=quay.io/ascend/vllm-omni:v0.28.0
export NAME=vllm-omni-qwen-image21
export HOST_MODEL_PATH=/opt/data/models/Qwen-Image-2.1
export SHM=256g
docker run -d --name "$NAME" \
--shm-size "$SHM" \
--net=host \
--privileged \
-e ASCEND_VISIBLE_DEVICES=0-7 \
--device /dev/davinci0 --device /dev/davinci1 \
--device /dev/davinci2 --device /dev/davinci3 \
--device /dev/davinci4 --device /dev/davinci5 \
--device /dev/davinci6 --device /dev/davinci7 \
--device /dev/davinci_manager --device /dev/devmm_svm --device /dev/hisi_hdc \
-v /usr/local/dcmi:/usr/local/dcmi \
-v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v ${HOST_MODEL_PATH}:/opt/data/models \
-v /root/.cache:/root/.cache \
-v /tmp:/tmp \
"$IMAGE" sleep infinity说明:
--net=host:容器端口即宿主机端口(8091 直接对外);--privileged+ davinci 设备组为 NPU 访问必需- 权重挂载为
${HOST_MODEL_PATH}:/opt/data/models,模型路径容器内恒为/opt/data/models/Qwen-Image-2.1;/tmp:/tmp让容器与宿主机共享日志/临时文件ASCEND_VISIBLE_DEVICES=0-7只是容器可见全集(CANN 8.x 环境变量名),实际使用的卡在「第三步」服务层指定
1. 上传补丁到容器(仓库根目录执行):
docker cp patches/patch_rope.py vllm-omni-qwen-image21:/tmp/
docker cp patches/patch_rope3.py vllm-omni-qwen-image21:/tmp/2. 按序应用(顺序不可换):
docker exec vllm-omni-qwen-image21 python /tmp/patch_rope.py # ① 补丁①
docker exec vllm-omni-qwen-image21 python /tmp/patch_rope3.py # ② 补丁②+③补丁会同时写入 diffusers 的 site-packages 与 git 源码副本(
/vllm-workspace/diffusers-main/),纯源码改动无需重新编译。
3. 验证:
docker exec vllm-omni-qwen-image21 bash -c 'P=$(python3 -c "import diffusers,os;print(os.path.join(os.path.dirname(diffusers.__file__),\"models/transformers/transformer_qwenimage21.py\"))"); grep -c "npu patch" "$P"'
# 期望输出 5diffusers 环境前置(重装后再打补丁才有效):官方要求 diffusers 走 git main(无 release)且 transformers ≥5.17:
docker exec vllm-omni-qwen-image21 bash -lc ' curl --retry 3 -L -o /tmp/diffusers-main.tar.gz https://codeload.github.com/huggingface/diffusers/tar.gz/refs/heads/main tar xf /tmp/diffusers-main.tar.gz -C /vllm-workspace/ pip install /vllm-workspace/diffusers-main/ # 装成 0.41.0.dev0 pip install -U transformers==5.17.0'
将下文启动命令保存为容器内
/workspace/start_service.sh后执行。服务形态:TP=1 / 单张 910B3 / 端口 8091 / DiffusersAdapterPipeline(adapter 加载)。
容器内 /workspace/start_service.sh:
# ---- 设置环境变量 ----
unset ASCEND_VISIBLE_DEVICES # 当前镜像所用 CANN 下该旧名不生效,清除避免歧义
export ASCEND_RT_VISIBLE_DEVICES=<物理卡号> # 指定使用的物理卡(CANN 8.x 用此新名;按 npu-smi 余量选择,见下)
export VLLM_PLATFORM=ascend
export VLLM_WORKER_MULTIPROC_METHOD=spawn
# ---- 启动服务 ----
exec vllm serve /opt/data/models/Qwen-Image-2.1 \
--omni \
--port 8091 \
--trust-remote-code \
--diffusion-load-format diffusers \ # 必须:adapter 加载(原生 registry 无 QwenImage21)
--diffusion-attention-backend TORCH_SDPA \ # 必须:见关键参数说明
--tensor-parallel-size 1 \
--gpu-memory-utilization 0.9从宿主机后台启动(推荐,日志落 /tmp 双端可见):
docker exec -d vllm-omni-qwen-image21 bash -lc 'bash /workspace/start_service.sh > /tmp/qwen_image_2_1_vllm.log 2>&1'
# 等待启动完成(含一次真实 512×512/1 步 dummy run,~1 分钟内就绪)
grep "Application startup complete" /tmp/qwen_image_2_1_vllm.log| 参数 | 值 | 原因 |
|---|---|---|
--diffusion-load-format | 必须 diffusers | default 走原生 registry,QwenImage21 不在其中 → ValueError: Model class QwenImage21Pipeline not found;diffusers 走官方为任意新模型准备的 DiffusersAdapterPipeline 黑盒包装 |
--diffusion-attention-backend | 必须 TORCH_SDPA | 默认值在 910B 无报错挂死:diffusers _native_npu 后端不可用且无日志退出,主进程空转、worker 阻塞(日志停在 "Attention backends are an experimental feature")。TORCH_SDPA 走 diffusers 原生 SDPA segments 路径 |
ASCEND_RT_VISIBLE_DEVICES | <物理卡号>(必须 export,不能用旧名) | 镜像所用 CANN 8.x 中 ASCEND_VISIBLE_DEVICES 已弃用不生效(服务会按默认枚举落卡)。用新名精确指定物理卡;核对落点看 npu-smi info 的 0000: 行与 HBM-Usage |
--tensor-parallel-size | 1 | 单卡部署:adapter 加载形态由单卡载入全量模型(~37-41G HBM)完成整条推理 |
--gpu-memory-utilization | 0.9 | 单卡全量权重 + 激活,留 VAE/后处理余量 |
选卡:共享机器部署前用
npu-smi info核对目标卡 HBM 余量 ≥ 45G(ASCEND_RT_VISIBLE_DEVICES填该卡物理号)。 启动后:首次启动会做一次真实渲染的 dummy run(512×512/1 步)再开始监听;之后首条请求即为正常延迟(910B3 实测 512/30 步 3.9s)。
容器 --net=host,API 端口即宿主机端口;启用 firewalld 并需对外提供访问时:
| 端口 | 协议 | 用途 |
|---|---|---|
| 8091 | TCP | 文生图 API(/v1/chat/completions) |
firewall-cmd --add-port=8091/tcp --permanent
firewall-cmd --reload服务启动后(dummy run 完成开始监听):
# 健康检查 & 模型列表
curl -s -o /dev/null -w "%{http_code}\n" http://<API_HOST>:8091/health # 期望 200
curl -s http://<API_HOST>:8091/v1/models原始 curl 示例(图以 base64 PNG 返回,需解出落盘;尺寸/步数/seed 经 extra_body 透传):
curl -s http://<API_HOST>:8091/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "一只柯基犬在草地上晒太阳"}],
"extra_body": {"height": 512, "width": 512, "num_inference_steps": 30, "seed": 42}
}' -o /tmp/qwen21_resp.json
python3 - <<'EOF'
import json, base64
d = json.load(open("/tmp/qwen21_resp.json"))
url = d["choices"][0]["message"]["content"][0]["image_url"]["url"] # data:image/png;base64,...
open("/tmp/qwen21_out.png", "wb").write(base64.b64decode(url.split(",", 1)[1]))
print("saved /tmp/qwen21_out.png")
EOF注意:
- 图像在
choices[0].message.content[0].image_url.url(base64 PNG 串),不是文本字段- 固定
seed可复现同构图- 服务为串行处理:并发请求按序排队,总耗时近似按请求数累加
日常运维:重启服务 = docker restart vllm-omni-qwen-image21 后重跑第三步,禁止 pkill -f 'vllm serve' / docker exec pkill(spawn 起的 worker 子进程无法用 pkill 清理,残留会占用 HBM 导致下次起服失败)。
能力边界:当前 adapter 加载形态不支持 CFG parallel / SP / 缓存加速 / 并发批处理;真实 TP 权重切分与请求批依赖模型侧原生 pipeline 支持,实现后更新本文档。