أدوات

دوال مساعدة وأدوات للعمل مع 🤗 Diffusers.

numpy_to_pil

diffusers.utils.numpy_to_pil

< source >

( images )

تحويل صورة numpy أو دفعة من الصور إلى صورة PIL.

pt_to_pil

diffusers.utils.pt_to_pil

< source >

( images )

تحويل صورة torch إلى صورة PIL.

load_image

diffusers.utils.load_image

< source >

( image: str | PIL.Image.Imageconvert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None ) → PIL.Image.Image

المعاملات

image (str أو PIL.Image.Image) — الصورة التي سيتم تحويلها إلى صيغة صورة PIL.
convert_method (Callable[[PIL.Image.Image], PIL.Image.Image], اختياري) — طريقة تحويل تُطبَّق على الصورة بعد تحميلها. عند ضبطها على None سيتم تحويل الصورة إلى “RGB”.

يعيد

PIL.Image.Image

صورة PIL.

يحمّل image إلى صورة PIL.

load_video

diffusers.utils.load_video

< source >

( video: strconvert_method: typing.Optional[typing.Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]]] = Nonereturn_fps: bool = False ) → list[PIL.Image.Image] or tuple[list[PIL.Image.Image], float]

المعاملات

video (str) — رابط URL أو مسار Path لفيديو لتحويله إلى قائمة بصيغة صور PIL.
convert_method (Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]], اختياري) — طريقة تحويل تُطبَّق على الفيديو بعد تحميله. عند ضبطه على None سيتم تحويل الصور إلى “RGB”.
return_fps (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب إرجاع معدل الإطارات الذي تم ترميز الفيديو به أيضاً. وهو مطلوب في خطوط الأنابيب التي تعيد أخذ عينات من المدخلات إلى معدل الإطارات الذي يعمل به النموذج، لأن قائمة الإطارات لا تحمل هذه المعلومات.

يعيد

list[PIL.Image.Image] أو tuple[list[PIL.Image.Image], float]

الفيديو كقائمة من صور PIL، ومعدل إطاراته إذا تم تعيين return_fps.

يحمّل video إلى قائمة من صور PIL.

export_to_gif

diffusers.utils.export_to_gif

< source >

( image: list[PIL.Image.Image]output_gif_path: str = Nonefps: int = 10 )

export_to_video

diffusers.utils.export_to_video

< source >

( video_frames: list[np.ndarray] | list[PIL.Image.Image]output_video_path: str = Nonefps: int = 10quality: float = 5.0bitrate: int | None = Nonemacro_block_size: int | None = 16 )

quality: جودة مخرجات الفيديو. القيمة الافتراضية هي 5. يستخدم معدل بت متغير. أعلى جودة هي 10، وأدناها هي 0. اضبطها على None لمنع أعلام معدل البت المتغير من الوصول إلى FFMPEG حتى تتمكن من تحديدها يدويًا باستخدام output_params بدلاً من ذلك. تحديد معدل بت ثابت باستخدام bitrate يعطّل هذا المعامل.

bitrate: تعيين معدل بت ثابت لتشفير الفيديو. القيمة الافتراضية هي None مما يؤدي إلى استخدام معامل quality بدلاً من ذلك. ستنتج فيديوهات بجودة أفضل وحجم ملفات أصغر عند استخدام معامل معدل بت متغير quality بدلاً من تحديد معدل بت ثابت باستخدام هذا المعامل.

macro_block_size: قيود الحجم للفيديو. العرض والارتفاع، ويجب أن يكونا قابلين للقسمة على هذا الرقم. إذا لم يكونا قابلين للقسمة على هذا الرقم، فسيطلب imageio من ffmpeg تكبير الصورة إلى أقرب حجم قابل للقسمة على هذا الرقم. معظم مشفّرات الفيديو متوافقة مع حجم كتلة ماكرو (macroblock) يساوي 16 (الافتراضي)، وبعضها يمكن أن يكون أصغر (4، 8). لتعطيل هذه الميزة التلقائية، اضبطه على None أو 1، مع تحذير بأن العديد من مشغلات الفيديو لا تستطيع فك ترميز الفيديوهات ذات الأبعاد الفردية، وبعض مشفّرات الفيديو قد تعطي نتائج رديئة أو تفشل. راجع https://en.wikipedia.org/wiki/Macroblock.

encode_video

diffusers.utils.encode_video

< source >

المعاملات

video (List[PIL.Image.Image] أو np.ndarray أو torch.Tensor) — مصفوفة فيديو (video tensor) بأبعاد [frames, height, width, channels] بقيم بكسل صحيحة ضمن المدى [0, 255]. إذا كان المدخل np.ndarray، يُتوقع أن يكون مصفوفة أرقام عشرية بقيم ضمن المدى [0, 1] (وهو ما تعيده خطوط الأنابيب عادةً مع output_type="np").
fps (int) — عدد الإطارات في الثانية (FPS) للفيديو المُرمَّز.
output_path (str) — المسار الذي يُحفظ فيه الفيديو المُرمَّز.
audio (torch.Tensor، اختياري) — موجة صوتية ذات الشكل [audio_channels, samples].
audio_sample_rate — (int, اختياري): معدل أخذ العينات لموجة الصوت.
video_chunks_number (int, اختياري، القيمة الافتراضية 1) — عدد الأجزاء التي يُقسَّم إليها الفيديو للتشفير. سيتم تشفير كل جزء بشكل مستقل. غالباً ما يعتمد عدد الأجزاء المستخدمة على إعداد التقطيع (tiling config) الخاص بنموذج VAE للفيديو.

يقوم بتشفير فيديو مع صوت اختياري باستخدام مكتبة PyAV. يعتمد على الكود من مستودع LTX-2 الأصلي: https://github.com/Lightricks/LTX-2/blob/4f410820b198e05074a1e92de793e3b59e9ab5a0/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py#L182

make_image_grid

diffusers.utils.make_image_grid

< source >

( images: listrows: intcols: intresize: int = None )

يُعدّ شبكة واحدة من الصور. مفيد لأغراض التصور.

randn_tensor

diffusers.utils.torch_utils.randn_tensor

< source >

دالة مساعدة لإنشاء مصفوفات عشوائية على device المطلوب مع dtype المطلوب. عند تمرير قائمة من المولّدات، يمكنك تحديد البذرة لكل حجم دفعة على حدة. إذا تم تمرير مولّدات CPU، فإن المصفوفة تُنشأ دائمًا على CPU.

TorchDeviceBackend

فئة diffusers.utils.torch_utils.TorchDeviceBackend

< source >

( device: str | torch.device | None = None )

وكيل (Proxy) لمساحة الأسماء torch.<backend> (torch.cuda، torch.xpu، torch.mps، …) لجهاز واحد. الخصائص التي لا يحددها هذا الصنف هي خصائص الوحدة نفسها (synchronize، device_count، Stream، current_stream، …)؛ أما الطرق المعرفة هنا فتتجاوز العمليات التي يختلف توفرها بين الخلفيات (backends) وتحتاج إلى بديل احتياطي: مسح ذاكرة التخزين المؤقت، وتعيين البذرة (seeding)، واستعلامات الذاكرة. في حال عدم وجود device، يكتشف مُسرّع المضيف (host accelerator) عبر torch.accelerator. يثير استثناءً إذا لم يكن لدى torch وحدة للخلفية (backend) بدلاً من الرجوع بصمت إلى torch.cuda.

max_memory_allocated

< source >

( )

ذروة الذاكرة المخصصة على الجهاز بالبايت منذ آخر إعادة تعيين؛ 0 حيث لا يحتفظ البرنامج الخلفي بأي إحصاءات.

mem_get_info

< source >

( )

الذاكرة الحرة وإجمالي ذاكرة الجهاز بالبايت.

apply_layerwise_casting

diffusers.hooks.apply_layerwise_casting

< source >

( module: Modulestorage_dtype: dtypecompute_dtype: dtypeskip_modules_pattern: str | tuple[str, ...] = 'auto'skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = Nonenon_blocking: bool = False )

المعاملات

module (torch.nn.Module) — الوحدة التي سيتم تحويل وحداتها الفرعية إلى نوع بيانات بدقة عالية للحساب، وإلى نوع بيانات بدقة منخفضة للتخزين.
storage_dtype (torch.dtype) — نوع البيانات (dtype) الذي يُحوَّل إليه الوحدة قبل وبعد مسار الأمامي (forward pass) لأغراض التخزين.
compute_dtype (torch.dtype) — نوع البيانات (dtype) الذي يُحوَّل إليه الوحدة (module) أثناء المرور الأمامي (forward pass) لأغراض الحساب.
skip_modules_pattern (tuple[str, ...])، القيمة الافتراضية "auto") — قائمة أنماط مطابقة لأسماء الوحدات التي يجب تجاوزها أثناء عملية الصبّ على مستوى الطبقات. إذا تم ضبطها على "auto"، تُستخدم الأنماط الافتراضية. إذا تم ضبطها على None، لا يتم تجاوز أي وحدات. إذا تم ضبطها على None مع ضبط skip_modules_classes على None، تُطبَّق عملية الصبّ على مستوى الطبقات مباشرةً على الوحدة بدلا من وحداتها الفرعية الداخلية.
skip_modules_classes (tuple[Type[torch.nn.Module], ...]، القيمة الافتراضية None) — قائمة لفئات الوحدات التي يجب تجاوزها أثناء عملية الصب الطبقي (layerwise casting).
non_blocking (bool، القيمة الافتراضية False) — إذا كانت True، فإن عمليات تحويل الأوزان غير حاصِرة.

يطبّق الإقحام على مستوى الطبقات على وحدة محددة. يُتوقّع أن تكون الوحدة هنا من نوع Diffusers ModelMixin، لكنها يمكن أن تكون أي nn.Module يستخدم طبقات diffusers أو أساسيات pytorch.

مثال:

>>> import torch
>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     model_id, subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> apply_layerwise_casting(
...     transformer,
...     storage_dtype=torch.float8_e4m3fn,
...     compute_dtype=torch.bfloat16,
...     skip_modules_pattern=["patch_embed", "norm", "proj_out"],
...     non_blocking=True,
... )

apply_group_offloading

diffusers.hooks.apply_group_offloading

< source >

( module: Moduleonload_device: typing.Union[str, torch.device]offload_device: typing.Union[str, torch.device] = torch.device()offload_type: str | diffusers.hooks.group_offloading.GroupOffloadingType = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage: bool = Falseoffload_to_disk_path: str | None = Noneblock_modules: list[str] | None = Noneexclude_kwargs: list[str] | None = None )

المعاملات

module (torch.nn.Module) — الوحدة التي يُطبَّق عليها تفريغ المجموعة.
onload_device (torch.device) — الجهاز الذي تُحمَّل عليه مجموعة الوحدات.
offload_device (torch.device، الافتراضي torch.device("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).
block_modules (list[str], اختياري) — قائمة بأسماء الوحدات التي يجب معالجتها كتُحَف (blocks) لأغراض الإزاحة (offloading). إذا تم تقديمها، فسيتم النظر في هذه الوحدات فقط لأغراض الإزاحة على مستوى التُحَف. إذا لم يتم تقديمها، فسيتم استخدام منطق اكتشاف التُحَف الافتراضي.
exclude_kwargs (list[str]، اختياري) — قائمة بمفاتيح معاملات الكلمات المفتاحية التي يجب ألا تُعالج بواسطة send_to_device. هذا مفيد للحالات المتغيرة مثل قوائم التخزين المؤقت التي تحتاج إلى الحفاظ على هوية كائنها عبر عمليات الأمامية. إذا لم يُقدَّم، فسيتم استنتاجه من خاصية _skip_keys للوحدة إذا كانت موجودة.

يطبّق تفريغ المجموعات على الطبقات الداخلية لـ torch.nn.Module. لفهم ما هو تفريغ المجموعات، وأين يكون مفيداً، نحتاج أولاً إلى تقديم بعض السياق حول كيفية عمل طرق التفريغ الأخرى المدعومة.

عادةً، يتم تنفيذ الإزاحة على مستويين:

على مستوى الوحدة: في Diffusers، يمكن تفعيل ذلك باستخدام طريقة ModelMixin::enable_model_cpu_offload(). تعمل هذه الطريقة عن طريق نقل كل مكوّن من مكوّنات خط الأنابيب إلى وحدة المعالجة المركزية (CPU) للتخزين، ثم تحميله على جهاز التسريع عند الحاجة إليه للحساب. هذه الطريقة أكثر كفاءة في استخدام الذاكرة من إبقاء جميع المكوّنات على جهاز التسريع، لكن متطلبات الذاكرة لا تزال مرتفعة إلى حد كبير. لكي تعمل هذه الطريقة، يجب توفر ذاكرة تعادل حجم النموذج في نوع البيانات وقت التشغيل + حجم أكبر توترات التنشيط الوسيطة، وذلك لإكمال مسار الأمامي (forward pass).
على مستوى الأوراق: في Diffusers، يمكن تفعيل ذلك باستخدام طريقة ModelMixin::enable_sequential_cpu_offload(). تعمل هذه الطريقة عن طريق نقل معاملات مستوى الأوراق الأدنى في رسم الحساب إلى وحدة المعالجة المركزية (CPU) للتخزين، ونقل الأوراق فقط إلى جهاز التسريع لأداء الحسابات. يستخدم هذا الأسلوب أقل قدر من ذاكرة جهاز التسريع، لكنه قد يكون أبطأ بسبب العدد المفرط من عمليات المزامنة بين الأجهزة.

يعتبر تفريغ المجموعات (Group offloading) حلًا وسطًا بين الطريقتين. يعمل عن طريق تفريغ مجموعات من الطبقات الداخلية، (سواءً torch.nn.ModuleList أو torch.nn.Sequential). تستخدم هذه الطريقة ذاكرة أقل من تفريغ مستوى الوحدة (module-level offloading). كما أنها أسرع من تفريغ مستوى الورقة/التسلسلي (leaf-level/sequential offloading)، نظرًا لتقليل عدد مزامنات الأجهزة.

ميزة أخرى مدعومة (لأجهزة CUDA التي تدعم تدفقات نقل البيانات غير المتزامنة) هي القدرة على تداخل نقل البيانات والحساب لتقليل وقت التنفيذ الإجمالي مقارنةً بالتفريغ التسلسلي. يتم تمكين ذلك باستخدام الاستباق للطبقات مع التدفقات، أي أن الطبقة التي سيتم تنفيذها التالية تبدأ التحميل إلى جهاز المعالج التسارعي بينما يتم تنفيذ الطبقة الحالية - وهذا يزيد من متطلبات الذاكرة قليلاً. لاحظ أن هذا التنفيذ يدعم أيضًا التفريغ على مستوى الأوراق، لكنه يمكن أن يصبح أسرع بكثير عند استخدام التدفقات.

مثال:

>>> from diffusers import CogVideoXTransformer3DModel
>>> from diffusers.hooks import apply_group_offloading

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> apply_group_offloading(
...     transformer,
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="block_level",
...     num_blocks_per_group=2,
...     use_stream=True,
... )

Update on GitHub