Transformers 文档

特征提取器

Transformers

加入 Hugging Face 社区

并获取增强的文档体验

协作模型、数据集和空间

使用加速推理更快地运行示例

在文档主题之间切换

开始使用

特征提取器

特征提取器负责为音频或视觉模型准备输入特征。这包括从序列中提取特征，例如，预处理音频文件以生成 Log-Mel 谱图特征，从图像中提取特征，例如，裁剪图像文件，以及填充、规范化和转换为 NumPy、PyTorch 和 TensorFlow 张量。

FeatureExtractionMixin

class transformers.FeatureExtractionMixin

< source >

( **kwargs )

这是一个用于提供序列和图像特征提取器的保存/加载功能的特征提取 mixin。

from_pretrained

< source >

( pretrained_model_name_or_path: Union cache_dir: Union = None force_download: bool = False local_files_only: bool = False token: Union = None revision: str = 'main' **kwargs )

参数

pretrained_model_name_or_path (str 或 os.PathLike) — 这可以是：
- 一个字符串，即托管在 huggingface.co 上模型仓库中的预训练特征提取器的模型 ID。
- 包含使用 save_pretrained() 方法保存的特征提取器文件的目录的路径，例如，./my_model_directory/。
- 保存的特征提取器 JSON 文件的路径或 URL，例如，./my_model_directory/preprocessor_config.json。
cache_dir (str 或 os.PathLike, 可选) — 用于缓存下载的预训练模型特征提取器的目录路径，如果不想使用标准缓存。
force_download (bool, 可选，默认值为 False) — 是否强制（重新）下载特征提取器文件并覆盖现有的缓存版本。 resume_download — 已弃用且被忽略。所有下载现在默认情况下尽可能恢复。将在 Transformers 的 v5 版本中删除。
proxies (Dict[str, str], 可选) — 按协议或端点使用的代理服务器字典，例如，{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. 代理在每个请求中使用。
token (str 或 bool, 可选) — 用作远程文件 HTTP 身份验证标头的令牌。如果为 True，或未指定，则将使用运行 huggingface-cli login 时生成的令牌（存储在 ~/.huggingface 中）。
revision (str, 可选，默认值为 "main") — 要使用的特定模型版本。它可以是分支名称、标签名称或提交 ID，因为我们使用基于 git 的系统在 huggingface.co 上存储模型和其他工件，因此 revision 可以是 git 允许的任何标识符。

从特征提取器（例如，SequenceFeatureExtractor 的派生类）实例化 FeatureExtractionMixin 类型。

示例

# 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

< source >

( save_directory: Union push_to_hub: bool = False

参数

save_directory (str 或 os.PathLike) — 特征提取器 JSON 文件将保存到的目录（如果目录不存在则创建）。
push_to_hub (bool, 可选, 默认为 False) — 是否在保存模型后将其推送到 Hugging Face 模型中心。您可以使用 repo_id 指定要推送到哪个仓库（默认为您的命名空间中 save_directory 的名称）。
kwargs (Dict[str, Any], 可选) — 传递给 push_to_hub() 方法的额外关键字参数。

将特征提取器对象保存到 save_directory 目录中，以便可以使用 from_pretrained() 类方法重新加载它。

SequenceFeatureExtractor

class transformers.SequenceFeatureExtractor

< 源代码 >

( feature_size: int sampling_rate: int padding_value: float **kwargs )

参数

feature_size (int) — 提取的特征的特征维度。
sampling_rate (int) — 音频文件应以赫兹 (Hz) 表示的数字化采样率。
padding_value (float) — 用于填充填充值/向量的值。

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

填充

< 源代码 >

( processed_features: Union padding: Union = True max_length: Optional = None truncation: bool = False pad_to_multiple_of: Optional = None return_attention_mask: Optional = None return_tensors: Union = None )

参数

processed_features (BatchFeature, list of 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 收集函数中使用此方法。

除了 List[float] 之外，您还可以使用张量（NumPy 数组、PyTorch 张量或 TensorFlow 张量），请参阅上面的说明以了解返回值类型。
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, 可选) — 如果设置，将填充序列以使其成为所提供值的倍数。

这对于在具有 >= 7.5 (Volta) 计算能力的 NVIDIA 硬件上使用张量核心，或者在从序列长度是 128 的倍数中受益的 TPU 上使用非常有用。
return_attention_mask (bool, 可选) — 是否返回注意力掩码。如果保留默认值，将根据特定特征提取器的默认值返回注意力掩码。

什么是注意力掩码？
return_tensors (str 或 TensorType, 可选) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：
- 'tf': 返回 TensorFlow tf.constant 对象。
- 'pt': 返回 PyTorch torch.Tensor 对象。
- 'np': 返回 NumPy np.ndarray 对象。

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

填充侧（左/右）填充值在特征提取器级别定义（使用 self.padding_side、self.padding_value）。

如果传递的 processed_features 是 NumPy 数组、PyTorch 张量或 TensorFlow 张量的字典，除非您使用 return_tensors 提供不同的张量类型，否则结果将使用相同的类型。在 PyTorch 张量的情况下，您将丢失张量的特定设备。

BatchFeature

class transformers.BatchFeature

< 源代码 >

( data: Optional = None tensor_type: Union = None )

参数

data (dict, 可选) — 由调用/填充方法返回的列表/数组/张量的字典（“input_values”、“attention_mask”等）。
tensor_type (Union[None, str, TensorType], 可选) — 你可以在初始化时提供一个 tensor_type 来将 PyTorch/TensorFlow/Numpy 张量中的整数列表进行转换。

保存 pad() 和特征提取器特定的 __call__ 方法的输出。

此类派生自 Python 字典，可以作为字典使用。

convert_to_tensors

< 源代码 >

( tensor_type: Union = None )

参数

tensor_type (str 或 TensorType, 可选) — 要使用的张量类型。如果为 str，则应为枚举 TensorType 的值之一。如果为 None，则不进行任何修改。

将内部内容转换为张量。

to

< 源代码 >

( *args **kwargs ) → BatchFeature

参数

args (Tuple) — 将传递给张量的 to(...) 函数。
kwargs (Dict, 可选) — 将传递给张量的 to(...) 函数。

BatchFeature

修改后的相同实例。

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

ImageFeatureExtractionMixin

class transformers.ImageFeatureExtractionMixin

< 源代码 >

( )

包含用于准备图像特征的实用程序的混合。

center_crop

( image size ) → 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

< source >

( image )

参数

image (PIL.Image.Image) — 要转换的图像。

将 PIL.Image.Image 转换为 RGB 格式。

expand_dims

< source >

( image )

参数

image (PIL.Image.Image 或 np.ndarray 或 torch.Tensor) — 要扩展的图像。

将二维 image 扩展为三维。

flip_channel_order

< source >

( image )

参数

image (PIL.Image.Image 或 np.ndarray 或 torch.Tensor) — 要翻转颜色通道的图像。如果 np.ndarray 或 torch.Tensor，则通道维度应为第一位。

将 image 的通道顺序从 RGB 翻转为 BGR，反之亦然。请注意，如果它是 PIL 图像，这将触发将 image 转换为 NumPy 数组。

normalize

< source >

( image mean std rescale = False )

参数

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 图像，这将触发将其转换为 NumPy 数组。

rescale

< 源代码 >

( image: ndarray scale: Union )

按比例缩放 numpy 图像。

resize

< 源代码 >

( image size resample = None default_to_square = True max_size = None ) → image

参数

image (PIL.Image.Image 或 np.ndarray 或 torch.Tensor) — 要调整大小的图像。
size (int 或 Tuple[int, int]) — 用于调整图像大小的大小。如果 size 是一个序列，例如 (h, w)，则输出大小将与之匹配。

如果 size 是一个整数，并且 default_to_square 为 True，则图像将调整为 (size, size)。如果 size 是一个整数，并且 default_to_square 为 False，则图像的较小边将与该数字匹配。例如，如果高度 > 宽度，则图像将调整为 (size * 高度 / 宽度, size)。
resample (int, 可选, 默认为 PILImageResampling.BILINEAR) — 用于重采样的过滤器。
default_to_square (bool, 可选, 默认为 True) — 当 size 是单个整数时如何转换 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 时使用。

图像

调整大小后的 PIL.Image.Image。

调整 image 的大小。强制将输入转换为 PIL.Image。

旋转

< 源代码 >

( image angle resample = None expand = 0 center = None translate = None fillcolor = None ) → image

参数

image (PIL.Image.Image 或 np.ndarray 或 torch.Tensor) — 要旋转的图像。如果为 np.ndarray 或 torch.Tensor，将在旋转之前转换为 PIL.Image.Image。

图像

旋转后的 PIL.Image.Image。

返回 image 的旋转副本。此方法返回 image 的副本，以逆时针方向围绕其中心旋转给定的度数。

转换为 NumPy 数组

< 源代码 >

( image rescale = None channel_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 数组。可选地对其进行缩放并将通道维度设置为第一个维度。

转换为 PIL Image

< 源代码 >

( image rescale = None )

参数

image (PIL.Image.Image 或 numpy.ndarray 或 torch.Tensor) — 要转换为 PIL Image 格式的图像。
rescale (bool, 可选) — 是否应用缩放因子（使像素值介于 0 和 255 之间的整数）。如果图像类型为浮点类型，则默认为 True，否则为 False。

将 image 转换为 PIL Image。可选地对其进行缩放，并在需要时将通道维度放回最后一个轴。

< > 在 GitHub 上更新

←ExecuTorch 图像处理器→