# 連続バッチ処理

このページでは、連続バッチ推論の背後にあるクラスについて説明します。プロンプトの送信、スケジューリングとメモリ制限の設定、結果の取得です。

使用例については、[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, 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/main/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オブジェクトへの辞書

連続バッチ処理を使用して、プロンプトのバッチに対してシーケンスを生成します。

## 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/main/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, 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/main/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 ドライバーでない場合、この操作は何もしません。

#### add_requests[[transformers.ContinuousBatchingManager.add_requests]]

```python
add_requests(inputs: list, max_new_tokens: int | None = None, streaming: bool = False, record_timestamps: bool = False, **logit_processor_kwargs: Any)
```

[ソース](https://github.com/huggingface/transformers/blob/main/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/main/src/transformers/generation/continuous_batching/continuous_api.py#L1007)

IDを指定してリクエストをキャンセルします。このメソッドがTPドライバー以外のプロセスから呼び出された場合、何もしません。マネージャーとのやり取りはTPドライバーのプロセスのみが行います。

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

```python
destroy()
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L887)

マネージャーを終了し、分散リソースを解放します。複数回呼び出しても安全です。このメソッドを呼び出した後、マネージャーを再起動することはできません。

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

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

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L1016)

出力キューから1つの結果を取得します。IDが指定されている場合、最初に一致するリクエストを返します。タイムアウトが指定されている場合、タイムアウト（秒）後にNoneを返します。

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

```python
is_running()
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L801)

バックグラウンド生成スレッドが開始され、かつまだ生存している場合は True を返します。

#### 結合[[transformers.ContinuousBatchingManager.join]]

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

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L872)

バックグラウンドスレッドの完了を待機します。waitは、timeout引数（秒）で上限を設定できます。

#### 一時停止[[transformers.ContinuousBatchingManager.pause]]

```python
pause()
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L894)

…は、生成ループを一時停止するコンテキストマネージャーです。これにより、呼び出し元スレッドがモデルを使用できるようになり、通常はモデルをインプレースで更新するために使用されます。スレッドはループが一時停止した後にのみこのコンテキストに入ります。コンテキストを抜けた時点でループは再開され、キャッシュと進行中のリクエストは保持されます。何も排空されず、リクエストが失われることもありません。複数のスレッドが同時に一時停止を保持でき、最後のスレッドが抜けた時点でループは再開されます。TPが有効な場合、すべてのランクがこのコンテキストに入らなければなりません。そうでない場合、他のランクが永久にハングします。

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

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

[ソース](https://github.com/huggingface/transformers/blob/main/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/main/src/transformers/generation/continuous_batching/continuous_api.py#L1040)

特定のrequest idに一致する結果を反復処理します（ブロッキング）。

再キューイングを伴う共有出力キューを使用します。高並行度でのサービングには、代わりに`register_result_handler`を使用してください。

#### 開始[[transformers.ContinuousBatchingManager.start]]

```python
start()
```

[ソース](https://github.com/huggingface/transformers/blob/main/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/main/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/main/src/transformers/generation/continuous_batching/continuous_api.py#L745)

attnの実装を、CB互換のものに切り替えます。auto_switch_to_flashがTrueの場合、かつattnの実装がSDPAまたはeagerの場合、サポートおよび利用可能な場合はflashに切り替えます。

#### ウォームアップ[[transformers.ContinuousBatchingManager.warmup]]

```python
warmup()
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L791)

ダミーバッチを実行して、varlenパスおよびデコードパス用のCUDAグラフを事前キャプチャします。バッチプロセッサがまだ初期化されていない場合は、初期化します。

## 連続バッチ処理の設定[[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/main/src/transformers/generation/configuration_utils.py#L1683)

**パラメータ:**

page_size (`int`、*optional*、デフォルトは 256) : (full-attention) ページ内で各層に保存されるトークンの数です。N 層のキャッシュを保存するブロックには N 個のページ（層ごとに 1 個）があり、各ページは 1 層分の `page_size` トークンのキャッシュを保持します。デフォルトは 256 です。

num_blocks (`int`, *optional*) : KV キャッシュのブロック数。`None` の場合、GPU メモリから自動推定されます。

max_batch_tokens (`int`, *任意*) : バッチ内の最大トークン数。`None`の場合、GPUメモリから自動推定されます。

max_memory_percent (`float`, *任意*) : モデルの読み込み後に使用可能な GPU メモリの最大割合（KV キャッシュ用に使用）。`None` の場合、実行時に、logit 処理がない場合は 0.9、ある場合は 0.8 に解決され、語彙サイズ分の一時テンソルに余裕を持たせます。

max_requests_per_batch (`int`, *optional*) : バッチあたりの最大リクエスト数。`None` の場合はワークロードのヒントから自動推論され、フォールバック値は 1024 です。

max_blocks_per_request (`int`, *optional*) : 1リクエストあたりの最大ブロック数。`flash_attn_with_kvcache` の高速デコードパスで、ブロックテーブルの次元を決定するために使用されます。これを 0 に設定すると、高速デコードパスが無効になります。デフォルトは None（自動推定）です。

allow_block_sharing (`bool`、*任意*、デフォルトは`True`) : プレフィックスキャッシュのためのブロック共有を許可するかどうか。一部のモデルがブロック共有をサポートしていないため、ブロック共有は許可することはできても、強制することはできません。短いプロンプトが少なく、生成長が長い場合は無効にしてください。

use_async_batching (`bool`, *省略可*) : 非同期ダブルバッファリングを有効にするかどうか。VRAM使用量が2倍になる代わりに、連続バッチ処理ループからCPUオーバーヘッドを排除します。`None`の場合、自動検出されます。

use_cuda_graph (`bool` または `tuple[bool, bool]`、*省略可*) : CUDA グラフを有効にするかどうかを指定します。これは、ブール値のタプル（varlen パス用と decode fast path 用をそれぞれ1つずつ）、両方のパスに適用されるブール値、または None（自動推論）のいずれかです。`decide_use_cuda_graphs` を呼び出した後、この属性はブール値のタプルになります。デフォルトは None（自動推論）です。

q_padding_interval_size (`int`、*任意*、デフォルト値は 0) : CUDA グラフ用のクエリパディングの粒度（トークン数）。0 に設定されている場合、`continuous_api.py` のプリセットを使用します。

kv_padding_interval_size (`int`、*任意*、デフォルト値は 0) : CUDA グラフ用の KV パディングの粒度（トークン数）。0 に設定されている場合、`continuous_api.py` のプリセットを使用します。

varlen_compile_config (`CompileConfig`、*任意*) : varlen (prefill) パス用の CompileConfig。デフォルトは None (generation_config のフォールバックを使用) varlen パスは、クエリと KV の長さが異なるバッチを処理し、dynamic=True を使用することで恩恵を受けやすい場合があります。

decode_compile_config (`CompileConfig`、*任意*) : デコード（高速）パス用の CompileConfig。デフォルトは None（generation_config のフォールバックを使用）です。デコードパスではバッチを処理し、KV の長さが動的でないため、静的な形状の方が適しています。

default_compile_level (`int`、*optional*、デフォルト値は 0) : この値が 0 より大きく、かつ varlen または decode パスに対して compile config が指定されていない場合、デフォルトの compile config が提供されます。レベルは最大 3 まで設定でき、レベルが高いほどパフォーマンスは向上しますが、ウォームアップ時間が長くなります。

scheduler_type (`str`、*任意*、デフォルトは `"fifo"`) : 使用するスケジューラーの種類。

safety_margin (`float`, *任意*) : オフロード量を制限するために使用される安全マージン。デフォルトは None（クラスのデフォルトを使用）。

return_logprobs (`bool`、*任意*、デフォルトは`False`) : 生成されたトークンとともに対数確率を返すかどうか。

seed (`int | None`, *任意*) : 生成用の任意のシードです。指定しない場合、内部のシードはランダムな値に設定されます。

auto_switch_to_flash (`bool`、*任意*、デフォルトは`True`) : 実装が SDPA または eager の場合、利用可能な場合にフラッシュアテンションへ自動的に切り替えるかどうか。デフォルトは True です。フラッシュアテンションは連続バッチ処理に大幅に優れているためです。

cpu_offload_space (`float`、*optional*、デフォルト値は 0.0) : KV キャッシュのオフローディングに使用する CPU スワップスペースのサイズ (GiB)。初期化時に、このサイズ分の事前割り当て済みピン留め 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`, *optional*) : 5.13 で非推奨: グラフの最大数はもはや問題ではありません。

block_size (`int | None`, *任意*) : 5.17 で非推奨: 代わりに page_size が使用されます。

`generate_batch` メソッドまたは `continuous_batching_context_manager` コンテキストマネージャーを通じて continuous batching を使用する場合、continuous batching に関する引数を持つクラス。