Z-Image-Turbo WebUI 本地部署指南：环境配置与启动流程

安装项目依赖库

pip install -r requirements.txt

常见关键依赖：

• diffsynth-studio>=0.3.0
• gradio==3.50.2
• transformers
• safetensors
• accelerate

步骤二：下载预训练模型权重

Z-Image-Turbo 使用 ModelScope 平台托管的大模型文件，需通过官方 SDK 下载。

1. 安装 ModelScope 客户端

pip install modelscope

2. 登录认证（可选，部分模型公开）

# 若需要 token，请前往 https://modelscope.cn 获取
modelscope login

3. 下载核心模型

from modelscope.pipelines import pipeline
from modelscope.utils.constant import Tasks

# 自动触发模型下载至 ~/.cache/modelscope/hub/
pipe = pipeline(Tasks.text_to_image_synthesis, 'Tongyi-MAI/Z-Image-Turbo')

首次运行会自动下载以下组件：

• 主模型权重：pytorch_model.safetensors (~7.8GB)
• 分词器：tokenizer/
• 配置文件：config.json, generation_config.json

模型默认缓存路径：~/.cache/modelscope/hub/Tongyi-MAI/Z-Image-Turbo

步骤三：启动 WebUI 服务

方式一：使用一键启动脚本（推荐新手）

bash scripts/start_app.sh

该脚本内部执行逻辑如下：

#!/bin/bash
source /opt/miniconda3/etc/profile.d/conda.sh
conda activate torch28
export PYTHONPATH=./
python -m app.main --host 0.0.0.0 --port 7860

方式二：手动调试模式启动

适用于排查错误或自定义参数：

conda activate torch28
python -m app.main \
  --host 0.0.0.0 \
  --port 7860 \
  --device cuda:0 \
  --enable-xformers \
  --precision float16

启动参数说明

成功启动标志

当终端出现以下日志时，表示服务已就绪：

==================================================
Z-Image-Turbo WebUI 启动中...
==================================================
[INFO] 加载模型中：Tongyi-MAI/Z-Image-Turbo
[INFO] 使用设备：CUDA:0 (NVIDIA A100)
[INFO] 模型加载成功！耗时 186.4s
[INFO] 启动服务器：0.0.0.0:7860
👉 请访问：http://localhost:7860

首次加载模型约需 2-4 分钟（取决于磁盘 IO 速度），后续重启可缩短至 10 秒内。

浏览器访问与界面操作

打开浏览器，输入：

http://<你的服务器 IP>:7860

例如本地测试：

http://localhost:7860

你将看到主界面。

核心功能详解

图像生成（主界面）

输入参数解析

快速预设按钮使用技巧

点击即可一键设置常用比例：

• 1024×1024：标准方形图（推荐）
• 横版 16:9：适合风景、壁纸
• 竖版 9:16：适合人像、社交媒体头像

高级设置页

此页面展示系统运行状态，包含：

• 模型信息：当前加载的模型名称、路径、参数量
• 设备信息：GPU 型号、显存占用、CUDA 版本
• PyTorch 版本：确认是否启用 CUDA 加速

实用技巧：若发现 GPU 未被识别，请检查 nvidia-smi 输出及 PyTorch 安装是否正确。

关于页面

查看项目版权、开发者信息与更新日志。

性能调优

批量生成优化策略

修改 app/main.py 中的默认参数，支持一次生成多张图像：

# 在 generate 函数中调整 num_images
output_paths, gen_time, metadata = generator.generate(
    prompt=prompt,
    negative_prompt=negative_prompt,
    width=1024,
    height=1024,
    num_inference_steps=40,
    seed=-1,
    num_images=4,  # 一次性生成 4 张
    cfg_scale=7.5
)

显存警告：生成 4 张 1024×1024 图像需至少 14GB 显存。

Python API 集成示例

可用于自动化任务或与其他系统对接：

# api_example.py
from app.core.generator import get_generator

def batch_generate(prompts):
    generator = get_generator()
    results = []
    for prompt in prompts:
        try:
            paths, time_cost, meta = generator.generate(
                prompt=prompt,
                negative_prompt="low quality, blurry",
                width=1024,
                height=1024,
                num_inference_steps=40,
                num_images=1,
                seed=-1
            )
            results.append({
                "prompt": prompt,
                "output": paths[0],
                "time": f"{time_cost:.2f}s"
            })
        except Exception as e:
            results.append({"error": str(e)})
    return results

# 使用示例
prompts = [
    "樱花树下的少女，动漫风格",
    "未来城市夜景，赛博朋克，霓虹灯",
    "雪山湖泊，清晨薄雾，摄影风格"
]
results = batch_generate(prompts)
for r in results:
    print(r)

运行命令：

python api_example.py

故障排查

CUDA out of memory

现象：生成时报错 RuntimeError: CUDA out of memory

解决方法：

1. 降低图像尺寸至 768×768
2. 减少 num_images=1
3. 使用 --precision float16 启动
4. 添加 --enable-xformers 优化显存

python -m app.main --precision float16 --enable-xformers

WebUI 无法访问（Connection Refused）

排查步骤：

1. 检查服务是否正在运行：ps aux | grep python
2. 查看 7860 端口占用情况：lsof -ti:7860
3. 重启服务并观察日志：bash scripts/start_app.sh > webui.log 2>&1 & tail -f webui.log
4. 防火墙放行端口（云服务器）：sudo ufw allow 7860

模型加载缓慢或失败

可能原因：

• 网络连接不稳定导致下载中断
• .cache 目录权限不足
• 磁盘空间不足

解决方案：

1. 手动下载模型并放置指定目录：

   mkdir -p ~/.cache/modelscope/hub/Tongyi-MAI/Z-Image-Turbo
   # 将 modelscope 下载的文件复制至此
   

2. 设置缓存目录：

   export MODELSCOPE_CACHE=/your/large/disk/modelscope_cache
   

输出管理

所有生成图像自动保存在：

./outputs/

命名格式：outputs_YYYYMMDDHHMMSS.png

例如：

outputs_20260105143025.png

可通过脚本定期归档：

# daily_backup.sh
DATE=$(date +%Y%m%d)
mkdir -p backups/$DATE
cp outputs/*.png backups/$DATE/

进阶建议

推荐部署架构

[用户浏览器]
      ↓
HTTPS (Nginx)
      ↓
[Gradio WebUI]
      ↓
[GPU 服务器 · Docker 容器]
      ↓
[ModelScope 模型缓存 · SSD 存储]

安全增强建议

1. 反向代理+Nginx：

   nginx location / {
       proxy_pass http://127.0.0.1:7860;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
   }
   

2. 添加身份验证（修改 app/main.py）：

   demo.launch(auth=("admin", "your_password"), ...)
   

3. 限制访问 IP（企业内网场景）：

   --host 192.168.1.100  # 仅绑定内网 IP
   

部署检查清单

已完成事项核对表：

资源链接

• 项目主页：https://github.com/kege/Z-Image-Turbo-WebUI
• 模型地址：Tongyi-MAI/Z-Image-Turbo @ ModelScope
• 框架支持：DiffSynth Studio