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

特征提取器

特征提取器负责为音频模型准备输入特征。这包括从序列中提取特征，例如对音频文件进行预处理以生成 Log-Mel Spectrogram 特征，以及将其转换为 NumPy 和 PyTorch 张量。

FeatureExtractionMixin

class 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) — 可以是以下之一：
    • 一个字符串，即托管在 huggingface.co 上某个模型仓库中的预训练 feature_extractor 的 model id。
    • 指向一个目录的路径，该目录包含使用 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 的系统来存储模型和其他工件，因此它可以是分支名称、标签名称或提交 id，revision 可以是 git 允许的任何标识符。

从特征提取器实例化 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 模型库。您可以使用 repo_id 指定要推送到的仓库（默认使用您命名空间中 save_directory 的名称）。
  • kwargs (dict[str, Any]，可选) — 传递给 push_to_hub() 方法的额外关键字参数。

将 feature_extractor 对象保存到目录 save_directory，以便之后可以使用 from_pretrained() 类方法重新加载。

SequenceFeatureExtractor

class transformers.SequenceFeatureExtractor

< >

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

参数

  • feature_size (int) — 提取特征的维度。
  • sampling_rate (int) — 音频文件应被数字化时的采样率，以赫兹（Hz）为单位。
  • padding_value (float) — 用于填充填充值/向量的数值。

这是一个用于语音识别的通用特征提取类。

填充

< >

( 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 列表 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]]]) 因此，您可以在预处理阶段以及 PyTorch Dataloader 的 collate 函数中使用此方法。

    您可以使用张量（numpy 数组或 PyTorch 张量）代替 list[float]，有关返回类型，请参阅上方的说明。

  • 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, 可选) — 如果设置，将把序列填充为所提供值的倍数。

    这在启用 NVIDIA 硬件（计算能力 >= 7.5，即 Volta 架构）上的 Tensor Cores 使用时尤为有用，或者在 TPU 上使用时也特别有益，因为 TPU 在序列长度为 128 的倍数时性能更佳。

  • return_attention_mask (bool, 可选) — 是否返回注意力掩码。如果保持默认值，将根据特定 feature_extractor 的默认设置返回注意力掩码。

    什么是注意力掩码？

  • return_tensors (str 或 TensorType, 可选) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：
    • 'pt'：返回 PyTorch torch.Tensor 对象。
    • 'np'：返回 Numpy np.ndarray 对象。

将输入值 / 输入向量或一批输入值 / 输入向量填充至预定义长度或批次中的最大序列长度。

填充侧（left/right）的填充值在特征提取器级别定义（通过 self.padding_side、self.padding_value）

如果传入的 processed_features 是 numpy 数组或 PyTorch 张量的字典，则结果将使用相同的类型，除非你通过 return_tensors 指定了不同的张量类型。对于 PyTorch 张量，你将会丢失张量所在的特定设备信息。

BatchFeature

class 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。

将内部内容转换为张量。

注意： 不具有数组结构（例如字符串、字典、字符串列表）的值会被自动跳过，不会转换为张量。对于不规则数组（长度不同的数组列表），系统仍会尝试进行转换，但在转换过程中可能会引发错误。

到

< >

( *args**kwargs ) → BatchFeature

参数

  • args (Tuple) — 将传递给张量的 to(...) 函数。
  • kwargs (Dict, 可选) — 将传递给张量的 to(...) 函数。 若要启用异步数据传输，请在 kwargs 中设置 non_blocking 标志（默认为 False）。

返回值

BatchFeature

修改后的同一实例。

通过调用 v.to(*args, **kwargs) 将所有值发送到设备（仅限 PyTorch）。这应支持转换为不同的 dtypes，并将 BatchFeature 发送到不同的 device。

ImageFeatureExtractionMixin

class transformers.ImageFeatureExtractionMixin

< >

( )

包含用于准备图像特征的实用工具的方法混入类。

center_crop

< >

( imagesize ) → new_image

参数

  • image（PIL.Image.Image 或 np.ndarray 或形状为 (n_channels, height, width) 或 (height, width, n_channels) 的 torch.Tensor） — 要调整大小的图像。
  • 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 Image，这将触发将其转换为 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 图像，缩放会自动进行。

使用 mean 和 std 对 image 进行归一化。请注意，如果 image 是 PIL Image，这将触发将其转换为 NumPy 数组。

rescale

< >

( image: ndarrayscale: float | int )

按缩放比例调整 numpy 图像

调整大小

< >

( 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，则图像的较短边将匹配该数值。即，如果 height > width，则图像将被重新缩放为 (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. 之间的浮点数）。如果图像是 PIL Image 或整数数组/张量，则默认为 True，否则为 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 Image。如有需要，可选择对其进行重新缩放，并将通道维度移回最后一个轴。

Update on GitHub

←ExecuTorch 图像处理器→