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

Модели

Базовый класс PreTrainedModel реализует общие методы для загрузки/сохранения модели из локального файла или каталога, либо из конфигурации предобученной модели, предоставляемой библиотекой (скачанной с HuggingFace Hub).

PreTrainedModel также реализует несколько методов, общих для всех моделей:

  • изменить размер встраиваний входных токенов при добавлении новых токенов в словарь

Остальные методы, общие для каждой модели, определены в ModuleUtilsMixin и GenerationMixin.

PreTrainedModel

класс transformers.PreTrainedModel

< >

( config: PreTrainedConfig*inputs**kwargs )

Базовый класс для всех моделей.

PreTrainedModel отвечает за хранение конфигурации моделей и управляет методами загрузки, скачивания и сохранения моделей, а также несколькими методами, общими для всех моделей:

  • изменить размер входных эмбеддингов

Атрибуты класса (переопределяются производными классами):

  • config_class (PreTrainedConfig) — Подкласс PreTrainedConfig, используемый в качестве класса конфигурации для данной архитектуры модели.
  • base_model_prefix (str) — строка, указывающая на атрибут, связанный с базовой моделью в производных классах той же архитектуры, которые добавляют модули поверх базовой модели.
  • main_input_name (str) — Название основного входа модели (часто input_ids для NLP-моделей, pixel_values для моделей зрения и input_values для речевых моделей).
  • can_record_outputs (dict):

push_to_hub

< >

( repo_id: strcommit_message: str | None = Nonecommit_description: str | None = Noneprivate: bool | None = Nonetoken: bool | str | None = Nonerevision: str | None = Nonecreate_pr: bool = Falsemax_shard_size: int | str | None = '50GB'tags: list[str] | None = None )

Параметры

  • repo_id (str) — Имя репозитория, в который вы хотите загрузить свою модель. При загрузке в конкретную организацию оно должно содержать имя вашей организации.
  • commit_message (str, необязательный) — Сообщение для коммита при отправке. По умолчанию — "Upload model".
  • commit_description (str, необязательный) — Описание коммита, который будет создан
  • private (bool, optional) — Определяет, следует ли сделать репозиторий приватным. Если None (по умолчанию), репозиторий будет публичным, если только по умолчанию для организации не задан приватный режим. Это значение игнорируется, если репозиторий уже существует.
  • token (bool или str, необязательный) — Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если True (по умолчанию), будет использован токен, сгенерированный при выполнении hf auth login (хранится в ~/.huggingface).
  • revision (str, необязательный) — Ветка, в которую будут загружены файлы.
  • create_pr (bool, необязательный, по умолчанию False) — Создавать ли PR с загруженными файлами или коммитить изменения напрямую.
  • max_shard_size (int или str, необязательный, по умолчанию "50GB") — Применимо только к моделям. Максимальный размер контрольной точки перед её разбиением на части. Каждая из частей будет иметь размер, меньший этого значения. Если значение указано в виде строки, оно должно состоять из цифр, за которыми следует единица измерения (например, "5MB").
  • tags (list[str], необязательный) — Список тегов для загрузки на Hub.

Загрузите файл модели в 🤗 Model Hub.

Примеры:

from transformers import AutoModel

model = AutoModel.from_pretrained("google-bert/bert-base-cased")

# Push the model to your namespace with the name "my-finetuned-bert".
model.push_to_hub("my-finetuned-bert")

# Push the model to an organization with the name "my-finetuned-bert".
model.push_to_hub("huggingface/my-finetuned-bert")

activation_checkpointing_disable

< >

( )

Отключает контрольную точку активации для текущей модели.

activation_checkpointing_enable

< >

( activation_checkpointing_kwargs = Noneevery_n_layers: int = 1offload: bool = False )

Параметры

  • every_n_layers (int, необязательный, по умолчанию 1) — Создавать контрольные точки только для каждого every_n_layers-го слоя декодера, оставляя остальные слои с сохранёнными активациями. Значение 1 создаёт контрольные точки для каждого слоя, что соответствует стандартному поведению «всё или ничего». Большие значения позволяют обменять освобождённую память на скорость, что оправдано, когда память, высвобожденная при полном контрольном точковании, остаётся неиспользованной.
  • offload (bool, необязательный, по умолчанию False) — Хранить активации, сохранённые для пересчёта, в закреплённой памяти хоста, а не на ускорителе. Это освобождает layers x sequence x hidden байт памяти устройства, что является доминирующим фактором при длинных последовательностях, но требует копирования с устройства на хост в прямом проходе и с хоста на устройство в обратном. Оба копирования выполняются в потоке вычислений, из-за чего шаг становится медленнее.
  • activation_checkpointing_kwargs (dict, необязательный) — Дополнительные именованные аргументы, передаваемые в функцию torch.utils.checkpoint.checkpoint.

Включает контрольную точку активации для текущей модели.

Мы передаём метод __call__ модулей вместо forward, потому что __call__ подключает все хуки модуля. https://discuss.pytorch.org/t/any-different-between-model-input-and-model-forward-input/3690/2

add_model_tags

< >

( tags: list[str] | str )

Параметры

  • tags (Union[list[str], str]) — Необходимые теги для внедрения в модель

Добавляет пользовательские теги в модель, которая отправляется на Hugging Face Hub. Существующие теги модели не будут перезаписаны.

Примеры:

from transformers import AutoModel

model = AutoModel.from_pretrained("google-bert/bert-base-cased")

model.add_model_tags(["custom", "custom-bert"])

# Push the model to your namespace with the name "my-custom-bert".
model.push_to_hub("my-custom-bert")

can_generate

< >

( ) → bool

Возвращает

bool

Может ли эта модель генерировать последовательности с помощью .generate().

Возвращает, может ли эта модель генерировать последовательности с помощью .generate(), из GenerationMixin или из класса с похожим интерфейсом.

Внутри, для классов, для которых эта функция возвращает True, запускаются некоторые изменения, специфичные для генерации: например, у экземпляра модели будет заполнен атрибут generation_config.

cuda

( *args**kwargs )

Мок-значение для пути с точками (например, torch.float32): цепочки доступа к атрибутам и вызовы работают как пропускные декораторы, repr возвращает путь с точками, а использование в качестве базового класса подставляет обычный базовый класс type (PEP 560 __mro_entries__), благодаря чему реальные дочерние классы сохраняют обычный метакласс, а inspect.signature читает их реальный __init__, а не мок-объект.

dequantize

< >

( dtype = None )

При необходимости выполнить декуантизацию модели, если она была квантована методом квантования, поддерживающим декуантизацию.

disable_input_require_grads

< >

( )

Удаляет _require_grads_hook.

enable_input_require_grads

< >

( )

Включает градиенты для входных эмбеддингов. Это полезно для дообучения весов адаптеров при сохранении весов модели неизменными.

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLike | None*model_argsconfig: transformers.configuration_utils.PreTrainedConfig | str | os.PathLike | None = Nonecache_dir: str | os.PathLike | None = Noneignore_mismatched_sizes: bool = Falseforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'use_safetensors: bool | None = Noneweights_only: bool = Truefusion_config: dict[str, bool | dict[str, typing.Any]] | None = Nonedisable_mmap: bool | None = None**kwargs )

Параметры

  • pretrained_model_name_or_path (str или os.PathLike, необязательный) — Может быть одним из следующих:
    • Строка, model id предобученной модели, размещенной в репозитории моделей на huggingface.co.
    • Путь к каталогу, содержащему веса модели, сохранённые с помощью save_pretrained(), например, ./my_model_directory/. Каталоги, сохранённые с save_pretrained(..., distributed_checkpoint=True), обнаруживаются и загружаются с использованием распределённого чекпоинтинга (DCP), сохраняя текущую сетку и размещения модели. Для этого требуется torch>=2.7, и загрузка выполняется строго: каждый ключ модели должен присутствовать в чекпоинте.
    • None, если вы предоставляете и конфигурацию, и словарь состояния (соответственно, с аргументами по имени config и state_dict).
  • model_args (последовательность позиционных аргументов, необязательно) — Все оставшиеся позиционные аргументы передаются в метод __init__ базовой модели.
  • config (Union[PreTrainedConfig, str, os.PathLike], необязательный) — Может быть:
    • экземпляр класса, производного от PreTrainedConfig,
    • строка или путь, допустимый в качестве входного параметра для from_pretrained().

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

    • Модель — это модель, предоставляемая библиотекой (загружаемая с помощью строки model id предобученной модели).
    • Модель была сохранена с помощью save_pretrained() и загружается заново путем указания каталога сохранения.
    • Модель загружается путём указания локального каталога в качестве pretrained_model_name_or_path, при этом в каталоге находится файл конфигурации JSON с именем config.json.
  • state_dict (dict[str, torch.Tensor], необязательный) — Словарь состояния, который используется вместо словаря состояния, загруженного из файла сохранённых весов. Этот параметр можно использовать, если вы хотите создать модель на основе предобученной конфигурации, но загрузить собственные веса. В этом случае, однако, стоит проверить, не является ли использование save_pretrained() и from_pretrained() более простым вариантом.

    Этот вариант можно использовать, если вы хотите создать модель на основе предобученной конфигурации, но загрузить собственные веса. В этом случае, однако, стоит проверить, не является ли использование save_pretrained() и from_pretrained() более простым решением.

  • cache_dir (Union[str, os.PathLike], необязательный) — Путь к каталогу, в котором следует кэшировать загруженную конфигурацию предобученной модели, если стандартный кэш не используется.
  • ignore_mismatched_sizes (bool, необязательный, по умолчанию False) — Следует ли вызывать ошибку, если размеры некоторых весов из контрольной точки не совпадают с размерами весов модели (например, если вы инициализируете модель с 10 метками из контрольной точки с 3 метками).
  • force_download (bool, необязательный, по умолчанию False) — Следует ли принудительно (пере)скачивать веса модели и файлы конфигурации, игнорируя кэшированные версии, если они существуют.
  • proxies (dict[str, str], необязательный) — Словарь прокси-серверов, используемых по протоколу или конечной точке, например, {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Прокси применяются при каждом запросе.
  • output_loading_info(bool, optional, по умолчанию False) — Определяет, следует ли также возвращать словарь, содержащий отсутствующие ключи, неожиданные ключи и сообщения об ошибках.
  • local_files_only(bool, optional, по умолчанию False) — Определяет, следует ли использовать только локальные файлы (то есть не пытаться скачать модель).
  • token (str или bool, необязательный) — Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если указано True или параметр не задан, будет использован токен, сгенерированный при выполнении hf auth login (хранится в ~/.huggingface).
  • revision (str, необязательный, по умолчанию "main") — Конкретная версия модели, которую нужно использовать. Это может быть имя ветки, имя тега или идентификатор коммита, так как для хранения моделей и других артефактов на huggingface.co используется система на базе git, поэтому revision может быть любым идентификатором, разрешенным git.

    Чтобы протестировать pull request, который вы создали на Hub, вы можете передать revision="refs/pr/<pr_number>".

  • attn_implementation (str, необязательный) — Реализация механизма внимания, используемая в модели (если применимо). Допустимые значения:

    Принимать ссылки на ядра HF в формате:

    /[@][:]
    • и — это любые последовательности, не содержащие «/» и «:».
    • “@” является необязательным (ветка, тег или commit-ish), например, “@main”, “@v1.2.0”, “@abc123”.
    • ”:” — необязательный параметр, позволяющий выбрать функцию внутри репозитория ядра.
    • Оба варианта могут появляться вместе и только в таком порядке: сначала @revision, затем :kernel_name.
    • Мы намеренно допускаем префикс “|” в начале строки (например, “flash|…”), поскольку код удаляет его перед загрузкой; символ ’|’ не исключен в классах символов здесь.

    Примеры, которые соответствуют: “org/model” “org/model@main” “org/model:custom_kernel” “org/model@v1.2.3:custom_kernel”

  • experts_implementation (str, необязательный) — Реализация экспертов, используемая в модели (если применимо). Может быть одной из следующих:
    • "eager" (последовательная реализация умножения матриц экспертов).
    • "batched_mm" (используя torch.bmm).
    • "grouped_mm" (используя torch.nn.functional.grouped_mm).

    По умолчанию, если модель это поддерживает, будет использоваться "grouped_mm". В противном случае по умолчанию используется ручная реализация "eager".

Параметры для инференса больших моделей

  • dtype (str или torch.dtype, необязательный, по умолчанию "auto") — Переопределяет параметр torch_dtype и загружает модель в указанном dtype. Доступные варианты:

    1. torch.float16 или torch.bfloat16 или torch.float: загрузка в указанном dtype, игнорируя config.dtype модели, если он существует. Если не указано

      • модель будет загружена в torch.float (fp32).

    2. "auto" — будет предпринята попытка использовать запись dtype или torch_dtype из файла config.json модели. Если такая запись не найдена, то следующим шагом проверяется dtype первого веса в контрольной точке, имеющего тип с плавающей точкой, и он используется в качестве dtype. В результате модель будет загружена с тем dtype, в котором она была сохранена по завершении обучения. Это значение нельзя использовать как индикатор того, как именно обучалась модель, поскольку она могла обучаться в одном из полупrecizных dtypes, но сохраняться в fp32.

    3. Строка, являющаяся допустимым torch.dtype. Например, “float32” загружает модель в torch.float32, “float16” — в torch.float16 и т. д.

    Для некоторых моделей неизвестен dtype, в котором они обучались. Вы можете попробовать проверить статью о модели или связаться с её авторами и попросить их добавить эту информацию в карточку модели и вставить запись dtype или torch_dtype в config.json на хабе.

  • device_map (str или dict[str, Union[int, str, torch.device]] или int или torch.device, необязательный) — Карта, указывающая, на какое устройство следует поместить каждый подмодуль. Не обязательно указывать её для каждого параметра или буфера: как только имя модуля указано в карте, все его подмодули будут отправлены на то же устройство. Если передать только устройство (e.g., "cpu", "cuda:1", "mps", или порядковый номер GPU, например 1) ), на котором будет размещена модель, карта устройств отобразит всю модель на этом устройстве. Передача device_map = 0 означает, что вся модель будет размещена на GPU 0.

    Чтобы Accelerate автоматически вычислял наиболее оптимизированный device_map, установите device_map="auto". Подробнее о каждом варианте см. в разделе проектирование карты устройств.

  • max_memory (Dict, необязательный) — Словарь с идентификаторами устройств и максимальным объемом памяти при использовании device_map. Если не задан, по умолчанию используется максимальная доступная память для каждого GPU и доступная оперативная память CPU.
  • distributed_config (DistributedConfig, необязательный) — Конфигурация для нативной распределённой загрузки с использованием tensor parallelism или FSDP2. Передайте DistributedConfig(tp_size=N), чтобы использовать предопределённый план tensor parallelism модели, DistributedConfig(tp_plan=...), чтобы указать план tensor parallelism, или DistributedConfig(fsdp_size=N) для FSDP2. Требует torchrun и инициализированную группу процессов, если tp_size > 1 или fsdp_size > 1. Взаимоисключается с device_map.
  • device_mesh (torch.distributed.DeviceMesh, необязательный) — Сетка устройств torch. Если не задана, по умолчанию используется world size. В настоящее время используется только для tensor parallel. Если задана, при размерности больше 1 она должна содержать измерение с именем "tp"; это измерение будет использоваться для tensor parallelism
  • offload_folder (str или os.PathLike, необязательный) — Папка, в которую будут выгружаться веса, если device_map содержит значение "disk".
  • offload_buffers (bool, необязательный) — Определяет, следует ли выгружать буферы с параметрами модели.
  • quantization_config (Union[QuantizationConfigMixin,Dict], необязательный) — Словарь параметров конфигурации или объект QuantizationConfigMixin для квантования (например, bitsandbytes, gptq).
  • subfolder (str, необязательный, по умолчанию "") — Если нужные файлы находятся в подпапке репозитория модели на huggingface.co, укажите здесь имя папки.
  • variant (str, необязательный) — Если указано, загружает веса из файла с именем variant, например pytorch_model..bin.
  • use_safetensors (bool, необязательный, по умолчанию None) — Использовать ли контрольные точки safetensors. По умолчанию None. Если значение не указано и safetensors не установлен, параметр будет установлен в False.
  • weights_only (bool, необязательный, по умолчанию True) — Определяет, следует ли ограничивать разупаковщик загрузкой только тензоров, примитивных типов, словарей и любых типов, добавленных через torch.serialization.add_safe_globals(). Если установлено в False, можно загрузить веса подклассов тензоров-обёрток.
  • disable_mmap (bool, необязательный) — Определяет, следует ли отключать отображение в память (memory mapping) при загрузке контрольных точек safetensors. Если значение равно None (по умолчанию), режим определяется автоматически: True устанавливается, если контрольная точка находится на файловой системе FUSE hf-mount (используется в HF Spaces/Endpoints), где комбинация mmap и параллельных page-faults может привести к взаимной блокировке (deadlock). Если значение равно True, файлы полностью загружаются в память и обрабатываются с помощью safetensors.torch.load. Если значение равно False, всегда используется загрузчик с отображением в память по умолчанию.
  • fusion_config (dict[str, bool | dict[str, Any]], необязательный) — Необязательная конфигурация слияния, применяемая до создания экземпляра модели. Каждый ключ включает семейство слияний, а его значение может быть True для включения данного слияния с параметрами по умолчанию или словарем параметров, специфичных для семейства. Например, {"patch_embeddings": True} включает слияние встраиваний патчей. Этот параметр следует использовать только для оптимизации вывода, так как он может незначительно изменить результаты. Если параметр опущен, from_pretrained() обращается к config.fusion_config, если он доступен. Дополнительные сведения см. в руководстве по соответствию слияний в docs/source/en/fusion_mapping.md.
  • key_mapping (`dict[str, str], необязательный) — Возможное сопоставление имён весов, если используется модель с Hub, совместимая с архитектурой Transformers, но не преобразованная в соответствии с ней.
  • kwargs (остаточный словарь именованных аргументов, необязательный) — Может использоваться для обновления объекта конфигурации (после его загрузки) и инициализации модели (например, output_attentions=True). Поведение зависит от того, предоставляется ли config явно или загружается автоматически:
    • Если конфигурация передана с помощью config, **kwargs будут непосредственно переданы в метод __init__ базовой модели (мы предполагаем, что все необходимые обновления конфигурации уже были выполнены)
    • Если конфигурация не предоставлена, kwargs сначала передаются в функцию инициализации класса конфигурации (from_pretrained()). Каждое ключевое значение kwargs, соответствующее атрибуту конфигурации, используется для переопределения этого атрибута переданным значением из kwargs. Оставшиеся ключи, не соответствующие ни одному атрибуту конфигурации, передаются в функцию __init__ базовой модели.

Создайте предобученную модель PyTorch на основе конфигурации предобученной модели.

По умолчанию модель переводится в режим оценки с помощью model.eval() (модули Dropout отключаются). Для обучения модели сначала необходимо вернуть её в режим обучения с помощью model.train().

The warning Weights from XXX not initialized from pretrained model means that the weights of XXX do not come pretrained with the rest of the model. It is up to you to train those weights with a downstream fine-tuning task.

Предупреждение Weights from XXX not used in YYY означает, что слой XXX не используется в YYY, поэтому соответствующие веса отбрасываются.

Активируйте специальный режим “offline-mode”, чтобы использовать этот метод в среде с файрволом.

Примеры:

>>> from transformers import BertConfig, BertModel

>>> # Download model and configuration from huggingface.co and cache.
>>> model = BertModel.from_pretrained("google-bert/bert-base-uncased")
>>> # Model was saved using *save_pretrained('./test/saved_model/')* (for example purposes, not runnable).
>>> model = BertModel.from_pretrained("./test/saved_model/")
>>> # Update configuration during loading.
>>> model = BertModel.from_pretrained("google-bert/bert-base-uncased", output_attentions=True)
>>> assert model.config.output_attentions == True

get_compiled_call

< >

( compile_config: transformers.generation.configuration_utils.CompileConfig | None )

Возвращает версию self.__call__, скомпилированную с помощью torch.compile. Это полезно для динамического выбора между нескомпилированной и скомпилированной версией forward во время инференса, особенно для переключения между prefill (где мы не хотим использовать скомпилированную версию, чтобы избежать пересчёта графа с новыми формами) и итеративным декодированием (где нам нужны ускорения скомпилированной версии со статическими формами).

get_decoder

< >

( )

Попытка поиска модуля decoder в режиме best-effort.

Порядок попыток (покрывает ~85 % текущих случаев использования):

  1. self.decoder/self.language_model/self.text_model
  2. self.base_model (многие обёртки хранят декодер здесь)
  3. self.base_model.get_decoder() (вложенные обёртки)
  4. fallback: raise для нескольких экзотических моделей, которым требуется индивидуальное правило

get_encoder

< >

( modality: str | None = None )

Поиск модуля encoder в режиме best-effort. Если указан аргумент modality, функция ищет специфичный для модальности энкодер в мультимодальных моделях (например, “image_encoder”). По умолчанию функция возвращает текстовый энкодер модели, если он есть, иначе возвращает self.

Возможные значения modality: “image”, “video” и “audio”.

get_expanded_tied_weights_keys

< >

( all_submodels: bool = False )

Возвращает расширенные ключи связанных весов (в случае, если они содержат модули или регулярные выражения) только для текущей модели, либо рекурсивно для всех подмоделей, если all_submodels=True (то есть значения конфигурации будут повторно проверены для всех подмоделей).

Для подавляющего большинства моделей достаточно связать эмбеддинги, поэтому у модели есть внутреннее свойство _tied_weights_keys = {"lm_head.weight": "model.embed_tokens.weight"}. В этом случае отображение уже «развёрнуто», то есть содержит полные параметры, и эта функция просто вернёт копию свойства. Для более сложных схем, например для DFineForObjectDetection, у нас есть следующее атрибут

_tied_weights_keys = {
    r"bbox_embed.(?![0])\d+": "bbox_embed.0",
    r"class_embed.(?![0])\d+": "class_embed.0",
    "model.decoder.class_embed": "class_embed",
    "model.decoder.bbox_embed": "bbox_embed",
}
In this case, the function looks up all the model's parameters and buffers, and matches all the params,

возвращает следующее:

{
    'bbox_embed.1.layers.0.bias': 'bbox_embed.0.layers.0.bias',
    'bbox_embed.1.layers.0.weight': 'bbox_embed.0.layers.0.weight',
    'bbox_embed.1.layers.1.bias': 'bbox_embed.0.layers.1.bias',
    'bbox_embed.1.layers.1.weight': 'bbox_embed.0.layers.1.weight',
    'bbox_embed.1.layers.2.bias': 'bbox_embed.0.layers.2.bias',
    'bbox_embed.1.layers.2.weight': 'bbox_embed.0.layers.2.weight',
    'bbox_embed.2.layers.0.bias': 'bbox_embed.0.layers.0.bias',
    'bbox_embed.2.layers.0.weight': 'bbox_embed.0.layers.0.weight',
    ...
    'class_embed.1.bias': 'class_embed.0.bias',
    'class_embed.1.weight': 'class_embed.0.weight',
    'class_embed.2.bias': 'class_embed.0.bias',
    'class_embed.2.weight': 'class_embed.0.weight',
    ...
    'model.decoder.class_embed.0.bias': 'class_embed.0.bias',
    'model.decoder.class_embed.0.weight': 'class_embed.0.weight',
    'model.decoder.class_embed.1.bias': 'class_embed.0.bias',
    'model.decoder.class_embed.1.weight': 'class_embed.0.weight',
    ...
    'model.decoder.bbox_embed.0.layers.0.bias': 'bbox_embed.0.layers.0.bias',
    'model.decoder.bbox_embed.0.layers.0.weight': 'bbox_embed.0.layers.0.weight',
    'model.decoder.bbox_embed.0.layers.1.bias': 'bbox_embed.0.layers.1.bias',
    'model.decoder.bbox_embed.0.layers.1.weight': 'bbox_embed.0.layers.1.weight',
    ...
}
i.e. all the parameters matching the regex and modules patterns in `_tied_weights_keys`

get_experts_implementation

< >

( )

Возвращает реализацию экспертов для этой модели и её подмоделей в виде dict в формате, принимаемом set_experts_implementation ("" для этой модели и одна запись для каждого sub_config). Это обратная операция для set_experts_implementation, например, для создания снимка текущей реализации и последующего её восстановления.

get_memory_footprint

< >

( return_buffers = True )

Параметры

  • return_buffers (bool, необязательный, по умолчанию True) — Определяет, следует ли учитывать размер тензоров буферов при вычислении объёма занимаемой памяти. Буферы — это тензоры, для которых не требуется вычисление градиентов и которые не зарегистрированы как параметры. Например, среднее значение и стандартное отклонение в слоях batch norm. См.: https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2

Получить объём памяти, занимаемый моделью. Этот метод возвращает объём памяти текущей модели в байтах. Полезно для бенчмаркинга объёма памяти текущей модели и проектирования тестов. Решение вдохновлено обсуждениями в PyTorch: https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2

get_parameter_or_buffer

< >

( target: str )

Возвращает параметр или буфер, указанный в target, если он существует, иначе выбрасывает ошибку. Эта функция объединяет get_parameter() и get_buffer() в одну удобную функцию. Если целевой объект является атрибутом _extra_state, будет возвращено дополнительное состояние, предоставленное модулем. Обратите внимание, что это работает только в том случае, если target является листом модели.

gradient_checkpointing_disable

< >

( )

Устаревший псевдоним для activation_checkpointing_disable(), будет удалён в v6.

gradient_checkpointing_enable

< >

( gradient_checkpointing_kwargs = None**kwargs )

Устаревший псевдоним для activation_checkpointing_enable(), будет удалён в v6.

init_weights

< >

( )

Инициализируйте и свяжите веса при необходимости. Если вы используете собственную PreTrainedModel, вам нужно реализовать логику инициализации в _init_weights.

initialize_weights

< >

( )

Это эквивалентно вызову self.apply(self._initialize_weights), но корректно обрабатывает составные модели. Эта функция динамически вызывает правильную функцию init_weights для модулей по мере продвижения по графу модулей в процессе рекурсии. Она может обрабатывать произвольное количество подмоделей. Без неё каждая составная модель была бы вынуждена выполнять вторую рекурсию по всем подмоделям явно во внешней функции _init_weights, что является крайне подверженным ошибкам и неэффективным подходом.

is_custom_code

< >

( )

Возвращает, является ли текущая модель кастомным кодом, то есть загруженным с хаба или определённым в пользовательском модуле/сессии.

is_remote_code

< >

( )

Возвращает, является ли текущая модель кастомным кодом, то есть кодом, загруженным с хаба, или классом, который мы только что зарегистрировали с помощью register_for_auto_class.

mark_tied_weights_as_initialized

< >

( loading_info )

Добавляет флаг _is_hf_initialized к параметрам, которые будут связаны, чтобы избежать их инициализации позже, поскольку они всё равно будут связаны (перезаписаны). Это очень важно, так как большинство эмбеддингов связаны, и это огромные параметры (размер словаря часто составляет 256k), поэтому запуск инициализации для них очень затратен.

named_non_persistent_buffers

< >

( recurse: bool = Trueremove_duplicate: bool = True )

Аналогично named_buffers, но возвращает только непостоянные буферы. Это удобно, так как не всегда очевидно, являются ли буферы постоянными

post_init

< >

( )

Метод, выполняемый в конце инициализации каждой модели Transformers, для запуска кода, требующего корректно инициализированных модулей модели (например, инициализации весов). Он также используется для получения всех корректных статических свойств (parallelism plans, tied_weights_keys, _keep_in_fp32_modules и т. д.) в случае составных моделей (то есть верхнеуровневая модель должна знать о свойствах своих дочерних элементов).

register_for_auto_class

< >

( auto_class = 'AutoModel' )

Параметры

  • auto_class (str или type, необязательный, по умолчанию "AutoModel") — Класс Auto, с которым будет зарегистрирована эта новая модель.

Зарегистрируйте этот класс с указанным автоклассом. Это следует использовать только для пользовательских моделей, так как модели из библиотеки уже сопоставлены с автоклассами.

resize_token_embeddings

< >

( new_num_tokens: int | None = Nonepad_to_multiple_of: int | None = Nonemean_resizing: bool = True ) → torch.nn.Embedding

Параметры

  • new_num_tokens (int, необязательный) — Новое количество токенов в матрице эмбеддингов. Увеличение размера добавит новые инициализированные векторы в конец. Уменьшение размера удалит векторы с конца. Если значение не указано или равно None, возвращается указатель на входной модуль torch.nn.Embedding модели без каких-либо изменений.
  • pad_to_multiple_of (int, необязательный) — Если задано, матрица эмбеддингов будет дополнена нулями до кратного указанного значения. Если new_num_tokens установлено в None , эмбеддинг будет дополнен до кратного значения pad_to_multiple_of.

    Это особенно полезно для использования Tensor Cores на аппаратных средствах NVIDIA с вычислительной мощностью >= 7.5 (Volta) или на TPU, где длина последовательности должна быть кратна 128. Более подробную информацию об этом, а также помощь в выборе правильного значения для изменения размера, см. в этом руководстве: https://docs.nvidia.com/deeplearning/performance/dl-performance-matrix-multiplication/index.html#requirements-tc

  • mean_resizing (bool) — Следует ли инициализировать добавленные эмбеддинги из многомерного нормального распределения, имеющего среднее и ковариацию старых эмбеддингов, или инициализировать их нормальным распределением со средним, равным нулю, и стандартным отклонением, равным config.initializer_range.

    Установка mean_resizing в True полезна при увеличении размера эмбеддингов каузальных языковых моделей, где вероятности сгенерированных токенов не будут затронуты добавленными эмбеддингами, поскольку инициализация новых эмбеддингов средним значением старых эмбеддингов уменьшит kl-расхождение между вероятностями следующего токена до и после добавления новых эмбеддингов. Подробнее об этом в статье: https://nlp.stanford.edu/~johnhew/vocab-expansion.html

Возвращает

torch.nn.Embedding

Указатель на модуль эмбеддингов входных токенов модели.

Изменяет размер матрицы эмбеддингов входных токенов модели, если new_num_tokens != config.vocab_size.

После этого привязывает веса эмбеддингов, если класс модели имеет метод tie_weights().

save_pretrained

< >

( save_directory: str | os.PathLikeis_main_process: bool = Truestate_dict: dict | None = Nonepush_to_hub: bool = Falsemax_shard_size: int | str = '50GB'variant: str | None = Nonetoken: str | bool | None = Nonesave_peft_format: bool = Truesave_original_format: bool = Truedistributed_checkpoint: bool = False**kwargs )

Параметры

  • save_directory (str или os.PathLike) — Каталог для сохранения. Будет создан, если не существует.
  • is_main_process (bool, необязательный, по умолчанию True) — Указывает, является ли процесс, вызывающий эту функцию, основным. Полезно при распределённом обучении, например на TPU, когда необходимо вызвать эту функцию во всех процессах. В этом случае установите is_main_process=True только в основном процессе, чтобы избежать гонок.
  • state_dict (вложенный словарь torch.Tensor) — Словарь состояния модели, который нужно сохранить. По умолчанию используется self.state_dict(), но этот параметр позволяет сохранять только части модели или применять особые меры предосторожности при восстановлении словаря состояния модели (например, при использовании параллелизма моделей).
  • push_to_hub (bool, необязательный, по умолчанию False) — Указывает, следует ли после сохранения отправить вашу модель в Hugging Face model hub. С помощью repo_id можно указать репозиторий, в который нужно отправить модель (по умолчанию используется имя save_directory в вашем пространстве имён).
  • max_shard_size (int или str, необязательный, по умолчанию "50GB") — Максимальный размер чекпоинта перед его разбиением на части. Каждая часть чекпоинта будет иметь размер, меньший этого значения. Если значение указано в виде строки, оно должно состоять из цифр и единицы измерения (например, "5MB").

    Если вес модели превышает max_shard_size, он будет размещен в отдельном фрагменте контрольной точки, размер которого превысит max_shard_size.

  • variant (str, необязательный) — Если указано, веса сохраняются в формате model..safetensors.
  • token (str или bool, необязательный) — Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если указано True или параметр не задан, будет использован токен, сгенерированный при выполнении hf auth login (хранится в ~/.huggingface).
  • save_peft_format (bool, необязательный, по умолчанию True) — Для обратной совместимости с библиотекой PEFT, если веса адаптеров присоединены к модели, все ключи словаря состояния адаптеров должны быть дополнены префиксом base_model.model. Опытные пользователи могут отключить это поведение, установив save_peft_format в False.
  • save_original_format (bool, необязательный, по умолчанию True) — Для обратной совместимости с предыдущими версиями transformers вы можете сохранить контрольную точку с обратным отображением. Обратное отображение должно существовать, даже если модель была загружена из контрольной точки None legacy.
  • distributed_checkpoint (bool, необязательный, по умолчанию False) — При сохранении модели, разбитой на шарды FSDP или TP, записывает safetensors с использованием распределенного чекпоинтинга (DCP), а не сначала собирает веса на CPU. Этот метод должен вызываться на каждом ранке. Если False, веса сначала собираются на CPU на ранке 0 с помощью gather_full_state_dict перед записью. Параметр предназначен только для сохранения и возобновления обучения; установите False, если вам нужны все возможности save_pretrained. При push_to_hub=True ранк 0 консолидирует чекпоинт в подкаталоге consolidated/ и загружает этот каталог. Требуется torch>=2.7.
  • kwargs (dict[str, Any], необязательный) — Дополнительные именованные аргументы, передаваемые в метод push_to_hub().

Сохраните модель и файл её конфигурации в каталог, чтобы её можно было загрузить снова с помощью метода класса from_pretrained().

set_attn_implementation

< >

( attn_implementation: str | dictallow_all_kernels: bool = False )

Параметры

  • attn_implementation (str or dict) — Реализация механизма внимания, которую следует установить для этой модели. Она может быть str, в этом случае значение будет передано всем подмоделям, если это применимо, или dict, где ключами являются имена sub_configs, в этом случае каждая подмодель передаст соответствующее значение (себе и всем вложенным в неё подмоделям). Само значение может быть dict в том же формате, чтобы указать sub_configs для данной подмодели (как при инициализации конфигурации со вложенным словарём attn_implementation).
  • allow_all_kernels (bool, optional) — Загружать ли ядра из непроверенных репозиториев hub, если attn_implementation является пользовательским ядром, не входящим в репозиторий hub kernels-community.

Установите требуемое значение attn_implementation для этой модели.

set_decoder

< >

( decoder )

Симметричный setter. Повторяет логику поиска, используемую в get_decoder.

set_encoder

< >

( encodermodality: str | None = None )

Симметричный setter. Повторяет логику поиска, используемую в get_encoder.

set_experts_implementation

< >

( experts_implementation: str | dict )

Параметры

  • experts_implementation (str or dict) — Реализация экспертов, которую следует установить для этой модели. Это может быть str, в этом случае значение будет передано всем подмоделям, если это применимо, или dict, где ключами являются имена sub_configs, в этом случае каждая подмодель получит соответствующее значение.

Установите требуемое значение experts_implementation для этой модели.

set_use_kernels

< >

( use_kernelskernel_config: transformers.utils.kernel_config.KernelConfig | None = Nonemode: Mode | None = None )

Параметры

  • use_kernels (bool) — Использовать ли библиотеку kernels для применения ядерных операций к некоторым слоям модели.
  • kernel_config (KernelConfig, необязательный) — Конфигурация ядра, используемая для кернелизации модели. Если None, будет использоваться сопоставление ядер по умолчанию.
  • mode (Mode, необязательный) — Режим, который должен применяться во время kernelize. Необязательный параметр, по умолчанию устанавливается в режим обучения или вывода в зависимости от внутреннего флага training.

Определяет, следует ли использовать библиотеку kernels для ядровой обработки некоторых слоёв модели.

tie_weights

< >

( missing_keys: set[str] | None = Nonerecompute_mapping: bool = True )

Свяжите веса модели. Если recompute_mapping=False (значение по умолчанию при внутреннем вызове), будет использоваться атрибут model.all_tied_weights_keys, содержащий отображение {target: source} для связанных параметров. Если recompute_mapping=True, будет повторно проверяться все внутренние подмодели и их конфигурация, чтобы определить параметры, которые необходимо связать. Это значение по умолчанию, когда model.tie_weights() вызывается самостоятельно, вне __init__ и from_pretrained, на случай, если значения конфигурации были изменены где-либо.

Обратите внимание, что во время from_pretrained связывание является симметричным: если в маппинге указано «target -> source», но source отсутствует в чекпоинте, а target присутствует, мы меняем source и target местами, чтобы всё равно связать всё с параметром, который действительно существует.

до

( *args**kwargs )

Мок-значение для пути с точками (например, torch.float32): цепочки доступа к атрибутам и вызовы работают как пропускные декораторы, repr возвращает путь с точками, а использование в качестве базового класса подставляет обычный базовый класс type (PEP 560 __mro_entries__), благодаря чему реальные дочерние классы сохраняют обычный метакласс, а inspect.signature читает их реальный __init__, а не мок-объект.

warn_if_padding_and_no_attention_mask

< >

( input_idsattention_mask )

Показывает одноразовое предупреждение, если input_ids, по-видимому, содержат padding, а attention mask не была передана.

Пользовательские модели также должны включать _supports_assign_param_buffer, который определяет, можно ли применить superfast init к данной модели. Признак того, что вашей модели это необходимо, — сбой test_save_and_load_from_pretrained. В этом случае установите значение False.

ModuleUtilsMixin

класс transformers.modeling_utils.ModuleUtilsMixin

< >

( )

Несколько утилит для torch.nn.Modules, предназначенных для использования в качестве миксина.

num_parameters

< >

( only_trainable: bool = Falseexclude_embeddings: bool = False ) → int

Параметры

  • only_trainable (bool, необязательный, по умолчанию False) — Возвращать ли только количество обучаемых параметров
  • exclude_embeddings (bool, необязательный, по умолчанию False) — Возвращать ли только количество параметров, не являющихся эмбеддингами

Возвращает

int

Количество параметров.

Получить количество (опционально, обучаемых или не являющихся эмбеддингами) параметров в модуле.

Загрузка в Hub

класс transformers.utils.PushToHubMixin

< >

( )

Миксин, содержащий функциональность для загрузки модели или токенизатора на хаб.

push_to_hub

< >

( repo_id: strcommit_message: str | None = Nonecommit_description: str | None = Noneprivate: bool | None = Nonetoken: bool | str | None = Nonerevision: str | None = Nonecreate_pr: bool = Falsemax_shard_size: int | str | None = '50GB'tags: list[str] | None = None )

Параметры

  • repo_id (str) — Имя репозитория, в который вы хотите отправить {object}. При отправке в конкретную организацию оно должно содержать имя вашей организации.
  • commit_message (str, необязательный) — Сообщение для коммита при отправке. По умолчанию — "Upload {object}".
  • commit_description (str, необязательный) — Описание коммита, который будет создан
  • private (bool, optional) — Определяет, следует ли сделать репозиторий приватным. Если None (по умолчанию), репозиторий будет публичным, если только по умолчанию для организации не задан приватный режим. Это значение игнорируется, если репозиторий уже существует.
  • token (bool или str, необязательный) — Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если True (по умолчанию), будет использован токен, сгенерированный при выполнении hf auth login (хранится в ~/.huggingface).
  • revision (str, необязательный) — Ветка, в которую будут загружены файлы.
  • create_pr (bool, необязательный, по умолчанию False) — Создавать ли PR с загруженными файлами или коммитить изменения напрямую.
  • max_shard_size (int или str, необязательный, по умолчанию "50GB") — Применимо только к моделям. Максимальный размер контрольной точки перед её разбиением на части. Каждая из частей будет иметь размер, меньший этого значения. Если значение указано в виде строки, оно должно состоять из цифр, за которыми следует единица измерения (например, "5MB").
  • tags (list[str], необязательный) — Список тегов для загрузки на Hub.

Загрузите {object_files} в 🤗 Model Hub.

Примеры:

from transformers import {object_class}

{object} = {object_class}.from_pretrained("google-bert/bert-base-cased")

# Push the {object} to your namespace with the name "my-finetuned-bert".
{object}.push_to_hub("my-finetuned-bert")

# Push the {object} to an organization with the name "my-finetuned-bert".
{object}.push_to_hub("huggingface/my-finetuned-bert")
Update on GitHub

←Логирование Генерация текста→