# Написание тестов для моделей

Тестовый набор Transformers использует архитектуру на основе миксинов для автоматической генерации более 100 тестов из минимального кода. Вы пишете небольшой объём кода, специфичного для модели, а миксины берут на себя сохранение/загрузку, генерацию, пайплайны, обучение и тензорный параллелизм.

Запустите тесты вашей модели с помощью следующих команд.

```bash
# run your model's tests
pytest tests/models/mymodel/test_modeling_mymodel.py -v

# run a specific test
pytest tests/models/mymodel/test_modeling_mymodel.py::MyModelTest::test_model

# run tests matching a keyword pattern (useful to run all integration tests)
pytest tests/models/mymodel/ -k integration -v

# include slow integration tests
RUN_SLOW=1 pytest tests/models/mymodel/ -v
```

CI Hugging Face запускает тесты моделей без `@slow` для каждого pull request, а медленные тесты выполняются по ночному расписанию (см. [Проверки pull request](./pr_checks), чтобы узнать, что именно проверяет CI).

## Запуск контрактов интеграции моделей локально

MICs проверяют опубликованные пути использования моделей по сравнению с проверенными базовыми линиями, используя небольшие фикстуры. Запускающая программа (`transformers-mic`) и `hf-doc-builder` поставляются с дополнительным пакетом `testing`. Из вашей копии Transformers:

```bash
python -m pip install -e ".[testing]"
```

Затем выполните:

```bash
make run-mic MODEL=bert  # only the contracts for this model directory under src/transformers/models/
make run-mic MODEL=Wav2Vec2  # a model name works too (case and punctuation are ignored)
make run-mic MODEL=qwen+    # every matching model directory: + stands for any characters
make run-mic             # contracts affected by local changes
make run-mic ALL=1       # all fixtures in the fleet
make run-mic BASE=main   # use a different Git comparison base
make run-mic FLEET=control  # the control fleet instead of the default prototypes fleet
make run-mic ALL=1 JOBS=8   # number of runner processes working in parallel (default: cores / 4, up to 4)
```

Команда использует исходный код текущего чек-аута и ревизию флота из `tests/contracts.lock`. По умолчанию запускается флот прототипов; `FLEET=control` выбирает более мелкий контрольный флот. Как и в CI, команда проверяет флот прототипов в `bfloat16`, а контрольный флот — в обоих режимах: `default` и `bfloat16`. При необходимости скачиваются зафиксированные контракты, фикстуры и базовые значения, они выполняются локально, после чего выводится по одной строке на каждую фикстуру и итоговая сводка; любая упавшая фикстура приводит к сбою команды. Контракты распределяются между параллельными процессами раннера (`JOBS`, по умолчанию до 4, `JOBS=1` для последовательного выполнения). Каждый раннер использует `OMP_NUM_THREADS=4` — количество потоков, с которым записаны базовые значения (переопределите `OMP_NUM_THREADS`, чтобы изменить его), поэтому количество потоков не вносит дополнительных расхождений с CI. `make run-mic` является обёрткой над проверщиком `mic` (`python utils/checkers.py mic`), который включается явно и не входит в `make check-repo` или CI, поскольку требует доступа к сети и рантаймов моделей. Команда не создаёт и не публикует контракты. Требуется наличие зависимостей рантайма, специфичных для модели, и проверенного базового значения для вашей платформы; успешное прохождение фикстуры не валидирует полную контрольную точку.

По умолчанию изменённые файлы — это разница между базой слияния с `origin/main` и вашим рабочим деревом, плюс неотслеживаемые файлы. Сюда входят коммиты ветки, внесённые и не внесённые в индекс изменения, а также оба пути при переименовании. В чистой копии нечего запускать. Если изменения затрагивают все контракты (например, `setup.py`, общий код или фиксацию флота в `tests/contracts.lock`), ничего не запускается: команда объясняет причину, и вы выбираете `MODEL=<name>` или `ALL=1`.

MIC выводит зависимости модели из конфигураций фикстур (включая вложенные модели), архитектур и классов токенизаторов/процессоров. Изменения в каталоге модели выбирают соответствующие контракты; изменения в общем коде Transformers, классах Auto, декларациях зависимостей или пине флота выбирают все контракты. Изменения документации и обычные изменения, затрагивающие только тесты, ничего не выбирают. Запускающий процесс выводит выбранные контракты и причины; отсутствие подходящего контракта означает отсутствие покрытия, а не успешную проверку модели. Выбор является эвристикой, а не полным графом зависимостей Python; при сомнениях в том, покрыты ли косвенные зависимости, используйте `ALL=1`.

`MODEL=bert` — более узкий вариант: запускаются только контракты, у которых в фикстуре `config.json` определено `model_type` из `models/bert`. Композитные модели, которые просто включают BERT, не запускаются; для их включения используйте выборку по изменённым файлам по умолчанию (или `ALL=1`).

## Выберите базовый класс тестов

Три базовых класса охватывают наиболее распространённые семейства моделей. Выберите тот, который соответствует модальности вашей модели.

| Базовый класс | Использование | Миксины |
|---|---|---|
| `CausalLMModelTest` | Causal-языковые модели | `ModelTesterMixin`, `GenerationTesterMixin`, `PipelineTesterMixin`, `TrainingTesterMixin`, `TensorParallelTesterMixin` |
| `VLMModelTest` | Модели «зрение-язык» | `ModelTesterMixin`, `GenerationTesterMixin`, `PipelineTesterMixin` |
| `ALMModelTest` | Модели «аудио-язык» | `ModelTesterMixin`, `GenerationTesterMixin`, `PipelineTesterMixin` |

`VLMModelTest` и `ALMModelTest` имеют общего предка `MultiModalModelTest`, который встраивает подконфигурации в составную верхнеуровневую конфигурацию и размещает токены-заполнители модальности в `input_ids` рядом с исходными признаками модальности (аудио или зрение). `CausalLMModelTest` не использует мультимодального предка. Он строится на трёх общих миксинах и добавляет `TrainingTesterMixin` и `TensorParallelTesterMixin` для покрытия сценариев обучения и тензорного параллелизма.

Для архитектур, которые не подходят ни под одну из трёх (только энкодер, энкодер-декодер и т. д.), создайте инфраструктуру тестирования непосредственно на основе [паттерна двух классов](#modeltester-and-modeltest) и [смесей для тестирования](#test-mixins), описанных ниже.

## CausalLMModelTest

`CausalLMModelTest` — рекомендуемый базовый класс для тестирования каузальных языковых моделей. Он наследуется от пяти [тестовых миксинов](#test-mixins) и автоматически генерирует тесты для сохранения/загрузки, генерации, пайплайнов, обучения и тензорного параллелизма.

```py
import unittest

from transformers.testing_utils import require_torch
from transformers import is_torch_available

from ...causal_lm_tester import CausalLMModelTest, CausalLMModelTester

if is_torch_available():
    from transformers import MyModel

class MyModelTester(CausalLMModelTester):
    if is_torch_available():
        base_model_class = MyModel

@require_torch
class MyModelTest(CausalLMModelTest, unittest.TestCase):
    model_tester_class = MyModelTester
```

Эти два класса обеспечивают полное покрытие тестами для `MyModel` и всех его классов-голов (`MyModelForCausalLM`, `MyModelForSequenceClassification` и т. д.). Реальный пример можно найти в [tests/models/llama/test_modeling_llama.py](https://github.com/huggingface/transformers/blob/main/tests/models/llama/test_modeling_llama.py).

`CausalLMModelTester` требует только `base_model_class`. Тестер удаляет суффикс `Model`, чтобы получить базовое имя (`LlamaModel` превращается в `Llama`), а затем добавляет суффиксы вроде `Config` или `ForCausalLM`, чтобы найти связанные классы. Если класс не существует в модуле, атрибут остаётся `None`, и тестер пропускает соответствующие тесты.

### Переопределение значений по умолчанию в CausalLMTester

Если ваша модель не следует стандартному именованию или вам нужно настроить поведение, переопределите атрибуты на тестере или тестовом классе.

```py
class MyModelTester(CausalLMModelTester):
    if is_torch_available():
        base_model_class = MyModel
        # override if the class name doesn't follow the convention
        causal_lm_class = MyCustomCausalLM

@require_torch
class MyModelTest(CausalLMModelTest, unittest.TestCase):
    model_tester_class = MyModelTester
    # disable embedding resize tests
    test_resize_embeddings = False
```

Для моделей, которым требуются дополнительные параметры конструктора в тестере, переопределите `__init__` и вызовите `super().__init__(parent=parent)` перед установкой дополнительных атрибутов. Пример можно найти в [tests/models/youtu/test_modeling_youtu.py](https://github.com/huggingface/transformers/blob/main/tests/models/youtu/test_modeling_youtu.py).

```py
class YoutuModelTester(CausalLMModelTester):
    if is_torch_available():
        base_model_class = YoutuModel

    def __init__(self, parent, kv_lora_rank=16, q_lora_rank=32):
        super().__init__(parent=parent)
        self.kv_lora_rank = kv_lora_rank
        self.q_lora_rank = q_lora_rank
```

## VLMModelTest

`VLMModelTest` — базовый класс для моделей «зрение-язык». Он наследуется от трёх миксинов (`ModelTesterMixin`, `GenerationTesterMixin`, `PipelineTesterMixin`) и устанавливает `_is_composite = True` для работы с несколькими подмоделями.

```py
import unittest

from transformers.testing_utils import require_torch
from transformers import is_torch_available

from ...vlm_tester import VLMModelTest, VLMModelTester

if is_torch_available():
    from transformers import (
        MyVLMConfig,
        MyVLMModel,
        MyVLMTextConfig,
        MyVLMVisionConfig,
        MyVLMForConditionalGeneration,
    )

class MyVLMTester(VLMModelTester):
    if is_torch_available():
        base_model_class = MyVLMModel
        config_class = MyVLMConfig
        text_config_class = MyVLMTextConfig
        vision_config_class = MyVLMVisionConfig
        conditional_generation_class = MyVLMForConditionalGeneration

@require_torch
class MyVLMTest(VLMModelTest, unittest.TestCase):
    model_tester_class = MyVLMTester
```

### Переопределение значений по умолчанию в VLMModelTester

Если VLM требует нестандартных параметров зрения или значений конфигурации, отличных от значений по умолчанию, переопределите `__init__`. Установите значения по умолчанию с помощью `setdefault` перед вызовом `super().__init__(parent, **kwargs)`. Пример ниже показывает первые несколько значений по умолчанию из [tests/models/qianfan_ocr/test_modeling_qianfan_ocr.py](https://github.com/huggingface/transformers/blob/main/tests/models/qianfan_ocr/test_modeling_qianfan_ocr.py).

```py
class QianfanOCRVisionText2TextModelTester(VLMModelTester):
    base_model_class = QianfanOCRModel
    config_class = QianfanOCRConfig
    text_config_class = Qwen3Config
    vision_config_class = QianfanOCRVisionConfig
    conditional_generation_class = QianfanOCRForConditionalGeneration

    def __init__(self, parent, **kwargs):
        kwargs.setdefault("image_token_id", 1)
        kwargs.setdefault("image_size", 32)
        kwargs.setdefault("patch_size", 4)
        kwargs.setdefault("num_channels", 3)
        # ... more defaults
        super().__init__(parent, **kwargs)
```

Тесты VLM отличаются от `CausalLMModelTest` несколькими способами.

- Необходимо задать `config_class`, `text_config_class`, `vision_config_class` и `conditional_generation_class` в тестере.
- `VLMModelTest` не включает `TrainingTesterMixin` или `TensorParallelTesterMixin`.
- Метод `__init__` тестера принимает параметры зрения (`image_size`, `patch_size`, `num_channels`, `num_image_tokens`) из `**kwargs` и `setdefault()`.
- `ConfigTester` использует `has_text_modality=False`, поскольку конфигурация верхнего уровня является составной, а не конфигурацией текстовой модели.

## ALMModelTest

`ALMModelTest` — базовый класс для аудиоязыковых моделей (ALM), таких как Qwen2Audio, AudioFlamingo3 и GraniteSpeech. Он повторяет паттерн VLM с тем же родителем `MultiModalModelTest` и автообнаружением классов head. Механизмы, связанные с визуальной частью, заменены на аудиособытия, аудиоподконфигурацию и стратегию размещения аудиотокенов.

```py
class MyALMTester(ALMModelTester):
    config_class = MyALMConfig
    text_config_class = MyALMTextConfig
    audio_config_class = MyALMAudioConfig
    conditional_generation_class = MyALMForConditionalGeneration
    audio_mask_key = "feature_attention_mask"

class MyALMTest(ALMModelTest, unittest.TestCase):
    model_tester_class = MyALMTester
```

### Переопределение значений по умолчанию в ALMModelTester

Метод `__init__` тестера задаёт значения по умолчанию, специфичные для ALM (`feat_seq_length=128`, `num_mel_bins=80`, `audio_token_id=0`). Переопределите их с помощью `setdefault` перед вызовом `super().__init__(parent, **kwargs)`.

Два атрибута класса сообщают тестеру, как ваша модель именует объекты.

- `audio_mask_key`: имя аргумента, которое ваша модель ожидает для маски аудио (`"feature_attention_mask"`, `"input_features_mask"` и т. д.). Оставьте `None`, если ваша модель не использует отдельную маску аудио.
- `audio_config_key`: имя атрибута, которое ваша конфигурация верхнего уровня использует для вложенной аудиоконфигурации. По умолчанию — `"audio_config"`, но модели вроде GraniteSpeech используют `"encoder_config"`.

```py
class Qwen2AudioModelTester(ALMModelTester):
    def __init__(self, parent, **kwargs):
        kwargs.setdefault("feat_seq_length", 60)
        kwargs.setdefault("max_source_positions", kwargs["feat_seq_length"] // 2)
        super().__init__(parent, **kwargs)
```

`ALMModelTester` требует переопределения одного хука, `get_audio_embeds_mask(audio_mask)`, и предоставляет несколько дополнительных необязательных хуков для настройки.

- `get_audio_embeds_mask(audio_mask)`: возвращает маску позиций аудиовстракций для каждой выборки после понижающей дискретизации в кодере. Тестер использует сумму по строкам этой маски, чтобы определить, сколько плейсхолдеров `audio_token_id` вставить в `input_ids`, поэтому количество должно совпадать с тем, что выдаёт ваш кодер.
- `create_audio_features()`: возвращает тензор аудиопризнаков. Форма по умолчанию — `[batch_size, num_mel_bins, feat_seq_length]`. Переопределите метод, если ваша модель, например GraniteSpeech, ожидает признаки с временным измерением на первом месте (`[batch_size, feat_seq_length, num_mel_bins]`).
- `create_audio_mask()`: возвращает маску внимания на уровне аудио. По умолчанию для каждой строки в батче формируется случайный непрерывный валидный регион. Переопределите её детерминированной маской полной длины, если ваши тесты сравнивают два вызова `prepare_config_and_inputs_for_common()` друг с другом, или если ваш аудио-энкодер обращается к бэкенду, который отклоняет ненулевые маски.
- `place_audio_tokens(input_ids, config, num_audio_tokens)`: размещает токены-заполнители аудио подряд после `BOS`. Переопределяйте только в том случае, если вашей модели требуется другая раскладка.
- `get_audio_feature_key()`: возвращает ключ словаря входных данных для аудиопризнаков (по умолчанию `"input_features"`).

Помимо унаследованных мультимодальных тестов, `ALMModelTest` добавляет `test_mismatching_num_audio_tokens`. Тест проверяет, что модель вызывает явную ошибку `ValueError`, если количество аудио-фич не совпадает с количеством аудио-плейсхолдерных токенов в `input_ids`, и подтверждает, что промпт с несколькими аудио-сегментами успешно проходит прямой проход.

## Напишите тесты для других архитектур

Для архитектур, содержащих только энкодер, энкодер-декодер, аудио или других нестандартных архитектур, создайте инфраструктуру тестирования непосредственно на основе двухклассового паттерна и миксинов для тестов, описанных ниже.

### ModelTester и ModelTest

Каждый файл тестов модели имеет одинаковую структуру.

1. `ModelTester` (обычный класс) создаёт небольшие конфигурации и фиктивные входные данные для тестирования, а также может содержать небольшие регрессионные тесты, специфичные для модели.
2. `ModelTest` (`unittest.TestCase` + миксины) наследует автоматически сгенерированные тесты и запускает их для каждого варианта модели.

`ModelTest` вызывает `prepare_config_and_inputs_for_common()` у тестера, чтобы получить кортеж `(config, inputs_dict)`. Все миксины полагаются на `prepare_config_and_inputs_for_common()` для получения тестовых данных.

### Тестовые миксины

Выберите миксины, необходимые для вашей модели.

| Миксин | Исходный файл | Что проверяется |
|---|---|---|
| `ModelTesterMixin` | `tests/test_modeling_common.py` | Сохранение/загрузка, градиентный чекпоинтинг, сигнатура forward, общие атрибуты |
| `GenerationTesterMixin` | `tests/generation/test_utils.py` | Жадный поиск, выборка, beam search, assisted decoding |
| `PipelineTesterMixin` | `tests/test_pipeline_mixin.py` | Один тест на задачу конвейера |
| `TrainingTesterMixin` | `tests/test_training_mixin.py` | Переобучение на малой партии |
| `TensorParallelTesterMixin` | `tests/test_tensor_parallel_mixin.py` | Распределённый тензорный параллелизм |

### Создание теста модели

Полный рабочий пример см. в [tests/models/modernbert/test_modeling_modernbert.py](https://github.com/huggingface/transformers/blob/main/tests/models/modernbert/test_modeling_modernbert.py). Ключевые шаги описаны ниже.

1. Класс `ModelTester` создаёт небольшие конфигурации и тестовые входные данные. Держите размеры тензоров маленькими, чтобы тесты завершались за несколько секунд на CPU. Используйте три вспомогательные функции для тензоров, приведённые ниже, для построения входных данных.

    - `ids_tensor(shape, vocab_size)`: случайный целочисленный тензор в диапазоне `[0, vocab_size)`. Используйте для `input_ids`, `token_type_ids` и тензоров меток.
    - `random_attention_mask(shape)`: двоичный тензор (содержит 0 и 1), в котором первый токен всегда равен 1. Используется для `attention_mask`.
    - `floats_tensor(shape, scale=1.0)`: Случайный тензор с плавающей точкой. Используйте для непрерывных входных данных, таких как `pixel_values` или `inputs_embeds`.

    Тестер должен реализовать `get_config()`, `prepare_config_and_inputs()` и `prepare_config_and_inputs_for_common()`. Добавьте методы `create_and_check_*` для каждой задачи (базовая модель, классификация последовательностей, классификация токенов и т. д.).

2. Наследуйте от тех миксинов, которые нужны вашей модели, задайте `all_model_classes` и `pipeline_model_mapping`, а также определите `setUp()`. Напишите методы `test_*`, которые делегируют вызовы методам `create_and_check_*` тестера.

3. Для каждой task head добавьте метод `create_and_check_*` в тестер, который создаёт модель, выполняет прямой проход и проверяет формы выходных данных. Затем добавьте соответствующий метод `test_*` в класс тестов.

### Организация файлов

Файлы тестов находятся в `tests/models/mymodel/` в соответствии со структурой, показанной ниже.

```text
tests/models/mymodel/
├── __init__.py
├── test_modeling_mymodel.py            # model tests (required)
├── test_tokenization_mymodel.py        # tokenizer tests (if custom tokenizer)
├── test_image_processing_mymodel.py    # image processor tests (if vision model)
├── test_feature_extraction_mymodel.py  # feature extractor tests (if audio/speech model)
└── test_processing_mymodel.py          # processor tests (if multimodal)
```

Тесты токенизаторов следуют тому же шаблону. Наследуйте `TokenizerTesterMixin` из `tests/test_tokenization_common.py`, задайте несколько атрибутов, и тесты будут сгенерированы автоматически. Пример — [tests/models/llama/test_tokenization_llama.py](https://github.com/huggingface/transformers/blob/main/tests/models/llama/test_tokenization_llama.py).

## Тесты конфигурации

`ConfigTester` проверяет, что класс конфигурации корректно обрабатывает сериализацию, сохранение/загрузку и стандартные свойства. `CausalLMModelTest` и `VLMModelTest` автоматически включают тесты конфигурации. Для общего пути с `ModelTester` и `ModelTest` определите тестер конфигурации вручную в `setUp()`.

```py
from tests.test_configuration_common import ConfigTester

def setUp(self):
    self.config_tester = ConfigTester(self, config_class=MyModelConfig, hidden_size=32)

def test_config(self):
    self.config_tester.run_common_tests()
```

`run_common_tests()` выполняет несколько проверок.

- Проверяет наличие общих свойств, таких как `hidden_size`, `num_attention_heads` и `num_hidden_layers` (а также `vocab_size`, если `has_text_modality=True`).
- Тестирует сериализацию в JSON с помощью `to_json_string()` и `to_json_file()`.
- Методы `save_pretrained()` и `from_pretrained()` обеспечивают обратимое сохранение и загрузку.
- Проверяет согласованность `id2label` и `label2id`.
- Создаёт конфигурацию без аргументов для проверки инициализации по умолчанию.
- Устанавливает общие аргументы, такие как `output_hidden_states`, и проверяет, что они корректно сохранены.

Передавайте `has_text_modality=False` для моделей, работающих только с изображениями и не имеющих `vocab_size`, а также передавайте дополнительные `**kwargs`, чтобы переопределить значения по умолчанию в конфигурации.

```py
self.config_tester = ConfigTester(
    self, config_class=MyVisionConfig, has_text_modality=False, hidden_size=64
)
```

## Интеграционные тесты и небольшие модели

Тесты миксинов используют небольшие конфигурации со случайными весами, чтобы быстро проверять поведение модели. Интеграционные тесты выполняют инференс с реальными предобученными весами для проверки корректности вывода. Небольшие модели на Hub достаточно малы для быстрого CI, но структурированы как настоящие чекпоинты.

### Написание интеграционных тестов

Размещайте интеграционные тесты в отдельном тестовом классе, помечайте их `@slow` и подключайте `MemoryCleanupMixin`. Каждый тест загружает реальные веса, выполняет инференс и сверяет выходные данные с ожидаемыми значениями. Миксин освобождает память, занятую каждым тестом, и запускает методы тестов в режиме `torch.no_grad()` — см. [Освобождение памяти между тестами](#releasing-memory-between-tests), чтобы узнать, что он делает и как отключить его поведение.

```py
import torch
from transformers import AutoTokenizer
from transformers.testing_utils import MemoryCleanupMixin, require_torch, slow, torch_device

class MyModelIntegrationTest(MemoryCleanupMixin, unittest.TestCase):
    @slow
    @require_torch
    def test_inference(self):
        model = MyModelForCausalLM.from_pretrained("myorg/mymodel-base").to(torch_device)
        tokenizer = AutoTokenizer.from_pretrained("myorg/mymodel-base")
        inputs = tokenizer("Hello, world", return_tensors="pt").to(torch_device)

        outputs = model(**inputs)

        # check against expected values
        expected_slice = torch.tensor([[-0.1234, 0.5678, -0.9012]])
        torch.testing.assert_close(outputs.logits[0, :1, :3], expected_slice, atol=1e-4, rtol=1e-4)
```

Отметьте любой тест тегом `@slow`, если он загружает веса, считывает большой набор данных или выполняется дольше нескольких секунд. [CI для pull request](./pr_checks) пропускает медленные тесты, но ночной график их запускает.

#### Освобождение памяти между тестами

Интеграционные тесты загружают реальные контрольные точки, поэтому тест, удерживающий ссылку на свою модель, может исчерпать память для всех последующих тестов. `MemoryCleanupMixin` в `tests/test_memory_cleanup_mixin.py` решает эту проблему для всего класса:

- Выполняет `cleanup(torch_device, gc_collect=True)` до и после каждого теста, чтобы остатки не переносились.
- Удаляет атрибуты, которые тест добавил в `self` (включая кэши `@cached_property`) и в класс (например, `cls.model = ...` в `setUpClass`). Pytest сохраняет экземпляры тестов в течение всей сессии, поэтому `gc.collect()` не может освободить объекты, на которые эти ссылки всё ещё указывают.
- Запускает методы тестирования в режиме `torch.no_grad()`, чтобы прямой проход не сохранял активации.

Классы, которые обучают или вызывают `backward()`, задают `run_under_no_grad = False`. Класс, в котором смешаны оба варианта, вместо этого помечает отдельные методы тестов `@with_grad` или `@with_no_grad`.

Атрибуты, назначенные в теле класса, сохраняются, а всё, что добавляется позже, отбрасывается. Если вы переопределяете `setUp`, вызовите `super().setUp()`: миксин делает снимок атрибутов экземпляра именно там и выдаёт ошибку, если этого не сделать.

> [!TIP]
> `MemoryCleanupTestCase` объединяет миксин с `TestCasePlus` для тестов, которым также требуется автоматическое удаление временных каталогов.

Чтобы найти тест с утечкой памяти, установите `TRANSFORMERS_TEST_MEMORY_LEAK_MIB` в значение бюджета в МБ; любой тест, оставляющий на устройстве выделенную память сверх этого лимита, будет отчитан вместе с пиковым значением использования. Добавьте `TRANSFORMERS_TEST_MEMORY_LEAK_MODE=error`, чтобы тест завершался с ошибкой, а не с предупреждением. Проверка отключена по умолчанию, и её следует включать при поиске остаточных выделений. Стандартный разбор миксина уже выполняет `gc.collect`, что может освободить выделение, которое вы хотели бы исследовать при воспроизведении утечки.

#### Тесты интеграции генерации

Используйте `do_sample=False` в тестах генерации, чтобы результат был детерминированным при разных запусках и на разном оборудовании. Для моделей Mixture-of-Experts также вызывайте `model.set_experts_implementation("eager")` перед генерацией, чтобы принудительно использовать стабильный путь маршрутизации экспертов. Без этого небольшие численные различия в роутере могут изменить то, какой эксперт обрабатывает токен, и повлиять на вывод.

```py
@slow
@require_torch
def test_generate(self):
    model = MyModelForCausalLM.from_pretrained("myorg/mymodel-base").to(torch_device)
    tokenizer = AutoTokenizer.from_pretrained("myorg/mymodel-base")
    inputs = tokenizer("Hello, world", return_tensors="pt").to(torch_device)

    # model.set_experts_implementation("eager")  # uncomment for MoE models
    generated_ids = model.generate(**inputs, max_new_tokens=20, do_sample=False)
    output = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)
    self.assertEqual(output, ["Hello, world! This is the expected continuation..."])
```

#### Ожидаемые значения для конкретного оборудования

CI-процесс Transformers выполняет медленные тесты на NVIDIA A10. Числовые результаты могут незначительно различаться в зависимости от поколения GPU, поэтому интеграционные тесты используют класс [Expectations](https://github.com/huggingface/transformers/blob/main/src/transformers/testing_utils.py#L3247) для регистрации ожидаемых значений для каждого устройства. `Expectations` выбирает наилучшее соответствие для текущего оборудования на основе ключей SM `(device_type, (major, minor))` и переключается на значение по умолчанию, если подходящего варианта не найдено.

Выполните `torch.cuda.get_device_capability()`, чтобы вывести локальную версию SM (например, `(8, 6)` для A10, `(9, 0)` для H100).

```py
from transformers.testing_utils import Expectations

expected_texts = Expectations(
    {
        ("cuda", (8, 6)): ["Hello, world! This is the A10 continuation..."],
        ("cuda", (9, 0)): ["Hello, world! This is the H100 continuation..."],
    }
).get_expectation()

self.assertEqual(output, expected_texts)
```

### Создание небольших моделей

Малые модели со случайными весами размещены на Hub в организации [hf-internal-testing](https://huggingface.co/hf-internal-testing). Тесты Pipeline используют малые модели, когда требуется чекпоинт, размещённый на Hub, но качество вывода не имеет значения. Быстрые smoke-тесты также загружают малые модели, чтобы проверить формы выходных тензоров прямого прохода без скачивания крупных чекпоинтов.

Малые модели — крайняя мера для интеграционных тестов. Используйте их только в том случае, если размер самого доступного чекпоинта превышает ~24 ГБ видеопамяти. По возможности используйте исходные предобученные веса, чтобы выявлять реальные численные регрессии.

Скрипт `utils/create_dummy_models.py` генерирует миниатюрные модели на основе `ModelTester.get_config()`. Скрипт извлекает миниатюрные гиперпараметры из вашего тестера, собирает модель со случайными весами и загружает результат в Hub.

Генерируйте небольшие модели локально.

```bash
python utils/create_dummy_models.py output_dir -m your_model_type
```

Загрузите их в Hub.

```bash
python utils/create_dummy_models.py output_dir -m your_model_type --upload --organization hf-internal-testing
```

Каждая модель использует имя `hf-internal-testing/tiny-random-{ModelClassName}` и фиксируется в `tests/utils/tiny_model_summary.json`. CI-процесс (`.github/workflows/check_tiny_models.yml`) ежедневно пересоздаёт миниатюрные модели.

## Управление тем, что тестируется

Логические флаги в `ModelTesterMixin` управляют автоматически генерируемыми тестами. Переопределите любой флаг в вашем тестовом классе, чтобы включить или отключить конкретные проверки.

```py
class MyModelTest(CausalLMModelTest, unittest.TestCase):
    model_tester_class = MyModelTester
    test_resize_embeddings = False
    test_all_params_have_gradient = False  # when not all parameters are activated in every forward pass
```

| Флаг | По умолчанию | Что он контролирует |
|---|---|---|
| `test_resize_embeddings` | `True` | Изменение размера слоя встраивания |
| `test_resize_position_embeddings` | `False` | Изменение размера позиционных эмбеддингов |
| `test_mismatched_shapes` | `True` | Обработка несоответствия форм входных и выходных данных |
| `test_missing_keys` | `True` | Предупреждения об отсутствующих ключах при загрузке |
| `test_torch_exportable` | `True` | Совместимость с `torch.export` |
| `test_all_params_have_gradient` | `True` | Все параметры получают градиенты (установите `False`, если не все параметры активируются при каждом прямом проходе, например, эксперты MoE) |
| `is_encoder_decoder` | `False` | Тесты, специфичные для архитектуры encoder-decoder |
| `has_attentions` | `True` | Тесты вывода внимания |
| `_is_composite` | `False` | Обработка составных/мультимодальных моделей |
| `model_split_percents` | `[0.5, 0.7, 0.9]` | Проценты разбиения для тестов параллелизма моделей |

## Дальнейшие шаги

- Ознакомьтесь с документацией [pytest](https://docs.pytest.org/en/latest/getting-started.html), чтобы узнать больше о выборе тестов, фикстурах, ведении журнала и других возможностях.

