Diffusers documentation
Krea 2
Krea 2
نموذج Krea 2 (K2) هو نموذج لتوليد الصور من النص يعتمد على مطابقة التدفق (flow-matching) ويُبنى حول مكوّن MMDiT أحادي التيار مع انتباه الاستعلامات المجمّعة (grouped-query attention). يوفر مُشفّر النص Qwen3-VL شروط التوليد: بدلاً من استخدام حالة المخفي الأخيرة، تُستخرج حالات المخفي من اثني عشر طبقة فكّ ترميز لكل رمز وتُدمج داخل محوّل التحويل (transformer) عبر مرحلة دمج نصي صغيرة. وتُفكّ ترميز الصور باستخدام VAE الخاص بـ Qwen-Image.
تم إصدار نقطتي تفتيش، تتشاركان في نفس البنية المعمارية لكن مع إعدادات مُوصى بها مختلفة لمُعيّن العينات:
- الأساسي (التدريب المتوسط) — استخدم المُعيّن الكامل مع التوجيه الحر من التصنيف:
num_inference_steps=28،guidance_scale=4.5. - تي دي إم (مُقطَّر) — مُقطَّر لأخذ عينات بعدد خطوات قليل، يُشغَّل مع
num_inference_steps=8وإيقاف التوجيه (guidance_scale=0.0).
يتبع guidance_scale اتفاقية Krea 2: حيث يُحسب السرعة على النحو cond + guidance_scale * (cond - uncond) ويُفعَّل التوجيه عندما يكون guidance_scale > 0 (وهذا يعادل صياغة CFG المعتادة مع مقياس 1 + guidance_scale).
النص إلى صورة
import torch
from diffusers import Krea2Pipeline
# Load from a local directory produced by the Krea 2 conversion (no hub repo yet).
pipe = Krea2Pipeline.from_pretrained("krea/Krea-2-Raw", dtype=torch.bfloat16)
pipe.to("cuda") # or "mps", "xpu", "cpu"
prompt = "a fox in the snow"
image = pipe(
prompt,
height=1024,
width=1024,
num_inference_steps=28,
guidance_scale=4.5,
generator=torch.Generator("cuda").manual_seed(0),
).images[0]
image.save("krea2.png")نوفر أيضًا مثالًا لاستخدام Krea2 Turbo :
import torch
from diffusers import Krea2Pipeline
pipe = Krea2Pipeline.from_pretrained("krea/Krea-2-Turbo", dtype=torch.bfloat16)
pipe.to("cuda") # or "mps", "xpu", "cpu"
image = pipe(
"a fox in the snow",
height=1024,
width=1024,
num_inference_steps=8,
guidance_scale=0.0,
generator=torch.Generator("cuda").manual_seed(0),
).images[0]
image.save("krea2_turbo.png")تحميل نقاط التفتيش أحادية الملف
import torch
from diffusers import Krea2Pipeline, Krea2Transformer2DModel
transformer = Krea2Transformer2DModel.from_single_file(
"https://huggingface.co/krea/Krea-2-Turbo/blob/main/turbo.safetensors", dtype=torch.bfloat16
)
pipe = Krea2Pipeline.from_pretrained("krea/Krea-2-Turbo", transformer=transformer, dtype=torch.bfloat16).to("cuda")Krea2Pipeline
فئة diffusers.Krea2Pipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLQwenImagetext_encoder: Qwen3VLModeltokenizer: AutoTokenizertransformer: Krea2Transformer2DModeltext_encoder_select_layers: tuple[int, ...] | list[int] | None = Noneis_distilled: bool = Falsepatch_size: int = 2 )
المعاملات
- scheduler (FlowMatchEulerDiscreteScheduler) —
جدولة أويلر لمطابقة التدفق. جدول سيجما الخاص بـ Krea 2 هو إزاحة زمنية أسية واعية بالدقة، لذا يُتوقع أن يحدد تكوين الجدولة
use_dynamic_shifting=Trueمعًا مع معاملات الإزاحة الخاصة بـ Krea 2 (base_shift=0.5،max_shift=1.15،base_image_seq_len=256،max_image_seq_len=6400). - vae (AutoencoderKLQwenImage) — شيفرة الترميز التحويلية (Variational Auto-Encoder) الخاصة بـ Qwen-Image (f8، 16 قناة كامنة) المستخدمة لفك ترميز الكامنات إلى صور.
- text_encoder (PreTrainedModel) —
نموذج Qwen3-VL (مثل
Qwen3VLModelالخاص بـQwen/Qwen3-VL-4B-Instruct). يستهلك خط المعالجة مجموعة من حالات الإخفاء المستخرجة من عدة طبقات فكّ ترميز، بدلاً من حالة الإخفاء الأخيرة. - tokenizer (AutoTokenizer) — المُرمِّز المرافق لمُرمِّز النص.
- transformer (Krea2Transformer2DModel) — نموذج Krea 2 أحادي التدفق من نوع MMDiT الذي يتنبأ بسرعة مطابقة التدفق.
- text_encoder_select_layers (
tuple[int, ...], اختياري) — فهارس داخل مجموعةhidden_statesالخاصة بمشفّر النص (حيث يمثل 0 مخرج التضمين) التي تُكدّس حالاتها لكل رمز كشرط نصي للمحوّل. يجب أن تحتوي علىtransformer.config.num_text_layersمدخلات. - is_distilled (
bool، اختياري، القيمة الافتراضيةFalse) — ما إذا كان المحوّل هو نقطة الفحص المُقطّرة ذات الخطوات القليلة (TDM/turbo). عند تعيينTrue، يُستخدم إزاحة خطوة زمنية ثابتةmu=1.15؛ وإلا يُحسبmuمن دقة الصورة. - patch_size (
int, اختياري، القيمة الافتراضية 2) — طول جانب المربعات التي تُجمَّع فيها الكميات الكامنة قبل إدخالها إلى المحوّل. عامل تقليل الدقة الفعلي من البكسل إلى الرمز هوvae_scale_factor * patch_size.
خط أنابيب Krea 2 لتوليد الصور من النص.
__call__
< source >( prompt: str | list[str] | None = Nonenegative_prompt: str | list[str] | None = Noneheight: int = 1024width: int = 1024num_inference_steps: int = 28sigmas: list[float] | None = Noneguidance_scale: float = 4.5num_images_per_prompt: int = 1generator: typing.Union[torch.Generator, 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: str | None = 'pil'return_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list[str] = ['latents']attention_kwargs: dict[str, typing.Any] | None = Nonemax_sequence_length: int = 512 ) → Krea2PipelineOutput or tuple
المعاملات
- prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي تُوجّه توليد الصورة. إذا لم يُعرَّف، يجب تمريرprompt_embeds. - negative_prompt (
strأوlist[str]، اختياري) — الموجّه أو الموجّهات التي لا ينبغي أن توجّه توليد الصورة. يتم تجاهلها عندما يكونguidance_scale <= 0؛ الافتراضي هو موجّه فارغ عندما تكون التوجيه مفعّلاً. - height (
int) — ارتفاع الصورة المولّدة بالبكسلات. القيمة الافتراضية 1024. يُقرَّب إلى أقرب مضاعف لـ 16 عند الحاجة. - width (
int، القيمة الافتراضية 1024) — عرض الصورة المولّدة بالبكسلات. يُقرَّب إلى أقرب مضاعف لـ 16 عند الحاجة. - num_inference_steps (
int، القيمة الافتراضية 28) — عدد خطوات إزالة الضوضاء. استخدم 28 لنقطة التفتيش الأساسية (midtrain) و8 لنقطة التفتيش المُقطّرة ذات الخطوات القليلة (TDM). - sigmas (
list[float]، اختياري) — قيم sigmas مخصصة للمجدول. إذا لم تُعرَّف، تُستخدم شبكةlinspace(1.0, 1/num_inference_steps, num_inference_steps)الافتراضية (يتم تطبيق الإزاحة الواعية بالدقة داخل المجدول). - guidance_scale (
float، القيمة الافتراضية 4.5) — مقياس التوجيه الحر من التصنيف، وفقاً لاتفاقية Krea 2: يتم حساب السرعة على النحوcond + guidance_scale * (cond - uncond)ويتم تفعيل التوجيه عندما يكونguidance_scale > 0(وهذا يساوي صيغة CFG المعتادة مع مقياس1 + guidance_scale). اضبطه على0.0لتعطيله (مثلاً لنقطة التفتيش TDM). - num_images_per_prompt (
int، القيمة الافتراضية 1) — عدد الصور التي سيتم توليدها لكل موجه. - generator (
torch.Generatorأوlist[torch.Generator]، اختياري) — واحد أو أكثر من مولّدات torch لجعل التوليد حتميًا. - latents (
torch.Tensor، اختياري) — كائنات ضجيج مُولّدة مسبقًا في شكل مُجمّع(batch_size, image_seq_len, in_channels)، مُستخرجة من توزيع غاوسي، لاستخدامها كمدخلات لتوليد الصور. - prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا على شكل(batch_size, text_seq_len, num_text_layers, text_hidden_dim). إذا لم تُقدَّم، يتم توليد التضمينات منprompt. - prompt_embeds_mask (
torch.Tensor، اختياري) — قناع منطقي لـprompt_embeds؛ مطلوب عند تمريرprompt_embeds. - negative_prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية سالبة مُولّدة مسبقًا؛ بنفس الترتيب مثلprompt_embeds. - negative_prompt_embeds_mask (
torch.Tensor، اختياري) — قناع منطقي لـnegative_prompt_embeds؛ مطلوب عند تمريرnegative_prompt_embeds. - output_type (
str، اختياري، الافتراضي"pil") — صيغة مخرجات الصورة المولّدة. اختر بين"pil"أو"np"أو"pt"أو"latent". - return_dict (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان يجب إرجاع Krea2PipelineOutput بدلاً من tuple عادي. - callback_on_step_end (
Callable، اختياري) — دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء عبرcallback_on_step_end(self, step, timestep, callback_kwargs). - callback_on_step_end_tensor_inputs (
list[str]، اختياري، القيمة الافتراضية["latents"]) — قائمة مدخلات المصفوفات (tensors) لدالةcallback_on_step_end. يجب أن تكون مجموعة فرعية من._callback_tensor_inputs. - attention_kwargs (
dict، اختياري) — قاموس kwargs يُمرَّر إلىAttentionProcessorإذا تم تحديده، كما هو معرَّف تحتself.processorفي diffusers.models.attention_processor. - max_sequence_length (
int، القيمة الافتراضية 512) — طول ثابت لسلسلة النص الذي يستهلكه المحوّل؛ يتم ملء الأوامر أو تقصيرها لتطابق هذا الطول.
يعيد
Krea2PipelineOutput أو tuple
return_dict إذا كان tuple، وإلا Krea2PipelineOutput، حيث يكون العنصر الأول قائمة بالصور المولّدة.
الدالة التي تُستدعى عند استدعاء خط الأنابيب للتوليد.
أمثلة:
>>> import torch
>>> from diffusers import Krea2Pipeline
>>> # Load from a local directory produced by the Krea 2 conversion (no hub repo yet).
>>> pipe = Krea2Pipeline.from_pretrained("path/to/krea2-diffusers", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "a fox in the snow"
>>> # Base (midtrain) checkpoint defaults. For the few-step distilled (TDM) checkpoint use
>>> # `num_inference_steps=8, guidance_scale=0.0` instead.
>>> image = pipe(prompt, num_inference_steps=28, guidance_scale=4.5).images[0]
>>> image.save("krea2.png")encode_prompt
< source >( prompt: str | 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 = 512 )
المعاملات
- prompt (
strأوlist[str]، اختياري) — الموجّه الذي سيتم ترميزه - device — (
torch.device): جهاز torch - num_images_per_prompt (
int) — عدد الصور التي يجب توليدها لكل موجه - prompt_embeds (
torch.Tensor، اختياري) — تضمينات نصية مُولَّدة مسبقًا على شكل(batch_size, text_seq_len, num_text_layers, text_hidden_dim). يمكن استخدامها لتعديل مدخلات النص بسهولة، مثلًا وزن الموجه. إذا لم تُقدَّم، فسيتم توليد تضمينات النص من معامل الإدخالprompt. - prompt_embeds_mask (
torch.Tensor، اختياري) — قناع منطقي مُولّد مسبقًا يحدد الرموز النصية الصالحة، وبشكل(batch_size, text_seq_len). مطلوب عند تمريرprompt_embeds. - max_sequence_length (
int، القيمة الافتراضية 512) — طول ثابت لسلسلة النص الذي يستهلكه المحوّل؛ يتم ملء الأوامر أو تقصيرها لتطابق هذا الطول.
( prompt: str | list[str]max_sequence_length: int = 512device: typing.Optional[torch.device] = None )
قم بتجزئة prompt إلى تخطيط Krea 2 ذي الطول الثابت واستخرج حالات المُشفِّر المختارة المخفية.
يعيد مجموعة (hidden_states, attention_mask) بأشكال (batch_size, text_seq_len, num_text_layers, text_hidden_dim) و(batch_size, text_seq_len) (bool).
أنشئ إحداثيات الدوران (text_seq_len + grid_height * grid_width, 3) للتسلسل المدمج:
تقع رموز النص عند نقطة الأصل، بينما تحمل رموز الصورة إحداثيات الشبكة الكامنة (0, h, w) الخاصة بها.
Krea2PipelineOutput
فئة diffusers.pipelines.krea2.Krea2PipelineOutput
< source >( images: list[PIL.Image.Image] | numpy.ndarray )
فئة الإخراج لخط أنابيب Krea 2.
المنفصلة
يتوفر Krea 2 أيضاً على شكل خط أنابيب معياري. يتم تكوين التوجيه الحر من التصنيف من خلال مكوّن guider بدلاً من معامل استدعاء guidance_scale. يستخدم Krea 2 CFG مرسوماً على الشرط، وهو ClassifierFreeGuidance مع use_original_formulation=True.
import torch
from diffusers import ClassifierFreeGuidance, ModularPipeline
pipe = ModularPipeline.from_pretrained("krea/Krea-2-Raw")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda") # or "mps", "xpu", "cpu"
image = pipe(
prompt="a fox in the snow",
height=1024,
width=1024,
num_inference_steps=28,
generator=torch.Generator("cuda").manual_seed(0),
).images[0]
image.save("krea2.png")نوفّر أيضًا مثالًا لاستخدام Krea2 Turbo. يُخضع نقطة التفتيش المُقطّرة إلى مجموعة خاصة من الكتل (Krea2TurboAutoBlocks): فهي تعمل دون توجيه (بدون guider)، ولا تستقبل أي موجه سلبي، وتُنتج العينات في خطوات قليلة. يختار ModularPipeline.from_pretrained كتل turbo تلقائيًا من إعداد is_distilled الخاص بنقطة التفتيش، لذا لا حاجة إلى أي إعداد للتوجيه:
import torch
from diffusers import ModularPipeline
pipe = ModularPipeline.from_pretrained("krea/Krea-2-Turbo")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda") # or "mps", "xpu", "cpu"
image = pipe(
prompt="a fox in the snow",
height=1024,
width=1024,
num_inference_steps=8,
generator=torch.Generator("cuda").manual_seed(0),
).images[0]
image.save("krea2_turbo.png")Krea2ModularPipeline
فئة diffusers.Krea2ModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
خط أنابيب معياري لـ Krea 2.
Krea2AutoBlocks
خط أنابيب Auto Modular لتوليد الصور من النص باستخدام Krea 2: ترميز النص -> إزالة الضوضاء الأساسية (CFG متماثل) -> فك الترميز.
سير العمل المدعومة:
text2image: يتطلبprompt
المكوّنات:
text_encoder (Qwen3VLModel): مُشفّر النص الخاص بـ Qwen3-VL. tokenizer (AutoTokenizer): مُجزّئ الرموز المرافق
لمُشفّر النص. guider (ClassifierFreeGuidance) transformer (Krea2Transformer2DModel) scheduler
(FlowMatchEulerDiscreteScheduler) vae (AutoencoderKLQwenImage) image_processor (VaeImageProcessor)
المدخلات:
prompt (str):
الموجّه أو الموجّهات لتوجيه توليد الصورة.
negative_prompt (str, اختياري):
الموجّهات السالبة لـ CFG.
max_sequence_length (int, اختياري, الافتراضي 512):
أقصى طول للتسلسل لتشفير الموجّه.
num_images_per_prompt (int, اختياري, الافتراضي 1):
عدد الصور المراد توليدها لكل موجّه.
latents (Tensor, اختياري):
متغيرات كامنة ضجيجية مُولّدة مسبقًا لتوليد الصورة.
height (int, اختياري, الافتراضي 1024):
ارتفاع الصورة المولّدة بالبكسل.
width (int, اختياري, الافتراضي 1024):
عرض الصورة المولّدة بالبكسل.
generator (Generator, اختياري):
مولّد Torch لتوليد حتمي.
num_inference_steps (int, اختياري, الافتراضي 28):
عدد خطوات إزالة الضجيج.
sigmas (list, اختياري):
جدول سيجما مخصص (الافتراضي هو منحدر خطي).
attention_kwargs (dict, اختياري):
معاملات إضافية لمعالجات الانتباه.
output_type (str, اختياري, الافتراضي pil):
صيغة الإخراج: ‘pil’، ‘np’، ‘pt’.
المخرجات:
صور (list):
الصور المولّدة.
Krea2TurboModularPipeline
فئة diffusers.Krea2TurboModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
ModularPipeline لنقطة التفتيش المُصغّرة من Krea 2 turbo (TDM). يعمل دون توجيه حر من المُصنّف، لذا لا يستقبل أي موجه سلبي ولا يحتوي على مُوجِّه.
Krea2TurboAutoBlocks
خط أنابيب Auto Modular لتوليد الصور من النص باستخدام نقطة الفحص المُصغّرة Krea 2 turbo: ترميز النص -> إزالة الضوضاء الأساسية (بدون توجيه) -> فك الترميز.
سير العمل المدعومة:
text2image: يتطلبprompt
المكوّنات:
text_encoder (Qwen3VLModel): مُشفّر النص الخاص بـ Qwen3-VL. tokenizer (AutoTokenizer): مُجزّئ الرموز المرافق
لمُشفّر النص. transformer (Krea2Transformer2DModel) scheduler (FlowMatchEulerDiscreteScheduler)
vae (AutoencoderKLQwenImage) image_processor (VaeImageProcessor)
المدخلات:
prompt (str):
الموجّه أو الموجّهات لتوجيه توليد الصور.
max_sequence_length (int, اختياري, الافتراضي 512):
الحد الأقصى لطول التسلسل لتشفير الموجّه.
num_images_per_prompt (int, اختياري, الافتراضي 1):
عدد الصور المراد توليدها لكل موجّه.
latents (Tensor, اختياري):
متغيرات كامنة ضجيجية مُولّدة مسبقًا لتوليد الصور.
height (int, اختياري, الافتراضي 1024):
ارتفاع الصورة المولّدة بالبكسل.
width (int, اختياري, الافتراضي 1024):
عرض الصورة المولّدة بالبكسل.
generator (Generator, اختياري):
مولّد Torch لتوليد حتمي.
num_inference_steps (int, اختياري, الافتراضي 8):
عدد خطوات إزالة الضوضاء.
sigmas (list, اختياري):
جدول سيجما مخصص (الافتراضي هو منحدر خطي).
attention_kwargs (dict, اختياري):
معاملات إضافية لمعالجات الانتباه.
output_type (str, اختياري, الافتراضي pil):
صيغة الإخراج: ‘pil’، ‘np’، ‘pt’.
المخرجات:
صور (list):
الصور المولّدة.