# JoyAI-Image-Edit-Plus

[JoyAI-Image](https://github.com/jd-opensource/JoyAI-Image) 是一个用于图像理解、文生图以及指令引导图像编辑的统一多模态基础模型。它将一个 8B 多模态大语言模型（MLLM）与一个 16B 多模态扩散 Transformer（MMDiT）相结合。

JoyAI-Image-Edit-Plus 是一个多图像指令引导的编辑模型，它接受**多张参考图像**和一条文本指令，根据指令生成一张融合参考图像中元素的新图像。每个样本支持 1–5 张参考图像。

| 模型 | 描述 | 下载 |
|:-----:|:-----------:|:--------:|
| JoyAI-Image-Edit-Plus | 基于多参考图的元素组合，实现多图指令引导编辑 | [Hugging Face](https://huggingface.co/jdopensource/JoyAI-Image-Edit-Plus-Diffusers) |

```python
import torch
from PIL import Image
from diffusers import JoyImageEditPlusPipeline

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

images = [
    Image.open("reference_0.png").convert("RGB"),
    Image.open("reference_1.png").convert("RGB"),
]

target_h, target_w = pipeline.image_processor.get_default_height_width(images[-1])

output = pipeline(
    images=images,
    prompt="Combine the person from the second image with the scene from the first image.",
    negative_prompt="low quality, blurry, deformed",
    height=target_h,
    width=target_w,
    num_inference_steps=30,
    guidance_scale=4.0,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
output.save("joyimage_edit_plus_output.png")
```

## JoyImageEditPlusPipeline[[diffusers.JoyImageEditPlusPipeline]]

#### diffusers.JoyImageEditPlusPipeline[[diffusers.JoyImageEditPlusPipeline]]

```python
diffusers.JoyImageEditPlusPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLWan, text_encoder: Qwen3VLForConditionalGeneration, tokenizer: Qwen2Tokenizer, transformer: JoyImageEditPlusTransformer3DModel, processor: Qwen3VLProcessor, text_token_max_length: int = 2048)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/joyimage/pipeline_joyimage_edit_plus.py#L129)

**参数：**

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler))：用于与 `transformer` 配合，对编码后的图像潜变量进行去噪的调度器。

vae ([AutoencoderKLWan](/docs/diffusers/v0.43.0/zh/api/models/autoencoder_kl_wan#diffusers.AutoencoderKLWan))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，以及从潜在表示解码为图像。

text_encoder (`Qwen3VLForConditionalGeneration`)：多模态文本编码器，用于提示编码，支持内联图像理解。

tokenizer (`Qwen2Tokenizer`)：用于文本处理的分词器。

transformer ([JoyImageEditPlusTransformer3DModel](/docs/diffusers/v0.43.0/zh/api/models/transformer_joyimage_edit_plus#diffusers.JoyImageEditPlusTransformer3DModel))：用于对编码后的图像潜在变量进行去噪的条件 Transformer (MMDiT) 架构。

processor (`Qwen3VLProcessor`)：用于多模态输入（文本 + 图像）的处理器。

text_token_max_length (`int`，默认为 `2048`)：文本编码的最大 token 长度。

使用 JoyImage Edit Plus 进行多图像指令引导编辑的扩散流水线。

支持使用不同分辨率的多张参考图像。每张参考图像会独立进行 VAE 编码和分块处理，然后与目标噪声块拼接，用于联合去噪。

#### __调用__[[diffusers.JoyImageEditPlusPipeline.__call__]]

```python
__call__(images: list[PIL.Image.Image] | list[list[PIL.Image.Image]] | None = None, prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 30, timesteps: list[int] = None, sigmas: list[float] = None, guidance_scale: float = 4.0, negative_prompt: str | list[str] | None = None, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_mask: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, callback_on_step_end: typing.Union[typing.Callable[[int, int, dict], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], max_sequence_length: int = 4096)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/joyimage/pipeline_joyimage_edit_plus.py#L441)

**参数：**

images (`list[Image.Image]` 或 `list[list[Image.Image]]`，*可选*) : 用于编辑的参考图像。每幅图像可以具有不同的分辨率。如果提供的是扁平列表，则将其视为包含多个参考图像的一个样本。

prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的提示词或提示词列表。如果未定义，则必须传入 `prompt_embeds`。

height (`int`, *可选*) : 生成图像的高度（以像素为单位）。如果为 `None`，则从最后一张参考图像中确定。

width (`int`, *可选*) : 生成图像的像素宽度。如果为 `None`，则根据最后一张参考图像确定。

num_inference_steps (`int`，*可选*，默认值为 `30`)：去噪步数。更多的去噪步数通常能生成更高质量的图像，但代价是推理速度变慢。

timesteps (`list[int]`, *可选*) : 用于去噪过程的自定义时间步。如果未定义，则使用等间距。

sigmas (`list[float]`, *可选*) : 用于去噪过程的自定义 sigmas。

guidance_scale (`float`，*可选*，默认值为 `4.0`)：无分类器引导（Classifier-free guidance）的缩放系数。较高的值会促使模型生成与 `prompt` 更一致的图片，但代价是图像质量降低。

negative_prompt (`str` 或 `list[str]`，*可选*)：用于引导图像生成的负面提示词。如果未定义，则使用空白提示词进行无分类器引导。

generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：一个或一组 [torch 生成器](https://pytorch.org/docs/stable/generated/torch.Generator.html)，用于使生成过程具有确定性。

latents (`torch.Tensor`, *可选*) : 预生成的噪声潜变量，用作图像生成的输入。

prompt_embeds (`torch.Tensor`, *可选*) : 预生成的文本嵌入。可用于轻松调整文本输入。

prompt_embeds_mask (`torch.Tensor`, *可选*) : 用于预生成文本嵌入的注意力掩码。

negative_prompt_embeds (`torch.Tensor`, *可选*) : 预生成的负文本嵌入。

negative_prompt_embeds_mask (`torch.Tensor`, *可选*) : 用于预生成的负文本嵌入的注意力掩码。

output_type (`str`，*可选*，默认为 `"pil"`)：生成图像的输出格式。可选 `"pil"`（`PIL.Image.Image`）、`"np"`（`np.ndarray`）、`"pt"`（`torch.Tensor`）或 `"latent"`（原始潜在输出）。

return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [JoyImageEditPlusPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/joyimage_edit_plus#diffusers.JoyImageEditPlusPipelineOutput) 而不是普通元组。

callback_on_step_end (`Callable`，*可选*)：在每个去噪步骤结束时调用的函数，参数包括：pipeline、步骤索引、timestep 以及包含回调张量输入的字典。

callback_on_step_end_tensor_inputs (`list[str]`，*可选*，默认为 `["latents"]`)：`callback_on_step_end` 函数的张量输入列表。

max_sequence_length (`int`，*可选*，默认为 `4096`)：文本编码器的最大序列长度。

**返回：** [JoyImageEditPlusPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/joyimage_edit_plus#diffusers.JoyImageEditPlusPipelineOutput) 或 `tuple`

如果 `return_dict` 为 `True`，则返回 [JoyImageEditPlusPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/joyimage_edit_plus#diffusers.JoyImageEditPlusPipelineOutput)；否则返回一个 `tuple`，其中第一个元素是生成图像的列表。

调用生成 pipeline 时调用的函数。

示例：
```python
>>> import torch
>>> from diffusers import JoyImageEditPlusPipeline
>>> from diffusers.utils import load_image

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

>>> images = [
...     load_image("dog.png"),
...     load_image("person.png"),
... ]
>>> output = pipe(
...     images=images,
...     prompt="Let the person lovingly play with the dog.",
...     height=1024,
...     width=1024,
...     num_inference_steps=30,
...     guidance_scale=4.0,
...     generator=torch.manual_seed(42),
... )
>>> output.images[0].save("output.png")
```

#### encode_prompt_multiple_images[[diffusers.JoyImageEditPlusPipeline.encode_prompt_multiple_images]]

```python
encode_prompt_multiple_images(prompt: str | list[str], device: typing.Optional[torch.device] = None, images: list[PIL.Image.Image] | None = None, max_sequence_length: int | None = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/joyimage/pipeline_joyimage_edit_plus.py#L229)

通过 Qwen3-VL 处理器对包含内联 tokens 的提示进行编码。

#### prepare_latents[[diffusers.JoyImageEditPlusPipeline.prepare_latents]]

```python
prepare_latents(batch_size: int, num_channels_latents: int, height: int, width: int, dtype: dtype, device: device, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType], reference_images: list[list[PIL.Image.Image]] | None = None, latents: typing.Optional[torch.Tensor] = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/joyimage/pipeline_joyimage_edit_plus.py#L274)

**参数：**

latents : 可选的针对目标槽位的预计算噪声。形状为 `(B, C, 1, H', W')`，其中 `H'` 和 `W'` 是潜在空间的维度。当为 `None` 时，将采样随机噪声。

**返回：** `padded_latents`

[B, max_patches, C, pt, ph, pw] target_mask: [B, max_patches]（目标 patch 为 True）shape_list: 每个样本的 (t, h, w) 元组列表，对应每个组件

准备 6D 填充后的潜在张量，包含目标噪声和参考图像的潜在表示。

## JoyImageEditPlusPipelineOutput[[diffusers.JoyImageEditPlusPipelineOutput]]

#### diffusers.JoyImageEditPlusPipelineOutput[[diffusers.JoyImageEditPlusPipelineOutput]]

```python
diffusers.JoyImageEditPlusPipelineOutput(images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray])
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/joyimage/pipeline_output.py#L20)

JoyImage Edit Plus 多图像编辑流水线的输出类。