Transformers 文档

处理器

Transformers

加入 Hugging Face 社区

并获得增强文档体验的访问权限

协作模型、数据集和 Spaces

通过加速推理实现更快的示例

切换文档主题

开始使用

处理器

在 Transformers 库中，“处理器”可以指两种不同的东西：

用于多模态模型（例如 Wav2Vec2（语音和文本）或 CLIP（文本和视觉））预处理输入的对象。
在旧版本库中用于预处理 GLUE 或 SQUAD 数据的已弃用对象。

多模态处理器

任何多模态模型都需要一个对象来编码或解码将多种模态（文本、视觉和音频）组合在一起的数据。这由称为处理器的对象处理，这些对象将两个或多个处理对象组合在一起，例如分词器（用于文本模态）、图像处理器（用于视觉）和特征提取器（用于音频）。

这些处理器继承自以下实现保存和加载功能的基类：

class transformers.ProcessorMixin

( *args **kwargs )

这是一个混合类，用于为所有处理器类提供保存/加载功能。

apply_chat_template

( conversation: List chat_template: Optional = None tokenize: bool = False **kwargs )

参数

conversation (List[Dict, str, str]) — 要格式化的对话。
chat_template (Optional[str], 可选) — 用于格式化对话的 Jinja 模板。如果未提供，将使用分词器的聊天模板。
tokenize (bool, 可选，默认为 False) — 是否对输出进行分词。**kwargs — 附加关键字参数

与分词器上的 apply_chat_template 方法类似，此方法将 Jinja 模板应用于输入对话，以将其转换为单个可分词的字符串。

from_args_and_dict

( args processor_dict: Dict **kwargs ) → ~processing_utils.ProcessingMixin

参数

processor_dict (Dict[str, Any]) — 将用于实例化处理器对象的字典。可以通过利用 ~processing_utils.ProcessingMixin.to_dict 方法从预训练检查点检索这样的字典。
kwargs (Dict[str, Any]) — 用于初始化处理器对象的附加参数。

返回

~processing_utils.ProcessingMixin

从这些参数实例化的处理器对象。

从 Python 参数字典中实例化一种 ~processing_utils.ProcessingMixin 类型。

from_pretrained

( 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。 **kwargs — 传递给 from_pretrained() 和 ~tokenization_utils_base.PreTrainedTokenizer.from_pretrained 的其他关键字参数。

实例化与预训练模型相关的处理器。

此类方法只是调用特征提取器 from_pretrained()，图像处理器 ImageProcessingMixin 和标记器 ~tokenization_utils_base.PreTrainedTokenizer.from_pretrained 方法。有关更多信息，请参阅上述方法的文档字符串。

get_processor_dict

( pretrained_model_name_or_path: Union **kwargs ) → Tuple[Dict, Dict]

参数

pretrained_model_name_or_path (str 或 os.PathLike) — 我们想要从中获取参数字典的预训练检查点的标识符。
subfolder (str，可选，默认为 "") — 如果相关文件位于 huggingface.co 上的模型仓库的子文件夹中，您可以在此处指定文件夹名称。

返回

Tuple[Dict, Dict]

将用于实例化处理器对象的字典。

从 pretrained_model_name_or_path 中解析出参数字典，用于使用 from_args_and_dict 实例化 ~processing_utils.ProcessingMixin 类型的处理器。

prepare_and_validate_optional_call_args

( *args )

将可选的位置参数与其在处理器类中的 optional_call_args 中的对应名称匹配，按它们传递给处理器调用的顺序。

请注意，这应该只用于具有特殊参数的处理器的 __call__ 方法中。特殊参数是指不是 text、images、audio 或 videos 但也不传递给标记器、图像处理器等的参数。此类处理器的示例包括

CLIPSegProcessor
LayoutLMv2Processor
OwlViTProcessor

另请注意，按位置传递给处理器调用现在已弃用，将在未来版本中被禁止。我们只有为了向后兼容性才保留此功能。

示例：假设处理器类具有 optional_call_args = ["arg_name_1", "arg_name_2"]。

并且我们将调用方法定义为

def __call__(
    self,
    text: str,
    images: Optional[ImageInput] = None,
    *arg,
    audio=None,
    videos=None,
)

那么，如果我们像这样调用处理器

images = [...]
processor("What is common in these images?", images, arg_value_1, arg_value_2)

那么，此方法将返回

{
    "arg_name_1": arg_value_1,
    "arg_name_2": arg_value_2,
}

然后我们可以将此作为 kwargs 传递给 `self._merge_kwargs`

push_to_hub

( repo_id: str use_temp_dir: Optional = None commit_message: Optional = None private: Optional = None token: Union = None max_shard_size: Union = '5GB' create_pr: bool = False safe_serialization: bool = True revision: str = None commit_description: str = None tags: Optional = None **deprecated_kwargs )

参数

repo_id (str) — 您想要将您的处理器推送到其中的存储库的名称。推送到特定组织时，它应包含您的组织名称。
use_temp_dir (bool, 可选) — 是否使用临时目录来存储在推送到 Hub 之前保存的文件。如果没有名为 repo_id 的目录，则默认为 True，否则为 False。
commit_message (str, 可选) — 推送时要提交的消息。默认为 "Upload processor"。
private (bool, 可选) — 创建的存储库是否应该是私有的。
token (bool 或 str, 可选) — 用作远程文件 HTTP 身份验证头的令牌。如果为 True，则使用运行 huggingface-cli login 时生成的令牌（存储在 ~/.huggingface 中）。如果未指定 repo_url，则默认为 True。
max_shard_size (int 或 str, 可选, 默认为 "5GB") — 仅适用于模型。检查点在被分片之前可以达到的最大尺寸。然后检查点分片将分别小于此尺寸。如果表示为字符串，则需要以数字后跟单位（如 "5MB"）的形式表示。我们将其默认设置为 "5GB"，以便用户可以在没有 CPU OOM 问题的免费层 Google Colab 实例上轻松加载模型。
create_pr (bool, 可选, 默认为 False) — 是否使用上传的文件创建 PR，还是直接提交。
safe_serialization (bool, 可选, 默认为 True) — 是否将模型权重转换为 safetensors 格式以进行更安全的序列化。
revision (str, 可选) — 要将上传的文件推送到其中的分支。
commit_description (str, 可选) — 将要创建的提交的描述
tags (List[str], 可选) — 推送到 Hub 的标签列表。

将处理器文件上传到 🤗 模型 Hub。

示例

from transformers import AutoProcessor

processor = AutoProcessor.from_pretrained("google-bert/bert-base-cased")

# Push the processor to your namespace with the name "my-finetuned-bert".
processor.push_to_hub("my-finetuned-bert")

# Push the processor to an organization with the name "my-finetuned-bert".
processor.push_to_hub("huggingface/my-finetuned-bert")

register_for_auto_class

( auto_class = 'AutoProcessor' )

参数

auto_class (str 或 type, 可选，默认为 "AutoProcessor") — 要将此新特征提取器注册到的自动类。

使用给定的自动类注册此类。这应该只用于自定义特征提取器，因为库中的特征提取器已经与 AutoProcessor 映射。

此 API 处于实验阶段，在下一个版本中可能会有一些轻微的破坏性更改。

save_pretrained

( save_directory push_to_hub: bool = False **kwargs )

参数

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

将此处理器的属性（特征提取器、分词器等）保存到指定的目录中，以便可以使用 from_pretrained() 方法重新加载。

此类方法只是调用了 save_pretrained() 和 save_pretrained()。请参考上述方法的文档字符串以获取更多信息。

to_dict

( ) → Dict[str, Any]

返回

Dict[str, Any]

构成此处理器实例的所有属性的字典。

将此实例序列化为 Python 字典。

to_json_file

( json_file_path: Union )

参数

json_file_path (str 或 os.PathLike) — 将此处理器实例的参数保存到的 JSON 文件的路径。

将此实例保存到 JSON 文件中。

to_json_string

( ) → str

返回

str

包含构成此 feature_extractor 实例的所有属性的 JSON 格式字符串。

将此实例序列化为 JSON 字符串。

已弃用的处理器

所有处理器都遵循相同的体系结构，即 DataProcessor 的体系结构。处理器返回一个 InputExample 列表。这些 InputExample 可以转换为 InputFeatures 以便馈送到模型中。

class transformers.DataProcessor

( )

用于序列分类数据集的数据转换器的基类。

get_dev_examples

( data_dir )

获取开发集的 InputExample 集合。

get_example_from_tensor_dict

( tensor_dict )

从包含 tensorflow 张量的字典中获取示例。

get_labels

( )

获取此数据集的标签列表。

get_test_examples

( data_dir )

获取测试集的 InputExample 集合。

get_train_examples

( data_dir )

获取训练集的 InputExample 集合。

tfds_map

( example )

一些 tensorflow_datasets 数据集的格式与 GLUE 数据集不同。此方法将示例转换为正确的格式。

class transformers.InputExample

( guid: str text_a: str text_b: Optional = None label: Optional = None )

用于简单序列分类的单个训练/测试示例。

to_json_string

( )

将此实例序列化为 JSON 字符串。

class transformers.InputFeatures

( input_ids: List attention_mask: Optional = None token_type_ids: Optional = None label: Union = None )

一组数据的特征。属性名称与模型的对应输入相同。

to_json_string

( )

将此实例序列化为 JSON 字符串。

GLUE

通用语言理解评估 (GLUE) 是一个基准，用于评估模型在一组不同的现有 NLU 任务中的性能。它与论文GLUE: A multi-task benchmark and analysis platform for natural language understanding 一起发布。

该库总共包含 10 个用于以下任务的处理器：MRPC、MNLI、MNLI（不匹配）、CoLA、SST2、STSB、QQP、QNLI、RTE 和 WNLI。

这些处理器是

~data.processors.utils.MrpcProcessor
~data.processors.utils.MnliProcessor
~data.processors.utils.MnliMismatchedProcessor
~data.processors.utils.Sst2Processor
~data.processors.utils.StsbProcessor
~data.processors.utils.QqpProcessor
~data.processors.utils.QnliProcessor
~data.processors.utils.RteProcessor
~data.processors.utils.WnliProcessor

此外，以下方法可用于从数据文件中加载值并将其转换为 InputExample 列表。

transformers.glue_convert_examples_to_features

( examples: Union tokenizer: PreTrainedTokenizer max_length: Optional = None task = None label_list = None output_mode = None )

将数据文件加载到 InputFeatures 列表中。

XNLI

跨语言 NLI 语料库 (XNLI) 是一个基准，用于评估跨语言文本表示的质量。XNLI 是基于MultiNLI 的众包数据集：文本对标注了 15 种不同语言的文本蕴涵注释（包括英语等高资源语言和斯瓦希里语等低资源语言）。

它与论文XNLI: Evaluating Cross-lingual Sentence Representations 一起发布。

此库包含用于加载 XNLI 数据的处理器。

~data.processors.utils.XnliProcessor

请注意，由于测试集上提供金标签，因此评估是在测试集上进行的。

在 run_xnli.py 脚本中给出了使用这些处理器的示例。

SQuAD

斯坦福问答数据集 (SQuAD) 是一个基准，用于评估模型在问答方面的性能。有两个版本可用，v1.1 和 v2.0。第一个版本 (v1.1) 与论文 SQuAD：100,000 多个用于文本机器理解的问题一起发布。第二个版本 (v2.0) 与论文知道你不知道什么：SQuAD 的不可回答问题一起发布。

此库为这两个版本中的每一个版本都提供了一个处理器。

处理器

这些处理器是

~data.processors.utils.SquadV1Processor
~data.processors.utils.SquadV2Processor

它们都继承自抽象类 ~data.processors.utils.SquadProcessor

class transformers.data.processors.squad.SquadProcessor

( )

SQuAD 数据集的处理器。由 SquadV1Processor 和 SquadV2Processor 覆盖，分别用于 SQuAD 的 1.1 版和 2.0 版。

get_dev_examples

( data_dir filename = None )

从数据目录返回评估示例。

get_examples_from_dataset

( dataset evaluate = False )

使用 TFDS 数据集创建 SquadExample 列表。

示例

>>> import tensorflow_datasets as tfds

>>> dataset = tfds.load("squad")

>>> training_examples = get_examples_from_dataset(dataset, evaluate=False)
>>> evaluation_examples = get_examples_from_dataset(dataset, evaluate=True)

get_train_examples

( data_dir filename = None )

从数据目录返回训练示例。

此外，可以使用以下方法将 SQuAD 示例转换为 ~data.processors.utils.SquadFeatures，这些特征可以用作模型输入。

transformers.squad_convert_examples_to_features

( examples tokenizer max_seq_length doc_stride max_query_length is_training padding_strategy = 'max_length' return_dataset = False threads = 1 tqdm_enabled = True )

将示例列表转换为可以直接作为模型输入的特征列表。它是模型相关的，并利用分词器的许多功能来创建模型的输入。

示例

processor = SquadV2Processor()
examples = processor.get_dev_examples(data_dir)

features = squad_convert_examples_to_features(
    examples=examples,
    tokenizer=tokenizer,
    max_seq_length=args.max_seq_length,
    doc_stride=args.doc_stride,
    max_query_length=args.max_query_length,
    is_training=not evaluate,
)

这些处理器以及前面提到的方法可以与包含数据的文件以及 tensorflow_datasets 包一起使用。下面给出了示例。

示例用法

这是一个使用处理器以及使用数据文件的转换方法的示例。

# Loading a V2 processor
processor = SquadV2Processor()
examples = processor.get_dev_examples(squad_v2_data_dir)

# Loading a V1 processor
processor = SquadV1Processor()
examples = processor.get_dev_examples(squad_v1_data_dir)

features = squad_convert_examples_to_features(
    examples=examples,
    tokenizer=tokenizer,
    max_seq_length=max_seq_length,
    doc_stride=args.doc_stride,
    max_query_length=max_query_length,
    is_training=not evaluate,
)

使用 tensorflow_datasets 与使用数据文件一样简单。

# tensorflow_datasets only handle Squad V1.
tfds_examples = tfds.load("squad")
examples = SquadV1Processor().get_examples_from_dataset(tfds_examples, evaluate=evaluate)

features = squad_convert_examples_to_features(
    examples=examples,
    tokenizer=tokenizer,
    max_seq_length=max_seq_length,
    doc_stride=args.doc_stride,
    max_query_length=max_query_length,
    is_training=not evaluate,
)

在 run_squad.py 脚本中给出了另一个使用这些处理器的示例。

< > 更新在 GitHub 上

←管道量化→