저장소 시작하기

저장소 시작하기

이 초보자 가이드는 Hub에서 저장소를 만들고 관리하는 기본기를 다져주는 문서예요. 각 섹션이 이전 섹션을 기반으로 쌓이니 원하는 지점부터 시작하면 돼요. 웹 인터페이스와 터미널 두 가지 방식 모두 설명해요.

출처: 공식문서

본문

요구 사항

웹 UI만 쓴다면 별도 요구사항은 없어요. 터미널로 작업하려면 git CLI가 필요하고, 이미지·모델 가중치 같은 대용량 파일을 다루려면 Git-Xet(git-xet)도 설치해야 해요. 코드를 Hub로 push하려면 인증이 필요한데, hf CLI를 설치하고 로그인하는 방법이 제일 간단해요.

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

저장소 만들기

huggingface.co/new에서 저장소를 만들 수 있어요. ① 소유자(본인 또는 소속 조직), ② 모델 이름(저장소 이름이 됨), ③ 공개/비공개 여부, ④ 라이선스를 지정해야 해요. 만들면 Hub가 모델 카드(Model Card) 작성을 안내하는데, 모델 저장소엔 모델 카드를 포함하는 게 모범 사례예요.

웹 UI로 파일 추가

Files 탭 → 원하는 디렉터리로 이동 → Add file을 클릭해 새 파일을 만들거나 컴퓨터에서 파일을 직접 업로드해요. 커밋 메시지를 입력해 저장소에 반영하거나, 바로 main 브랜치에 커밋하는 대신 Open as a pull request로 Pull Request를 만들 수도 있어요.

CLI로 파일 업로드

hf CLI의 hf upload 명령으로 로컬 파일이나 폴더를 통째로 올릴 수 있어요. 대용량 파일은 자동으로 처리돼 추가 설정이 필요 없어요.

# 단일 파일 업로드
hf upload your-username/your-model-name model.safetensors

# 디렉터리 통째로 업로드
hf upload your-username/your-model-name ./my-model-directory

# 데이터셋 저장소로 업로드
hf upload your-username/your-dataset-name ./data --repo-type dataset

Git으로 파일 추가

저장소를 로컬로 내려받는 것을 **클로닝(cloning)**이라 해요.

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

SSH로 클론할 수도 있어요. push하거나 비공개 저장소에 접근하려면 사용자 설정에 SSH 공개 키를 등록해야 해요.

10MB보다 큰 파일은 git-xet로 추적돼요. git xet install로 초기화하고, 처리되지 않는 확장자는 git xet track "*.your_extension"으로 추가해요. Hub가 저장소를 만들 때 .gitattributes에 흔한 ML 대용량 파일 확장자 목록을 자동 제공하지만, 새 확장자는 직접 추가해야 할 수 있어요.

파일을 저장하려면 add → commit → push 사이클을 돌려요.

git add .
git commit -m "First model version"
git push

HTTP로 클론했다면 push할 때마다 사용자 이름·비밀번호를 물어볼 수 있어요. SSH로 전환하거나 git credential helper를 설정하는 게 편해요.

히스토리 보기

add-commit-push 사이클을 반복할 때마다 저장소가 모든 변경을 추적해요. UI에서 History: X commits 링크를 클릭하면 커밋과 각 커밋이 만든 변경(diff)을 볼 수 있어요. 개별 커밋을 클릭하면 그 커밋이 바꾼 내용을 확인할 수 있어요.

더 알아보기