Hugging Face's logo

Accelerate documentation

العمل مع النماذج الكبيرة

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v1.15.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

العمل مع النماذج الكبيرة

التوزيع والإزاحة

init_empty_weights

accelerate.init_empty_weights

< >

( include_buffers: bool | None = None )

المعاملات

  • include_buffers (bool، اختياري) — ما إذا كان يجب وضع جميع المخازن (buffers) على جهاز meta أثناء التهيئة أم لا.

مدير سياق يتم بموجبه تهيئة النماذج مع وضع جميع المعلمات على جهاز meta، مما يؤدي إلى إنشاء نموذج فارغ. يكون مفيداً عندما يؤدي مجرد تهيئة النموذج إلى استنفاد ذاكرة الوصول العشوائي المتاحة.

مثال:

import torch.nn as nn
from accelerate import init_empty_weights

# Initialize a model with 100 billions parameters in no time and without using any RAM.
with init_empty_weights():
    tst = nn.Sequential(*[nn.Linear(10000, 10000) for _ in range(1000)])

Any model created under this context manager has no weights. As such you can’t do something like model.to(some_device) with it. To load weights inside your empty model, see load_checkpoint_and_dispatch(). Make sure to overwrite the default device_map param for load_checkpoint_and_dispatch(), otherwise dispatch is not called.

cpu_offload

accelerate.cpu_offload

< >

( model: Moduleexecution_device: torch.device | None = Noneoffload_buffers: bool = Falsestate_dict: dict[str, torch.Tensor] | None = Nonepreload_module_classes: list[str] | None = None )

المعاملات

  • model (torch.nn.Module) — النموذج الذي سيتم نقله.
  • execution_device (torch.device، اختياري) — الجهاز الذي سيتم تنفيذ المرور الأمامي (forward pass) للنموذج عليه (يجب أن يكون GPU). سيُستخدم افتراضيًا جهاز أول معامل في النموذج.
  • offload_buffers (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تفريغ المخازن (buffers) مع معاملات النموذج أم لا.
  • state_dict (Dict[str, torch.Tensor]، اختياري) — قائمة الحالة الخاصة بالنموذج التي ستبقى على وحدة المعالجة المركزية (CPU).
  • preload_module_classes (List[str]، اختياري) — قائمة بالفئات التي يجب أن تُحمّل جميع أوزانها (حتى في الوحدات الفرعية) في بداية التقدّم الأمامي. يجب استخدام هذا فقط للفئات التي تحتوي على وحدات فرعية مسجّلة لكنها غير مستدعاة مباشرةً أثناء التقدّم الأمامي، على سبيل المثال إذا كان هناك طبقة خطية dense مسجّلة، لكن في التقدّم الأمامي، تُستخدم dense.weight وdense.bias في بعض العمليات بدلاً من استدعاء dense مباشرةً.

يفعّل هذا التحميل الكامل على وحدة المعالجة المركزية (CPU) لنموذج. ونتيجةً لذلك، سيتم نقل جميع معاملات النموذج إلى خارج الجهاز، وسيتم الاحتفاظ بنسخة واحدة فقط من قاموس الحالة (state dict) للنموذج. أثناء المرور الأمامي (forward pass)، سيتم استخراج المعاملات من ذلك القاموس ووضعها على جهاز التنفيذ المُمرَّر، وذلك عند الحاجة إليها، ثم يتم نقلها إلى خارج الجهاز مرة أخرى.

cpu_offload_with_hook

accelerate.cpu_offload_with_hook

< >

( model: Moduleexecution_device: int | str | torch.device | None = Noneprev_module_hook: accelerate.hooks.UserCpuOffloadHook | None = None )

المعاملات

  • model (torch.nn.Module) — النموذج الذي سيتم نقله.
  • execution_device(str, int or torch.device, اختياري) — الجهاز الذي يجب أن يُنفَّذ عليه النموذج. سيكون الافتراضي هو جهاز MPS إذا كان متاحًا، ثم الجهاز 0 إذا كان هناك جهاز تسريع، وأخيرًا المعالج المركزي (CPU).
  • prev_module_hook (UserCpuOffloadHook، اختياري) — الخطاف الذي تعيده هذه الدالة لنموذج سابق في خط الأنابيب الذي تعمل عليه. إذا تم تمريره، فسيتم استدعاء طريقة الإزاحة الخاصة به مباشرةً قبل التقدّم (forward) للنموذج الذي يُثبَّت عليه هذا الخطاف.

ينقل نموذجًا إلى وحدة المعالجة المركزية (CPU) ويعيده إلى جهاز التنفيذ عند التشغيل. والفرق مع cpu_offload() هو أن النموذج يبقى على جهاز التنفيذ بعد التمرير الأمامي ولا يُنقل مرة أخرى إلا عند استدعاء طريقة offload الخاصة بـ hook المُعاد. مفيد للأنابيب التي تشغّل نموذجًا في حلقة.

مثال:

model_1, hook_1 = cpu_offload_with_hook(model_1, device)
model_2, hook_2 = cpu_offload_with_hook(model_2, device, prev_module_hook=hook_1)
model_3, hook_3 = cpu_offload_with_hook(model_3, device, prev_module_hook=hook_2)

hid_1 = model_1(input)
for i in range(50):
    # model1 is offloaded on the CPU at the first iteration, model 2 stays on the GPU for this whole loop.
    hid_2 = model_2(hid_1)
# model2 is offloaded to the CPU just before this forward.
hid_3 = model_3(hid_3)

# For model3, you need to manually call the hook offload method.
hook_3.offload()

disk_offload

accelerate.disk_offload

< >

( model: Moduleoffload_dir: str | os.PathLikeexecution_device: torch.device | None = Noneoffload_buffers: bool = Falsepreload_module_classes: list[str] | None = None )

المعاملات

  • model (torch.nn.Module) — النموذج الذي سيتم نقله.
  • offload_dir (str أو os.PathLike) — المجلد الذي يتم فيه تفريغ أوزان النموذج (أو المكان الذي تكون فيه أوزان النموذج مفروغة بالفعل).
  • execution_device (torch.device، اختياري) — الجهاز الذي ستُنفَّذ عليه عملية المرور الأمامي (forward pass) للنموذج (يجب أن يكون GPU). سيُستخدم افتراضيًا جهاز أول معامل في النموذج.
  • offload_buffers (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تفريغ المخازن (buffers) مع معاملات النموذج أم لا.
  • preload_module_classes (List[str]، اختياري) — قائمة بالفئات التي يجب أن تُحمّل جميع أوزانها (حتى في الوحدات الفرعية) في بداية التقدّم الأمامي. يجب استخدام هذا فقط للفئات التي تحتوي على وحدات فرعية مسجّلة لكنها غير مستدعاة مباشرةً أثناء التقدّم الأمامي، على سبيل المثال إذا كان هناك طبقة خطية dense مسجّلة، لكن في التقدّم الأمامي، تُستخدم dense.weight وdense.bias في بعض العمليات بدلاً من استدعاء dense مباشرةً.

يفعّل هذا التحميل الكامل على القرص لنموذج. ونتيجةً لذلك، سيتم نقل جميع معاملات النموذج كمصفوفة مرمّزة بالذاكرة في مجلد محدد. أثناء المرور الأمامي، سيتم الوصول إلى المعاملات من ذلك المجلد ووضعها على جهاز التنفيذ المُمرَّر كما هي عند الحاجة إليها، ثم يتم نقلها مرة أخرى.

dispatch_model

accelerate.dispatch_model

< >

( model: Moduledevice_map: dictmain_device: torch.device | None = Nonestate_dict: dict[str, torch.Tensor] | None = Noneoffload_dir: str | os.PathLike | None = Noneoffload_index: dict[str, str] | None = Noneoffload_buffers: bool = Falseskip_keys: str | list[str] | None = Nonepreload_module_classes: list[str] | None = Noneforce_hooks: bool = False )

المعاملات

  • model (torch.nn.Module) — النموذج المراد إرساله.
  • device_map (Dict[str, Union[str, int, torch.device]]) — قاموس يربط أسماء الوحدات في state_dict للنماذج بالجهاز الذي يجب أن تُنقل إليه. لاحظ أن "disk" مقبول حتى لو لم يكن قيمة صحيحة لـ torch.device.
  • main_device (str أو int أو torch.device، اختياري) — جهاز التنفيذ الرئيسي. سيُستخدم الجهاز الأول في device_map الذي يختلف عن "cpu" أو "disk" افتراضيًا.
  • state_dict (Dict[str, torch.Tensor]، اختياري) — قائمة الحالة (state dict) للجزء من النموذج الذي سيُحفظ على وحدة المعالجة المركزية (CPU).
  • offload_dir (str أو os.PathLike) — المجلد الذي يتم فيه تفريغ أوزان النموذج (أو المكان الذي تكون فيه أوزان النموذج مفروغة بالفعل).
  • offload_index (Dict، اختياري) — قاموس من اسم الوزن إلى معلوماته (dtype/ shape أو اسم ملف safetensors). سيُستخدم بشكل افتراضي الفهرس المحفوظ في save_folder.
  • offload_buffers (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تفريغ المخازن (buffers) مع معاملات النموذج أم لا.
  • skip_keys (str أو List[str]، اختياري) — قائمة بالمفاتيح التي يجب تجاهلها عند نقل المدخلات أو المخرجات بين الأجهزة.
  • preload_module_classes (List[str]، اختياري) — قائمة بالفئات التي يجب أن تُحمّل جميع أوزانها (حتى في الوحدات الفرعية) في بداية التقدّم الأمامي. يجب استخدام هذا فقط للفئات التي تحتوي على وحدات فرعية مسجّلة لكنها غير مستدعاة مباشرةً أثناء التقدّم الأمامي، على سبيل المثال إذا كان هناك طبقة خطية dense مسجّلة، لكن في التقدّم الأمامي، تُستخدم dense.weight وdense.bias في بعض العمليات بدلاً من استدعاء dense مباشرةً.
  • force_hooks (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب إجبار تثبيت خطافات الجهاز على النموذج حتى لو تم توزيع جميع الطبقات على جهاز واحد.

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

load_checkpoint_and_dispatch

accelerate.load_checkpoint_and_dispatch

< >

( model: Modulecheckpoint: str | os.PathLikedevice_map: str | dict[str, int | str | torch.device] | None = Nonemax_memory: dict[int | str, int | str] | None = Noneno_split_module_classes: list[str] | None = Noneoffload_folder: str | os.PathLike | None = Noneoffload_buffers: bool = Falsedtype: str | torch.dtype | None = Noneoffload_state_dict: bool | None = Noneskip_keys: str | list[str] | None = Nonepreload_module_classes: list[str] | None = Noneforce_hooks: bool = Falsestrict: bool = Falsefull_state_dict: bool = Truebroadcast_from_rank0: bool = False )

المعاملات

  • model (torch.nn.Module) — النموذج الذي نرغب في تحميل نقطة تفتيش (checkpoint) فيه.
  • checkpoint (str أو os.PathLike) — نقطة التفتيش (checkpoint) المجلد الذي سيتم تحميله. يمكن أن تكون:
    • مسار إلى ملف يحتوي على حالة النموذج الكاملة
    • مسار إلى ملف .json يحتوي على فهرس لنقطة تحقق مقسمة
    • مسار إلى مجلد يحتوي على ملف .index.json فريد وقطع نقطة التفتيش.
  • device_map (Dict[str, Union[int, str, torch.device]], اختياري) — خريطة تحدد المكان الذي يجب أن يذهب إليه كل وحدة فرعية. لا حاجة إلى تحديد كل اسم معلم/مخزن، فبمجرد إدخال اسم وحدة معينة، سيتم إرسال جميع وحداتها الفرعية إلى نفس الجهاز.

    لحساب device_map الأكثر تحسينًا تلقائيًا بواسطة Accelerate، اضبط device_map="auto". لمزيد من المعلومات حول كل خيار، راجع هنا. القيمة الافتراضية هي None، مما يعني أنه لن يتم استدعاء dispatch_model().

  • max_memory (Dict, اختياري) — قاموس يربط معرّف الجهاز بحدّ الذاكرة الأقصى. إذا لم يُضبط، فسيُستخدم الحد الأقصى للذاكرة المتاحة لكل وحدة معالجة رسومية (GPU) والذاكرة العشوائية المتاحة للمعالج المركزي (CPU).
  • no_split_module_classes (List[str]، اختياري) — قائمة بأسماء فئات الطبقات التي يجب ألا تُقسَّم عبر الأجهزة (على سبيل المثال أي طبقة تحتوي على اتصال متبقي).
  • offload_folder (str أو os.PathLike، اختياري) — إذا احتوى device_map على أي قيمة "disk"، فهو المجلد الذي سننقل إليه الأوزان.
  • offload_buffers (bool، اختياري، القيمة الافتراضية False) — في الطبقات التي يتم نقلها إلى وحدة المعالجة المركزية أو القرص الصلب، ما إذا كان سيتم نقل المخازن (buffers) إلى جانب المعاملات أم لا.
  • dtype (str أو torch.dtype، اختياري) — إذا تم تقديمه، سيتم تحويل الأوزان إلى ذلك النوع عند التحميل.
  • offload_state_dict (bool، اختياري) — إذا كان True، فسيتم نقل قاموس حالة المعالج المركزي مؤقتًا إلى القرص الصلب لتجنب نفاد ذاكرة المعالج المركزي إذا لم يتسع وزن قاموس حالة المعالج المركزي + أكبر شريحة. سيكون الافتراضي True إذا احتوى خريطة الأجهزة المختارة على قيم "disk".
  • skip_keys (str أو List[str]، اختياري) — قائمة بالمفاتيح التي يجب تجاهلها عند نقل المدخلات أو المخرجات بين الأجهزة.
  • preload_module_classes (List[str]، اختياري) — قائمة بالفئات التي يجب أن تُحمّل جميع أوزانها (حتى في الوحدات الفرعية) في بداية التقدّم الأمامي. يجب استخدام هذا فقط للفئات التي تحتوي على وحدات فرعية مسجّلة لكنها غير مستدعاة مباشرةً أثناء التقدّم الأمامي، على سبيل المثال إذا كان هناك طبقة خطية dense مسجّلة، لكن في التقدّم الأمامي، تُستخدم dense.weight وdense.bias في بعض العمليات بدلاً من استدعاء dense مباشرةً.
  • force_hooks (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب إجبار تثبيت خطافات الجهاز على النموذج حتى لو تم توزيع جميع الطبقات على جهاز واحد.
  • strict (bool، اختياري، الافتراضي False) — ما إذا كان سيتم فرض مطابقة مفاتيح state_dict في نقطة الحفظ مع مفاتيح state_dict للنموذج بشكل صارم.
  • full_state_dict (bool، اختياري، القيمة الافتراضية True) — إذا تم تعيين هذا إلى True، فسيتم تجميع جميع الموترات في state_dict المحمّل. لن يكون هناك ShardedTensor أو DTensor في state_dict المحمّل.
  • broadcast_from_rank0 (False، اختياري، القيمة الافتراضية False) — عندما تكون الخانة True، يجب تهيئة ProcessGroup موزّع. يجب أن يستقبل rank0 حالة state_dict كاملة، وسيبثّ المصفوفات (tensors) الموجودة في state_dict واحدة تلو الأخرى إلى الرتب الأخرى. ستستقبل الرتب الأخرى المصفوفات وتُجزّئها (إن كان ذلك مطبقاً) وفقاً للتجزئات المحلية في النموذج.

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

مثال:

>>> from accelerate import init_empty_weights, load_checkpoint_and_dispatch
>>> from huggingface_hub import hf_hub_download
>>> from transformers import AutoConfig, AutoModelForCausalLM

>>> # Download the Weights
>>> checkpoint = "EleutherAI/gpt-j-6B"
>>> weights_location = hf_hub_download(checkpoint, "pytorch_model.bin")

>>> # Create a model and initialize it with empty weights
>>> config = AutoConfig.from_pretrained(checkpoint)
>>> with init_empty_weights():
...     model = AutoModelForCausalLM.from_config(config)

>>> # Load the checkpoint and dispatch it to the right devices
>>> model = load_checkpoint_and_dispatch(
...     model, weights_location, device_map="auto", no_split_module_classes=["GPTJBlock"]
... )

load_checkpoint_in_model

accelerate.load_checkpoint_in_model

< >

( model: Modulecheckpoint: str | os.PathLikedevice_map: dict[str, int | str | torch.device] | None = Noneoffload_folder: str | os.PathLike | None = Nonedtype: str | torch.dtype | None = Noneoffload_state_dict: bool = Falseoffload_buffers: bool = Falsekeep_in_fp32_modules: list[str] | None = Noneoffload_8bit_bnb: bool = Falsestrict: bool = Falsefull_state_dict: bool = Truebroadcast_from_rank0: bool = False )

المعاملات

  • model (torch.nn.Module) — النموذج الذي نرغب في تحميل نقطة تفتيش (checkpoint) فيه.
  • checkpoint (str أو os.PathLike) — نقطة التفتيش (checkpoint) المجلد الذي سيتم تحميله. يمكن أن تكون:
    • مسار إلى ملف يحتوي على حالة النموذج الكاملة
    • مسار إلى ملف .json يحتوي على فهرس لنقطة تحقق مقسمة
    • مسار إلى مجلد يحتوي على ملف .index.json فريد وقطع نقطة التفتيش.
    • مسار إلى مجلد يحتوي على ملف pytorch_model.bin فريد أو ملف model.safetensors.
  • device_map (Dict[str, Union[int, str, torch.device]], اختياري) — خريطة تحدد المكان الذي يجب أن يذهب إليه كل وحدة فرعية. لا حاجة إلى تفصيلها لكل اسم معلمة/مخزن، فبمجرد أن يكون اسم وحدة معينة داخلها، سيتم إرسال كل وحدة فرعية منها إلى نفس الجهاز.
  • offload_folder (str أو os.PathLike، اختياري) — إذا احتوى device_map على أي قيمة "disk"، فهو المجلد الذي سننقل إليه الأوزان.
  • dtype (str أو torch.dtype، اختياري) — إذا تم تقديمه، سيتم تحويل الأوزان إلى ذلك النوع عند التحميل.
  • offload_state_dict (bool، اختياري، القيمة الافتراضية False) — إذا كانت True، فسيتم نقل قاموس حالة المعالج المركزي مؤقتًا إلى القرص الصلب لتجنب نفاد ذاكرة المعالج المركزي إذا لم يتسع وزن قاموس حالة المعالج المركزي + أكبر شريحة.
  • offload_buffers (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تضمين المخازن (buffers) في الأوزان المُحمّلة على القرص.
  • keep_in_fp32_modules(List[str], اختياري) — قائمة بالوحدات التي نحتفظ بها في نوع البيانات torch.float32.
  • offload_8bit_bnb (bool، اختياري) — ما إذا كان سيتم تفعيل نقل وحدات 8-بت إلى وحدة المعالجة المركزية/القرص.
  • strict (bool، اختياري، الافتراضي False) — ما إذا كان سيتم فرض مطابقة مفاتيح state_dict في نقطة الحفظ مع مفاتيح state_dict للنموذج بشكل صارم.
  • full_state_dict (bool، اختياري، القيمة الافتراضية True) — إذا تم تعيين هذا إلى True، فسيتم تجميع جميع الموترات في state_dict المحمّل. لن يكون هناك ShardedTensor أو DTensor في state_dict المحمّل.
  • broadcast_from_rank0 (False، اختياري، القيمة الافتراضية False) — عندما تكون الخانة True، يجب تهيئة ProcessGroup موزّع. يجب أن يستقبل rank0 حالة state_dict كاملة، وسيبثّ المصفوفات (tensors) الموجودة في state_dict واحدة تلو الأخرى إلى الرتب الأخرى. ستستقبل الرتب الأخرى المصفوفات وتُجزّئها (إن كان ذلك مطبقاً) وفقاً للتجزئات المحلية في النموذج.

يحمّل نقطة تفتيش (قد تكون مقسّمة) داخل نموذج، مع إمكانية إرسال الأوزان إلى جهاز محدد أثناء تحميلها.

Once loaded across devices, you still need to call dispatch_model() on your model to make it able to run. To group the checkpoint loading and dispatch in one single call, use load_checkpoint_and_dispatch().

infer_auto_device_map

accelerate.infer_auto_device_map

< >

( model: Modulemax_memory: dict[int | str, int | str] | None = Noneno_split_module_classes: list[str] | None = Nonedtype: str | torch.dtype | None = Nonespecial_dtypes: dict[str, str | torch.dtype] | None = Noneverbose: bool = Falseclean_result: bool = Trueoffload_buffers: bool = Falsefallback_allocation: bool = False )

المعاملات

  • model (torch.nn.Module) — النموذج المراد تحليله.
  • max_memory (Dict, اختياري) — قاموس يربط معرّف الجهاز بالحد الأقصى للذاكرة. إذا لم يُضبط، فسيتم افتراض الحد الأقصى للذاكرة المتاحة. مثال: max_memory={0: "1GB"}.
  • no_split_module_classes (List[str]، اختياري) — قائمة بأسماء فئات الطبقات التي يجب ألا تُقسَّم عبر الأجهزة (على سبيل المثال أي طبقة تحتوي على اتصال متبقي).
  • dtype (str أو torch.dtype، اختياري) — إذا تم تقديمه، سيتم تحويل الأوزان إلى ذلك النوع عند التحميل.
  • special_dtypes (Dict[str, Union[str, torch.device]]، اختياري) — إذا تم تقديمه، أنواع البيانات الخاصة التي يجب مراعاتها لبعض الأوزان المحددة (ستتجاوز نوع البيانات المستخدم كافتراضي لجميع الأوزان).
  • verbose (bool، اختياري، الافتراضي False) — ما إذا كان سيتم توفير عبارات تصحيح الأخطاء أثناء بناء الدالة لـ device_map.
  • clean_result (bool، اختياري، القيمة الافتراضية True) — تنظيف خريطة الأجهزة الناتجة عن طريق تجميع جميع الوحدات الفرعية التي تعمل على نفس الجهاز معًا.
  • offload_buffers (bool، اختياري، القيمة الافتراضية False) — في الطبقات التي يتم نقلها إلى وحدة المعالجة المركزية أو القرص الصلب، ما إذا كان سيتم نقل المخازن (buffers) إلى جانب المعاملات أم لا.
  • fallback_allocation (bool، اختياري، القيمة الافتراضية False) — عند فشل التخصيص العادي، حاول تخصيص وحدة تتناسب مع حد الحجم باستخدام BFS.

احسب خريطة جهاز لنموذج معين مع إعطاء الأولوية لوحات GPU، ثم نقل الأحمال إلى وحدة المعالجة المركزية CPU، وأخيراً النقل إلى القرص، بحيث:

  • لا نتجاوز الذاكرة المتاحة لأي من وحدات معالجة الرسوميات.
  • إذا كان الإزاحة إلى وحدة المعالجة المركزية (CPU) مطلوبة، فسيظل هناك دائمًا مساحة متاحة على وحدة معالجة الرسوميات (GPU) 0 لإعادة طبقة الإزاحة إلى وحدة المعالجة المركزية (CPU) التي تمتلك أكبر حجم.
  • إذا كان النقل إلى وحدة المعالجة المركزية (CPU) مطلوبًا، فإننا لا نتجاوز ذاكرة الوصول العشوائي (RAM) المتاحة على وحدة المعالجة المركزية.
  • إذا كان التفريغ إلى القرص مطلوبًا، فسيظل هناك دائمًا مساحة متاحة على وحدة المعالجة المركزية لإعادة طبقة التفريغ على القرص التي تمتلك أكبر حجم.

تتم جميع العمليات الحسابية من خلال تحليل أحجام وأنواع البيانات (dtypes) لمعاملات النموذج. ونتيجةً لذلك، يمكن أن يكون النموذج على جهاز meta (كما لو تم تهيئته داخل مدير السياق init_empty_weights).

خطافات

ModelHook

فئة accelerate.hooks.ModelHook

< >

( )

خطاف يحتوي على استدعاءات (callbacks) تُنفَّذ مباشرةً قبل وبعد طريقة forward في النموذج. الفرق عن الخطافات الموجودة مسبقًا في PyTorch هو أنها تُمرَّر مع معاملات kwargs.

خاصية الفئة:

  • no_grad (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تنفيذ المرور الأمامي الفعلي تحت مُدير السياق torch.no_grad() أم لا.

detach_hook

< >

( module )

المعاملات

  • module (torch.nn.Module) — الوحدة المنفصلة عن هذا الخطاف.

يُنفَّذ عند فصل الخطاف عن وحدة.

init_hook

< >

( module )

المعاملات

  • module (torch.nn.Module) — الوحدة المرتبطة بهذا الخطاف.

يتم تنفيذه عند ربط الخطاف بالوحدة.

post_forward

< >

( moduleoutput ) → Any

المعاملات

  • module (torch.nn.Module) — الوحدة التي تم تنفيذ تمريرها الأمامي (forward pass) مباشرة قبل هذا الحدث.
  • output (Any) — مخرجات الوحدة.

يعيد

Any

المخرجات output بعد المعالجة.

لتنفيذها مباشرة بعد طريقة النموذج الأمامية.

pre_forward

< >

( module*args**kwargs ) → Tuple[Tuple[Any], Dict[Str, Any]]

المعاملات

  • module (torch.nn.Module) — الوحدة التي سيتم تنفيذ تمريرها الأمامي مباشرة بعد هذا الحدث.
  • args (Tuple[Any]) — الحُجج الموضعية المُمرَّرة إلى الوحدة.
  • kwargs (Dict[Str, Any]) — حُجج الكلمات المفتاحية المُمرَّرة إلى الوحدة.

يعيد

Tuple[Tuple[Any], Dict[Str, Any]]

مجموعة (tuple) تحتوي على args وkwargs المعالَجة.

لتنفيذها مباشرةً قبل طريقة النموذج الأمامية.

AlignDevicesHook

فئة accelerate.hooks.AlignDevicesHook

< >

( execution_device: int | str | torch.device | None = Noneoffload: bool = Falseio_same_device: bool = Falseweights_map: collections.abc.Mapping | None = Noneoffload_buffers: bool = Falseplace_submodules: bool = Falseskip_keys: str | list[str] | None = Nonetied_params_map: dict[int, dict[torch.device, torch.Tensor]] | None = None )

المعاملات

  • execution_device (torch.device، اختياري) — الجهاز الذي يجب وضع المدخلات وأوزان النموذج عليه قبل المرور الأمامي.
  • offload (bool، اختياري، الافتراضي False) — ما إذا كان يجب نقل الأوزان بعد عملية الأمامية أم لا.
  • io_same_device (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب وضع المخرجات على نفس الجهاز الذي كانت عليه المدخلات أم لا.
  • weights_map (Mapping[str, torch.Tensor]، اختياري) — عند تفريغ أوزان النموذج، خريطة (قد تكون كسولة) من أسماء المعاملات إلى قيم المصفوفات.
  • offload_buffers (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تضمين مخازن الوحدة المرتبطة عند الإزاحة.
  • place_submodules (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم وضع الوحدات الفرعية على execution_device أثناء حدث init_hook.

ModelHook عام يضمن أن المدخلات وأوزان النموذج موجودة على نفس الجهاز أثناء تمرير الأمامي للوحدة المرتبطة، مع إمكانية نقل الأوزان إلى جهاز آخر بعد تمرير الأمامي.

SequentialHook

فئة accelerate.hooks.SequentialHook

< >

( *hooks )

خطاف يمكن أن يحتوي على عدة خطافات ويتكرر عبرها عند كل حدث.

LayerwiseCastingHook

فئة accelerate.hooks.LayerwiseCastingHook

< >

( storage_dtype: dtypecompute_dtype: dtypenon_blocking: bool )

خطاف يقوم بإسقاط أوزان وحدة إلى نوع بيانات عالي الدقة للعمليات الحسابية، وإلى نوع بيانات منخفض الدقة للتخزين. قد يؤدي هذا العملية إلى فقدان في جودة المخرجات، لكنه يمكن أن يقلل بشكل كبير من بصمة الذاكرة.

إضافة الخطافات

add_hook_to_module

accelerate.hooks.add_hook_to_module

< >

( module: Modulehook: ModelHookappend: bool = False ) → torch.nn.Module

المعاملات

  • module (torch.nn.Module) — الوحدة التي سيتم إرفاق الخطاف بها.
  • hook (ModelHook) — الخطاف الذي يجب إرفاقه.
  • append (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب ربط الخطاف (hook) بآخر موجود (في حال احتوى الوحدة بالفعل على خطاف) أم لا.

يعيد

torch.nn.Module

نفس الوحدة، مع الخطاف المرفق (تُعدَّل الوحدة في مكانها، لذا يمكن تجاهل النتيجة).

يضيف خطافًا (hook) إلى وحدة محددة. سيؤدي هذا إلى إعادة كتابة طريقة forward للوحدة لتشمل الخطاف، ولإزالة هذا السلوك واستعادة طريقة forward الأصلية، استخدم remove_hook_from_module.

إذا كان الوحدة تحتوي بالفعل على خطاف، فسيتم استبداله بالخطاف الجديد المُمرَّر افتراضيًا. لربط خطافين معًا، قم بتمرير append=True، بحيث يربط الخطاف الحالي والخطاف الجديد في كائن من فئة SequentialHook.

attach_execution_device_hook

accelerate.hooks.attach_execution_device_hook

< >

( module: Moduleexecution_device: int | str | torch.deviceskip_keys: str | list[str] | None = Nonepreload_module_classes: list[str] | None = Nonetied_params_map: dict[int, dict[torch.device, torch.Tensor]] | None = None )

المعاملات

  • module (torch.nn.Module) — الوحدة التي نرغب في إرفاق الخطافات بها.
  • execution_device (int أو str أو torch.device) — الجهاز الذي يجب وضع المدخلات وأوزان النموذج عليه قبل المرور الأمامي.
  • skip_keys (str أو List[str]، اختياري) — قائمة بالمفاتيح التي يجب تجاهلها عند نقل المدخلات أو المخرجات بين الأجهزة.
  • preload_module_classes (List[str]، اختياري) — قائمة بالفئات التي يجب أن تُحمّل جميع أوزانها (حتى في الوحدات الفرعية) في بداية التقدّم الأمامي. يجب استخدام هذا فقط للفئات التي تحتوي على وحدات فرعية مسجّلة لكنها غير مستدعاة مباشرةً أثناء التقدّم الأمامي، على سبيل المثال إذا كان هناك طبقة خطية dense مسجّلة، لكن في التقدّم الأمامي، تُستخدم dense.weight وdense.bias في بعض العمليات بدلاً من استدعاء dense مباشرةً.
  • tied_params_map (Optional[Dict[int, Dict[torch.device, torch.Tensor]]], اختياري، القيمة الافتراضية None) — خريطة من مؤشرات البيانات إلى قواميس من الأجهزة إلى الأوزان المرتبطة المُرسَلة مسبقًا. بالنسبة لجهاز التنفيذ المعطى، يكون هذا المعامل مفيدًا لإعادة استخدام أول مؤشر متاح لوزن مشترك لجميع البقية، بدلاً من تكرار الذاكرة.

يربط AlignDevicesHook بشكل تكراري بجميع الوحدات الفرعية لنموذج معين للتأكد من أنها تمتلك جهاز التنفيذ الصحيح

attach_align_device_hook

accelerate.hooks.attach_align_device_hook

< >

( module: Moduleexecution_device: torch.device | None = Noneoffload: bool = Falseweights_map: collections.abc.Mapping | None = Noneoffload_buffers: bool = Falsemodule_name: str = ''skip_keys: str | list[str] | None = Nonepreload_module_classes: list[str] | None = Nonetied_params_map: dict[int, dict[torch.device, torch.Tensor]] | None = None )

المعاملات

  • module (torch.nn.Module) — الوحدة التي نرغب في إرفاق الخطافات بها.
  • execution_device (torch.device، اختياري) — الجهاز الذي يجب وضع المدخلات وأوزان النموذج عليه قبل المرور الأمامي.
  • offload (bool، اختياري، الافتراضي False) — ما إذا كان يجب نقل الأوزان بعد عملية الأمامية أم لا.
  • weights_map (Mapping[str, torch.Tensor]، اختياري) — عند تفريغ أوزان النموذج، خريطة (قد تكون كسولة) من أسماء المعاملات إلى قيم المصفوفات.
  • offload_buffers (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تضمين مخازن الوحدة المرتبطة عند الإزاحة.
  • module_name (str، اختياري، الافتراضي "") — اسم الوحدة.
  • skip_keys (str أو List[str]، اختياري) — قائمة بالمفاتيح التي يجب تجاهلها عند نقل المدخلات أو المخرجات بين الأجهزة.
  • preload_module_classes (List[str]، اختياري) — قائمة بالفئات التي يجب أن تُحمّل جميع أوزانها (حتى في الوحدات الفرعية) في بداية التقدّم الأمامي. يجب استخدام هذا فقط للفئات التي تحتوي على وحدات فرعية مسجّلة لكنها غير مستدعاة مباشرةً أثناء التقدّم الأمامي، على سبيل المثال إذا كان هناك طبقة خطية dense مسجّلة، لكن في التقدّم الأمامي، تُستخدم dense.weight وdense.bias في بعض العمليات بدلاً من استدعاء dense مباشرةً.
  • tied_params_map (Optional[Dict[int, Dict[torch.device, torch.Tensor]]], اختياري، القيمة الافتراضية None) — خريطة من مؤشرات البيانات إلى قواميس من الأجهزة إلى الأوزان المرتبطة المُرسَلة مسبقًا. بالنسبة لجهاز التنفيذ المعطى، يكون هذا المعامل مفيدًا لإعادة استخدام أول مؤشر متاح لوزن مشترك لجميع البقية، بدلاً من تكرار الذاكرة.

يربط AlignDevicesHook بشكل تكراري بجميع الوحدات الفرعية لنموذج معين التي تحتوي على معاملات و/أو مخازن مباشرة.

attach_align_device_hook_on_blocks

accelerate.hooks.attach_align_device_hook_on_blocks

< >

( module: Moduleexecution_device: torch.device | dict[str, torch.device] | None = Noneoffload: bool | dict[str, bool] = Falseweights_map: collections.abc.Mapping | None = Noneoffload_buffers: bool = Falsemodule_name: str = ''skip_keys: str | list[str] | None = Nonepreload_module_classes: list[str] | None = Nonetied_params_map: dict[int, dict[torch.device, torch.Tensor]] | None = None )

المعاملات

  • module (torch.nn.Module) — الوحدة التي نرغب في إرفاق الخطافات بها.
  • execution_device (torch.device أو Dict[str, torch.device]، اختياري) — الجهاز الذي يجب وضع المدخلات وأوزان النموذج عليه قبل المرور الأمامي. يمكن أن يكون جهازًا واحدًا للوحدة بأكملها، أو قاموسًا يربط اسم الوحدة بالجهاز.
  • offload (bool، اختياري، الافتراضي False) — ما إذا كان يجب نقل الأوزان بعد عملية التمرير الأمامي. يمكن أن يكون قيمة منطقية واحدة للوحدة بأكملها، أو قاموسًا يربط اسم الوحدة بقيمة منطقية.
  • weights_map (Mapping[str, torch.Tensor]، اختياري) — عند تفريغ أوزان النموذج، خريطة (قد تكون كسولة) من أسماء المعاملات إلى قيم المصفوفات.
  • offload_buffers (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم تضمين مخازن الوحدة المرتبطة عند الإزاحة.
  • module_name (str، اختياري، الافتراضي "") — اسم الوحدة.
  • skip_keys (str أو List[str]، اختياري) — قائمة بالمفاتيح التي يجب تجاهلها عند نقل المدخلات أو المخرجات بين الأجهزة.
  • preload_module_classes (List[str]، اختياري) — قائمة بالفئات التي يجب أن تُحمّل جميع أوزانها (حتى في الوحدات الفرعية) في بداية التقدّم الأمامي. يجب استخدام هذا فقط للفئات التي تحتوي على وحدات فرعية مسجّلة لكنها غير مستدعاة مباشرةً أثناء التقدّم الأمامي، على سبيل المثال إذا كان هناك طبقة خطية dense مسجّلة، لكن في التقدّم الأمامي، تُستخدم dense.weight وdense.bias في بعض العمليات بدلاً من استدعاء dense مباشرةً.
  • tied_params_map (Optional[Dict[int, Dict[torch.device, torch.Tensor]]], اختياري، القيمة الافتراضية None) — خريطة من مؤشرات البيانات إلى قواميس من الأجهزة إلى الأوزان المرتبطة المُرسَلة مسبقًا. بالنسبة لجهاز التنفيذ المعطى، يكون هذا المعامل مفيدًا لإعادة استخدام أول مؤشر متاح لوزن مشترك لجميع البقية، بدلاً من تكرار الذاكرة.

يربط AlignDevicesHook بجميع كتل النموذج المحدد عند الحاجة.

attach_layerwise_casting_hooks

accelerate.big_modeling.attach_layerwise_casting_hooks

< >

( module: Modulestorage_dtype: dtypecompute_dtype: dtypeskip_modules_pattern: str | tuple[str, ...] | None = Noneskip_modules_classes: tuple[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, ...])، القيمة الافتراضية None) — قائمة أنماط لمطابقة أسماء الوحدات التي يجب تجاوزها أثناء عملية الصب على مستوى الطبقات. إذا تم ضبطها على None مع ضبط skip_modules_classes على None، تُطبَّق عملية الصب على مستوى الطبقات مباشرةً على الوحدة بدلا من وحداتها الفرعية الداخلية.
  • skip_modules_classes (tuple[type[torch.nn.Module], ...]، القيمة الافتراضية None) — قائمة لفئات الوحدات التي يجب تجاوزها أثناء عملية الصب على مستوى الطبقات.
  • non_blocking (bool، القيمة الافتراضية False) — إذا كانت True، فإن عمليات تحويل الأوزان غير حاصِرة.

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

مثال:

>>> from accelerate.hooks import attach_layerwise_casting_hooks
>>> from transformers import AutoModelForCausalLM
>>> import torch

>>> # Model
>>> checkpoint = "EleutherAI/gpt-j-6B"
>>> model = AutoModelForCausalLM.from_pretrained(checkpoint)

>>> # Attach hooks and perform inference
>>> attach_layerwise_casting_hooks(model, storage_dtype=torch.float8_e4m3fn, compute_dtype=torch.bfloat16)
>>> with torch.no_grad():
...     model(...)

يمكن للمستخدمين أيضًا تمرير الوحدات التي يرغبون في تجنب تحويلها إلى نوع بيانات أدنى.

>>> attach_layerwise_casting_hooks(
...     model, storage_dtype=torch.float8_e4m3fn, compute_dtype=torch.bfloat16, skip_modules_pattern=["norm"]
... )

إزالة الخطافات

remove_hook_from_module

accelerate.hooks.remove_hook_from_module

< >

( module: Modulerecurse = False ) → torch.nn.Module

المعاملات

  • module (torch.nn.Module) — الوحدة التي سيتم إرفاق الخطاف بها.
  • recurse (bool، اختياري) — ما إذا كان يجب إزالة الخطافات بشكل تكراري

يعيد

torch.nn.Module

نفس الوحدة، مع فصل الخطاف (تُعدَّل الوحدة في مكانها، لذا يمكن تجاهل النتيجة).

يزيل أي خطاف موصول بوحدة عبر add_hook_to_module.

remove_hook_from_submodules

accelerate.hooks.remove_hook_from_submodules

< >

( module: Module )

المعاملات

  • module (torch.nn.Module) — الوحدة التي سيتم إزالة جميع الخطافات منها.

يزيل بشكل متكرر جميع الخطافات (hooks) المرتبطة بالوحدات الفرعية لنموذج معين.

أدوات

has_offloaded_params

accelerate.utils.has_offloaded_params

< >

( module: Module ) → bool

المعاملات

  • module (torch.nn.Module) — الوحدة التي سيتم فحصها بحثًا عن خطاف الإزاحة (offload hook).

يعيد

bool

True إذا كان للوحدة خطاف إزاحة (offload hook) وتم تفعيل الإزاحة، وإلا False.

يتحقق مما إذا كانت وحدة تحتوي على معاملات مُحمّلة (offloaded) من خلال فحص ما إذا كانت الوحدة المحددة تحتوي على AlignDevicesHook مرفق مع تفعيل خاصية التحميل

align_module_device

accelerate.utils.align_module_device

< >

( module: Moduleexecution_device: torch.device | None = None )

المعاملات

  • module (torch.nn.Module) — وحدة تحتوي على معاملات للمواءمة.
  • execution_device (torch.device، اختياري) — إذا تم توفيره، يتجاوز جهاز تنفيذ الوحدة داخل السياق. وإلا، استخدم جهاز تنفيذ الخطاف أو مرّر

مدير سياق ينقل معاملات الوحدة إلى جهاز التنفيذ المحدد.

Update on GitHub

←التسجيل معالجات معاملات Kwargs→