hf-doc-build/doc / diffusers /main /es /api /pipelines /z_image.md

|

32.8 kB

Z-Image

Z-Image es un modelo de generación de imágenes potente y altamente eficiente con 6B parámetros. Actualmente solo hay un modelo, con dos más por lanzarse:

Modelo	Hugging Face
Z-Image-Turbo	https://huggingface.co/Tongyi-MAI/Z-Image-Turbo

Z-Image-Turbo

Z-Image-Turbo es una versión destilada de Z-Image que iguala o supera a los principales competidores con solo 8 NFEs (Number of Function Evaluations). Ofrece una latencia de inferencia inferior a un segundo en GPUs H800 de grado empresarial y cabe cómodamente en dispositivos de consumo con 16G de VRAM. Destaca en la generación de imágenes fotorrealistas, el renderizado de texto bilingüe (inglés y chino) y el cumplimiento robusto de instrucciones.

Imagen a imagen

Use ZImageImg2ImgPipeline para transformar una imagen existente en función de un prompt de texto.

import torch
from diffusers import ZImageImg2ImgPipeline
from diffusers.utils import load_image

pipe = ZImageImg2ImgPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
init_image = load_image(url).resize((1024, 1024))

prompt = "A fantasy landscape with mountains and a river, detailed, vibrant colors"
image = pipe(
    prompt,
    image=init_image,
    strength=0.6,
    num_inference_steps=8,
    guidance_scale=0.0,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("zimage_img2img.png")

Inpainting

Use ZImageInpaintPipeline para rellenar regiones específicas de una imagen en función de un prompt de texto y una máscara.

import torch
import numpy as np
from PIL import Image
from diffusers import ZImageInpaintPipeline
from diffusers.utils import load_image

pipe = ZImageInpaintPipeline.from_pretrained("Tongyi-MAI/Z-Image-Turbo", dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

url = "https://raw.githubusercontent.com/CompVis/stable-diffusion/main/assets/stable-samples/img2img/sketch-mountains-input.jpg"
init_image = load_image(url).resize((1024, 1024))

# Create a mask (white = inpaint, black = preserve)
mask = np.zeros((1024, 1024), dtype=np.uint8)
mask[256:768, 256:768] = 255  # Inpaint center region
mask_image = Image.fromarray(mask)

prompt = "A beautiful lake with mountains in the background"
image = pipe(
    prompt,
    image=init_image,
    mask_image=mask_image,
    strength=1.0,
    num_inference_steps=8,
    guidance_scale=0.0,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("zimage_inpaint.png")

ZImagePipeline[[diffusers.ZImagePipeline]]

diffusers.ZImagePipeline[[diffusers.ZImagePipeline]]

diffusers.ZImagePipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: ZImageTransformer2DModel)

Fuente

call[[diffusers.ZImagePipeline.call]]

__call__(prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 5.0, cfg_normalization: bool = False, cfg_truncation: float = 1.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: list[torch.FloatTensor] | None = None, negative_prompt_embeds: list[torch.FloatTensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 512)

Fuente

Parámetros:

prompt (str o list[str], opcional) : El prompt o los prompts para guiar la generación de la imagen. Si no se define, se debe pasar prompt_embeds en su lugar.

height (int, opcional, valor predeterminado 1024) : La altura en píxeles de la imagen generada.

width (int, opcional, valor predeterminado 1024) : El ancho en píxeles de la imagen generada.

num_inference_steps (int, opcional, valor predeterminado 50) : El número de pasos de desruido. Más pasos de desruido suelen conducir a una imagen de mayor calidad a costa de una inferencia más lenta.

sigmas (list[float], opcional) : Sigmas personalizados para usar en el proceso de desruido con programadores que admiten un argumento sigmas en su método set_timesteps. Si no se define, se usará el comportamiento predeterminado cuando se pase num_inference_steps.

guidance_scale (float, opcional, valor predeterminado 5.0) : Escala de orientación definida en Classifier-Free Diffusion Guidance. guidance_scale se define como w de la ecuación 2. de Imagen Paper. La escala de orientación se habilita estableciendo guidance_scale > 1. Una escala de orientación más alta fomenta la generación de imágenes estrechamente vinculadas al prompt de texto, generalmente a costa de una menor calidad de imagen.

cfg_normalization (bool, opcional, predeterminado en False) : Si se aplica la normalización de la configuración.

cfg_truncation (float, opcional, valor predeterminado 1.0) : El valor de truncamiento para la configuración.

negative_prompt (str o list[str], opcional) : El prompt o prompts que no deben guiar la generación de la imagen. Si no se define, se debe pasar negative_prompt_embeds en su lugar. Se ignora cuando no se usa guía (es decir, se ignora si guidance_scale es menor que 1).

num_images_per_prompt (int, opcional, valor predeterminado 1) : El número de imágenes a generar por indicación.

generator (torch.Generator o list[torch.Generator], opcional) : Uno o una lista de generadores de torch para hacer la generación determinista.

latents (torch.FloatTensor, opcional) : Latentes ruidosos pregenerados, muestreados de una distribución gaussiana, que se usarán como entradas para la generación de imágenes. Se pueden utilizar para ajustar la misma generación con diferentes prompts. Si no se proporcionan, se generará un tensor de latentes mediante muestreo usando el generator aleatorio suministrado.

prompt_embeds (list[torch.FloatTensor], opcional) : Embeddings de texto pregenerados. Se pueden utilizar para ajustar fácilmente las entradas de texto, p. ej. ponderación de prompts. Si no se proporcionan, los embeddings de texto se generarán a partir del argumento de entrada prompt.

negative_prompt_embeds (list[torch.FloatTensor], opcional) : Embeddings de texto negativos pregenerados. Se pueden utilizar para ajustar fácilmente las entradas de texto, p. ej. el ponderado de prompts. Si no se proporcionan, negative_prompt_embeds se generará a partir del argumento de entrada negative_prompt.

output_type (str, opcional, por defecto "pil") : El formato de salida de la imagen generada. Elija entre PIL: PIL.Image.Image o np.array.

return_dict (bool, opcional, valor predeterminado True) : Indica si se debe devolver un ~pipelines.stable_diffusion.ZImagePipelineOutput en lugar de una tupla simple.

joint_attention_kwargs (dict, opcional) : Un diccionario de kwargs que, si se especifica, se pasa al AttentionProcessor tal como se define bajo self.processor en diffusers.models.attention_processor.

callback_on_step_end (Callable, opcional) : Una función que se llama al final de cada paso de desruido durante la inferencia. La función se llama con los siguientes argumentos: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs incluirá una lista de todos los tensores especificados por callback_on_step_end_tensor_inputs.

callback_on_step_end_tensor_inputs (List, opcional) : La lista de entradas de tensor para la función callback_on_step_end. Los tensores especificados en la lista se pasarán como argumento callback_kwargs. Solo podrá incluir variables enumeradas en el atributo ._callback_tensor_inputs de su clase de pipeline.

max_sequence_length (int, opcional, valor predeterminado 512) : Longitud máxima de la secuencia para usar con prompt.

Devuelve: ZImagePipelineOutput o tuple

ZImagePipelineOutput si return_dict es True, de lo contrario una tuple. Al devolver una tupla, el primer elemento es una lista con las imágenes generadas.

Función invocada al llamar a la pipeline para la generación.

Ejemplos:

>>> import torch
>>> from diffusers import ZImagePipeline

>>> pipe = ZImagePipeline.from_pretrained("Z-a-o/Z-Image-Turbo", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> # Optionally, set the attention backend to flash-attn 2 or 3, default is SDPA in PyTorch.
>>> # (1) Use flash attention 2
>>> # pipe.transformer.set_attention_backend("flash")
>>> # (2) Use flash attention 3
>>> # pipe.transformer.set_attention_backend("_flash_3")

>>> prompt = "一幅为名为“造相「Z-IMAGE-TURBO」”的项目设计的创意海报。画面巧妙地将文字概念视觉化：一辆复古蒸汽小火车化身为巨大的拉链头，正拉开厚厚的冬日积雪，展露出一个生机盎然的春天。"
>>> image = pipe(
...     prompt,
...     height=1024,
...     width=1024,
...     num_inference_steps=8,
...     guidance_scale=0.0,
...     generator=torch.Generator("cuda").manual_seed(42),
... ).images[0]
>>> image.save("zimage.png")

ZImageImg2ImgPipeline[[diffusers.ZImageImg2ImgPipeline]]

diffusers.ZImageImg2ImgPipeline[[diffusers.ZImageImg2ImgPipeline]]

diffusers.ZImageImg2ImgPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKL, text_encoder: PreTrainedModel, tokenizer: AutoTokenizer, transformer: ZImageTransformer2DModel)

Fuente

Parámetros:

scheduler (FlowMatchEulerDiscreteScheduler) : Un programador para usar en combinación con transformer para desruidar los latentes de imagen codificados.

vae (AutoencoderKL) : Modelo de Variational Auto-Encoder (VAE) para codificar y decodificar imágenes hacia y desde representaciones latentes.

text_encoder (PreTrainedModel) : Un modelo de codificador de texto para codificar prompts de texto.

tokenizer (AutoTokenizer) : Un tokenizador para tokenizar prompts de texto.

transformer (ZImageTransformer2DModel) : Un modelo transformer de ZImage para desruidar los latentes de imagen codificados.

El pipeline ZImage para la generación de imagen a imagen.

call[[diffusers.ZImageImg2ImgPipeline.call]]

__call__(prompt: str | list[str] = None, image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, strength: float = 0.6, height: int | None = None, width: int | None = None, num_inference_steps: int = 50, sigmas: list[float] | None = None, guidance_scale: float = 5.0, cfg_normalization: bool = False, cfg_truncation: float = 1.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.FloatTensor] = None, prompt_embeds: list[torch.FloatTensor] | None = None, negative_prompt_embeds: list[torch.FloatTensor] | None = None, output_type: str | None = 'pil', return_dict: bool = True, joint_attention_kwargs: dict[str, typing.Any] | None = None, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 512)

Fuente

Parámetros:

prompt (str o list[str], opcional) : El prompt o los prompts para guiar la generación de la imagen. Si no se define, se debe pasar prompt_embeds en su lugar.

image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image] o list[np.ndarray]) : Image, array de numpy o tensor que representa un lote de imágenes para usarse como punto de partida. Tanto para el array de numpy como para el tensor de pytorch, el rango de valores esperado está entre [0, 1]. Si es un tensor o una lista de tensors, la forma esperada debe ser (B, C, H, W) o (C, H, W). Si es un array de numpy o una lista de arrays, la forma esperada debe ser (B, H, W, C) o (H, W, C).

strength (float, opcional, valor predeterminado 0.6) : Indica el grado en que se transforma la image de referencia. Debe estar entre 0 y 1. image se utiliza como punto de partida y se añade más ruido a medida que aumenta el strength. El número de pasos de desruido depende de la cantidad de ruido añadido inicialmente. Cuando strength es 1, el ruido añadido es máximo y el proceso de desruido se ejecuta durante el número completo de iteraciones especificado en num_inference_steps. Un valor de 1 ignora esencialmente image.

height (int, opcional, valor predeterminado 1024) : La altura en píxeles de la imagen generada. Si no se proporciona, se utiliza la altura de la imagen de entrada.

width (int, opcional, valor predeterminado 1024) : El ancho en píxeles de la imagen generada. Si no se proporciona, se utiliza el ancho de la imagen de entrada.