Hugging Face's logo

Transformers documentation

Batching berkelanjutan

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

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 dan untuk interaksi antara penjadwalan dan memori, lihat dokumen 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]

Parameter

  • inputs — Daftar urutan 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 manager akan dipertahankan setelah generasi selesai. Default adalah False.
  • warmup — apakah akan pre-capture CUDA graphs sebelum memproses permintaan. Default adalah True.

Mengembalikan

dict[str, GenerationOutput]

kamus dari id permintaan ke objek GenerationOutput

Generate sequences untuk batch prompt menggunakan continuous batching.

ContinuousBatchingManager

kelas transformers.ContinuousBatchingManager

< >

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

Manajer untuk menangani pengelompokan berkelanjutan (continuous batching) permintaan generasi. Kelas ini menyediakan antarmuka pengguna untuk mengirimkan permintaan generasi, mengambil hasil, dan mengelola thread generasi latar belakang. Kelas ini tidak boleh dibuat secara langsung, melainkan melalui salah satu titik masuk berikut (semua merupakan metode dari mixin 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

Parameter

  • input_ids — ID token input yang 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 — Whether to stream tokens as they’re generated
  • record_timestamps — Apakah akan merekam timestamp untuk setiap token yang dihasilkan
  • eos_token_id — ID token akhir-sekuens
  • logit_processor_kwargs — Argumen kata kunci untuk logits processor.

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

< >

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

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

cancel_request

< >

( request_id: str )

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 manajer.

destroy

< >

( )

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

get_result

< >

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

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

is_running

< >

( )

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

join

< >

( stop_trigger_time: floattimeout: float | None = None )

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

jeda

< >

( )

Manajer konteks yang menjeda loop generasi, sehingga thread pemanggil dapat menggunakan model, biasanya untuk memperbaruinya di tempat. 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 dikuras dan tidak ada permintaan yang hilang. Beberapa thread dapat menahan jeda secara bersamaan, dan loop dilanjutkan setelah yang terakhir keluar. Jika TP aktif, semua rank harus masuk ke konteks ini, jika tidak rank lain akan menggantung selamanya.

register_result_handler

< >

( request_id: strcallback: Callable )

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 pada saat selesai. Handler dibersihkan secara otomatis ketika permintaan selesai.

request_id_iter

< >

( request_id: str )

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

< >

( )

Mulai thread generasi latar belakang.

berhenti

< >

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

Hentikan thread generasi latar belakang. Jika flag block diset ke True, maka metode ini menunggu thread berhenti selama waktu maksimum timeout detik (None berarti tanpa batas waktu). Jika flag keep_for_next_session diset ke True, maka manager di-cache pada model untuk penggunaan di masa depan. Jika flag hard_stop diset, thread generasi latar belakang akan dihentikan segera dan permintaan yang tertunda akan gagal.

switch_to_cb_friendly_attn

< >

( model: ProtoPretrainedModelauto_switch_to_flash: bool = True )

Ganti implementasi attn menjadi 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

< >

( )

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

Konfigurasi pengelompokan berkelanjutan

kelas 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 )

Parameter

  • page_size (int, opsional, default 256) — Jumlah token yang disimpan untuk setiap layer di dalam sebuah halaman (full-attention). Blok yang menyimpan cache dari N layer memiliki N halaman (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. Disimpulkan 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, nilainya ditentukan pada saat runtime menjadi 0.9 jika tidak ada pemrosesan logit, dan 0.8 jika ada, untuk menyisakan ruang bagi tensor sementara berukuran 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) — Blok maksimum per permintaan, digunakan dalam 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. Dideteksi 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 cepat), 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 diatur 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 diatur 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, defaultnya "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. Default adalah True, karena flash jauh lebih baik untuk continuous batching.
  • cpu_offload_space (float, opsional, default 0.0) — Ruang tukar 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 dievakuasi 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 proporsi ini dari total RAM sistem, nilai tersebut akan dibatasi (clamped) untuk menghindari OOM pada host. Atur ke 1.0 untuk menonaktifkan batas keamanan. Diabaikan jika psutil tidak tersedia.
  • max_queue_size (int, opsional, default 0) — Ukuran antrean permintaan maksimum 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, defaultnya True) — Hapus logits processor yang tidak didukung alih-alih menghasilkan error. Defaultnya adalah True.
  • disable_nccl_graph_mixing (bool, opsional, default True) — Nonaktifkan jaring pengaman NCCL untuk komunikasi yang ditangkap secara paralel melalui graph. 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 untuk tidak ada timeout. Default adalah 300 detik.
  • use_default_compile_configs (bool | None, opsional) — Tidak didukung lagi di 5.11: gunakan default_compile_level sebagai gantinya.
  • max_cached_graphs (int, opsional) — Tidak digunakan lagi di 5.13: jumlah maksimum grafik bukan lagi masalah.
  • block_size (int | None, optional) — Deprecated in 5.17: now page_size is used instead.

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

Update on GitHub

←Konfigurasi Data collator→