Hugging Face's logo

Transformers documentation

Lô liên tục

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

Lô liên tục

Trang này tài liệu hóa các lớp đằng sau suy luận liên tục theo lô: gửi các prompt, cấu hình lịch trình và giới hạn bộ nhớ, và lấy kết quả.

Để xem ví dụ về cách sử dụng, hãy tham khảo hướng dẫn Continuous batching và để tìm hiểu cách lập lịch và bộ nhớ tương tác với nhau, hãy xem tài liệu 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]

Tham số

  • inputs — Danh sách các chuỗi token đầu vào (prompt)
  • generation_config — Cấu hình sinh tùy chọn
  • continuous_batching_config — Cấu hình continuous batching tùy chọn
  • record_timestamps — Nếu được đặt thành true, các yêu cầu sẽ có dấu thời gian cho từng token được tạo ra
  • progress_bar — Nếu được đặt thành true, một thanh tiến trình sẽ được hiển thị
  • persistent_manager — có nên giữ lại manager sau khi quá trình sinh kết thúc hay không. Mặc định là False.
  • warmup — có nên bắt trước các đồ thị CUDA trước khi xử lý các yêu cầu hay không. Mặc định là True.

Trả về

dict[str, GenerationOutput]

một từ điển ánh xạ các id yêu cầu tới các đối tượng GenerationOutput

Tạo các chuỗi cho một lô prompt bằng cách sử dụng continuous batching.

ContinuousBatchingManager

lớp transformers.ContinuousBatchingManager

< >

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

Trình quản lý để xử lý xếp lô liên tục (continuous batching) các yêu cầu sinh. Nó cung cấp giao diện người dùng để gửi yêu cầu sinh, lấy kết quả và quản lý luồng sinh nền. Lớp này không nên được tạo trực tiếp, mà phải thông qua một trong các điểm vào sau đây (tất cả là các phương thức của 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

Tham số

  • input_ids — Các ID token đầu vào được sử dụng làm prompt
  • request_id — ID yêu cầu tùy chỉnh tùy chọn (tự động tạo nếu là None)
  • max_new_tokens — Số lượng token mới tối đa cần tạo
  • streaming — Có nên phát trực tiếp các token khi chúng được tạo ra hay không
  • record_timestamps — Có ghi lại dấu thời gian cho từng token được tạo hay không
  • eos_token_id — ID của token kết thúc chuỗi
  • logit_processor_kwargs — Các đối số dạng từ khóa cho bộ xử lý logits.

Trả về

str | None

ID của yêu cầu nếu tiến trình là trình điều khiển TP, ngược lại là None.

Thêm một yêu cầu sinh mới vào hàng đợi. Nếu tiến trình không phải là trình điều khiển TP, đây là một thao tác không làm gì.

add_requests

< >

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

Hàm tiện ích để xử lý hàng loạt add_request và trả về ID của chúng. Xem tài liệu của nó để biết thêm chi tiết.

cancel_request

< >

( request_id: str )

Hủy một yêu cầu theo ID của nó. Nếu hàm này được gọi từ một tiến trình không phải là tiến trình điều khiển TP, nó sẽ không thực hiện gì: chỉ các tiến trình điều khiển TP mới tương tác với trình quản lý.

destroy

< >

( )

Kết thúc trình quản lý và giải phóng các tài nguyên phân tán. An toàn để gọi nhiều lần. Sau khi gọi hàm này, trình quản lý không thể được khởi động lại.

get_result

< >

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

Lấy một kết quả từ hàng đợi đầu ra. Nếu một ID được cung cấp, trả về yêu cầu khớp đầu tiên. Nếu một timeout được cung cấp, trả về None sau khi hết timeout (tính bằng giây).

is_running

< >

( )

Trả về True nếu luồng tạo nền đã được khởi động và vẫn đang hoạt động.

join

< >

( stop_trigger_time: floattimeout: float | None = None )

Chờ cho đến khi luồng nền hoàn tất. Việc chờ có thể bị giới hạn bằng đối số timeout (tính bằng giây).

tạm dừng

< >

( )

Một context manager tạm dừng vòng lặp sinh, cho phép luồng gọi sử dụng mô hình, thường là để cập nhật nó tại chỗ. Luồng chỉ đi vào ngữ cảnh này khi vòng lặp đã được tạm dừng, và vòng lặp sẽ tiếp tục khi thoát ra, giữ nguyên bộ nhớ đệm và các yêu cầu đang xử lý: không có gì bị xả và không có yêu cầu nào bị mất. Nhiều luồng có thể giữ trạng thái tạm dừng cùng lúc, và vòng lặp sẽ tiếp tục khi luồng cuối cùng thoát ra. Nếu TP đang bật, tất cả các rank phải đi vào ngữ cảnh này, nếu không các rank khác sẽ treo vĩnh viễn.

register_result_handler

< >

( request_id: strcallback: Callable )

Tham số

  • request_id (str) — ID của yêu cầu để nhận kết quả đầu ra.
  • callback (callable) — Được gọi với một GenerationOutput cho mỗi kết quả.

Đăng ký một callback để giao kết quả (dòng chảy hoặc không dòng chảy).

Callback được gọi trên vòng lặp sự kiện thông qua call_soon_threadsafe mỗi khi một kết quả được tạo ra cho yêu cầu này. Đối với các yêu cầu streaming, điều này xảy ra ở mỗi token; đối với các yêu cầu không streaming, chỉ xảy ra khi hoàn tất. Handler được dọn dẹp tự động khi yêu cầu kết thúc.

request_id_iter

< >

( request_id: str )

Lặp qua các kết quả khớp với một id yêu cầu cụ thể (chặn).

Sử dụng hàng đợi đầu ra chung với tính năng xếp hàng lại. Để phục vụ với mức độ đồng thời cao, hãy sử dụng register_result_handler thay thế.

bắt đầu

< >

( )

Bắt đầu luồng tạo nền.

stop

< >

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

Dừng luồng tạo nền. Nếu cờ block được đặt thành True, phương thức này sẽ chờ cho đến khi luồng dừng lại trong tối đa timeout giây (None nghĩa là không có thời gian chờ). Nếu cờ keep_for_next_session được đặt thành True, trình quản lý sẽ được lưu đệm trên mô hình để sử dụng sau này. Nếu cờ hard_stop được đặt, luồng tạo nền sẽ bị dừng ngay lập tức và các yêu cầu đang chờ sẽ bị thất bại.

switch_to_cb_friendly_attn

< >

( model: ProtoPretrainedModelauto_switch_to_flash: bool = True )

Chuyển đổi implementation của attn sang một phiên bản tương thích với CB. Nếu auto_switch_to_flash là True, và implementation của attn là SDPA hoặc eager, thì cũng chuyển sang flash nếu được hỗ trợ và khả dụng.

giai đoạn khởi động

< >

( )

Chạy các lô dữ liệu giả lập để tạo trước các đồ thị CUDA cho các đường dẫn varlen và decode. Khởi tạo bộ xử lý lô nếu chưa được thực hiện.

Cấu hình xếp lô liên tục

lớp 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 )

Tham số

  • page_size (int, tùy chọn, mặc định là 256) — Số lượng token được lưu trữ cho mỗi lớp bên trong một trang (full-attention). Một khối lưu trữ cache của N lớp sẽ có N trang (một trang cho mỗi lớp), mỗi trang chứa cache cho page_size token của một lớp. Mặc định là 256.
  • num_blocks (int, tùy chọn) — Số lượng khối trong bộ nhớ đệm KV. Được suy luận tự động từ bộ nhớ GPU khi None.
  • max_batch_tokens (int, tùy chọn) — Số lượng token tối đa trong một batch. Được suy luận tự động từ bộ nhớ GPU khi None.
  • max_memory_percent (float, tùy chọn) — Tỷ lệ phần trăm tối đa của bộ nhớ GPU trống (sau khi mô hình được nạp) để sử dụng cho bộ đệm KV. Khi None, giá trị này được xác định lúc chạy là 0.9 nếu không có xử lý logit và là 0.8 nếu có, để chừa chỗ cho các tensor tạm thời có kích thước bằng bảng từ vựng.
  • max_requests_per_batch (int, tùy chọn) — Số lượng yêu cầu tối đa cho mỗi batch. Được suy luận tự động từ các gợi ý về khối lượng công việc khi None, với giá trị dự phòng là 1024.
  • max_blocks_per_request (int, tuỳ chọn) — Số khối tối đa cho mỗi yêu cầu, được sử dụng trong đường dẫn giải mã nhanh flash_attn_with_kvcache để xác định kích thước bảng khối. Đặt giá trị này thành 0 sẽ vô hiệu hóa đường dẫn giải mã nhanh. Mặc định là None (tự suy luận).
  • allow_block_sharing (bool, tùy chọn, mặc định là True) — Có cho phép chia sẻ khối (block sharing) cho bộ đệm tiền tố (prefix caching) hay không. Việc chia sẻ khối chỉ có thể được cho phép, không bao giờ được ép buộc, vì một số mô hình không hỗ trợ tính năng này. Hãy tắt nếu bạn có ít prompt ngắn nhưng độ dài sinh ra (generation length) dài.
  • use_async_batching (bool, tùy chọn) — Có bật double-buffering bất đồng bộ hay không, giúp loại bỏ chi phí CPU khỏi vòng lặp continuous batching với cái giá là tăng gấp đôi lượng VRAM sử dụng. Tự động phát hiện khi None.
  • use_cuda_graph (bool hoặc tuple[bool, bool], không bắt buộc) — Có bật CUDA graphs hay không. Giá trị này có thể là một tuple gồm các boolean (một cho đường dẫn varlen và một cho đường dẫn decode nhanh), một boolean áp dụng cho cả hai đường dẫn, hoặc None (tự động suy luận). Sau khi gọi decide_use_cuda_graphs, thuộc tính này sẽ là một tuple gồm các boolean. Mặc định là None (tự động suy luận).
  • q_padding_interval_size (int, tùy chọn, mặc định là 0) — Độ mịn của padding cho query tính bằng số token dành cho CUDA graphs. Sử dụng một cài đặt có sẵn từ continuous_api.py khi được đặt thành 0.
  • kv_padding_interval_size (int, tùy chọn, mặc định là 0) — Độ mịn đệm KV theo token cho CUDA graphs. Sử dụng một cài đặt có sẵn từ continuous_api.py khi được đặt thành 0.
  • varlen_compile_config (CompileConfig, tùy chọn) — CompileConfig cho đường dẫn varlen (prefill). Mặc định là None (sử dụng fallback của generation_config) Đường dẫn varlen xử lý các batch có độ dài query và KV khác nhau, thường được hưởng lợi từ dynamic=True.
  • decode_compile_config (CompileConfig, tùy chọn) — CompileConfig cho đường dẫn decode (nhanh). Mặc định là None (sử dụng fallback của generation_config) Đường dẫn decode xử lý các batch không có độ dài KV động, do đó các hình dạng tĩnh phù hợp hơn.
  • default_compile_level (int, tuỳ chọn, mặc định là 0) — Nếu giá trị này >0 và không có cấu hình compile nào được cung cấp cho đường dẫn varlen hoặc decode, một cấu hình compile mặc định sẽ được cung cấp. Mức có thể lên đến 3, và mức cao hơn đồng nghĩa với hiệu suất tốt hơn nhưng thời gian warmup lâu hơn.
  • scheduler_type (str, tùy chọn, mặc định là "fifo") — Loại scheduler cần sử dụng.
  • safety_margin (float, tùy chọn) — Biên an toàn được sử dụng để giới hạn lượng offloading. Mặc định là None (sử dụng mặc định của lớp).
  • return_logprobs (bool, tùy chọn, mặc định là False) — Có nên trả về log probabilities cùng với các token được tạo ra hay không.
  • seed (int | None, tùy chọn) — Một seed tùy chọn cho quá trình sinh. Nếu không được chỉ định, seed nội bộ sẽ được đặt thành một giá trị ngẫu nhiên.
  • auto_switch_to_flash (bool, tùy chọn, mặc định là True) — Có nên tự động chuyển sang flash attention (nếu khả dụng) khi implementation là SDPA hay eager hay không. Mặc định là True, vì flash hoạt động tốt hơn nhiều cho continuous batching.
  • cpu_offload_space (float, tuỳ chọn, mặc định là 0.0) — Dung lượng bộ nhớ đệm CPU (GiB) để offload KV cache. Một bộ đệm CPU pinned có kích thước này được phân bổ trước khi khởi tạo. Khi bộ đệm GPU đầy, KV cache của các yêu cầu bị loại sẽ được sao chép sang đây thay vì bị loại bỏ. Giá trị 0 tắt offload (mặc định).
  • cpu_offload_space_safety_threshold (float, tùy chọn, mặc định là 0.8) — Nếu cpu_offload_space vượt quá tỷ lệ này so với tổng RAM của hệ thống, giá trị sẽ bị giới hạn để tránh OOM trên host. Đặt thành 1.0 để tắt giới hạn an toàn. Bỏ qua khi psutil không khả dụng.
  • max_queue_size (int, tùy chọn, mặc định là 0) — Kích thước hàng đợi yêu cầu tối đa cho việc phục vụ. 0 có nghĩa là không giới hạn.
  • per_request_processors (bool, tùy chọn, mặc định là False) — Bật các tham số bộ xử lý logits cho từng yêu cầu. Mặc định là False.
  • drop_unsupported_processors (bool, tùy chọn, mặc định là True) — Loại bỏ các logits processor không được hỗ trợ thay vì gây lỗi. Mặc định là True.
  • disable_nccl_graph_mixing (bool, tùy chọn, mặc định là True) — Tắt lưới an toàn của NCCL cho các comms được ghi nhận song song theo graph. Không bao giờ xảy ra trong CB và mang lại tăng hiệu năng cho TP.
  • cpu_group_timeout (float, tùy chọn, mặc định là 300.0) — Thời gian (tính bằng giây) sau đó một liên lạc CPU sẽ hết hạn và tiến trình sẽ bị dừng. Để là None nếu không muốn có thời gian hết hạn. Mặc định là 300 giây.
  • use_default_compile_configs (bool | None, tùy chọn) — Đã bị ngừng hỗ trợ trong 5.11: vui lòng sử dụng default_compile_level thay thế.
  • max_cached_graphs (int, tùy chọn) — Đã bị ngừng hỗ trợ trong 5.13: số lượng tối đa của graph không còn là vấn đề nữa.
  • block_size (int | None, optional) — Deprecated in 5.17: now page_size is used instead.

Lớp chứa các đối số liên quan đến continuous batching, khi sử dụng continuous batching thông qua phương thức generate_batch hoặc context manager continuous_batching_context_manager.

Update on GitHub

←Cấu hình Trình tổng hợp dữ liệu→