레포지토리 시작하기

입문자 친화적인 이 가이드는 Hub에서 저장소를 생성하고 관리하는 데 필요한 기본 기술을 습득하는 데 도움이 됩니다. 각 섹션은 이전 섹션을 기반으로 하므로 원하는 위치에서 시작해 보세요!

요구 사항

이 문서는 웹 인터페이스와 터미널을 통해 저장소를 관리하는 방법을 보여줍니다. UI를 사용하는 경우 특별한 요구 사항은 없습니다. 터미널을 사용하려면 다음 설치 지침을 따르십시오.

CLI 명령어로 git을 아직 사용할 수 없다면, 해당 플랫폼에 Git을 설치해야 합니다. 이미지와 모델 가중치와 같은 대용량 파일을 처리하는 데 사용되는 Git-Xet도 설치해야 합니다.

Git에서 대용량 파일을 다운로드하고 업로드하려면 Git Xet 확장을 설치해야 합니다.

Hub에 코드를 push하려면 인증이 필요합니다. 가장 쉬운 방법은 hf CLI를 설치한 후 login 명령을 실행하는 것입니다:

# Install hf:
#   brew install hf
#   or
#   pip install hf
hf auth login

이 문서의 Getting Started 섹션에 포함된 내용은 동영상으로도 제공됩니다!

리포지토리 생성

Hub의 웹 인터페이스를 사용하면 저장소를 쉽게 생성하고, 파일(대용량 파일 포함!)을 추가하고, 모델을 탐색하고, 차이를 시각화하는 등 다양한 작업을 수행할 수 있습니다. Hub에는 세 가지 유형의 저장소가 있으며, 이 가이드에서는 데모 목적으로 모델 저장소를 생성합니다. 모델, 데이터셋, Spaces의 생성 및 관리에 대한 정보는 각 해당 문서를 참고하세요.

1. 새 저장소를 만들려면 huggingface.co/new을 방문하세요:

2. 저장소 소유자를 지정합니다. 이는 사용자 자신 또는 사용자가 소속된 조직 중 하나일 수 있습니다.

3. 모델 이름을 입력하세요. 이는 저장소 이름으로도 사용됩니다.

4. 모델을 공개로 할지 비공개로 할지 지정합니다.

5. 라이선스를 지정합니다. License 필드는 당분간 비워 두셔도 됩니다. 라이선스에 대한 자세한 내용은 Licenses 문서를 참고하세요.

모델 저장소를 생성한 후, 다음과 같은 페이지가 표시되어야 합니다:

Hub에서는 Model Card 생성을 안내하며, Model Cards 문서에서 이에 대해 자세히 알아볼 수 있습니다. 모델 저장소에 Model Card를 포함하는 것이 권장 사항이지만, 현재는 테스트 저장소만 생성하는 것이므로 이 단계를 건너뛸 수 있습니다.

리포지토리에 파일 추가 (Web UI)

웹 UI를 통해 저장소에 파일을 추가하려면 Files 탭을 선택하고 원하는 디렉터리로 이동한 다음 Add file을 클릭하세요. 새 파일을 만들거나 컴퓨터에서 파일을 직접 업로드하는 옵션이 제공됩니다.

새 파일 만들기

새 파일 생성을 선택하면 파일 이름 지정, 콘텐츠 추가, 변경 사항을 요약하는 메시지와 함께 파일을 저장할 수 있는 다음 편집 화면으로 이동합니다. 새 파일을 저장소의 main 브랜치에 직접 커밋하는 대신 Open as a pull request를 선택하여 Pull Request를 생성할 수 있습니다.

파일 업로드

Upload file를 선택하면 저장소에 대한 변경 사항을 요약한 메시지와 함께 업로드할 로컬 파일을 선택할 수 있습니다.

새 파일 생성과 마찬가지로, Open as a pull request를 선택하여 변경 사항을 저장소의 main 브랜치에 직접 추가하는 대신 Pull Request를 생성할 수 있습니다.

리포지토리에 파일 추가 (CLI)

터미널에서 hf CLI를 사용하여 저장소에 파일을 직접 업로드할 수 있습니다. hf upload 명령을 사용하여 로컬 파일 또는 전체 폴더를 푸시하세요:

# Upload a single file to your model repo
hf upload your-username/your-model-name model.safetensors

# Upload an entire directory
hf upload your-username/your-model-name ./my-model-directory

# Upload to a dataset repo
hf upload your-username/your-dataset-name ./data --repo-type dataset

hf CLI는 대용량 파일을 자동으로 처리하므로 추가 설정이 필요하지 않습니다.

저장소(git)에 파일 추가

리포지토리 클론

로컬 머신으로 저장소를 다운로드하는 작업은 클로닝이라고 합니다. 다음 명령어를 사용하여 저장소를 로드하고 해당 디렉터리로 이동할 수 있습니다:

git clone https://huggingface.co/<your-username>/<your-model-name>
cd <your-model-name>

또는 데이터셋 저장소의 경우:

git clone https://huggingface.co/datasets/<your-username>/<your-dataset-name>
cd <your-dataset-name>

다음 명령을 사용하여 SSH를 통해 클론할 수 있습니다:

git clone git@hf.co:<your-username>/<your-model-name>
cd <your-model-name>

변경 사항을 push하거나 비공개 저장소에 액세스하려면 사용자 설정에 SSH 공개 키를 추가해야 합니다.

설정

이제 원하는 파일을 저장소에 자유롭게 추가할 수 있습니다! 🔥

10MB보다 큰 파일이 있나요? 이러한 파일은 git-xet로 추적해야 하며, 다음 명령으로 초기화할 수 있습니다:

git xet install

Hugging Face를 사용하여 저장소를 생성하면, Hugging Face는 .gitattributes 파일에 일반적인 Machine Learning 대용량 파일의 공통 파일 확장자 목록을 자동으로 제공합니다. git-xet는 이 정보를 사용하여 대용량 파일의 변경 사항을 효율적으로 추적합니다. 다만, 파일 유형이 이미 처리되지 않은 경우 새로운 확장자를 추가해야 할 수 있습니다. git xet track "*.your_extension"를 사용하여 이를 수행할 수 있습니다.

파일 푸시

Git을 사용하여 새 파일과 기존 파일의 변경 사항을 commit이라는 변경 사항 묶음으로 저장할 수 있으며, 이는 프로젝트의 “수정판”으로 볼 수 있습니다. commit을 생성하려면, 변경 사항을 저장할 계획임을 Git에 알리기 위해 파일을 add한 다음 해당 변경 사항을 commit해야 합니다. Hugging Face Hub와 새 commit을 동기화하려면, commit을 Hub에 push합니다.

# Create any files you like! Then...
git add .
git commit -m "First model version"  # You can choose any descriptive message
git push

그리고 완료되었습니다! Hugging Face에서 최근 추가된 파일이 모두 포함된 저장소를 확인할 수 있습니다. 예를 들어, 아래 스크린샷에서는 사용자가 여러 파일을 추가했습니다. 참고로 이 예시에서 일부 파일의 크기가 1.04 GB이므로, 해당 저장소는 Xet을 사용하여 이를 추적합니다.

리포지토리를 HTTP로 클론한 경우, push 작업을 수행할 때마다 사용자 이름과 비밀번호를 입력하라는 요청을 받을 수 있습니다. 반복을 피하는 가장 간단한 방법은 HTTP 대신 SSH로 전환하는 것입니다. 또는 HTTP를 사용해야 하는 경우, 사용자 이름과 비밀번호를 자동으로 입력하도록 git credential helper를 설정하는 것이 도움이 될 수 있습니다.

리포지토리의 히스토리 보기

add-commit-push 사이클을 거칠 때마다 저장소는 파일에 적용한 모든 변경 사항을 추적합니다. UI를 통해 모델 파일과 커밋을 탐색하고 각 커밋에서 도입된 차이(또는 diff)를 확인할 수 있습니다. 히스토리를 보려면 History: X commits 링크를 클릭하세요.

개별 커밋을 클릭하여 해당 커밋에서 어떤 변경 사항이 도입되었는지 확인할 수 있습니다: