Transformers documentation
모델 테스트 작성
모델 테스트 작성
Transformers 테스트 스위트는 믹스인 기반 아키텍처를 사용하여 최소한의 코드로 100개 이상의 테스트를 자동 생성합니다. 모델에 특화된 소량의 코드만 작성하면, 믹스인이 저장/로드, 생성, 파이프라인, 학습, 텐서 병렬화를 처리합니다.
다음 명령어로 모델의 테스트를 실행하세요.
# 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/ -vHugging Face CI는 모든 pull request에서 @slow 없이 모델 테스트를 실행하며, slow 테스트는 매일 밤 정기적으로 실행됩니다(CI가 검증하는 내용은 Pull request checks를 참고하세요).
Run Model Integration Contracts를 로컬에서 실행
MIC는 작은 픽스처를 사용하여 게시된 모델 사용 경로를 검토된 베이스라인과 비교합니다.
러너(transformers-mic)와 hf-doc-builder에는 testing extra가 포함되어 있습니다. 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을 확인합니다.
필요한 고정된 계약, 픽스처, 베이스라인을 다운로드하고 로컬에서 실행한 후, 픽스처당 한 줄씩 및 요약을 출력합니다. 실패한 픽스처가 있으면 명령이 실패합니다.
계약은 병렬 러너 프로세스(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와의 merge base와 작업 트리의 차이, 그리고 추적되지 않은 파일입니다. 여기에는 브랜치 커밋, 스테이징된 변경 사항과 스테이징되지 않은 변경 사항, 그리고 이름이 변경된 파일의 양쪽 경로가 모두 포함됩니다. 깨끗한 체크아웃 상태에서는 실행할 것이 없습니다.
변경 사항이 모든 계약을 선택하는 경우(예: setup.py, 공유 코드 또는 tests/contracts.lock의 fleet pin), 아무것도 실행되지 않습니다. 명령은 그 이유를 표시하며, MODEL=<name> 또는 ALL=1을 선택해야 합니다.
MIC는 fixture 설정(중첩된 모델을 포함), 아키텍처, tokenizer/processor 클래스에서 모델 의존성을 파생합니다. 모델 디렉터리 변경 사항은 일치하는 계약을 선택하며, 공유된 Transformers 코드, Auto 클래스, 의존성 선언 또는 fleet pin에 대한 변경 사항은 모든 계약을 선택합니다. 문서 및 일반적인 테스트 전용 변경 사항은 아무것도 선택하지 않습니다. 러너는 선택 내용과 이유를 출력합니다. 일치하는 계약이 없으면 커버리지가 없는 것을 의미하며, 모델 체크가 성공한 것이 아닙니다. 선택은 휴리스틱이며 완전한 Python 의존성 그래프가 아니므로, 간접 의존성이 커버되는지 확실하지 않을 경우 ALL=1을 사용하세요.
MODEL=bert는 더 좁은 범위를 가집니다. models/bert에 model_type이 정의된 config.json을 가진 fixture의 계약만 실행합니다. BERT를 단순히 임베딩하는 복합 모델은 실행되지 않으며, 이를 포함하려면 기본 변경 파일 선택(또는 ALL=1)을 사용하세요.
기본 테스트 클래스 선택
세 가지 베이스 클래스가 가장 일반적인 모델 계열을 다룹니다. 모델의 모달리티에 맞는 클래스를 선택하세요.
| 기본 클래스 | 사용 | 믹스인 |
|---|---|---|
CausalLMModelTest | Causal language models | ModelTesterMixin, GenerationTesterMixin, PipelineTesterMixin, TrainingTesterMixin, TensorParallelTesterMixin |
VLMModelTest | 비전-언어 모델 | ModelTesterMixin, GenerationTesterMixin, PipelineTesterMixin |
ALMModelTest | 오디오-언어 모델 | ModelTesterMixin, GenerationTesterMixin, PipelineTesterMixin |
VLMModelTest와 ALMModelTest는 서브 설정을 복합적인 최상위 설정에 중첩하고, 원본 모달리티 특징(오디오 또는 비전)과 함께 input_ids에 모달리티 플레이스홀더 토큰을 배치하는 공통 MultiModalModelTest 부모 클래스를 공유합니다. CausalLMModelTest는 멀티모달 부모 클래스를 사용하지 않습니다. 이 클래스는 세 가지 공유 믹스인을 기반으로 하며, 학습 및 텐서 병렬 커버리지를 위해 TrainingTesterMixin과 TensorParallelTesterMixin을 추가합니다.
세 가지(인코더 전용, 인코더-디코더 등) 중 어느 것도 해당하지 않는 아키텍처의 경우, 아래에 설명된 two-class pattern와 test mixins를 기반으로 테스트 인프라를 직접 구축하세요.
CausalLMModelTest
CausalLMModelTest은 causal language model을 테스트하기 위한 권장 기본 클래스입니다. 이 클래스는 다섯 개의 test mixin을 상속하며, 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이 두 클래스는 MyModel과 모든 헤드 클래스(MyModelForCausalLM, MyModelForSequenceClassification 등)에 대한 완전한 테스트 커버리지를 제공합니다. 실제 예제는 tests/models/llama/test_modeling_llama.py를 참고하세요.
CausalLMModelTester에는 base_model_class만 필요합니다. tester는 Model 접미사를 제거하여 기본 이름(LlamaModel은 Llama가 됨)을 얻은 뒤, Config나 ForCausalLM와 같은 접미사를 붙여 관련 클래스를 찾습니다. 해당 모듈에 클래스가 없으면 해당 속성은 None으로 유지되고, tester는 이에 해당하는 테스트를 건너뜁니다.
CausalLMTester에서 기본값 재정의
모델이 표준 네이밍을 따르지 않거나 동작을 커스터마이즈해야 하는 경우, tester 또는 test class에서 속성을 오버라이드하세요.
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_rankVLMModelTest
VLMModelTest은 비전-언어 모델의 기본 클래스입니다. 이 클래스는 세 가지 믹스인(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 = MyVLMTesterVLMModelTester에서 기본값 재정의
VLM에 커스텀 비전 파라미터나 기본값이 아닌 config 값이 필요한 경우 __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는 최상위 설정이 텍스트 모델 설정이 아닌 복합 설정이기 때문에has_text_modality=False를 사용합니다.
ALMModelTest
ALMModelTest는 Qwen2Audio, AudioFlamingo3, GraniteSpeech와 같은 오디오-언어 모델(ALM)의 기본 클래스입니다. MultiModalModelTest라는 동일한 부모 클래스를 공유하며 헤드 클래스를 자동 탐색하는 VLM 패턴을 따릅니다. 비전 쪽 메커니즘은 오디오 특징, 오디오 서브 구성, 오디오 토큰 배치 전략으로 대체됩니다.
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 = MyALMTesterALMModelTester에서 기본값 재정의
테스터의 __init__는 ALM 전용 기본값(feat_seq_length=128, num_mel_bins=80, audio_token_id=0)을 설정합니다. super().__init__(parent, **kwargs)를 호출하기 전에 setdefault로 이 값들을 오버라이드하세요.
두 개의 클래스 속성이 테스터가 모델이 이름을 붙이는 방식을 어떻게 처리하는지 알려 줍니다.
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는 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와 같이 시간 우선 특징([batch_size, feat_seq_length, num_mel_bins])을 기대하는 모델을 사용하는 경우 오버라이드하세요.create_audio_mask(): 오디오 레벨의 attention mask를 반환합니다. 기본값은 배치의 각 행마다 무작위로 연속된 유효 영역을 구성합니다. 두 번의prepare_config_and_inputs_for_common()호출 결과를 서로 비교하는 테스트를 수행하거나, 오디오 인코더가 null이 아닌 mask를 거부하는 백엔드로 디스패치되는 경우, 결정적인 전체 길이 mask로 오버라이드하세요.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를 발생시키는지 확인하고, 여러 오디오 세그먼트가 포함된 프롬프트가 여전히 성공적으로 포워딩되는지 검증합니다.
다른 아키텍처에 대한 테스트 작성
인코더 전용, 인코더-디코더, 오디오 또는 기타 비표준 아키텍처의 경우, 아래에서 설명하는 두 클래스 패턴과 테스트 믹스를 기반으로 테스트 인프라를 직접 구축하세요.
ModelTester와 ModelTest
모든 모델 테스트 파일은 동일한 구조를 따릅니다.
ModelTester(일반 클래스)는 테스트를 위한 작은 config와 더미 입력을 생성하며, 모델에 특화된 작은 회귀 테스트도 포함할 수 있습니다.ModelTest(unittest.TestCase+ mixins)는 자동 생성된 테스트를 상속받아 모든 모델 변형에 대해 실행합니다.
ModelTest은 tester에서 prepare_config_and_inputs_for_common()을 호출하여 (config, inputs_dict) 튜플을 가져옵니다. 모든 mixin은 테스트 데이터에 대해 prepare_config_and_inputs_for_common()에 의존합니다.
테스트 믹스인
모델에 필요한 믹스인을 선택하세요.
| Mixin | 소스 파일 | … |
|---|---|---|
ModelTesterMixin | tests/test_modeling_common.py | 저장/로드, 그라디언트 체크포인트, forward 시그니처, 공통 속성 |
GenerationTesterMixin | tests/generation/test_utils.py | 탐욕적 디코딩, 샘플링, 빔 검색, 보조 디코딩 |
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를 참고하세요. 주요 단계는 아래와 같습니다.
ModelTester클래스는 작은 config와 더미 입력을 생성합니다. CPU에서 테스트가 몇 초 안에 완료되도록 차원을 작게 유지하세요. 아래 세 가지 텐서 헬퍼를 사용하여 입력을 구성하세요.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): 무작위 float 텐서.pixel_values나inputs_embeds와 같은 연속 입력에 사용합니다.
테스터는
get_config(),prepare_config_and_inputs(),prepare_config_and_inputs_for_common()를 구현해야 합니다. 각 태스크 헤드(베이스 모델, 시퀀스 분류, 토큰 분류 등)에 대해create_and_check_*메서드를 추가하세요.모델에 필요한 mixin을 상속받고,
all_model_classes와pipeline_model_mapping을 설정한 뒤setUp()을 정의합니다.test_*메서드를 작성하여 tester의create_and_check_*메서드에 위임합니다.각 태스크 헤드에 대해, 모델 인스턴스를 생성하고 forward pass를 실행한 뒤 출력 shape를 검증하는
create_and_check_*메서드를 tester에 추가합니다. 그런 다음 테스트 클래스에 해당하는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를 참고하세요.
Config 테스트
ConfigTester는 config 클래스가 직렬화, 저장/로드, 표준 속성을 올바르게 처리하는지 검증합니다. CausalLMModelTest와 VLMModelTest는 config 테스트를 자동으로 포함합니다. ModelTester와 ModelTest를 사용하는 일반적인 경로에서는 setUp()에서 config tester를 수동으로 정의해야 합니다.
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의 일관성을 확인합니다.- 인수 없이 config를 생성하여 기본 초기화를 검증합니다.
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을 혼합(mix in)합니다. 각 테스트는 실제 가중치를 다운로드하고 추론을 실행한 뒤, 출력이 기대값과 일치하는지 확인합니다. 이 mixin은 각 테스트가 차지하는 메모리를 해제하고, 테스트 메서드를 torch.no_grad() 아래에서 실행합니다 — 동작 방식과 제외(opt out) 방법은 테스트 간 메모리 해제를 참고하세요.
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는 실제 checkpoint를 로드하므로, 모델에 대한 참조를 유지하는 테스트는 이후에 실행되는 모든 작업에서 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()아래에서 테스트 메서드를 실행하여 forward pass가 activations를 유지하지 않도록 합니다.
backward()를 학습하거나 호출하는 클래스는 run_under_no_grad = False를 설정합니다. 두 가지를 모두 사용하는 클래스는 개별 테스트 메서드에 @with_grad 또는 @with_no_grad를 붙입니다.
클래스 본문에서 할당된 속성은 유지되고, 이후에 추가된 모든 항목은 삭제됩니다. setUp을 오버라이드하는 경우 super().setUp()을 호출해야 합니다. 믹스인은 해당 위치에서 인스턴스 속성을 스냅샷으로 저장하며, 이를 호출하지 않으면 오류가 발생합니다.
MemoryCleanupTestCase는 자동 삭제되는 임시 디렉터리가 필요한 테스트를 위해 mixin을TestCasePlus와 결합합니다.
누수 테스트를 찾으려면 TRANSFORMERS_TEST_MEMORY_LEAK_MIB를 MiB 단위의 예산으로 설정하세요. 디바이스에 해당 예산을 초과하는 할당이 남아 있는 테스트는 피크 사용량과 함께 보고됩니다. 경고 대신 실패하도록 하려면 TRANSFORMERS_TEST_MEMORY_LEAK_MODE=error를 추가하세요. 이 체크는 기본적으로 비활성화되어 있으며, 잔여 할당을 조사할 때 활성화해야 합니다. 믹신의 일반적인 teardown은 이미 gc.collect를 실행하므로, 누수를 재현하는 과정에서 검사하려는 할당이 정리될 수 있습니다.
Generation 통합 테스트
생성 테스트에서는 do_sample=False를 사용하여 실행 및 하드웨어 간에 출력이 결정론적으로 유지되도록 하세요. Mixture-of-Experts 모델의 경우, 생성 전에 model.set_experts_implementation("eager")를 호출하여 안정적인 expert dispatch 경로를 강제해야 합니다. 이를 하지 않으면 router의 미세한 수치적 차이로 인해 토큰을 처리하는 expert가 달라져 출력이 변경될 수 있습니다.
@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 모델을 사용합니다. 빠른 스모크 테스트도 대형 체크포인트를 다운로드하지 않고 forward pass의 shape을 검증하기 위해 Tiny 모델을 로드합니다.
Tiny 모델은 통합 테스트를 위한 최후의 수단입니다. 가장 작은 가용한 checkpoint가 약 24 GB의 VRAM을 초과할 때만 사용하세요. 가능한 경우 실제 수치 회귀를 포착하기 위해 원래의 사전 학습된 가중치를 사용하세요.
utils/create_dummy_models.py 스크립트는 ModelTester.get_config()에서 tiny 모델을 생성합니다. 이 스크립트는 테스터에서 tiny 하이퍼파라미터를 추출하고, 무작위 가중치로 모델을 빌드한 후 결과를 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_embeddings | True | 임베딩 레이어 리사이징 |
test_resize_position_embeddings | False | Position embedding 리사이징 |
test_mismatched_shapes | True | 입력/출력 형상 불일치 처리 |
test_missing_keys | True | 로드 시 누락된 키 경고 |
test_torch_exportable | True | torch.export 호환성 |
test_all_params_have_gradient | True | 모든 파라미터가 그래디언트를 수신합니다(모든 forward pass에서 모든 파라미터가 활성화되지 않는 경우, 예를 들어 MoE experts인 경우 False로 설정) |
is_encoder_decoder | False | Encoder-decoder 전용 테스트 |
has_attentions | True | Attention 출력 테스트 |
_is_composite | False | 복합/멀티모달 모델 처리 |
model_split_percents | [0.5, 0.7, 0.9] | 모델 병렬성 테스트를 위한 분할 비율 |
다음 단계
- 테스트 선택, 픽스처, 로깅 등에 대한 자세한 내용은 pytest 문서를 참고하세요.