Transformers 文档

构建自定义模型

构建自定义模型

🤗 Transformers 库设计得非常易于扩展。每个模型都在存储库的特定子文件夹中完全编码,没有任何抽象,因此您可以轻松复制一个建模文件并根据您的需求进行调整。

如果你正在编写一个全新的模型,从头开始可能会更容易。在本教程中,我们将向你展示如何编写一个自定义模型及其配置,以便它可以在Transformers中使用,以及如何与社区分享它(包括它所依赖的代码),这样任何人都可以使用它,即使它不在🤗 Transformers库中。我们将看到如何基于transformers构建,并通过你的钩子和自定义代码扩展框架。

我们将通过将timm库的ResNet类包装到PreTrainedModel中,来在ResNet模型上展示所有这些内容。

编写自定义配置

在我们深入模型之前,让我们先编写其配置。模型的配置是一个对象,它将包含构建模型所需的所有必要信息。正如我们将在下一节中看到的,模型只能通过config进行初始化,因此我们确实需要这个对象尽可能完整。

transformers 库中的模型通常遵循一个约定,即它们在 __init__ 方法中接受一个 config 对象,然后将整个 config 传递给模型中的子层,而不是将配置对象拆分为多个参数并分别传递给子层。以这种方式编写模型可以使代码更简单,并且为任何超参数提供一个明确的“真相来源”,同时也更容易重用 transformers 中其他模型的代码。

在我们的示例中,我们将使用ResNet类的几个参数,这些参数我们可能想要调整。不同的配置将为我们提供可能的不同类型的ResNets。然后我们只需在检查其中一些参数的有效性后存储这些参数。

from transformers import PretrainedConfig
from typing import List


class ResnetConfig(PretrainedConfig):
    model_type = "resnet"

    def __init__(
        self,
        block_type="bottleneck",
        layers: List[int] = [3, 4, 6, 3],
        num_classes: int = 1000,
        input_channels: int = 3,
        cardinality: int = 1,
        base_width: int = 64,
        stem_width: int = 64,
        stem_type: str = "",
        avg_down: bool = False,
        **kwargs,
    ):
        if block_type not in ["basic", "bottleneck"]:
            raise ValueError(f"`block_type` must be 'basic' or bottleneck', got {block_type}.")
        if stem_type not in ["", "deep", "deep-tiered"]:
            raise ValueError(f"`stem_type` must be '', 'deep' or 'deep-tiered', got {stem_type}.")

        self.block_type = block_type
        self.layers = layers
        self.num_classes = num_classes
        self.input_channels = input_channels
        self.cardinality = cardinality
        self.base_width = base_width
        self.stem_width = stem_width
        self.stem_type = stem_type
        self.avg_down = avg_down
        super().__init__(**kwargs)

编写自己的配置时需要记住的三个重要事项如下:

  • 你必须继承自 PretrainedConfig,
  • 你的 __init__PretrainedConfig 必须接受任何 kwargs,
  • 那些 kwargs 需要传递给父类的 __init__

继承是为了确保你从🤗 Transformers库中获得所有功能,而另外两个约束来自于PretrainedConfig具有比你设置的更多的字段。当使用from_pretrained方法重新加载配置时,这些字段需要被你的配置接受,然后发送到父类。

为您的配置定义model_type(这里model_type="resnet")不是强制性的,除非您希望将您的模型注册到自动类中(参见最后一部分)。

完成此操作后,您可以像处理库中的任何其他模型配置一样轻松创建并保存您的配置。以下是我们如何创建并保存一个resnet50d配置的示例:

resnet50d_config = ResnetConfig(block_type="bottleneck", stem_width=32, stem_type="deep", avg_down=True)
resnet50d_config.save_pretrained("custom-resnet")

这将保存一个名为 config.json 的文件到 custom-resnet 文件夹中。然后你可以使用 from_pretrained 方法重新加载你的配置:

resnet50d_config = ResnetConfig.from_pretrained("custom-resnet")

你也可以使用PretrainedConfig类的任何其他方法,比如push_to_hub()来直接将你的配置上传到Hub。

编写自定义模型

现在我们有了ResNet配置,我们可以继续编写模型。我们实际上会编写两个:一个从一批图像中提取隐藏特征(如BertModel),另一个适合图像分类(如BertForSequenceClassification)。

正如我们之前提到的,为了保持这个示例的简单性,我们只会编写一个模型的松散包装。在编写这个类之前,我们唯一需要做的是在块类型和实际块类之间建立一个映射。然后,通过将所有内容传递给ResNet类,从配置中定义模型:

from transformers import PreTrainedModel
from timm.models.resnet import BasicBlock, Bottleneck, ResNet
from .configuration_resnet import ResnetConfig


BLOCK_MAPPING = {"basic": BasicBlock, "bottleneck": Bottleneck}


class ResnetModel(PreTrainedModel):
    config_class = ResnetConfig

    def __init__(self, config):
        super().__init__(config)
        block_layer = BLOCK_MAPPING[config.block_type]
        self.model = ResNet(
            block_layer,
            config.layers,
            num_classes=config.num_classes,
            in_chans=config.input_channels,
            cardinality=config.cardinality,
            base_width=config.base_width,
            stem_width=config.stem_width,
            stem_type=config.stem_type,
            avg_down=config.avg_down,
        )

    def forward(self, tensor):
        return self.model.forward_features(tensor)

对于将分类图像的模型,我们只需更改forward方法:

import torch


class ResnetModelForImageClassification(PreTrainedModel):
    config_class = ResnetConfig

    def __init__(self, config):
        super().__init__(config)
        block_layer = BLOCK_MAPPING[config.block_type]
        self.model = ResNet(
            block_layer,
            config.layers,
            num_classes=config.num_classes,
            in_chans=config.input_channels,
            cardinality=config.cardinality,
            base_width=config.base_width,
            stem_width=config.stem_width,
            stem_type=config.stem_type,
            avg_down=config.avg_down,
        )

    def forward(self, tensor, labels=None):
        logits = self.model(tensor)
        if labels is not None:
            loss = torch.nn.functional.cross_entropy(logits, labels)
            return {"loss": loss, "logits": logits}
        return {"logits": logits}

在这两种情况下,请注意我们如何从PreTrainedModel继承并使用config调用超类初始化(有点像你编写常规的torch.nn.Module时)。设置config_class的行不是强制性的,除非你想将你的模型注册到自动类中(参见最后一部分)。

如果你的模型与库中的某个模型非常相似,你可以重复使用与该模型相同的配置。

你可以让你的模型返回任何你想要的内容,但像我们为ResnetModelForImageClassification所做的那样返回一个字典,当传递标签时包含损失,将使你的模型可以直接在Trainer类中使用。只要你计划使用自己的训练循环或其他库进行训练,使用其他输出格式也是可以的。

现在我们有了我们的模型类,让我们创建一个:

resnet50d = ResnetModelForImageClassification(resnet50d_config)

再次,你可以使用PreTrainedModel的任何方法,比如save_pretrained()push_to_hub()。我们将在下一节中使用第二个方法,并看看如何用我们模型的代码推送模型权重。 但首先,让我们在模型中加载一些预训练的权重。

在您自己的使用案例中,您可能会在自己的数据上训练自定义模型。为了在本教程中快速进行,我们将使用预训练的resnet50d版本。由于我们的模型只是它的一个包装器,因此转移这些权重将很容易:

import timm

pretrained_model = timm.create_model("resnet50d", pretrained=True)
resnet50d.model.load_state_dict(pretrained_model.state_dict())

现在让我们看看如何确保当我们执行save_pretrained()push_to_hub()时,模型的代码会被保存。

将带有自定义代码的模型注册到自动类

如果你正在编写一个扩展🤗 Transformers的库,你可能希望扩展自动类以包含你自己的模型。这与将代码推送到Hub不同,因为用户需要导入你的库才能获取自定义模型(与从Hub自动下载模型代码相反)。

只要你的配置有一个model_type属性,该属性与现有的模型类型不同,并且你的模型类具有正确的config_class属性,你就可以像这样将它们添加到自动类中:

from transformers import AutoConfig, AutoModel, AutoModelForImageClassification

AutoConfig.register("resnet", ResnetConfig)
AutoModel.register(ResnetConfig, ResnetModel)
AutoModelForImageClassification.register(ResnetConfig, ResnetModelForImageClassification)

请注意,当您将自定义配置注册到AutoConfig时,使用的第一个参数需要与自定义配置的model_type匹配,并且当您将自定义模型注册到任何自动模型类时,使用的第一个参数需要与这些模型的config_class匹配。

将代码发送到Hub

此API是实验性的,在接下来的版本中可能会有一些轻微的破坏性更改。

首先,确保您的模型在一个.py文件中完全定义。它可以依赖其他文件的相对导入,只要所有文件都在同一个目录中(我们目前还不支持此功能的子模块)。在我们的示例中,我们将在当前工作目录的一个名为resnet_model的文件夹中定义一个modeling_resnet.py文件和一个configuration_resnet.py文件。配置文件包含ResnetConfig的代码,而建模文件包含ResnetModelResnetModelForImageClassification的代码。

.
└── resnet_model
    ├── __init__.py
    ├── configuration_resnet.py
    └── modeling_resnet.py

__init__.py 可以是空的,它只是为了让 Python 检测到 resnet_model 可以作为模块使用。

如果从库中复制建模文件,您需要替换文件顶部的所有相对导入,以从transformers包中导入。

请注意,您可以重复使用(或子类化)现有的配置/模型。

要与社区分享您的模型,请按照以下步骤操作:首先从新创建的文件中导入ResNet模型和配置:

from resnet_model.configuration_resnet import ResnetConfig
from resnet_model.modeling_resnet import ResnetModel, ResnetModelForImageClassification

然后你必须告诉库,在使用save_pretrained方法时,你想要复制这些对象的代码文件,并将它们正确注册到给定的Auto类中(特别是对于模型),只需运行:

ResnetConfig.register_for_auto_class()
ResnetModel.register_for_auto_class("AutoModel")
ResnetModelForImageClassification.register_for_auto_class("AutoModelForImageClassification")

请注意,配置不需要指定自动类(它们只有一个自动类, AutoConfig),但对于模型来说是不同的。您的自定义模型可能适用于许多不同的任务,因此您 必须指定哪个自动类是适合您的模型的正确类。

如果你想复制代码文件,请使用register_for_auto_class()。如果你更倾向于使用Hub上来自另一个仓库的代码,你不需要调用它。在有多个自动类的情况下,你可以直接使用以下结构修改config.json

"auto_map": {     
	"AutoConfig": "<your-repo-name>--<config-name>",     
	"AutoModel": "<your-repo-name>--<config-name>",
	"AutoModelFor<Task>": "<your-repo-name>--<config-name>",    
},

接下来,让我们像之前一样创建配置和模型:

resnet50d_config = ResnetConfig(block_type="bottleneck", stem_width=32, stem_type="deep", avg_down=True)
resnet50d = ResnetModelForImageClassification(resnet50d_config)

pretrained_model = timm.create_model("resnet50d", pretrained=True)
resnet50d.model.load_state_dict(pretrained_model.state_dict())

现在要将模型发送到Hub,请确保您已登录。可以在终端中运行:

huggingface-cli login

或者从笔记本中:

from huggingface_hub import notebook_login

notebook_login()

然后你可以像这样推送到你自己的命名空间(或者你所属的组织):

resnet50d.push_to_hub("custom-resnet50d")

除了建模权重和json格式的配置外,这还复制了建模和配置的.py文件到custom-resnet50d文件夹中,并将结果上传到了Hub。你可以在这个模型仓库中查看结果。

有关推送到 Hub 方法的更多信息,请参阅共享教程

使用自定义代码的模型

你可以使用任何配置、模型或分词器,通过其仓库中的自定义代码文件与自动类和from_pretrained方法。所有上传到Hub的文件和代码都会进行恶意软件扫描(更多信息请参阅Hub安全文档),但你仍应审查模型代码和作者,以避免在您的机器上执行恶意代码。设置trust_remote_code=True以使用带有自定义代码的模型:

from transformers import AutoModelForImageClassification

model = AutoModelForImageClassification.from_pretrained("sgugger/custom-resnet50d", trust_remote_code=True)

强烈建议传递一个提交哈希作为revision,以确保模型的作者没有更新代码并添加一些恶意的新行(除非你完全信任模型的作者)。

commit_hash = "ed94a7c6247d8aedce4647f00f20de6875b5b292"
model = AutoModelForImageClassification.from_pretrained(
    "sgugger/custom-resnet50d", trust_remote_code=True, revision=commit_hash
)

请注意,在浏览Hub上模型仓库的提交历史时,有一个按钮可以轻松复制任何提交的提交哈希值。

< > Update on GitHub