Transformers documentation

モデルのテストの作成

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

モデルのテストの作成

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

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

# 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 を参照してください)。

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

MICは、公開されたモデルの使用パスを、小さなフィクスチャを用いてレビュー済みのベースラインと比較してチェックします。 ランナー(transformers-mic)とhf-doc-builderには、testingエクストラが付属しています。Transformersのチェックアウト先から:

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

次に実行します:

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 と同様に、bfloat16 での prototypes fleet と、default および bfloat16 両方の control fleet をチェックします。 必要に応じて固定された 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 がパスしても、完全な checkpoint の検証にはなりません。

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

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

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

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

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

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

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

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

CausalLMModelTest

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

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を参照してください。

CausalLMModelTester には base_model_class の指定のみが必要です。このテスターは Model サフィックスを除去してベース名を取得し(LlamaModel は Llama になります)、その後 Config や ForCausalLM などのサフィックスを付加して関連クラスを特定します。モジュール内にクラスが存在しない場合、その属性は None のままとなり、テスターは対応するテストをスキップします。

CausalLMTesterでのデフォルト値の上書き

モデルが標準的な命名規則に従っていない場合、または動作をカスタマイズする必要がある場合は、テスターまたはテストクラスの属性をオーバーライドしてください。

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 を参照してください。

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 を設定することで、複数のサブモデルを処理します。

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 にある最初の数個のデフォルト値を示しています。

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 を親クラスとし、ヘッドクラスの自動検出を行います。ビジョン側の仕組みは、音声特徴量、音声サブ設定、および音声トークンの配置戦略に置き換えられています。

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" が使用されます。
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() に依存しています。

テストミックスイン

モデルに必要なミックスインを選択します。

ミックスインソースファイルテスト対象
ModelTesterMixintests/test_modeling_common.py保存/読み込み、勾配チェックポイント、forwardシグネチャ、共通属性
GenerationTesterMixintests/generation/test_utils.py貪欲法、サンプリング、ビームサーチ、アシストデコーディング
PipelineTesterMixintests/test_pipeline_mixin.pyパイプラインタスクごとに1つのテスト
TrainingTesterMixintests/test_training_mixin.py小規模なバッチでの過学習
TensorParallelTesterMixintests/test_tensor_parallel_mixin.py分散テンソル並列

モデルのテストの作成

完全な動作例については、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/に配置されます。

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 を参照してください。

設定のテスト

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

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 を渡します。

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

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

Mixin テストでは、ランダムな重みを持つ小さな設定を使用して、モデルの動作を迅速に検証します。統合テストでは、実際の事前学習済み重みを使用して推論を実行し、出力の正確性を検証します。Hub 上の Tiny モデルは、CI を高速に実行するのに十分なほど小さい一方で、実際のチェックポイントと同様の構造を持っています。

統合テストの作成

統合テストは別のテストクラスに配置し、@slowでマークし、MemoryCleanupMixinをミックスインします。各テストは実際の重みをダウンロードし、推論を実行し、出力を期待値と比較して確認します。このミックスインは、各テストが使用したメモリを解放し、テストメソッドをtorch.no_grad()の下で実行します — 詳細とオプトアウトの方法については、テスト間のメモリ解放を参照してください。

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 では 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はそこでインスタンス属性のスナップショットを撮りますが、呼び出さない場合はエラーになります。

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") を呼び出して、安定したエキスパートディスパッチパスを強制する必要があります。これをしないと、ルーター内のわずかな数値の違いにより、トークンを処理するエキスパートが切り替わり、出力が変わる可能性があります。

@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 クラスを使用して、デバイスごとの期待値を登録します。Expectations は (device_type, (major, minor)) の SM キーに基づいて現在のハードウェアに最適な一致を選択し、一致しない場合はデフォルトにフォールバックします。

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

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 組織の下で Hub に公開されています。Pipeline のテストでは、Hub にホストされたチェックポイントが必要だが出力の品質は問わない場合に、Tiny モデルを使用します。高速なスモークテストでも、大きなチェックポイントのダウンロードを避けつつフォワードパスの形状を検証するために、Tiny モデルを読み込みます。

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

utils/create_dummy_models.py スクリプトは、ModelTester.get_config() から小さなモデルを生成します。このスクリプトは、テスターから小さなハイパーパラメータを抽出し、ランダムな重みでモデルを構築して、その結果を Hub にアップロードします。

ローカルで小さなモデルを生成します。

python utils/create_dummy_models.py output_dir -m your_model_type

Hub にアップロードします。

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

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_embeddingsTrue埋め込み層のリサイズ
test_resize_position_embeddingsFalse位置埋め込みのリサイズ
test_mismatched_shapesTrue入力/出力形状の不一致の処理
test_missing_keysTrue読み込み時の欠落キーの警告
test_torch_exportableTruetorch.exportとの互換性
test_all_params_have_gradientTrueすべてのパラメータが勾配を受けます(MoEのエキスパートのように、すべてのフォワードパスで全パラメータが活性化されない場合はFalseに設定してください)
is_encoder_decoderFalseエンコーダー・デコーダー固有のテスト
has_attentionsTrueAttention出力のテスト
_is_compositeFalse複合/マルチモーダルモデルの処理
model_split_percents[0.5, 0.7, 0.9]モデル並列性テストの分割パーセンテージ

次のステップ

  • テストの選択、フィクスチャ、ログ出力などについて詳しくは、pytestのドキュメントを参照してください。
Update on GitHub