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

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

لمعرفة أمثلة على الاستخدام، راجع دليل [Continuous batching](../continuous_batching)، وللاطلاع على كيفية تفاعل الجدولة مع الذاكرة، راجع مستند [Continuous batching architecture](../continuous_batching_architecture).

## ContinuousMixin.generate_batch[[transformers.ContinuousMixin.generate_batch]]

#### transformers.ContinuousMixin.generate_batch[[transformers.ContinuousMixin.generate_batch]]

```python
transformers.ContinuousMixin.generate_batch(inputs: list, generation_config: transformers.generation.configuration_utils.GenerationConfig | None = None, continuous_batching_config: transformers.generation.configuration_utils.ContinuousBatchingConfig | None = None, record_timestamps: bool = False, progress_bar: bool = False, persistent_manager: bool = False, warmup: bool = True, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L1368)

**المعاملات:**

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]]

#### transformers.ContinuousBatchingManager[[transformers.ContinuousBatchingManager]]

```python
transformers.ContinuousBatchingManager(model: ProtoPretrainedModel, generation_config: GenerationConfig, continuous_batching_config: ContinuousBatchingConfig, workload_hints: transformers.generation.continuous_batching.utils.WorkloadHints | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L658)

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

#### add_request[[transformers.ContinuousBatchingManager.add_request]]

```python
add_request(input_ids: list, request_id: str | None = None, max_new_tokens: int | None = None, streaming: bool = False, record_timestamps: bool = False, eos_token_id: int | list[int] | None = None, **logit_processor_kwargs: Any)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L914)

**المعاملات:**

input_ids : معرّفات الرموز المدخلة لاستخدامها كموجّه

request_id : معرّف طلب مخصص اختياري (يتم توليده تلقائيًا إذا كان فارغًا)

max_new_tokens : الحد الأقصى لعدد الرموز الجديدة التي سيتم توليدها

streaming : ما إذا كان سيتم بث الرموز أثناء توليدها

record_timestamps : ما إذا كان سيتم تسجيل طوابع زمنية لكل رمز مُولَّد

eos_token_id : معرف رمز نهاية التسلسل

logit_processor_kwargs : حُجج الكلمات المفتاحية لمعالج القيم الاحتمالية (logits).

**يعيد:** `str | None`

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

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

#### add_requests[[transformers.ContinuousBatchingManager.add_requests]]

```python
add_requests(inputs: list, max_new_tokens: int | None = None, streaming: bool = False, record_timestamps: bool = False, **logit_processor_kwargs: Any)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L972)

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

#### cancel_request[[transformers.ContinuousBatchingManager.cancel_request]]

```python
cancel_request(request_id: str)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L1007)

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

#### إتلاف[[transformers.ContinuousBatchingManager.destroy]]

```python
destroy()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L887)

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

#### get_result[[transformers.ContinuousBatchingManager.get_result]]

```python
get_result(request_id: str | None = None, timeout: float | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L1016)

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

#### is_running[[transformers.ContinuousBatchingManager.is_running]]

```python
is_running()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L801)

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

#### انضم[[transformers.ContinuousBatchingManager.join]]

```python
join(stop_trigger_time: float, timeout: float | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L872)

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

#### إيقاف مؤقت[[transformers.ContinuousBatchingManager.pause]]

```python
pause()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L894)

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

#### register_result_handler[[transformers.ContinuousBatchingManager.register_result_handler]]

```python
register_result_handler(request_id: str, callback: Callable)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L1053)

**المعاملات:**

request_id (*str*) : معرّف الطلب الذي ستُستلم المخرجات الخاصة به.

callback (*callable*) : تُستدعى مع `GenerationOutput` لكل نتيجة.

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

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

#### request_id_iter[[transformers.ContinuousBatchingManager.request_id_iter]]

```python
request_id_iter(request_id: str)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L1040)

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

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

#### ابدأ[[transformers.ContinuousBatchingManager.start]]

```python
start()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L805)

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

#### stop[[transformers.ContinuousBatchingManager.stop]]

```python
stop(block: bool = True, timeout: float | None = None, keep_for_next_session: bool = False, hard_stop: bool = False)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L814)

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

#### switch_to_cb_friendly_attn[[transformers.ContinuousBatchingManager.switch_to_cb_friendly_attn]]

```python
switch_to_cb_friendly_attn(model: ProtoPretrainedModel, auto_switch_to_flash: bool = True)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L745)

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

#### الاحماء[[transformers.ContinuousBatchingManager.warmup]]

```python
warmup()
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L791)

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

## إعدادات الدفع المستمر[[transformers.ContinuousBatchingConfig]]

#### transformers.ContinuousBatchingConfig[[transformers.ContinuousBatchingConfig]]

```python
transformers.ContinuousBatchingConfig(page_size: int = 256, num_blocks: int | None = None, max_batch_tokens: int | None = None, max_memory_percent: float | None = None, max_requests_per_batch: int | None = None, max_blocks_per_request: int | None = None, allow_block_sharing: bool = True, use_async_batching: bool | None = None, use_cuda_graph: bool | tuple[bool, bool] | None = None, q_padding_interval_size: int = 0, kv_padding_interval_size: int = 0, varlen_compile_config: transformers.generation.configuration_utils.CompileConfig | None = None, decode_compile_config: transformers.generation.configuration_utils.CompileConfig | None = None, default_compile_level: int = 0, scheduler_type: str = 'fifo', safety_margin: float | None = None, return_logprobs: bool = False, seed: int | None = None, auto_switch_to_flash: bool = True, cpu_offload_space: float | None = 0.0, cpu_offload_space_safety_threshold: float = 0.8, max_queue_size: int = 0, per_request_processors: bool = False, drop_unsupported_processors: bool = True, disable_nccl_graph_mixing: bool = True, cpu_group_timeout: float | None = 300.0, use_default_compile_configs: bool | None = None, max_cached_graphs: int | None = None, block_size: int | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/configuration_utils.py#L1683)

**المعاملات:**

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`، *اختياري*) : ما إذا كان سيتم تفعيل التخزين المؤقت المزدوج غير المتزامن (async double-buffering)، والذي يزيل الحمل على وحدة المعالجة المركزية (CPU) من حلقة الدفع المستمر (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 ولم يتم تقديم إعداد تجميع لمسار varlen أو decode، فسيتم تقديم إعداد تجميع افتراضي. يمكن أن يصل المستوى إلى 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 CPU buffer) بهذا الحجم عند التهيئة. عندما تمتلئ ذاكرة 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`) : إزالة معالجات اللوغيتات غير المدعومة بدلاً من إظهار خطأ. الافتراضي هو 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`.