Z-Image-Turbo下载按钮使用说明：一键保存所有结果

阿里通义Z-Image-Turbo WebUI图像快速生成模型二次开发构建by科哥

Z-Image-Turbo WebUI 用户使用手册

欢迎使用 Z-Image-Turbo AI 图像生成 WebUI！本手册将帮助您快速上手并充分利用这个强大的 AI 图像生成工具。

快速开始

启动 WebUI

在终端中执行以下命令启动服务：

# 方式 1: 使用启动脚本（推荐） bash scripts/start_app.sh # 方式 2: 手动启动 source /opt/miniconda3/etc/profile.d/conda.sh conda activate torch28 python -m app.main

启动成功后，终端会显示：

================================================== Z-Image-Turbo WebUI 启动中... ================================================== 模型加载成功! 启动服务器: 0.0.0.0:7860 请访问: http://localhost:7860

访问界面

在浏览器中打开：http://localhost:7860

界面说明

WebUI 分为三个标签页：

1. 🎨 图像生成（主界面）

这是您最常用的界面，用于生成 AI 图像。

左侧：输入参数面板

正向提示词（Prompt）- 描述您想要生成的图像内容 - 支持中文和英文 - 建议使用具体、详细的描述 - 示例：一只可爱的橘色猫咪，坐在窗台上，阳光洒进来，温暖的氛围，高清照片

负向提示词（Negative Prompt）- 描述您不希望出现在图像中的内容 - 用于排除低质量元素 - 常用词：低质量，模糊，扭曲，丑陋，多余的手指

图像设置

| 参数 | 说明 | 范围 | 推荐值 | |------|------|------|--------| | 宽度 | 图像宽度（像素） | 512-2048 | 1024 | | 高度 | 图像高度（像素） | 512-2048 | 1024 | | 推理步数 | 生成迭代次数 | 1-120 | 40 | | 生成数量 | 单次生成张数 | 1-4 | 1 | | 随机种子 | 控制随机性 | -1=随机 | -1 | | CFG引导强度 | 对提示词的遵循程度 | 1.0-20.0 | 7.5 |

快速预设按钮-512×512：小尺寸方形 -768×768：中等方形 -1024×1024：大尺寸方形（推荐） -横版 16:9：1024×576 -竖版 9:16：576×1024

右侧：输出面板

生成的图像：显示生成结果
生成信息：显示生成参数和元数据
下载按钮：一键下载全部当前生成的图像文件

核心功能亮点：点击“下载”按钮可自动打包并保存本次生成的所有图像至本地设备，无需逐张右键另存为。

2. ⚙️ 高级设置

查看当前模型配置和系统信息：

模型信息：当前使用的模型名称、路径、设备类型
系统信息：PyTorch 版本、CUDA 状态、GPU 型号

使用技巧：此页面包含详细的使用提示和参数说明

3. ℹ️ 关于

下载功能详解：如何高效保存生成结果

功能定位与设计初衷

Z-Image-Turbo 的“下载”按钮是为提升用户操作效率而设计的核心交互组件。在多图批量生成场景下（如一次生成4张），传统方式需对每张图像进行“右键 → 另存为”操作，流程繁琐且易出错。

为此，我们集成了一键式下载机制，实现： - ✅ 自动识别当前会话中所有生成图像 - ✅ 打包成独立 PNG 文件集合 - ✅ 触发浏览器原生下载流程 - ✅ 保留完整元数据命名规则

实际使用步骤（图文指引）

完成图像生成
输入提示词并设置参数
点击“生成”按钮等待完成
确认右侧输出区域已显示所需图像
点击【下载】按钮
位于图像预览区下方，图标为 ↓
支持 Chrome / Firefox / Edge 浏览器
不支持 Safari（存在跨域限制）
选择保存位置
浏览器弹出标准文件保存对话框
默认文件名格式：outputs_YYYYMMDDHHMMSS.zip
可手动修改保存路径和文件名
验证下载完整性
解压后检查文件数量是否与“生成数量”一致
核对文件命名时间戳是否匹配生成时刻

示例行为：若单次生成3张图像，则下载包内将包含3个PNG文件，如outputs_20260105143025_0.png,_1.png,_2.png。

技术实现原理剖析

前端逻辑架构

下载功能由前端 React 组件驱动，基于HTMLCanvasElement.toBlob()和JSZip库实现客户端压缩打包。

// 伪代码示意：downloadHandler.js async function handleDownload(images) { const zip = new JSZip(); for (let i = 0; i < images.length; i++) { const response = await fetch(images[i].src); const blob = await response.blob(); zip.file(`output_${timestamp}_${i}.png`, blob); } const content = await zip.generateAsync({type:"blob"}); saveAs(content, `outputs_${timestamp}.zip`); }

fetch()获取 canvas 导出的图像 Blob
JSZip在内存中构建 ZIP 包
saveAs()调用 FileSaver.js 触发下载

后端协同机制

虽然主要处理在前端完成，但后端提供了关键支持：

# app/api/routes.py @router.get("/api/images/latest") def get_latest_images(): output_dir = Path("./outputs") recent_files = sorted(output_dir.glob("*.png"), key=lambda x: x.stat().st_mtime, reverse=True)[:4] return {"images": [f.name for f in recent_files]}

该接口供前端轮询最新生成文件列表，确保下载内容同步更新。

兼容性与性能优化

| 浏览器 | 支持情况 | 最大并发图像数 | |--------|----------|----------------| | Chrome | ✅ 完全支持 | ≤8 张 | | Firefox | ✅ 完全支持 | ≤6 张 | | Edge | ✅ 完全支持 | ≤8 张 | | Safari | ❌ 存在 CORS 问题 | 不推荐使用 |

性能建议： - 单次下载不超过6张图像以避免内存溢出 - 若生成大量图像，请分批操作或直接访问./outputs/目录手动复制

使用技巧进阶指南

批量工作流优化策略

当需要连续生成多个主题图像时，推荐以下工作流：

设置统一参数模板（如1024×1024, 步数40）
每组生成后立即点击【下载】保存结果
清空画布开始下一组创作
所有任务完成后统一整理下载目录

这样可避免文件混淆，并便于后期分类管理。

文件命名与追溯机制

所有生成图像均采用标准化命名：

outputs_<TIMESTAMP>_<INDEX>.png

其中： -<TIMESTAMP>：精确到秒的时间戳（如20260105143025） -<INDEX>：同一请求内的图像序号（从0开始）

此设计确保： - 时间顺序清晰可查 - 避免文件覆盖风险 - 支持自动化脚本处理

与本地文件系统的联动

除了通过下载按钮获取图像外，还可直接访问输出目录：

# 查看最近生成的5个文件 ls -lt ./outputs/*.png | head -5 # 按日期归档旧文件 mkdir -p ./archives/$(date +%Y%m%d) mv ./outputs/*.png ./archives/$(date +%Y%m%d)/

适用于需要长期保存或批量迁移的高级用户。

常见问题与解决方案

Q1：点击下载无反应？

可能原因及排查步骤：

浏览器阻止弹窗
检查地址栏是否有“已阻止弹出窗口”提示
点击允许后重试
内存不足导致压缩失败
尝试减少“生成数量”至1-2张
关闭其他占用内存的应用
网络延迟影响资源加载
刷新页面重新加载图像
等待图像完全渲染后再点击下载

Q2：下载的ZIP包损坏无法解压？

根本原因分析：通常因前端压缩过程中断所致，常见于低配设备或高分辨率图像。

解决方法： - 降低图像尺寸至768×768测试 - 更换为 Chrome 浏览器尝试 - 直接从./outputs/目录复制文件

Q3：部分图像缺失？

典型场景：用户在生成未完成时提前点击下载。

预防措施： - 等待进度条完全消失、状态变为“生成完成” - 观察所有缩略图均已加载完毕再操作

高级应用场景拓展

场景一：创意素材批量采集

设计师需为某品牌收集10组不同风格的视觉概念图。

操作流程： 1. 编写多样化提示词组合（现代/复古/极简等） 2. 每组生成4张候选图 3. 每组完成后立即下载并重命名ZIP包（如brand_concept_modern.zip） 4. 后期统一评审选图

优势体现：下载功能极大提升了素材采集效率，避免重复操作。

场景二：教学演示中的即时分享

教师在课堂上演示AI绘画过程，需让学生快速获取成果。

解决方案： - 演示结束后一键下载 - 将ZIP包上传至课程群或学习平台 - 学生可复现参数对比效果

故障排除补充

问题：图像质量不佳

可能原因和解决方法：

提示词不够清晰
添加更多细节描述
明确指定风格和质量要求
CFG 值不合适
尝试调整到 7-10 范围
太低(1-4)会导致不遵循提示词
太高(15+)会导致过饱和
推理步数太少
增加到 40-60 步
更多步数通常带来更好质量

问题：生成速度慢

优化方法：

降低图像尺寸
从 1024×1024 降到 768×768
减少推理步数
从 60 降到 30-40
减少生成数量
一次只生成 1 张

问题：WebUI 无法访问

检查方法：

确认服务正在运行bash lsof -ti:7860 # 查看端口是否被占用
查看日志bash tail -f /tmp/webui_*.log
尝试不同浏览器
推荐使用 Chrome 或 Firefox
清除浏览器缓存

输出文件管理规范

生成的图像自动保存在：./outputs/目录

文件命名格式：outputs_YYYYMMDDHHMMSS.png

例如：outputs_20260105143025.png

管理建议： - 定期归档旧文件防止目录臃肿 - 使用软链接建立项目专属输出路径 - 配合.gitignore忽略输出目录版本控制

键盘快捷键

目前 WebUI 不支持键盘快捷键，所有操作通过鼠标点击完成。

高级功能

使用 Python API

如果需要批量生成或集成到其他程序：

from app.core.generator import get_generator # 获取生成器 generator = get_generator() # 生成图像 output_paths, gen_time, metadata = generator.generate( prompt="一只可爱的猫咪", negative_prompt="低质量，模糊", width=1024, height=1024, num_inference_steps=40, seed=-1, num_images=1, cfg_scale=7.5 ) print(f"生成完成：{output_paths}")

可通过编程方式绕过前端限制，直接读取output_paths进行后续处理。