Hugging Face's logo

Transformers documentation

Извлекатель признаков

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Извлекатель признаков

Функция-экстрактор отвечает за подготовку входных признаков для аудиомоделей. Это включает извлечение признаков из последовательностей, например, предобработку аудиофайлов для генерации признаков Log-Mel Spectrogram, а также преобразование в тензоры NumPy и PyTorch.

FeatureExtractionMixin

класс transformers.FeatureExtractionMixin

< >

( **kwargs )

Это миксин для извлечения признаков, используемый для предоставления функциональности сохранения/загрузки для последовательных и аудиопризнаковых экстракторов.

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLikecache_dir: str | os.PathLike | None = Noneforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'**kwargs )

Параметры

  • pretrained_model_name_or_path (str или os.PathLike) — Это может быть:
    • строка, model id предобученного feature_extractor, размещенного в репозитории модели на huggingface.co.
    • путь к каталогу, содержащему файл экстрактора признаков, сохранённый с помощью метода save_pretrained(), например, ./my_model_directory/.
    • путь к сохранённому JSON-файлу экстрактора признаков, например, ./my_model_directory/preprocessor_config.json.
  • cache_dir (str или os.PathLike, необязательный) — Путь к каталогу, в котором следует кэшировать загруженный предобученный экстрактор признаков модели, если стандартный кэш не используется.
  • force_download (bool, необязательный, по умолчанию False) — Следует ли принудительно (пере)скачивать файлы экстрактора признаков и заменять кэшированные версии, если они существуют.
  • proxies (dict[str, str], необязательный) — Словарь прокси-серверов, используемых по протоколу или конечной точке, например, {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Прокси применяются при каждом запросе.
  • 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>".

  • return_unused_kwargs (bool, необязательный, по умолчанию False) — Если False, функция возвращает только итоговый объект feature extractor. Если True, функция возвращает Tuple(feature_extractor, unused_kwargs), где unused_kwargs — это словарь, содержащий пары ключ/значение, ключи которых не являются атрибутами feature extractor, то есть та часть kwargs, которая не была использована для обновления feature_extractor и в остальном игнорируется.
  • kwargs (dict[str, Any], необязательный) — Значения в kwargs для любых ключей, являющихся атрибутами feature extractor, будут использоваться для переопределения загруженных значений. Поведение в отношении пар ключ/значение, ключи которых не являются атрибутами feature extractor, контролируется параметром return_unused_kwargs.

Создайте экземпляр типа FeatureExtractionMixin из экстрактора признаков, например производного класса SequenceFeatureExtractor.

Примеры:

# We can't instantiate directly the base class *FeatureExtractionMixin* nor *SequenceFeatureExtractor* so let's show the examples on a
# derived class: *Wav2Vec2FeatureExtractor*
feature_extractor = Wav2Vec2FeatureExtractor.from_pretrained(
    "facebook/wav2vec2-base-960h"
)  # Download feature_extraction_config from huggingface.co and cache.
feature_extractor = Wav2Vec2FeatureExtractor.from_pretrained(
    "./test/saved_model/"
)  # E.g. feature_extractor (or model) was saved using *save_pretrained('./test/saved_model/')*
feature_extractor = Wav2Vec2FeatureExtractor.from_pretrained("./test/saved_model/preprocessor_config.json")
feature_extractor = Wav2Vec2FeatureExtractor.from_pretrained(
    "facebook/wav2vec2-base-960h", return_attention_mask=False, foo=False
)
assert feature_extractor.return_attention_mask is False
feature_extractor, unused_kwargs = Wav2Vec2FeatureExtractor.from_pretrained(
    "facebook/wav2vec2-base-960h", return_attention_mask=False, foo=False, return_unused_kwargs=True
)
assert feature_extractor.return_attention_mask is False
assert unused_kwargs == {"foo": False}

save_pretrained

< >

( save_directory: str | os.PathLikepush_to_hub: bool = False**kwargs )

Параметры

  • save_directory (str или os.PathLike) — Каталог, в котором будет сохранён JSON-файл экстрактора признаков (будет создан, если не существует).
  • push_to_hub (bool, необязательный, по умолчанию False) — Указывает, следует ли после сохранения отправить вашу модель в Hugging Face model hub. С помощью repo_id можно указать репозиторий, в который нужно отправить модель (по умолчанию используется имя save_directory в вашем пространстве имён).
  • kwargs (dict[str, Any], необязательный) — Дополнительные именованные аргументы, передаваемые в метод push_to_hub().

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

SequenceFeatureExtractor

класс transformers.SequenceFeatureExtractor

< >

( feature_size: intsampling_rate: intpadding_value: float**kwargs )

Параметры

  • feature_size (int) — Размерность признаков извлечённых признаков.
  • sampling_rate (int) — Частота дискретизации, с которой аудиофайлы должны быть оцифрованы, выраженная в герцах (Гц).
  • padding_value (float) — Значение, используемое для заполнения позиций, отведённых под padding.

Это общий класс для извлечения признаков в задачах распознавания речи.

pad

< >

( processed_features: transformers.feature_extraction_utils.BatchFeature | list[transformers.feature_extraction_utils.BatchFeature] | dict[str, transformers.feature_extraction_utils.BatchFeature] | dict[str, list[transformers.feature_extraction_utils.BatchFeature]] | list[dict[str, transformers.feature_extraction_utils.BatchFeature]]padding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonetruncation: bool = Falsepad_to_multiple_of: int | None = Nonereturn_attention_mask: bool | None = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = None )

Параметры

  • processed_features (BatchFeature, список BatchFeature, dict[str, list[float]], dict[str, list[list[float]] или list[dict[str, list[float]]]) — Обработанные входные данные. Могут представлять один входной объект (BatchFeature или dict[str, list[float]]) или пакет входных значений/векторов (список BatchFeature, dict[str, list[list[float]]] или list[dict[str, list[float]]]) , поэтому этот метод можно использовать как на этапе предобработки, так и в функции collate для PyTorch Dataloader.

    Вместо list[float] можно использовать тензоры (массивы numpy или тензоры PyTorch), см. примечание выше о типе возвращаемого значения.

  • padding (bool, str или PaddingStrategy, необязательный, по умолчанию True) — Выберите стратегию дополнения возвращаемых последовательностей (с учётом стороны дополнения и индекса дополнения модели) из следующих вариантов:
    • True или 'longest': дополнить до самой длинной последовательности в батче (или не дополнять, если предоставлена только одна последовательность).
    • 'max_length': Дополнить до максимальной длины, указанной аргументом max_length, или до максимально допустимой длины входных данных для модели, если этот аргумент не указан.
    • False или 'do_not_pad' (по умолчанию): без дополнения нулями (т. е. может выводить батч с последовательностями разной длины).
  • max_length (int, необязательный) — Максимальная длина возвращаемого списка и, при необходимости, длина отступов (см. выше).
  • truncation (bool) — Включает усечение, чтобы обрезать входные последовательности длиннее max_length до max_length.
  • pad_to_multiple_of (int, необязательный) — Если задано, последовательность будет дополнена до кратного указанного значения.

    Это особенно полезно для использования Tensor Cores на аппаратных средствах NVIDIA с вычислительной способностью >= 7.5 (Volta) или на TPU, где производительность повышается при длине последовательности, кратной 128.

  • return_attention_mask (bool, необязательный) — Следует ли возвращать attention mask. Если значение не указано, будет возвращена attention mask в соответствии со значением по умолчанию для конкретного feature_extractor.

    Что такое маски внимания?

  • return_tensors (str или TensorType, необязательный) — Если задано, возвращает тензоры вместо списка целых чисел Python. Допустимые значения:
    • 'pt': возвращает объекты torch.Tensor PyTorch.
    • 'np': возвращает объекты Numpy np.ndarray.

Добавление заполнителей к входным значениям / векторам или к батчу входных значений / векторов до заданной длины или до максимальной длины последовательности в батче.

Сторона выравнивания (слева/справа) и значения выравнивания определяются на уровне экстрактора признаков (с помощью self.padding_side, self.padding_value)

Если переданные processed_features представляют собой словарь массивов numpy или тензоров PyTorch, результат будет использовать тот же тип, если только вы не укажете другой тип тензора с помощью return_tensors. В случае тензоров PyTorch, однако, вы потеряете информацию об устройстве, на котором они были созданы.

BatchFeature

класс transformers.BatchFeature

< >

( data: dict[str, typing.Any] | None = Nonetensor_type: None | str | transformers.utils.generic.TensorType = Noneskip_tensor_conversion: list[str] | set[str] | None = None )

Параметры

  • data (dict, необязательный) — Словарь списков/массивов/тензоров, возвращаемый методами call/pad (‘input_values’, ‘attention_mask’, и т. д.).
  • tensor_type (Union[None, str, TensorType], необязательный) — Здесь можно указать tensor_type, чтобы при инициализации преобразовать списки целых чисел в тензоры PyTorch/Numpy.
  • skip_tensor_conversion (list[str] или set[str], необязательный) — Список или множество ключей, которые НЕ следует преобразовывать в тензоры, даже если указан tensor_type.

Содержит результат методов pad() и специфичных для экстрактора признаков __call__.

Этот класс наследуется от словаря Python и может использоваться как словарь.

convert_to_tensors

< >

( tensor_type: str | transformers.utils.generic.TensorType | None = Noneskip_tensor_conversion: list[str] | set[str] | None = None )

Параметры

  • tensor_type (str или TensorType, необязательный) — Тип тензоров для использования. Если str, должно быть одним из значений перечисления TensorType. Если None, изменения не вносятся.
  • skip_tensor_conversion (list[str] или set[str], необязательный) — Список или множество ключей, которые НЕ следует преобразовывать в тензоры, даже если указан tensor_type.

Преобразуйте внутреннее содержимое в тензоры.

Note: Значения, не имеющие структуры, подобной массиву (например, строки, словари, списки строк), автоматически пропускаются и не преобразуются в тензоры. Для неровных массивов (списков массивов различной длины) преобразование всё же выполняется, хотя в процессе могут возникать ошибки.

до

< >

( *args**kwargs ) → BatchFeature

Параметры

  • args (Tuple) — Будет передано в функцию to(...) тензоров.
  • kwargs (Dict, необязательный) — Будет передан в функцию to(...) тензоров. Чтобы включить асинхронную передачу данных, установите флаг non_blocking в kwargs (по умолчанию False).

Возвращает

BatchFeature

Тот же самый экземпляр после модификации.

Отправьте все значения на устройство, вызвав v.to(*args, **kwargs) (только PyTorch). Это должно поддерживать приведение к различным dtypes и отправку BatchFeature на другое device.

ImageFeatureExtractionMixin

класс transformers.ImageFeatureExtractionMixin

< >

( )

Миксин, содержащий утилиты для подготовки признаков изображений.

center_crop

< >

( imagesize ) → new_image

Параметры

  • image (PIL.Image.Image или np.ndarray или torch.Tensor формы (n_channels, height, width) или (height, width, n_channels)) — Изображение, размер которого нужно изменить.
  • size (int или tuple[int, int]) — Размер, до которого нужно обрезать изображение.

Возвращает

new_image

Центрированный кроп PIL.Image.Image или np.ndarray или torch.Tensor со следующей формой: (n_channels, height, width).

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

convert_rgb

< >

( image )

Параметры

  • image (PIL.Image.Image) — Изображение для преобразования.

Преобразует PIL.Image.Image в формат RGB.

expand_dims

< >

( image )

Параметры

  • image (PIL.Image.Image или np.ndarray или torch.Tensor) — Изображение, которое нужно расширить.

Расширяет двумерное image до трёх измерений.

flip_channel_order

< >

( image )

Параметры

  • image (PIL.Image.Image или np.ndarray или torch.Tensor) — Изображение, каналы цвета которого нужно инвертировать. Если передано np.ndarray или torch.Tensor, размерность каналов должна идти первой.

Меняет порядок каналов в image с RGB на BGR или наоборот. Обратите внимание, что если image является изображением PIL, это вызовет его преобразование в массив NumPy.

normalize

< >

( imagemeanstdrescale = False )

Параметры

  • image (PIL.Image.Image или np.ndarray или torch.Tensor) — Изображение для нормализации.
  • mean (list[float] или np.ndarray или torch.Tensor) — Среднее значение (по каналам), используемое для нормализации.
  • std (list[float] или np.ndarray или torch.Tensor) — Стандартное отклонение (по каждому каналу), используемое для нормализации.
  • rescale (bool, необязательный, по умолчанию False) — Указывает, нужно ли масштабировать изображение в диапазон от 0 до 1. Если передано изображение в формате PIL, масштабирование выполняется автоматически.

Нормализует image с использованием mean и std. Обратите внимание, что это вызовет преобразование image в массив NumPy, если это изображение PIL.

rescale

< >

( image: ndarrayscale: float | int )

Масштабирование изображения numpy на заданный коэффициент

resize

< >

( imagesizeresample = Nonedefault_to_square = Truemax_size = None ) → image

Параметры

  • image (PIL.Image.Image или np.ndarray или torch.Tensor) — Изображение, размер которого нужно изменить.
  • size (int или tuple[int, int]) — Размер, используемый для изменения размера изображения. Если size является последовательностью вида (h, w), выходной размер будет соответствовать ей.

    Если size — это int, а default_to_square равно True, изображение будет изменено до размера (size, size). Если size — это int, а default_to_square равно False, меньшая сторона изображения будет приведена к этому значению. То есть, если высота > ширина, изображение будет масштабировано до (size * height / width, size).

  • resample (int, необязательный, по умолчанию PILImageResampling.BILINEAR) — Фильтр, используемый для ресемплинга.
  • default_to_square (bool, необязательный, по умолчанию True) — Способ преобразования size, если он задан одним целым числом. Если установлено значение True, size будет преобразован в квадрат (size,size). Если установлено значение False, будет воспроизведено поведение torchvision.transforms.Resize с поддержкой изменения размера только самой короткой стороны и необязательным параметром max_size.
  • max_size (int, необязательный, по умолчанию None) — Максимально допустимое значение для большей стороны изображения после изменения размера: если большая сторона изображения после изменения размера согласно size превышает max_size, изображение снова изменяется по размеру так, чтобы большая сторона была равна max_size. В результате size может быть переопределено, то есть меньшая сторона может оказаться короче size. Используется только если default_to_square равно False.

Возвращает

image

Изображение PIL.Image.Image с изменённым размером.

Изменяет размер image. Принудительно преобразует входные данные в PIL.Image.

rotate

< >

( imageangleresample = Noneexpand = 0center = Nonetranslate = Nonefillcolor = None ) → image

Параметры

  • image (PIL.Image.Image или np.ndarray или torch.Tensor) — Изображение для поворота. Если передано np.ndarray или torch.Tensor, оно будет преобразовано в PIL.Image.Image перед поворотом.

Возвращает

image

Повёрнутое изображение PIL.Image.Image.

Возвращает повёрнутую копию image. Этот метод возвращает копию image, повёрнутую на заданное количество градусов против часовой стрелки вокруг её центра.

to_numpy_array

< >

( imagerescale = Nonechannel_first = True )

Параметры

  • image (PIL.Image.Image или np.ndarray или torch.Tensor) — Изображение, которое нужно преобразовать в массив NumPy.
  • rescale (bool, необязательный) — Применять ли коэффициент масштабирования (чтобы значения пикселей стали числами с плавающей точкой в диапазоне от 0. до 1.). По умолчанию равно True, если изображение представлено как PIL Image или массив/тензор целых чисел, и False в противном случае.
  • channel_first (bool, необязательный, по умолчанию True) — Определяет, нужно ли переставлять измерения изображения, чтобы размерность канала шла первой.

Преобразует image в массив numpy. При необходимости выполняет масштабирование и перемещает размерность каналов на первое место.

to_pil_image

< >

( imagerescale = None )

Параметры

  • image (PIL.Image.Image или numpy.ndarray или torch.Tensor) — Изображение, которое нужно преобразовать в формат PIL Image.
  • rescale (bool, необязательный) — Применять ли коэффициент масштабирования (чтобы значения пикселей были целыми числами от 0 до 255). По умолчанию True, если тип изображения — с плавающей точкой, иначе False.

Преобразует image в изображение PIL. При необходимости выполняет масштабирование и возвращает размерность каналов в качестве последней оси.

Update on GitHub

←ExecuTorch Обработчик изображений→