Hugging Face's logo

Transformers documentation

Loteo continuo

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

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 y, para saber cómo interactúan la programación y la memoria, consulte el documento de 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]

Parámetros

  • inputs — Lista de secuencias de tokens de entrada (prompts)
  • 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 tendrá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 mantener el gestor después de que finalice la generación. El valor predeterminado es False.
  • warmup — si se deben precapturar los gráficos de CUDA 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

clase transformers.ContinuousBatchingManager

< >

( model: ProtoPretrainedModelgeneration_config: GenerationConfigcontinuous_batching_config: ContinuousBatchingConfigworkload_hints: transformers.generation.continuous_batching.utils.WorkloadHints | None = None )

Gestor para el procesamiento por lotes continuo de solicitudes de generación. Proporciona una interfaz de usuario para enviar solicitudes de generación, recuperar 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

< >

( 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

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 registran marcas de tiempo para cada token generado
  • eos_token_id — ID(s) del token de fin de secuencia
  • logit_processor_kwargs — Argumentos de palabra 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

< >

( inputs: listmax_new_tokens: int | None = Nonestreaming: bool = Falserecord_timestamps: bool = False**logit_processor_kwargs: Any )

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

cancel_request

< >

( request_id: str )

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

< >

( )

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

< >

( request_id: str | None = Nonetimeout: float | None = None )

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

is_running

< >

( )

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

join

< >

( stop_trigger_time: floattimeout: float | None = None )

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

pausa

< >

( )

Un gestor de contexto que pausa el bucle de generación, de modo que el hilo que lo llama pueda usar 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 sale. Si TP está activado, todos los rangos deben entrar en este contexto, de lo contrario los demás rangos se bloquearán indefinidamente.

register_result_handler

< >

( request_id: strcallback: Callable )

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 termina.

request_id_iter

< >

( request_id: str )

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.

inicio

< >

( )

Inicie el hilo de generación en segundo plano.

stop

< >

( block: bool = Truetimeout: float | None = Nonekeep_for_next_session: bool = Falsehard_stop: bool = False )

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

< >

( model: ProtoPretrainedModelauto_switch_to_flash: bool = True )

Cambia la implementación de attn a una que sea 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.

calentamiento

< >

( )

Captura de antemano los 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

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

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 la 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 (inferido automáticamente). Después de llamar a decide_use_cuda_graphs, el atributo será una tupla de booleanos. El valor predeterminado es None (inferido automáticamente).
  • q_padding_interval_size (int, opcional, valor predeterminado 0) — Granularidad del 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 son más adecuadas.
  • default_compile_level (int, opcional, valor predeterminado 0) — Si este valor es >0 y no se proporciona ninguna 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 significa más rendimiento pero un tiempo de calentamiento más largo.
  • scheduler_type (str, opcional, por defecto "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 logarítmicas 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) — 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 de CPU preasignado de este tamaño durante la inicialización. Cuando la caché de 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 deshabilitar 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 capturadas en paralelo mediante grafos. 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 de CPU expirará y el proceso se cerrará. Déjalo en None para no tener 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) — No recomendado 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.

Update on GitHub

←Configuración Colaborador de datos→