Hugging Face's logo

Transformers documentation

연속 배치

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: list[list[int]]generation_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 — 선택적 continuous batching 구성
  • record_timestamps — true로 설정하면, 생성된 각 토큰에 대해 요청에 타임스탬프가 포함됩니다
  • progress_bar — true로 설정하면 진행률 표시줄이 표시됩니다
  • persistent_manager — 생성이 완료된 후 매니저를 유지할지 여부. 기본값은 False입니다.
  • warmup — 요청을 처리하기 전에 CUDA 그래프를 사전 캡처할지 여부입니다. 기본값은 True입니다.

반환값

dict[str, GenerationOutput]

요청 ID를 GenerationOutput 객체로 매핑한 사전

연속 배치(continuous batching)를 사용하여 프롬프트 배치에 대해 시퀀스를 생성합니다.

ContinuousBatchingManager

class 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: list[int]request_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 — 프롬프트로 사용할 입력 토큰 ID
  • request_id — 선택 사항. 사용자 지정 요청 ID (None인 경우 자동 생성)
  • max_new_tokens — 생성할 새 토큰의 최대 개수
  • streaming — 생성되는 토큰을 스트리밍할지 여부
  • record_timestamps — 생성된 각 토큰에 대한 타임스탬프를 기록할지 여부
  • eos_token_id — 시퀀스 종료 토큰 ID
  • logit_processor_kwargs — logits 프로세서에 사용할 키워드 인자.

반환값

str | None

프로세스가 TP 드라이버인 경우 요청 ID, 그렇지 않으면 None.

새로운 생성 요청을 큐에 추가합니다. 프로세스가 TP 드라이버가 아닌 경우, 이 작업은 아무것도 하지 않습니다(no-op).

add_requests

< >

( inputs: list[list[int]]max_new_tokens: int | None = Nonestreaming: bool = Falserecord_timestamps: bool = False**logit_processor_kwargs: Any )

add_request를 배치로 처리하고 해당 ID를 반환하는 유틸리티 함수입니다. 자세한 내용은 해당 문서에서 확인하세요.

cancel_request

< >

( request_id: str )

ID를 사용하여 요청을 취소합니다. 이 함수가 TP 드라이버가 아닌 프로세스에서 호출되면 아무 동작도 하지 않습니다(no-op). 관리자(manager)와 상호작용하는 것은 TP 드라이버 프로세스뿐입니다.

destroy

< >

( )

매니저를 종료하고 분산 리소스를 해제합니다. 여러 번 호출해도 안전합니다. 이 메서드를 호출한 후 매니저를 다시 시작할 수 없습니다.

get_result

< >

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

출력 큐에서 결과를 하나 가져옵니다. ID가 제공되면 첫 번째 일치하는 요청을 반환합니다. 타임아웃이 제공되면 타임아웃(초 단위) 후 None을 반환합니다.

is_running

< >

( )

배경 생성 스레드가 시작되어 아직 실행 중인지 확인하여 True를 반환합니다.

join

< >

( stop_trigger_time: floattimeout: float | None = None )

백그라운드 스레드가 완료될 때까지 기다립니다. timeout 인자(초 단위)를 사용하여 대기 시간을 제한할 수 있습니다.

일시정지

< >

( )

생성 루프를 일시 중지하여 호출 스레드가 모델을 사용할 수 있도록 하는 컨텍스트 매니저입니다. 일반적으로 모델을 인플레이스(in-place)로 업데이트하는 데 사용됩니다. 루프가 일시 중지된 후에만 스레드가 이 컨텍스트에 진입하며, 컨텍스트를 벗어나면 루프가 재개됩니다. 이때 캐시와 진행 중인 요청은 유지되며, 아무것도 비워지지 않고 요청이 유실되지 않습니다. 여러 스레드가 동시에 일시 중지를 보유할 수 있으며, 마지막 스레드가 컨텍스트를 벗어날 때 루프가 재개됩니다. TP가 활성화된 경우, 모든 랭크가 이 컨텍스트에 진입해야 하며, 그렇지 않으면 다른 랭크가 영원히 멈춥니다.

register_result_handler

< >

( request_id: strcallback: Callable )

매개변수

  • request_id (str) — 출력을 받을 요청 ID입니다.
  • callback (callable) — 각 결과에 대해 GenerationOutput와 함께 호출됩니다.

결과 전달(스트리밍 또는 비스트리밍)을 위한 콜백을 등록합니다.

이 콜백은 이 요청에 대한 결과가 생성될 때마다 이벤트 루프를 통해 call_soon_threadsafe로 호출됩니다. 스트리밍 요청의 경우 모든 토큰마다, 비스트리밍 요청의 경우 완료 시에만 발생합니다. 요청이 완료되면 핸들러는 자동으로 정리됩니다.

request_id_iter

< >

( request_id: str )

request id가 일치하는 결과를 반복합니다(블로킹).

재큐잉(requeue)을 사용하는 공유 출력 큐를 사용합니다. 높은 동시성 서빙의 경우, 대신 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가 지원되고 사용 가능한 경우에도 flash로 전환합니다.

워밍업

< >

( )

dummy 배치 실행을 통해 varlen 및 decode 경로에 대한 CUDA 그래프를 사전 캡처합니다. 배치 프로세서가 아직 초기화되지 않은 경우 초기화합니다.

연속 배치 구성

class 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) — (full-attention) 페이지 내부에서 각 레이어에 저장되는 토큰 수입니다. N개 레이어의 캐시를 저장하는 블록에는 N개의 페이지(레이어당 하나)가 있으며, 각 페이지는 한 레이어에 대해 page_size개의 토큰 캐시를 보유합니다. 기본값은 256입니다.
  • num_blocks (int, 선택 사항) — KV 캐시의 블록 수. None인 경우 GPU 메모리에서 자동으로 추론됩니다.
  • max_batch_tokens (int, 선택 사항) — 배치 내 최대 토큰 수. None인 경우 GPU 메모리에서 자동 추론됩니다.
  • max_memory_percent (float, 선택 사항) — 모델이 로드된 후 KV 캐시에 사용할 수 있는 GPU 메모리의 최대 비율입니다. None인 경우, 어휘 크기만큼의 임시 텐서를 위한 여유 공간을 확보하기 위해 logit 처리가 없으면 런타임에 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) — prefix caching을 위한 block sharing을 허용할지 여부입니다. 일부 모델이 이를 지원하지 않으므로 block sharing은 허용만 가능하고 강제할 수는 없습니다. 짧은 프롬프트가 적고 생성 길이가 긴 경우 비활성화하세요.
  • use_async_batching (bool, 선택 사항) — VRAM 사용량이 두 배로 증가하는 대가로 continuous batching 루프에서 CPU 오버헤드를 제거하는 async double-buffering을 활성화할지 여부입니다. None인 경우 자동으로 감지됩니다.
  • use_cuda_graph (bool 또는 tuple[bool, bool], 선택 사항) — CUDA graphs를 활성화할지 여부입니다. 이는 varlen 경로와 decode fast path 각각에 대한 boolean 튜플, 두 경로 모두에 적용되는 boolean, 또는 None(자동 추론)일 수 있습니다. decide_use_cuda_graphs를 호출한 후 이 속성은 boolean 튜플이 됩니다. 기본값은 None(자동 추론)입니다.
  • q_padding_interval_size (int, 선택 사항, 기본값 0) — CUDA graphs를 위한 토큰 단위의 Query 패딩 세분화 수준입니다. 0으로 설정된 경우 continuous_api.py의 프리셋을 사용합니다.
  • kv_padding_interval_size (int, 선택 사항, 기본값 0) — CUDA graphs를 위한 토큰 단위의 KV 패딩 세분화 수준입니다. 0으로 설정된 경우 continuous_api.py의 프리셋을 사용합니다.
  • varlen_compile_config (CompileConfig, 선택 사항) — varlen(prefill) 경로에 사용할 CompileConfig입니다. 기본값은 None이며(generation_config 폴백 사용) varlen 경로는 쿼리와 KV 길이가 서로 다른 배치 처리에 사용되며, dynamic=True를 사용하는 것이 유리한 경우가 많습니다.
  • decode_compile_config (CompileConfig, 선택 사항) — decode(고속) 경로에 사용할 CompileConfig입니다. 기본값은 None이며(generation_config 폴백 사용) decode 경로는 배치 처리 시 동적 KV 길이가 없으므로 정적 shape이 더 적합합니다.
  • default_compile_level (int, 선택 사항, 기본값 0) — 이 값이 >0이고 varlen 또는 decode 경로에 compile config가 제공되지 않으면, 기본 compile config가 제공됩니다. 레벨은 최대 3까지 가능하며, 레벨이 높을수록 성능은 향상되지만 warmup 시간이 길어집니다.
  • scheduler_type (str, 선택 사항, 기본값 "fifo") — 사용할 스케줄러 유형입니다.
  • safety_margin (float, 선택 사항) — 오프로딩 양을 제한하는 데 사용되는 안전 마진. 기본값은 None(클래스 기본값 사용)입니다.
  • return_logprobs (bool, 선택 사항, 기본값 False) — 생성된 토큰과 함께 로그 확률을 반환할지 여부입니다.
  • seed (int | None, 선택 사항) — 생성을 위한 선택적 시드입니다. 지정하지 않으면 내부 시드가 무작위 값으로 설정됩니다.
  • auto_switch_to_flash (bool, 선택 사항, 기본값 True) — 구현 방식이 SDPA 또는 eager인 경우, flash attention이 사용 가능한지 여부에 따라 자동으로 전환할지 여부입니다. 기본값은 True이며, 이는 flash attention이 continuous batching에 훨씬 유리하기 때문입니다.
  • cpu_offload_space (float, 선택 사항, 기본값 0.0) — KV 캐시 오프로딩을 위한 GiB 단위의 CPU 스왑 공간입니다. 이 크기의 사전 할당된 고정(pinned) CPU 버퍼가 초기화 시점에 생성됩니다. GPU 캐시가 가득 차면, 제거된 요청의 KV 캐시가 폐기되는 대신 이 버퍼로 복사됩니다. 0은 오프로딩을 비활성화합니다(기본값).
  • cpu_offload_space_safety_threshold (float, 선택 사항, 기본값 0.8) — cpu_offload_space가 시스템 전체 RAM의 해당 비율을 초과하면, 호스트 OOM을 방지하기 위해 값이 제한됩니다. 안전 상한을 비활성화하려면 1.0으로 설정하세요. psutil이 사용 불가능한 경우 무시됩니다.
  • max_queue_size (int, 선택 사항, 기본값 0) — 서빙을 위한 최대 요청 큐 크기입니다. 0은 무제한을 의미합니다.
  • per_request_processors (bool, 선택 사항, 기본값 False) — 요청별 logits 프로세서 매개변수를 활성화합니다. 기본값은 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 컨텍스트 매니저를 통해 continuous batching을 사용할 때, continuous batching과 관련된 인수를 담는 클래스입니다.

Update on GitHub

←구성 데이터 콜레이터→