Diffusers documentation
خطوط الأنابيب
خطوط الأنابيب
توفّر خطوط الأنابيب طريقة بسيطة لتشغيل نماذج الانتشار المتقدمة في الاستدلال عن طريق تجميع جميع المكونات اللازمة (نماذج مدرّبة بشكل مستقل، ومجدولات، ومعالجات) في فئة واحدة شاملة من البداية إلى النهاية. خطوط الأنابيب مرنة ويمكن تكييفها لاستخدام مجدولات مختلفة أو حتى مكونات نماذج مختلفة.
تُبنى جميع خطوط الأنابيب من الفئة الأساسية DiffusionPipeline التي توفر الوظائف الأساسية لتحميل جميع المكونات وتنزيلها وحفظها. يتم اكتشاف أنواع خطوط الأنابيب المحددة (مثل StableDiffusionPipeline) التي يتم تحميلها باستخدام from_pretrained() تلقائيًا، وتُحمَّل مكونات خط الأنابيب وتُمرَّر إلى دالة __init__ الخاصة بخط الأنابيب.
لا ينبغي استخدام فئة DiffusionPipeline للتدريب. تُدرَّب المكونات الفردية (مثل UNet2DModel و UNet2DConditionModel) في خطوط أنابيب الانتشار عادةً بشكل مستقل، لذا نقترح العمل معها مباشرةً بدلاً من ذلك.
لا توفر خطوط الأنابيب أي وظيفة للتدريب. ستلاحظ أن autograd في PyTorch معطّل من خلال تزيين طريقة
__call__()بمُزيّنtorch.no_gradلأن خطوط الأنابيب لا ينبغي استخدامها للتدريب. إذا كنت مهتمًا بالتدريب، فيرجى الاطلاع على أدلة التدريب بدلاً من ذلك!
Use API > Pipelines in the sidebar to browse all pipeline references by modality. For task-oriented workflows, start with the Quickstart or a guide such as text-to-image, image-to-image, inpainting, or video generation.
DiffusionPipeline
الفئة الأساسية لجميع خطوط الأنابيب.
تُخزّن DiffusionPipeline جميع المكونات (النماذج، والمجدولون، والمعالجات) لخطوط أنابيب الانتشار، وتوفر طرقًا لتحميل النماذج وتنزيلها وحفظها. كما تتضمن طرقًا لـ:
- نقل جميع وحدات PyTorch إلى الجهاز الذي تختاره
- تفعيل/تعطيل شريط التقدم لتكرار إزالة الضوضاء
خصائص الفئة:
- config_name (
str) — اسم ملف الإعداد الذي يخزّن أسماء الفئات والوحدات لجميع مكوّنات خط أنابيب الانتشار. - _optional_components (
List[str]) — قائمة بجميع المكونات الاختيارية التي لا يجب تمريرها إلى خط الأنابيب حتى يعمل (يجب أن تُستبدل بواسطة الفئات الفرعية).
جهاز
< source >( ) → torch.device
يعيد
torch.device
جهاز torch الذي يقع عليه خط المعالجة. عند تقسيم المكونات عبر الأجهزة (على سبيل المثال، مشفّرات النص على وحدة المعالجة المركزية بينما يعمل العمود الفقري لإزالة الضوضاء على مُسرِّع)، يُعاد جهاز المُسرِّع.
إلى
< source >( *args**kwargs ) → DiffusionPipeline
المعاملات
- dtype (
torch.dtype، اختياري) — يعيد خط أنابيب معdtypeالمحدد - device (
torch.Device، اختياري) — يعيد خط أنابيب معdeviceالمحدد - silence_dtype_warnings (
str، اختياري، القيمة الافتراضيةFalse) — ما إذا كان يجب تجاهل التحذيرات إذا لم يكنdtypeالمستهدف متوافقًا معdeviceالمستهدف.
يعيد
تم تحويل خط الأنابيب إلى dtype و/أو dtype المحدد.
يُنفّذ تحويل نوع البيانات (dtype) و/أو الجهاز (device) الخاص بـ Pipeline. يتم استنتاج torch.dtype وtorch.device من معاملات self.to(*args, **kwargs).
> إذا كان خط الأنابيب يحتوي بالفعل على torch.dtype وtorch.device الصحيحين، فإنه يُعاد كما هو. وإلا، > فإن خط الأنابيب المُعاد هو نسخة من self مع torch.dtype وtorch.device المطلوبين.
إليك طرق استدعاء to:
to(dtype, silence_dtype_warnings=False) → DiffusionPipelineلإرجاع خط أنابيب بالـdtypeالمحددto(device, silence_dtype_warnings=False) → DiffusionPipelineلإرجاع خط أنابيب معdeviceالمحددto(device=None, dtype=None, silence_dtype_warnings=False) → DiffusionPipelineلإرجاع خط أنابيب معdeviceوdtypeالمحددين
يمكن أن يكون الخاصية self.components مفيدةً لتشغيل خطوط أنابيب مختلفة بنفس الأوزان والإعدادات دون إعادة تخصيص ذاكرة إضافية.
يعيد (dict):
قاموس يحتوي على جميع الوحدات اللازمة لتهيئة خط المعالجة.
أمثلة:
>>> from diffusers import (
... StableDiffusionPipeline,
... StableDiffusionImg2ImgPipeline,
... StableDiffusionInpaintPipeline,
... )
>>> text2img = StableDiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")
>>> img2img = StableDiffusionImg2ImgPipeline(**text2img.components)
>>> inpaint = StableDiffusionInpaintPipeline(**text2img.components)تعطيل حساب الانتباه المقطّع. إذا كان enable_attention_slicing قد تم استدعاؤه سابقًا، يتم حساب الانتباه في خطوة واحدة.
تعطيل الانتباه الموفّر للذاكرة من xFormers.
تنزيل
< source >( pretrained_model_name**kwargs ) → os.PathLike
المعاملات
- pretrained_model_name (
strأوos.PathLike، اختياري) — نص، وهو معرّف المستودع (مثلCompVis/ldm-text2im-large-256) لخط أنابيب مُدرَّب مسبقًا مستضاف على Hub. - custom_pipeline (
str, اختياري) — يمكن أن يكون أحد ما يلي: سلسلة نصية، معرف المستودع (مثل CompVis/ldm-text2im-large-256) لخط أنابيب مُدرَّب مسبقًا مستضاف على Hub. يجب أن يحتوي المستودع على ملف يُسمى pipeline.py يحدد خط الأنابيب المخصص. سلسلة نصية، اسم ملف لخط أنابيب مجتمعي مستضاف على GitHub تحت قسم Community. يجب أن تتطابق أسماء الملفات الصالحة مع اسم الملف وليس مع سكربت خط الأنابيب (clip_guided_stable_diffusion بدلاً من clip_guided_stable_diffusion.py). يتم دائمًا تحميل خطوط الأنابيب المجتمعية من الفرع الرئيسي الحالي main على GitHub. مسار إلى مجلد (./my_pipeline_directory/) يحتوي على خط أنابيب مخصص. يجب أن يحتوي المجلد على ملف يُسمى pipeline.py يحدد خط الأنابيب المخصص. > 🧪 هذه ميزة تجريبية وقد تتغير في المستقبل. لمزيد من المعلومات حول كيفية تحميل وإنشاء خطوط الأنابيب المخصصة، راجع كيفية المساهمة بخط أنابيب مجتمعي.-
سلسلة نصية، وهي معرّف المستودع (على سبيل المثال
CompVis/ldm-text2im-large-256) لخط أنابيب مُدرَّب مسبقًا مستضاف على Hub. يجب أن يحتوي المستودع على ملف يُسمىpipeline.pyيحدد خط الأنابيب المخصص. -
سلسلة نصية، وهي اسم الملف لخط أنابيب مجتمعي مستضاف على GitHub تحت Community. يجب أن تتطابق أسماء الملفات الصالحة مع اسم الملف وليس مع سكربت خط الأنابيب (
clip_guided_stable_diffusionبدلاً منclip_guided_stable_diffusion.py). يتم تحميل خطوط الأنابيب المجتمعية دائمًا من فرعmainالحالي على GitHub. -
مسار إلى مجلد (
./my_pipeline_directory/) يحتوي على خط أنابيب مخصص. يجب أن يحتوي المجلد على ملف يُسمىpipeline.pyيحدد خط الأنابيب المخصص.
> 🧪 هذه ميزة تجريبية وقد تتغير في المستقبل.
لمزيد من المعلومات حول كيفية تحميل خطوط الأنابيب المخصصة وإنشائها، راجع كيفية المساهمة بخط أنابيب مجتمعي.
-
- force_download (
bool، اختياري، القيمة الافتراضيةFalse) — ما إذا كان يجب إجبار إعادة تنزيل أوزان النموذج وملفات الإعداد، مع تجاوز النسخ المخزنة مؤقتًا إذا كانت موجودة. - proxies (
Dict[str, str]، اختياري) — قاموس لخوادم الوكيل (proxy) للاستخدام حسب البروتوكول أو نقطة النهاية، على سبيل المثال{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. تُستخدم هذه الوكلاء في كل طلب. - output_loading_info(
bool, اختياري، القيمة الافتراضيةFalse) — ما إذا كان يجب إرجاع قاموس يحتوي على المفاتيح الناقصة والمفاتيح غير المتوقعة ورسائل الأخطاء أم لا. - local_files_only (
bool، اختياري، القيمة الافتراضيةFalse) — ما إذا كان سيتم تحميل أوزان النموذج وملفات الإعداد المحلية فقط أم لا. إذا تم ضبطه علىTrue، فلن يتم تنزيل النموذج من Hub. - token (
strأو bool، اختياري) — الرمز الذي يُستخدم كتفويض حامل HTTP للملفات البعيدة. إذا كانTrue، يُستخدم الرمز المولّد منdiffusers-cli login(المخزّن في~/.huggingface). - revision (
str، اختياري، القيمة الافتراضية"main") — الإصدار المحدد من النموذج الذي سيتم استخدامه. يمكن أن يكون اسم فرع، أو اسم وسم، أو معرف commit، أو أي معرّف مسموح به بواسطة Git. - custom_revision (
str، اختياري، القيمة الافتراضية"main") — الإصدار المحدد من النموذج الذي سيتم استخدامه. يمكن أن يكون اسم فرع، أو اسم وسم، أو معرف commit مشابه لـrevisionعند تحميل خط أنابيب مخصص من Hub. يمكن أن يكون إصدار 🤗 Diffusers عند تحميل خط أنابيب مخصص من GitHub، وإلا فإن القيمة الافتراضية تكون"main"عند التحميل من Hub. - mirror (
str، اختياري) — مصدر مرآة لحل مشاكل إمكانية الوصول إذا كنت تقوم بتنزيل نموذج في الصين. نحن لا نضمن حداثة المصدر أو أمانه، وينبغي لك الرجوع إلى موقع المرآة لمزيد من المعلومات. - variant (
str، اختياري) — تحميل الأوزان من اسم ملف متغير محدد مثل"fp16"أو"ema". - use_safetensors (
bool، اختياري، القيمة الافتراضيةNone) — إذا تم تعيينه إلىNone، يتم تنزيل أوزان safetensors إذا كانت متاحة و إذا كانت مكتبة safetensors مثبتة. إذا تم تعيينه إلىTrue، يتم تحميل النموذج بشكل إجباري من أوزان safetensors. إذا تم تعيينه إلىFalse، لا يتم تحميل أوزان safetensors. - use_onnx (
bool، اختياري، القيمة الافتراضيةFalse) — إذا تم ضبطه علىTrue، فسيتم تنزيل أوزان ONNX دائمًا إذا كانت موجودة. إذا تم ضبطه علىFalse، فلن يتم تنزيل أوزان ONNX أبدًا. افتراضيًا، تكون القيمة الافتراضية لـuse_onnxهي سمة الفئة_is_onnxوالتي تكونFalseلخطوط الأنابيب غير ONNX وTrueلخطوط الأنابيب ONNX. تشمل أوزان ONNX كلا من الملفات التي تنتهي بـ.onnxو.pb. - trust_remote_code (
bool، اختياري، القيمة الافتراضيةFalse) — ما إذا كان سيتم السماح بخطوط الأنابيب والمكوّنات المخصصة المعرّفة على Hub في ملفات خاصة بها. يجب ضبط هذا الخيار علىTrueفقط للمستودعات التي تثق بها والتي قرأت كودها، لأنه سيقوم بتنفيذ الكود الموجود على Hub على جهازك المحلي. - use_flashpack (
bool، اختياري، القيمة الافتراضيةFalse) — إذا تم ضبطه علىTrue، فسيتم تنزيل أوزان FlashPack دائمًا إذا كانت موجودة. إذا تم ضبطه علىFalse، فلن يتم تنزيل أوزان FlashPack أبدًا.
يعيد
os.PathLike
مسار إلى خط المعالجة الذي تم تنزيله.
تنزيل خط أنابيب انتشار PyTorch وتخزينه مؤقتاً من أوزان خط أنابيب مُسبقة التدريب.
> لاستخدام النماذج الخاصة أو النماذج المُقيَّدة، سجّل الدخول باستخدام `hf > auth login
enable_attention_slicing
< source >( slice_size: str | int = 'auto' )
المعاملات
- slice_size (
strأوint، اختياري، القيمة الافتراضية"auto") — عندما تكون القيمة"auto"، يتم تقسيم المدخلات إلى رؤوس الانتباه إلى نصفين، بحيث يُحسب الانتباه في خطوتين. أما إذا كانت"max"، فسيتم توفير أقصى قدر من الذاكرة من خلال تشغيل شريحة واحدة في كل مرة. وإذا تم تقديم رقم، يتم استخدام عدد من الشرائح يساويattention_head_dim // slice_size. في هذه الحالة، يجب أن يكونattention_head_dimمضاعفًا لـslice_size.
تفعيل حساب الانتباه المقطّع. عند تفعيل هذا الخيار، يقسم وحدة الانتباه المصفوفة المدخلة إلى شرائح لحساب الانتباه على عدة خطوات. في حالة وجود أكثر من رأس انتباه، يتم تنفيذ الحساب بشكل تسلسلي على كل رأس. وهذا مفيد لتوفير بعض الذاكرة مقابل انخفاض طفيف في السرعة.
> ⚠️ لا تفعّل تقطيع الانتباه إذا كنت تستخدم بالفعل
scaled_dot_product_attention(SDPA) من PyTorch > 2.0 أو xFormers. فحسابات الانتباه هذه فعّالة جداً من حيث الذاكرة، لذا لن تحتاج إلى تفعيل > هذه الوظيفة. إذا فعّلت تقطيع الانتباه مع SDPA أو xFormers، فقد يؤدي ذلك إلى تباطؤ كبير!
أمثلة:
>>> import torch
>>> from diffusers import StableDiffusionPipeline
>>> pipe = StableDiffusionPipeline.from_pretrained(
... "stable-diffusion-v1-5/stable-diffusion-v1-5",
... dtype=torch.float16,
... use_safetensors=True,
... )
>>> prompt = "a photo of an astronaut riding a horse on mars"
>>> pipe.enable_attention_slicing()
>>> image = pipe(prompt).images[0]enable_group_offload
< source >( onload_device: deviceoffload_device: device = torch.device()offload_type: str = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage = Falseoffload_to_disk_path: str | None = Noneexclude_modules: str | list[str] | None = None )
المعاملات
- onload_device (
torch.device) — الجهاز الذي تُحمَّل عليه مجموعة الوحدات. - offload_device (
torch.device، الافتراضيtorch.device("cpu")) — الجهاز الذي يتم نقل مجموعة الوحدات إليه. يجب أن يكون هذا الجهاز عادةً وحدة المعالجة المركزية (CPU). الافتراضي هو وحدة المعالجة المركزية (CPU). - offload_type (
strأوGroupOffloadingType، الافتراضي “block_level”) — نوع الإزاحة (offloading) الذي سيتم تطبيقه. يمكن أن يكون “block_level” أو “leaf_level”. الافتراضي هو “block_level”. - offload_to_disk_path (
str، اختياري، القيمة الافتراضيةNone) — المسار إلى المجلد الذي سيتم فيه تفريغ المعاملات. قد يكون ضبط هذا الخيار مفيدًا في بيئات محدودة الذاكرة العشوائية (RAM) حيث يُرغب في تحقيق توازن معقول بين السرعة والذاكرة. - num_blocks_per_group (
int, اختياري) — عدد الكتل في كل مجموعة عند استخدام offload_type=“block_level”. هذا مطلوب عند استخدام offload_type=“block_level”. - non_blocking (
bool)، القيمة الافتراضيةFalse) — إذا كانت القيمة True، يتم تنفيذ عمليات الإزاحة والتحميل عبر نقل بيانات غير محجوز. - use_stream (
bool، القيمة الافتراضيةFalse) — إذا كانت القيمة True، يتم تنفيذ عمليات الإزاحة (offloading) والتحميل (onloading) بشكل غير متزامن باستخدام تدفق CUDA. قد يكون ذلك مفيدًا لتداخل الحسابات مع نقل البيانات. - record_stream (
bool، القيمة الافتراضيةFalse) — عند تفعيله معuse_stream، يُعلّم المصفوفة الحالية بأنها استُخدمت بواسطة هذا التدفق. فهو أسرع على حساب زيادة طفيفة في استهلاك الذاكرة. راجع التوثيق الرسمي لـ PyTorch لمزيد من التفاصيل. - low_cpu_mem_usage (
bool، القيمة الافتراضيةFalse) — إذا كانت القيمة True، يتم تقليل استخدام ذاكرة المعالج المركزي (CPU) عن طريق تثبيت المصفوفات (tensors) أثناء التشغيل بدلاً من تثبيتها مسبقاً. لا تهم هذه الخيارات إلا عند استخدام إزاحة المعالج المركزي (CPU) عبر البث (أيuse_stream=True). قد يكون هذا مفيداً عندما تكون ذاكرة المعالج المركزي عنقاً زجاجة، لكنه قد يقاوم فوائد استخدام البث (streams). - exclude_modules (
Union[str, List[str]]، القيمة الافتراضيةNone) — قائمة الوحدات التي يجب استبعادها من عملية الإزاحة.
يطبّق تفريغ المجموعات على الطبقات الداخلية لـ torch.nn.Module. لفهم ما هو تفريغ المجموعات، وأين يكون مفيداً، نحتاج أولاً إلى تقديم بعض السياق حول كيفية عمل طرق التفريغ الأخرى المدعومة.
عادةً، يتم تنفيذ الإزاحة على مستويين:
- على مستوى الوحدة: في Diffusers، يمكن تفعيل ذلك باستخدام طريقة
ModelMixin::enable_model_cpu_offload(). تعمل هذه الطريقة عن طريق نقل كل مكوّن من مكوّنات خط الأنابيب إلى وحدة المعالجة المركزية (CPU) للتخزين، ثم تحميله إلى جهاز التسريع عند الحاجة إليه للحساب. هذه الطريقة أكثر كفاءة في استخدام الذاكرة من إبقاء جميع المكوّنات على جهاز التسريع، لكن متطلبات الذاكرة لا تزال مرتفعة إلى حد كبير. لكي تعمل هذه الطريقة، يجب توفر ذاكرة تعادل حجم النموذج في نوع البيانات وقت التشغيل + حجم أكبر توترات التنشيط الوسيطة، وذلك لإكمال مسار الأمامي. - على مستوى الأوراق: في Diffusers، يمكن تفعيل ذلك باستخدام طريقة
ModelMixin::enable_sequential_cpu_offload(). يعمل هذا عن طريق نقل معاملات مستوى الأوراق الأدنى من رسم الحساب إلى وحدة المعالجة المركزية للتخزين، ونقل الأوراق فقط إلى جهاز التسريع لأغراض الحساب. يستخدم هذا أقل قدر من ذاكرة التسريع، لكنه قد يكون أبطأ بسبب العدد المفرط من مزامنات الأجهزة.
يعتبر تفريغ المجموعات (Group offloading) حلًا وسطًا بين الطريقتين. يعمل عن طريق تفريغ مجموعات من الطبقات الداخلية، (سواءً torch.nn.ModuleList أو torch.nn.Sequential). تستخدم هذه الطريقة ذاكرة أقل من تفريغ مستوى الوحدة (module-level offloading). كما أنها أسرع من تفريغ مستوى الورقة/التسلسلي (leaf-level/sequential offloading)، نظرًا لتقليل عدد مزامنات الأجهزة.
ميزة أخرى مدعومة (لأجهزة CUDA التي تدعم تدفقات نقل البيانات غير المتزامنة) هي القدرة على تداخل نقل البيانات والحساب لتقليل وقت التنفيذ الإجمالي مقارنةً بالتفريغ التسلسلي. يتم تمكين ذلك باستخدام الاستباق للطبقات مع التدفقات، أي أن الطبقة التي سيتم تنفيذها التالية تبدأ التحميل إلى جهاز المعالج التسارعي بينما يتم تنفيذ الطبقة الحالية - وهذا يزيد من متطلبات الذاكرة قليلاً. لاحظ أن هذا التنفيذ يدعم أيضًا التفريغ على مستوى الأوراق، لكنه يمكن أن يصبح أسرع بكثير عند استخدام التدفقات.
مثال:
>>> from diffusers import DiffusionPipeline
>>> import torch
>>> pipe = DiffusionPipeline.from_pretrained("Qwen/Qwen-Image", dtype=torch.bfloat16)
>>> pipe.enable_group_offload(
... onload_device=torch.device("cuda"),
... offload_device=torch.device("cpu"),
... offload_type="leaf_level",
... use_stream=True,
... )
>>> image = pipe("a beautiful sunset").images[0]enable_model_cpu_offload
< source >( gpu_id: int | None = Nonedevice: typing.Union[torch.device, str] = None )
المعاملات
ينقل جميع النماذج إلى وحدة المعالجة المركزية (CPU) باستخدام accelerate، مما يقلل من استهلاك الذاكرة مع تأثير ضئيل على الأداء. مقارنةً بـ enable_sequential_cpu_offload، تنقل هذه الطريقة نموذجًا كاملًا في كل مرة إلى المُسرِّع عند استدعاء طريقة forward الخاصة به، ويبقى النموذج في المُسرِّع حتى تشغيل النموذج التالي. تكون وفورات الذاكرة أقل مما هي عليه مع enable_sequential_cpu_offload، لكن الأداء يكون أفضل بكثير بسبب التنفيذ التكراري لـ unet.
enable_sequential_cpu_offload
< source >( gpu_id: int | None = Nonedevice: typing.Union[torch.device, str] = None )
المعاملات
ينقل جميع النماذج إلى وحدة المعالجة المركزية (CPU) باستخدام 🤗 Accelerate، مما يقلل من استهلاك الذاكرة بشكل كبير. عند الاستدعاء، تُحفظ قوائم الحالة (state dicts) لجميع مكونات torch.nn.Module (باستثناء تلك الموجودة في self._exclude_from_cpu_offload) على وحدة المعالجة المركزية، ثم تُنقل إلى torch.device('meta') ولا تُحمَّل على المُسرِّع (accelerator) إلا عند استدعاء طريقة forward الخاصة بالوحدة الفرعية المعنية. يتم النقل على أساس الوحدات الفرعية. تكون وفورات الذاكرة أعلى مما هي عليه مع enable_model_cpu_offload، لكن الأداء يكون أدنى.
enable_xformers_memory_efficient_attention
< source >( attention_op: typing.Optional[typing.Callable] = None )
المعاملات
- attention_op (
Callable، اختياري) — تجاوز المشغّل الافتراضيNoneلاستخدامه كحجةopفي دالةmemory_efficient_attention()الخاصة بـ xFormers.
تفعيل الانتباه الموفّر للذاكرة من xFormers. عند تفعيل هذا الخيار، يجب أن تلاحظ انخفاضًا في استخدام ذاكرة وحدة معالجة الرسوميات (GPU) وتسريعًا محتملًا أثناء الاستدلال. لا يُضمن التسريع أثناء التدريب.
> ⚠️ عند تفعيل كل من الانتباه الموفّر للذاكرة والانتباه المقطّع، فإنّ الانتباه الموفّر للذاكرة يحظى بالأولوية.
أمثلة:
>>> import torch
>>> from diffusers import DiffusionPipeline
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp
>>> pipe = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-2-1", dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> pipe.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)
>>> # Workaround for not accepting attention shape using VAE for Flash Attention
>>> pipe.vae.enable_xformers_memory_efficient_attention(attention_op=None)from_pipe
< source >( pipeline**kwargs ) → DiffusionPipeline
أنشئ خط أنابيب جديدًا من خط أنابيب معيّن. يُعدّ هذا الأسلوب مفيدًا لإنشاء خط أنابيب جديد من مكوّنات خط الأنابيب الموجود دون تخصيص ذاكرة إضافية.
from_pretrained
< source >( pretrained_model_name_or_path: str | os.PathLike**kwargs )
المعاملات
- pretrained_model_name_or_path (
strأوos.PathLike, اختياري) — يمكن أن يكون أحد ما يلي:- سلسلة نصية، وهي repo id (على سبيل المثال
CompVis/ldm-text2im-large-256) لخط أنابيب مُدرَّب مسبقًا مستضاف على Hub. - مسار إلى مجلد (على سبيل المثال
./my_pipeline_directory/) يحتوي على أوزان خط الأنابيب المحفوظة باستخدام save_pretrained().
- سلسلة نصية، وهي repo id (على سبيل المثال
- dtype (
torch.dtypeأوdict[str, Union[str, torch.dtype]]، اختياري) — تجاوزtorch.dtypeالافتراضي وتحميل النموذج بنوع بيانات آخر. لتحميل النماذج الفرعية بأنواع بيانات مختلفة، مرّرdict(على سبيل المثال{'transformer': torch.bfloat16, 'vae': torch.float16}). اضبط نوع البيانات الافتراضي للمكونات غير المحددة باستخدامdefault(على سبيل المثال{'transformer': torch.bfloat16, 'default': torch.float16}). إذا لم يُحدد مكوّن ولم يُضبط نوع بيانات افتراضي، يتم استخدامtorch.float32. - custom_pipeline (
str, اختياري) —> 🧪 هذه ميزة تجريبية وقد تتغير في المستقبل.
يمكن أن يكون إما:
- سلسلة نصية، وهي repo id (على سبيل المثال
hf-internal-testing/diffusers-dummy-pipeline) لخط أنابيب مخصص مستضاف على Hub. يجب أن يحتوي المستودع على ملف يُسمى pipeline.py يحدد خط الأنابيب المخصص. - سلسلة نصية، وهي اسم الملف لخط أنابيب مجتمعي مستضاف على GitHub تحت
Community. يجب أن تتطابق أسماء الملفات الصالحة مع اسم الملف وليس مع سكربت خط الأنابيب (
clip_guided_stable_diffusionبدلاً منclip_guided_stable_diffusion.py). يتم تحميل خطوط الأنابيب المجتمعية دائمًا من فرع main الحالي على GitHub. - مسار إلى مجلد (
./my_pipeline_directory/) يحتوي على خط أنابيب مخصص. يجب أن يحتوي المجلد على ملف يُسمىpipeline.pyيحدد خط الأنابيب المخصص.
لمزيد من المعلومات حول كيفية تحميل وإنشاء خطوط أنابيب مخصصة، يرجى الاطلاع على تحميل وإضافة خطوط أنابيب مخصصة
- سلسلة نصية، وهي repo id (على سبيل المثال
- force_download (
bool، اختياري، القيمة الافتراضيةFalse) — ما إذا كان يجب إجبار إعادة تنزيل أوزان النموذج وملفات الإعداد، مع تجاوز النسخ المخزنة مؤقتًا إذا كانت موجودة. - cache_dir (
Union[str, os.PathLike], اختياري) — المسار إلى مجلد حيث يتم تخزين إعدادات النموذج المُدرَّب مسبقًا المُحمَّل مؤقتًا إذا لم يُستخدم المجلد المؤقت القياسي. - proxies (
Dict[str, str]، اختياري) — قاموس لخوادم الوكيل (proxy) للاستخدام حسب البروتوكول أو نقطة النهاية، على سبيل المثال{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. تُستخدم هذه الوكلاء في كل طلب. - output_loading_info(
bool, اختياري، القيمة الافتراضيةFalse) — ما إذا كان يجب إرجاع قاموس يحتوي على المفاتيح الناقصة والمفاتيح غير المتوقعة ورسائل الأخطاء أم لا. - local_files_only (
bool، اختياري، القيمة الافتراضيةFalse) — ما إذا كان سيتم تحميل أوزان النموذج وملفات الإعداد المحلية فقط أم لا. إذا تم ضبطه علىTrue، فلن يتم تنزيل النموذج من Hub. - token (
strأو bool، اختياري) — الرمز الذي يُستخدم كتفويض حامل HTTP للملفات البعيدة. إذا كانTrue، يُستخدم الرمز المولّد منdiffusers-cli login(المخزّن في~/.huggingface). - revision (
str، اختياري، القيمة الافتراضية"main") — الإصدار المحدد من النموذج الذي سيتم استخدامه. يمكن أن يكون اسم فرع، أو اسم وسم، أو معرف commit، أو أي معرّف مسموح به بواسطة Git. - custom_revision (
str، اختياري) — الإصدار المحدد من النموذج الذي سيتم استخدامه. يمكن أن يكون اسم فرع، أو اسم وسم، أو معرّف التزامن (commit id) مشابهًا لـrevisionعند تحميل خط أنابيب مخصص من Hub. القيمة الافتراضية هي أحدث إصدار مستقر من 🤗 Diffusers. - mirror (
str، اختياري) — مصدر مرآة لحل مشاكل إمكانية الوصول إذا كنت تقوم بتنزيل نموذج في الصين. نحن لا نضمن حداثة المصدر أو أمانه، وينبغي لك الرجوع إلى موقع المرآة لمزيد من المعلومات. - device_map (
str، اختياري) — الاستراتيجية التي تحدد كيفية توزيع المكونات المختلفة للخط الأنابيب على الأجهزة المتاحة. حاليًا، يتم دعمdevice_map“balanced” فقط. راجع هذا لمعرفة المزيد. - max_memory (
Dict, اختياري) — قاموس معرّف الجهاز للذاكرة القصوى. إذا لم يُضبط، فسيتم افتراضياً استخدام أقصى ذاكرة متاحة لكل وحدة معالجة رسومية (GPU) والذاكرة العشوائية المتاحة للمعالج المركزي (CPU). - offload_folder (
strأوos.PathLike، اختياري) — المسار الذي تُموضع فيه الأوزان إذا احتوى device_map على القيمة"disk". - offload_state_dict (
bool، اختياري) — إذا كانTrue، يتم نقل قاموس الحالة على وحدة المعالجة المركزية مؤقتًا إلى القرص الصلب لتجنب نفاد ذاكرة وحدة المعالجة المركزية إذا لم يتسع وزن قاموس الحالة على وحدة المعالجة المركزية + أكبر شريحة من نقطة الحفظ. القيمة الافتراضية هيTrueعند وجود أي نقل إلى القرص. - low_cpu_mem_usage (
bool، اختياري، القيمة الافتراضيةTrueإذا كان إصدار torch >= 1.9.0 وإلاFalse) — تسريع تحميل النموذج من خلال تحميل الأوزان المُسبقة التدريب فقط دون تهيئة الأوزان. كما يحاول هذا الخيار عدم استخدام أكثر من 1x حجم النموذج في ذاكرة المعالج المركزي (بما في ذلك الذروة) أثناء تحميل النموذج. مدعوم فقط لـ PyTorch >= 1.9.0. إذا كنت تستخدم إصدارًا أقدم من PyTorch، فإن تعيين هذا الحجج إلىTrueسيؤدي إلى رفع خطأ. - use_safetensors (
bool، اختياري، القيمة الافتراضيةNone) — إذا تم تعيينه إلىNone، يتم تنزيل أوزان safetensors إذا كانت متاحة و إذا كانت مكتبة safetensors مثبتة. إذا تم تعيينه إلىTrue، يتم تحميل النموذج بشكل إجباري من أوزان safetensors. إذا تم تعيينه إلىFalse، لا يتم تحميل أوزان safetensors. - use_onnx (
bool، اختياري، القيمة الافتراضيةNone) — إذا تم ضبطه علىTrue، فسيتم تنزيل أوزان ONNX دائمًا إذا كانت موجودة. إذا تم ضبطه علىFalse، فلن يتم تنزيل أوزان ONNX أبدًا. افتراضيًا، تكون القيمة الافتراضية لـuse_onnxهي سمة الفئة_is_onnxوالتي تكونFalseلخطوط الأنابيب غير ONNX وTrueلخطوط الأنابيب ONNX. تشمل أوزان ONNX كلا من الملفات التي تنتهي بـ.onnxو.pb. - kwargs (قاموس متبقٍ من معاملات الكلمات المفتاحية، اختياري) —
يمكن استخدامه لتجاوز متغيرات التحميل والحفظ (مكونات خط الأنابيب الخاصة بفئة خط الأنابيب المحددة). تُمرَّر المكونات المُتجاوزة مباشرةً إلى طريقة
__init__لخطوط الأنابيب. راجع المثال أدناه لمزيد من المعلومات. - variant (
str، اختياري) — تحميل الأوزان من اسم ملف متغير محدد مثل"fp16"أو"ema". - disable_mmap (‘bool’، اختياري، القيمة الافتراضية ‘False’) — ما إذا كان سيتم تعطيل mmap عند تحميل نموذج Safetensors. قد يؤدي هذا الخيار إلى أداء أفضل عندما يكون النموذج على وحدة تخزين شبكية أو قرص صلب، حيث قد لا تتعامل هذه الوسائط بشكل جيد مع طبيعة عمليات البحث (seek) التي يتطلبها mmap.
أنشئ خط أنابيب انتشار PyTorch من أوزان خط أنابيب مُدرَّب مسبقًا.
يتم ضبط خط الأنابيب في وضع التقييم (model.eval()) افتراضيًا.
إذا ظهرت لك رسالة الخطأ أدناه، فأنت بحاجة إلى ضبط الأوزان لمهمتك التالية:
Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.> لاستخدام النماذج الخاصة أو المقيّدة، سجّل الدخول باستخدام
hf > auth login.
أمثلة:
>>> from diffusers import DiffusionPipeline
>>> # Download pipeline from huggingface.co and cache.
>>> pipeline = DiffusionPipeline.from_pretrained("CompVis/ldm-text2im-large-256")
>>> # Download pipeline that requires an authorization token
>>> # For more information on access tokens, please refer to this section
>>> # of the documentation](https://huggingface.co/docs/hub/security-tokens)
>>> pipeline = DiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")
>>> # Use a different scheduler
>>> from diffusers import LMSDiscreteScheduler
>>> scheduler = LMSDiscreteScheduler.from_config(pipeline.scheduler.config)
>>> pipeline.scheduler = schedulerطريقة تنفّذ ما يلي:
- ينقل جميع المكونات.
- يزيل جميع خطافات النموذج التي أُضيفت عند استخدام
enable_model_cpu_offload، ثم يطبقها مرة أخرى. في حال لم يتم نقل النموذج، تكون هذه الدالة بلا تأثير. - يعيد تعيين خطافات
register_hook()المضافة لمكونات إزالة الضوضاء (denoiser) التي تحتوي على حالة (stateful).
تأكد من إضافة هذه الدالة إلى نهاية دالة __call__ في خط أنابيبك حتى تعمل بشكل صحيح عند تطبيق enable_model_cpu_offload.
تحويل صورة NumPy أو دفعة من الصور إلى صورة PIL.
يزيل جميع الخطافات التي أُضيفت عند استخدام enable_sequential_cpu_offload أو enable_model_cpu_offload.
يعيد تعيين خرائط الأجهزة (إن وجدت) إلى None.
save_pretrained
< source >( save_directory: str | os.PathLikesafe_serialization: bool = Truevariant: str | None = Nonemax_shard_size: int | str | None = Nonepush_to_hub: bool = Falseuse_flashpack: bool = False**kwargs )
المعاملات
- save_directory (
strأوos.PathLike) — المجلد الذي سيتم حفظ خط الأنابيب فيه. سيتم إنشاؤه إذا لم يكن موجودًا. - safe_serialization (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان سيتم حفظ النموذج باستخدامsafetensorsأو بالطريقة التقليدية الخاصة بـ PyTorch باستخدامpickle. - variant (
str، اختياري) — إذا تم تحديده، تُحفظ الأوزان بالتنسيقpytorch_model.<variant>.bin. - max_shard_size (
intأوstr، القيمة الافتراضيةNone) — الحد الأقصى لحجم نقطة التفتيش قبل تقسيمها إلى أجزاء. ستكون نقاط التفتيش المقسمة بعد ذلك كل منها بحجم أقل من هذا الحجم. إذا عُبر عنها كنص، فيجب أن تتكون من أرقام تليها وحدة (مثل"5GB"). إذا عُبر عنها كعدد صحيح، تكون الوحدة هي البايت. لاحظ أن هذا الحد سيُخفَّض بعد فترة زمنية معينة (بدءًا من أكتوبر 2024) للسماح للمستخدمين بالترقية إلى أحدث إصدار منdiffusers. وذلك لإرساء حجم افتراضي مشترك لهذا الحجة عبر مكتبات مختلفة في منظومة Hugging Face (مثلtransformers، وaccelerate). - push_to_hub (
bool، اختياري، الافتراضيFalse) — ما إذا كان سيتم دفع نموذجك إلى مركز نماذج Hugging Face بعد حفظه. يمكنك تحديد المستودع الذي تريد الدفع إليه باستخدامrepo_id(سيكون الافتراضي هو اسمsave_directoryفي نطاقك). - kwargs (
Dict[str, Any]، اختياري) — معلمات إضافية تُمرَّر إلى طريقة push_to_hub().
احفظ جميع متغيرات خط المعالجة القابلة للحفظ في مجلد. يمكن حفظ متغير خط المعالجة وتحميله إذا كانت صفته (class) تنفّذ كلًا من طريقة حفظ وطريقة تحميل. يمكن إعادة تحميل خط المعالجة بسهولة باستخدام طريقة الفئة from_pretrained().
diffusers.StableDiffusionMixin.enable_freeu
< source >( s1: floats2: floatb1: floatb2: float )
المعاملات
- s1 (
float) — معامل التوسيع للمرحلة 1 لتخفيف مساهمات ميزات التخطي. يتم ذلك للتخفيف من “تأثير الإفراط في التنعيم” في عملية إزالة الضوضاء المعززة. - s2 (
float) — معامل التوسيع للمرحلة 2 لتخفيف مساهمات ميزات التخطي. يتم ذلك للتخفيف من “تأثير الإفراط في التنعيم” في عملية إزالة الضوضاء المعززة. - b1 (
float) — معامل التوسيع للمرحلة 1 لتضخيم مساهمات ميزات الهيكل الأساسي. - b2 (
float) — معامل التوسيع للمرحلة 2 لتضخيم مساهمات ميزات الهيكل الأساسي.
يُفعّل آلية FreeU كما في https://huggingface.co/papers/2309.11497.
تمثل البادئات التي تلي معاملات التوسيع المراحل التي تُطبَّق فيها.
يرجى الرجوع إلى المستودع الرسمي لمعرفة التوليفات من القيم التي يُعرف أنها تعمل بشكل جيد لأنابيب مختلفة مثل Stable Diffusion v1 وv2 وStable Diffusion XL.
يعطّل آلية FreeU إذا كانت مفعّلة.
PushToHubMixin
مزيج (Mixin) لدفع نموذج أو مجدول أو خط أنابيب إلى Hugging Face Hub.
push_to_hub
< source >( repo_id: strcommit_message: str | None = Noneprivate: bool | None = Nonetoken: str | None = Nonecreate_pr: bool = Falsesafe_serialization: bool = Truevariant: str | None = Nonesubfolder: str | None = None )
المعاملات
- repo_id (
str) — اسم المستودع الذي تريد دفع ملفات النموذج أو المجدول أو خط الأنابيب إليه. يجب أن يحتوي على اسم مؤسستك عند الدفع إلى مؤسسة. كما يمكن أن يكونrepo_idمسارًا إلى مجلد محلي. - commit_message (
str، اختياري) — الرسالة التي تُرسل عند الدفع. القيمة الافتراضية هي"Upload {object}". - private (
bool، اختياري) — ما إذا كان سيتم جعل المستودع خاصًا. إذا كانNone(الافتراضي)، فسيكون المستودع عامًا ما لم يكن الافتراضي للمنظمة هو الخاص. يتم تجاهل هذه القيمة إذا كان المستودع موجودًا بالفعل. - token (
str، اختياري) — الرمز الذي يُستخدم كتوكن مصادقة HTTP Bearer للملفات البعيدة. الرمز الذي يتم إنشاؤه عند تشغيلhf auth login(يُخزَّن في~/.huggingface). - create_pr (
bool، اختياري، القيمة الافتراضيةFalse) — ما إذا كان سيتم إنشاء طلب سحب (PR) بالملفات المرفوعة أم الالتزام مباشرة. - safe_serialization (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان سيتم تحويل أوزان النموذج إلى صيغةsafetensorsأم لا. - variant (
str، اختياري) — إذا تم تحديده، تُحفظ الأوزان بالتنسيقpytorch_model.<variant>.bin.
ارفع ملفات النموذج أو المجدول أو خط الأنابيب إلى 🤗 Hugging Face Hub.
أمثلة:
from diffusers import UNet2DConditionModel
unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-2", subfolder="unet")
# Push the `unet` to your namespace with the name "my-finetuned-unet".
unet.push_to_hub("my-finetuned-unet")
# Push the `unet` to an organization with the name "my-finetuned-unet".
unet.push_to_hub("your-org/my-finetuned-unet")المكالمات العكسية
فئة diffusers.callbacks.PipelineCallback
< source >( cutoff_step_ratio = 1.0cutoff_step_index = None )
الفئة الأساسية لجميع الاستدعاءات الخلفية الرسمية المستخدمة في خط المعالجة. توفر هذه الفئة هيكلًا لتنفيذ استدعاءات خلفية مخصصة، وتضمن أن جميع الاستدعاءات الخلفية تملك واجهة متسقة.
يرجى تنفيذ ما يلي: tensor_inputs: يجب أن يعيد هذا قائمةً بمدخلات المصفوفات (tensors) الخاصة بإجراء الاستدعاء (callback) الخاص بك. لن تتمكن من تضمين سوى المتغيرات المدرجة في خاصية ._callback_tensor_inputs لفئة خط الأنابيب (pipeline) الخاص بك. callback_fn: يحدد هذا الإجراء الوظيفة الأساسية لإجراء الاستدعاء الخاص بك.
فئة diffusers.callbacks.SDCFGCutoffCallback
< source >( cutoff_step_ratio = 1.0cutoff_step_index = None )
دالة الاستدعاء (Callback) لخطوط أنابيب Stable Diffusion. بعد عدد معين من الخطوات (المحدد بواسطة cutoff_step_ratio أو cutoff_step_index)، ستقوم هذه الدالة بتعطيل CFG.
ملاحظة: يعدّل هذا المستدعي خط الأنابيب عن طريق تغيير خاصية _guidance_scale إلى 0.0 بعد خطوة القطع.
فئة diffusers.callbacks.SDXLCFGCutoffCallback
< source >( cutoff_step_ratio = 1.0cutoff_step_index = None )
دالة الاستدعاء (Callback) الخاصة بخطوط أنابيب Stable Diffusion XL الأساسية. بعد عدد معين من الخطوات (المحدد بواسطة cutoff_step_ratio أو cutoff_step_index)، ستقوم هذه الدالة بتعطيل CFG.
ملاحظة: يعدّل هذا المستدعي خط الأنابيب عن طريق تغيير خاصية _guidance_scale إلى 0.0 بعد خطوة القطع.
فئة diffusers.callbacks.SDXLControlnetCFGCutoffCallback
< source >( cutoff_step_ratio = 1.0cutoff_step_index = None )
دالة الاستدعاء (Callback) لخطوط أنابيب Controlnet Stable Diffusion XL. بعد عدد معين من الخطوات (المحدد بواسطة cutoff_step_ratio أو cutoff_step_index)، ستقوم هذه الدالة بتعطيل CFG.
ملاحظة: يعدّل هذا المستدعي خط الأنابيب عن طريق تغيير خاصية _guidance_scale إلى 0.0 بعد خطوة القطع.
فئة diffusers.callbacks.IPAdapterScaleCutoffCallback
< source >( cutoff_step_ratio = 1.0cutoff_step_index = None )
دالة الاستدعاء (Callback) لأي خط أنابيب يرث IPAdapterMixin. بعد عدد معين من الخطوات (المحدد بواسطة cutoff_step_ratio أو cutoff_step_index)، ستقوم هذه الدالة بإعداد مقياس IP Adapter على 0.0.
ملاحظة: يعدّل هذا المستدعي معالجات الانتباه الخاصة بمحوّل IP Adapter عن طريق تعيين المقياس إلى 0.0 بعد خطوة القطع.
فئة diffusers.callbacks.SD3CFGCutoffCallback
< source >( cutoff_step_ratio = 1.0cutoff_step_index = None )
دالة الاستدعاء (Callback) لخطوط أنابيب Stable Diffusion 3. بعد عدد معين من الخطوات (المحدد بواسطة cutoff_step_ratio أو cutoff_step_index)، ستقوم هذه الدالة بتعطيل CFG.
ملاحظة: يعدّل هذا المستدعي خط الأنابيب عن طريق تغيير خاصية _guidance_scale إلى 0.0 بعد خطوة القطع.