FLUX 3 Image Klein

FLUX 3 Image Klein هو نموذج لتوليد الصور بحجم 5.6 مليار من Black Forest Labs: يقوم محوّل واحد (Flux3Transformer2DModel) بتوليد الصور من موجه نصي، بمفرده أو مع صورة مرجعية واحدة أو أكثر. يأتي التكييف النصي من Qwen3-VL، بينما تستخدم الصور مُشفِّر/مفكك الترميز التلقائي المعبأ FLUX.2 (AutoencoderKLFlux2).

يُطرح FLUX 3 Image Klein على شكل خط أنابيب معياري. ابدأ بتوليد صورة من نص:

import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base")
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
pipe.to("cuda")

image = pipe(
    prompt="A red fox in a snow-covered forest clearing at golden hour",
    generator=torch.Generator().manual_seed(0),
    output="images",
)[0]
image.save("fox.png")

prompt هو المدخل الإلزامي الوحيد: حيث تحمل خط الأنابيب إعدادات العينة الموصى بها (50 خطوة، مقياس التوجيه 3.5، إزاحة المجدول 6.93) وتولّد صورًا بقياس 1024 x 1024 افتراضيًا. يستقبل استدعاءً واحدًا لكل موجه؛ استخدم num_images_per_prompt للحصول على عدة صور لنفس الموجه.

كما ترون في المثال أعلاه، يختلف التحميل والتشغيل قليلاً عن DiffusionPipeline. التحميل كسول: from_pretrained() يبني خط الأنابيب فقط، وتقوم باستدعاء load_components() لتحميل الأوزان. يعيد الاستدعاء حالة خط الأنابيب، وتطلب ما تحتاجه باستخدام output: output="images" هنا، أو output=["images", "prompt"] للحصول أيضاً على الوصف الذي كتبه مُحسِّن المُوجِّه.

إذا كنت تعمل مع ModularPipeline لأول مرة، فاقرأ البدء السريع، والانتقال من DiffusionPipeline إذا كنت على دراية بالخطوط الأنابيب القياسية. بخلاف التحميل والمخرجات، تختلف بعض الأمور الأخرى: الإرشاد، المكالمات العكسية والتفريغ.

توسيع عينات المحفّز

تُعدّ الصياغة أمراً بالغ الأهمية: يستقبل نموذج FLUX 3 Image Klein أوصافاً كاملة للمشهد تصف الموضوع، والتكوين، والإضاءة، والأجواء، وليس مجرد أوامر قصيرة؛ فالطلب المُرسَل كما هو دون توسيع يُنتج مخرجات عامة. ولهذا السبب، يعمل خط المعالجة على مُوسّع الأوامر أولاً لكل طلب، سواء كان توليد صورة من نص أو تحرير. وهو نموذج مستقل بحجم 9B من Black Forest Labs (black-forest-labs/flux-3-image-klein-pup) يقوم بتوسيع prompt إلى وصف من هذا القبيل قبل مُشفّر النص، وكافٍ أن يكون الأمر قصيراً.

يحوّل مُوسّع المُوجِّه طلبًا قصيرًا، إلى جانب الصور المرجعية عند التحرير، إلى وصف كامل للمشهد الذي يتلقاه النموذج: الوسط والأسلوب، والمشهد، والإضاءة والكاميرا، وكل موضوع مع ألوانه ومواده وموقعه في الإطار. يغطي نموذج واحد توليد الصور من النص، والتحرير باستخدام الصور المرجعية، والتخطيط باستخدام الصناديق. يعود الوصف الذي كتبه كإخراج prompt. في المثال أعلاه، اطلبه إلى جانب الصور لرؤية ما استلمه نموذج الصور:

out = pipe(
    prompt="A red fox in a snow-covered forest clearing at golden hour",
    generator=torch.Generator().manual_seed(0),
    output=["images", "prompt"],
)
print(out["prompt"])

Full-color outdoor wildlife photograph taken from a low eye-level perspective in a snow-covered forest clearing at golden hour. In the center foreground, a red fox stands in profile facing left, its body turned toward the viewer and its head raised as it looks across the clearing. The fox has dense rust-red winter fur, a white throat and chest, black lower legs, pointed ears with dark tips, and a long bushy tail ending in white. ...

يصل طول الوصف الكامل إلى حوالي 240 كلمة؛ ويحدد max_new_tokens حدّ طوله (3584 افتراضيًا).

يمكنك طباعة doc الخاص بالخطوة لمعرفة ما يستهلكه وما يكتبه:

print(pipe.blocks.sub_blocks["prompt_upsampler"].doc)

  Inputs:
      prompt (`str`):
          The edit instruction to expand into the full caption (one per call).
      image (`Image | list`, *optional*):
          The reference image(s) of the edit, at most 10; the same ones the pipeline receives.
      boxes (`list`, *optional*):
          Layout boxes, each {'id', 'desc', 'from', 'src_bbox', 'tgt_bbox'} with the boxes as [y_min, x_min, y_max, x_max] in
          0-1: ...
      max_new_tokens (`int`, *optional*, defaults to 3584):
          The most tokens the upsampler may generate for the caption.

  Outputs:
      prompt (`str`):
          The full caption, replacing the request.

كما هو الحال مع الكتل الأخرى في خط المعالجة، يعمل كتلة prompt_upsampler بشكل مستقل. الطريقة الموصى بها هي فصلها عن الكتل: تصبح الكتلة المفصولة مُوسِّعًا مستقلًا، وتصبح الكتل المتبقية خط معالجة يستقبل الوصف الموسَّع بوصفه prompt:

blocks = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base").blocks
pup_block = blocks.sub_blocks.pop("prompt_upsampler")

pup = pup_block.init_pipeline("black-forest-labs/flux-3-image-klein-base")
pup.load_components(dtype=torch.bfloat16)
pup.to("cuda")
caption = pup(prompt="A red fox in a snow-covered forest clearing at golden hour", output="prompt")

pipe = blocks.init_pipeline("black-forest-labs/flux-3-image-klein-base")
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
pipe.to("cuda")
image = pipe(prompt=caption, generator=torch.Generator().manual_seed(0), output="images")[0]

بهذه الطريقة يمكن تقديمه كمرحلة مستقلة، على وحدة معالجة رسومية خاصة به أو خلف نقطة نهاية خاصة به، ويمكن لواجهة المستخدم أن تعرض الوصف الذي كتبه وتتيح للمستخدم تعديله قبل التوليد. يمكن لأي نموذج لغوي آخر أن يحل محل مُوسِّع الدقة، مع استخدام نفس أوامر النظام: أعطِه system_prompts["t2i"] من مستودع مُوسِّع الدقة (أو "i2i"، مع وضع المراجع أولاً في رسالة المستخدم) كمرجع للنظام والطلب كرسالة للمستخدم، ثم مرِّر الوصف الذي يعيده كـprompt إلى pipe.

من صورة إلى صورة

مرّر صورة مرجعية واحدة أو أكثر باستخدام image. تُحافظ الصورة المرجعية الواحدة على شكلها الكامل: فهي تُصغَّر فقط إذا تجاوزت 4 ميغابكسل، وتُملأ لتتوافق مع شبكة البكسلات البالغة 16 بكسل، وتكون القيمة الافتراضية للتوليد مطابقة لحجمها، لذا يعود التعديل بالحجم نفسه الذي دخلت به الصورة. أما الصور المرجعية المتعددة فتُصغَّر كل منها لتبقى تحت 1 ميغابكسل وتُقتطع لتتوافق مع الشبكة، وتكون القيمة الافتراضية للتوليد مطابقة لحجم الصورة الأولى. يمكن تجاوز القيمة الافتراضية بتحديد height/width معين. صف صورة الهدف بوصف كامل للصورة المرجعية مع دمج التعديل المطلوب فيها، بدلاً من تعليمات سطر واحد، أو اترك prompt upsampler يكتبه بناءً على التعليمات والصور المرجعية:

night = pipe(
    prompt="the same scene at night under a full moon",
    image=image,
    generator=torch.Generator().manual_seed(0),
    output=["images", "prompt"],
)

مع وجود عدة مراجع، يُشار إليها على أنها الصورة الأولى، الصورة الثانية، … بالترتيب الذي تُمرَّر به إلى image؛ حيث تُسمّيها التسمية <ref_image_0>، <ref_image_1>، … لنموذج الصورة:

combined = pipe(
    prompt="the fox from the first image sitting on the wooden bench from the second image",
    image=[image, bench],
    height=768,
    width=1360,
    output="images",
)[0]

مرّر height و/أو width لتجاوز الحجم المستنتج.

التحكم في التخطيط

لوضع المحتوى بشكل صريح، مرّر boxes: لكل عنصر id، وdesc مختصر، وbbox على شكل [y_min, x_min, y_max, x_max] ضمن نطاق 0-1 (المبدأ أعلى اليسار)، بحيث يكون مستقلاً عن حجم المخرجات. يكتب المُوسِّع الوصف حولها، مستشهداً بكل عنصر على شكل <id>، ويضيف جدول الصناديق، مع الحفاظ على صناديقك كما هي تماماً:

boxes = [
    {"id": "balloon_1", "desc": "a red and yellow striped hot-air balloon", "bbox": [0.08, 0.06, 0.48, 0.38]},
    {"id": "balloon_2", "desc": "a small blue hot-air balloon", "bbox": [0.20, 0.62, 0.42, 0.80]},
]
out = pipe(prompt="hot-air balloons over a green valley at sunrise", boxes=boxes, output=["images", "prompt"])

عند التحرير، يحدد الصندوق مصدره بواسطة from: "target" مع tgt_bbox يضيف عنصراً جديداً في ذلك الموقع، و"ref_image_0" مع src_bbox وtgt_bbox ينقل عنصراً من ذلك المرجع (تبقى العناصر في مكانها إذا كانت الصناديق متساوية):

boxes = [{"id": "cactus", "desc": "a small potted cactus", "from": "target", "src_bbox": None, "tgt_bbox": [0.55, 0.62, 0.85, 0.85]}]
out = pipe(prompt="add a small potted cactus in the marked spot", image=mug, boxes=boxes, output=["images", "prompt"])

boxes = [{"id": "knight", "desc": "the knight figure", "from": "ref_image_0", "src_bbox": [0.50, 0.15, 0.85, 0.35], "tgt_bbox": [0.19, 0.06, 0.54, 0.26]}]
out = pipe(prompt="move the knight up and to the left, keep the rest unchanged", image=knight, boxes=boxes, output=["images", "prompt"])

يحتوي الوصف الذي يقرأه نموذج الصورة على العناصر الموسومة بـ <id> في النص، مع الجدول المضاف بصيغة JSON، حيث تكون الصناديق على لوحة بأبعاد 0-1000؛ اطبع مخرجات prompt لرؤيتها. أما الوصف المكتوب يدوياً بهذه الصيغة فيمر عبر خط الأنابيب دون هذه الخطوة، كما هو الحال في توسيع المحفّز.

مقياس التوجيه

يطبّق خطّ الأنابيب التوجيه الحرّ من التصنيف عبر مكوّنه guider ولا يقبل حجة guidance_scale عند الاستدعاء. الموجّه الافتراضي هو ClassifierFreeGuidance مع guidance_scale=3.5، وهو الإعداد الموصى به لكلا مساري العمل. لتغييره، أنشئ نسخة محدّثة من الموجّه:

pipe.guider = pipe.guider.new(guidance_scale=5.0)

راجع دليل المرشدين للتبديل إلى طريقة إرشاد مختلفة.

نموذج مُقطّر على مستوى الخطوات

يولّد نقطة الفحص المُقطّرة خطوةً بخطوة في 16 خطوةً دون توجيهٍ حرٍّ من المُصنِّف. محوّله هو خريطة تدفّق: في كل خطوة يُبلَّغ بالخطوة الزمنية الحالية والخطوة التي تقفز إليها الخطوة. يُحمَّل مثل النموذج الأساسي (حيث يحلّ modular_model_index.json في المستودع إلى Flux3DistilledModularPipeline وFlux3DistilledAutoBlocks)؛ ولا يحتوي خطّ الأنابيب على guider ولا يقبل negative_prompt:

pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = pipe(prompt=prompt, generator=torch.Generator().manual_seed(0), output="images")[0]

يخدم نفس مساري العمل اللذين يخدمهما النموذج الأساسي. القيمة الافتراضية لـnum_inference_steps هي 16؛ حيث تم تدريب النموذج على 4 إلى 16 خطوة.

توليد قابل للتكرار

يُثبّت generator الضوضاء التي يسحبها خط الأنابيب (انظر إعادة الإنتاج). لإعادة استخدام ضوضاء سُحبت في مكان آخر، مرّرها كـ latents بالشكل (batch_size, 128, height // 16, width // 16). على سبيل المثال، يسحب تنفيذ BFL ضوضاءه كرموز صورة على وحدة المعالجة المركزية (CPU) ويحوّلها إلى bf16؛ وهذا يُعيد إنتاج عيّنته لبذرة محددة:

height, width = 1024, 1024
h, w = height // 16, width // 16

noise = torch.randn((h * w, 128), generator=torch.Generator().manual_seed(0)).to(torch.bfloat16)
latents = noise.T.reshape(1, 128, h, w)

image = pipe(prompt=prompt, latents=latents, height=height, width=width, output="images")[0]

سير العمل

تخدم خط المعالجة مساري عمل، هما text2image وimage_conditioned؛ ويُختار المسار الذي يُنفَّذ بناءً على المدخلات (حيث يحدد image مسار الصورة إلى الصورة). كما يمكن لـfrom_pretrained() بناء خط معالجة لمسار عمل واحد باستخدام معامل workflow، والذي يتوقع في هذه الحالة ويحمّل فقط المكونات التي يحتاجها ذلك المسار:

from diffusers.modular_pipelines import Flux3AutoBlocks

print(Flux3AutoBlocks().available_workflows)
# ["text2image", "image_conditioned"]

t2i = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base", workflow="text2image")
print(t2i.blocks.doc)

إجراءات الاستدعاء لكل خطوة

لاستخدام دالة استدعاء موجودة مسبقًا، أدخل كتلة في حلقة إزالة الضوضاء. يحتوي دليل الاستدعاءات على مثال بسيط باستخدام كتلة CallbackOnStepEnd ودالة المساعدة walk_denoise_loops:

blocks = Flux3AutoBlocks()  # or Flux3DistilledAutoBlocks
for loop in walk_denoise_loops(blocks):
    loop.sub_blocks["callback"] = CallbackOnStepEnd()
pipe = blocks.init_pipeline("black-forest-labs/flux-3-image-klein-base")

image = pipe(prompt=caption, callback_on_step_end=my_callback, output="images")[0]

للتوقف مبكرًا، ارفع استثناءً من الدالة الاستدعائية؛ لا يوجد علم interrupt.

الذاكرة

تتطلب التحميل الكامل في bf16 حوالي 39 جيجابايت من الأوزان: حيث يتكون الترانسفورمر من 5.5 مليار معلمة، ومشفّر النص Qwen3-VL-4B من 4 مليارات، وموسّع الأوامر من 9 مليارات (حوالي 19 جيجابايت بمفرده)، مع استخدام VAE للصور في fp32. أما خط الأنابيب الذي يُبنى دون خطوة الموسّع (انظر هناك) فيحمّل حوالي 20 جيجابايت. بالنسبة للوحدات الرسومية ذات ذاكرة أقل، فعّل تفريغ المكونات؛ حيث يقوم المدير بنقل المكونات بين وحدة المعالجة المركزية والوحدة الرسومية كلما احتاجت كل خطوة إليها، بما في ذلك الموسّع:

from diffusers import ComponentsManager, ModularPipeline

manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base", components_manager=manager)
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
manager.enable_auto_cpu_offload(device="cuda")

التحميل من ملف واحد

تحمّل Flux3Transformer2DModel نموذج التحويل مباشرةً من حزمة نموذج Black Forest Labs باستخدام from_single_file(). لا يتم قراءة ملف config.json في الحزمة؛ بل مرّر إعدادات diffusers عبر config وsubfolder.

import torch
from diffusers import Flux3Transformer2DModel, ModularPipeline

transformer = Flux3Transformer2DModel.from_single_file(
    "https://huggingface.co/black-forest-labs/flux-3-image-klein-base/blob/main/model.safetensors",
    config="black-forest-labs/flux-3-image-klein-base",
    subfolder="transformer",
    dtype=torch.bfloat16,
)

pipe = ModularPipeline.from_pretrained("black-forest-labs/flux-3-image-klein-base")
pipe.load_components(dtype={"vae": torch.float32, "default": torch.bfloat16})
pipe.update_components(transformer=transformer)
pipe.to("cuda")

حمّل المكونات الأخرى بالاسم أولاً: load_components() بدون names سيؤدي أيضاً إلى تحميل المُحوِّل من مستودع خط المعالجة.

تُدعم أيضاً عملية تحميل نقاط التفتيش أحادية الملف الخاصة بـ FP8r وNVFP4. يتم تحميل كلاهما عبر نفس الاستدعاء باستخدام BFLQuantizationConfig. راجع دليل تكميم BFL لمعرفة متطلبات النواة لكل مخطط.

from diffusers import BFLQuantizationConfig

transformer = Flux3Transformer2DModel.from_single_file(
    "https://huggingface.co/black-forest-labs/flux-3-image-klein-base/blob/main/variants/nvfp4/model.safetensors",
    config="black-forest-labs/flux-3-image-klein-base",
    subfolder="transformer",
    quantization_config=BFLQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)

عند تحميل نقاط التفتيش المُقطّرة خطوة بخطوة، نحتاج إلى إعداداتها (flow_map=True):

transformer = Flux3Transformer2DModel.from_single_file(
    "https://huggingface.co/black-forest-labs/flux-3-image-klein/blob/main/variants/nvfp4/model.safetensors",
    config="black-forest-labs/flux-3-image-klein",
    subfolder="transformer",
    quantization_config=BFLQuantizationConfig(compute_dtype=torch.bfloat16),
    dtype=torch.bfloat16,
)

Flux3ModularPipeline

Flux3AutoBlocks

Flux3DistilledAutoBlocks

Flux3DistilledModularPipeline