Ascend-SACT/Qwen-Image-2.1
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

Qwen-Image-2.1 在 vLLM-Omni v0.28.0 部署指导文档

本仓库交付部署物料:部署指导(本文档 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 文件,按序应用)。

版本提交记录补丁规模更新内容
v12026-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-omnitag 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 管线
diffusers0.41.0.dev0(git main 源码安装)
transformers5.17.0(pip -U 覆盖镜像内置,官方要求 ≥5.17)
torch / torch_nputorch 2.10.0+cpu + torch_npu(镜像自带,CANN 8.2.RC1 环境)
CANN8.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
NPU1× 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(含文本端)
patchifypatch_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"'
# 期望输出 5

diffusers 环境前置(重装后再打补丁才有效):官方要求 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必须 diffusersdefault 走原生 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-size1单卡部署:adapter 加载形态由单卡载入全量模型(~37-41G HBM)完成整条推理
--gpu-memory-utilization0.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 并需对外提供访问时:

端口协议用途
8091TCP文生图 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 支持,实现后更新本文档。