# 特征提取器

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

## FeatureExtractionMixin[[transformers.FeatureExtractionMixin]]

#### transformers.FeatureExtractionMixin[[transformers.FeatureExtractionMixin]]

```python
transformers.FeatureExtractionMixin(**kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_utils.py#L266)

这是一个用于为顺序特征提取器和音频特征提取器提供保存/加载功能的特征提取混入类。

#### from_pretrained[[transformers.FeatureExtractionMixin.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | os.PathLike, cache_dir: str | os.PathLike | None = None, force_download: bool = False, local_files_only: bool = False, token: str | bool | None = None, revision: str = 'main', **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_utils.py#L286)

**参数：**

pretrained_model_name_or_path (`str` 或 `os.PathLike`) : 可以是以下之一： - 一个字符串，即托管在 huggingface.co 模型仓库中的预训练 feature_extractor 的 *model id*。 - 指向一个 *目录* 的路径，该目录包含使用 [save_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin.save_pretrained) 方法保存的 feature extractor 文件，例如 `./my_model_directory/`。 - 指向已保存的 feature extractor JSON *file* 的路径，例如 `./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](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin) 的特征提取器。

从特征提取器实例化 [FeatureExtractionMixin](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin) 的一种类型，*例如* [SequenceFeatureExtractor](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor) 的派生类。

示例：

```python
# 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[[transformers.FeatureExtractionMixin.save_pretrained]]

```python
save_pretrained(save_directory: str | os.PathLike, push_to_hub: bool = False, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_utils.py#L390)

**参数：**

save_directory (`str` 或 `os.PathLike`) : 用于保存特征提取器 JSON 文件的目录（如果该目录不存在，则会自动创建）。

push_to_hub (`bool`，*可选*，默认为 `False`)：是否在保存模型后将其推送到 Hugging Face 模型库。您可以通过 `repo_id` 指定要推送到的仓库（默认使用您命名空间中 `save_directory` 的名称）。

kwargs (`dict[str, Any]`，*可选*)：传递给 [push_to_hub()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) 方法的额外关键字参数。

将 feature_extractor 对象保存到目录 `save_directory`，以便之后可以使用 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.FeatureExtractionMixin.from_pretrained) 类方法重新加载。

## SequenceFeatureExtractor[[transformers.SequenceFeatureExtractor]]

#### transformers.SequenceFeatureExtractor[[transformers.SequenceFeatureExtractor]]

```python
transformers.SequenceFeatureExtractor(feature_size: int, sampling_rate: int, padding_value: float, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_sequence_utils.py#L28)

**参数：**

feature_size (`int`) : 提取特征的维度。

sampling_rate (`int`) : 音频文件应被数字化采样的采样率，以赫兹 (Hz) 为单位。

padding_value (`float`) : 用于填充填充值/向量的数值。

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

#### pad[[transformers.SequenceFeatureExtractor.pad]]

```python
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 = True, max_length: int | None = None, truncation: bool = False, pad_to_multiple_of: int | None = None, return_attention_mask: bool | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_sequence_utils.py#L51)

**参数：**

processed_features ([BatchFeature](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.BatchFeature)、[BatchFeature](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.BatchFeature) 列表、`dict[str, list[float]]`、`dict[str, list[list[float]]` 或 `list[dict[str, list[float]]]`)：处理后的输入。它可以表示单个输入（[BatchFeature](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.BatchFeature) 或 `dict[str, list[float]]`），也可以表示一批输入值/向量（[BatchFeature](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.BatchFeature) 列表、*dict[str, list[list[float]]]* 或 *list[dict[str, list[float]]]*），因此您可以在预处理阶段以及 PyTorch Dataloader 的 collate 函数中使用此方法。 您可以使用张量（numpy 数组或 PyTorch 张量）代替 `list[float]`，有关返回类型，请参阅上方的说明。

padding (`bool`、`str` 或 [PaddingStrategy](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.utils.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`, *optional*) : 如果设置，则将序列填充为所提供值的倍数。 这对于在计算能力 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 的使用特别有用，或者对于受益于序列长度为 128 的倍数的 TPU 也很有用。

return_attention_mask (`bool`，*可选*)：是否返回注意力掩码。如果保持默认值，则根据特定 feature_extractor 的默认设置返回注意力掩码。[什么是注意力掩码？](../glossary#attention-mask)

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.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[[transformers.BatchFeature]]

#### transformers.BatchFeature[[transformers.BatchFeature]]

```python
transformers.BatchFeature(data: dict[str, typing.Any] | None = None, tensor_type: None | str | transformers.utils.generic.TensorType = None, skip_tensor_conversion: list[str] | set[str] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_utils.py#L58)

**参数：**

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()](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor.pad) 和特征提取器特定的 `__call__` 方法的输出。

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

#### convert_to_tensors[[transformers.BatchFeature.convert_to_tensors]]

```python
convert_to_tensors(tensor_type: str | transformers.utils.generic.TensorType | None = None, skip_tensor_conversion: list[str] | set[str] | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_utils.py#L158)

**参数：**

tensor_type (`str` 或 [TensorType](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.TensorType)，*可选*) : 要使用的张量类型。如果为 `str`，则应为枚举 [TensorType](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.TensorType) 的某个值。如果为 `None`，则不进行任何修改。

skip_tensor_conversion (`list[str]` 或 `set[str]`，*可选*) : 即使指定了 `tensor_type`，也不应转换为张量的键的列表或集合。

将内部内容转换为张量。

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

#### 到[[transformers.BatchFeature.to]]

```python
to(*args, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/feature_extraction_utils.py#L215)

**参数：**

args (`Tuple`) : 将传递给张量的 `to(...)` 函数。

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

**返回：** [BatchFeature](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.BatchFeature)

修改后的同一实例。

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

## ImageFeatureExtractionMixin[[transformers.ImageFeatureExtractionMixin]]

#### transformers.ImageFeatureExtractionMixin[[transformers.ImageFeatureExtractionMixin]]

```python
transformers.ImageFeatureExtractionMixin()
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L649)

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

#### center_crop[[transformers.ImageFeatureExtractionMixin.center_crop]]

```python
center_crop(image, size)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L883)

**参数：**

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[[transformers.ImageFeatureExtractionMixin.convert_rgb]]

```python
convert_rgb(image)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L691)

**参数：**

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

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

#### expand_dims[[transformers.ImageFeatureExtractionMixin.expand_dims]]

```python
expand_dims(image)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L744)

**参数：**

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

将二维 `image` 扩展为三维。

#### flip_channel_order[[transformers.ImageFeatureExtractionMixin.flip_channel_order]]

```python
flip_channel_order(image)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L958)

**参数：**

image (`PIL.Image.Image` 或 `np.ndarray` 或 `torch.Tensor`)：要翻转其颜色通道的图像。如果为 `np.ndarray` 或 `torch.Tensor`，通道维度应位于最前面。

将 `image` 的通道顺序从 RGB 翻转为 BGR，或反之。请注意，如果 `image` 是 PIL Image，这将触发将其转换为 NumPy 数组。

#### normalize[[transformers.ImageFeatureExtractionMixin.normalize]]

```python
normalize(image, mean, std, rescale = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L764)

**参数：**

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[[transformers.ImageFeatureExtractionMixin.rescale]]

```python
rescale(image: ndarray, scale: float | int)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L705)

按缩放比例调整 numpy 图像

#### resize[[transformers.ImageFeatureExtractionMixin.resize]]

```python
resize(image, size, resample = None, default_to_square = True, max_size = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L816)

**参数：**

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`](https://pytorch.org/vision/stable/transforms.html#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[[transformers.ImageFeatureExtractionMixin.rotate]]

```python
rotate(image, angle, resample = None, expand = 0, center = None, translate = None, fillcolor = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L975)

**参数：**

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

**返回：** `image`

旋转后的 `PIL.Image.Image`。

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

#### to_numpy_array[[transformers.ImageFeatureExtractionMixin.to_numpy_array]]

```python
to_numpy_array(image, rescale = None, channel_first = True)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L712)

**参数：**

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[[transformers.ImageFeatureExtractionMixin.to_pil_image]]

```python
to_pil_image(image, rescale = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/image_utils.py#L661)

**参数：**

image (`PIL.Image.Image` 或 `numpy.ndarray` 或 `torch.Tensor`)：要转换为 PIL Image 格式的图像。

rescale (`bool`, *可选*) : 是否应用缩放因子（使像素值变为 0 到 255 之间的整数）。如果图像类型为浮点类型，则默认为 `True`，否则为 `False`。

将 `image` 转换为 PIL Image。如有需要，可选择对其进行重新缩放，并将通道维度移回最后一个轴。