模型推理指导

一、模型简介

Z-Image 是 ⚡️- Image 系列的基础模型，专为高质量、强生成多样性、广泛的风格覆盖能力以及精准的提示词遵循而设计。 Z-Image-Turbo 以速度为核心，而 Z-Image 则是一个完整容量、未经蒸馏的 Transformer 模型，旨在为需要最高级别创作自由度的创作者、研究人员和开发者提供坚实基础。

🌟核心特性

**未经蒸馏的基础模型：**作为非蒸馏的基础模型，Z-Image 保留了完整的训练信号。它支持完整的无分类器引导（Classifier-Free Guidance, CFG），为复杂提示工程和专业工作流提供所需的精确控制。
**美学多样性：**Z-Image 掌握了极其丰富的视觉语言——从超写实摄影、电影级数字艺术，到精细的动漫和风格化插画。它是需要丰富、多维表达场景的理想引擎。
**增强的输出多样性：**专为探索而生，Z-Image 在不同随机种子下能显著提升构图、人脸身份和光照等方面的多样性，确保多人场景始终保持独特且生动。
**面向开发友好：**社区理想的起点。其非蒸馏特性使其成为 LoRA 微调、结构条件控制（如 ControlNet）和语义条件控制的良好基础。
**强大的负面控制能力：**对负面提示具有高保真响应，使用户能够可靠地抑制伪影并调整构图。

🆚 Z-Image 与 Z-Image-Turbo 对比

方面	Z-Image	Z-Image-Turbo
CFG	✅	❌
步数	50	9
可微调性	✅	❌
负面提示	✅	❌
多样性	高	低
视觉质量	高	极高
强化学习（RL）	❌	✅

二、环境准备

表 1 版本配套表

配套	版本	环境准备指导
Python	3.11.10	-
torch	2.8.0	-

2.1 获取安装包

支持设备：Atlas 800I A2
支持卡数：支持的卡数为1
环境准备指导

2.2 CANN安装

推荐使用CANN 8.5.0版本（latest）以获取最优性能：CANN 8.5.0

# 需要以root用户执行如下命令
# 增加软件包可执行权限，以下以CANN 8.5.0，arm64架构，A2服务器910B芯片为例。
chmod +x ./Ascend-cann-toolkit_8.5.0_linux-aarch64.run
chmod +x ./Ascend-cann-910b-ops_8.5.0_linux-aarch64.run
# 校验软件包安装文件的一致性和完整性
./Ascend-cann-toolkit_8.5.0_linux-aarch64.run --check
./Ascend-cann-910b-ops_8.5.0_linux-aarch64.run --check
# 安装
./Ascend-cann-toolkit_8.5.0_linux-aarch64.run --install
./Ascend-cann-910b-ops_8.5.0_linux-aarch64.run --install
# 设置环境变量
source /usr/local/Ascend/ascend-toolkit/set_env.sh

2.3 torch_npu安装

2.3.1 安装pytorch框架版本2.8.0

下载软件包

wget https://download.pytorch.org/whl/cpu/torch-2.8.0%2Bcpu-cp311-cp311-manylinux_2_28_aarch64.whl

安装命令

pip3 install torch-2.8.0+cpu-cp311-cp311-manylinux_2_28_aarch64.whl

2.3.2 安装torch_npu框架版本2.8.0

下载软件包

wget https://gitcode.com/Ascend/pytorch/releases/download/v7.2.0-pytorch2.8.0/torch_npu-2.8.0-cp311-cp311-manylinux_2_28_aarch64.whl

安装命令

pip3 install torch_npu-2.8.0-cp311-cp311-manylinux_2_28_aarch64.whl

2.3.3 安装后验证

执行以下命令可检查PyTorch框架和torch_npu插件是否已成功安装。

python3 -c "import torch;import torch_npu; a = torch.randn(3, 4).npu(); print(a + a);"

输出如下类似信息说明安装成功。

tensor([[-0.6066,  6.3385,  0.0379,  3.3356],
        [ 2.9243,  3.3134, -1.5465,  0.1916],
        [-2.1807,  0.2008, -1.1431,  2.1523]], device='npu:0')

2.4 安装gcc、g++

# 若环境镜像中没有gcc、g++，请用户自行安装
yum install gcc
yum install g++

# 导入头文件路径
export CPLUS_INCLUDE_PATH=/usr/include/c++/12/:/usr/include/c++/12/aarch64-openEuler-linux/:$CPLUS_INCLUDE_PATH

2.5 下载本仓库

git clone https://modelers.cn/MindIE/Z-Image.git

2.6 安装所需依赖

2.6.1 安装最新版本的diffusers

pip install git+https://github.com/huggingface/diffusers

2.6.2 安装其他所需依赖

pip install -r requirements.txt

三、模型权重

3.1 权重下载

Z-Image权重下载地址

3.2 配置文件说明

修改权重配置文件：

vi ${model_path}/model_index.json

做如下修改：

{
    "_class_name": "ZImagePipeline",
    "_diffusers_version": "0.36.0.dev0",
    "scheduler": [
        "diffusers",
        "FlowMatchEulerDiscreteScheduler"
    ],
    "text_encoder": [
        "transformers",
        "Qwen3Model"
    ],
    "tokenizer": [
        "transformers",
        "Qwen2Tokenizer"
    ],
    "transformer": [
        "zimage",
        "ZImageTransformer2DModel"
    ],
    "vae": [
        "diffusers",
        "AutoencoderKL"
    ]
}

四、模型推理

4.1 Atlas-800I-A2-64g单卡推理性能测试

设置权重路径

export model_path="your local Z-Image model path"

执行命令：

# 在环境中导入以下环境变量提高推理性能
export CPU_AFFINITY_CONF=2
export TASK_QUEUE_ENABLE=2

python inference.py \
       --model_path ${model_path} \
       --output_path "./output" \
       --device_id 0 \
       --prompt "两名年轻亚裔女性紧密站在一起，背景为朴素的灰色纹理墙面，可能是室内地毯地面。左侧女性留着长卷发，身穿藏青色毛衣，左袖有奶油色褶皱装饰，内搭白色立领衬衫，下身白色裤子；佩戴小巧金色耳钉，双臂交叉于背后。右侧女性留直肩长发，身穿奶油色卫衣，胸前印有“Tun the tables”字样，下方为“New ideas”，搭配白色裤子；佩戴银色小环耳环，双臂交叉于胸前。两人均面带微笑直视镜头。照片，自然光照明，柔和阴影，以藏青、奶油白为主的中性色调，休闲时尚摄影，中等景深，面部和上半身对焦清晰，姿态放松，表情友好，室内环境，地毯地面，纯色背景。" \
       --negative_prompt "" \
       --width 720 \
       --height 1280 \
       --infer_steps 50 \
       --guidance_scale 4 \
       --seed 42

参数说明：

model_path: Z-Image本地模型权重路径，必须填写的参数
output_path: 保存图像路径，默认当前文件夹下的output文件夹
device_id: 推理设备ID，默认值设置为0
prompt: 用于图像生成的文字描述提示
negative_prompt：用于图像生成的负向文字描述提示，可选，若提供则可以使模型生成的图片更加精确
width: 图像生成的宽度，默认720
height: 图像生成的高度，默认1280
infer_steps: Z-Image图像推理步数，默认值为50
seed: 设置随机种子，默认值为42
guidance_scale: 引导系数，用于控制图像生成的质量，默认值为4
cfg_normalization：是否开启CFG Normalization，开启后可提升文生图扩散模型生成的稳定性，尤其在高guidance_scale下能有效防止数值溢出和图像结构崩溃

五、推理结果参考

Z-Image性能数据

硬件形态	CPU规格	NPU算力	Batch Size	分辨率	迭代次数	性能	采样器	备注
Atlas 800I A2(8×64G)	48核(arm)	313T	1	1024*1024	50	31.4s	FlowMatchEulerDiscreteScheduler	单卡运行

声明

本代码仓提到的数据集和模型仅作为示例，这些数据集和模型仅供您用于非商业目的，如您使用这些数据集和模型来完成示例，请您特别注意应遵守对应数据集和模型的License，如您因使用数据集或模型而产生侵权纠纷，华为不承担任何责任。
如您在使用本代码仓的过程中，发现任何问题（包括但不限于功能问题、合规问题），请在本代码仓提交issue，我们将及时审视并解答。

模型推理指导

一、模型简介

🌟核心特性

**未经蒸馏的基础模型：**作为非蒸馏的基础模型，Z-Image 保留了完整的训练信号。它支持完整的无分类器引导（Classifier-Free Guidance, CFG），为复杂提示工程和专业工作流提供所需的精确控制。
**美学多样性：**Z-Image 掌握了极其丰富的视觉语言——从超写实摄影、电影级数字艺术，到精细的动漫和风格化插画。它是需要丰富、多维表达场景的理想引擎。
**增强的输出多样性：**专为探索而生，Z-Image 在不同随机种子下能显著提升构图、人脸身份和光照等方面的多样性，确保多人场景始终保持独特且生动。
**面向开发友好：**社区理想的起点。其非蒸馏特性使其成为 LoRA 微调、结构条件控制（如 ControlNet）和语义条件控制的良好基础。
**强大的负面控制能力：**对负面提示具有高保真响应，使用户能够可靠地抑制伪影并调整构图。

🆚 Z-Image 与 Z-Image-Turbo 对比

方面	Z-Image	Z-Image-Turbo
CFG	✅	❌
步数	50	9
可微调性	✅	❌
负面提示	✅	❌
多样性	高	低
视觉质量	高	极高
强化学习（RL）	❌	✅

二、环境准备

表 1 版本配套表

配套	版本	环境准备指导
Python	3.11.10	-
torch	2.8.0	-

2.1 获取安装包

支持设备：Atlas 800I A2
支持卡数：支持的卡数为1
环境准备指导

2.2 CANN安装

推荐使用CANN 8.5.0版本（latest）以获取最优性能：CANN 8.5.0

# 需要以root用户执行如下命令
# 增加软件包可执行权限，以下以CANN 8.5.0，arm64架构，A2服务器910B芯片为例。
chmod +x ./Ascend-cann-toolkit_8.5.0_linux-aarch64.run
chmod +x ./Ascend-cann-910b-ops_8.5.0_linux-aarch64.run
# 校验软件包安装文件的一致性和完整性
./Ascend-cann-toolkit_8.5.0_linux-aarch64.run --check
./Ascend-cann-910b-ops_8.5.0_linux-aarch64.run --check
# 安装
./Ascend-cann-toolkit_8.5.0_linux-aarch64.run --install
./Ascend-cann-910b-ops_8.5.0_linux-aarch64.run --install
# 设置环境变量
source /usr/local/Ascend/ascend-toolkit/set_env.sh

2.3 torch_npu安装

2.3.1 安装pytorch框架版本2.8.0

下载软件包

wget https://download.pytorch.org/whl/cpu/torch-2.8.0%2Bcpu-cp311-cp311-manylinux_2_28_aarch64.whl

安装命令

pip3 install torch-2.8.0+cpu-cp311-cp311-manylinux_2_28_aarch64.whl

2.3.2 安装torch_npu框架版本2.8.0

下载软件包

wget https://gitcode.com/Ascend/pytorch/releases/download/v7.2.0-pytorch2.8.0/torch_npu-2.8.0-cp311-cp311-manylinux_2_28_aarch64.whl

安装命令

pip3 install torch_npu-2.8.0-cp311-cp311-manylinux_2_28_aarch64.whl

2.3.3 安装后验证

执行以下命令可检查PyTorch框架和torch_npu插件是否已成功安装。

python3 -c "import torch;import torch_npu; a = torch.randn(3, 4).npu(); print(a + a);"

输出如下类似信息说明安装成功。

tensor([[-0.6066,  6.3385,  0.0379,  3.3356],
        [ 2.9243,  3.3134, -1.5465,  0.1916],
        [-2.1807,  0.2008, -1.1431,  2.1523]], device='npu:0')

2.4 安装gcc、g++

# 若环境镜像中没有gcc、g++，请用户自行安装
yum install gcc
yum install g++

# 导入头文件路径
export CPLUS_INCLUDE_PATH=/usr/include/c++/12/:/usr/include/c++/12/aarch64-openEuler-linux/:$CPLUS_INCLUDE_PATH

2.5 下载本仓库

git clone https://modelers.cn/MindIE/Z-Image.git

2.6 安装所需依赖

2.6.1 安装最新版本的diffusers

pip install git+https://github.com/huggingface/diffusers

2.6.2 安装其他所需依赖

pip install -r requirements.txt

三、模型权重

3.1 权重下载

Z-Image权重下载地址

3.2 配置文件说明

修改权重配置文件：

vi ${model_path}/model_index.json

做如下修改：

{
    "_class_name": "ZImagePipeline",
    "_diffusers_version": "0.36.0.dev0",
    "scheduler": [
        "diffusers",
        "FlowMatchEulerDiscreteScheduler"
    ],
    "text_encoder": [
        "transformers",
        "Qwen3Model"
    ],
    "tokenizer": [
        "transformers",
        "Qwen2Tokenizer"
    ],
    "transformer": [
        "zimage",
        "ZImageTransformer2DModel"
    ],
    "vae": [
        "diffusers",
        "AutoencoderKL"
    ]
}

四、模型推理

4.1 Atlas-800I-A2-64g单卡推理性能测试

设置权重路径

export model_path="your local Z-Image model path"

执行命令：

# 在环境中导入以下环境变量提高推理性能
export CPU_AFFINITY_CONF=2
export TASK_QUEUE_ENABLE=2

python inference.py \
       --model_path ${model_path} \
       --output_path "./output" \
       --device_id 0 \
       --prompt "两名年轻亚裔女性紧密站在一起，背景为朴素的灰色纹理墙面，可能是室内地毯地面。左侧女性留着长卷发，身穿藏青色毛衣，左袖有奶油色褶皱装饰，内搭白色立领衬衫，下身白色裤子；佩戴小巧金色耳钉，双臂交叉于背后。右侧女性留直肩长发，身穿奶油色卫衣，胸前印有“Tun the tables”字样，下方为“New ideas”，搭配白色裤子；佩戴银色小环耳环，双臂交叉于胸前。两人均面带微笑直视镜头。照片，自然光照明，柔和阴影，以藏青、奶油白为主的中性色调，休闲时尚摄影，中等景深，面部和上半身对焦清晰，姿态放松，表情友好，室内环境，地毯地面，纯色背景。" \
       --negative_prompt "" \
       --width 720 \
       --height 1280 \
       --infer_steps 50 \
       --guidance_scale 4 \
       --seed 42

参数说明：

model_path: Z-Image本地模型权重路径，必须填写的参数
output_path: 保存图像路径，默认当前文件夹下的output文件夹
device_id: 推理设备ID，默认值设置为0
prompt: 用于图像生成的文字描述提示
negative_prompt：用于图像生成的负向文字描述提示，可选，若提供则可以使模型生成的图片更加精确
width: 图像生成的宽度，默认720
height: 图像生成的高度，默认1280
infer_steps: Z-Image图像推理步数，默认值为50
seed: 设置随机种子，默认值为42
guidance_scale: 引导系数，用于控制图像生成的质量，默认值为4
cfg_normalization：是否开启CFG Normalization，开启后可提升文生图扩散模型生成的稳定性，尤其在高guidance_scale下能有效防止数值溢出和图像结构崩溃

五、推理结果参考

Z-Image性能数据

硬件形态	CPU规格	NPU算力	Batch Size	分辨率	迭代次数	性能	采样器	备注
Atlas 800I A2(8×64G)	48核(arm)	313T	1	1024*1024	50	31.4s	FlowMatchEulerDiscreteScheduler	单卡运行

声明

本代码仓提到的数据集和模型仅作为示例，这些数据集和模型仅供您用于非商业目的，如您使用这些数据集和模型来完成示例，请您特别注意应遵守对应数据集和模型的License，如您因使用数据集或模型而产生侵权纠纷，华为不承担任何责任。
如您在使用本代码仓的过程中，发现任何问题（包括但不限于功能问题、合规问题），请在本代码仓提交issue，我们将及时审视并解答。

模型推理指导

一、模型简介

二、环境准备

2.1 获取安装包

2.2 CANN安装

2.3 torch_npu安装

2.3.1 安装pytorch框架 版本2.8.0

2.3.2 安装torch_npu框架 版本2.8.0

2.3.3 安装后验证

2.4 安装gcc、g++

2.5 下载本仓库

2.6 安装所需依赖

2.6.1 安装最新版本的diffusers

2.6.2 安装其他所需依赖

三、模型权重

3.1 权重下载

3.2 配置文件说明

四、模型推理

4.1 Atlas-800I-A2-64g单卡推理性能测试

五、推理结果参考

声明

模型推理指导

一、模型简介

二、环境准备

2.1 获取安装包

2.2 CANN安装

2.3 torch_npu安装

2.3.1 安装pytorch框架 版本2.8.0

2.3.2 安装torch_npu框架 版本2.8.0

2.3.3 安装后验证

2.4 安装gcc、g++

2.5 下载本仓库

2.6 安装所需依赖

2.6.1 安装最新版本的diffusers

2.6.2 安装其他所需依赖

三、模型权重

3.1 权重下载

3.2 配置文件说明

四、模型推理

4.1 Atlas-800I-A2-64g单卡推理性能测试

五、推理结果参考

声明

2.3.1 安装pytorch框架版本2.8.0

2.3.2 安装torch_npu框架版本2.8.0

2.3.1 安装pytorch框架版本2.8.0

2.3.2 安装torch_npu框架版本2.8.0