Hugging Face's logo

Diffusers documentation

JoyAI-Image-Edit

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

JoyAI-Image-Edit

JoyAI-Image — это единая мультимодальная базовая модель для понимания изображений, генерации изображений по тексту и редактирования изображений по инструкциям. Она объединяет мультимодальную большую языковую модель (MLLM) на 8 млрд параметров и мультимодальный диффузионный трансформер (MMDiT) на 16 млрд параметров. Ключевой принцип JoyAI-Image — замкнутый цикл взаимодействия между пониманием, генерацией и редактированием.

JoyAI-Image-Edit поддерживает общее редактирование изображений, а также возможности пространственного редактирования, включая перемещение объектов, поворот объектов и управление камерой.

МодельОписаниеЗагрузить
JoyAI-Image-EditРедактирование изображений по инструкциям с точным и управляемым пространственным манипулированиемHugging Face
import torch
from diffusers import JoyImageEditPipeline
from diffusers.utils import load_image

pipeline = JoyImageEditPipeline.from_pretrained(
    "jdopensource/JoyAI-Image-Edit-Diffusers", dtype=torch.bfloat16
)
pipeline.to("cuda")  # or "mps", "xpu", "cpu"

image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg")
prompt = "Add wings to the astronaut."

output = pipeline(
    image=image,
    prompt=prompt,
    num_inference_steps=40,
    guidance_scale=4.0,
    generator=torch.Generator("cuda").manual_seed(0),
).images[0]
output.save("joyimage_edit_output.png")

Пространственное редактирование

JoyAI-Image поддерживает три шаблона промптов для пространственного редактирования: Object Move, Object Rotation и Camera Control. Для достижения наилучших результатов максимально точно следуйте приведённым ниже шаблонам промптов. Подробнее см. в SpatialEdit.

Перемещение объекта

Переместите целевой объект в указанную область, отмеченную красным прямоугольником на входном изображении.

Move the <object> into the red box and finally remove the red box.

Поворот объекта

Повернуть объект в заданное каноническое положение. Поддерживаемые значения <view>: front, right, left, rear, front right, front left, rear right, rear left.

Rotate the <object> to show the <view> side view.

Управление камерой

Измените точку обзора камеры, сохранив 3D-сцену без изменений.

Move the camera.
- Camera rotation: Yaw {y_rotation}°, Pitch {p_rotation}°.
- Camera zoom: in/out/unchanged.
- Keep the 3D scene static; only change the viewpoint.

JoyImageEditPipeline

класс diffusers.JoyImageEditPipeline

< >

( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLWantext_encoder: Qwen3VLForConditionalGenerationtokenizer: Qwen2Tokenizertransformer: JoyImageEditTransformer3DModelprocessor: Qwen3VLProcessortext_token_max_length: int = 2048 )

Diffusion pipeline для редактирования изображений с использованием архитектуры JoyImage.

Пайплайн кодирует текстовые и визуальные условия с помощью текстового энкодера Qwen3-VL, выполняет денойзинг латентов с помощью 3-D трансформера и декодирует результат с помощью WAN VAE.

Порядк offloading моделей: text_encoder -> transformer -> vae.

__call__

< >

( image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 40timesteps: typing.List[int] = Nonesigmas: typing.List[float] = Noneguidance_scale: float = 4.0negative_prompt: typing.Union[str, typing.List[str], NoneType] = Nonenum_images_per_prompt: typing.Optional[int] = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds_mask: typing.Optional[torch.Tensor] = Noneoutput_type: typing.Optional[str] = 'pil'return_dict: bool = Truecallback_on_step_end: typing.Union[typing.Callable[[int, int, typing.Dict], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']max_sequence_length: int = 4096enable_denormalization: bool = True ) → [~pipelines.joyimage.JoyImageEditPipelineOutput] or torch.Tensor

Параметры

  • prompt (str или List[str]) — Промпт или промпты для управления генерацией.
  • height (int) — Высота сгенерированного вывода в пикселях.
  • width (int) — Ширина сгенерированного вывода в пикселях.
  • image (PipelineImageInput, необязательный) — Справочное изображение, используемое для условного формирования. При его указании конвейер работает в режиме редактирования изображений с num_items=2.
  • num_inference_steps (int, optional, по умолчанию 40) — Количество шагов денойзинга. Увеличение числа шагов, как правило, повышает качество, но замедляет инференс.
  • timesteps (List[int], необязательный) — Пользовательские шаги для процесса удаления шума. Если указаны, num_inference_steps вычисляется на основе длины списка.
  • sigmas (List[float], optional) — Пользовательские сигмы для процесса удаления шума. Взаимоисключаются с timesteps.
  • guidance_scale (float, optional, по умолчанию 4.0) — Масштаб классификаторного свободного руководства.
  • negative_prompt (str или List[str], необязательный) — Негативный промпт(ы) для подавления нежелательного контента.
  • num_images_per_prompt (int, optional, по умолчанию 1) — Количество генерируемых образцов на промпт.
  • generator (torch.Generator или List[torch.Generator], необязательный) — Генератор(ы) случайных чисел для детерминированной выборки.
  • latents (torch.Tensor, optional) — Предварительно сгенерированные зашумленные латенты для целевого слота. Если не указаны, выборка выполняется из гауссова распределения. Можно использовать для инициализации генерации с конкретного начального тензора шума.
  • prompt_embeds (torch.Tensor, optional) — Предварительно вычисленные эмбеддинги промпта. Если указано, prompt можно опустить.
  • prompt_embeds_mask (torch.Tensor, optional) — Маска внимания для prompt_embeds.
  • negative_prompt_embeds (torch.Tensor, optional) — Предварительно вычисленные эмбеддинги отрицательного промпта.
  • negative_prompt_embeds_mask (torch.Tensor, optional) — Маска внимания для negative_prompt_embeds.
  • output_type (str, необязательный, по умолчанию "pil") — Формат вывода. Передайте "latent", чтобы вернуть необработанные латенты.
  • return_dict (bool, необязательный, по умолчанию True) — Определяет, возвращать ли JoyImageEditPipelineOutput или обычный тензор.
  • callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, optional) — Обработчик, вызываемый в конце каждого шага денойзинга с сигнатурой (self, step: int, timestep: int, callback_kwargs: Dict).
  • callback_on_step_end_tensor_inputs (List[str], optional, по умолчанию ["latents"]) — Ключи тензоров, включаемые в callback_kwargs для callback_on_step_end.
  • max_sequence_length (int, optional, по умолчанию 4096) — Максимальная длина последовательности для кодирования промпта.
  • enable_denormalization (bool, необязательный, по умолчанию True) — Убирает денормализацию латентов перед декодированием VAE.

Возвращает

[~pipelines.joyimage.JoyImageEditPipelineOutput] или torch.Tensor

Если return_dict равно True, возвращает объект вывода конвейера, содержащий сгенерированное изображение или изображения. В противном случае возвращает тензор изображения напрямую.

Сгенерируйте отредактированное изображение на основе опорного изображения и текстового запроса.

Примеры:

>>> import torch
>>> from diffusers import JoyImageEditPipeline
>>> from diffusers.utils import load_image

>>> model_id = "jdopensource/JoyAI-Image-Edit-Diffusers"
>>> pipe = JoyImageEditPipeline.from_pretrained(model_id, torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> image = load_image("https://huggingface.co/datasets/diffusers/docs-images/resolve/main/astronaut.jpg")
>>> output = pipe(
...     image=image,  # pass an image for editing; omit for text-to-image generation
...     prompt="Add wings to the astronaut.",
...     num_inference_steps=40,
...     guidance_scale=4.0,
...     generator=torch.manual_seed(0),
... )
>>> output.images[0].save("joyimage_edit.png")

check_inputs

< >

( promptheightwidthnegative_prompt = Noneprompt_embeds = Nonenegative_prompt_embeds = Noneprompt_embeds_mask = Nonenegative_prompt_embeds_mask = Nonecallback_on_step_end_tensor_inputs = None )

Исключения

ValueError

  • ValueError — при любой некорректной комбинации аргументов.

Проверяйте входные данные конвейера перед прямым проходом.

denormalize_latents

< >

( latent: Tensor )

Параметры

  • latent — Нормализованный латентный тензор.

Инвертируйте normalize_latents, чтобы восстановить исходный масштаб латентов.

encode_prompt

< >

( prompt: typing.Union[str, typing.List[str]]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1prompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonemax_sequence_length: int = 1024template_type: str = 'image' )

Параметры

  • prompt — строка-запрос или список строк-запросов.
  • device — Целевое устройство.
  • num_images_per_prompt — Количество генерируемых результатов на один запрос.
  • prompt_embeds — Предварительно вычисленные эмбеддинги промпта.
  • prompt_embeds_mask — Маска внимания для предварительно вычисленных эмбеддингов.
  • max_sequence_length — Максимальная длина выходной последовательности.
  • template_type — Ключ шаблона промпта ("image" или "multiple_images").

Кодируйте текстовый промпт в эмбеддинги (только текстовый путь).

Предварительно вычисленные prompt_embeds полностью обходят кодирование.

encode_prompt_multiple_images

< >

( prompt: typing.Union[str, typing.List[str]]device: typing.Optional[torch.device] = Nonenum_images_per_prompt: int = 1images: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneprompt_embeds_mask: typing.Optional[torch.Tensor] = Nonetemplate_type: typing.Optional[str] = 'multiple_images'max_sequence_length: typing.Optional[int] = None )

Параметры

  • prompt — Строка(и) с промптом, при необходимости содержащая токены <image>\n.
  • device — Целевое устройство.
  • num_images_per_prompt — Количество генерируемых результатов на один запрос.
  • images — тензоры пикселей, соответствующие встроенным токенам изображений.
  • prompt_embeds — Предварительно вычисленные эмбеддинги промпта.
  • prompt_embeds_mask — Маска внимания для предварительно вычисленных эмбеддингов.
  • template_type — должно быть "multiple_images".
  • max_sequence_length — если задано, обрезает вывод до этой длины (сохраняя последние max_sequence_length токенов).

Кодируйте промпты, содержащие встроенные токены изображений, с помощью процессора Qwen.

<image>\n в каждой строке запроса заменяются специальными токенами зрения Qwen перед передачей в мультимодальный кодировщик.

normalize_latents

< >

( latent: Tensor )

Параметры

  • latent — Исходный тензор латентного пространства из vae.encode.

Нормализуйте латенты с использованием статистики по каналам из конфигурации VAE.

Использует (latent - mean) / std, если VAE предоставляет latents_mean и latents_std; в противном случае использует масштабирование с помощью scaling_factor.

prepare_latents

< >

( batch_size: intnum_channels_latents: intheight: intwidth: intvideo_length: intdtype: dtypedevice: devicegenerator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType]latents: typing.Optional[torch.Tensor] = Noneimage: typing.Optional[typing.List[PIL.Image.Image]] = Noneenable_denormalization: bool = True )

Параметры

  • batch_size — количество образцов в батче.
  • num_channels_latents — Размерность латентных каналов из конфигурации трансформера.
  • height — Пространственная высота в пикселях.
  • width — Пространственная ширина в пикселях.
  • video_length — Количество кадров (1 для инференса изображений).
  • dtype — Тип данных с плавающей точкой для тензора латентов.
  • device — Целевое устройство.
  • generator — генератор(ы) случайных чисел для воспроизводимой выборки.
  • latents — Необязательный параметр. Начальный шум, предоставленный пользователем для целевого слота. Если значение равно None, шум генерируется случайно.
  • image — Необязательный список эталонных изображений в формате PIL для кодирования VAE в качестве слотов условий.
  • enable_denormalization — Нужно ли нормализовать закодированные референсные латенты.

Исключения

ValueError

  • ValueError — если generator является списком, длина которого отличается от batch_size.

Подготовьте начальный шумовой тензор латентов для цикла денуазинга.

JoyImageEditPipelineOutput

класс diffusers.JoyImageEditPipelineOutput

< >

( images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray] )

Класс вывода для конвейеров генерации JoyImageEdit.

Update on GitHub

←InstructPix2Pix JoyImage Edit Plus→