Hugging Face's logo

Diffusers documentation

JoyAI-Image-Edit

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→