Hugging Face's logo

Transformers documentation

연속 배치

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

연속 배치

이 페이지는 연속 배치 추론을 뒷받침하는 클래스들을 문서화합니다: 프롬프트 제출, 스케줄링 및 메모리 한도 설정, 결과 가져오기.

사용 예제는 Continuous batching 가이드를, 스케줄링과 메모리의 상호작용에 대해서는 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]

매개변수

  • 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: 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

매개변수

  • 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: listmax_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

←구성 데이터 콜레이터→