Z-Image开发者完全手册API参考与自定义扩展指南【免费下载链接】Z-Image项目地址: https://ai.gitcode.com/hf_mirrors/MindIE/Z-ImageZ-Image是HuggingFace镜像项目MindIE中的核心组件提供了强大的图像生成API和灵活的扩展机制。本手册将帮助开发者快速掌握Z-Image的API使用方法并指导如何进行自定义扩展开发。快速开始Z-Image API基础核心API组件概览Z-Image的核心功能通过ZImagePipeline类实现该类位于zimage/native_diffusers/pipeline_z_image.py。这个类集成了文本编码器、图像生成器和调度器等关键组件为图像生成提供了完整的工作流。class ZImagePipeline(DiffusionPipeline, ZImageLoraLoaderMixin, FromSingleFileMixin): model_cpu_offload_seq text_encoder-transformer-vae _optional_components [] _callback_tensor_inputs [latents, prompt_embeds]初始化图像生成管道使用Z-Image API的第一步是初始化图像生成管道。典型的初始化流程如下from zimage.native_diffusers.pipeline_z_image import ZImagePipeline # 加载预训练模型组件 scheduler FlowMatchEulerDiscreteScheduler.from_pretrained(...) vae AutoencoderKL.from_pretrained(...) text_encoder PreTrainedModel.from_pretrained(...) tokenizer AutoTokenizer.from_pretrained(...) transformer ZImageTransformer2DModel.from_pretrained(...) # 创建管道实例 pipeline ZImagePipeline( schedulerscheduler, vaevae, text_encodertext_encoder, tokenizertokenizer, transformertransformer )在实际应用中你可以使用inference.py中的init_pipeline函数快速初始化管道from inference import init_pipeline pipeline init_pipeline(args, device)图像生成API详解核心生成方法callZImagePipeline的__call__方法是图像生成的主要入口提供了丰富的参数控制生成过程def __call__( self, prompt: Union[str, List[str]] None, height: Optional[int] None, width: Optional[int] None, num_inference_steps: int 50, sigmas: Optional[List[float]] None, guidance_scale: float 5.0, cfg_normalization: bool False, cfg_truncation: float 1.0, negative_prompt: Optional[Union[str, List[str]]] None, num_images_per_prompt: Optional[int] 1, generator: Optional[Union[torch.Generator, List[torch.Generator]]] None, latents: Optional[torch.FloatTensor] None, prompt_embeds: Optional[List[torch.FloatTensor]] None, negative_prompt_embeds: Optional[List[torch.FloatTensor]] None, output_type: Optional[str] pil, return_dict: bool True, joint_attention_kwargs: Optional[Dict[str, Any]] None, callback_on_step_end: Optional[Callable[[int, int, Dict], None]] None, callback_on_step_end_tensor_inputs: List[str] [latents], max_sequence_length: int 512, ):关键参数说明参数名称类型描述promptstr或List[str]引导图像生成的文本提示height/widthint生成图像的高度和宽度num_inference_stepsint去噪步骤数默认50步guidance_scalefloat指导尺度控制文本与图像的匹配程度默认5.0negative_promptstr或List[str]不希望在图像中出现的内容描述num_images_per_promptint每个提示生成的图像数量output_typestr输出类型可选pil、np或pt简单生成示例以下是使用Z-Image API生成图像的基本示例# 生成单张图像 result pipeline( prompta beautiful landscape with mountains and lake, height1024, width1024, num_inference_steps30, guidance_scale7.5 ) # 获取生成的图像 image result.images[0] image.save(generated_landscape.png)自定义扩展开发指南扩展点概述Z-Image设计了多个扩展点允许开发者自定义图像生成流程提示编码扩展通过重写encode_prompt或_encode_prompt方法自定义文本处理逻辑潜在变量准备通过prepare_latents方法自定义初始潜在变量生成调度器扩展集成自定义的去噪调度器回调机制通过callback_on_step_end监控和修改生成过程扩展管道类示例创建自定义管道的推荐方式是继承ZImagePipeline并覆盖需要自定义的方法from zimage.native_diffusers.pipeline_z_image import ZImagePipeline class CustomZImagePipeline(ZImagePipeline): def encode_prompt(self, prompt, deviceNone, do_classifier_free_guidanceTrue, negative_promptNone, prompt_embedsNone, negative_prompt_embedsNone, max_sequence_length512): # 自定义提示编码逻辑 # ... return super().encode_prompt(prompt, device, do_classifier_free_guidance, negative_prompt, prompt_embeds, negative_prompt_embeds, max_sequence_length) def prepare_latents(self, batch_size, num_channels_latents, height, width, dtype, device, generator, latentsNone): # 自定义潜在变量准备逻辑 # ... return super().prepare_latents(batch_size, num_channels_latents, height, width, dtype, device, generator, latents)集成LoRA模型Z-Image支持通过ZImageLoraLoaderMixin集成LoRA模型实现模型微调# 加载LoRA权重 pipeline.load_lora_weights(path/to/lora_weights) # 生成图像时应用LoRA pipeline( prompta beautiful landscape with mountains and lake, lora_scale0.7 # 控制LoRA影响程度 )高级配置与优化性能优化技巧设备选择根据硬件配置选择合适的设备CPU/GPU精度调整使用混合精度加速生成过程模型卸载利用model_cpu_offload_seq配置实现模型组件的动态卸载配置文件使用项目根目录下的config.py提供了全局配置选项可以通过修改该文件或在运行时传递参数来调整系统行为。常见问题与解决方案API调用错误如果遇到API调用错误请检查所有模型组件是否正确加载输入参数是否符合要求设备内存是否充足生成质量问题若生成图像质量不佳可尝试增加num_inference_steps提高去噪步数调整guidance_scale平衡文本指导强度使用更具体的提示词项目结构与资源Z-Image项目主要包含以下目录和文件zimage/native_diffusers/核心扩散模型实现pipeline_z_image.py图像生成管道transformer_z_image.pyTransformer模型modeling_utils.py模型工具函数zimage/utils/辅助工具cache.py缓存管理env.py环境配置seed.py随机种子管理根目录文件inference.py推理入口config.py全局配置requirements.txt依赖项列表开始使用Z-Image要开始使用Z-Image请按照以下步骤操作克隆仓库git clone https://gitcode.com/hf_mirrors/MindIE/Z-Image cd Z-Image安装依赖pip install -r requirements.txt参考inference.py编写你的第一个图像生成程序Z-Image提供了强大而灵活的API无论是快速集成图像生成功能还是进行深度自定义扩展都能满足你的需求。通过本手册的指导希望你能充分利用Z-Image的能力开发出令人惊艳的图像生成应用【免费下载链接】Z-Image项目地址: https://ai.gitcode.com/hf_mirrors/MindIE/Z-Image创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Z-Image开发者完全手册：API参考与自定义扩展指南
发布时间：2026/6/1 21:44:41
Z-Image开发者完全手册API参考与自定义扩展指南【免费下载链接】Z-Image项目地址: https://ai.gitcode.com/hf_mirrors/MindIE/Z-ImageZ-Image是HuggingFace镜像项目MindIE中的核心组件提供了强大的图像生成API和灵活的扩展机制。本手册将帮助开发者快速掌握Z-Image的API使用方法并指导如何进行自定义扩展开发。快速开始Z-Image API基础核心API组件概览Z-Image的核心功能通过ZImagePipeline类实现该类位于zimage/native_diffusers/pipeline_z_image.py。这个类集成了文本编码器、图像生成器和调度器等关键组件为图像生成提供了完整的工作流。class ZImagePipeline(DiffusionPipeline, ZImageLoraLoaderMixin, FromSingleFileMixin): model_cpu_offload_seq text_encoder-transformer-vae _optional_components [] _callback_tensor_inputs [latents, prompt_embeds]初始化图像生成管道使用Z-Image API的第一步是初始化图像生成管道。典型的初始化流程如下from zimage.native_diffusers.pipeline_z_image import ZImagePipeline # 加载预训练模型组件 scheduler FlowMatchEulerDiscreteScheduler.from_pretrained(...) vae AutoencoderKL.from_pretrained(...) text_encoder PreTrainedModel.from_pretrained(...) tokenizer AutoTokenizer.from_pretrained(...) transformer ZImageTransformer2DModel.from_pretrained(...) # 创建管道实例 pipeline ZImagePipeline( schedulerscheduler, vaevae, text_encodertext_encoder, tokenizertokenizer, transformertransformer )在实际应用中你可以使用inference.py中的init_pipeline函数快速初始化管道from inference import init_pipeline pipeline init_pipeline(args, device)图像生成API详解核心生成方法callZImagePipeline的__call__方法是图像生成的主要入口提供了丰富的参数控制生成过程def __call__( self, prompt: Union[str, List[str]] None, height: Optional[int] None, width: Optional[int] None, num_inference_steps: int 50, sigmas: Optional[List[float]] None, guidance_scale: float 5.0, cfg_normalization: bool False, cfg_truncation: float 1.0, negative_prompt: Optional[Union[str, List[str]]] None, num_images_per_prompt: Optional[int] 1, generator: Optional[Union[torch.Generator, List[torch.Generator]]] None, latents: Optional[torch.FloatTensor] None, prompt_embeds: Optional[List[torch.FloatTensor]] None, negative_prompt_embeds: Optional[List[torch.FloatTensor]] None, output_type: Optional[str] pil, return_dict: bool True, joint_attention_kwargs: Optional[Dict[str, Any]] None, callback_on_step_end: Optional[Callable[[int, int, Dict], None]] None, callback_on_step_end_tensor_inputs: List[str] [latents], max_sequence_length: int 512, ):关键参数说明参数名称类型描述promptstr或List[str]引导图像生成的文本提示height/widthint生成图像的高度和宽度num_inference_stepsint去噪步骤数默认50步guidance_scalefloat指导尺度控制文本与图像的匹配程度默认5.0negative_promptstr或List[str]不希望在图像中出现的内容描述num_images_per_promptint每个提示生成的图像数量output_typestr输出类型可选pil、np或pt简单生成示例以下是使用Z-Image API生成图像的基本示例# 生成单张图像 result pipeline( prompta beautiful landscape with mountains and lake, height1024, width1024, num_inference_steps30, guidance_scale7.5 ) # 获取生成的图像 image result.images[0] image.save(generated_landscape.png)自定义扩展开发指南扩展点概述Z-Image设计了多个扩展点允许开发者自定义图像生成流程提示编码扩展通过重写encode_prompt或_encode_prompt方法自定义文本处理逻辑潜在变量准备通过prepare_latents方法自定义初始潜在变量生成调度器扩展集成自定义的去噪调度器回调机制通过callback_on_step_end监控和修改生成过程扩展管道类示例创建自定义管道的推荐方式是继承ZImagePipeline并覆盖需要自定义的方法from zimage.native_diffusers.pipeline_z_image import ZImagePipeline class CustomZImagePipeline(ZImagePipeline): def encode_prompt(self, prompt, deviceNone, do_classifier_free_guidanceTrue, negative_promptNone, prompt_embedsNone, negative_prompt_embedsNone, max_sequence_length512): # 自定义提示编码逻辑 # ... return super().encode_prompt(prompt, device, do_classifier_free_guidance, negative_prompt, prompt_embeds, negative_prompt_embeds, max_sequence_length) def prepare_latents(self, batch_size, num_channels_latents, height, width, dtype, device, generator, latentsNone): # 自定义潜在变量准备逻辑 # ... return super().prepare_latents(batch_size, num_channels_latents, height, width, dtype, device, generator, latents)集成LoRA模型Z-Image支持通过ZImageLoraLoaderMixin集成LoRA模型实现模型微调# 加载LoRA权重 pipeline.load_lora_weights(path/to/lora_weights) # 生成图像时应用LoRA pipeline( prompta beautiful landscape with mountains and lake, lora_scale0.7 # 控制LoRA影响程度 )高级配置与优化性能优化技巧设备选择根据硬件配置选择合适的设备CPU/GPU精度调整使用混合精度加速生成过程模型卸载利用model_cpu_offload_seq配置实现模型组件的动态卸载配置文件使用项目根目录下的config.py提供了全局配置选项可以通过修改该文件或在运行时传递参数来调整系统行为。常见问题与解决方案API调用错误如果遇到API调用错误请检查所有模型组件是否正确加载输入参数是否符合要求设备内存是否充足生成质量问题若生成图像质量不佳可尝试增加num_inference_steps提高去噪步数调整guidance_scale平衡文本指导强度使用更具体的提示词项目结构与资源Z-Image项目主要包含以下目录和文件zimage/native_diffusers/核心扩散模型实现pipeline_z_image.py图像生成管道transformer_z_image.pyTransformer模型modeling_utils.py模型工具函数zimage/utils/辅助工具cache.py缓存管理env.py环境配置seed.py随机种子管理根目录文件inference.py推理入口config.py全局配置requirements.txt依赖项列表开始使用Z-Image要开始使用Z-Image请按照以下步骤操作克隆仓库git clone https://gitcode.com/hf_mirrors/MindIE/Z-Image cd Z-Image安装依赖pip install -r requirements.txt参考inference.py编写你的第一个图像生成程序Z-Image提供了强大而灵活的API无论是快速集成图像生成功能还是进行深度自定义扩展都能满足你的需求。通过本手册的指导希望你能充分利用Z-Image的能力开发出令人惊艳的图像生成应用【免费下载链接】Z-Image项目地址: https://ai.gitcode.com/hf_mirrors/MindIE/Z-Image创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
