# 연속 배치

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

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

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

**매개변수:**

inputs : 입력 토큰 시퀀스(프롬프트) 목록

generation_config : 선택적 생성 구성

continuous_batching_config : 선택 사항인 연속 배치 처리 구성

record_timestamps : true로 설정하면, 생성된 각 토큰에 대해 타임스탬프가 포함됩니다

progress_bar : true로 설정하면 진행률 표시줄이 표시됩니다

persistent_manager : 생성이 완료된 후 매니저를 유지할지 여부. 기본값은 False입니다.

warmup : 요청을 처리하기 전에 CUDA 그래프를 사전에 캡처할지 여부. 기본값은 True입니다.

**반환값:** `dict[str, GenerationOutput]`

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

연속 배치(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)
```

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

생성 요청의 연속 배치 처리를 관리하는 매니저입니다. 생성 요청 제출, 결과 조회, 백그라운드 생성 스레드 관리를 위한 사용자 인터페이스를 제공합니다. 이 클래스는 직접 생성하지 말고, 다음 진입점(`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)
```

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

**매개변수:**

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

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

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

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

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

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

ID를 사용하여 요청을 취소합니다. 이 함수가 TP 드라이버가 아닌 프로세스에서 호출된 경우 아무 동작도 수행하지 않습니다. 관리자와의 상호작용은 TP 드라이버 프로세스에서만 이루어집니다.

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

```python
destroy()
```

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

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

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

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

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

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

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

```python
is_running()
```

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

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

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

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

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

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

#### 일시 정지[[transformers.ContinuousBatchingManager.pause]]

```python
pause()
```

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

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

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

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

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

**매개변수:**

request_id (*str*) : 출력을 받을 요청 ID입니다.

callback (*callable*) : 각 결과에 대해 `GenerationOutput`와 함께 호출됩니다.

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

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

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

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

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

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

재큐잉(requeue)을 사용하는 공유 출력 큐를 사용합니다. 높은 동시성 서빙의 경우, 대신 `register_result_handler`를 사용하세요.

#### 시작[[transformers.ContinuousBatchingManager.start]]

```python
start()
```

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

배경 생성 스레드를 시작합니다.

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

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

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

백그라운드 생성 스레드를 중지합니다. `block` 플래그가 True로 설정된 경우, 이 메서드는 스레드가 중지될 때까지 최대 `timeout`초 동안 대기합니다(None은 타임아웃 없음). `keep_for_next_session` 플래그가 True로 설정된 경우, 매니저는 향후 사용을 위해 모델에 캐시됩니다. `hard_stop` 플래그가 설정된 경우, 백그라운드 생성 스레드가 즉시 중지되고 대기 중인 요청은 실패 처리됩니다.

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

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

attn 구현을 CB와 호환되는 방식으로 전환합니다. auto_switch_to_flash이 True이고 attn 구현이 SDPA 또는 eager인 경우, flash가 지원되고 사용 가능한 경우에도 flash로 전환합니다.

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

```python
warmup()
```

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

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

## 연속 배치 구성[[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)
```

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

**매개변수:**

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로, logit 처리가 있으면 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을 지원하지 않으므로, 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 패딩 granulariry입니다. 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 경로는 query와 KV 길이가 서로 다른 배치 처리에 사용되며, 일반적으로 dynamic=True 설정에서 이점을 얻습니다.

decode_compile_config (`CompileConfig`, *선택 사항*) : 디코드(고속) 경로에 사용할 CompileConfig입니다. 기본값은 None이며, 이 경우 generation_config의 폴백을 사용합니다. 디코드 경로는 배치 처리 시 동적 KV 길이가 없으므로 정적 shape이 더 적합합니다.

default_compile_level (`int`, *optional*, 기본값 0) : 이 값이 >0이고 varlen 또는 decode 경로에 대한 compile config가 제공되지 않으면, 기본 compile config가 제공됩니다. 레벨은 최대 3까지 가능하며, 레벨이 높을수록 성능은 향상되지만 warmup 시간이 길어집니다.

scheduler_type (`str`, *선택 사항*, 기본값 `"fifo"`) : 사용할 Scheduler 유형입니다.

safety_margin (`float`, *선택 사항*) : 오프로딩 양을 제한하는 데 사용되는 안전 마진. 기본값은 None(클래스 기본값 사용)입니다.

return_logprobs (`bool`, *선택 사항*, 기본값 `False`) : 생성된 토큰과 함께 로그 확률을 반환할지 여부.

seed (`int | None`, *선택 사항*) : 생성을 위한 선택적 시드입니다. 지정하지 않으면 내부 시드가 무작위 값으로 설정됩니다.

auto_switch_to_flash (`bool`, *선택 사항*, 기본값 `True`) : 구현 방식이 SDPA 또는 eager인 경우, flash attention이 사용 가능한지 여부에 따라 자동으로 전환할지 여부입니다. continuous batching에 flash가 훨씬 유리하기 때문에 기본값은 True입니다.

cpu_offload_space (`float`, *선택 사항*, 기본값 0.0) : KV 캐시 오프로딩을 위한 CPU 스왑 공간(GiB). 초기화 시 이 크기의 미리 할당된 고정(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 processor 매개변수를 활성화합니다. 기본값은 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과 관련된 인수를 담는 클래스입니다.

