# モデルのテストの作成

Transformers のテストスイートは、ミックスインベースのアーキテクチャを採用しており、最小限のコードから 100 以上のテストを自動生成します。モデル固有のコードを少量記述するだけで、ミックスインが save/load、生成、パイプライン、トレーニング、テンソル並列処理を処理します。

以下のコマンドでモデルのテストを実行します。

```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
```

Hugging Face の CI は、すべての Pull Request に対して `@slow` なしでモデルのテストを実行し、slow テストは毎晩のスケジュールで実行されます（CI が検証する内容については、[Pull request checks](./pr_checks) を参照してください）。

## モデル統合契約をローカルで実行する

MICは、公開されたモデルの使用パスをレビュー済みのベースラインと比較してチェックします。ランナー(`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 リビジョンを使用します。デフォルトでは prototypes fleet を実行し、`FLEET=control` を指定すると、より小さい control fleet を選択できます。CI と同様に、prototypes fleet は `bfloat16` で、control fleet は `default` と `bfloat16` の両方でチェックされます。必要に応じて、固定された contracts、fixtures、baselines をダウンロードし、ローカルで実行して、fixture ごとに 1 行ずつとサマリーを出力します。失敗した fixture があると、コマンド全体が失敗します。Contracts は並列ランナープロセス (`JOBS`、デフォルトは最大 4、`JOBS=1` で 1 つずつ実行) に分割されます。各ランナーは `OMP_NUM_THREADS=4` を使用し、これは baselines が記録されたスレッド数です (`OMP_NUM_THREADS` を設定して上書きできます)。これにより、スレッド数が CI との差分に寄与しません。`make run-mic` は、`mic` チェッカー (`python utils/checkers.py mic`) のラッパーであり、オプトイン方式で、ネットワークアクセスとモデルランタイムが必要なため、`make check-repo` や CI の一部ではありません。このコマンドは contracts を作成したり公開したりしません。モデル固有のランタイム依存関係と、あなたのプラットフォーム用にレビュー済みの baseline が必要です。fixture がパスしても、完全なチェックポイントの検証にはなりません。

デフォルトでは、変更ファイルは、`origin/main` との merge base と作業ツリーとの差分、および未追跡ファイルです。これには、ブランチのコミット、ステージ済みおよびステージ未済みの変更、リネームの両方のパスが含まれます。クリーンなチェックアウトでは、実行対象は何もありません。変更がすべてのコントラクトを選択した場合（例えば `setup.py`、共有コード、または `tests/contracts.lock` 内の fleet pin など）、何も実行されません。コマンドは理由を出力し、`MODEL=<name>` または `ALL=1` を選択することになります。

MIC は、フィクスチャ設定（ネストされたモデルを含む）、アーキテクチャ、およびトークナイザ/プロセッサクラスからモデルの依存関係を導出します。モデルディレクトリの変更は、一致するコントラクトを選択します。共有 Transformers コード、Auto クラス、依存関係の宣言、またはフリートピンの変更は、すべてのコントラクトを選択します。ドキュメントや通常のテスト専用の変更は、何も選択しません。ランナーは選択結果とその理由を出力します。一致するコントラクトがない場合、それはカバレッジがないことを意味し、モデルチェックが成功したことを意味しません。選択はヒューリスティックであり、完全な Python 依存関係グラフではありません。間接的な依存関係がカバーされているか不明な場合は、`ALL=1` を使用してください。

`MODEL=bert` はより狭い範囲です。`config.json` に `model_type` が `models/bert` で定義されている fixture のコントラクトのみを実行します。BERT を埋め込んでいるだけの複合モデルは実行されません。これらを含めるには、変更ファイルのデフォルト選択（または `ALL=1`）を使用してください。

## ベースとなるテストクラスを選択します

3つのベースクラスが、最も一般的なモデルファミリーをカバーしています。モデルのモダリティに一致するものを選択してください。

| ベースクラス | 用途 | ミックスイン |
|---|---|---|
| `CausalLMModelTest` | 因果言語モデル | `ModelTesterMixin`, `GenerationTesterMixin`, `PipelineTesterMixin`, `TrainingTesterMixin`, `TensorParallelTesterMixin` |
| `VLMModelTest` | ビジョン・言語モデル | `ModelTesterMixin`, `GenerationTesterMixin`, `PipelineTesterMixin` |
| `ALMModelTest` | 音声言語モデル | `ModelTesterMixin`, `GenerationTesterMixin`, `PipelineTesterMixin` |

`VLMModelTest` と `ALMModelTest` は、サブ設定を複合的なトップレベル設定にネストし、生データモダリティ特徴量（音声またはビジョン）とともに `input_ids` にモダリティプレースホルダトークンを配置する共通の親クラス `MultiModalModelTest` を共有しています。`CausalLMModelTest` はマルチモーダル親クラスを使用しません。3つの共有ミックスインを基盤とし、トレーニングとテンソル並列カバレッジのために `TrainingTesterMixin` と `TensorParallelTesterMixin` を追加しています。

上記の3つ（エンコーダーのみ、エンコーダーデコーダーなど）のいずれにも該当しないアーキテクチャの場合、以下で説明する[2クラスパターン](#modeltester-and-modeltest)と[テストミックスイン](#test-mixins)から直接、テストインフラストラクチャを構築してください。

## CausalLMModelTest

`CausalLMModelTest` は、因果言語モデルのテストに推奨されるベースクラスです。5 つの [テストミックスイン](#test-mixins) を継承し、save/load、generation、pipelines、training、tensor parallelism に関するテストを自動生成します。

```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
```

これら2つのクラスにより、`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` は、ビジョン・言語モデルの基底クラスです。3つのミックスイン（`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__` をオーバーライドします。`super().__init__(parent, **kwargs)` を呼び出す前に、`setdefault` でデフォルト値を設定します。以下の例は、[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__`は、`**kwargs`と`setdefault()`から、ビジョンのパラメータ（`image_size`、`patch_size`、`num_channels`、`num_image_tokens`）を受け取ります。
- `ConfigTester` は、トップレベルの config がテキストモデルの config ではなく複合 config であるため、`has_text_modality=False` を使用します。

## ALMModelTest

`ALMModelTest` は、Qwen2Audio、AudioFlamingo3、GraniteSpeech などの音声言語モデル（ALM）のベースクラスです。VLM のパターンを踏襲し、同じ `MultiModalModelTest` を親クラスとし、ヘッドクラスの自動検出を行います。ビジョン側の仕組みは、音声特徴量、音声サブ設定、および音声トークンの配置戦略に置き換えられています。

```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`）を設定します。`super().__init__(parent, **kwargs)`を呼び出す前に、`setdefault`でこれらをオーバーライドしてください。

2つのクラス属性が、モデルがどのように名前を付けるかをテスターに伝えます。

- `audio_mask_key`: モデルがオーディオマスクに期待する kwarg の名前（`"feature_attention_mask"`、`"input_features_mask"` など）。モデルが個別のオーディオマスクを使用しない場合は、`None` にしてください。
- `audio_config_key`: トップレベルの config がオーディオのサブ config をネストするために使用する属性名です。デフォルトは `"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` では、1つのフックである `get_audio_embeds_mask(audio_mask)` のオーバーライドが必須であり、カスタマイズ用にいくつかの任意のフックも公開されています。

- `get_audio_embeds_mask(audio_mask)`: エンコーダーのダウンサンプリング後の、バッチごとのオーディオ埋め込み位置のマスクを返します。テスターはこの行ごとの合計値に基づいて、`input_ids`に挿入する`audio_token_id`プレースホルダーの数を決定するため、この数はエンコーダーが出力する数と一致する必要があります。
- `create_audio_features()`: 音声特徴テンソルを返します。デフォルトの形状は `[batch_size, num_mel_bins, feat_seq_length]` です。GraniteSpeech のように、time-first の特徴（`[batch_size, feat_seq_length, num_mel_bins]`）を期待するモデルを使用する場合は、このメソッドをオーバーライドしてください。
- `create_audio_mask()`: オーディオレベルの注意マスクを返します。デフォルトでは、バッチ内の各行に対してランダムな連続する有効領域を構築します。2回の`prepare_config_and_inputs_for_common()`呼び出しを互いに比較するテストを行う場合、またはオーディオエンコーダーが非nullのマスクを拒否するバックエンドにディスパッチされる場合は、決定論的な全長マスクでオーバーライドしてください。
- `place_audio_tokens(input_ids, config, num_audio_tokens)`: `BOS`の直後に、音声プレースホルダートークンを連続して配置します。モデルが異なるレイアウトを必要とする場合のみ、このメソッドをオーバーライドしてください。
- `get_audio_feature_key()`: 音声特徴の inputs-dict キーを返します（デフォルトは`"input_features"`）。

継承されたマルチモーダルテストに加えて、`ALMModelTest`は`test_mismatching_num_audio_tokens`を追加します。このテストは、`input_ids`内のオーディオプレースホルダトークンの数とオーディオ特徴の数が一致しない場合に、モデルが明確な`ValueError`を送出することをアサートし、複数のオーディオセグメントを含むプロンプトが依然として正常にフォワードされることを検証します。

## 他のアーキテクチャのテストを作成する

エンコーダーのみ、エンコーダー・デコーダー、オーディオ、またはその他の非標準アーキテクチャの場合、以下の2クラスパターンとテストミックスインに基づいて、テストインフラストラクチャを直接構築してください。

### 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` | 貪欲法、サンプリング、ビームサーチ、アシストデコーディング |
| `PipelineTesterMixin` | `tests/test_pipeline_mixin.py` | パイプラインタスクごとに1つのテスト |
| `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上で数秒でテストが完了するように、次元を小さく保ってください。以下の3つのテンソルヘルパーを使用して入力を構築します。

    - `ids_tensor(shape, vocab_size)`: `[0, vocab_size)` の範囲のランダムな整数テンソル。`input_ids`、`token_type_ids`、およびラベルテンソルに使用します。
    - `random_attention_mask(shape)`: 最初のトークンが常に 1 であるバイナリテンソル（0 と 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. 各タスクヘッドについて、`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)
```

Tokenizer のテストも同じパターンです。`tests/test_tokenization_common.py` から `TokenizerTesterMixin` を継承し、いくつかの属性を設定するだけで、テストが自動生成されます。例として [tests/models/llama/test_tokenization_llama.py](https://github.com/huggingface/transformers/blob/main/tests/models/llama/test_tokenization_llama.py) を参照してください。

## 設定のテスト

`ConfigTester` は、config クラスがシリアライズ、保存/読み込み、および標準的なプロパティを正しく処理していることを検証します。`CausalLMModelTest` と `VLMModelTest` は、config テストを自動的に含みます。`ModelTester` と `ModelTest` を使用する一般的なパスでは、`setUp()` 内で config テスターを手動で定義します。

```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` などの共通プロパティが存在すること（`has_text_modality=True` の場合は `vocab_size` も）を確認します。
- `to_json_string()` および `to_json_file()` を使用して、JSON シリアライズをテストします。
- `save_pretrained()` と `from_pretrained()` を往復します。
- `id2label`と`label2id`の一貫性を確認します。
- 引数を指定せずに設定を作成し、デフォルトの初期化を検証します。
- `output_hidden_states` などの共通の kwargs を設定し、正しく保存されていることを確認します。

`vocab_size` を持たないビジョン専用モデルには `has_text_modality=False` を渡し、設定のデフォルト値を上書きするには追加の `**kwargs` を渡します。

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

## 統合テストと小さなモデル

Mixin テストでは、ランダムな重みを持つ小さな設定を使用して、モデルの動作を迅速に検証します。統合テストでは、実際の事前学習済み重みを使用して推論を実行し、出力の正確性を検証します。Hub 上の Tiny モデルは、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` を付与するテストは、重みのダウンロード、大規模データセットの読み込み、または数秒を超える実行時間を伴うものとしてマークしてください。[pull request CI](./pr_checks) では slow テストはスキップされますが、nightly スケジュールでは実行されます。

#### テスト間のメモリ解放

Integration testsは実際のチェックポイントをロードするため、モデルへの参照を保持するテストは、その後で実行されるテストにOOMを引き起こす可能性があります。`tests/test_memory_cleanup_mixin.py` 内の `MemoryCleanupMixin` は、クラス全体でその問題を処理します:

- 各テストの前後で`cleanup(torch_device, gc_collect=True)`を実行し、残存物が次のテストに持ち越されないようにします。
- `self`（`@cached_property` のキャッシュを含む）およびクラス（`setUpClass` 内の `cls.model = ...` など）に、テストが追加した属性を削除します。Pytest はセッションの間テストインスタンスを保持するため、これらの参照がまだオブジェクトを保持している限り、`gc.collect()` では解放できません。
- `torch.no_grad()` の下でテストメソッドを実行し、フォワードパスでアクティベーションが保持されないようにします。

`backward()` を呼び出す、または学習を行うクラスでは、`run_under_no_grad = False` を設定します。両方を組み合わせたクラスでは、代わりに個々のテストメソッドに `@with_grad` または `@with_no_grad` を付与します。

クラス本体で割り当てられた属性は保持されますが、その後追加されたものは破棄されます。`setUp`をオーバーライドする場合は、`super().setUp()`を呼び出してください。このmixinはそこでインスタンス属性のスナップショットを撮りますが、呼び出さない場合はエラーになります。

> [!TIP]
> `MemoryCleanupTestCase` は、自動で一時ディレクトリを削除するテストにも対応するために、mixin を `TestCasePlus` と組み合わせたものです。

リークするテストを見つけるには、`TRANSFORMERS_TEST_MEMORY_LEAK_MIB` に MiB 単位の予算を設定します。デバイス上でその量を超えるメモリが割り当てられたままのテストは、ピーク使用量とともに報告されます。警告ではなく失敗として扱いたい場合は、`TRANSFORMERS_TEST_MEMORY_LEAK_MODE=error` を追加してください。このチェックはデフォルトで無効になっており、残存メモリを調査する際に有効にしてください。ミックスインの通常の teardown は `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..."])
```

#### ハードウェア固有の期待値

Transformers CI は NVIDIA A10 上でスローテストを実行します。数値結果は GPU の世代によってわずかに異なる可能性があるため、統合テストでは [Expectations](https://github.com/huggingface/transformers/blob/main/src/transformers/testing_utils.py#L3247) クラスを使用して、デバイスごとの期待値を登録します。`Expectations` は `(device_type, (major, minor))` の SM キーに基づいて現在のハードウェアに最適な一致を選択し、一致しない場合はデフォルトにフォールバックします。

`torch.cuda.get_device_capability()` を実行して、ローカルの SM バージョンを表示します（例: A10 の場合は `(8, 6)`、H100 の場合は `(9, 0)`）。

```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)
```

### 小さなモデルの作成

ランダムな重みを持つ Tiny モデルは、[hf-internal-testing](https://huggingface.co/hf-internal-testing) 組織の下で Hub に公開されています。Pipeline のテストでは、Hub にホストされたチェックポイントが必要だが出力品質は問わない場合に Tiny モデルを使用します。高速なスモークテストでも、大きなチェックポイントのダウンロードを避け、フォワードパスの形状を検証するために Tiny モデルを読み込みます。

Tiny モデルは統合テストにおける最終手段です。利用可能な最小のチェックポイントが約 24 GB の VRAM を超える場合のみ使用してください。可能な限り、元の事前学習済み重みを使用し、実際の数値的なリグレッションを検出できるようにしてください。

`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`) が毎日 tiny モデルを再生成します。

## テスト対象を制御

`ModelTesterMixin` の Boolean フラグは、自動生成されるテストの切り替えに使用されます。テストクラス上で任意のフラグをオーバーライドすることで、特定のチェックを有効化または無効化できます。

```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` | すべてのパラメータが勾配を受けます（MoEのエキスパートのように、すべてのフォワードパスで全パラメータが活性化されない場合は`False`に設定してください） |
| `is_encoder_decoder` | `False` | エンコーダー・デコーダー固有のテスト |
| `has_attentions` | `True` | Attention出力のテスト |
| `_is_composite` | `False` | 複合/マルチモーダルモデルの処理 |
| `model_split_percents` | `[0.5, 0.7, 0.9]` | モデル並列性テストの分割パーセンテージ |

## 次のステップ

- テストの選択、フィクスチャ、ログ出力などについて詳しくは、[pytest](https://docs.pytest.org/en/latest/getting-started.html)のドキュメントを参照してください。

