PEFT에 기여하기

PEFT에 기여를 환영합니다. 기여를 계획하고 계신 경우, 프로세스가 원활하게 진행될 수 있도록 이 문서를 읽어 주세요.

PR을 열기 전에 논의하고 승인을 받으세요

Pull request(초안 포함)를 열기 전에 huggingface/peft에서 이슈를 열거나 기존 이슈를 찾아 제안한 기여 사항에 대해 논의하세요. 이미 존재하는 이슈가 있고 누군가가 해당 이슈를 작업 중이거나 작업 의사를 밝히거나 열린 PR이 있는 경우, 별도의 PR을 제출하지 마세요. PEFT 유지보수자 또는 Hugging Face 멤버가 제안을 명시적으로 승인할 때까지 기다리세요. 이슈를 열 경우, 설명의 길이와 복잡도는 이슈의 복잡도와 비례해야 합니다. 긴 설명보다 재현 스크립트가 포함된 짧은 설명이 더 가치 있는 경우가 많습니다.

승인 댓글에는 /peft-triage approved 메시지가 포함되어 있습니다. 할당된 기여자의 이름을 추가로 명시할 수 있으며, 예를 들어 /peft-triage approved username 또는 /peft-triage approved @username와 같습니다. 자신에게 할당되지 않은 이슈에 대해 PR을 열면 해당 PR이 폐기됩니다.

PR 설명에 #123, huggingface/peft#123, 또는 https://github.com/huggingface/peft/issues/123를 사용하여 승인된 공개 이슈를 링크하세요. 예외적으로, 유지보수자는 별도의 승인 코멘트 없이 전체 GitHub URL로 참조할 수 있는 특정 장기 진행 중인 토론을 지정할 수 있습니다. 여러 이슈나 토론을 참조하는 경우, 유효한 참조 하나만 있으면 충분합니다.

자동화 워크플로가 승인된 공개 이슈나 토론이 있는지 PR을 확인합니다. 유효한 참조가 없는 PR은 설명과 함께 자동으로 닫힙니다. 이슈 승인을 얻고, PR 설명을 업데이트한 후, 동일한 PR을 다시 열 수 있습니다. 대체 PR을 생성하지 마세요. PR이 잘못 닫혔다고 생각되면 PR에서 유지보수자를 멘션하세요.

독립적인 stale bot은 triaged 라벨이 붙어 있더라도 비활성 항목을 닫을 수 있습니다. 유지보수자가 기여를 놓쳤다고 생각되면 ping을 보낼 수 있지만, 2주간의 비활성 기간이 지나기 전에는 보내지 마세요.

설치

기여를 시작하려면 다음 단계를 따르세요:

저장소 페이지의 ‘Fork’ 버튼을 클릭하여 repository를 포크하세요. 그러면 GitHub 사용자 계정 아래에 코드의 사본이 생성됩니다.
포크를 로컬 디스크에 클론하고 기본 저장소를 리모트로 추가합니다. 다음 명령은 공개 SSH 키를 GitHub에 업로드했다고 가정합니다. 자세한 내용은 다음 가이드를 참조하세요.
```
git clone git@github.com:<your Github handle>/peft.git
cd peft
git remote add upstream https://github.com/huggingface/peft.git
```
개발 변경 사항을 담을 새 브랜치를 생성하고, 작업하는 모든 새 PR에 대해 이 작업을 수행하세요.

main 브랜치를 upstream/main 브랜치와 동기화하는 것부터 시작하세요(GitHub Docs에서 자세한 내용을 확인하세요):
```
git checkout main
git fetch upstream
git merge upstream/main
```
main 브랜치가 동기화되면, 해당 브랜치에서 새 브랜치를 생성합니다:
```
git checkout -b a-descriptive-name-for-my-changes
```
main 브랜치에서 작업하지 마세요.
이 라이브러리를 작업하기 위해 만든 conda 또는 가상 환경에서 다음 명령을 실행하여 개발 환경을 설정합니다:
```
pip install -e ".[test]"
```
(PEFT가 이미 가상 환경에 설치되어 있다면, 다시 설치하기 전에 pip uninstall peft로 제거하세요.)

Pull request 생성이 처음이라면 GitHub의 Creating a pull request 가이드를 따르세요.

테스트 및 코드 품질 검사

기여 유형(문서 관련 기여만 제외)에 관계없이, PR을 생성하기 전에 테스트와 코드 품질 검사를 실행하여 기여가 아무것도 깨뜨리지 않고 프로젝트 표준을 준수하는지 확인해야 합니다.

테스트 및 검사 실행

필요한 테스트를 실행하기 위한 Makefile을 제공합니다. 단위 테스트를 실행하려면 아래 코드를 실행하세요:

make test

코드 품질과 스타일을 검사만 하거나 검사하고 수정하려면 다음 중 하나를 실행하세요:

make quality  # just check
make style  # check and fix

make quality를 실행하면 PEFT의 공개 API(즉, peft.__all__에 언급된 모든 것)의 모든 메서드/클래스가 문서에 언급되어 있는지 여부도 확인합니다. 이러한 오류는 make style로 수정할 수 없으며, 공개 API의 새 항목을 문서에 기록해야만 이 오류를 수정할 수 있습니다.

pre-commit를 설정하여 이러한 수정 사항을 Git 커밋 훅으로 자동으로 실행할 수도 있습니다.

$ pip install pre-commit
$ pre-commit install

모든 테스트를 실행하는 데 시간이 걸릴 수 있으므로, 개발 중에는 변경 사항에 해당하는 테스트만 실행하는 것이 더 효율적일 수 있습니다. 예를 들어, 다음과 같이 실행할 수 있습니다:

pytest tests/<test-file-name> -k <name-of-test>

이렇게 하면 훨씬 빠르게 완료되어 더 빠른 반복이 가능합니다.

테스트 추가

새 테스트를 추가하는 일반적인 가이드는 tests/README.md를 확인하세요.

변경 사항이 특정 하드웨어 설정(예: CUDA 필요)에 해당한다면, tests/test_gpu_examples.py와 tests/test_common_gpu.py를 확인하여 해당 위치에 테스트를 추가하는 것이 적절한지 살펴보세요. 변경 사항이 모델 저장 및 로딩에 영향을 줄 수 있다면, --regression 플래그를 지정하여 테스트를 실행해 회귀 테스트를 트리거하세요.

오래된 PR

PR 작업을 진행하는 동안 다른 변경 사항이 병합되어 기본 코드 베이스가 변경될 수 있습니다. 이 경우, 특히 병합 충돌이 발생했다면 최신 변경 사항으로 브랜치를 업데이트해 주세요. 이는 병합(merge) 또는 리베이스(rebase)를 통해 수행할 수 있으며, PR이 준비되면 squash and merge 방식으로 병합합니다. 리뷰를 용이하게 하기 위해 force push를 피하세요.

PR 설명

PR을 열 때, 제안하는 변경 사항에 대한 자세한 설명을 제공하고, 위에서 설명한 대로 승인된 이슈를 참조해 주세요. 다른 이슈나 PR과 관련이 있다면 그것들도 함께 참조해 주세요. 좋은 설명을 제공하는 것은 리뷰어가 코드를 더 잘, 더 빠르게 검토하는 데 도움이 될 뿐만 아니라, 장기적인 프로젝트 유지보수에 도움이 되는 커밋 메시지의 근거로 나중에 사용될 수도 있습니다.

PR 설명의 길이와 복잡도는 변경 사항의 규모와 일치해야 합니다. 한 줄의 자명한 변경 사항에 대해 10단락의 설명은 필요하지 않습니다. diff를 보면 명확히 알 수 있는 내용을 반복하지 마십시오(예: “‘foobaar’의 오타를 수정했습니다”).

코드가 비자명한(non-trivial) 변경을 포함하는 경우, 해당 변경 사항을 설명하는 코멘트를 추가하는 것도 좋은 방법입니다. 예를 들어, 가장 명백한 방식이 작동하지 않아 구현을 여러 번 반복해야 했다면, 이는 코멘트가 필요하다는 좋은 신호입니다.

관련이 있다면, pytest 테스트 명령어나 재현 코드를 보여 주는 방식으로 변경 사항을 어떻게 테스트했는지 명시하세요.

리뷰어 피드백

PR을 제출한 후, 일반적으로 유지보수자가 며칠 이내에 피드백을 제공합니다. 2주 이내에 피드백을 받지 못했다면, PR이 유지보수자의 시야에서 벗어났을 수 있습니다. 이 경우 유지보수자에게 알림을 보내도 되지만, 그보다 이전에는 보내지 마세요.

리뷰어가 인라인 코멘트를 제공한 경우, 해당 코멘트를 처리했더라도 해결로 표시하지 마세요. 리뷰어가 작업을 재개하는 데 도움이 되므로 이러한 코멘트는 열린 상태로 유지하세요.

리뷰어 피드백을 반영한 후, PR이 리뷰 준비가 되었음을 알리도록 리뷰어에게 알림을 보냅니다.

버그 수정

버그가 발생한 상황을 설명해 주세요. 기존에 관련 이슈가 있다면 링크를 포함해 주세요 (예: “Resolves #12345”).

이상적으로 버그 수정이 제공될 때, 해당 버그에 대한 테스트와 함께 제공되어야 합니다. 테스트는 현재 코드에서는 실패하고 버그 수정이 적용된 코드에서는 통과해야 합니다. 이슈나 PR을 참조하는 주석을 테스트에 추가하세요. 테스트가 없으면 향후 회귀(regression)를 방지하기가 더 어려워집니다.

문서 개선

깨진 링크 수정 및 누락되거나 불분명한 문서에 대한 수정을 환영합니다. 빠르게 변화하는 환경에서 예제가 최신 상태를 유지하고 정상적으로 실행되도록 관리하는 것도 매우 감사드립니다.

타이핑 오류만 수정하는 pull request는 일반적으로 해결하는 것보다 더 많은 업무를 발생시키므로 보내지 마십시오. 이러한 변경 사항은 깨진 링크 수정이나 문서 확장/업데이트와 같은 보다 실질적인 수정 사항과 함께 통합하는 것이 좋습니다.

새로운 PEFT 미세 조정 방법 추가

새로운 매개변수 효율적 파인튜닝 방법이 지속적으로 개발되고 있습니다. PEFT에 새로운 유망한 방법을 추가하려면 다음 단계를 따르세요.

원래 논문의 저자가 아니시다면, 기존 구현이 있는지 확인하고, 저자들이 직접 PR을 제출할 계획이 없는지 재확인하세요.
위에서 설명한 대로 명시적인 승인을 기다리기 위해 제안 이슈를 열고, 아래에 나열된 핵심 통합 작업을 시작하십시오.
새로운 PEFT 메서드가 추가되는지 확인하기 위해 최근 커밋을 살펴보고 영감을 받으세요.
제안이 승인된 후에는, 해당 방법이 기본적으로 작동하고 첫 테스트가 통과하는 시점에 초안 PR을 미리 열어 피드백을 요청하는 것이 유용할 수 있습니다. 초안 PR 설명에 승인된 이슈를 참조하세요.

새 PEFT 방법의 핵심 통합

새 PEFT 메서드를 추가하기 위한 전체 PR

해당 메서드에 특화된 구성 인자가 명확하게 명명되고 설명되어 있는지 확인하세요. 사용자가 해당 논문을 완전히 숙지하고 있다고 가정하지 마세요.
PEFT의 네이밍 및 코딩 컨벤션을 따르세요.
코드 포맷터가 관련 없는 파일을 수정하는 경우와 같이, 관련 없는 변경 사항이 실수로 커밋되지 않았는지 확인하세요.
일부 구현 선택 사항이 자명하지 않은 경우, 코드 주석으로 문서화하세요.
PEFT 메서드를 테스트 매트릭스에 추가하여 전체 테스트 스위트(test_config.py, test_decoder_models.py 등)를 완료합니다. 테스트가 통과하는지 확인합니다.
docs/source/package_reference/에 짧은 설명, 논문 링크, 사용 예시, autodoc 블록을 포함하여 문서를 추가합니다. LoRA와 같은 다른 방법들과 비교했을 때의 장단점을 설명합니다. 해당 문서 페이지를 docs/source/_toctree.yml에 등록합니다.
examples/ 아래에 실행 가능한 예제(기존 예제의 복사본일 수 있음)와 짧은 README.md를 추가합니다.
Check the benchmarks in method_comparison/ and add experiment settings for your new method. This is a good place to sanity check that the PEFT method trains as expected. Include one or two reasonable benchmark configurations (one default, one optimized for the benchmark).
권장 사항: 범용 양자화 지원 추가. 각 양자화 방식에 대해 양자화 레이어 유형을 명시적으로 추가해야 하는 대신, 범용 양자화를 지원하세요. 구현 예시로 BOFT를 확인해 보세요. https://github.com/huggingface/peft/blob/main/tests/test_quantization.py에 PEFT 메서드를 추가하여 확장하세요. 필요 시 유지보수자에게 도움을 요청하세요.

기존 PEFT 방법 변경

PEFT 메서드에 출력 결과를 변경할 수 있는 잠재적 변경 사항을 적용하여 이미 학습된 체크포인트를 무효화할 수 있는 경우, 추가적인 주의가 필요합니다. 자세한 내용은 https://github.com/huggingface/peft/blob/main/.ai/skills/peft-method-changes/SKILL.md의 설명을 확인하세요. 해당 지침은 인간과 AI 모두를 위해 작성되었습니다.

기타 기능 추가

먼저 GitHub에 새 기능을 추가하는 제안에 대한 이슈를 열고, 위에서 설명한 대로 명시적인 승인을 기다리세요. 이렇게 하면 구현에 너무 많은 시간을 들이기 전에 해당 기능을 추가하는 것이 적절한지 유지보수자들과 논의할 수 있습니다.

새로운 기능은 일반적으로 테스트와 문서 또는 예시와 함께 제공되어야 합니다. 후자가 없으면 사용자가 멋진 새 기능을 발견하기 어렵습니다.

코드 변경 사항은 하위 호환성을 유지하는 방식으로 구현해야 합니다. 예를 들어, 기능이 병합된 후에도 기존 코드가 동일한 방식으로 계속 작동해야 합니다.

Update on GitHub