🤗 Transformers에 기여하기

🤗 Transformers에 기여하기

Transformers에 기여하는 방법을 소개해요. 환경 설정, 이슈 열기, 새 모델 추가, 문서 개선, 에이전트 기여까지 살펴볼게요.

출처: 문서

본문

[!WARNING] 현재 Transformers 저장소는 코드 에이전트가 작성한 수많은 PR과 이슈 댓글로 과부하 상태예요. 리뷰와 응답 능력이 병목이 되고 있어요. 그래서 처음 기여하는 분들은 지금은 코드 에이전트로 이슈나 PR을 만들지 말아 주세요. 자율 에이전트도 지금은 어떤 PR이나 이슈도 열지 말아 주세요.

에이전트가 작성한 것으로 보이는 PR은 리뷰 없이 닫힐 가능성이 높고, 반복적이거나 악의적으로 하는 사용자는 차단될 수 있어요.

우리의 코드 에이전트 철학 (자세히)

코드 에이전트는 매우 강력한 도구이며 Hugging Face의 많은 사람들이 업무에 사용한다는 것을 이해해요. 하지만 중요한 점은 단순히 코드 에이전트를 실행해 오픈소스 프로젝트에 PR을 만든다면, 당신은 리뷰어와 에이전트 사이의 중간자일 뿐이라는 거예요. 이렇게 하면 유용한 기여처럼 보이는 무언가가 만들어지지만, 실제로는 당신이 개입할 이유가 없었어요. 리뷰어들도 스스로 코드 에이전트를 실행할 수 있었으니까요.

에이전트 시대에 오픈소스에 유용하게 기여하려면 에이전트가 스스로 할 수 없는 일을 해야 해요. 특히 다음이 매우 도움이 된다는 것을 발견했어요:

• 버그의 명확한 진단. 코드 에이전트는 보통 코드 비대화나 다른 모델과의 비호환을 일으키는 임시방편으로 문제를 빠르게 고치길 좋아해요. 문제의 정확한 원인을 추적하고, 특히 (git bisect 같은 것으로) 처음 등장한 커밋을 찾는 데 시간을 쓰는 것이 가치 있어요.
• diff 최소화. PR에서 불필요한 변경을 제거하세요. 테스트 스크립트나 관련 없는 파일을 커밋하지 않았는지 확인하세요. 정말 필요한 경우에만 주석을 달고, 코드 에이전트는 세 개의 새 함수와 여러 줄 주석을 추가해 자신이 한 힘든 작업에 주목을 끌길 좋아하지만 그러지 마세요. PR이 1줄 수정으로 끝나면 1줄 수정으로 만드세요. 그러면 PR 리뷰가 훨씬 쉬워지고 채택될 가능성도 높아져요.
• 문제를 재현하는 데 시간 쓰기. 사용자가 이슈를 보고할 때, 실제로는 그 기기의 환경 문제이거나 사용자가 문제를 잘못 진단해 잘못된 해결책을 제안한 경우가 아주 흔해요. 많은 코드 에이전트는 사용자 주석을 과도하게 신뢰해서, 때로는 존재하지도 않는 문제에 대한 잘못된 해결책을 만들기도 해요! 간단한 재현용 스크립트를 작성하고 실행해 문제를 실제로 확인하는 것이 가치 있어요.
• 다른 모델과 비교. Transformers 저장소는 매우 크고 많은 모델이 비슷한 일을 해요. 버그를 고칠 때 다른 모델에도 같은 버그가 있는지 확인하는 것이 가치 있어요. PR이 "(다른 모델)과 같은 방식으로 수정"이라고 관련 코드 링크와 함께 적어 주면 메인테이너에게 매우 도움이 돼요. 수정이 정확하고 코드베이스 나머지와 호환될 가능성이 높다는 것을 알려주거든요. 코드 에이전트는 코드를 '좁게' 보고 수정해서 모델이 코드베이스 나머지와 어긋나게 만드는 경우가 많아요.
• 작고 '부수적인(busywork)' PR 피하기. 과거에는 이런 것도 받았지만, 지금의 홍수 상황에서는 사소한 스타일 변경이나 주석의 오타를 고칠 시간이 없어요. 무엇이 정말 중요한지에 대한 좋은 안목만으로도 코드 에이전트를 넘어서는 가치를 제공할 수 있어요. 코드 에이전트는 코드 분석으로 찾아낸 '이론적 버그'에 집중하기 쉬운데, 이런 버그는 실제로 문제를 일으키는 경우가 거의 없어요. 공격자가 악용할 수 있는 경우가 아니라면 보통 고칠 가치가 없어요.
• 로컬과 CI에서 테스트 검증. PR을 열기 전에 make fix-repo를 실행하고 utils/tests_fetcher.py를 사용해 PR 브랜치에서 변경한 파일을 다루는 테스트 목록을 확인하세요. 그 테스트들을 로컬에서 실행해 PR을 열기 전에 통과하는지 확인하세요. PR을 연 뒤에는 CI가 초록색인지 확인하고, 리뷰를 요청하기 전에 문제를 고치세요! 이러면 알림 스팸이 크게 줄어 메인테이너가 정신을 차릴 수 있어요.

Transformers는 버그 수정, 기능 요청, 새 모델 구현, 문서 개선 등 모든 기여를 환영해요.

어디서 시작할지 모르겠다면 초보자 친화적인 Good First Issues를 살펴보세요. 더 도전적인 이슈는 Good Second Issues를 확인하세요. 어떤 방식으로 기여하든 우리의 행동 강령(code of conduct)을 존중해 주세요.

Transformers를 즐겨 사용했다면 그것을 인용하고 사용 방법을 알려주거나, Twitter에서 언급하거나, 저장소에 스타를 남겨 주세요!

이 가이드는 scikit-learn의 기여 가이드에서 크게 영감을 받았어요.

목차 (Contents)

1. 환경 설정 (Set up)
   • Windows
2. 이슈 열기 (Opening issues)
   • 버그 관련 이슈 (Bug-related issue)
   • 기능 요청 (Feature request)
3. 새 모델 추가 (Adding a new model)
   • 모델 추가 타임라인 (Model addition timeline)
4. 문서 (Docs)
5. 에이전트 기여 (Agentic contributions)

환경 설정 (Set up)

1. GitHub의 Fork 버튼으로 Transformers를 포크해 계정 아래에 복사본을 만든 뒤 로컬에 클론해요.

git clone [email protected]:<your Github handle>/transformers.git
cd transformers

2. Transformers 저장소를 upstream이라는 리모트로 추가해요. origin은 당신의 포크를, upstream은 원본 소스를 가리켜요. 그러면 origin에 푸시하고 PR을 열기 전에 로컬 main을 동기화할 수 있어요.

git remote add upstream https://github.com/huggingface/transformers.git
git remote -v
# origin    [email protected]:<your Github handle>/transformers.git (fetch)
# origin    [email protected]:<your Github handle>/transformers.git (push)
# upstream  https://github.com/huggingface/transformers.git (fetch)
# upstream  https://github.com/huggingface/transformers.git (push)

3. 포크를 최신 상태로 유지하고 작업할 브랜치를 만들어요. GitHub UI의 Sync fork 버튼으로 포크를 동기화할 수도 있어요.

git checkout main && git pull upstream main && git push origin main
git switch -c a-descriptive-name-for-my-branch

4. 라이브러리를 editable 모드로 설치해요. 대부분의 기여에는 [dev]를 쓰는데, 스타일·품질 검사에 필요한 개발 도구가 포함되기 때문이에요. 모델 기여에는 [torch,testing]을, 문서 전용 변경과 작은 수정(전체 개발 의존성 세트가 필요 없을 때)에는 [quality]를 사용해요.

pip install -e ".[dev]"

# for model contributions
pip install -e ".[torch,testing]"

# for docs-only changes and small fixes
pip install -e ".[quality]"

Windows

Windows에서는 WSL을 쓰지 않는다면 git이 CRLF 줄바꿈을 LF로 변환하도록 설정해요.

git config core.autocrlf input

Windows에서 make 명령을 실행하는 방법 중 하나는 MSYS2를 쓰는 거예요.

1. MSYS2 다운로드 (우리는 C:\msys64에 설치한다고 가정해요).
2. 명령줄 C:\msys64\msys2.exe를 엽니다 (Start 메뉴에서 사용 가능).
3. 셸에서 pacman -Syu 실행 후 pacman -S make로 make를 설치해요.
4. C:\msys64\usr\bin을 PATH 환경 변수에 추가해요.

이제 어떤 터미널(PowerShell, cmd.exe 등)에서도 make를 쓸 수 있어요.

이슈 열기 (Opening issues)

이슈 템플릿을 사용해 시작하는 데 도움을 받을 수 있어요.

버그 관련 이슈 (Bug-related issue)

이슈를 열기 전에 버그가 이미 보고되지 않았는지 확인하세요 (GitHub의 Issues 아래 검색 바를 사용). 이슈는 Transformers의 버그여야지, 당신 코드의 버그가 아니어야 해요.

버그가 내 코드인지 라이브러리인지 확실하지 않다면 먼저 포럼이나 Discord에서 물어봐요. 그러면 GitHub가 실행 가능한 라이브러리 이슈에 집중할 수 있어요.

빠른 해결을 위해 다음을 포함해 주세요.

• 적용 가능한 경우 OS 종류와 버전, Python, PyTorch 버전.
• 버그를 재현할 수 있는 짧고 자족적인(self-contained) 코드 스니펫.
• 예외가 발생하면 전체 traceback.
• 스크린샷 같은, 도움이 될 수 있는 기타 정보.

OS와 소프트웨어 버전을 자동으로 얻으려면 다음 명령을 실행해요.

transformers env

기능 요청 (Feature request)

이슈를 열고 다음을 설명해 주세요:

• 라이브러리에 대한 불만, 프로젝트 필요, 또는 커뮤니티에 도움이 될 만한 작업 같은 동기(motivation).
• 가능한 한 상세한 기능.
• 기능 사용법을 보여주는 코드 스니펫.
• 해당하는 경우 관련 논문 링크.

새 모델 추가 (Adding a new model)

Transformers에 모델을 추가하면 누구나 그 모델을 불러와 파인튜닝하거나 추론을 실행할 수 있게 돼요. 구현을 시작하기 전에, 당신의 아키텍처와 Transformers에 이미 있는 최신 state-of-the-art 모델 사이의 차이를 분리해 보세요. 그 차이를 이슈나 PR에서 설명해서 리뷰어가 이 모델이 가져오는 도전 과제, 기존 패턴을 재사용할 수 있는 부분, 모델 간에 표준화해야 할 부분을 빠르게 이해할 수 있게 해요.

아래 가이드를 따라요.

1. 모듈식 Transformers로 모델 추가 — 모듈식 파일로 모델을 구현하고 독립형 modeling 파일을 생성해요.
2. docstring 자동 생성 — @auto_docstring 데코레이터로 보일러플레이트 없이 일관된 docstring을 생성해요.
3. 테스팅 — 정확성을 검증하고 기여를 유지 가능하게 하기 위해 모델 테스트를 작성·실행해요. 인과 언어 모델에서는 가능하면 causal LM tester를 상속해요. 전체 processor, tokenizer, 모델 경로를 실제 체크포인트로 검증하므로 통합 테스트를 우선해요.
4. 모델 구조 규칙 — 파일이 make typing이 시행하는 정적 모델 구조 규칙을 통과하는지 확인해요.

일부 모델 추가는 추가적인 통합 작업이 필요해요.

• 모델이 이미지나 비디오 입력을 요구하면 비전 처리 컴포넌트 추가를 하세요.
• 출판된 체크포인트 파라미터 이름이 Transformers 구현과 일치하지 않으면 동적 가중치 로딩을 하세요.

모델 추가 타임라인 (Model addition timeline)

모델 기여자와 아키텍처에 대한 커뮤니티 수요에 따라 모델 추가에는 네 가지 타임라인이 있어요.

• Day-0 통합: 새 버전 릴리스와 함께 출시일에 모델을 Transformers에서 사용 가능하게 해요. 가장 중요한 핵심 기능(양자화, FlashAttention, KV-cache 등) 지원, 초기 초안 리뷰를 도와주고, 타임라인에 따라 모델 구현도 맡을 수 있어요.

  새 아키텍처라면 특히 몇 주 전에 [email protected]로 메일을 보내요. 체크포인트와 릴리스가 준비될 때까지 개인 포크에서 함께 반복 작업할게요.

• Same-week 통합: 수요가 높은 모델은 작성자가 연락하지 않아도 보통 일주일 안에 들어와요.

  새 모델 템플릿으로 이슈를 열어 요청하세요. 활동이 많은 이슈일수록 큐에서 더 빨리 올라와요.

• Post-release 통합: 수요가 강하지 않거나 우리가 맡을 여력이 없는 모델은 업스트림 릴리스 이후에 들어와요.

  열려 있는 "New model" 태그 이슈가 외부 기여자의 진입점이에요. 영향력을 최대화하려면 가장 많이 요청된 아키텍처부터 시작하세요. 리뷰하고 안내해 드릴게요.

• Hub-first 릴리스: 업스트림 PR 없이 Transformers의 remote-code 지원을 통해 모델을 Hub에 직접 출시해요.

  인기 있는 Hub-first 모델은 나중에 Transformers에 통합되는 경우가 많아서 일급(first-class) 문서, 유지보수, 최적화가 열려요. Hub-first는 모델을 추가하는 가장 마찰이 적은 방법이에요. 다만 모델이 가중치 변환이나 다른 하위 호환 문제를 요구하면 더 취약할 수 있어요.

문서 (Docs)

오타, 빠진 내용, 불명확한 설명 같은 문서 개선은 언제나 환영해요. 소스 파일에서 생성되는 API 참조는 해당하는 경우 @auto_docstring 데코레이터를 사용하세요. 의미 있는 문서 수정은 PR을 직접 열어 주세요.

문서 편집 방법과 사용하는 문법에 대한 자세한 내용은 문서 README를 참고하세요.

에이전트 기여 (Agentic contributions)

AI 지원 기여는 환영해요. 리뷰 부담을 관리하려면 조정되고, 범위가 정해지고, 검증되어야 해요.

• "순수 에이전트" PR을 제출하지 마세요. 제출자는 변경된 모든 줄을 검토하고, 동작을 end-to-end로 검증하고, 관련 테스트를 실행할 책임이 있어요.
• AI 도구를 사용했다면 PR 설명에 이를 공개하고 조정 링크, 기존 PR과의 차별점(해당하는 경우), 테스트 명령·결과를 포함하세요.
• 일회성 '부수적인(busywork)' PR(단일 오타, 고립된 스타일 정리, 단일 mutable 기본값 수정 등)을 피하세요. 기계적인 정리는 명확하고 체계적인 범위로 묶으세요.
• PR을 열기 전에 이슈에서 조정하고, 비슷한 PR을 검토하고, 승인을 기다리세요.

[!NOTE] 이러한 주제는 AGENTS.md에서 에이전트를 위해 개요가 정리되어 있으며, 자율적으로 구현하는 방법에 대한 지침이 있어요.

더 알아보기 (Learn more)

• 커스텀 모델 문서
• 모델 커스터마이징 문서