Hugging Face's logo

Transformers documentation

Loteamento contínuo

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

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 e, para entender como o agendamento e a memória interagem, consulte o documento 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 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 mantido após o término da geração. O valor padrão é False.
  • warmup — se deve pré-capturar os gráficos CUDA antes de processar as 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

classe transformers.ContinuousBatchingManager

< >

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

Gerenciador para o processamento de solicitações de geração com loteamento contínuo. 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

< >

( 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 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 timestamps para cada token gerado
  • eos_token_id — ID(s) do(s) token(s) 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

< >

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

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

cancel_request

< >

( request_id: str )

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

< >

( )

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

get_result

< >

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

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

is_running

< >

( )

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

join

< >

( stop_trigger_time: floattimeout: float | None = None )

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

pausar

< >

( )

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

< >

( request_id: strcallback: Callable )

Parâmetros

  • request_id (str) — O ID da solicitação para 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

< >

( request_id: str )

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.

início

< >

( )

Inicie a thread de geração em segundo plano.

stop

< >

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

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 é 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 pendentes solicitações falharão.

switch_to_cb_friendly_attn

< >

( model: ProtoPretrainedModelauto_switch_to_flash: bool = True )

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

< >

( )

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

classe 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, 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 a partir 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 de 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 query 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 chegar a 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 valor padrão é None (usa o padrão da classe).
  • return_logprobs (bool, opcional, padrão False) — Se deve retornar as log probabilidades 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 flash é muito melhor para continuous batching.
  • 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 de CPU fixo (pinned) pré-alocado com esse tamanho é criado na inicialização. Quando o cache da GPU está cheio, os KV caches das requisiçõ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, ele é 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 parâmetros de 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 graph. Nunca ocorre no CB e proporciona um ganho de desempenho para o 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. Deixe como None para não haver tempo limite. 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) — Descontinuado 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.

Update on GitHub

←Configuração Colaborador de dados→