# Importando utilitários

Esta página apresenta os utilitários do `transformers` para permitir a importação de objetos de forma preguiçosa e rápida. Embora busquemos manter dependências mínimas, alguns modelos possuem requisitos de dependências específicas que não podem ser contornados. Não queremos que todos os usuários do `transformers` precisem instalar essas dependências para usar outros modelos; por isso, as marcamos como dependências suaves, em vez de dependências rígidas.

O toolkit transformers não foi projetado para falhar na importação de um modelo que possui uma dependência específica; em vez disso, um objeto para o qual você não tem uma dependência disponível causará um erro ao chamar qualquer método nele. Como exemplo, se `torchvision` não estiver instalado, os processadores de imagem rápidos não estarão disponíveis.

Este objeto ainda é importável:

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

No entanto, os métodos desse objeto verificam suas dependências opcionais quando são chamados. Por exemplo, se o `torchvision` não estiver disponível, essa chamada levanta um `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.
```

Vamos ver como especificar dependências de objetos específicos.

## Especificando Dependências de Objetos

### Baseado em nome de arquivo

Todos os objetos sob um determinado nome de arquivo têm uma dependência automática para a ferramenta vinculada ao nome de arquivo

**PyTorch**: Todos os arquivos que começam com `modeling_` têm uma dependência automática do PyTorch

**Tokenizers**: Todos os arquivos que começam com `tokenization_` e terminam com `_fast` possuem uma dependência automática de `tokenizers`

**Visão**: todos os arquivos que começam com `image_processing_` têm uma dependência automática do grupo de dependências `vision`; no momento da redação, esse grupo contém apenas a dependência `pillow`.

**Visão + Torch + Torchvision**: Todos os arquivos que começam com `image_processing_` e terminam com `_fast` têm uma dependência automática de `vision`, `torch` e `torchvision`.

Todas essas dependências automáticas são adicionadas por cima das dependências explícitas detalhadas abaixo.

### Dependências de Objetos Explícitas

Adicionamos um método chamado `requires` que é usado para especificar explicitamente as dependências de um objeto dado. Como exemplo, a classe `Trainer` tem duas dependências obrigatórias: `torch` e `accelerate`. Veja como especificamos essas dependências obrigatórias:

```python
from .utils.import_utils import requires

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

Os backends que podem ser adicionados aqui são todos os backends disponíveis no módulo `import_utils.py`.

Além disso, é possível especificar versões específicas em cada backend. Por exemplo, é assim que você especificaria um requisito de torch>=2.6 na classe `Trainer`:

```python
from .utils.import_utils import requires

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

Você pode especificar os seguintes operadores: `==`, `>`, `>=`, `<`, `<=`, `!=`.

## Métodos[[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)
```

Este método recebe um module_path como entrada e cria uma estrutura de importação digerível por um _LazyModule.

Aqui está um exemplo de uma estrutura de importação de saída no nível 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'} } }

A estrutura de importação é um dict definido com frozensets como chaves e dicts de strings para conjuntos de objetos.

Se `prefix` não for None, ele adicionará esse prefixo a todas as chaves no dicionário retornado.

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/import_utils.py#L3027)

Este decorador permite duas coisas:
- Anexar uma tupla `__backends` a um objeto para ver quais são os backends necessários para que ele seja executado corretamente, sem instanciá-lo
- A string '@requires' é usada para importar objetos dinamicamente

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

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

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/import_utils.py#L2447)

**Parâmetros:**

obj : objeto a ser verificado

backends : lista ou tupla de backends a serem verificados.

Método que lança automaticamente uma exceção caso os backends especificados não estejam disponíveis. Ele é frequentemente usado durante a

inicialização para garantir que as dependências necessárias sejam instaladas:

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

Os backends devem ser definidos no `BACKEND_MAPPING` definido em `transformers.utils.import_utils`.