# 阿里通义Z-Image-Turbo Python API调用：批量生成代码实例 ## 1. 项目介绍与环境准备 阿里通义Z-Image-Turbo是一个基于WebUI的图像快速生成模型，提供了强大的AI图像生成能力。通过Python API调用，我们可以实现批量图像生成，大大提高工作效率。本文将详细介绍如何使用Python代码进行批量图像生成。 ### 1.1 环境要求 在开始之前，请确保您的环境满足以下要求： - Python 3.8+ - PyTorch 2.0+ - CUDA 11.7+（GPU加速） - 至少8GB显存（推荐16GB以上） ### 1.2 安装依赖 ```bash # 创建conda环境（推荐） conda create -n z-image-turbo python=3.10 conda activate z-image-turbo # 安装核心依赖 pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 pip install diffusers transformers accelerate ``` ## 2. 基础API调用方法 ### 2.1 初始化生成器 首先我们需要初始化图像生成器，这是所有操作的基础： ```python import torch from diffusers import StableDiffusionXLPipeline import os class ZImageTurboGenerator: def __init__(self, model_path="Tongyi-MAI/Z-Image-Turbo"): """ 初始化Z-Image-Turbo生成器 Args: model_path: 模型路径，可以是本地路径或HuggingFace模型ID """ print("正在加载模型...") # 使用半精度浮点数节省显存 self.pipe = StableDiffusionXLPipeline.from_pretrained( model_path, torch_dtype=torch.float16, variant="fp16", use_safetensors=True ) # 启用GPU加速 self.pipe = self.pipe.to("cuda") # 启用xformers优化（可选） try: self.pipe.enable_xformers_memory_efficient_attention() except: print("xformers不可用，继续使用标准注意力机制") print("模型加载完成！") # 初始化生成器 generator = ZImageTurboGenerator() ``` ### 2.2 单张图像生成 让我们先实现单张图像生成的基础功能： ```python def generate_single_image(prompt, output_path, negative_prompt="", width=1024, height=1024, num_inference_steps=40, guidance_scale=7.5, seed=None): """ 生成单张图像 Args: prompt: 正向提示词 output_path: 输出路径 negative_prompt: 负向提示词 width: 图像宽度 height: 图像高度 num_inference_steps: 推理步数 guidance_scale: CFG引导强度 seed: 随机种子 """ # 设置随机种子（如果提供） if seed is not None: torch.manual_seed(seed) torch.cuda.manual_seed_all(seed) # 生成图像 with torch.autocast("cuda"): image = generator.pipe( prompt=prompt, negative_prompt=negative_prompt, width=width, height=height, num_inference_steps=num_inference_steps, guidance_scale=guidance_scale, num_images_per_prompt=1 ).images[0] # 保存图像 image.save(output_path) print(f"图像已保存: {output_path}") return image # 示例：生成一张猫咪图像 generate_single_image( prompt="一只可爱的橘色猫咪，坐在窗台上，阳光洒进来，温暖的氛围，高清照片", negative_prompt="低质量，模糊，扭曲，丑陋", output_path="cat_image.png", width=1024, height=1024, num_inference_steps=40, guidance_scale=7.5, seed=42 ) ``` ## 3. 批量生成实现 ### 3.1 基础批量生成函数 现在让我们实现批量生成的核心功能： ```python import time from datetime import datetime from tqdm import tqdm def batch_generate_images(prompts, output_dir="./batch_output", batch_size=1, **kwargs): """ 批量生成图像 Args: prompts: 提示词列表，可以是字符串或字典 output_dir: 输出目录 batch_size: 每批生成数量 **kwargs: 其他生成参数 """ # 创建输出目录 os.makedirs(output_dir, exist_ok=True) # 记录生成信息 results = [] total_start_time = time.time() # 处理提示词格式 if isinstance(prompts[0], str): prompts = [{"prompt": p} for p in prompts] # 分批处理 for i in tqdm(range(0, len(prompts), batch_size), desc="批量生成进度"): batch_prompts = prompts[i:i+batch_size] for j, prompt_info in enumerate(batch_prompts): # 生成唯一文件名 timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") filename = f"image_{timestamp}_{i+j}.png" output_path = os.path.join(output_dir, filename) # 合并参数 params = { "prompt": prompt_info.get("prompt", ""), "negative_prompt": prompt_info.get("negative_prompt", ""), "width": prompt_info.get("width", 1024), "height": prompt_info.get("height", 1024), "num_inference_steps": prompt_info.get("num_inference_steps", 40), "guidance_scale": prompt_info.get("guidance_scale", 7.5), "seed": prompt_info.get("seed", None), "output_path": output_path } # 更新用户自定义参数 params.update(kwargs) # 生成图像 start_time = time.time() try: image = generate_single_image(**params) gen_time = time.time() - start_time # 记录结果 results.append({ "filename": filename, "prompt": params["prompt"], "negative_prompt": params["negative_prompt"], "generation_time": gen_time, "file_size": os.path.getsize(output_path), "success": True }) except Exception as e: print(f"生成失败: {e}") results.append({ "filename": filename, "prompt": params["prompt"], "error": str(e), "success": False }) # 生成报告 total_time = time.time() - total_start_time generate_report(results, total_time, output_dir) return results def generate_report(results, total_time, output_dir): """生成批量生成报告""" report_path = os.path.join(output_dir, "generation_report.txt") successful = sum(1 for r in results if r["success"]) failed = len(results) - successful with open(report_path, "w", encoding="utf-8") as f: f.write("=" * 50 + "\n") f.write("批量生成报告\n") f.write("=" * 50 + "\n\n") f.write(f"生成时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n") f.write(f"总耗时: {total_time:.2f} 秒\n") f.write(f"生成数量: {len(results)} 张\n") f.write(f"成功: {successful} 张\n") f.write(f"失败: {failed} 张\n") f.write(f"平均生成时间: {total_time/len(results):.2f} 秒/张\n\n") f.write("详细信息:\n") f.write("-" * 30 + "\n") for i, result in enumerate(results, 1): f.write(f"\n{i}. {result['filename']}\n") if result["success"]: f.write(f" 提示词: {result['prompt'][:50]}...\n") f.write(f" 生成时间: {result['generation_time']:.2f}秒\n") f.write(f" 文件大小: {result['file_size']} bytes\n") else: f.write(f" 失败原因: {result['error']}\n") print(f"生成报告已保存: {report_path}") ``` ### 3.2 批量生成示例 让我们看几个实际的批量生成示例： ```python # 示例1：基础批量生成 prompts = [ "一只可爱的橘色猫咪，坐在窗台上，阳光洒进来", "壮丽的山脉日出，云海翻腾，金色阳光", "现代简约风格的咖啡杯，白色陶瓷，放在木质桌面上", "可爱的动漫少女，粉色长发，蓝色眼睛，穿着校服" ] # 执行批量生成 results = batch_generate_images( prompts=prompts, output_dir="./batch_output_basic", batch_size=2, # 每次生成2张 width=1024, height=1024, num_inference_steps=40, guidance_scale=7.5 ) # 示例2：带详细参数的批量生成 detailed_prompts = [ { "prompt": "一只金毛犬，坐在草地上，阳光明媚，绿树成荫", "negative_prompt": "低质量，模糊，扭曲", "width": 1024, "height": 1024, "num_inference_steps": 45, "guidance_scale": 8.0, "seed": 123 }, { "prompt": "未来城市夜景，霓虹灯光，飞行汽车，赛博朋克风格", "negative_prompt": "白天，模糊，低质量", "width": 1024, "height": 576, # 横版 "num_inference_steps": 50, "guidance_scale": 7.8, "seed": 456 }, { "prompt": "古典油画风格的静物，水果篮，柔和光线", "negative_prompt": "现代，照片，锐利", "width": 768, "height": 768, "num_inference_steps": 60, "guidance_scale": 6.5, "seed": 789 } ] results = batch_generate_images( prompts=detailed_prompts, output_dir="./batch_output_detailed", batch_size=1 # 每次生成1张 ) ``` ## 4. 高级批量处理技巧 ### 4.1 从文件读取提示词 对于大规模的批量生成，我们可以从文件中读取提示词： ```python import json import csv def load_prompts_from_file(file_path, file_type="auto"): """ 从文件加载提示词 Args: file_path: 文件路径 file_type: 文件类型 (json, csv, txt, auto) """ if file_type == "auto": if file_path.endswith('.json'): file_type = 'json' elif file_path.endswith('.csv'): file_type = 'csv' else: file_type = 'txt' prompts = [] try: if file_type == 'json': with open(file_path, 'r', encoding='utf-8') as f: data = json.load(f) if isinstance(data, list): prompts = data else: prompts = [data] elif file_type == 'csv': with open(file_path, 'r', encoding='utf-8') as f: reader = csv.DictReader(f) for row in reader: prompts.append(row) elif file_type == 'txt': with open(file_path, 'r', encoding='utf-8') as f: for line in f: line = line.strip() if line and not line.startswith('#'): prompts.append({"prompt": line}) except Exception as e: print(f"读取文件失败: {e}") return [] return prompts # 使用示例 json_prompts = load_prompts_from_file("prompts.json") csv_prompts = load_prompts_from_file("prompts.csv") txt_prompts = load_prompts_from_file("prompts.txt") # 批量生成 results = batch_generate_images( prompts=json_prompts, output_dir="./batch_from_file", batch_size=2 ) ``` ### 4.2 生成参数模板 创建可重用的参数模板，方便批量使用： ```python def create_prompt_templates(base_prompt, variations): """ 创建提示词变体 Args: base_prompt: 基础提示词 variations: 变体列表 """ templates = [] for variation in variations: full_prompt = f"{base_prompt}, {variation}" templates.append({ "prompt": full_prompt, "filename_suffix": variation.replace(" ", "_").replace(",", "") }) return templates # 示例：创建不同风格的同一主题 base_prompt = "一只猫咪" styles = [ "水彩画风格，柔和色彩", "油画风格，厚重笔触", "动漫风格，大眼睛", "写实照片风格，高清细节", "像素艺术风格，8-bit" ] templates = create_prompt_templates(base_prompt, styles) # 批量生成不同风格 results = batch_generate_images( prompts=templates, output_dir="./style_variations", batch_size=1 ) ``` ### 4.3 智能批处理与内存管理 对于大规模批量生成，需要智能的内存管理： ```python def smart_batch_generate(prompts, output_dir, max_memory_usage=0.8, **kwargs): """ 智能批量生成，自动管理内存 Args: prompts: 提示词列表 output_dir: 输出目录 max_memory_usage: 最大内存使用率 **kwargs: 其他参数 """ import gc import psutil results = [] current_batch = [] batch_size = 1 for i, prompt_info in enumerate(prompts): current_batch.append(prompt_info) # 检查内存使用 memory_usage = psutil.virtual_memory().percent / 100 if len(current_batch) >= batch_size or memory_usage > max_memory_usage: # 生成当前批次 batch_results = batch_generate_images( prompts=current_batch, output_dir=output_dir, batch_size=len(current_batch), **kwargs ) results.extend(batch_results) # 清理内存 current_batch = [] torch.cuda.empty_cache() gc.collect() # 动态调整批次大小 if memory_usage > max_memory_usage * 0.9: batch_size = max(1, batch_size // 2) elif memory_usage < max_memory_usage * 0.7: batch_size = min(4, batch_size + 1) # 处理剩余批次 if current_batch: batch_results = batch_generate_images( prompts=current_batch, output_dir=output_dir, batch_size=len(current_batch), **kwargs ) results.extend(batch_results) return results # 使用智能批处理 results = smart_batch_generate( prompts=prompts, output_dir="./smart_batch_output", max_memory_usage=0.85, width=1024, height=1024 ) ``` ## 5. 实战案例：电商产品图批量生成 让我们看一个实际的电商应用案例： ```python def generate_ecommerce_product_images(product_list, output_dir): """ 生成电商产品图像 Args: product_list: 产品列表 output_dir: 输出目录 """ prompts = [] for product in product_list: # 根据产品类型生成不同的提示词 if product["category"] == "electronics": prompt = generate_electronics_prompt(product) elif product["category"] == "clothing": prompt = generate_clothing_prompt(product) elif product["category"] == "home": prompt = generate_home_prompt(product) else: prompt = generate_general_prompt(product) prompts.append({ "prompt": prompt, "negative_prompt": "低质量，模糊，扭曲，水印，文字", "width": 1024, "height": 1024, "num_inference_steps": 50, "guidance_scale": 8.0 }) # 批量生成 results = batch_generate_images( prompts=prompts, output_dir=output_dir, batch_size=2 ) return results def generate_electronics_prompt(product): """生成电子产品提示词""" return f""" {product['name']}产品照片，现代科技感，纯白色背景， 专业产品摄影，明亮光线，细节清晰，4K高清质量， {product['color']}颜色， minimalist design """ def generate_clothing_prompt(product): """生成服装产品提示词""" return f""" {product['name']}服装，模特穿着，自然光线， studio拍摄， {product['color']}颜色， {product['style']}风格， 高质量服装摄影，细节清晰 """ # 示例产品数据 products = [ {"name": "智能手机", "category": "electronics", "color": "黑色"}, {"name": "笔记本电脑", "category": "electronics", "color": "银色"}, {"name": "T恤", "category": "clothing", "color": "白色", "style": "休闲"}, {"name": "连衣裙", "category": "clothing", "color": "红色", "style": "时尚"} ] # 生成电商产品图 ecommerce_results = generate_ecommerce_product_images( products, "./ecommerce_products" ) ``` ## 6. 性能优化与错误处理 ### 6.1 性能优化技巧 ```python def optimize_generation_settings(): """优化生成设置""" # 启用各种优化 generator.pipe.enable_attention_slicing() # 使用更快的scheduler（如果可用） try: from diffusers import EulerDiscreteScheduler generator.pipe.scheduler = EulerDiscreteScheduler.from_config( generator.pipe.scheduler.config ) except: pass # 设置设备优化 torch.backends.cudnn.benchmark = True def estimate_generation_time(prompts, avg_time_per_image=25): """估算生成时间""" total_seconds = len(prompts) * avg_time_per_image hours = total_seconds // 3600 minutes = (total_seconds % 3600) // 60 seconds = total_seconds % 60 return f"{hours:02d}:{minutes:02d}:{seconds:02d}" # 使用优化设置 optimize_generation_settings() ``` ### 6.2 错误处理与重试机制 ```python def robust_batch_generate(prompts, output_dir, max_retries=3, **kwargs): """ 带重试机制的批量生成 Args: prompts: 提示词列表 output_dir: 输出目录 max_retries: 最大重试次数 **kwargs: 其他参数 """ results = [] for i, prompt_info in enumerate(prompts): for attempt in range(max_retries + 1): try: result = batch_generate_images( prompts=[prompt_info], output_dir=output_dir, batch_size=1, **kwargs )[0] results.append(result) break except Exception as e: if attempt == max_retries: print(f"提示词 {i} 生成失败: {e}") results.append({ "prompt": prompt_info.get("prompt", ""), "error": str(e), "success": False }) else: print(f"提示词 {i} 第{attempt+1}次尝试失败，重试...") time.sleep(2) # 等待后重试 return results ``` ## 7. 总结与最佳实践 通过本文的介绍，我们学习了如何使用阿里通义Z-Image-Turbo的Python API进行批量图像生成。以下是一些最佳实践建议： ### 7.1 批量生成最佳实践 1. **合理设置批次大小**：根据GPU显存调整，通常1-4张为宜 2. **使用智能内存管理**：监控内存使用，动态调整批次大小 3. **做好错误处理**：实现重试机制，记录失败任务 4. **生成详细报告**：记录每次生成的参数和结果 5. **定期清理缓存**：使用`torch.cuda.empty_cache()`释放显存 ### 7.2 性能优化建议 - 使用半精度浮点数（fp16）减少显存占用 - 启用xformers优化注意力机制 - 使用更快的scheduler（如EulerDiscreteScheduler） - 合理设置推理步数（20-60步通常足够） ### 7.3 实用技巧 - 从文件读取提示词，方便大规模批量生成 - 创建提示词模板，生成风格统一的图像系列 - 使用随机种子复现特定效果 - 生成详细报告，便于后续分析和优化 通过掌握这些技巧，您可以高效地使用阿里通义Z-Image-Turbo进行批量图像生成，满足各种商业和创意需求。 --- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。