Diffusers documentation
JoyAI-Image-Edit
JoyAI-Image-Edit
JoyAI-Image는 이미지 이해, 텍스트-이미지 생성, 지시 기반 이미지 편집을 위한 통합 멀티모달 파운데이션 모델입니다. 8B 멀티모달 대규모 언어 모델(MLLM)과 16B 멀티모달 디퓨전 트랜스포머(MMDiT)를 결합합니다. 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
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLWantext_encoder: Qwen3VLForConditionalGenerationtokenizer: Qwen2Tokenizertransformer: JoyImageEditTransformer3DModelprocessor: Qwen3VLProcessortext_token_max_length: int = 2048 )
JoyImage 아키텍처를 사용하여 이미지 편집을 위한 Diffusion 파이프라인입니다.
파이프라인은 Qwen3-VL 텍스트 인코더를 통해 텍스트와 이미지 조건을 인코딩하고, 3-D 트랜스포머로 잠재 변수를 디노이즈한 후, WAN VAE로 결과를 디코딩합니다.
모델 오프로딩 순서: 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
매개변수
- prompt (str 또는 List[str]) — 생성을 안내할 프롬프트입니다.
- height (int) — 생성된 출력의 픽셀 단위 높이.
- width (int) — 생성된 출력의 픽셀 단위 폭.
- image (PipelineImageInput, 선택 사항) —
조건부 생성에 사용되는 참조 이미지. 제공되면 파이프라인은
num_items=2로 이미지 편집 모드로 작동합니다. - num_inference_steps (int, 선택 사항, 기본값 40) — 디노이징 단계 수. 단계가 많을수록 일반적으로 품질이 향상되지만 추론 속도는 느려집니다.
- timesteps (List[int], 선택 사항) —
노이즈 제거 과정에 사용할 커스텀 timesteps입니다. 값이 제공되면
num_inference_steps는 리스트의 길이에서 추론됩니다. - sigmas (List[float], 선택 사항) —
노이즈 제거 과정에 사용할 커스텀 시그마입니다.
timesteps와 상호 배타적입니다. - guidance_scale (float, 선택 사항, 기본값 4.0) — Classifier-free guidance scale입니다.
- negative_prompt (str 또는 List[str], 선택 사항) — 원치 않는 콘텐츠를 억제하는 데 사용되는 negative prompt입니다.
- num_images_per_prompt (int, 선택 사항, 기본값 1) — 프롬프트당 생성되는 샘플 수.
- generator (torch.Generator 또는 List[torch.Generator], 선택 사항) — 결정론적 샘플링을 위한 RNG 생성기입니다.
- latents (torch.Tensor, 선택 사항) — 대상 슬롯에 사용할 사전 생성된 노이즈 latents입니다. 제공되지 않으면 가우시안 분포에서 샘플링됩니다. 특정 시작 노이즈 텐서로부터 생성을 시작하기 위한 시드로 사용할 수 있습니다.
- prompt_embeds (torch.Tensor, 선택) —
미리 계산된 프롬프트 임베딩입니다. 이 값을 제공하면
prompt를 생략할 수 있습니다. - prompt_embeds_mask (torch.Tensor, optional) —
prompt_embeds에 대한 어텐션 마스크입니다. - negative_prompt_embeds (torch.Tensor, optional) — 사전 계산된 negative prompt 임베딩입니다.
- negative_prompt_embeds_mask (torch.Tensor, 선택 사항) —
negative_prompt_embeds에 대한 어텐션 마스크입니다. - output_type (str, 선택 사항, 기본값
"pil") — 출력 형식입니다."latent"를 전달하면 원시 latent를 반환합니다. - return_dict (bool, optional, defaults to True) — Whether to return a JoyImageEditPipelineOutput or a plain tensor.
- callback_on_step_end (Callable, PipelineCallback, MultiPipelineCallbacks, optional) —
각 디노이징 단계의 끝에서 호출되는 콜백으로, 시그니처는
(self, step: int, timestep: int, callback_kwargs: Dict)입니다. - callback_on_step_end_tensor_inputs (List[str], 선택 사항, 기본값
["latents"]) —callback_on_step_end의callback_kwargs에 포함되는 텐서 키입니다. - max_sequence_length (int, 선택 사항, 기본값 4096) — 프롬프트 인코딩을 위한 최대 시퀀스 길이입니다.
- enable_denormalization (bool, 선택 사항, 기본값 True) — VAE 디코딩 전에 latents를 비정규화합니다.
반환값
[~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
< source >( promptheightwidthnegative_prompt = Noneprompt_embeds = Nonenegative_prompt_embeds = Noneprompt_embeds_mask = Nonenegative_prompt_embeds_mask = Nonecallback_on_step_end_tensor_inputs = None )
발생
ValueError
ValueError— 인수의 잘못된 조합이 있는 경우.
Forward pass 전에 파이프라인 입력을 검증합니다.
normalize_latents를 역으로 적용하여 원래의 latent 스케일을 복원합니다.
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' )
텍스트 프롬프트를 임베딩으로 인코딩합니다(텍스트 전용 경로).
prompt_embeds가 사전 계산되어 있으면 인코딩을 완전히 우회합니다.
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 )
매개변수
- 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 비전 특수 토큰으로 대체됩니다.
VAE 구성에서 채널별 통계를 사용하여 latents를 정규화합니다.
VAE가 latents_mean과 latents_std를 노출하는 경우 (latent - mean) / std를 사용하며, 그렇지 않으면 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 )
매개변수
- batch_size — 배치에 포함된 샘플 수.
- num_channels_latents — transformer 설정에서 가져온 Latent 채널 차원.
- height — 픽셀 단위의 공간적 높이.
- width — 픽셀 단위의 공간적 폭.
- video_length — 프레임 수(이미지 추론의 경우 1).
- dtype — 잠재 변수 텐서의 부동 소수점 dtype입니다.
- device — 대상 장치.
- generator — 재현 가능한 샘플링을 위한 RNG 생성기.
- latents — 대상 슬롯에 사용할 선택적 사용자 지정 초기 노이즈입니다.
None인 경우 무작위 노이즈가 샘플링됩니다. - image — VAE 인코딩하여 조건 슬롯으로 사용할 PIL 참조 이미지의 선택적 목록.
- enable_denormalization — 인코딩된 참조 latents를 정규화할지 여부.
발생
ValueError
ValueError—generator가batch_size와 길이가 다른 리스트인 경우.
디노이징 루프를 위한 초기 노이즈가 포함된 잠재 텐서를 준비합니다.
JoyImageEditPipelineOutput
클래스 diffusers.JoyImageEditPipelineOutput
< source >( images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray] )
JoyImageEdit 생성 파이프라인의 출력 클래스입니다.