# Loteamento contínuo

Esta página documenta as classes por trás da inferência com loteamento contínuo: envio de prompts, configuração de agendamento e limites de memória, e recuperação de resultados.

Para exemplos de uso, consulte o guia [Continuous batching](../continuous_batching) e, para entender como o agendamento e a memória interagem, consulte o documento [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)
```

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

**Parâmetros:**

inputs : Lista de sequências de tokens de entrada (prompts)

generation_config : Configuração de geração opcional

continuous_batching_config : Configuração opcional de loteamento contínuo

record_timestamps : Se definido como true, as solicitações terão um timestamp para cada token gerado

progress_bar : Se definido como true, uma barra de progresso será exibida

persistent_manager : se o gerenciador deve ser persistido após o término da geração. O valor padrão é False.

warmup : se as grafos CUDA devem ser pré-capturados antes do processamento das solicitações. O valor padrão é True.

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

um dicionário de ids de solicitação para objetos GenerationOutput

Gere sequências para um 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)
```

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

Gerenciador para o processamento em lote contínuo de solicitações de geração. Ele fornece uma interface de usuário para o envio de solicitações de geração, a recuperação de resultados e o gerenciamento da thread de geração em segundo plano. Esta classe não deve ser criada diretamente, mas por meio de um dos seguintes pontos de entrada (todos métodos do 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)
```

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

**Parâmetros:**

input_ids : IDs dos tokens de entrada a serem usados como prompt

request_id : ID de solicitação personalizado opcional (gerado automaticamente se for None)

max_new_tokens : Número máximo de novos tokens a serem gerados

streaming : Se os tokens devem ser transmitidos conforme são gerados

record_timestamps : Se deve registrar carimbos de data e hora para cada token gerado

eos_token_id : ID(s) do token de fim de sequência

logit_processor_kwargs : Argumentos de palavra-chave para o processador de logits.

**Retorna:** `str | None`

O ID da solicitação, se o processo for um driver de TP; caso contrário, None.

Adiciona uma nova solicitação de geração à fila. Se o processo não for um driver de TP, esta é uma operação sem efeito.

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

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

Função utilitária para agrupar `add_request` e retornar seus IDs. Consulte sua documentação para mais detalhes.

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

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

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

Cancela uma solicitação pelo seu ID. Se chamado de um processo que não é um driver de TP, é uma operação nula: apenas os processos de driver de TP interagem com o gerenciador.

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

```python
destroy()
```

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

Encerra o gerenciador e libera os recursos distribuídos. É seguro chamar várias vezes. Após chamar este método, o gerenciador não pode ser reiniciado.

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

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

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

Recupera um resultado da fila de saída. Se um ID for fornecido, retorna a primeira solicitação correspondente. Se um tempo limite for fornecido, retorna None após o tempo limite (em segundos).

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

```python
is_running()
```

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

Retorna True se a thread de geração em segundo plano foi iniciada e ainda está ativa.

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

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

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

Aguarde a conclusão da thread em segundo plano. O tempo de espera pode ser limitado usando o argumento timeout (em segundos).

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

```python
pause()
```

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

Um gerenciador de contexto que pausa o loop de geração, permitindo que a thread chamadora utilize o modelo, tipicamente para atualizá-lo no local. A thread só entra neste contexto quando o loop está pausado, e o loop retoma ao sair, mantendo seu cache e suas solicitações em andamento: nada é drenado e nenhuma solicitação é perdida. Várias threads podem manter a pausa simultaneamente, e o loop retoma quando a última delas sai. Se o TP estiver ativado, todos os ranks devem entrar neste contexto; caso contrário, os outros ranks ficarão pendurados para sempre.

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

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

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

**Parâmetros:**

request_id (*str*) : O ID da solicitação para o qual receber as saídas.

callback (*callable*) : Chamado com um `GenerationOutput` para cada resultado.

Registre um callback para a entrega de resultados (com streaming ou sem streaming).

O callback é chamado no loop de eventos por meio de `call_soon_threadsafe` sempre que um resultado é produzido para esta solicitação. Para solicitações com streaming, isso ocorre a cada token; para as não-streaming, apenas na conclusão. O manipulador é limpo automaticamente quando a solicitação termina.

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

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

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

Iterar sobre os resultados que correspondem a um id de solicitação específico (bloqueante).

Usa a fila de saída compartilhada com requeue. Para atendimento com alta concorrência, use `register_result_handler` em vez disso.

#### iniciar[[transformers.ContinuousBatchingManager.start]]

```python
start()
```

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

Inicie a thread de geração em 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)
```

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

Interrompe a thread de geração em segundo plano. Se a flag `block` estiver definida como True, este método aguarda a parada da thread por um tempo máximo de `timeout` segundos (None significa sem tempo limite). Se a flag `keep_for_next_session` estiver definida como True, o gerenciador será armazenado em cache no modelo para uso futuro. Se a flag `hard_stop` estiver definida, a thread de geração em segundo plano será interrompida imediatamente e as solicitações pendentes serão falhadas.

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

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

Alterne a implementação de attn para uma compatível com CB. Se auto_switch_to_flash for True e a implementação de attn for SDPA ou eager, alterne também para flash, caso seja suportado e disponível.

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

```python
warmup()
```

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

Pré-captura os gráficos CUDA para os caminhos varlen e decode executando lotes fictícios. Inicializa o processador de lotes, caso ainda não tenha sido feito.

## Configuração de lote contínuo[[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)
```

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

**Parâmetros:**

page_size (`int`, *opcional*, padrão 256) : O número de tokens armazenados para cada camada dentro de uma página (de atenção completa). Um bloco que armazena o cache de N camadas possui N páginas (uma por camada), cada uma contendo o cache de `page_size` tokens para uma camada. O padrão é 256.

num_blocks (`int`, *opcional*) : Número de blocos no cache de KV. Inferido automaticamente da memória da GPU quando `None`.

max_batch_tokens (`int`, *opcional*) : Número máximo de tokens em um lote. Inferido automaticamente da memória da GPU quando `None`.

max_memory_percent (`float`, *opcional*) : Percentual máximo da memória livre da GPU (após o carregamento do modelo) a ser usado para o cache de KV. Quando `None`, o valor é resolvido em tempo de execução como 0,9 se não houver processamento de logits e 0,8 se houver, para deixar folga para tensores temporários do tamanho do vocabulário.

max_requests_per_batch (`int`, *opcional*) : Número máximo de solicitações por lote. Inferido automaticamente a partir das dicas de carga de trabalho quando `None`, com valor padrão de 1024.

max_blocks_per_request (`int`, *opcional*) : Número máximo de blocos por solicitação, usado no caminho de decodificação rápida `flash_attn_with_kvcache` para dimensionar a tabela de blocos. Definir este valor como 0 desativa o caminho de decodificação rápida. O padrão é None (inferido automaticamente).

allow_block_sharing (`bool`, *opcional*, padrão `True`) : Se permite o compartilhamento de blocos para cache de prefixo. O compartilhamento de blocos só pode ser permitido, nunca forçado, pois alguns modelos não o suportam. Desative se você tiver poucos prompts curtos, mas com comprimentos de geração longos.

use_async_batching (`bool`, *opcional*) : Se deve habilitar o double-buffering assíncrono, que remove a sobrecarga da CPU do loop de continuous batching, ao custo de um uso de VRAM dobrado. Detectado automaticamente quando `None`.

use_cuda_graph (`bool` ou `tuple[bool, bool]`, *opcional*) : Se deve habilitar os CUDA graphs. Pode ser uma tupla de booleanos (um para o caminho varlen e um para o caminho rápido de decodificação), um booleano que será aplicado a ambos os caminhos, ou None (inferido automaticamente). Após chamar `decide_use_cuda_graphs`, o atributo será uma tupla de booleanos. O padrão é None (inferido automaticamente).

q_padding_interval_size (`int`, *opcional*, padrão 0) : Granularidade de padding da consulta em tokens para CUDA graphs. Usa um preset de `continuous_api.py` quando definido como 0.

kv_padding_interval_size (`int`, *opcional*, padrão 0) : Granularidade de padding de KV em tokens para CUDA graphs. Usa um preset de `continuous_api.py` quando definido como 0.

varlen_compile_config (`CompileConfig`, *opcional*) : CompileConfig para o caminho varlen (prefill). O padrão é None (usa o fallback de generation_config). O caminho varlen lida com lotes com comprimentos de query e KV variáveis, frequentemente se beneficiando de dynamic=True.

decode_compile_config (`CompileConfig`, *opcional*) : CompileConfig para o caminho de decodificação (rápido). O padrão é None (usa o fallback de generation_config). O caminho de decodificação processa lotes sem comprimento dinâmico de KV, portanto, formas estáticas são mais adequadas.

default_compile_level (`int`, *opcional*, padrão 0) : Se este valor for >0 e nenhuma configuração de compilação for fornecida para o caminho varlen ou decode, uma configuração de compilação padrão será fornecida. O nível pode ir até 3, e um nível mais alto significa mais desempenho, mas tempo de aquecimento mais longo.

scheduler_type (`str`, *opcional*, padrão `"fifo"`) : Tipo de agendador a ser usado.

safety_margin (`float`, *opcional*) : Margem de segurança usada para limitar a quantidade de offloading. O padrão é None (usar o padrão da classe).

return_logprobs (`bool`, *opcional*, padrão `False`) : Se deve retornar as probabilidades logarítmicas junto com os tokens gerados.

seed (`int | None`, *opcional*) : Uma semente opcional para a geração. Se não for especificada, a semente interna será definida com um valor aleatório.

auto_switch_to_flash (`bool`, *opcional*, padrão `True`) : Se deve alternar automaticamente para flash attention (se disponível) quando a implementação for SDPA ou eager. O padrão é True, pois o flash é muito melhor para loteamento contínuo.

cpu_offload_space (`float`, *opcional*, padrão 0.0) : Espaço de troca na CPU em GiB para o offloading do KV cache. Um buffer fixo (pinned) na CPU com esse tamanho é pré-alocado na inicialização. Quando o cache da GPU fica cheio, os KV caches das solicitações removidas são copiados para cá em vez de serem descartados. 0 desativa o offloading (padrão).

cpu_offload_space_safety_threshold (`float`, *opcional*, padrão 0.8) : Se `cpu_offload_space` exceder essa fração da RAM total do sistema, o valor é limitado para evitar OOM no host. Defina como 1.0 para desativar o limite de segurança. Ignorado quando o psutil não está disponível.

max_queue_size (`int`, *opcional*, padrão 0) : Tamanho máximo da fila de solicitações para o serviço. 0 significa ilimitado.

per_request_processors (`bool`, *opcional*, padrão `False`) : Ativa os parâmetros do processador de logits por solicitação. O padrão é False.

drop_unsupported_processors (`bool`, *opcional*, padrão `True`) : Remove processadores de logits não suportados em vez de gerar um erro. O padrão é True.

disable_nccl_graph_mixing (`bool`, *opcional*, padrão `True`) : Desativa a rede de segurança do NCCL para comunicações capturadas em paralelo por grafo. Nunca ocorre no CB e proporciona um aumento de desempenho ao TP.

cpu_group_timeout (`float`, *opcional*, padrão 300.0) : O tempo (em segundos) após o qual uma comunicação de CPU expira e o processo é encerrado. Defina como None para não haver expiração. O padrão é 300 segundos.

use_default_compile_configs (`bool | None`, *opcional*) : Descontinuado na 5.11: use default_compile_level em vez disso.

max_cached_graphs (`int`, *opcional*) : Obsoleto na 5.13: o número máximo de grafos não é mais um problema.

block_size (`int | None`, *opcional*) : Descontinuado na 5.17: agora page_size é usado no lugar.

Classe que armazena os argumentos relativos ao continuous batching, ao usar continuous batching por meio do método `generate_batch` ou do context manager `continuous_batching_context_manager`.