Hugging Face's logo

Transformers documentation

الدفعية المستمرة

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

and get access to the augmented documentation experience

to get started

الدفعية المستمرة

توثّق هذه الصفحة الفئات المسؤولة عن الاستدلال مع الدفع المستمر: إرسال الأوامر، وإعداد جدولة المهام وحدود الذاكرة، واسترجاع النتائج.

لمعرفة أمثلة على الاستخدام، راجع دليل Continuous batching، وللاطلاع على كيفية تفاعل الجدولة مع الذاكرة، راجع مستند Continuous batching architecture.

ContinuousMixin.generate_batch

transformers.ContinuousMixin.generate_batch

< >

( inputs: listgeneration_config: transformers.generation.configuration_utils.GenerationConfig | None = Nonecontinuous_batching_config: transformers.generation.configuration_utils.ContinuousBatchingConfig | None = Nonerecord_timestamps: bool = Falseprogress_bar: bool = Falsepersistent_manager: bool = Falsewarmup: bool = True**kwargs ) → dict[str, GenerationOutput]

المعاملات

  • inputs — قائمة تسلسلات الرموز المدخلة (الموجّهات)
  • generation_config — تكوين توليد اختياري
  • continuous_batching_config — تكوين اختيارية للتجميع المستمر
  • record_timestamps — إذا تم ضبطه على true، فستحتوي الطلبات على طابع زمني لكل رمز يتم توليده
  • progress_bar — إذا تم ضبطه على true، فسيتم عرض شريط تقدم
  • persistent_manager — ما إذا كان يجب الإبقاء على المُدير بعد انتهاء التوليد. القيمة الافتراضية هي False.
  • warmup — ما إذا كان يجب التقاط رسوميات CUDA مسبقًا قبل معالجة الطلبات. القيمة الافتراضية هي True.

يعيد

dict[str, GenerationOutput]

قاموس من معرّفات الطلبات إلى كائنات GenerationOutput

أنشئ تسلسلات لدفعة من الأوامر باستخدام الدفع المستمر.

ContinuousBatchingManager

فئة transformers.ContinuousBatchingManager

< >

( model: ProtoPretrainedModelgeneration_config: GenerationConfigcontinuous_batching_config: ContinuousBatchingConfigworkload_hints: transformers.generation.continuous_batching.utils.WorkloadHints | None = None )

مديرٌ للتعامل مع الدفع المستمر لطلبات التوليد. يوفر واجهة مستخدم لتقديم طلبات التوليد، واستخراج النتائج، وإدارة خيط التوليد في الخلفية. يجب ألا يتم إنشاء هذا الصنف مباشرةً، بل من خلال أحد نقاط الدخول التالية (جميعها طرق من مزيج ContinuousMixin):

  • init_continuous_batching
  • continuous_batching_context_manager
  • generate_batch

add_request

< >

( input_ids: listrequest_id: str | None = Nonemax_new_tokens: int | None = Nonestreaming: bool = Falserecord_timestamps: bool = Falseeos_token_id: int | list[int] | None = None**logit_processor_kwargs: Any ) → str | None

المعاملات

  • input_ids — معرّفات الرموز المدخلة التي تُستخدم كموجّه
  • request_id — معرّف طلب مخصص اختياري (يتم توليده تلقائيًا إذا كان فارغًا)
  • max_new_tokens — الحد الأقصى لعدد الرموز الجديدة التي سيتم توليدها
  • streaming — ما إذا كان سيتم بث الرموز أثناء توليدها
  • record_timestamps — ما إذا كان سيتم تسجيل الطوابع الزمنية لكل رمز مُولَّد
  • eos_token_id — معرفات رمز نهاية التسلسل
  • logit_processor_kwargs — معاملات الكلمات المفتاحية لمعالج القيم الاحتمالية (logits).

يعيد

str | None

معرّف الطلب إذا كان العملية سائق TP، وإلا فهي None.

أضف طلب توليد جديدًا إلى قائمة الانتظار. إذا لم يكن العملية سائق TP، فإن هذا إجراء لا شيء.

add_requests

< >

( inputs: listmax_new_tokens: int | None = Nonestreaming: bool = Falserecord_timestamps: bool = False**logit_processor_kwargs: Any )

دالة مساعدة لتجميع add_request وإرجاع معرّفاتها. راجع توثيقها لمزيد من التفاصيل.

cancel_request

< >

( request_id: str )

إلغاء طلب معرّفه ID. إذا تم استدعاء هذه العملية من عملية ليست سائق TP، فإنها لا تؤدي أي إجراء: فعمليات سائق TP فقط هي التي تتفاعل مع المدير.

destroy

< >

( )

أنهِ المدير وأطلق الموارد الموزعة. يُعدّ استدعاء هذه الدالة عدة مرات آمناً. بعد استدعائها، لا يمكن إعادة تشغيل المدير.

get_result

< >

( request_id: str | None = Nonetimeout: float | None = None )

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

is_running

< >

( )

يعيد True إذا كان خيط توليد الخلفية قد بدأ وما زال نشطًا.

join

< >

( stop_trigger_time: floattimeout: float | None = None )

انتظر حتى ينتهي الخيط في الخلفية. يمكن تحديد حد أقصى لـ Wait باستخدام معامل timeout (بالثواني).

إيقاف مؤقت

< >

( )

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

register_result_handler

< >

( request_id: strcallback: Callable )

المعاملات

  • request_id (str) — معرّف الطلب لاستلام المخرجات الخاصة به.
  • callback (callable) — تُستدعى مع GenerationOutput لكل نتيجة.

سجّل مستدعٍ (callback) لتسليم النتائج (بثّ متواصل أو غير متواصل).

يتم استدعاء مُعيد الاستدعاء (callback) عبر حلقة الأحداث (event loop) بواسطة call_soon_threadsafe في كل مرة يُنتج فيها نتيجة لهذا الطلب. ففي حالات الطلبات التدفّقية (streaming)، يحدث ذلك عند كل رمز (token)؛ أما في الطلبات غير التدفّقية، فيحدث فقط عند اكتمال الطلب. كما يتم تنظيف المُعالِج (handler) تلقائياً عند انتهاء الطلب.

request_id_iter

< >

( request_id: str )

التكرار على النتائج المطابقة لـ request id معيّن (حجب).

يستخدم طابور المخرجات المشترك مع إعادة الطابور. لخدمة عالية التوازي، استخدم register_result_handler بدلاً من ذلك.

بدء

< >

( )

ابدأ خيط توليد الخلفية.

إيقاف

< >

( block: bool = Truetimeout: float | None = Nonekeep_for_next_session: bool = Falsehard_stop: bool = False )

أوقف خيط التوليد في الخلفية. إذا تم تعيين علم block إلى True، فإن هذه الطريقة تنتظر توقف الخيط لمدة قصوى تبلغ timeout ثانية (حيث يعني None عدم وجود مهلة زمنية). إذا تم تعيين علم keep_for_next_session إلى True، يتم تخزين المدير مؤقتًا على النموذج للاستخدام في المستقبل. إذا تم تعيين علم hard_stop، فسيتم إيقاف خيط التوليد في الخلفية فورًا وستفشل الطلبات المعلقة.

switch_to_cb_friendly_attn

< >

( model: ProtoPretrainedModelauto_switch_to_flash: bool = True )

بدّل تنفيذ attn إلى تنفيذ متوافق مع CB. إذا كان auto_switch_to_flash بقيمة True، وكان تنفيذ attn هو SDPA أو eager، فبدّل أيضاً إلى flash إذا كان مدعوماً ومتوفراً.

الإحماء

< >

( )

التقاط مسارات CUDA graphs مسبقًا لمسارات varlen و decode من خلال تشغيل دفعات وهمية. يقوم بمعالج الدفعة (batch processor) إذا لم يتم ذلك بعد.

إعدادات الدفع المستمر

فئة transformers.ContinuousBatchingConfig

< >

( page_size: int = 256num_blocks: int | None = Nonemax_batch_tokens: int | None = Nonemax_memory_percent: float | None = Nonemax_requests_per_batch: int | None = Nonemax_blocks_per_request: int | None = Noneallow_block_sharing: bool = Trueuse_async_batching: bool | None = Noneuse_cuda_graph: bool | tuple[bool, bool] | None = Noneq_padding_interval_size: int = 0kv_padding_interval_size: int = 0varlen_compile_config: transformers.generation.configuration_utils.CompileConfig | None = Nonedecode_compile_config: transformers.generation.configuration_utils.CompileConfig | None = Nonedefault_compile_level: int = 0scheduler_type: str = 'fifo'safety_margin: float | None = Nonereturn_logprobs: bool = Falseseed: int | None = Noneauto_switch_to_flash: bool = Truecpu_offload_space: float | None = 0.0cpu_offload_space_safety_threshold: float = 0.8max_queue_size: int = 0per_request_processors: bool = Falsedrop_unsupported_processors: bool = Truedisable_nccl_graph_mixing: bool = Truecpu_group_timeout: float | None = 300.0use_default_compile_configs: bool | None = Nonemax_cached_graphs: int | None = Noneblock_size: int | None = None )

المعاملات

  • page_size (int، اختياري، القيمة الافتراضية 256) — عدد الرموز المخزنة لكل طبقة داخل صفحة (انتباه كامل). الكتلة التي تخزن ذاكرة التخزين المؤقت لطبقات N تحتوي على N صفحات (صفحة لكل طبقة)، حيث تحتفظ كل صفحة بذاكرة تخزين مؤقت لـ page_size رمزًا لطبقة واحدة. القيمة الافتراضية هي 256.
  • num_blocks (int, اختياري) — عدد الكتل في ذاكرة KV. يُستنتج تلقائيًا من ذاكرة GPU عندما تكون None.
  • max_batch_tokens (int, اختياري) — الحد الأقصى لعدد الرموز في الدفعة. يُستنتج تلقائيًا من ذاكرة وحدة معالجة الرسوميات عندما تكون None.
  • max_memory_percent (float, اختياري) — النسبة المئوية القصوى من ذاكرة وحدة معالجة الرسوميات (GPU) المتاحة (بعد تحميل النموذج) التي تُستخدم لذاكرة KV. عند تعيين None، يتم تحديد القيمة وقت التشغيل على 0.9 إذا لم يكن هناك معالجة لوجيت، وعلى 0.8 إذا كانت موجودة، وذلك لتوفير مساحة كافية للمصفوفات المؤقتة بحجم المفردات.
  • max_requests_per_batch (int, اختياري) — الحد الأقصى لعدد الطلبات في الدفعة. يُستنتج تلقائيًا من تلميحات الحمل عند تعيين None، مع قيمة احتياطية تساوي 1024.
  • max_blocks_per_request (int, اختياري) — الحد الأقصى لعدد الكتل لكل طلب، ويُستخدم في مسار فك الترميز السريع flash_attn_with_kvcache لتحديد أبعاد جدول الكتل. ضبط هذه القيمة على 0 يُعطّل مسار فك الترميز السريع. القيمة الافتراضية هي None (تُستنتج تلقائيًا).
  • allow_block_sharing (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم السماح بمشاركة الكتل للتخزين المؤقت للبدايات. لا يمكن السماح بمشاركة الكتل إلا بشكل اختياري، ولا يمكن إجبارها، لأن بعض النماذج لا تدعمها. عطّل هذا الخيار إذا كان لديك عدد قليل من الأوامر القصيرة مع أطوال توليد طويلة.
  • use_async_batching (bool، اختياري) — ما إذا كان سيتم تفعيل التخزين المؤقت المزدوج غير المتزامن، والذي يُزيل الحمل على وحدة المعالجة المركزية من حلقة الدفع المستمر (continuous batching) مقابل زيادة استخدام ذاكرة الفيديو (VRAM) إلى الضعف. يتم اكتشافه تلقائيًا عند تعيينه إلى None.
  • use_cuda_graph (bool أو tuple[bool, bool]، اختياري) — ما إذا كان سيتم تفعيل رسوم CUDA. يمكن أن يكون هذا عبارة عن tuple من القيم المنطقية (قيمة واحدة لمسار varlen وقيمة واحدة لمسار decode السريع)، أو قيمة منطقية واحدة تُطبَّق على المسارين معًا، أو None (تُستنتج تلقائيًا). بعد استدعاء decide_use_cuda_graphs، سيصبح هذا السمة عبارة عن tuple من القيم المنطقية. القيمة الافتراضية هي None (تُستنتج تلقائيًا).
  • q_padding_interval_size (int, اختياري، القيمة الافتراضية 0) — حجم حشوة الاستعلام بالرموز لرسوم CUDA. يستخدم إعدادًا مسبقًا من continuous_api.py عند تعيينه إلى 0.
  • kv_padding_interval_size (int، اختياري، القيمة الافتراضية 0) — حجم حشوة KV بالرموز لرسوم CUDA. يستخدم إعدادًا مسبقًا من continuous_api.py عند تعيينه إلى 0.
  • varlen_compile_config (CompileConfig، اختياري) — CompileConfig لمسار varlen (prefill). القيمة الافتراضية هي None (يتم استخدام generation_config كبديل) يتعامل مسار varlen مع دفعات ذات أطوال استعلام وKV متغيرة، وغالباً ما يستفيد من dynamic=True.
  • decode_compile_config (CompileConfig، اختياري) — CompileConfig لمسار فك الترميز (السرعة). القيمة الافتراضية هي None (يُستخدم generation_config كبديل) يعالج مسار فك الترميز دفعات لا تحتوي على طول KV ديناميكي، لذا فإن الأشكال الثابتة أكثر ملاءمة.
  • default_compile_level (int، اختياري، القيمة الافتراضية 0) — إذا كانت هذه القيمة >0 ولم يتم تقديم إعداد تجميع للمسار ذي الطول المتغير أو مسار فك الترميز، فسيتم تقديم إعداد تجميع افتراضي. يمكن أن تصل القيمة إلى 3، وكلما زادت القيمة زادت الأداء لكن زاد وقت التسخين الأولي.
  • scheduler_type (str، اختياري، القيمة الافتراضية "fifo") — نوع المجدول (Scheduler) المستخدم.
  • safety_margin (float, اختياري) — هامش الأمان المستخدم لتقييد كمية الإزاحة. القيمة الافتراضية هي None (استخدام الافتراضي الخاص بالفئة).
  • return_logprobs (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب إرجاع احتمالات السجل (log probabilities) إلى جانب الرموز المولّدة.
  • seed (int | None، اختياري) — بذرة اختيارية للتوليد. إذا لم يتم تحديدها، فسيتم تعيين البذرة الداخلية إلى قيمة عشوائية.
  • auto_switch_to_flash (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم التحويل تلقائيًا إلى flash attention (إذا كان متاحًا) عندما تكون طريقة التنفيذ SDPA أو eager. القيمة الافتراضية هي True، لأن flash أفضل بكثير للدفعية المستمرة (continuous batching).
  • cpu_offload_space (float، اختياري، القيمة الافتراضية 0.0) — مساحة تبديل المعالج المركزي (CPU) بالجيجابايت (GiB) لإخلاء ذاكرة KV. يتم إنشاء مخزن مؤقت مثبّت (pinned) على المعالج المركزي بحجم هذا المقدار أثناء التهيئة. عندما تمتلئ ذاكرة GPU، تُنسخ ذاكرات KV الخاصة بالطلبات المُستبعَدة إلى هذا المخزن بدلاً من حذفها. القيمة 0 تعطل الإخلاء (الافتراضي).
  • cpu_offload_space_safety_threshold (float، اختياري، القيمة الافتراضية 0.8) — إذا تجاوز cpu_offload_space هذه الكسرة من إجمالي ذاكرة الوصول العشوائي (RAM) في النظام، يتم ضبطه (Clamping) لتجنب نفاد ذاكرة المضيف (Host OOM). اضبطه على 1.0 لتعطيل حد الأمان. يتم تجاهله عندما لا يكون psutil متاحًا.
  • max_queue_size (int، اختياري، القيمة الافتراضية 0) — الحد الأقصى لحجم قائمة الطلبات للخدمة. القيمة 0 تعني عدم وجود حد.
  • per_request_processors (bool، اختياري، القيمة الافتراضية False) — تفعيل معاملات معالج اللوغيتس لكل طلب. القيمة الافتراضية هي False.
  • drop_unsupported_processors (bool، اختياري، القيمة الافتراضية True) — إزالة معالجات logits غير المدعومة بدلاً من إظهار خطأ. القيمة الافتراضية هي True.
  • disable_nccl_graph_mixing (bool، اختياري، القيمة الافتراضية True) — تعطيل شبكة الأمان الخاصة بـ NCCL للتوازي في الاتصالات الملتقطة عبر الرسوم البيانية. لا يحدث أبدًا في CB ويمنح TP دفعة في الأداء.
  • cpu_group_timeout (float، اختياري، القيمة الافتراضية 300.0) — المدة (بالثواني) التي بعدها تنتهي مهلة اتصال المعالج (CPU) وتنهار العملية. اتركها None لعدم وجود مهلة. القيمة الافتراضية هي 300 ثانية.
  • use_default_compile_configs (bool | None، اختياري) — تم إيقاف استخدامه في 5.11: يُرجى استخدام default_compile_level بدلاً من ذلك.
  • max_cached_graphs (int، اختياري) — تم إيقاف استخدامه في 5.13: لم يعد الحد الأقصى لعدد الرسوم البيانية مشكلة.
  • block_size (int | None، اختياري) — تم إيقاف استخدامه في 5.17: يتم استخدام page_size بدلاً منه الآن.

فئة تحتوي على الحُجج المتعلقة بالتجميع المستمر، عند استخدام التجميع المستمر عبر طريقة generate_batch أو مدير السياق continuous_batching_context_manager.

Update on GitHub

←الإعداد منسّق البيانات→