# Batching continu

Cette page documente les classes derrière l'inférence par lot continu : la soumission des prompts, la configuration de l'ordonnancement et des limites de mémoire, et la récupération des résultats.

Pour des exemples d’utilisation, consultez le guide [Continuous batching](../continuous_batching) et, pour comprendre l’interaction entre la planification et la mémoire, consultez le document [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)
```

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

**Paramètres :**

inputs : Liste de séquences de jetons d'entrée (invites)

generation_config : Configuration de génération facultative

continuous_batching_config : Configuration optionnelle du groupement continu

record_timestamps : Si défini sur true, les requêtes incluront un horodatage pour chaque jeton généré

progress_bar : Si défini sur true, une barre de progression sera affichée

persistent_manager : indique s'il faut conserver le gestionnaire après la fin de la génération. La valeur par défaut est False.

warmup : spécifie s'il faut pré-capturer les graphes CUDA avant le traitement des requêtes. La valeur par défaut est True.

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

un dictionnaire d'identifiants de requêtes vers des objets GenerationOutput

Générer des séquences pour un lot de prompts en utilisant le batchage continu.

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

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

Gestionnaire pour le traitement par lot continu des requêtes de génération. Il fournit une interface utilisateur pour soumettre des requêtes de génération, récupérer les résultats et gérer le thread de génération en arrière-plan. Cette classe ne doit pas être créée directement, mais via l'un des points d'entrée suivants (toutes les méthodes du mixin `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)
```

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

**Paramètres :**

input_ids : Identifiants des jetons d'entrée à utiliser comme invite

request_id : ID de demande personnalisé facultatif (généré automatiquement si None)

max_new_tokens : Nombre maximum de nouveaux jetons à générer

streaming : Indique s'il faut diffuser les jetons au fur et à mesure de leur génération

record_timestamps : Indique s'il faut enregistrer les horodatages pour chaque jeton généré

eos_token_id : ID(s) du jeton de fin de séquence

logit_processor_kwargs : Arguments par mot-clé pour le processeur de logits.

**Retourne :** `str | None`

L'identifiant de la requête si le processus est un pilote TP, None sinon.

Ajoute une nouvelle requête de génération à la file d’attente. Si le processus n’est pas un pilote TP, cette opération est sans effet.

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

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

Fonction utilitaire pour mettre en lot `add_request` et retourner leurs identifiants. Consultez sa documentation pour plus de détails.

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

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

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

Annuler une requête par son identifiant. Si cette méthode est appelée depuis un processus qui n'est pas un pilote TP, elle n'a aucun effet : seuls les processus pilotes TP interagissent avec le gestionnaire.

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

```python
destroy()
```

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

Termine le gestionnaire et libère les ressources distribuées. Il est sûr d'appeler cette méthode plusieurs fois. Après cet appel, le gestionnaire ne peut plus être redémarré.

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

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

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

Récupère un résultat depuis la file de sortie. Si un identifiant est fourni, renvoie la première requête correspondante. Si un délai d’attente est fourni, renvoie None après expiration du délai (en secondes).

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

```python
is_running()
```

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

Retourne True si le thread de génération en arrière-plan a été démarré et est toujours actif.

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

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

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

Attendez que le thread en arrière-plan se termine. L'attente peut être limitée à l'aide de l'argument timeout (en secondes).

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

```python
pause()
```

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

Un gestionnaire de contexte qui met en pause la boucle de génération, afin que le thread appelant puisse utiliser le modèle, généralement pour le mettre à jour sur place. Le thread n'entre dans ce contexte qu'une fois la boucle mise en pause, et la boucle reprend à la sortie, en conservant son cache et ses requêtes en cours : rien n'est vidangé et aucune requête n'est perdue. Plusieurs threads peuvent maintenir la pause simultanément, et la boucle reprend dès que le dernier thread en sort. Si le TP est activé, tous les rangs doivent entrer dans ce contexte, sinon les autres rangs resteront bloqués indéfiniment.

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

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

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

**Paramètres :**

request_id (*str*) : L'identifiant de la requête pour laquelle recevoir les sorties.

callback (*callable*) : Appelé avec un `GenerationOutput` pour chaque résultat.

Enregistrer un rappel pour la livraison des résultats (en streaming ou non).

Le rappel est invoqué sur la boucle d'événements via `call_soon_threadsafe` à chaque fois qu'un résultat est produit pour cette requête. Pour les requêtes en streaming, cela se produit à chaque jeton ; pour les requêtes non en streaming, uniquement à la fin. Le gestionnaire est automatiquement nettoyé lorsque la requête se termine.

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

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

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

Itérer sur les résultats correspondant à un identifiant de requête spécifique (bloquant).

Utilise la file de sortie partagée avec remise en file. Pour le service à forte concurrence, utilisez plutôt `register_result_handler`.

#### commencer[[transformers.ContinuousBatchingManager.start]]

```python
start()
```

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

Démarrer le thread de génération en arrière-plan.

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

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

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

Arrête le thread de génération en arrière-plan. Si le drapeau `block` est défini sur True, cette méthode attend l’arrêt du thread pendant un temps maximal de `timeout` secondes (None signifie aucun délai d’attente). Si le drapeau `keep_for_next_session` est défini sur True, le gestionnaire est mis en cache sur le modèle pour une utilisation future. Si le drapeau `hard_stop` est défini, le thread de génération en arrière-plan est arrêté immédiatement et les requêtes en attente échouent.

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

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

Basculez l’implémentation de l’attention vers une version compatible CB. Si auto_switch_to_flash est True et que l’implémentation de l’attention est SDPA ou eager, basculez également vers flash si celle-ci est prise en charge et disponible.

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

```python
warmup()
```

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

Pré-capture des graphes CUDA pour les chemins varlen et decode en exécutant des lots fictifs. Initialise le processeur de lots si ce n'est pas déjà fait.

## Configuration du lotissement continu[[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)
```

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

**Paramètres :**

page_size (`int`, *facultatif*, valeur par défaut : 256) : Le nombre de jetons stockés pour chaque couche à l'intérieur d'une page (attention complète). Un bloc stockant le cache de N couches contient N pages (une par couche), chacune contenant le cache de `page_size` jetons pour une couche. La valeur par défaut est 256.

num_blocks (`int`, *facultatif*) : Nombre de blocs dans le cache KV. Inféré automatiquement à partir de la mémoire GPU lorsque la valeur est `None`.

max_batch_tokens (`int`, *facultatif*) : Nombre maximal de jetons par lot. Inféré automatiquement à partir de la mémoire GPU lorsque la valeur est `None`.

max_memory_percent (`float`, *facultatif*) : Pourcentage maximal de la mémoire GPU libre (après le chargement du modèle) à utiliser pour le cache KV. Si la valeur est `None`, elle est résolue à l'exécution à 0,9 s'il n'y a pas de traitement des logits, et à 0,8 s'il y en a, afin de laisser de la marge pour les tenseurs temporaires de la taille du vocabulaire.

max_requests_per_batch (`int`, *facultatif*) : Nombre maximal de requêtes par lot. Inféré automatiquement à partir des indices de charge de travail lorsque la valeur est `None`, avec une valeur par défaut de 1024.

max_blocks_per_request (`int`, *facultatif*) : Nombre maximal de blocs par requête, utilisé dans le chemin de décodage rapide `flash_attn_with_kvcache` pour dimensionner le tableau de blocs. Définir cette valeur à 0 désactive le chemin de décodage rapide. La valeur par défaut est None (inférée automatiquement).

allow_block_sharing (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut autoriser le partage de blocs pour le cache de préfixe. Le partage de blocs ne peut être que autorisé, jamais imposé, car certains modèles ne le prennent pas en charge. À désactiver si vous avez peu de prompts courts mais des longueurs de génération importantes.

use_async_batching (`bool`, *facultatif*) : Indique s'il faut activer le double-buffering asynchrone, qui supprime la surcharge CPU de la boucle de lotissement continu au prix d'un doublement de l'utilisation de la VRAM. Détecté automatiquement lorsque la valeur est `None`.

use_cuda_graph (`bool` ou `tuple[bool, bool]`, *facultatif*) : Indique s'il faut activer les graphes CUDA. Cette valeur peut être un tuple de booléens (un pour le chemin varlen et un pour le chemin rapide de décodage), un booléen qui s'appliquera aux deux chemins, ou None (inféré automatiquement). Après l'appel de `decide_use_cuda_graphs`, l'attribut sera un tuple de booléens. La valeur par défaut est None (inféré automatiquement).

q_padding_interval_size (`int`, *facultatif*, valeur par défaut 0) : Granularité du padding de requête en jetons pour les graphes CUDA. Utilise un préréglage de `continuous_api.py` lorsqu'il est défini sur 0.

kv_padding_interval_size (`int`, *facultatif*, valeur par défaut 0) : granularité du padding KV en jetons pour les graphes CUDA. Utilise un préréglage de `continuous_api.py` lorsqu'il est défini sur 0.

varlen_compile_config (`CompileConfig`, *facultatif*) : CompileConfig pour le chemin varlen (prefill). La valeur par défaut est None (utilise le repli sur generation_config). Le chemin varlen gère des lots avec des longueurs de requête et de KV variables, et bénéficie souvent de dynamic=True.

decode_compile_config (`CompileConfig`, *facultatif*) : CompileConfig pour le chemin de décodage (rapide). La valeur par défaut est None (utilise le repli de generation_config). Le chemin de décodage gère des lots sans longueur de KV dynamique, ce qui convient mieux aux formes statiques.

default_compile_level (`int`, *facultatif*, valeur par défaut 0) : Si cette valeur est >0 et qu'aucune configuration de compilation n'est fournie pour le chemin varlen ou decode, une configuration de compilation par défaut sera fournie. Le niveau peut aller jusqu'à 3, et un niveau plus élevé signifie de meilleures performances mais un temps de préchauffage plus long.

scheduler_type (`str`, *facultatif*, valeur par défaut `"fifo"`) : Type de planificateur à utiliser.

safety_margin (`float`, *facultatif*) : Marge de sécurité utilisée pour limiter la quantité de déchargement. Valeur par défaut : None (utiliser la valeur par défaut de la classe).

return_logprobs (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut retourner les probabilités logarithmiques en plus des jetons générés.

seed (`int | None`, *facultatif*) : Graine facultative pour la génération. Si elle n'est pas spécifiée, la graine interne est définie sur une valeur aléatoire.

auto_switch_to_flash (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut basculer automatiquement sur flash attention (si disponible) lorsque l'implémentation est SDPA ou eager. La valeur par défaut est True, car flash est bien plus performant pour le continuous batching.

cpu_offload_space (`float`, *facultatif*, valeur par défaut 0.0) : espace d'échange CPU en GiB pour le déchargement du cache KV. Un tampon CPU épinglé préalloué de cette taille est créé à l'initialisation. Lorsque le cache GPU est plein, les caches KV des requêtes évacuées sont copiés ici au lieu d'être supprimés. 0 désactive le déchargement (valeur par défaut).

cpu_offload_space_safety_threshold (`float`, *facultatif*, valeur par défaut 0,8) : Si `cpu_offload_space` dépasse cette fraction de la RAM système totale, il est limité pour éviter une OOM hôte. Définissez la valeur à 1,0 pour désactiver cette limite de sécurité. Ignoré si psutil n'est pas disponible.

max_queue_size (`int`, *facultatif*, valeur par défaut 0) : Taille maximale de la file d'attente des requêtes pour le service. 0 signifie illimité.

per_request_processors (`bool`, *facultatif*, valeur par défaut `False`) : Active les paramètres du processeur de logits par requête. La valeur par défaut est False.

drop_unsupported_processors (`bool`, *facultatif*, valeur par défaut `True`) : Supprime les processeurs de logits non pris en charge au lieu de déclencher une erreur. La valeur par défaut est True.

disable_nccl_graph_mixing (`bool`, *facultatif*, valeur par défaut `True`) : Désactive le filet de sécurité de NCCL pour les communications parallèles capturées par graphe. Ne se produit jamais dans CB et offre un gain de performance à TP.

cpu_group_timeout (`float`, *facultatif*, valeur par défaut 300.0) : Le délai (en secondes) après lequel une communication CPU expirera et le processus s'arrêtera. Laisser à None pour désactiver le délai d'attente. La valeur par défaut est de 300 secondes.

use_default_compile_configs (`bool | None`, *facultatif*) : Déprécié dans la version 5.11 : veuillez utiliser default_compile_level à la place.

max_cached_graphs (`int`, *facultatif*) : Déprécié dans la version 5.13 : le nombre maximal de graphes n'est plus un problème.

block_size (`int | None`, *facultatif*) : Déprécié dans la version 5.17 : page_size est désormais utilisé à la place.

Classe qui contient les arguments relatifs au batch continu, lors de l’utilisation du batch continu via la méthode `generate_batch` ou le gestionnaire de contexte `continuous_batching_context_manager`.