Hugging Face's logo

Transformers documentation

Непрерывная пакетная обработка

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

Непрерывная пакетная обработка

На этой странице описаны классы, лежащие в основе непрерывного батчинга при инференсе: отправка промптов, настройка планирования и ограничений по памяти, а также получение результатов.

Примеры использования приведены в руководстве Continuous batching, а о взаимодействии планирования и памяти — в документации 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]

Параметры

  • inputs — список входных последовательностей токенов (промптов)
  • generation_config — Необязательная конфигурация генерации
  • continuous_batching_config — Необязательная конфигурация непрерывного пакетирования
  • record_timestamps — Если установлено в true, запросы будут содержать метку времени для каждого сгенерированного токена
  • progress_bar — если установлено в true, будет отображаться индикатор прогресса
  • persistent_manager — сохранять ли менеджер после завершения генерации. По умолчанию False.
  • warmup — нужно ли предварительно захватывать графы CUDA перед обработкой запросов. По умолчанию True.

Возвращает

dict[str, GenerationOutput]

словарь, сопоставляющий идентификаторы запросов с объектами GenerationOutput

Генерация последовательностей для пакета промптов с использованием непрерывного пакетирования.

ContinuousBatchingManager

класс transformers.ContinuousBatchingManager

< >

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

Менеджер для обработки непрерывного батчинга запросов на генерацию. Он предоставляет пользовательский интерфейс для отправки запросов на генерацию, получения результатов и управления фоновым потоком генерации. Этот класс не следует создавать напрямую, а использовать один из следующих точек входа (все методы миксина 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

Параметры

  • input_ids — ID входных токенов, используемые в качестве промпта
  • request_id — Необязательный пользовательский идентификатор запроса (генерируется автоматически, если значение равно None)
  • max_new_tokens — Максимальное количество новых токенов для генерации
  • streaming — Флаг, определяющий, следует ли передавать токены по мере их генерации
  • record_timestamps — Записывать ли временные метки для каждого сгенерированного токена
  • eos_token_id — ID токена(ов) конца последовательности
  • logit_processor_kwargs — Именованные аргументы для процессора логитов.

Возвращает

str | None

Идентификатор запроса, если процесс является драйвером TP, иначе None.

Добавляет новый запрос генерации в очередь. Если процесс не является драйвером TP, это действие не выполняется.

add_requests

< >

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

Вспомогательная функция для пакетного вызова add_request и возврата их идентификаторов. Подробности смотрите в документации.

cancel_request

< >

( request_id: str )

Отмена запроса по его ID. Если этот метод вызывается из процесса, который не является драйвером TP, он ничего не делает: с менеджером взаимодействуют только процессы драйвера TP.

destroy

< >

( )

Завершает работу менеджера и освобождает распределённые ресурсы. Безопасно вызывать несколько раз. После вызова этого метода менеджер не может быть перезапущен.

get_result

< >

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

Получить один результат из очереди вывода. Если указан ID, возвращается первое совпадающее запрос. Если указан timeout, возвращается None после истечения тайм-аута (в секундах).

is_running

< >

( )

Возвращает True, если фоновый поток генерации был запущен и по-прежнему активен.

join

< >

( stop_trigger_time: floattimeout: float | None = None )

Дождитесь завершения фонового потока. Ожидание можно ограничить с помощью аргумента timeout (в секундах).

пауза

< >

( )

Контекстный менеджер, приостанавливающий цикл генерации, чтобы вызывающий поток мог использовать модель, как правило, для её обновления на месте. Поток входит в этот контекст только после того, как цикл будет приостановлен, а при выходе цикл возобновляется, сохраняя свой кэш и текущие запросы: ничего не сбрасывается и ни один запрос не теряется. Несколько потоков могут удерживать паузу одновременно, и цикл возобновляется после выхода последнего из них. Если включён TP, все ранки должны войти в этот контекст, иначе другие ранки будут блокироваться навсегда.

register_result_handler

< >

( request_id: strcallback: Callable )

Параметры

  • request_id (str) — Идентификатор запроса, для которого необходимо получить результаты.
  • callback (callable) — Вызывается с GenerationOutput для каждого результата.

Зарегистрируйте обратный вызов для доставки результата (потокового или непотокового).

Обработчик вызывается в цикле событий через call_soon_threadsafe каждый раз, когда для данного запроса формируется результат. Для потоковых запросов это происходит для каждого токена; для непотоковых — только по завершении. Обработчик автоматически удаляется после завершения запроса.

request_id_iter

< >

( request_id: str )

Итерировать по результатам, соответствующим конкретному идентификатору запроса (блокирующий режим).

Использует общую очередь вывода с повторной постановкой в очередь. Для обслуживания с высокой степенью параллелизма используйте вместо этого register_result_handler.

старт

< >

( )

Запустите фоновый поток генерации.

остановка

< >

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

Останавливает фоновый поток генерации. Если флаг block установлен в True, метод ожидает остановки потока в течение максимального времени timeout секунд (None означает отсутствие тайм-аута). Если флаг keep_for_next_session установлен в True, менеджер кэшируется в модели для будущего использования. Если установлен флаг hard_stop, фоновый поток генерации будет остановлен немедленно, а ожидающие запросы будут завершены с ошибкой.

switch_to_cb_friendly_attn

< >

( model: ProtoPretrainedModelauto_switch_to_flash: bool = True )

Переключите реализацию attn на совместимую с CB. Если auto_switch_to_flash равно True, а реализация attn — SDPA или eager, также переключитесь на flash, если он поддерживается и доступен.

разогрев

< >

( )

Предварительный захват графов CUDA для путей varlen и decode путём выполнения тестовых батчей. Инициализирует процессор батчей, если это ещё не было сделано.

Конфигурация непрерывного пакетирования

класс 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 )

Параметры

  • page_size (int, необязательный, по умолчанию 256) — Количество токенов, хранящихся для каждого слоя внутри страницы (полного внимания). Блок, хранящий кэш N слоев, содержит N страниц (по одной на слой), каждая из которых хранит кэш для page_size токенов одного слоя. По умолчанию 256.
  • num_blocks (int, необязательный) — Количество блоков в KV-кэше. Автоматически вычисляется из памяти GPU, если None.
  • max_batch_tokens (int, необязательный) — Максимальное количество токенов в батче. Автоматически вычисляется из доступной памяти GPU, если None.
  • max_memory_percent (float, необязательный) — Максимальный процент свободной памяти GPU (после загрузки модели), который следует использовать для KV-кэша. Если значение равно None, время выполнения определяет его как 0.9, если обработка логитов отсутствует, и как 0.8, если она присутствует, чтобы оставить запас под временные тензоры размером с словарь.
  • max_requests_per_batch (int, необязательный) — Максимальное количество запросов в батче. Если None, значение выводится автоматически из подсказок о нагрузке, с резервным значением 1024.
  • max_blocks_per_request (int, необязательный) — Максимальное количество блоков на запрос, используется в быстром пути декодирования flash_attn_with_kvcache для определения размера таблицы блоков. Установка значения 0 отключает быстрый путь декодирования. По умолчанию None (определяется автоматически).
  • allow_block_sharing (bool, необязательный, по умолчанию True) — Разрешает ли использование общего кэширования блоков для префиксного кэширования. Общее кэширование блоков может только разрешаться, но никогда не принуждаться, так как некоторые модели не поддерживают эту функцию. Отключите, если у вас мало коротких запросов, но длинные последовательности генерации.
  • use_async_batching (bool, необязательный) — Включает ли асинхронное двойное буферизирование, которое устраняет накладные расходы CPU в цикле непрерывного батчинга за счёт удвоения использования VRAM. Автоматически определяется, если None.
  • use_cuda_graph (bool or tuple[bool, bool], необязательный) — Определяет, следует ли включать CUDA graphs. Может быть кортежем из двух булевых значений (одно для пути varlen и одно для быстрого пути decode), булевым значением, применяемым к обоим путям, или None (определяется автоматически). После вызова decide_use_cuda_graphs атрибут становится кортежем из двух булевых значений. По умолчанию None (определяется автоматически).
  • q_padding_interval_size (int, необязательный, по умолчанию 0) — Размерность выравнивания запроса в токенах для CUDA-графов. При значении 0 используется пресет из continuous_api.py.
  • kv_padding_interval_size (int, необязательный, по умолчанию 0) — размерность выравнивания KV в токенах для CUDA-графов. При значении 0 используется пресет из continuous_api.py.
  • varlen_compile_config (CompileConfig, необязательный) — CompileConfig для varlen (prefill) пути. По умолчанию None (используется fallback из generation_config) Путь varlen обрабатывает батчи с изменяющейся длиной запросов и KV, часто выигрывая от dynamic=True.
  • decode_compile_config (CompileConfig, необязательный) — CompileConfig для пути декодирования (быстрый путь). По умолчанию None (используется запасной вариант из generation_config) Путь декодирования обрабатывает батчи без динамической длины KV, поэтому статические формы лучше подходят.
  • default_compile_level (int, необязательный, по умолчанию 0) — Если это значение >0 и конфигурация компиляции не указана для пути varlen или decode, будет предоставлена конфигурация компиляции по умолчанию. Уровень может достигать 3, при этом более высокий уровень означает большую производительность, но более длительное время прогрева.
  • scheduler_type (str, необязательный, по умолчанию "fifo") — Тип планировщика для использования.
  • safety_margin (float, необязательный) — Безопасный запас, используемый для ограничения объёма выгрузки. По умолчанию None (используется значение по умолчанию класса).
  • return_logprobs (bool, необязательный, по умолчанию False) — Возвращать ли логарифмические вероятности вместе с сгенерированными токенами.
  • seed (int | None, необязательный) — Необязательный seed для генерации. Если не указан, внутренний seed будет установлен в случайное значение.
  • auto_switch_to_flash (bool, необязательный, по умолчанию True) — Определяет, следует ли автоматически переключаться на flash attention (если он доступен), когда реализация — SDPA или eager. По умолчанию True, так как flash значительно лучше подходит для непрерывного батчинга.
  • cpu_offload_space (float, необязательный, по умолчанию 0.0) — объём swap-памяти на CPU в ГиБ для выгрузки KV-кэша. При инициализации создаётся предварительно выделенный буфер закреплённой памяти CPU указанного размера. Когда кэш на GPU заполняется, KV-кэши вытесненных запросов копируются сюда, а не удаляются. Значение 0 отключает выгрузку (по умолчанию).
  • cpu_offload_space_safety_threshold (float, необязательный, по умолчанию 0.8) — Если cpu_offload_space превышает эту долю от общего объёма системной ОЗУ, значение ограничивается, чтобы избежать исчерпания памяти на хосте. Установите 1.0, чтобы отключить ограничение безопасности. Игнорируется, если psutil недоступен.
  • max_queue_size (int, необязательный, по умолчанию 0) — Максимальный размер очереди запросов для обслуживания. 0 означает отсутствие ограничений.
  • per_request_processors (bool, необязательный, по умолчанию False) — Включает параметры logits-процессора для каждого запроса. По умолчанию False.
  • drop_unsupported_processors (bool, необязательный, по умолчанию True) — Удаляет неподдерживаемые обработчики логитов вместо того, чтобы вызывать ошибку. По умолчанию True.
  • disable_nccl_graph_mixing (bool, необязательный, по умолчанию True) — Отключает механизм безопасности NCCL для параллельных коммуникаций, захваченных в графе. В CB это не происходит, а для TP даёт прирост производительности.
  • cpu_group_timeout (float, необязательный, по умолчанию 300.0) — Время (в секундах), по истечении которого связь на CPU будет прервана по таймауту, а процесс завершится с ошибкой. Оставьте значение None, чтобы отключить таймаут. По умолчанию — 300 секунд.
  • use_default_compile_configs (bool | None, необязательный) — Устарело в 5.11: используйте вместо этого default_compile_level.
  • max_cached_graphs (int, необязательный) — Устарело в 5.13: максимальное количество графов больше не является проблемой.
  • block_size (int | None, необязательный) — Устарело в 5.17: теперь вместо него используется page_size.

Класс, содержащий аргументы, связанные с непрерывным батчингом, при использовании непрерывного батчинга через метод generate_batch или контекстный менеджер continuous_batching_context_manager.

Update on GitHub

←Конфигурация Коллатор данных→