# 导入实用工具

本页介绍了 `transformers` 中用于实现对象惰性且快速导入的工具。虽然我们力求将依赖项控制在最少，但某些模型有特定的依赖要求，无法绕过。我们并不希望所有 `transformers` 用户为了使用其他模型而必须安装这些依赖，因此我们将它们标记为软依赖，而非硬依赖。

Transformers 工具包的设计目标并非在导入具有特定依赖项的模型时直接报错；相反，当缺少某个依赖项时，只有在调用该对象的方法时才会触发错误。例如，如果未安装 `torchvision`，则快速图像处理器将不可用。

此对象仍然可以导入：

```python
>>> from transformers import DetrImageProcessor
>>> print(DetrImageProcessor)
<class 'transformers.models.detr.image_processing_detr.DetrImageProcessor'>
```

不过，该对象上的方法在调用时会检查其可选依赖项。例如，如果 `torchvision` 不可用，此调用将引发 `ImportError`：

```python
>>> DetrImageProcessor.from_pretrained("facebook/detr-resnet-50")
ImportError:
DetrImageProcessor requires the Torchvision library but it was not found in your environment. Check out the instructions on the
installation page: https://pytorch.org/get-started/locally/ and follow the ones that match your environment.
Please note that you may need to restart your runtime after installation.
```

让我们看看如何指定特定的对象依赖项。

## 指定对象依赖

### 基于文件名

给定文件名下的所有对象都会自动依赖于与该文件名关联的工具

**PyTorch**：所有以 `modeling_` 开头的文件都自动依赖 PyTorch

**Tokenizers**：所有以 `tokenization_` 开头且以 `_fast` 结尾的文件都自动依赖 `tokenizers`

**视觉**：所有以 `image_processing_` 开头的文件都自动依赖于 `vision` 依赖组；在撰写本文时，该组仅包含 `pillow` 依赖。

**Vision + Torch + Torchvision**：所有以 `image_processing_` 开头且以 `_fast` 结尾的文件都自动依赖于 `vision`、`torch` 和 `torchvision`。

所有这些自动依赖项都会叠加在下方详述的显式依赖项之上。

### 显式对象依赖

我们添加了一个名为 `requires` 的方法，用于显式指定给定对象的依赖项。例如，`Trainer` 类有两个硬性依赖项：`torch` 和 `accelerate`。以下是我们如何指定这些必需依赖项：

```python
from .utils.import_utils import requires

@requires(backends=("torch", "accelerate"))
class Trainer:
    ...
```

可以在此处添加的后端，即 `import_utils.py` 模块中可用的所有后端。

此外，可以在每个后端中指定特定版本。例如，要在 `Trainer` 类中指定对 torch>=2.6 的要求，可以这样操作：

```python
from .utils.import_utils import requires

@requires(backends=("torch>=2.6", "accelerate"))
class Trainer:
    ...
```

您可以指定以下运算符：`==`、`>`、`>=`、`<`、`<=`、`!=`。

## 方法[[transformers.utils.import_utils.define_import_structure]]

#### transformers.utils.import_utils.define_import_structure[[transformers.utils.import_utils.define_import_structure]]

```python
transformers.utils.import_utils.define_import_structure(module_path: str, prefix: str | None = None)
```

该方法接收 module_path 作为输入，并创建一个可被 _LazyModule 解析的导入结构。

以下是 src.transformers.models 级别的输出导入结构示例：

{ frozenset({'tokenizers'}): { 'albert.tokenization_albert_fast': {'AlbertTokenizer'} }, frozenset(): { 'albert.configuration_albert': {'AlbertConfig'}, 'align.processing_align': {'AlignProcessor'}, 'align.configuration_align': {'AlignConfig', 'AlignTextConfig', 'AlignVisionConfig'}, 'altclip.configuration_altclip': {'AltCLIPConfig', 'AltCLIPTextConfig', 'AltCLIPVisionConfig'}, 'altclip.processing_altclip': {'AltCLIPProcessor'} } }

导入结构是一个字典，其键为 frozenset，值为从字符串到对象集合的字典。

如果 `prefix` 不为 None，则会将该前缀添加到返回字典中的所有键中。

#### transformers.utils.import_utils.requires[[transformers.utils.import_utils.requires]]

```python
transformers.utils.import_utils.requires(backends = ())
```

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

此装饰器实现了以下两项功能：
- 将 `__backends` 元组附加到对象上，以查看其正确执行所需的后端，而无需实例化该对象
- “@requires” 字符串用于动态导入对象

#### transformers.requires_backends[[transformers.requires_backends]]

```python
transformers.requires_backends(obj, backends)
```

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

**参数：**

obj : 要检查的对象

backends : 要检查的后端列表或元组。

在指定的后端不可用时自动抛出异常的方法。它通常在类

初始化，以确保已安装所需的依赖项：

```py
requires_backends(self, ["torch"])
```

后端应在 `transformers.utils.import_utils` 中定义的 `BACKEND_MAPPING` 中进行定义。

