Z-Image-Turbo模型基于ModelArts Lite Server适配NPU推理指导

方案概览

在图像内容创作领域，随着消费者对图像质量要求的提高，图像生成的需求日益增长。然而现有图像生成模型往往需要高性能的计算资源，这使得许多创作者难以负担。Z-Image-Turbo 是通义推出的一款功能强大且高效的开源图像生成模型，拥有60 亿个参数，仅需8 次函数评估 (NFE)，即可达到甚至超越领先竞争对手的性能。通过对该模型的适配工作，有助于丰富晟腾云服务的文生图模型生态，形成差异化的模型能力解决方案。

如何在有限的计算资源下实现高效、高质量的图像生成？本文主要介绍如何在ModelArts的Lite Server环境中，使用NPU卡对Z-Image-Turbo模型进行推理适配，以解决这一问题。

资源规格要求

ModelArts Lite Server的Snt9b单机或Snt9b23单机资源。

获取软件和镜像

约束限制

• 本文档适配ModelArts 6.5.912版本，请参考表3获取配套版本的软件包和镜像，请严格遵照版本配套关系使用本文档。
• 确保容器可以访问公网。

步骤一：准备环境

1. 请参考Lite Server资源开通，购买Server资源，并确保机器已开通，密码已获取，能通过SSH登录，不同机器之间网络互通。
   

   当容器需要提供服务给多个用户，或者多个用户共享使用该容器时，应限制容器访问Openstack的管理地址（169.254.169.254），以防止容器获取宿主机的元数据。具体操作请参见禁止容器获取宿主机元数据。

2. SSH登录机器后，检查NPU设备状态。运行如下命令，返回NPU设备信息。

   npu-smi info                    # 在每个实例节点上运行此命令可以看到NPU卡状态
   npu-smi info -l | grep Total    # 在每个实例节点上运行此命令可以看到总卡数

   如出现错误，可能是机器上的NPU设备没有正常安装，或者NPU镜像被其他容器挂载。请先正常安装固件和驱动，或释放被挂载的NPU。

3. 检查docker是否安装。

   docker -v   #检查docker是否安装

   如尚未安装，运行以下命令安装docker。

   yum install -y docker-engine.aarch64 docker-engine-selinux.noarch docker-runc.aarch64

4. 配置IP转发，用于容器内的网络访问。执行以下命令查看net.ipv4.ip_forward配置项的值，如果为1，可跳过此步骤。

   sysctl -p | grep net.ipv4.ip_forward

   如果net.ipv4.ip_forward配置项的值不为1，执行以下命令配置IP转发。

   sed -i 's/net\.ipv4\.ip_forward=0/net\.ipv4\.ip_forward=1/g' /etc/sysctl.conf
   sysctl -p | grep net.ipv4.ip_forward

步骤二：获取基础镜像

建议使用官方提供的镜像部署服务。镜像地址{image_url}参见表3。

docker pull {image_url}

步骤三：启动容器镜像（Snt9b23）

1. Snt9b23启动容器镜像。启动前请先按照参数说明修改${}中的参数。

   export work_dir="自定义挂载的工作目录"
   export container_work_dir="自定义挂载到容器内的工作目录"
   export container_name="自定义容器名称"
   export image_name="镜像名称或ID"
   // 启动一个容器去运行镜像 
   docker run -itd \
       --network=host \
       --privileged \
       --device=/dev/davinci_manager \
       --device=/dev/devmm_svm \
       --device=/dev/hisi_hdc \
       --shm-size=256g \
       -v /usr/local/dcmi:/usr/local/dcmi \
       -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
       -v /var/log/npu/:/usr/slog \
       -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \
       -v ${work_dir}:${container_work_dir} \
       --name ${container_name} \
       ${image_name} \
       /bin/bash

   参数说明：

   • -v ${work_dir}:${container_work_dir}：代表需要在容器中挂载宿主机的目录。宿主机和容器使用不同的文件系统。work_dir为宿主机中工作目录，目录下可存放项目所需代码、数据等文件。container_work_dir为要挂载到的容器中的目录。为方便两个地址可以相同。
     

     • 容器不能挂载到/home/ma-user目录，此目录为ma-user用户家目录。如果容器挂载到/home/ma-user下，拉起容器时会与基础镜像冲突，导致基础镜像不可用。

     • driver及npu-smi需同时挂载至容器。
   • --name ${container_name}：容器名称，进入容器时会用到，此处可以自己定义一个容器名称。
   • ${image_name}：容器镜像的名称。
2. Snt9b23需要使用root权限进入容器中。

   docker exec -itu root ${container_name} bash

步骤三：启动容器镜像（Snt9b）

1. Snt9b启动容器镜像。启动前请先按照参数说明修改${}中的参数。

   export work_dir="自定义挂载的工作目录"
   export container_work_dir="自定义挂载到容器内的工作目录"
   export container_name="自定义容器名称"
   export image_name="镜像名称或ID"
   // 启动一个容器去运行镜像 
   docker run -itd \
       --network=host \
       --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 \
       --shm-size=256g \
       -v /usr/local/dcmi:/usr/local/dcmi \
       -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
       -v /var/log/npu/:/usr/slog \
       -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi \
       -v ${work_dir}:${container_work_dir} \
       --name ${container_name} \
       ${image_name} \
       /bin/bash

   参数说明：

   • -v ${work_dir}:${container_work_dir}：代表需要在容器中挂载宿主机的目录。宿主机和容器使用不同的文件系统。work_dir为宿主机中工作目录，目录下可存放项目所需代码、数据等文件。container_work_dir为要挂载到的容器中的目录。为方便两个地址可以相同。
     

     • 容器不能挂载到/home/ma-user目录，此目录为ma-user用户家目录。如果容器挂载到/home/ma-user下，拉起容器时会与基础镜像冲突，导致基础镜像不可用。

     • driver及npu-smi需同时挂载至容器。
   • --name ${container_name}：容器名称，进入容器时会用到，此处可以自己定义一个容器名称。
   • ${image_name}：容器镜像的名称。
   • --device=/dev/davinci0 ：挂载对应卡到容器，当需要挂载多卡，请依次添加多项该配置。
2. Snt9b通过容器名称进入容器中。默认使用ma-user用户，后续所有操作步骤都在ma-user用户下执行。

   docker exec -it ${container_name} bash

步骤四：安装依赖和软件包

1. 将获取到的插件代码包AscendCloud-AIGC-xxx.zip文件上传到容器的/home/ma-user/目录下，并解压。

   cd /home/ma-user/
   unzip AscendCloud-AIGC-*.zip -d ./AscendCloud

2. 拉取代码，在容器的/home/ma-user/目录下进行操作。

   git config --global http.sslVerify false
   git clone https://github.com/huggingface/diffusers.git
   cd diffusers
   git checkout v0.36.0
   git apply /home/ma-user/AscendCloud/aigc_inference/torch_npu/diffusers/0.36.0/Z-Image-Turbo/Z-Image-Turbo-NPU-Transfer.patch
   pip install -e .
   pip install "peft==0.18.0"

   应用patch之后出现下列提示属于正常现象，仅为格式问题无需处理。

   

3. 下载模型权重。如下图所示，下载Z-Image-Turbo权重下所有文件，保存在Z-Image-Turbo目录下，并上传Z-Image-Turbo目录到容器/home/ma-user路径下。
   图1 下载Z-Image-Turbo模型权重
   

步骤五：Z-Image-Turbo推理

cd /home/ma-user/AscendCloud/aigc_inference/torch_npu/diffusers/0.36.0/examples
# 查看显卡占用状态
npu-smi info
# 将单张空闲显卡指定为默认推理设备
export device_index=单张空闲显卡索引
# 指定提示词文件夹
export test_group=提示词文件夹
# 指定提示词文件名
export test_name=提示词文件名
# 运行推理脚本
python z-image-turbo_example.py --model_path /home/ma-user/Z-Image-Turbo --device_index=${device_index} --test_group=${test_group} --test_name=${test_name}

参数解释如下：

• model_path：模型权重路径
• device_index：推理显卡索引
• test_group：提示词文件夹。可选值包括：ASCEND_AIGC、Z-Image
• test_name：提示词jsonl文件。当test_group为ASCEND_AIGC时，请将test_name指定为normal；当test_group为Z-Image时，test_name可选值包括：bilingual、normal

若希望指定提示词、生成图片尺寸、文件名，请在以下目录新建提示词文件夹和提示词jsonl文件。

/home/ma-user/AscendCloud/aigc_inference/torch_npu/diffusers/0.36.0/Z-Image-Turbo/prompts

文件结构请参考下图：

jsonl文件内容格式可参考：

/home/ma-user/AscendCloud/aigc_inference/torch_npu/diffusers/0.36.0/Z-Image-Turbo/prompts/ASCEND_AIGC/normal.jsonl

此处展示前三行内容：

{"prompt": "她有着飘逸的黑色长发，略带蓝色调，身着带有未来感细节的时尚服装，以大胆的蓝白色调为主。她自信的姿态和时尚的着装让她格外引人注目。男孩：他有着棕色的短发，身着活力四射的街头风格服装，色彩大胆，设计前卫。他热情洋溢的姿态和酷炫的气质让他脱颖而出。色彩：整体色调鲜明，大胆的蓝色、白色和点缀的绿色交相辉映，背景明亮欢快。", "width": 1728, "height": 2304, "filename": "男生女生.jpeg"}
{"prompt": "一个男孩坐在椅子上，手里拿着手机，穿着潮牌服装，羽绒服，墨镜，戴着帽子，背景是黄绿色，黑色的头发，座位周围灯光明亮，气泡漂浮，周围摆满了玩具，闪闪发光，他独自一人，坐在背景中，天空呈棋盘格状渐变。镜头周围是各种彩色彩车：蓝色笑脸、粉色“促销”标志、黑白胶片、男孩、贴纸、鞋子、耳机、硬币和购物车。", "width": 2848, "height": 1600, "filename": "羽绒服男孩.jpeg"}
{"prompt": "财神爷，骑着电动车，送年货，风韵十足，灯笼，爆竹，春节，热闹非凡。", "width": 1728, "height": 2304, "filename": "财神爷.jpeg"}

参数解释如下：

• prompt：提示词。长度不超过40,960 Tokens（大约相当于 2-3 万个汉字或 3-4 万个英文单词）。
• width：生成图片宽度。不超过3328，需要能被16整除。
• height：生成图片高度。不超过3328，需要能被16整除。
• filename：生成图片的基础文件名。建议默认设置为"*.jpeg"、"*.png"

请将一张图片需要的上述信息以dict的形式规整在一行之中，不要发生跨行现象，因为jsonl以行为单位进行信息读取，同时jsonl文件中尽量不要出现空行。

假设创建的提示词文件夹和提示词文件如下图所示：

则将上述命令填充为：

cd /home/ma-user/AscendCloud/aigc_inference/torch_npu/diffusers/0.36.0/examples
# 查看显卡占用状态
npu-smi info
# 将单张空闲显卡指定为默认推理设备
export device_index=单张空闲显卡索引
# 指定提示词文件夹
export test_group=TEST
# 指定提示词文件名
export test_name=test
# 运行推理脚本
python z-image-turbo_example.py --model_path /home/ma-user/Z-Image-Turbo --device_index=${device_index} --test_group=${test_group} --test_name=${test_name}

步骤六：查看Z-Image-Turbo推理结果

图片生成结果与性能统计结果会被分别保存在/home/ma-user/AscendCloud/aigc_inference/torch_npu/diffusers/0.36.0/examples的images和reports目录下，以test_group=ASCEND_AIGC，test_name=normal为例：

其中，以提示词内容

{"prompt": "她有着飘逸的黑色长发，略带蓝色调，身着带有未来感细节的时尚服装，以大胆的蓝白色调为主。她自信的姿态和时尚的着装让她格外引人注目。男孩：他有着棕色的短发，身着活力四射的街头风格服装，色彩大胆，设计前卫。他热情洋溢的姿态和酷炫的气质让他脱颖而出。色彩：整体色调鲜明，大胆的蓝色、白色和点缀的绿色交相辉映，背景明亮欢快。", "width": 1728, "height": 2304, "filename": "男生女生.jpeg"}

为例，生成的图片和性能报告内容如下：

{"model": "Z-Image-Turbo", "filename": "男生女生_seed42.jpeg", "width": 1728, "height": 2304, "prompt": "她有着飘逸的黑色长发，略带蓝色调，身着带有未来感细节的时尚服装，以大胆的蓝白色调为主。她自信的姿态和时尚的着装让她格外引人注目。男孩：他有着棕色的短发，身着活力四射的街头风格服装，色彩大胆，设计前卫。他热情洋溢的姿态和酷炫的气质让他脱颖而出。色彩：整体色调鲜明，大胆的蓝色、白色和点缀的绿色交相辉映，背景明亮欢快。", "seed": 42, "status": "success", "avg_inference_time": 25.8463, "max_memory_gb": 28.3187, "error_msg": ""}

其中avg_inference_time为推理时间（单位：秒），max_memory_gb为最大显存占用（单位：GB），若出现错误信息会记载在error_msg对应的项中，常见的错误包括“OOM”（超出显存上限）