Transformers documentation

Pull request 체크

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Pull request 체크

Pull request를 열면 Hugging Face CI가 여러 가지 검사를 실행하며, PR이 병합되기 전에 이 검사들이 모두 통과해야 합니다.

  • CI 수정은 체크를 통과하기 위해 로컬에서 실행할 명령어를 나열합니다.
  • 그 이후의 섹션에서는 코드 품질과 저장소 일관성과 같이 각 체크가 무엇을 검증하는지 설명합니다.
  • Tests는 실행되는 테스트, 테스트 카테고리, 느린 테스트를 설명합니다.

CI 수정

대부분의 경우, make style만 실행하면 가장 흔한 실패 원인인 코드 품질 검사를 통과할 수 있습니다.

make style

리포지토리 일관성, 복사본, 또는 자동 생성 파일 관련 오류가 발생하면 make fix-repo를 실행하세요. 이 명령은 스타일, 복사본, docstring, 자동 생성 파일을 한 번에 수정합니다.

make fix-repo

…

make fix-repo   # auto-fix everything that can be auto-fixed
make typing     # check types and model structure, fix any errors manually
make check-repo # verify all checks pass, fix anything that remains

make typing은 수동으로 수정해야 하는 타입 오류와 모델 구조 위반 사항을 감지합니다. make check-repo는 모든 것이 준비되었는지 확인하기 위해 최종 읽기 전용 검사를 수행합니다.

CI는 간헐적으로 불안정(flaky)할 수 있습니다. 변경 사항과 무관한 항목에서 체크가 실패한 경우, 유지보수자에게 재실행을 요청하세요.

코드 품질

코드 품질 검사는 포맷팅, import, 타입 검사, 모델 구조 규칙을 포함합니다. 이는 make fix-repo와 make typing에 해당합니다.

make style(make fix-repo에 포함됨)는 Ruff 린팅 및 포맷팅, __init__.py의 import 정렬 순서, 그리고 자동 매핑 일관성을 자동으로 수정합니다.

make typing은 ty를 사용하여 타입 검사를 수행하고, config 클래스 명명 규칙과 forward() 시그니처를 포함하는 TRansFormers(TRF) 규칙을 검증합니다. 타입 오류와 TRF 위반 사항은 구체적인 규칙 번호를 보고하며, 수동으로 수정해야 합니다. 해당 규칙은 mlinter 저장소에 있습니다. 모든 TRF 규칙을 확인하려면 python -m utils.mlinter --list-rules를 실행하고, 특정 규칙의 전체 문서를 보려면 python -m utils.mlinter --rule TRFXXX를 실행하세요.

TRF 규칙에 예외가 필요한 경우, 다음 옵션 중 하나를 선택하세요(자세한 내용은 위반 사항 억제를 참조하세요).

  • utils/mlinter/rules.toml의 해당 규칙에 대해 allowlist_models 목록에 모델 이름을 추가하세요. 모델 파일 전체에 예외가 필요한 경우 이 방법을 사용하세요.
  • # trf-ignore: TRFXXX를 문제의 구문과 같은 줄에, 또는 바로 위 줄에 추가하세요. 예외가 필요한 구문이 하나뿐인 경우에 이 방법을 사용하세요.

리포지토리 일관성

저장소 일관성 확인은 make check-repo와 유사하지만, 첫 번째 실패에서 중단됩니다. 아래 범주에 걸쳐 저장소가 내부적으로 일관되도록 유지합니다: 공개 객체는 계속 import 가능해야 하고, 복사된 코드는 소스와 동기화되어 있어야 하며, 자동 생성된 파일(dummies, doctests, metadata)은 코드의 현재 상태를 반영해야 합니다. 새로운 모델의 경우, 모든 새 모델 클래스가 auto-mappings에 등록되어 있는지도 확인합니다.

카테고리검증 대상자동 수정되었나요?
Init 파일src/transformers/models/ 안의 __init__.py 파일은 최신 상태입니다make fix-repo
복사본 및 모듈# Copied from 블록은 소스와 일치하며, 모듈러 생성 파일은 최신 상태입니다make fix-repo
Docstring과 문서인수 docstring이 함수 시그니처 및 문서 목차와 일치합니다make fix-repo
자동 생성된 파일Dummies, 파이프라인 타이핑, doctest 목록, 메타데이터, 의존성 테이블make fix-repo
설정 검증Config 클래스의 docstring에 유효한 체크포인트가 있으며 config 속성이 modeling 파일과 일치합니다수동
리뷰어 할당모든 모델 디렉터리와 리뷰어 파일의 모든 규칙은 여전히 리뷰어에게 도달합니다수동

리뷰어 할당

.github/scripts/codeowners_for_review_action은 어떤 사람이 어떤 파일을 리뷰하는지 기록합니다.

소유권은 파일별로, 가장 구체적인 것부터 순서대로 결정됩니다.

WhereThe input "Looks like" is a fragment, likely part of a sentence (e.g., "Looks like an error"). In a technical documentation context, this is often used to introduce a code block or a result. A natural Korean translation for this fragment, maintaining the informal/neutral tone often found in such snippets or keeping it professional, would be "다음과 같습니다" (It is as follows) or simply "다음과 같이 보입니다" (It looks like the following). Given the instruction to use formal 합니다 style, "다음과 같습니다" is the most appropriate and professional choice for a fragment that introduces content. 다음과 같습니다다음 용도로 사용하세요
모델 파일modular_<model>.py 또는 modeling_<model>.py의 앞부분 주석 블록에 # Reviewers: @login모달리티 소유자 이외의 사람이 필요한 모델. 모듈형 변환기는 헤더를 생성된 modeling 파일에 복사하므로, 태그가 재생성 후에도 유지됩니다.
경로 규칙.github/scripts/codeowners_for_review_action의 /src/transformers/<area>/ @login모델이 아닌 모든 것
모달리티 테이블@@modality/vision @login, 동일한 파일에서docs/source/en/_toctree.yml의 해당 섹션에 문서 페이지가 있는 모든 모델
모두 포괄하는* @Rocketknight1 @ArthurZuckerThe input text "whatever nothing else claims" is a fragment, likely part of a sentence or a list item. It translates to "무엇이든 다른 것이 주장하지 않는" or "다른 것이 주장하지 않는 무엇이든". Given the context of technical documentation, it's likely part of a condition or a description of a state. A natural translation would be "다른 것이 주장하지 않는 무엇이든" (whatever nothing else claims).

새로운 모델은 어디에도 항목을 추가할 필요가 없습니다. 문서 목차 검사에서 이미 요구하는 _toctree.yml에 해당 모델의 문서 페이지를 추가하면 해당 모델이 특정 모달리티에 배치되고, 이후에는 모달리티 테이블이 이를 자동으로 포함합니다.

make check-repository-consistency는 utils/check_reviewers.py를 실행하며, 이 스크립트는 모델이 catch-all을 제외한 누구에게도 연결되지 않았거나, 어떤 규칙도 더 이상 파일과 일치하지 않거나, 모달리티 테이블이 목차와 일치하지 않을 때 실패합니다. 해당 리졸버는 transformers의 의존성이 아닙니다. utils/checkers-requirements.txt에 나열되어 있으며, 체커 러너는 환경에서 처음 실행될 때 이를 설치합니다. 설치가 불가능한 경우(예: 오프라인 상태)에는 체커가 이를 보고하고 통과 처리하며, 작업을 차단하지 않습니다. src/transformers/models 외부에 소유자가 없는 경로는 참고 사항으로 보고됩니다. 목록을 확인하려면 다음을 사용하세요:

python utils/check_reviewers.py --strict

테스트

CI는 PR에서 변경된 내용에 따라 테스트의 대상 하위 집합을 실행합니다. CI는 pytest-random-order를 사용하여 테스트를 약간 무작위화된 순서로 실행하여 결합된 테스트를 포착합니다. 실행 시작 시 무작위 시드가 출력되므로, --random-order-seed=<seed>를 사용하여 동일한 순서를 재현할 수 있습니다.

GPU에서 로컬 테스트는 통과하지만 CI에서 실패하는 경우, TRANSFORMERS_TEST_DEVICE="cpu"를 설정하여 CPU에서도 실패를 재현할 수 있는지 확인하세요.

TRANSFORMERS_TEST_DEVICE="cpu" pytest tests/models/my_model/ -v

아래 섹션에서는 테스트 선택 방식, 실행되는 작업, 느린 테스트 처리 방법을 설명합니다.

테스트 선택

CI는 모든 PR에서 전체 테스트 스위트를 실행하지 않습니다. CI는 모든 PR에서 @slow로 장식된 테스트를 건너뛰며, PR이 검토 대상이 되면 유지보수자가 GPU에서 해당 테스트를 실행합니다.

utils/tests_fetcher.py는 변경된 파일의 import 의존성을 추적하여 영향을 받는 테스트를 식별하고, 해당 테스트만 실행합니다. 또한 공유 유틸리티를 수정할 때 다른 모델에서 발생하는 회귀 문제도 포착합니다. fetcher는 변경된 파일과 영향을 받는 테스트를 출력한 뒤, 목록을 tests_torch_test_list.txt에 기록합니다.

fetcher를 사용하여 CI에서 실행하는 내용을 정확히 재현합니다.

python utils/tests_fetcher.py
python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_preparation/tests_torch_test_list.txt)

modeling_utils.py나 generation/utils.py와 같은 핵심 파일을 수정하면 영향받은 부분만 아니라 모든 모델 테스트가 실행됩니다.

모델에 대한 모든 테스트를 무조건적으로 실행할 수도 있습니다. 직접 실행은 더 빠른 로컬 sanity check이지만, 수정한 공유 코드로 인해 다른 모델에서 발생하는 회귀(regression)를 잡아내지 못합니다.

pytest tests/models/my_model/ -v

테스트 작업 카테고리

테스트는 병렬 CI 작업으로 나뉘며, 각 작업은 경로 패턴에 따라 파일을 선택합니다. 모델 PR에 관련되는 작업은 다음과 같습니다:

  • tests_torch: 모델링 테스트(tests/models/*/test_modeling_*.py)
  • tests_tokenization: 토크나이저 테스트 (tests/models/*/test_tokenization_*.py)
  • tests_processors: 프로세서 및 피처 추출기 테스트 (tests/models/*/test_(processing|image_processing|feature_extractor)_*.py)
  • tests_generate: 생성 테스트
  • pipelines_torch: 파이프라인 테스트
  • tests_training_ci: 학습 루프 테스트
  • tests_tensor_parallel_ci: 텐서 병렬 테스트
  • tests_fsdp_ci: FSDP 테스트

느린 테스트

일반적인 CI 실행에서는 @slow 데코레이터가 붙은 테스트를 건너뜁니다. 이러한 테스트는 실제 체크포인트를 다운로드하거나 상당한 컴퓨트 자원이 필요하므로 GPU 인스턴스에서 실행되며, 유지보수자가 PR이 리뷰 대상이 되면 이를 트리거합니다.

Slow tests는 NVIDIA A10에서 실행되며, 수치 결과는 CI 하드웨어와 로컬 머신 사이에서 약간 다를 수 있습니다. 새 모델을 추가할 때 필요에 따라 유지보수자는 테스트에서 해당 값을 조정합니다.

아래 명령어로 로컬에서 느린 테스트를 실행합니다.

RUN_SLOW=1 python -m pytest tests/models/my_model/ -v

문서 빌드

build_pr_documentation 작업은 문서를 빌드하고 미리보기를 생성합니다. 봇이 PR에 미리보기 링크를 게시하며, 병합 전에 해당 체크가 통과해야 합니다. 대부분의 실패 원인은 toctree에 항목이 누락된 것입니다. 로컬에서 문서를 빌드하는 방법은 docs 폴더의 README.md를 참고하세요.

# 구문에서 복사됨

새로운 모델의 경우 # Copied from보다 모듈형 워크플로(modular_*.py)를 항상 우선 사용하세요. # Copied from는 가능한 한 피하세요.

# Copied from 메커니즘은 복사된 코드가 원본과 동기화되도록 유지합니다. make fix-repo가 실행되면 모든 # Copied from 블록을 검사하여 원본과 일치하도록 업데이트하므로, # Copied from 블록 내부에서 한 편집은 덮어쓰기됩니다. 대신 소스를 편집하고 make fix-repo가 변경 사항을 전파하도록 하세요.

# Copied from의 기본 형태는 다음과 같습니다.

# Copied from transformers.models.bert.modeling_bert.BertSelfOutput

# Copied from transformers.models.bert.modeling_bert.BertAttention with Bert->Roberta

# Copied from transformers.models.bert.modeling_bert.BertForSequenceClassification with Bert->MobileBert all-casing

with model->newModel 구문은 복사 후 문자열 치환을 적용합니다. 여러 치환은 쉼표로 구분하며, 왼쪽에서 오른쪽으로 순서대로 적용됩니다. all-casing 옵션은 모든 대소문자 변형을 한 번에 치환합니다(Bert, bert, BERT가 각각 MobileBert, mobilebert, MOBILEBERT로 변경됨).

Update on GitHub