# Batching berkelanjutan

Halaman ini mendokumentasikan kelas di balik inferensi continuous batching: pengiriman prompt, konfigurasi penjadwalan dan batas memori, serta pengambilan hasil.

Untuk contoh penggunaan, lihat panduan [Continuous batching](../continuous_batching) dan untuk interaksi antara penjadwalan dan memori, lihat dokumen [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[list[int]], 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)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L1368)

**Parameter:**

inputs : Daftar sekuens token input (prompt)

generation_config : Konfigurasi generasi opsional

continuous_batching_config : Konfigurasi continuous batching opsional

record_timestamps : Jika diatur ke true, permintaan akan memiliki timestamp untuk setiap token yang dihasilkan

progress_bar : Jika diatur ke true, bilah kemajuan akan ditampilkan

persistent_manager : apakah akan mempertahankan manager setelah generasi selesai. Default adalah False.

warmup : apakah akan menangkap grafik CUDA terlebih dahulu sebelum memproses permintaan. Nilai default adalah True.

**Mengembalikan:** `dict[str, GenerationOutput]`

kamus dari id permintaan ke objek GenerationOutput

Generate sequences untuk batch prompt menggunakan continuous batching.

## 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)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L658)

Manajer untuk menangani pengelompokan berkelanjutan (continuous batching) permintaan generasi. Kelas ini menyediakan antarmuka pengguna untuk mengirim permintaan generasi, mengambil hasil, dan mengelola thread generasi di latar belakang. Kelas ini tidak boleh dibuat secara langsung, melainkan melalui salah satu titik masuk berikut (semua metode dari mixin `ContinuousMixin`):
- `init_continuous_batching`
- `continuous_batching_context_manager`
- `generate_batch`

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

```python
add_request(input_ids: list[int], 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)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L914)

**Parameter:**

input_ids : ID token input yang akan digunakan sebagai prompt

request_id : ID permintaan kustom opsional (dibuat secara otomatis jika None)

max_new_tokens : Jumlah maksimum token baru yang akan dihasilkan

streaming : Apakah akan mengalirkan token saat token tersebut dihasilkan

record_timestamps : Apakah akan merekam stempel waktu untuk setiap token yang dihasilkan

eos_token_id : ID token akhir urutan

logit_processor_kwargs : Argumen kata kunci untuk pemroses logits.

**Mengembalikan:** `str | None`

ID permintaan jika proses adalah driver TP, None selain itu.

Tambahkan permintaan generasi baru ke antrean. Jika proses tersebut bukan driver TP, ini tidak melakukan apa-apa.

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

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L972)

Fungsi utilitas untuk mem-batch `add_request` dan mengembalikan ID-nya. Periksa dokumentasinya untuk detail lebih lanjut.

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

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L1007)

Batalkan permintaan berdasarkan ID-nya. Jika ini dipanggil dari proses yang bukan driver TP, ini tidak melakukan apa-apa: hanya proses driver TP yang berinteraksi dengan manager.

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

```python
destroy()
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L887)

Akhiri manager dan lepaskan sumber daya terdistribusi. Aman untuk dipanggil beberapa kali. Setelah memanggil ini, manager tidak dapat dimulai ulang.

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

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L1016)

Ambil satu hasil dari antrean keluaran. Jika ID diberikan, kembalikan permintaan yang cocok pertama kali. Jika timeout diberikan, kembalikan None setelah timeout (dalam detik).

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

```python
is_running()
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L801)

Mengembalikan True jika thread generasi latar belakang telah dimulai dan masih aktif.

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

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L872)

Tunggu hingga thread latar belakang selesai. Wait dapat dibatasi menggunakan argumen timeout (dalam detik).

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

```python
pause()
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L894)

Manajer konteks yang menjeda loop generasi, sehingga thread pemanggil dapat menggunakan model, biasanya untuk memperbaruinya secara in-place. Thread hanya masuk ke konteks ini setelah loop dijeda, dan loop dilanjutkan saat keluar, dengan mempertahankan cache dan permintaan yang sedang diproses: tidak ada yang dibuang dan tidak ada permintaan yang hilang. Beberapa thread dapat memegang jeda secara bersamaan, dan loop dilanjutkan setelah thread terakhir keluar. Jika TP diaktifkan, semua rank harus masuk ke konteks ini, jika tidak rank lain akan menggantung selamanya.

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

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L1053)

**Parameter:**

request_id (*str*) : ID permintaan untuk menerima output.

callback (*callable*) : Dipanggil dengan `GenerationOutput` untuk setiap hasil.

Daftarkan callback untuk pengiriman hasil (streaming atau non-streaming).

Callback dipanggil pada event loop melalui `call_soon_threadsafe` setiap kali hasil dihasilkan untuk permintaan ini. Untuk permintaan streaming, hal ini terjadi pada setiap token; untuk non-streaming, hanya saat selesai. Handler dibersihkan secara otomatis ketika permintaan selesai.

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

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L1040)

Iterasi hasil yang cocok dengan id permintaan tertentu (blocking).

Menggunakan antrean output bersama dengan requeue. Untuk penyajian dengan konkurensi tinggi, gunakan `register_result_handler` sebagai gantinya.

#### mulai[[transformers.ContinuousBatchingManager.start]]

```python
start()
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L805)

Mulai thread generasi latar belakang.

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

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L814)

Hentikan thread generasi latar belakang. Jika flag `block` disetel ke True, maka metode ini akan menunggu thread berhenti selama waktu maksimum `timeout` detik (None berarti tidak ada batas waktu). Jika flag `keep_for_next_session` disetel ke True, maka manager akan di-cache pada model untuk digunakan di kemudian hari. Jika flag `hard_stop` disetel, thread generasi latar belakang akan dihentikan segera dan permintaan yang tertunda akan gagal.

#### 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)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L745)

Ganti implementasi attn menjadi satu yang kompatibel dengan CB. Jika auto_switch_to_flash bernilai True, dan implementasi attn adalah SDPA atau eager, juga beralih ke flash jika didukung dan tersedia.

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

```python
warmup()
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L791)

Graf CUDA pra-capture untuk jalur varlen dan decode dengan menjalankan batch dummy. Menginisialisasi pemroses batch jika belum dilakukan.

## Konfigurasi pengelompokan berkelanjutan[[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)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/generation/configuration_utils.py#L1685)

**Parameter:**

page_size (`int`, *opsional*, default 256) : Jumlah token yang disimpan untuk setiap layer di dalam sebuah (full-attention) page. Sebuah block yang menyimpan cache dari N layer memiliki N page (satu per layer), masing-masing menyimpan cache untuk `page_size` token untuk satu layer. Default adalah 256.

num_blocks (`int`, *opsional*) : Jumlah blok dalam KV cache. Diinfer secara otomatis dari memori GPU ketika `None`.

max_batch_tokens (`int`, *opsional*) : Jumlah maksimum token dalam satu batch. Diinfer secara otomatis dari memori GPU ketika `None`.

max_memory_percent (`float`, *opsional*) : Persentase maksimum memori GPU yang tersedia (setelah model dimuat) yang akan digunakan untuk KV cache. Jika `None`, nilai ini akan ditentukan pada saat runtime menjadi 0,9 jika tidak ada pemrosesan logit, dan 0,8 jika ada, untuk menyisakan ruang bagi tensor sementara yang berukuran sesuai kosakata.

max_requests_per_batch (`int`, *opsional*) : Jumlah maksimum permintaan per batch. Diinfer secara otomatis dari petunjuk beban kerja ketika `None`, dengan nilai cadangan 1024.

max_blocks_per_request (`int`, *opsional*) : Jumlah blok maksimum per permintaan, digunakan pada jalur decode cepat `flash_attn_with_kvcache` untuk menentukan dimensi tabel blok. Mengatur nilai ini ke 0 akan menonaktifkan jalur decode cepat. Nilai default adalah None (ditentukan secara otomatis).

allow_block_sharing (`bool`, *opsional*, default `True`) : Apakah mengizinkan block sharing untuk prefix caching. Block sharing hanya dapat diizinkan, tidak pernah dipaksa, karena beberapa model tidak mendukungnya. Nonaktifkan jika Anda memiliki sedikit prompt pendek tetapi panjang generasi yang panjang.

use_async_batching (`bool`, *opsional*) : Apakah akan mengaktifkan double-buffering asinkron, yang menghilangkan overhead CPU dari loop continuous batching dengan biaya penggunaan VRAM yang dua kali lipat. Terdeteksi secara otomatis saat `None`.

use_cuda_graph (`bool` atau `tuple[bool, bool]`, *opsional*) : Apakah akan mengaktifkan CUDA graphs. Nilai ini dapat berupa tuple dari boolean (satu untuk jalur varlen dan satu untuk jalur decode fast path), boolean yang akan diterapkan ke kedua jalur, atau None (ditentukan secara otomatis). Setelah memanggil `decide_use_cuda_graphs`, atribut ini akan menjadi tuple dari boolean. Nilai default adalah None (ditentukan secara otomatis).

q_padding_interval_size (`int`, *opsional*, default 0) : Granularitas padding query dalam token untuk CUDA graphs. Menggunakan preset dari `continuous_api.py` ketika diset ke 0.

kv_padding_interval_size (`int`, *opsional*, default 0) : Granularitas padding KV dalam token untuk CUDA graphs. Menggunakan preset dari `continuous_api.py` ketika diset ke 0.

varlen_compile_config (`CompileConfig`, *opsional*) : CompileConfig untuk jalur varlen (prefill). Default adalah None (menggunakan fallback generation_config). Jalur varlen menangani batch dengan panjang query dan KV yang bervariasi, yang sering kali diuntungkan oleh dynamic=True.

decode_compile_config (`CompileConfig`, *opsional*) : CompileConfig untuk jalur decode (cepat). Default adalah None (menggunakan fallback generation_config). Jalur decode menangani batch yang tidak memiliki panjang KV dinamis, sehingga bentuk statis lebih cocok.

default_compile_level (`int`, *opsional*, default 0) : Jika nilai ini >0 dan tidak ada konfigurasi compile yang diberikan untuk jalur varlen atau decode, konfigurasi compile default akan disediakan. Level dapat mencapai 3, dan level yang lebih tinggi berarti performa lebih baik tetapi waktu warmup lebih lama.

scheduler_type (`str`, *opsional*, default `"fifo"`) : Jenis scheduler yang akan digunakan.

safety_margin (`float`, *opsional*) : Margin keamanan yang digunakan untuk membatasi jumlah offloading. Defaultnya None (gunakan default kelas).

return_logprobs (`bool`, *opsional*, default `False`) : Apakah akan mengembalikan log probabilitas bersama dengan token yang dihasilkan.

seed (`int | None`, *opsional*) : Seed opsional untuk generasi. Jika tidak ditentukan, seed internal akan diatur ke nilai acak.

auto_switch_to_flash (`bool`, *opsional*, default `True`) : Apakah akan secara otomatis beralih ke flash attention (jika tersedia) ketika implementasinya adalah SDPA atau eager. Defaultnya True, karena flash jauh lebih baik untuk continuous batching.

cpu_offload_space (`float`, *opsional*, default 0.0) : Ruang swap CPU dalam GiB untuk offloading KV cache. Buffer CPU pinned yang dialokasikan sebelumnya dengan ukuran ini dibuat saat inisialisasi. Ketika cache GPU penuh, KV cache dari permintaan yang dievict akan disalin ke sini alih-alih dibuang. 0 menonaktifkan offloading (default).

cpu_offload_space_safety_threshold (`float`, *opsional*, default 0.8) : Jika `cpu_offload_space` melebihi fraksi ini dari total RAM sistem, nilai tersebut akan dibatasi (clamped) untuk menghindari OOM pada host. Atur ke 1.0 untuk menonaktifkan batas keamanan ini. Diabaikan jika psutil tidak tersedia.

max_queue_size (`int`, *opsional*, default 0) : Ukuran maksimum antrean permintaan untuk penyajian. 0 berarti tanpa batas.

per_request_processors (`bool`, *opsional*, default `False`) : Aktifkan parameter logits processor per permintaan. Default adalah False.

drop_unsupported_processors (`bool`, *opsional*, default `True`) : Hapus logits processor yang tidak didukung alih-alih memicu error. Default adalah True.

disable_nccl_graph_mixing (`bool`, *opsional*, default `True`) : Nonaktifkan jaring pengaman NCCL untuk komunikasi paralel yang ditangkap dalam grafik. Hal ini tidak pernah terjadi di CB dan memberikan peningkatan performa untuk TP.

cpu_group_timeout (`float`, *opsional*, default 300.0) : Waktu (dalam detik) setelahnya komunikasi CPU akan timeout dan proses akan crash. Biarkan sebagai None jika tidak ingin ada timeout. Default adalah 300 detik.

use_default_compile_configs (`bool | None`, *opsional*) : Tidak didukung lagi sejak 5.11: gunakan default_compile_level sebagai gantinya.

max_cached_graphs (`int`, *opsional*) : Tidak digunakan lagi sejak 5.13: jumlah maksimum graf bukan lagi menjadi masalah.

block_size (`int | None`, *opsional*) : Tidak didukung lagi di 5.17: sekarang page_size digunakan sebagai gantinya.

Kelas yang menyimpan argumen terkait continuous batching, ketika menggunakan continuous batching melalui metode `generate_batch` atau context manager `continuous_batching_context_manager`.

