# 连续批处理

本页介绍了连续批处理推理背后的类：提交提示词、配置调度和内存限制，以及获取结果。

有关使用示例，请参阅 [连续批处理](../continuous_batching) 指南；有关调度与内存的交互方式，请参阅 [连续批处理架构](../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 : 输入 token 序列（提示词）列表

generation_config : 可选的生成配置

continuous_batching_config : 可选的连续批处理配置

record_timestamps : 如果设置为 true，请求将为每个生成的 token 添加时间戳

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/v5.23.0/src/transformers/generation/continuous_batching/continuous_api.py#L658)

用于处理生成请求连续批处理的 Manager。它提供了用于提交生成请求、获取结果以及管理后台生成线程的用户界面。不应直接创建此类，而应通过以下入口点之一（`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 : 用作提示的输入 token ID

request_id : 可选的自定义请求 ID（如果为 None，则自动生成）

max_new_tokens : 要生成的新 token 的最大数量

streaming : 是否以流式方式返回生成的 token

record_timestamps : 是否记录每个生成 token 的时间戳

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

终止管理器并释放分布式资源。可以安全地多次调用。调用此方法后，管理器将无法重新启动。

#### 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。

#### 加入[[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)

一个上下文管理器，用于暂停生成循环，以便调用线程可以使用该模型，通常是为了就地更新它。只有当循环暂停后，线程才会进入此上下文；退出时循环恢复，并保留其缓存和正在处理中的请求：不会清空任何内容，也不会丢失任何请求。多个线程可以同时持有暂停状态，当最后一个线程退出时，循环恢复。如果启用了 TP，所有 rank 都必须进入此上下文，否则其他 rank 将永远挂起。

#### 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` 在事件循环中被调用。对于流式请求，这会在每个 token 上发生；对于非流式请求，仅在完成时发生。当请求结束时，处理程序会被自动清理。

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

迭代与特定请求 ID 匹配的结果（阻塞）。

使用带有重新入队机制的共享输出队列。对于高并发服务场景，请改用 `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。

#### 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 图。如果尚未初始化，则初始化批次处理器。

## 连续批处理配置[[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)：每个（全注意力）页内为每一层存储的 token 数量。存储 N 层缓存的块包含 N 个页（每层一个），每个页为单层存储 `page_size` 个 token 的缓存。默认值为 256。

num_blocks (`int`, *可选*) : KV 缓存中的块数。当为 `None` 时，会根据 GPU 内存自动推断。

max_batch_tokens (`int`, *可选*) : 批次中的最大 token 数。当为 `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`)：是否允许为前缀缓存进行块共享。由于某些模型不支持块共享，因此只能允许而不能强制启用。如果您拥有少量短提示词但生成长度较长，请禁用此功能。

use_async_batching (`bool`, *可选*) : 是否启用异步双缓冲。该功能可消除连续批处理循环中的 CPU 开销，但代价是 VRAM 使用量翻倍。当值为 `None` 时，将自动检测。

use_cuda_graph (`bool` 或 `tuple[bool, bool]`，*可选*)：是否启用 CUDA graphs。该值可以是布尔元组（分别对应 varlen 路径和 decode 快速路径）、应用于两条路径的单个布尔值，或 None（自动推断）。调用 `decide_use_cuda_graphs` 后，该属性将变为布尔元组。默认值为 None（自动推断）。

q_padding_interval_size (`int`，*可选*，默认值为 0)：CUDA 图查询的填充粒度（以 token 为单位）。当设置为 0 时，使用 `continuous_api.py` 中的预设值。

kv_padding_interval_size (`int`，*可选*，默认为 0)：用于 CUDA 图的 KV 填充粒度（以 token 为单位）。当设置为 0 时，使用 `continuous_api.py` 中的预设值。

varlen_compile_config (`CompileConfig`，*可选*)：用于变长（prefill）路径的 CompileConfig。默认值为 None（使用 generation_config 作为回退）。变长路径处理查询和 KV 长度不同的批次，通常受益于 dynamic=True。

decode_compile_config (`CompileConfig`，*可选*)：用于解码（快速）路径的 CompileConfig。默认值为 None（使用 generation_config 作为回退方案）。由于解码路径处理的批次没有动态的 KV 长度，因此静态形状更为合适。

default_compile_level (`int`，*可选*，默认为 0)：如果该值 >0 且未为 varlen 或 decode 路径提供编译配置，则会自动提供一个默认的编译配置。级别最高可达 3，级别越高，性能越好，但预热时间也越长。

scheduler_type (`str`，*可选*，默认为 `"fifo"`)：要使用的调度器类型。

safety_margin (`float`, *可选*) : 用于限制卸载量的安全边际。默认为 None（使用类默认值）。

return_logprobs (`bool`，*可选*，默认为 `False`)：是否返回生成 token 的对数概率。

seed (`int | None`, *可选*) : 用于生成的可选随机种子。如果未指定，内部种子将被设置为一个随机值。

auto_switch_to_flash (`bool`，*可选*，默认为 `True`)：当实现为 SDPA 或 eager 时，是否自动切换到 flash attention（如果可用）。默认值为 True，因为 flash 在连续批处理（continuous batching）中表现更好。

cpu_offload_space (`float`，*可选*，默认值为 0.0)：用于 KV 缓存卸载的 CPU 交换空间（以 GiB 为单位）。初始化时会创建一个该大小的预分配固定 CPU 缓冲区。当 GPU 缓存已满时，被驱逐请求的 KV 缓存会被复制到此缓冲区，而不是被丢弃。0 表示禁用卸载（默认值）。

cpu_offload_space_safety_threshold (`float`，*可选*，默认值为 0.8)：如果 `cpu_offload_space` 超过系统总内存的该比例，则会被限制以避免主机内存溢出（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` 上下文管理器使用连续批处理的情况。

