# Z-Image-Turbo模型基于ModelArts轻量算力节点适配NPU推理指导（6.5.912） #### 方案概览 在图像内容创作领域，随着消费者对图像质量要求的提高，图像生成的需求日益增长。然而现有图像生成模型往往需要高性能的计算资源，这使得许多创作者难以负担。Z-Image-Turbo 是一款功能强大且高效的开源图像生成模型，拥有**60 亿个** 参数，仅需**8 次**函数评估 (NFE)，即可达到甚至超越领先竞争对手的性能，主打轻量、超快、中文友好。 通过对该模型的适配工作，有助于丰富昇腾云服务的文生图模型生态，形成差异化的模型能力解决方案。如何在有限的计算资源下实现高效、高质量的图像生成？本文主要介绍如何在ModelArts的轻量算力节点环境中，使用NPU卡对Z-Image-Turbo模型进行推理适配，以解决这一问题。 #### 资源规格要求 ModelArts 轻量算力节点的Snt9b单机或Snt9b23单机资源。 表1Ascend Snt9B 环境要求 | 名称 | 版本 | |:---|:---| | driver | 24.1.0.6 | | PyTorch | pytorch_2.5.1 | 表2Ascend Snt9B23 环境要求 | 名称 | 版本 | |:---|:---| | driver | 25.2.1 | | PyTorch | pytorch_2.5.1 | #### 获取软件和镜像 表3获取镜像 | 分类 | 名称 | 获取路径 | |:---|:---|:---| | 插件代码包 | AscendCloud-AIGC-6.5.912-xxx.zip 文件名中的xxx表示具体的时间戳，以包名发布的实际时间为准。 | 获取路径：[Support-E](https://support.huawei.com/enterprise/zh/cloud-computing/modelarts-pid-23404305/software/)，在此路径中查找下载ModelArts 6.5.912.3版本。 说明： 如果上述软件获取路径打开后未显示相应的软件信息，说明您没有下载权限，请联系您所在企业的华为方技术支持下载获取。 | | 基础镜像 | Snt9b：西南-贵阳一： swr.cn-southwest-2.myhuaweicloud.com/atelier/pytorch_ascend:pytorch_2.5.1-cann_8.2.rc2-py_3.11-hce_2.0.2509-aarch64-snt9b-20251105194139-a70c13c Snt9b23：西南-贵阳一： swr.cn-southwest-2.myhuaweicloud.com/atelier/pytorch_ascend:pytorch_2.5.1-cann_8.2.rc2-py_3.11-hce_2.0.2509-aarch64-snt9b23-20251106111344-87d9583 | 从SWR拉取。 | #### 约束限制 - 本文档适配ModelArts 6.5.912版本，请参考[表3]获取配套版本的软件包和镜像，请严格遵照版本配套关系使用本文档。 - 确保容器可以访问公网。 #### 步骤一：准备环境 1. 请参考[轻量算力节点资源开通](https://support.huaweicloud.com/resmgmt-modelarts/usermanual-server-0005.html)，购买轻量算力节点资源，并确保机器已开通，密码已获取，能通过SSH登录，不同机器之间网络互通。 ![](https://support.huaweicloud.com/bestpractice-modelarts/public_sys-resources/note_3.0-zh-cn.png) 当容器需要提供服务给多个用户，或者多个用户共享使用该容器时，应限制容器访问Openstack的管理地址（169.254.169.254），以防止容器获取宿主机的元数据。具体操作请参见[禁止容器获取宿主机元数据](https://support.huaweicloud.com/bestpractice-cce/cce_bestpractice_0318.html#section4)。 2. SSH登录机器后，检查NPU设备状态。运行如下命令，返回NPU设备信息。 ``` npu-smi info # 在每个实例节点上运行此命令可以看到NPU卡状态 npu-smi info -l | grep Total # 在每个实例节点上运行此命令可以看到总卡数 ``` 如出现错误，可能是机器上的NPU设备没有正常安装，或者NPU镜像被其他容器挂载。请先正常[安装驱动和固件](https://support.huaweicloud.com/resmgmt-modelarts/usermanual-server-0011.html#section4)，或释放被挂载的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为要挂载到的容器中的目录。为方便两个地址可以相同。 ![](https://support.huaweicloud.com/bestpractice-modelarts/public_sys-resources/note_3.0-zh-cn.png) - 容器不能挂载到/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为要挂载到的容器中的目录。为方便两个地址可以相同。 ![](https://support.huaweicloud.com/bestpractice-modelarts/public_sys-resources/note_3.0-zh-cn.png) - 容器不能挂载到/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之后出现下列提示属于正常现象，仅为格式问题无需处理。 ![](https://support.huaweicloud.com/bestpractice-modelarts/figure/zh-cn_image_0000002530301265.png "点击放大") 3. [下载模型权重](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo/tree/main)。如下图所示，下载Z-Image-Turbo权重下所有文件，保存在Z-Image-Turbo目录下，并上传Z-Image-Turbo目录到容器/home/ma-user路径下。 图1下载Z-Image-Turbo模型权重 ![](https://support.huaweicloud.com/bestpractice-modelarts/figure/zh-cn_image_0000002498506030.png "点击放大") #### 步骤五：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 ``` 文件结构请参考下图： ![](https://support.huaweicloud.com/bestpractice-modelarts/figure/zh-cn_image_0000002498358486.png "点击放大") 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文件中尽量不要出现空行。 假设创建的提示词文件夹和提示词文件如下图所示： ![](https://support.huaweicloud.com/bestpractice-modelarts/figure/zh-cn_image_0000002498379130.png "点击放大") 则将上述命令填充为： ``` 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为例： ![](https://support.huaweicloud.com/bestpractice-modelarts/figure/zh-cn_image_0000002498546700.png "点击放大") 其中，以提示词内容 ``` {"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"（超出显存上限） ![](https://support.huaweicloud.com/bestpractice-modelarts/figure/zh-cn_image_0000002530138527.png "点击放大")