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

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 允许的任何标识符。

    要测试您在 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 中任何作为特征提取器属性的键的值，将用于覆盖已加载的值。对于键不是特征提取器属性的键值对，其行为由 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 模型库。您可以使用 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 图像处理器→