Transformers documentation
레거시 모델 기여
레거시 모델 기여
더 모듈화된 접근 방식으로 새 모델을 추가하는 것을 먼저 시도해 보세요. 이렇게 하면 Transformers에 모델을 기여하는 것이 훨씬 쉬워집니다!
Transformers의 많은 모델은 개발자와 연구자들에 의해 기여되었습니다. 오픈소스 우선 프로젝트로서, 커뮤니티가 능동적이고 독립적으로 더 많은 모델을 추가할 수 있도록 지원하는 데 전념하고 있습니다.
Transformers에 모델을 추가하면 다음을 배울 수 있습니다:
- 오픈소스 모범 사례에 대해 자세히 보기
- 모델의 아키텍처에 대해
- Transformers의 설계 원칙에 대해
- 대형 모델을 효율적으로 테스트하는 방법
- Black와 Ruff와 같은 Python 유틸리티를 사용하여 깔끔하고 가독성 높은 코드를 작성하는 방법
도전적이지만 보람 있는 과정입니다.
이 가이드에서는 Transformers에 BrandNewLlama PyTorch 모델 예제를 추가하는 방법을 단계별로 안내합니다. 시작하기 전에 라이브러리에 익숙해지는 것이 좋습니다.
Transformers 개요
Transformers는 고유한 철학과 설계 선택을 가진 의견이 분명한 라이브러리입니다. 이러한 선택들은 Transformers를 지속 가능하게 확장하고 유지하는 데 도움이 됩니다.
Philosophy 문서에서 우리의 설계 원칙에 대해 자세히 알아보세요.
이러한 설계 선택 사항 중 일부는 다음과 같습니다:
- composition > 과잉 추상화
- 가독성과 접근성을 크게 향상시킨다면 중복 코드가 항상 나쁜 것은 아닙니다
- 모델 파일은 자체적으로 완결되어 있으며, 필요한 모든 모델 코드는
modeling_mymodel.py파일에서 찾을 수 있습니다
이러한 설계 선택은 모델과 상호작용하는 모든 사용자에게 중요합니다. 읽기, 이해하기, 수정하기가 더 쉬워집니다.
이 섹션에서는 모델 및 구성 클래스가 상호 작용하는 방식과 Transformers의 코드 스타일을 설명합니다.
모델 및 구성
모든 Transformers 모델은 기본 PreTrainedModel 및 PreTrainedConfig 클래스를 상속합니다. 구성은 모델의 청사진입니다.
모든 모델은 코드의 가독성을 유지하기 위해 추상화 수준이 최대 두 단계까지만 존재합니다. 여기 예시로 제시된 모델인 BrandNewLlama은 BrandNewLlamaPreTrainedModel과 PreTrainedModel을 상속받습니다. 새로운 모델이 PreTrainedModel에만 의존하도록 하는 것이 중요하며, 이를 통해 from_pretrained()와 save_pretrained() 메서드를 사용할 수 있습니다.
modeling.py 파일에는 forward 메서드와 같은 다른 중요한 함수들이 정의되어 있습니다.
특정 모델 헤드(예: 시퀀스 분류 또는 언어 모델링)는 추상화 수준을 낮게 유지하기 위해 forward pass에서 베이스 모델을 호출해야 하며, 이를 상속받아서는 안 됩니다.
새로운 모델에는 PreTrainedModel의 속성으로 저장되는 구성, 예를 들어 BrandNewLlamaConfig가 필요합니다.
model = BrandNewLlamaModel.from_pretrained("username/brand_new_llama")
model.configPreTrainedConfig은 from_pretrained()와 save_pretrained() 메서드를 제공합니다.
PreTrainedModel.save_pretrained()를 사용하면 모델과 설정이 함께 저장되도록 PreTrainedConfig.save_pretrained()가 자동으로 호출됩니다.
모델은 model.safetensors 파일로 저장되고, 구성은 config.json 파일로 저장됩니다.
코드 스타일
Transformers는 추상화된 코드 스타일보다는 깔끔하고 가독성 높은 코드를 선호합니다. 코드 스타일 선택 사항 중 일부는 다음과 같습니다:
코드는 영어를 모국어로 하지 않는 사용자도 접근할 수 있어야 합니다. 설명적인 변수 이름을 선택하고 약어를 피하세요. 예를 들어, “act” 대신 “activation”을 사용하는 것이 좋습니다. for 루프의 인덱스가 아닌 한 글자 변수 이름은 사용을 지양해야 합니다.
짧은 코드보다 명시적인 코드가 선호됩니다. 코드가 더 길더라도 마찬가지입니다.
nn.Sequential을 서브클래스로 사용하지 마세요. 대신 nn.Module을 서브클래스로 만들어 print 문이나 브레이크포인트로 코드를 빠르게 디버깅할 수 있도록 하세요.
함수 시그니처에는 타입 주석을 붙여야 합니다. 그렇지 않은 경우, 가독성을 높이기 위해 좋은 변수 이름을 사용하세요.
새 모델 추가 문제
특정 모델을 추가하려면 New model addition 이슈를 열어 주세요.
GitHub에서 New model 라벨로 필터링하여 기존 모델 요청을 확인하고 추가할 수 있습니다.
이제 BrandNewLlama에 익숙해지는 좋은 시기입니다. 모델의 기술적 설계와 구현을 이해하려면 해당 모델의 연구 논문을 읽는 것이 도움이 됩니다. 이론적 세부 사항에 대해 지나치게 걱정할 필요는 없습니다. 대신 실용적인 측면에 초점을 맞추세요. 아래 질문을 참고로 하여 논문을 읽어 보세요.
- BrandNewLlama은 어떤 유형의 모델인가요? encoder, decoder, 또는 encoder-decoder 모델인가요?
- BrandNewLlama은 어떤 작업에 사용할 수 있나요?
- BrandNewLlama가 다른 모델과 어떻게 다른가요?
- Transformers에서 BrandNewLlama와 가장 유사한 모델은 무엇인가요?
- BrandNewLlama은 어떤 토크나이저를 사용하나요?
모델에 대해 더 자세히 알아보는 것 외에도, 아래 팁을 참고하여 모델을 더 빠르게 추가할 수 있습니다.
각 기여자는 Transformers에 모델을 추가하는 데 고유한 스타일과 워크플로우를 가지고 있습니다. 예를 들어, Gemma가 어떻게 추가되었는지 살펴보세요.
- 바퀴를 다시 발명하지 마세요! 기존 모델과 토크나이저를 탐색하여 복사하고 재사용할 수 있는 부분을 확인하는 데 시간을 투자하세요. Grep와 ripgrep는 이를 위한 훌륭한 도구입니다.
- 이것은 과학적 도전이라기보다 엔지니어링적 도전입니다. 모델의 이론적 측면보다는 더 실용적인 측면(예: 효율적인 디버깅 환경 설정)에 초점을 맞추세요.
- 도움을 요청하는 것을 주저하지 마세요! 우리는 여러분을 지원하기 위해 여기 있습니다. 🤗
개발 환경
Transformers 저장소에서 Fork 버튼을 클릭하여 작업할 자신의 사본을 만듭니다. 저장소를 로컬 디스크에 클론한 후 기본 저장소를 리모트로 추가합니다.
git clone https://github.com/[your Github handle]/transformers.git
cd transformers
git remote add upstream https://github.com/huggingface/transformers.git가상 환경을 생성하고 “dev” 또는 개발 의존성을 포함하여 라이브러리를 editable install로 설치합니다.
python -m venv .env
source .env/bin/activate
pip install -e ".[dev]"Transformers의 선택적 의존성이 증가함에 따라 이 명령이 실패할 수 있습니다. 이 경우 “quality” 의존성을 설치하세요. 또한 딥러닝 프레임워크가 설치되어 있는지 확인하세요.
pip install -e ".[quality]"cd .. 명령을 실행하여 상위 디렉터리로 이동한 후, 원래의 BrandNewLlama 저장소를 클론하고 설치합니다.
git clone https://github.com/org_that_created_brand_new_llama_org/brand_new_llama.git
cd brand_new_bert
pip install -e .Transformers 클론으로 돌아가 BrandNewLlama를 이식하기 시작하세요.
cd transformers원래 모델을 실행하기 위한 디버깅 환경은 두 가지가 있습니다. 노트북(Google Colab 또는 Jupyter) 또는 로컬 Python 스크립트입니다.
원래 모델을 실행하기 위해 GPU 환경을 설정하는 것은 비용이 많이 들 수 있으므로 권장하지 않습니다. 대신, 먼저 CPU 환경에서 작업하여 모델이 Transformers에서 정상적으로 작동하는지 확인하세요. 정상 작동이 확인되면, 그 다음에 GPU에서 검증할 수 있습니다.
Notebooks는 코드를 셀 단위로 실행할 수 있어 논리적 구성 요소를 분리하는 데 도움이 됩니다. 중간 결과를 저장할 수 있어 디버깅 사이클을 가속화할 수도 있습니다. 또한 다른 기여자와 협업할 때 notebooks를 공유할 수 있습니다.
단점은, 익숙하지 않다면 적응하는 데 시간이 좀 걸릴 수 있다는 것입니다.
모델 아키텍처가 기존 모델과 동일하다면, 기존 모델의 아키텍처를 재사용할 수 있으므로 체크포인트 변환으로 건너뛰세요.
아래 명령을 실행하여 새 모델에 대한 기본 정보를 입력하고 설문지를 완료하세요. 이 명령은 자동으로 일부 모델 코드를 생성하여 프로세스를 시작하며, 해당 코드를 수정해야 합니다.
transformers add-new-model-like
를 생성합니다
코드를 수정하기 전에 Transformers 팀의 피드백을 받고 진행 상황을 추적하기 위해 pull request를 생성하세요. pull request 제목을 [WIP] Add BrandNewLlama로 지정하여 작업이 진행 중임을 명확히 하세요.
메인 브랜치에서 설명이 되는 이름을 가진 브랜치를 생성하세요.
git checkout -b add_brand_new_bert
코드를 커밋한 후 main 브랜치를 fetch하고 rebase합니다.
git add . git commit git fetch upstream git rebase upstream/main
변경 사항을 브랜치에 push한 후 GitHub에서 pull request를 열려면 Compare & pull request를 클릭하세요. 작업이 진행 중임을 나타내기 위해 pull request를 draft로 열어 두세요.
git push -u origin a-descriptive-name-for-my-changes
질문, 피드백, 코멘트, 리뷰를 위해 pull request에 관련 Hugging Face 팀 멤버의 GitHub 핸들을 추가하세요. Files changed 탭을 클릭한 후, 라인 번호 왼쪽의 +를 클릭하여 코드의 특정 부분을 팀 멤버에게 지정하고 코멘트를 추가할 수 있습니다. 질문이나 문제가 해결되면 Resolve를 클릭하여 해당 이슈가 해결되었음을 표시하세요. 이렇게 하면 대화가 체계적이고 깔끔하게 유지됩니다.
작업은 주기적으로 커밋하고 푸시하며, 현재 main 브랜치에 맞게 업데이트하세요.
git fetch upstream git merge upstream/main
원본 체크포인트
원본 모델 구현을 먼저 살펴보고 작동 방식을 이해하는 데 시간을 할애해 보세요.
원본 모델 저장소에 문서가 부족하거나 코드베이스가 복잡한 경우 이는 어려울 수 있습니다. 하지만 이를 Transformers에 모델을 구현하기 위한 동기 부여로 삼아야 합니다. 여러분의 기여는 모델이 모든 사용자에게 더 접근하기 쉽고 사용자 친화적이 되도록 만듭니다!
다음 단계를 수행하여 원본 저장소에 익숙해지세요.
- 사전 학습된 가중치를 찾습니다.
- pretrained weights를 모델에 로드하는 방법을 파악하세요.
- 모델과 독립적으로 토크나이저를 실행하는 방법을 파악하세요.
- 필요한 클래스와 함수를 파악하기 위해 Trace one forward pass를 따라가 보세요. 구현해야 할 클래스와 함수는 아마 이것들뿐일 것입니다.
- 모델의 모든 중요한 구성 요소(모델 클래스, 모델 하위 클래스, self-attention 레이어 등)를 찾아보세요.
- 원본 저장소에서 모델을 디버깅하는 방법을 파악하세요. print 문장을 추가하거나, ipdb와 같은 인터랙티브 디버거 또는 PyCharm와 같은 효율적인 통합 개발 환경(IDE)을 사용할 수 있습니다.
마지막 점은 특히 중요합니다. Transformers에서 모델을 재구현하려면 원래 모델 내부에서 일어나는 일을 충분히 이해해야 하기 때문입니다. 원본 저장소에서 문제가 발생하면 자유롭게 이슈와 pull request를 열어 주세요.
좋은 첫 단계는 작은 사전 학습된 체크포인트를 로드하고, 입력의 예시 정수 벡터로 단일 포워드 패스를 재현해 보는 것입니다. 예를 들어, 의사 코드로는 다음과 같이 작성할 수 있습니다.
model = BrandNewLlamaModel.load_pretrained_checkpoint("/path/to/checkpoint/")
input_ids = [0, 4, 5, 2, 3, 7, 9] # vector of input ids
original_output = model.generate(input_ids)디버깅
문제가 발생하면 원래 모델의 코드베이스에 따라 다음 디버깅 전략 중 하나를 선택해야 합니다.
이 전략은 코드가 eager mode에서 쉽게 실행될 수 있는 경우와 같이 원래 모델을 더 작은 하위 구성 요소로 분해하는 데 기반합니다. 구현 난이도는 더 높지만, 이 접근 방식에는 몇 가지 장점이 있습니다.
- 원본 모델과 구현을 나중에 비교하는 것이 더 쉽습니다. Transformers의 구현에서 각 개별 구성 요소가 해당 구성 요소와 일치하는지 자동으로 검증할 수 있습니다. 이는 print 문에 기반한 시각적 비교에 의존하는 것보다 좋습니다.
- 전체 모델을 이식하는 것보다 개별 구성 요소를 이식하는 것이 더 쉽습니다.
- 모델을 더 작은 부분으로 나누면 모델의 작동 방식을 이해하기가 더 쉽습니다.
- 컴포넌트별 테스트를 통해 코드를 변경할 때 후속 단계에서 회귀 문제를 방지하는 것이 더 쉽습니다.
모델을 더 작은 구성 요소로 분해하는 좋은 예로는 ELECTRA 통합 검사를 참고하세요.
…이 너무 복잡하거나, 중간 컴포넌트만 컴파일 모드로 실행할 수 있거나, 모델을 더 작은 하위 컴포넌트로 분리하는 데 시간이 너무 많이 걸리거나(아마도 불가능할 수도 있음) 하는 경우 이 전략은 실행 가능합니다.
예를 들어, T5의 MeshTensorFlow 구현은 너무 복잡하여 모델을 하위 구성 요소로 분해하는 간단한 방법을 제공하지 않습니다. 이러한 상황에서는 print 문장을 확인하는 데 의존해야 합니다.
어떤 전략을 선택하든, 처음에는 초기 레이어를, 마지막에는 최종 레이어를 디버깅하는 것이 좋습니다. 다음 레이어의 출력을 print 문이나 서브컴포넌트 함수를 사용하여 아래 순서대로 가져오세요.
- 모델에 전달되는 입력 ID
- 워드 임베딩
- 첫 번째 Transformer 레이어의 입력
- 첫 번째 Transformer 레이어의 출력
- 다음 n-1개의 Transformer 레이어의 출력
- 전체 모델의 출력
입력 ids는 input_ids = [0, 4, 4, 3, 2, 4, 1, 7, 19]와 같은 정수 배열이면 됩니다.
레이어 출력은 종종 다차원 float 배열로 구성됩니다.
[[
[-0.1465, -0.6501, 0.1993, ..., 0.1451, 0.3430, 0.6024],
[-0.4417, -0.5920, 0.3450, ..., -0.3062, 0.6182, 0.7132],
[-0.5009, -0.7122, 0.4548, ..., -0.3662, 0.6091, 0.7648],
...,
[-0.5613, -0.6332, 0.4324, ..., -0.3792, 0.7372, 0.9288],
[-0.5416, -0.6345, 0.4180, ..., -0.3564, 0.6992, 0.9191],
[-0.5334, -0.6403, 0.4271, ..., -0.3339, 0.6533, 0.8694]]],모든 Transformers 모델 출력은 1e-3의 정밀도 또는 오차 허용 범위를 가져야 합니다. 이는 다른 라이브러리 프레임워크를 사용할 때 발생하는 출력 차이까지 고려한 것입니다. 원본 모델의 중간 출력을 Transformers 구현과 비교하여 거의 동일한지 확인하세요. 이 단계에서는 효율적인 디버깅 환경이 필수적입니다.
효율적인 디버깅 환경을 위한 몇 가지 팁을 소개합니다.
중간 결과를 디버깅하려면 원래 모델 저장소가 사용하는 머신러닝 프레임워크에 따라 다릅니다. PyTorch의 경우, 원래 모델을 더 작은 하위 구성 요소로 분해하여 중간 값을 가져오도록 스크립트를 작성해야 합니다.
10초 이상 걸리는 큰 체크포인트보다 작은 사전 학습된 체크포인트로 디버깅하는 것이 더 빠릅니다. 큰 체크포인트만 사용할 수 있는 경우, 무작위로 초기화된 가중치를 가진 더미 모델을 생성하고 해당 가중치를 저장한 후 Transformers 구현과 비교해 보세요.
모델의 forward pass를 호출하는 가장 간단한 방법을 찾으세요. 이상적으로는 이 함수(
predict,evaluate,forward, 또는__call__로 명명될 수 있음)는 forward pass를 한 번만 호출해야 합니다. forward pass를 여러 번 호출하는 함수는 디버깅이 더 어렵습니다.토큰화를 forward pass와 분리합니다. forward pass에서 문자열 입력이 input ids로 변환되는 위치를 찾아서 여기서 시작합니다. 입력 문자열 대신 input ids를 직접 입력하도록 작은 스크립트를 작성하거나 기존 코드를 수정해야 할 수 있습니다.
모델이 학습 모드에 있지 않은지 확인하세요. 모델 내의 여러 dropout 레이어로 인해 무작위 출력이 발생할 수 있습니다. 디버깅 환경의 forward pass는 dropout 레이어가 사용되지 않도록 결정론적이어야 합니다.
original checkpoint를 실행할 수 있게 되면, 이제 Transformers용 모델 코드를 조정하기 시작할 준비가 된 것입니다.
모델 코드 수정
transformers add-new-model-like 명령을 실행하면 모델 및 구성 파일이 생성되었어야 합니다.
src/transformers/models/brand_new_llama/modeling_brand_new_llama.pysrc/transformers/models/brand_new_llama/configuration_brand_new_llama.py
modeling.py 파일에 자동 생성된 코드는 decoder-only 모델이라고 답한 경우 Llama와 동일한 아키텍처를, encoder-decoder 모델이라고 답한 경우 BART와 동일한 아키텍처를 가집니다. 생성된 코드는 시작점일 뿐입니다. 새로운 모델에 대한 연구를 바탕으로, 생성된 코드를 수정하여 해당 모델에 특화된 변경 사항을 구현해야 합니다. 여기에는 self-attention 레이어, normalization 레이어의 순서 등의 변경이 포함될 수 있습니다.
모델 초기화
이 시점에서 코드가 깔끔하거나 완전히 정확하지 않아도 됩니다. 먼저 초안을 빠르게 작성한 후 반복적으로 개선하는 것이 더 효율적입니다. 가장 중요한 것은 모델이 Transformers에서 인스턴스화될 수 있다는 것입니다. 아래 명령은 무작위 가중치로 설정에서 모델을 생성하여 __init__ 메서드가 정상적으로 작동하는지 확인합니다.
from transformers import BrandNewLlama, BrandNewLlamaConfig
model = BrandNewLlama(BrandNewLlamaConfig())_init_weights 메서드에서 BrandNewLlamaPreTrainedModel의 무작위 초기화가 수행됩니다. 모든 리프 모듈은 구성 변수에 따라 초기화됩니다. 가중치나 그 .data에 대해 인플레이스 연산을 직접 호출하는 대신, transformers.initialization 모듈의 헬퍼를 사용하여 값을 설정하세요.
from transformers import initialization as init
def _init_weights(self, module):
"""Initialize the weights"""
if isinstance(module, nn.Linear):
init.normal_(module.weight, mean=0.0, std=self.config.initializer_range)
if module.bias is not None:
init.zeros_(module.bias)
elif isinstance(module, nn.Embedding):
init.normal_(module.weight, mean=0.0, std=self.config.initializer_range)
if module.padding_idx is not None:
init.zeros_(module.weight[module.padding_idx])
elif isinstance(module, nn.LayerNorm):
init.zeros_(module.bias)
init.ones_(module.weight)transformers.initialization 헬퍼를 통해 항상 가중치를 초기화하세요. module.bias.zero_() 또는 module.weight.data에 접근하는 모든 in-place 연산은 이미 로드된 파라미터를 표시하는 _is_hf_initialized 플래그를 우회합니다. from_pretrained()는 체크포인트 로드 후 _init_weights를 실행하므로, in-place 연산은 로드된 가중치를 무작위 값으로 조용히 덮어쓰게 됩니다. 이는 Transformers 모델에 대해 TRF012 규칙으로 강제됩니다.
from_pretrained() 실행 중 모델은 일반적으로
meta디바이스에서 초기화됩니다. 로더는 비영속 버퍼를 빈 텐서로 다시 생성하므로,__init__에서 할당된 값은 유지되지 않습니다. 로딩 후 올바른 값을 가지도록 이 버퍼들을_init_weights에서 초기화하세요. 예시로, BERT가 위치 ID와 토큰 유형 ID를 초기화하는 방식을 참고하세요.
모델에 맞게 조정해야 하는 경우 초기화 방식이 다르게 보일 수 있습니다. 자체 reset_parameters 메서드를 가진 서브모듈은 이를 직접 호출할 수 있습니다. 예를 들어, Wav2Vec2ForPreTraining은 마지막 두 개의 선형 레이어에서 nn.Linear를 초기화합니다. from_pretrained()가 _init_weights를 실행하는 동안 _is_hf_initialized 플래그를 존중하도록 torch.nn.init 함수를 패치하기 때문에 이 호출은 안전하며, 로드된 가중치가 덮어쓰여지지 않습니다.
def _init_weights(self, module):
"""Initialize the weights"""
if isinstance(module, Wav2Vec2ForPreTraining):
module.project_hid.reset_parameters()
module.project_q.reset_parameters()Transformers로 체크포인트 변환
원본 체크포인트는 Transformers와 호환되는 체크포인트로 변환되어야 합니다.
모델에 복사, 수정, 재사용할 기존 변환 스크립트를 찾아보세요!
모든 필수 가중치가 초기화되었는지 확인하고, 초기화에 사용되지 않은 모든 체크포인트 가중치를 출력하여 모델이 올바르게 변환되었는지 확인하세요.
변환 과정에서 잘못된 shape 문장이나 이름 할당을 만나실 수 있습니다. 이는 대부분 BrandNewLlamaConfig의 잘못된 매개변수, 잘못된 아키텍처, 구현의 init 메서드 내의 버그, 또는 체크포인트 가중치 중 하나를 전치(transpose)해야 하는 경우 때문입니다.
모든 체크포인트 가중치가 올바르게 로드될 때까지 Adapt the model code 섹션을 계속 반복하세요. 모델에서 체크포인트를 로드할 수 있게 되면 폴더에 저장하세요. 이 폴더에는 model.safetensors 파일과 config.json 파일이 포함되어야 합니다.
model.save_pretrained("/path/to/converted/checkpoint/folder")변환을 돕기 위해, 다음 섹션에서는 PyTorch 모델이 레이어 가중치를 저장하고 이름을 정의하는 방식을 간략히 설명합니다.
PyTorch 레이어 가중치 및 이름
PyTorch 기본 모델을 만들어 보면 레이어 이름이 어떻게 정의되고 가중치가 어떻게 초기화되는지 이해하는 데 도움이 됩니다.
from torch import nn
class SimpleModel(nn.Module):
def __init__(self):
super().__init__()
self.dense = nn.Linear(10, 10)
self.intermediate = nn.Linear(10, 10)
self.layer_norm = nn.LayerNorm(10)PyTorch 레이어 이름은 레이어의 클래스 속성 이름(dense, intermediate, layer_norm)으로 정의됩니다. SimpleModel의 인스턴스를 생성하여 모든 레이어에 무작위 가중치를 채웁니다.
model = SimpleModel()
print(model)
SimpleModel(
(dense): Linear(in_features=10, out_features=10, bias=True)
(intermediate): Linear(in_features=10, out_features=10, bias=True)
(layer_norm): LayerNorm((10,), eps=1e-05, elementwise_affine=True)
)특정 레이어의 가중치 값은 무작위로 초기화됩니다.
print(model.dense.weight.data)
tensor([[-0.0818, 0.2207, -0.0749, -0.0030, 0.0045, -0.1569, -0.1598, 0.0212,
-0.2077, 0.2157],
[ 0.1044, 0.0201, 0.0990, 0.2482, 0.3116, 0.2509, 0.2866, -0.2190,
0.2166, -0.0212],
[-0.2000, 0.1107, -0.1999, -0.3119, 0.1559, 0.0993, 0.1776, -0.1950,
-0.1023, -0.0447],
[-0.0888, -0.1092, 0.2281, 0.0336, 0.1817, -0.0115, 0.2096, 0.1415,
-0.1876, -0.2467],
[ 0.2208, -0.2352, -0.1426, -0.2636, -0.2889, -0.2061, -0.2849, -0.0465,
0.2577, 0.0402],
[ 0.1502, 0.2465, 0.2566, 0.0693, 0.2352, -0.0530, 0.1859, -0.0604,
0.2132, 0.1680],
[ 0.1733, -0.2407, -0.1721, 0.1484, 0.0358, -0.0633, -0.0721, -0.0090,
0.2707, -0.2509],
[-0.1173, 0.1561, 0.2945, 0.0595, -0.1996, 0.2988, -0.0802, 0.0407,
0.1829, -0.1568],
[-0.1164, -0.2228, -0.0403, 0.0428, 0.1339, 0.0047, 0.1967, 0.2923,
0.0333, -0.0536],
[-0.1492, -0.1616, 0.1057, 0.1950, -0.2807, -0.2710, -0.1586, 0.0739,
0.2220, 0.2358]]).변환 스크립트에서 무작위 가중치는 원래 체크포인트의 해당 레이어에서 가져온 정확한 가중치로 대체해야 합니다.
# retrieve matching layer weights with recursive algorithm
layer_name = "dense"
pretrained_weight = array_of_dense_layer
model_pointer = getattr(model, "dense")
model_pointer.weight.data = torch.from_numpy(pretrained_weight)무작위로 초기화된 가중치와 해당 사전학습 체크포인트 가중치의 shape과 name이 동일한지 확인합니다. shape에 대한 assert 문을 추가하고 체크포인트 가중치 이름을 출력합니다.
assert (
model_pointer.weight.shape == pretrained_weight.shape
), f"Pointer shape of random weight {model_pointer.shape} and array shape of checkpoint weight {pretrained_weight.shape} mismatched"
logger.info(f"Initialize PyTorch weight {layer_name} from {pretrained_weight.name}")shape 또는 name이 일치하지 않으면, 무작위로 초기화된 레이어에 잘못된 checkpoint weight를 할당했을 수 있습니다. shape가 올바르지 않은 이유는 BrandNewLlama의 파라미터가 원래 모델의 파라미터와 정확히 일치하지 않기 때문일 수 있습니다. 하지만 PyTorch 레이어 구현이 weight를 먼저 전치(transpose)하도록 요구하기 때문일 수도 있습니다.
forward pass를 구현합니다
모델이 올바르게 로드되면 다음으로 forward pass를 구현해야 합니다. 이는 몇 가지 입력을 받아 모델 출력을 반환합니다.
model = BrandNewLlamaModel.from_pretrained("/path/to/converted/checkpoint/folder")
input_ids = [0, 4, 4, 3, 2, 4, 1, 7, 19]
output = model.generate(input_ids).last_hidden_statesforward pass가 원래 모델의 출력과 완전히 일치하지 않거나 오류를 반환한다고 해서 낙담하지 마세요. forward pass가 오류를 발생시키지 않는지 확인하세요. 이는 종종 차원이 잘못되었거나 잘못된 데이터 유형이 사용되었기 때문입니다(torch.long 대신 torch.float32가 사용된 경우).
출력의 정밀도는 1e-3여야 합니다. 출력 형상과 출력 값이 동일하도록 하십시오. 출력이 동일하지 않은 일반적인 이유는 다음과 같습니다:
- 일부 레이어가 추가되지 않았습니다(활성화 레이어 또는 잔차 연결).
- 단어 임베딩 행렬은 연결되어 있지 않습니다.
- …
- Dropout은 forward pass 동안 적용됩니다.
model.training이False인지 확인하고self.training을 torch.nn.functional.dropout에 전달하여 이 오류를 수정하세요.
원본 모델과 구현한 모델의 forward pass를 비교하여 차이가 있는지 확인하세요. 이상적으로는 두 구현의 forward pass 중간 출력을 디버깅하여 출력하고, 원본 구현과 자신의 구현이 어디서 다른지 정확히 파악하는 것이 좋습니다.
- 두 구현 모두에서 하드코딩된
input_ids가 동일한지 확인하세요. input_ids의 첫 번째 변환(보통 단어 임베딩)의 출력이 동일한지 확인한 후, 마지막 레이어까지 순서대로 진행합니다.
두 구현 방식 간의 모든 차이는 구현에 존재하는 버그를 가리킵니다.
가장 효과적인 전략 중 하나는 두 구현 모두의 동일한 위치에 여러 개의 print 문을 추가한 후, 중간 출력 값이 동일하게 출력되는 print 문을 차례대로 제거하는 것입니다.
두 구현이 동일한 출력을 생성하는 경우, 출력이 1e-3의 정밀도 범위 내에 있는지 확인합니다.
torch.allclose(original_output, output, atol=1e-3)이것은 일반적으로 이 과정에서 가장 어려운 부분입니다. 여기까지 오셨다면 축하드립니다!
이 단계에서 막히거나 어려움을 겪고 있다면, 주저하지 말고 pull request에서 도움을 요청하세요.
모델 테스트 추가
모델이 작동하더라도, Transformers와의 호환성을 보장하기 위해 테스트를 추가해야 합니다. 테스트는 사용자가 특정 테스트를 통해 여러분의 작업을 이해하는 데 도움이 되며, 향후 변경 사항이 있을 때 모델이 깨지는 것을 방지하기 때문에 중요합니다.
Cookiecutter는 모델에 대한 테스트 파일을 추가했어야 합니다. 아래 테스트 파일을 실행하여 모든 공통 테스트가 통과하는지 확인하세요.
pytest tests/models/brand_new_llama/test_modeling_brand_new_llama.py
새 모델을 Transformers에 구현할 때 이전에 사용했던 디버깅 스크립트와 동일한 목적을 수행하므로 통합 테스트를 먼저 추가해야 합니다. 해당 모델 테스트의 템플릿인 BrandNewLlamaModelIntegrationTests는 Cookiecutter에 의해 추가되었으므로 내용을 채워 넣어야 합니다. 통과를 확인하려면 다음 명령을 실행하세요.
RUN_SLOW=1 pytest -sv tests/models/brand_new_llama/test_modeling_brand_new_llama.py::BrandNewLlamaModelIntegrationTests
SET RUN_SLOW=1 pytest -sv tests/models/brand_new_llama/test_modeling_brand_new_llama.py::BrandNewLlamaModelIntegrationTests
BrandNewLlama에 고유한 모든 기능은 BrandNewLlamaModelTester/BrandNewLlamaModelTest의 별도 테스트에서 테스트해야 합니다. 이 테스트는 자주 간과되지만, 다음과 같은 이유로 매우 중요합니다:
- 모델의 새로운 기능이 어떻게 작동하는지 보여줌으로써, 과정에서 습득한 지식을 커뮤니티에 전달하는 데 도움이 됩니다
- 미래의 기여자들은 이러한 특수 테스트를 실행하여 모델의 변경 사항을 빠르게 테스트할 수 있습니다.
토크나이저 구현
최고의 성능을 제공하기 위해 빠른 토크나이저(PreTrainedTokenizerFast)를 추가하는 것을 권장합니다. PreTrainedTokenizerFast를 추가하는 방법에 대한 도움이 필요하시면 PR에서 @ArthurZucker 또는 @itazap를 태그로 지정해 주세요.
모델은 일단 제쳐 두고, 이제 토크나이저에 집중해 보겠습니다. 토크나이저는 Transformers의 기존 토크나이저와 동일하거나 매우 유사해야 합니다.
원래 저장소에서 원본 토크나이저 파일을 찾아 구현에 로드하세요. 문자열을 입력받아 input_ids를 반환하는 스크립트를 원래 저장소에 생성하세요. 의사 코드는 아래 코드와 유사해야 합니다.
input_str = "This is a long example input string containing special characters .$?-, numbers 2872 234 12 and words."
model = BrandNewLlamaModel.load_pretrained_checkpoint("/path/to/checkpoint/")
input_ids = model.tokenize(input_str)input_ids만 반환하도록 원본 저장소의 클론에서 기존 tokenizer를 수정하거나, 원본 저장소에서 올바른 tokenizer 함수를 찾아야 할 수 있습니다. tokenizer 스크립트는 다음과 유사한 형태여야 합니다.
from transformers import BrandNewLlamaTokenizer
input_str = "This is a long example input string containing special characters .$?-, numbers 2872 234 12 and words."
tokenizer = BrandNewLlamaTokenizer.from_pretrained("/path/to/tokenizer/folder/")
input_ids = tokenizer(input_str).input_ids두 구현 모두 동일한 input_ids를 가질 경우, 토크나이저 테스트 파일을 추가합니다. 이 파일은 모델링 테스트 파일과 유사합니다. 토크나이저 테스트 파일에는 몇 가지 하드코딩된 통합 테스트를 포함해야 합니다.
이미지 프로세서 구현
Image processor는 이제 백엔드 기반 아키텍처를 사용합니다. 기본 백엔드는 TorchvisionBackend이며, torchvision 라이브러리를 사용하여 GPU에서 이미지 처리를 수행할 수 있습니다. PIL/NumPy 대안 백엔드(PilBackend)도 제공됩니다. 두 백엔드 모두
image_processing_backends에서 가져옵니다. 도움이 필요하시면 @yonigozlan에게 태그를 달아 주세요.
이 예시에는 이미지 프로세서가 포함되어 있지 않지만, 모델이 이미지 입력을 필요로 한다면 구현해야 할 수 있습니다. 이미지 프로세서는 이미지를 모델에 적합한 형식으로 변환하는 역할을 합니다. 새로운 이미지 프로세서를 구현하기 전에, Transformers 라이브러리의 기존 이미지 프로세서 중 재사용할 수 있는 것이 있는지 확인해 보세요. 많은 모델이 유사한 이미지 처리 기법을 공유하기 때문입니다. 또한, 기존 구성 요소를 재사용하기 위해 이미지 프로세서에도 modular을 사용할 수 있습니다.
새로운 이미지 프로세서 구현이 필요한 경우, 각 모델에는 두 개의 프로세서 파일이 있습니다:
image_processing_<model>.py: 기본 torchvision 기반 프로세서(<Model>ImageProcessor)로, TorchvisionBackend를 상속합니다. 이는 기존 “fast” 프로세서를 대체합니다.image_processing_pil_<model>.py: PIL/NumPy 대안 프로세서(<Model>ImageProcessorPil)로, PilBackend를 상속합니다. 이 파일은 기존 “slow” 프로세서를 대체합니다.
torchvision 백엔드 파일은 또한 PIL 파일이 가져오는 모든 사용자 정의 kwargs 클래스를 정의합니다. 두 파일 모두 @auto_docstring 데코레이터를 사용합니다. 수동으로 클래스 docstring을 추가하지 마세요. 단계별 안내와 완전한 예제는 IMAGE_PROCESSOR_REFACTORING_GUIDE.md를 참조하세요.
tests/models/your_model_name/test_image_processing_your_model_name.py에 이미지 프로세서에 대한 테스트를 추가하세요. 이 테스트들은 다른 이미지 프로세서의 테스트와 유사해야 하며, 이미지 프로세서가 이미지 입력을 올바르게 처리하는지 확인해야 합니다. 이미지 프로세서에 고유한 기능이나 처리 방법이 포함된 경우, 해당 항목에 대한 구체적인 테스트도 추가해야 합니다.
프로세서 구현
모델이 텍스트와 이미지와 같은 여러 모달리티를 입력으로 받는 경우, 프로세서(processor)를 추가해야 합니다. 프로세서는 모델에 전달하기 전에 서로 다른 모달리티의 전처리(preprocessing)를 중앙에서 관리합니다.
프로세서의 __call__ 함수 내에서 각 입력 유형을 올바르게 처리하도록 해당 모달리티에 맞는 프로세서를 호출해야 합니다. 예상되는 구조를 이해하려면 라이브러리의 기존 프로세서를 확인해 보세요. Transformers는 __call__ 함수 시그니처에 다음 규칙을 사용합니다.
def __call__(
self,
images: ImageInput = None,
text: Union[TextInput, PreTokenizedInput, list[TextInput], list[PreTokenizedInput]] = None,
audio=None,
videos=None,
**kwargs: Unpack[YourModelProcessorKwargs],
) -> BatchFeature:
...YourModelProcessorKwargs는 일반적인 처리 인자와 특정 프로세서가 필요로 할 수 있는 추가 인자를 모두 포함하는 TypedDict입니다.
tests/models/your_model_name/test_processor_your_model_name.py에 프로세서에 대한 테스트를 추가하세요. 이 테스트들은 다른 프로세서의 테스트와 유사해야 하며, 프로세서가 서로 다른 모달리티를 올바르게 처리하는지 확인해야 합니다.
통합 테스트
모델과 토크나이저를 갖추셨으니, 이제 모델과 토크나이저에 대한 end-to-end 통합 테스트를 tests/models/brand_new_llama/test_modeling_brand_new_llama.py에 추가하세요.
테스트는 모델이 의도대로 작동하는지 보여주기 위해 의미 있는 텍스트-텍스트 예시를 제공해야 합니다. 예를 들어, 원문-번역문 쌍, 기사-요약 쌍, 질문-답변 쌍을 포함할 수 있습니다.
checkpoint가 다운스트림 작업으로 파인튜닝되지 않은 경우, 모델 테스트만으로도 충분합니다.
마지막으로, 모델의 내부 텐서에 .to(self.device) 문장을 추가하여 테스트가 GPU에서 실행될 수 있도록 하십시오. GPU에 접근할 수 없다면, 저희가 대신 처리해 드립니다.
문서 추가
모델은 사용자가 사용법을 알아야만 유용합니다. 따라서 문서와 docstring을 추가하는 것이 중요합니다. Cookiecutter는 모델에 대한 정보를 채워 넣을 수 있는 템플릿 파일 docs/source/model_doc/brand_new_llama.md를 추가했습니다.
이것은 일반적으로 사용자가 모델과 처음 상호작용하는 부분이므로, 문서가 명확하고 간결해야 합니다. 모델 사용 예시를 추가하는 것이 매우 유용한 경우가 많습니다.
src/transformers/models/brand_new_llama/modeling_brand_new_llama.py에 docstring이 추가되었는지, 그리고 필요한 모든 입력과 출력이 포함되어 있는지 확인하세요. 문서 및 docstring 작성에 대한 가이드를 검토하세요.
리팩터링
이제 정리하여 코드의 스타일이 라이브러리 나머지 부분과 일치하는지 확인합니다. 잘못된 스타일을 자동으로 수정하려면 다음 명령을 실행합니다.
make style
코드 스타일이 품질 검사를 통과하는지 확인하려면 아래 명령을 실행하세요.
make check-repo
Transformers의 엄격한 디자인 테스트로 인해 pull request에 다른 실패하는 테스트나 체크(문서 문자열 누락 또는 잘못된 이름 지정)가 있을 수 있습니다. 이러한 문제에서 막혔다면 도움을 드릴 수 있습니다.
코드가 올바르게 실행되는지 확인한 후, 가독성을 높이거나 더 깔끔하게 만들기 위해 리팩터링을 수행할 수 있습니다.
Hub에 업로드
모든 체크포인트를 Hub로 변환하여 업로드합니다. 모델에 대한 투명성과 맥락을 더 제공하기 위해 모델 카드를 추가합니다. 모델 카드에는 체크포인트의 특정 특성, 모델 학습 방법, 사용법에 대한 코드 예제가 강조되어야 합니다.
많은 경우, 사용자가 실행할 수 있는 인터랙티브 노트북을 추가하는 것은 모델을 추론에 사용하거나 다운스트림 작업으로 파인튜닝하는 방법을 보여주는 훌륭한 방법입니다. 필수 사항은 아니지만, 노트북을 포함하면 모델의 채택률을 높이는 데 도움이 될 수 있습니다.
모델에 적합한 이름을 결정하고 모델을 업로드하는 데 필요한 액세스 권한을 얻기 위해 Transformers 팀과도 상담해야 합니다.
모델을 업로드하려면 push_to_hub() 메서드를 사용하세요.
brand_new_bert.push_to_hub("brand_new_llama")모델을 Hub에 업로드하는 방법에 대한 자세한 내용은 공유 가이드를 참조하세요.
모델 병합
드디어 pull request를 병합하고 Transformers에 모델을 공식적으로 추가할 준비가 되었습니다. 모든 테스트가 통과하고 모든 코멘트와 피드백이 처리되었는지 확인하세요.
Transformers에 새 모델을 추가하신 것을 축하드립니다! 🥳
이것은 매우 중요한 기여입니다. 여러분의 작업은 전 세계 개발자와 연구자들이 Transformers를 더 쉽게 활용할 수 있게 합니다. 여러분의 기여를 자랑스럽게 여기고, 이 성과를 커뮤니티와 공유하세요!
참고
- 모델 구조 규칙 — 모든
modeling_*.py및configuration_*.py파일에 적용되는 정적 규칙입니다. PR을 열기 전에make typing을 실행하여 이를 확인하세요. - Pull request 검사 — PR에서 실행되는 CI 검사의 전체 참고 자료 및 통과 방법.