Diffusers documentation

JoyAI-Image-Edit

Diffusers

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).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

JoyAI-Image-Edit

JoyAI-Image là một mô hình nền tảng đa phương thức thống nhất cho việc hiểu hình ảnh, tạo hình ảnh từ văn bản và chỉnh sửa hình ảnh theo hướng dẫn. Nó kết hợp một Mô hình Ngôn ngữ Lớn Đa phương thức (MLLM) 8B với một Transformer Khuếch tán Đa phương thức (MMDiT) 16B. Một nguyên tắc cốt lõi của JoyAI-Image là sự hợp tác khép kín giữa việc hiểu, tạo và chỉnh sửa.

JoyAI-Image-Edit hỗ trợ chỉnh sửa hình ảnh chung cũng như các khả năng chỉnh sửa không gian bao gồm di chuyển đối tượng, xoay đối tượng và kiểm soát camera.

Mô hình	Mô tả	Tải xuống
JoyAI-Image-Edit	Chỉnh sửa hình ảnh theo hướng dẫn với thao tác không gian chính xác và có thể kiểm soát	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")

Chỉnh sửa không gian

JoyAI-Image hỗ trợ ba mẫu prompt chỉnh sửa không gian: Di chuyển đối tượng, Xoay đối tượng và Điều khiển camera. Để đạt kết quả tốt nhất, hãy tuân thủ các mẫu prompt bên dưới càng sát càng tốt. Để biết thêm thông tin, hãy tham khảo SpatialEdit.

Di chuyển đối tượng

Di chuyển một đối tượng đích vào một vùng được chỉ định, đánh dấu bằng một hộp màu đỏ, trong hình ảnh đầu vào.

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

Xoay Đối tượng

Xoay một đối tượng sang một góc nhìn chuẩn cụ thể. Các giá trị <view> được hỗ trợ: front, right, left, rear, front right, front left, rear right, rear left.

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

Điều khiển Camera

Thay đổi góc nhìn của camera trong khi giữ nguyên cảnh 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

lớp diffusers.JoyImageEditPipeline

< source >

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

Pipeline khuếch tán để chỉnh sửa hình ảnh sử dụng kiến trúc JoyImage.

Pipeline mã hóa điều kiện văn bản và hình ảnh thông qua trình mã hóa văn bản Qwen3-VL, khử nhiễu các biến tiềm ẩn bằng một transformer 3 chiều, và giải mã kết quả bằng WAN VAE.

Thứ tự offloading mô hình: text_encoder -> transformer -> vae.

call

< source >

( 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

Tham số

prompt (str hoặc List[str]) — Prompt hoặc các prompt để định hướng quá trình tạo.
height (int) — Chiều cao của đầu ra được tạo ra, tính bằng pixel.
width (int) — Chiều rộng của đầu ra được tạo ra, tính bằng pixel.
image (PipelineImageInput, tuỳ chọn) — Hình ảnh tham chiếu được dùng để điều kiện hóa. Khi được cung cấp, pipeline sẽ hoạt động ở chế độ chỉnh sửa hình ảnh với num_items=2.
num_inference_steps (int, tuỳ chọn, mặc định là 40) — Số bước khử nhiễu. Nhiều bước hơn thường cải thiện chất lượng nhưng đổi lại suy luận sẽ chậm hơn.
timesteps (List[int], tuỳ chọn) — Các bước thời gian (timesteps) tùy chỉnh cho quá trình khử nhiễu. Khi được cung cấp, num_inference_steps sẽ được suy ra từ độ dài của danh sách.
sigmas (List[float], tuỳ chọn) — Các sigma tùy chỉnh cho quá trình khử nhiễu. Loại trừ lẫn nhau với timesteps.
guidance_scale (float, tuỳ chọn, mặc định là 4.0) — Thang độ hướng dẫn không phân loại (classifier-free guidance).
negative_prompt (str hoặc List[str], tùy chọn) — Prompt âm dùng để hạn chế nội dung không mong muốn.
num_images_per_prompt (int, tuỳ chọn, mặc định là 1) — Số lượng mẫu được tạo ra cho mỗi prompt.
generator (torch.Generator hoặc List[torch.Generator], tùy chọn) — Bộ tạo RNG cho việc lấy mẫu xác định.
latents (torch.Tensor, optional) — Các latents nhiễu đã được tạo trước cho slot đích. Được lấy mẫu từ phân phối Gaussian khi không được cung cấp. Có thể được sử dụng để khởi tạo quá trình sinh từ một tensor nhiễu cụ thể.
prompt_embeds (torch.Tensor, optional) — Các embedding của prompt đã được tính trước. Khi được cung cấp, prompt có thể được bỏ qua.
prompt_embeds_mask (torch.Tensor, optional) — Mặt nạ chú ý cho prompt_embeds.
negative_prompt_embeds (torch.Tensor, optional) — Các embedding của prompt âm đã được tính trước.
negative_prompt_embeds_mask (torch.Tensor, optional) — Mặt nạ chú ý cho negative_prompt_embeds.
output_type (str, tuỳ chọn, mặc định là "pil") — Định dạng đầu ra. Truyền "latent" để trả về các latent thô.
return_dict (bool, tuỳ chọn, mặc định là True) — Có nên trả về một JoyImageEditPipelineOutput hay một tensor thông thường hay không.
callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, optional) — Callback được gọi vào cuối mỗi bước khử nhiễu với chữ ký (self, step: int, timestep: int, callback_kwargs: Dict).
callback_on_step_end_tensor_inputs (List[str], tuỳ chọn, mặc định là ["latents"]) — Các khóa tensor được bao gồm trong callback_kwargs cho callback_on_step_end.
max_sequence_length (int, optional, mặc định là 4096) — Độ dài tối đa của chuỗi cho việc mã hóa prompt.
enable_denormalization (bool, tuỳ chọn, mặc định là True) — Khử chuẩn hóa các biến tiềm năng trước khi giải mã VAE.

Trả về

[~pipelines.joyimage.JoyImageEditPipelineOutput] hoặc torch.Tensor

Nếu return_dict là True, trả về một đối tượng đầu ra của pipeline chứa hình ảnh đã được tạo. Ngược lại, trả về trực tiếp tensor hình ảnh.

Tạo một hình ảnh đã chỉnh sửa dựa trên một hình ảnh tham chiếu và một câu lệnh văn bản.

Ví dụ:

>>> 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

< source >

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

Gây ra

ValueError

ValueError — Với bất kỳ tổ hợp tham số nào không hợp lệ.

Xác thực đầu vào của pipeline trước bước truyền thuận.

denormalize_latents

< source >

( latent: Tensor )

Tham số

latent — Tensor latent đã được chuẩn hóa.

Đảo ngược normalize_latents để khôi phục thang đo latent ban đầu.

encode_prompt

< source >

( 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' )

Tham số

prompt — Chuỗi hoặc danh sách các chuỗi prompt.
device — Thiết bị đích.
num_images_per_prompt — Số lượng đầu ra cần tạo cho mỗi prompt.
prompt_embeds — Các embedding của prompt đã được tính toán trước.
prompt_embeds_mask — Mặt nạ chú ý cho các embedding đã tính toán trước.
max_sequence_length — Độ dài tối đa của chuỗi đầu ra.
template_type — Khóa mẫu prompt ("image" hoặc "multiple_images").

Mã hóa một prompt văn bản thành các embedding (đường dẫn chỉ văn bản).

prompt_embeds được tính trước sẽ bỏ qua hoàn toàn quá trình mã hóa.

encode_prompt_multiple_images

< source >

( 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 )

Tham số

prompt — Prompt string(s), optionally containing <image>\n tokens.
device — Thiết bị đích.
num_images_per_prompt — Số lượng đầu ra cần tạo cho mỗi prompt.
images — Các tensor pixel tương ứng với các token hình ảnh inline.
prompt_embeds — Các embedding của prompt đã được tính toán trước.
prompt_embeds_mask — Mặt nạ chú ý cho các embedding đã tính toán trước.
template_type — Phải là "multiple_images".
max_sequence_length — Nếu được đặt, cắt ngắn đầu ra xuống độ dài này (giữ lại max_sequence_length token cuối cùng).

Mã hóa các prompt chứa các token hình ảnh inline thông qua bộ xử lý Qwen.

Các placeholder <image>\n trong mỗi chuỗi prompt sẽ được thay thế bằng các token đặc biệt của thị giác Qwen trước khi được đưa vào bộ mã hóa đa phương tiện.

normalize_latents

< source >

( latent: Tensor )

Tham số

latent — Tensor latent thô từ vae.encode.

Chuẩn hóa các biến tiềm ẩn (latents) bằng cách sử dụng thống kê theo kênh (per-channel) từ cấu hình VAE.

Sử dụng (latent - mean) / std khi VAE cung cấp latents_mean và latents_std; nếu không, sẽ chuyển sang thang bằng scaling_factor.

prepare_latents

< source >

( 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 )

Tham số

batch_size — Số lượng mẫu trong batch.
num_channels_latents — Kích thước chiều kênh latent từ cấu hình transformer.
height — Chiều cao không gian tính bằng pixel.
width — Chiều rộng không gian tính bằng pixel.
video_length — Số lượng khung hình (1 cho suy luận ảnh).
dtype — Kiểu dữ liệu số thực động (floating-point) cho tensor ẩn (latent tensor).
device — Thiết bị đích.
generator — bộ tạo số ngẫu nhiên (RNG) để lấy mẫu có thể tái lập.
latents — Ban đầu nhiễu do người dùng cung cấp tùy chọn cho slot đích. Khi None, nhiễu ngẫu nhiên sẽ được lấy mẫu.
image — Danh sách tùy chọn các hình ảnh tham chiếu PIL để mã hóa bằng VAE làm các vị trí điều kiện.
enable_denormalization — Có nên chuẩn hóa các latents tham chiếu đã mã hóa hay không.

Gây ra

ValueError

ValueError — Nếu generator là một danh sách có độ dài khác với batch_size.

Chuẩn bị tensor latent nhiễu ban đầu cho vòng lặp khử nhiễu.

JoyImageEditPipelineOutput

lớp diffusers.JoyImageEditPipelineOutput

< source >

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

Lớp đầu ra cho các pipeline tạo JoyImageEdit.

Update on GitHub

←InstructPix2Pix JoyImage Edit Plus→

Diffusers

JoyAI-Image-Edit

Chỉnh sửa không gian

Di chuyển đối tượng

Xoay Đối tượng

Điều khiển Camera

JoyImageEditPipeline

lớp diffusers.JoyImageEditPipeline

__call__

check_inputs

denormalize_latents

encode_prompt

encode_prompt_multiple_images

normalize_latents

prepare_latents

JoyImageEditPipelineOutput

lớp diffusers.JoyImageEditPipelineOutput

call