# Loteo continuo

Esta página documenta las clases detrás de la inferencia con lotes continuos: el envío de indicaciones, la configuración de la programación y los límites de memoria, y la recuperación de resultados.

Para ver ejemplos de uso, consulte la guía de [Continuous batching](../continuous_batching) y, para saber cómo interactúan la programación y la memoria, consulte el documento de [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)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L1368)

**Parámetros:**

inputs : Lista de secuencias de tokens de entrada (indicaciones)

generation_config : Configuración de generación opcional

continuous_batching_config : Configuración opcional de lotes continuos

record_timestamps : Si se establece en true, las solicitudes incluirán una marca de tiempo para cada token generado

progress_bar : Si se establece en true, se mostrará una barra de progreso

persistent_manager : si se debe persistir el gestor después de que finalice la generación. El valor predeterminado es False.

warmup : si se deben capturar los gráficos de CUDA de antemano antes de procesar las solicitudes. El valor predeterminado es True.

**Devuelve:** `dict[str, GenerationOutput]`

un diccionario de ids de solicitud a objetos GenerationOutput

Genera secuencias para un lote de prompts usando 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)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L658)

Gestor para el procesamiento por lotes continuo de solicitudes de generación. Proporciona una interfaz de usuario para enviar solicitudes de generación, obtener resultados y gestionar el hilo de generación en segundo plano. Esta clase no debe crearse directamente, sino a través de uno de los siguientes puntos de entrada (todos métodos del mixin `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)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L914)

**Parámetros:**

input_ids : IDs de tokens de entrada para usar como prompt

request_id : ID de solicitud personalizado opcional (se genera automáticamente si es None)

max_new_tokens : Número máximo de nuevos tokens a generar

streaming : Si se deben transmitir los tokens a medida que se generan

record_timestamps : Si se deben registrar marcas de tiempo para cada token generado

eos_token_id : ID(s) del token de fin de secuencia

logit_processor_kwargs : Argumentos de palabras clave para el procesador de logits.

**Devuelve:** `str | None`

El ID de solicitud si el proceso es un controlador de TP, None en caso contrario.

Agrega una nueva solicitud de generación a la cola. Si el proceso no es un controlador de TP, esta operación no tiene efecto.

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

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L972)

Función de utilidad para agrupar `add_request` y devolver sus IDs. Consulta su documentación para más detalles.

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

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

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L1007)

Cancela una solicitud por su ID. Si se llama desde un proceso que no es un conductor de TP, no tiene efecto: solo los procesos de conductor de TP interactúan con el administrador.

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

```python
destroy()
```

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

Termina el gestor y libera los recursos distribuidos. Es seguro llamarlo varias veces. Después de llamarlo, el gestor no se puede reiniciar.

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

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

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

Recupera un resultado de la cola de salida. Si se proporciona un ID, devuelve la primera solicitud coincidente. Si se proporciona un tiempo de espera, devuelve None después del tiempo de espera (en segundos).

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

```python
is_running()
```

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

Devuelve True si el hilo de generación en segundo plano se ha iniciado y sigue activo.

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

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

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

Esperar a que el hilo en segundo plano termine. La espera puede limitarse mediante el argumento timeout (en segundos).

#### pausa[[transformers.ContinuousBatchingManager.pause]]

```python
pause()
```

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

Un gestor de contexto que pausa el bucle de generación, de modo que el hilo que lo llama pueda utilizar el modelo, normalmente para actualizarlo in situ. El hilo solo entra en este contexto una vez que el bucle está pausado, y el bucle se reanuda al salir, conservando su caché y sus solicitudes en curso: nada se vacía y ninguna solicitud se pierde. Varios hilos pueden mantener la pausa al mismo tiempo, y el bucle se reanuda cuando el último de ellos sale. Si TP está activado, todos los ranks deben entrar en este contexto; de lo contrario, los demás ranks se bloquearán indefinidamente.

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

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

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L1053)

**Parámetros:**

request_id (*str*) : El ID de solicitud para recibir las salidas.

callback (*callable*) : Se llama con un `GenerationOutput` para cada resultado.

Registre un callback para la entrega de resultados (con streaming o sin streaming).

El callback se invoca en el bucle de eventos mediante `call_soon_threadsafe` cada vez que se produce un resultado para esta solicitud. En las solicitudes de streaming, esto ocurre en cada token; en las no de streaming, solo al completarse. El manejador se limpia automáticamente cuando la solicitud finaliza.

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

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

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L1040)

Iterar sobre los resultados que coinciden con un id de solicitud específico (bloqueante).

Utiliza la cola de salida compartida con reencolado. Para el servicio de alta concurrencia, use `register_result_handler` en su lugar.

#### comenzar[[transformers.ContinuousBatchingManager.start]]

```python
start()
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L805)

Inicie el hilo de generación en segundo plano.

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

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

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L814)

Detiene el hilo de generación en segundo plano. Si la bandera `block` se establece en True, este método espera a que el hilo se detenga durante un tiempo máximo de `timeout` segundos (None significa sin tiempo de espera). Si la bandera `keep_for_next_session` se establece en True, el gestor se almacena en caché en el modelo para su uso futuro. Si se establece la bandera `hard_stop`, el hilo de generación en segundo plano se detendrá de inmediato y las solicitudes pendientes fallarán.

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

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/continuous_batching/continuous_api.py#L745)

Cambia la implementación de attn por una compatible con CB. Si auto_switch_to_flash es True y la implementación de attn es SDPA o eager, también cambia a flash si está soportada y disponible.

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

```python
warmup()
```

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

Captura de antemano de grafos CUDA para las rutas varlen y decode ejecutando lotes ficticios. Inicializa el procesador de lotes si aún no se ha hecho.

## Configuración de lotes continuos[[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)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/generation/configuration_utils.py#L1685)

**Parámetros:**

page_size (`int`, *opcional*, valor predeterminado 256) : El número de tokens almacenados para cada capa dentro de una página (de atención completa). Un bloque que almacena la caché de N capas tiene N páginas (una por capa), cada una con la caché de `page_size` tokens para una capa. El valor predeterminado es 256.

num_blocks (`int`, *opcional*) : Número de bloques en la caché KV. Se infiere automáticamente de la memoria de GPU cuando es `None`.

max_batch_tokens (`int`, *opcional*) : Número máximo de tokens en un lote. Se infiere automáticamente de la memoria de la GPU cuando es `None`.

max_memory_percent (`float`, *opcional*) : Porcentaje máximo de la memoria GPU libre (después de cargar el modelo) que se utilizará para la caché KV. Cuando es `None`, se resuelve en tiempo de ejecución a 0.9 si no hay procesamiento de logits y a 0.8 si lo hay, para dejar margen para tensores temporales del tamaño del vocabulario.

max_requests_per_batch (`int`, *opcional*) : Número máximo de solicitudes por lote. Se infiere automáticamente de las pistas de carga de trabajo cuando es `None`, con un valor predeterminado de 1024.

max_blocks_per_request (`int`, *opcional*) : Número máximo de bloques por solicitud, utilizado en la ruta de decodificación rápida `flash_attn_with_kvcache` para dimensionar la tabla de bloques. Establecer este valor en 0 deshabilita la ruta de decodificación rápida. El valor predeterminado es None (inferencia automática).

allow_block_sharing (`bool`, *opcional*, valor predeterminado `True`) : Si se permite el uso compartido de bloques para la caché de prefijos. El uso compartido de bloques solo se puede permitir, nunca forzar, ya que algunos modelos no lo admiten. Desactívalo si tienes pocos prompts cortos pero longitudes de generación largas.

use_async_batching (`bool`, *opcional*) : Si se habilita el doble buffer asíncrono, que elimina la sobrecarga de CPU del bucle de lotes continuos a costa de duplicar el uso de VRAM. Se detecta automáticamente cuando es `None`.

use_cuda_graph (`bool` o `tuple[bool, bool]`, *opcional*) : Si se habilitan los CUDA graphs. Puede ser una tupla de booleanos (uno para la ruta varlen y otro para la ruta rápida de decodificación), un booleano que se aplicará a ambas rutas, o None (inferencia automática). Después de llamar a `decide_use_cuda_graphs`, el atributo será una tupla de booleanos. El valor predeterminado es None (inferencia automática).

q_padding_interval_size (`int`, *opcional*, valor predeterminado 0) : Granularidad de relleno de la consulta en tokens para los gráficos de CUDA. Utiliza una configuración preestablecida de `continuous_api.py` cuando se establece en 0.

kv_padding_interval_size (`int`, *opcional*, valor predeterminado 0) : Granularidad del relleno de KV en tokens para los gráficos de CUDA. Utiliza una configuración preestablecida de `continuous_api.py` cuando se establece en 0.

varlen_compile_config (`CompileConfig`, *opcional*) : CompileConfig para la ruta varlen (prefill). El valor predeterminado es None (usa el fallback de generation_config). La ruta varlen maneja lotes con longitudes de consulta y KV variables, y a menudo se beneficia de dynamic=True.

decode_compile_config (`CompileConfig`, *opcional*) : CompileConfig para la ruta de decodificación (rápida). El valor predeterminado es None (usa el fallback de generation_config). La ruta de decodificación maneja lotes que no tienen longitud de KV dinámica, por lo que las formas estáticas encajan mejor.

default_compile_level (`int`, *opcional*, valor predeterminado 0) : Si este valor es >0 y no se proporciona una configuración de compilación para la ruta varlen o decode, se proporcionará una configuración de compilación predeterminada. El nivel puede llegar hasta 3, y un nivel más alto implica más rendimiento pero un tiempo de calentamiento más largo.

scheduler_type (`str`, *opcional*, valor predeterminado `"fifo"`) : Tipo de programador a utilizar.

safety_margin (`float`, *opcional*) : Margen de seguridad utilizado para limitar la cantidad de descargas. El valor predeterminado es None (usar el valor predeterminado de la clase).

return_logprobs (`bool`, *opcional*, valor predeterminado `False`) : Si se deben devolver las probabilidades de registro junto con los tokens generados.

seed (`int | None`, *opcional*) : Una semilla opcional para la generación. Si no se especifica, la semilla interna se establecerá en un valor aleatorio.

auto_switch_to_flash (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe cambiar automáticamente a flash attention (si está disponible) cuando la implementación es SDPA o eager. El valor predeterminado es True, porque flash es mucho mejor para el continuous batching.

cpu_offload_space (`float`, *opcional*, valor predeterminado 0.0) : Espacio de intercambio en CPU en GiB para el descargado de la caché KV. Se crea un búfer fijo en CPU preasignado de este tamaño durante la inicialización. Cuando la caché de la GPU está llena, las cachés KV de las solicitudes expulsadas se copian aquí en lugar de descartarse. 0 desactiva el descargado (predeterminado).

cpu_offload_space_safety_threshold (`float`, *opcional*, valor predeterminado 0.8) : Si `cpu_offload_space` supera esta fracción de la RAM total del sistema, se limita para evitar un OOM en el host. Establezca 1.0 para desactivar el límite de seguridad. Se ignora cuando psutil no está disponible.

max_queue_size (`int`, *opcional*, valor predeterminado 0) : Tamaño máximo de la cola de solicitudes para el servicio. 0 significa ilimitado.

per_request_processors (`bool`, *opcional*, valor predeterminado `False`) : Habilita los parámetros del procesador de logits por solicitud. El valor predeterminado es False.

drop_unsupported_processors (`bool`, *opcional*, valor predeterminado `True`) : Elimina los procesadores de logits no compatibles en lugar de generar un error. El valor predeterminado es True.

disable_nccl_graph_mixing (`bool`, *opcional*, valor predeterminado `True`) : Desactiva la red de seguridad de NCCL para las comunicaciones paralelas capturadas en un grafo. Nunca ocurre en CB y proporciona una mejora de rendimiento a TP.

cpu_group_timeout (`float`, *opcional*, valor predeterminado 300.0) : El tiempo (en segundos) tras el cual una comunicación por CPU caducará y el proceso se cerrará. Déjalo en None para no establecer un tiempo de espera. El valor predeterminado es 300 segundos.

use_default_compile_configs (`bool | None`, *opcional*) : Obsoleto en 5.11: use default_compile_level en su lugar.

max_cached_graphs (`int`, *opcional*) : Obsoleto en 5.13: el número máximo de grafos ya no es un problema.

block_size (`int | None`, *opcional*) : Obsoleto en 5.17: ahora se usa page_size en su lugar.

Clase que contiene los argumentos relativos al loteo continuo, al utilizar el loteo continuo a través del método `generate_batch` o el gestor de contexto `continuous_batching_context_manager`.