基于 Z-Image-Turbo Python API 的批量图像生成实践

每个任务可指定独立输出目录，便于后期分类管理。

执行批量生成主循环

编写主函数遍历任务队列并调用 API：

def batch_generate(tasks):
    total_start_time = time.time()
    for idx, task in enumerate(tasks, 1):
        print(f"\n🚀 开始第 {idx}/{len(tasks)} 个任务...")
        print(f"📌 主题：{task['prompt'][:30]}...")
        
        # 创建输出目录
        os.makedirs(task["output_dir"], exist_ok=True)
        
        # 设置临时输出路径
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
        temp_output = os.path.join(task["output_dir"], f"temp_{timestamp}")
        
        try:
            # 调用生成接口
            output_paths, gen_time, metadata = generator.generate(
                prompt=task["prompt"],
                negative_prompt=task["negative_prompt"],
                width=task["width"],
                height=task["height"],
                num_inference_steps=task["steps"],
                cfg_scale=task["cfg"],
                seed=task["seed"],
                num_images=task["count"],
                output_dir=temp_output
            )
            
            # 重命名并整理文件
            for i, path in enumerate(output_paths):
                new_name = f"{task.get('name', f'img_{idx}_{i+1}')}.png"
                final_path = os.path.join(task["output_dir"], new_name)
                os.rename(path, final_path)
                print(f"✅ 生成完成 → {final_path}")
                print(f"⏱️ 耗时：{gen_time:.2f} 秒 | 分辨率：{task['width']}×{task['height']}")
        except Exception as e:
            print(f"❌ 任务失败：{str(e)}")
            continue
            
    total_time = time.time() - total_start_time
    print(f"\n🎉 批量生成全部完成！总耗时：{total_time:.2f} 秒")

if __name__ == "__main__":
    batch_generate(tasks)

运行命令 python batch_generate.py 即可看到执行日志。首次任务因模型加载较慢（约 2-4 分钟），后续任务均进入高速推理阶段。

关键优化技巧

1. 复用生成器实例

务必在整个生命周期内只初始化一次 get_generator()，否则每次都会重新加载模型，极大拖慢整体速度。

2. 合理设置推理步数

并非越多越好。Z-Image-Turbo 经过蒸馏训练，20-40 步即可达到良好效果，过度增加步数收益递减。

3. 控制并发数量

尽管支持多卡并行，但建议单进程内同时生成不超过 2 张图像，防止显存溢出。若需更高吞吐，可考虑使用多进程池或分布式部署多个 WebUI 实例。

4. 自动清理缓存文件

长期运行可能积累大量临时文件，建议定期清理或在代码中加入自动清理逻辑。

高级应用场景

场景一：电商平台商品图自动生成

结合商品数据库，自动为新品生成宣传图：

for product in db.query_new_products():
    prompt = f"{product.name}，{product.color}色，{product.material}材质，放在{product.scene}背景下"
    task = {
        "prompt": prompt,
        "negative_prompt": "文字，logo，水印",
        "width": 1024,
        "height": 1024,
        "steps": 40,
        "cfg": 8.0,
        "output_dir": f"./outputs/products/{product.category}/"
    }
    generator.generate(**task)

场景二：社交媒体每日图文推送

配合定时任务（cron），每天早 8 点自动生成一张'今日风景'图：

# crontab -e
0 8 * * * cd /z-image-turbo && python daily_post.py

# daily_post.py
themes = ["晨曦森林", "海边日出", "城市夜景", "雪山湖泊"]
selected = random.choice(themes)
generator.generate(
    prompt=f"{selected}，高清摄影，电影质感",
    ...
)

故障排查与稳定性保障

常见问题及解决方案

建议的健壮性增强措施

1. 添加异常重试机制

from tenacity import retry, stop_after_attempt
@retry(stop=stop_after_attempt(3))
def safe_generate(**kwargs):
    return generator.generate(**kwargs)

2. 记录日志便于追踪

import logging
logging.basicConfig(filename='batch.log', level=logging.INFO)

3. 监控 GPU 使用情况

nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv

总结

通过本文的实践，我们完成了从 WebUI 手动操作到 Python API 批量自动化的关键跃迁。Z-Image-Turbo 不再只是一个图像生成器，而是可以嵌入真实业务流程的生产力工具。

核心收获包括：掌握了本地部署与 API 调用方式，实现了结构化任务驱动的批量图像生成流程，学会了性能调优与稳定性保障的关键技巧，以及拓展了与数据库、定时任务等系统的集成思路。下一步可以尝试建立自己的提示词库，封装通用生成函数，甚至探索 LoRA 微调以定制专属风格模型。