Diffusers documentation
JoyAI-Image-Edit
JoyAI-Image-Edit
JoyAI-Image هو نموذج أساسي متعدد الوسائط موحّد لفهم الصور، وتوليد الصور من النص، وتحرير الصور وفق التعليمات. يجمع بين نموذج لغة كبير متعدد الوسائط (MLLM) بحجم 8B، ومحوّل انتشار متعدد الوسائط (MMDiT) بحجم 16B. مبدأ محوري في 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 ثلاثة أنماط لأوامر التحرير المكاني: نقل الكائن، وتدوير الكائن، والتحكم في الكاميرا. للحصول على أفضل النتائج، اتبع قوالب الأوامر أدناه بأقرب ما يمكن. لمزيد من المعلومات، راجع 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.
التحكم في الكاميرا
غيّر زاوية الكاميرا مع إبقاء المشهد ثلاثي الأبعاد دون تغيير.
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.
يقوم خط المعالجة بتشفير شروط النص والصورة عبر مشفّر نصوص Qwen3-VL، وإزالة الضوضاء من الكمونيات باستخدام محوّل ثلاثي الأبعاد، وفك ترميز النتيجة باستخدام 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], اختياري) —
خطوات زمنية مخصصة لعملية إزالة الضوضاء. عند تقديمها، يُستنتج
num_inference_stepsمن طول القائمة. - sigmas (List[float], اختياري) —
قيم sigmas مخصصة لعملية إزالة الضوضاء. يتعارض مع
timesteps. - guidance_scale (float، اختياري، القيمة الافتراضية 4.0) — مقياس التوجيه الحر من التصنيف.
- negative_prompt (str أو List[str]، اختياري) — الموجّهات السلبية المستخدمة لكبح المحتوى غير المرغوب فيه.
- 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، اختياري) —
قناع الانتباه لـ
prompt_embeds. - negative_prompt_embeds (torch.Tensor، اختياري) — تضمينات سلبية مُسبقة الحساب.
- negative_prompt_embeds_mask (torch.Tensor، اختياري) —
قناع الانتباه (Attention mask) الخاص بـ
negative_prompt_embeds. - output_type (str، اختياري، الافتراضي
"pil") — صيغة الإخراج. مرّر"latent"لإرجاع الكمونيات الخام. - return_dict (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب إرجاع JoyImageEditPipelineOutput أو مجرد tensor.
- callback_on_step_end (Callable، PipelineCallback، MultiPipelineCallbacks، اختياري) —
دالة استدعاء تُستدعى في نهاية كل خطوة إزالة ضوضاء، وتوقيعها
(self, step: int, timestep: int, callback_kwargs: Dict). - callback_on_step_end_tensor_inputs (List[str]، اختياري، القيمة الافتراضية
["latents"]) — مفاتيح المصفوفات (Tensor) المضمنة فيcallback_kwargsالخاصة بـcallback_on_step_end. - max_sequence_length (int، اختياري، القيمة الافتراضية 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
< source >( promptheightwidthnegative_prompt = Noneprompt_embeds = Nonenegative_prompt_embeds = Noneprompt_embeds_mask = Nonenegative_prompt_embeds_mask = Nonecallback_on_step_end_tensor_inputs = None )
يرفع
ValueError
ValueError— عند أي مجموعة غير صالحة من الحُجج.
تحقق من مدخلات خط الأنابيب قبل المرور الأمامي.
عكس normalize_latents لاستعادة مقياس الكمون الأصلي.
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 — نص الأمر أو قائمة بنصوص الأوامر.
- device — الجهاز المستهدف.
- num_images_per_prompt — عدد المخرجات التي سيتم توليدها لكل موجه.
- prompt_embeds — تمثيلات مُسبقة الحساب للموجّه.
- prompt_embeds_mask — قناع الانتباه للتضمينات المحسوبة مسبقًا.
- max_sequence_length — الحد الأقصى لطول التسلسل الناتج.
- template_type — مفتاح قالب الإحاطة (
"image"أو"multiple_images").
ترميز موجه نصي إلى تمثيلات (مسار النص فقط).
تتجاوز 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 — نص أو نصوص الأمر (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.
يستخدم (الكامن - المتوسط) / الانحراف المعياري عندما يعرض VAE latents_mean وlatents_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 — بُعد قناة الحالة الكامنة من إعدادات المحوّل.
- height — الارتفاع المكاني بالبكسل.
- width — العرض المكاني بالبكسل.
- video_length — عدد الإطارات (1 للاستدلال على الصور).
- dtype — نوع البيانات العشري (Floating-point) للمصفوفة الكامنة (latent tensor).
- device — الجهاز المستهدف.
- generator — مولّدات الأرقام العشوائية (RNG) للعينة القابلة للتكرار.
- latents — ضوضاء أولية اختيارية يوفّرها المستخدم للفتحة المستهدفة. عند تعيين
Noneيتم أخذ عينة من ضوضاء عشوائية. - image — قائمة اختيارية لصور مرجعية بصيغة PIL يتم ترميزها بواسطة VAE كفتحات شرطية.
- enable_denormalization — ما إذا كان سيتم تطبيع الكامنات المرجعية المُرمّزة.
يرفع
ValueError
ValueError— إذا كانgeneratorقائمة يختلف طولها عنbatch_size.
جهّز متجه الكامنة الضوضائي الأولي لحلقة إزالة الضوضاء.
JoyImageEditPipelineOutput
فئة diffusers.JoyImageEditPipelineOutput
< source >( images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray] )
فئة الإخراج لخطوط أنابيب توليد JoyImageEdit.