Z-Image-Turbo离线环境部署：内网隔离下的模型运行完整指南

1. 环境准备与基础依赖确认

在内网隔离环境中部署Z-Image-Turbo，首要任务不是急着敲命令，而是确保底层环境真正“就绪”。很多用户卡在第一步，其实问题不出在模型本身，而在于几个容易被忽略的细节。

首先确认你的系统满足最低要求：Ubuntu 20.04或更高版本（推荐22.04），Python版本需为3.9或3.10。注意——不要用3.11及以上版本，Gradio在部分内网环境下对新Python版本兼容性尚未完全稳定，会导致UI无法加载或按钮无响应。

其次检查CUDA驱动。Z-Image-Turbo默认启用GPU加速，但如果你的内网服务器只有CPU，也不用担心。它支持纯CPU推理，只是生成速度会慢一些（单图约25–40秒）。你只需在启动脚本中添加一个参数即可切换，我们后面会讲。

最后提醒一点：所有操作都在~/workspace/目录下进行。这是官方推荐的工作路径，也是后续命令默认指向的位置。如果你习惯放在其他路径，请务必同步修改所有路径引用，否则会出现“文件找不到”的报错——这种错误在离线环境中最难排查，因为没有网络诊断工具辅助。

2. 模型与UI服务一键启动

Z-Image-Turbo的部署设计得非常轻量，整个流程不依赖Docker、不调用外部API、不联网下载权重。所有模型文件、UI代码、依赖库都已打包进镜像或离线包中，真正实现“拷进去就能跑”。

2.1 启动服务前的两个小检查

在执行启动命令前，建议快速做两件事：

进入项目根目录：cd ~/workspace/Z-Image-Turbo/
查看核心脚本是否存在：ls -l Z-Image-Turbo_gradio_ui.py
如果显示“no such file”，说明解压不完整，需要重新校验离线包MD5值（通常提供在部署包同级的checksum.txt中）。

2.2 正式启动服务

运行以下命令启动服务：

python /Z-Image-Turbo_gradio_ui.py

注意：命令中路径是/Z-Image-Turbo_gradio_ui.py，不是./Z-Image-Turbo_gradio_ui.py。这是因为该脚本在镜像中被预置在根目录下，直接调用更稳妥，避免因当前路径不同导致的导入失败。

启动后你会看到类似这样的日志输出：

Running on local URL: http://127.0.0.1:7860 To create a public link, set `share=True` in `launch()`. Loading model from /models/z-image-turbo-fp16.safetensors... Model loaded successfully in 12.4s. Starting Gradio app...

当看到Model loaded successfully和Starting Gradio app...这两行时，就可以放心了——模型已加载完毕，UI服务正在运行。此时不需要按Ctrl+C中断，让它保持后台运行即可。

关键提示：如果卡在“Loading model”超过90秒，大概率是显存不足（<6GB）或模型文件损坏。可尝试添加--cpu参数强制使用CPU模式：
python /Z-Image-Turbo_gradio_ui.py --cpu

3. UI界面访问与基础操作指南

Z-Image-Turbo的UI采用Gradio构建，界面简洁直观，没有多余选项，专为内网高频使用优化。它不追求花哨的视觉效果，而是把交互路径压缩到最短——从输入描述到生成图片，三步之内完成。

3.1 两种访问方式，选一种就行

方式一：手动输入地址（推荐首次使用）

打开你本地电脑上的任意浏览器（Chrome、Edge、Firefox均可），在地址栏输入：

http://localhost:7860

或等价写法：

http://127.0.0.1:7860

这两个地址完全等效，都是指向你本机运行的服务。如果打不开，请先确认：

命令行窗口中服务仍在运行（未被意外关闭）
防火墙未拦截7860端口（Linux可临时执行sudo ufw disable测试）

方式二：点击终端中的HTTP链接（适合远程SSH场景）

当你通过SSH连接到内网服务器并运行启动命令后，终端末尾通常会显示一行蓝色文字：

Running on public URL: https://xxx.gradio.live Running on local URL: http://127.0.0.1:7860

其中http://127.0.0.1:7860是可点击的超链接（在支持鼠标点击的终端如Windows Terminal、iTerm2中）。直接按住Ctrl键点击它，浏览器会自动打开——这个小技巧能帮你省去复制粘贴的步骤，尤其在反复调试时很实用。

3.2 界面功能分区说明（不看文档也能上手）

UI界面分为三大区域，从上到下依次是：

顶部提示区：显示当前模型名称、推理设备（GPU/CPU）、显存占用（仅GPU模式可见）
中部主操作区：包含两个核心输入框——“Prompt（正向提示词）”和“Negative Prompt（反向提示词）”，下方是生成参数滑块（CFG Scale、Sampling Steps、Image Size）
底部结果区：实时显示生成进度条，完成后自动展示图片，并附带“Save”按钮和“Copy Prompt”快捷操作

你不需要一开始就搞懂每个参数的意义。先试试这个最简流程：

在Prompt框里输入：“a realistic photo of a golden retriever sitting in a sunlit garden, shallow depth of field”
其他参数保持默认（CFG Scale=7，Steps=30，Size=1024x1024）
点击“Generate”按钮

等待10–20秒（GPU）或30–45秒（CPU），图片就会出现在下方。这就是Z-Image-Turbo最典型的使用节奏：输入一句话，点一下，等几秒，得到一张可用图。

4. 图片生成效果与实用技巧

Z-Image-Turbo的优势不在“全能”，而在“够用”——它不追求覆盖所有艺术风格，但对写实类、产品类、电商类图像的生成质量非常扎实。我们在内网实测过数百次生成，以下是几个真实有效的经验总结。

4.1 提示词怎么写才出图快、效果稳？

很多用户抱怨“生成的图不像狗”或“背景一团乱”，问题往往出在提示词太笼统。Z-Image-Turbo对中文提示词支持良好，但更推荐用简单英文短语，结构清晰：

推荐写法（主谓宾+修饰）：
professional product photo of wireless earbuds on white marble surface, studio lighting, ultra sharp focus

❌ 容易失效的写法：
耳塞，好看，高级，白色，干净（缺少主体关系和视觉约束）

小技巧：加入studio lighting（影棚光）、ultra sharp focus（超锐焦）、white background（白底）这类明确视觉条件的词，能显著提升电商图生成成功率。

4.2 生成尺寸怎么选？别盲目追大

Z-Image-Turbo原生支持1024×1024、1280×720、720×1280三种尺寸。很多人第一反应是选最大——但要注意：1024×1024在GPU上需约5.2GB显存；若显存紧张，选720×1280（竖版）反而更稳，且更适合手机端传播。

我们实测发现：对于商品图、头像、海报主视觉，1024×1024足够；对于社交媒体配图（如小红书、微信公众号），720×1280生成更快、文件更小、加载无压力。

4.3 为什么有时图里多出奇怪元素？试试反向提示词

比如你生成“一杯咖啡”，结果杯子里飘着一只蝴蝶。这不是模型故障，而是缺乏排除指令。这时在Negative Prompt框里加上：

deformed, mutated, extra limbs, text, watermark, logo, butterfly, insect

Z-Image-Turbo会对这些词主动抑制，生成更干净的结果。我们整理了一份内网常用负面词清单，放在~/workspace/docs/negative_prompts.md中，可随时查阅。

5. 历史图片管理：查看、保存与清理

所有生成的图片默认保存在~/workspace/output_image/目录下，按时间戳命名（如20240521_142305.png），方便追溯。这个路径是硬编码的，不随UI设置改变，所以无论你在哪个终端启动服务，图片都归集到同一位置。

5.1 快速查看已生成图片

在终端中执行：

ls ~/workspace/output_image/

你会看到一长串.png文件名。如果想按时间倒序排列（最新生成的在最上面），加个-t参数：

ls -lt ~/workspace/output_image/

小技巧：想直接在终端里预览某张图？安装feh工具（sudo apt install feh），然后运行：
feh ~/workspace/output_image/20240521_142305.png
它会在图形界面弹出一个轻量看图器，比反复打开文件管理器快得多。

5.2 安全删除图片的三种方式

删除操作务必谨慎，尤其是批量删除。我们提供三种粒度可控的方式：

删单张（最安全）：

rm ~/workspace/output_image/20240521_142305.png

删某天的所有图（用通配符）：

rm ~/workspace/output_image/20240521_*.png

清空全部（慎用！建议先备份）：
```
cd ~/workspace/output_image/ rm -f *.png
```
注意：这里用rm -f而非rm -rf。-r是递归删除目录，而output_image/是普通文件夹，加-r不仅多余，还可能误删同名子目录（虽然默认不存在，但留个习惯更稳妥）。

重要提醒：Z-Image-Turbo不会自动清理历史图片，磁盘空间会持续增长。建议每周执行一次清理，或在部署时配置定时任务：
0 3 * * 0 find /home/user/workspace/output_image/ -name "*.png" -mtime +7 -delete
（每周日凌晨3点，自动删除7天前的图片）

6. 常见问题与内网特有问题速查

在离线环境中，问题往往不是“模型不行”，而是“环境没配对”。以下是我们在多个客户内网部署中高频遇到的6类问题及对应解法，按发生概率排序。

6.1 浏览器打不开 http://localhost:7860，但终端显示服务已启动

检查项：是否在服务器本机浏览器打开？
❌ 错误做法：在办公电脑浏览器输入服务器IP+7860（如http://192.168.1.100:7860）
正确做法：必须在运行服务的那台机器上打开浏览器。若需远程访问，需额外配置Gradio的server_name参数（详见docs/remote_access.md）。