프로젝트를 진행하다 보면 모델 파일 크기가 수백 MB에서 수 GB까지 커질 때가 있습니다.
특히 머신러닝이나 딥러닝 프로젝트에서는 model.pkl, model.pt, model.h5 같은 파일이 너무 커서 깃허브에 바로 업로드되지 않는 경우가 많습니다.
저는 1년 전 진행했던 KREAM 스니커즈 리셀가 예측 프로젝트를 깃허브에 올리던 중, 대용량 모델 파일은 Git LFS로 관리해야 한다는 것을 처음 알게 되었습니다. (제 모델은 크기가 크진 않아서 그냥 올리긴 했지만...)
이번 글에서는 Git LFS (Large File Storage) 를 사용해 대용량 모델 파일을 깃허브에 업로드하는 방법을 정리해보겠습니다.
깃허브는 100MB 이상의 파일 업로드를 제한합니다.
그래서 모델 파일을 커밋하려고 하면 다음과 같은 에러가 발생합니다
remote: error: File model.pt is 210 MB; this exceeds GitHub's file size limit of 100.00 MB
이럴 때 사용하는 게 바로 Git LFS (Large File Storage) 입니다.
Git LFS란?
Git LFS (Git Large File Storage) 는 GitHub에서 대용량 파일을 효율적으로 관리하기 위한 확장 기능입니다.
실제 파일은 별도의 LFS 서버에 저장하고, Git에는 포인터(pointer) 파일만 기록되므로 깃 저장소 크기를 줄일 수 있습니다.
이제 설치 및 초기 설정에 대해 알아봅시다.
1. 설치방법
운영체제에 따라 아래 명령어로 설치할 수 있습니다.
# macOS
brew install git-lfs
# Ubuntu / Linux
sudo apt install git-lfs
# Windows
choco install git-lfs
2. 프로젝트에서 LFS 초기화
git lfs install이 명령어는 한 번만 실행하면 됩니다.
이후 .gitattributes 파일을 통해 LFS로 관리할 파일 유형을 지정합니다.
모델 파일 타입 지정 (.gitattributes)
다음은 제가 실제로 사용한 .gitattributes 설정입니다
# Git LFS로 관리할 파일 타입 지정
# 모델 파일 (일반적으로 큰 파일)
*.pkl filter=lfs diff=lfs merge=lfs -text
*.h5 filter=lfs diff=lfs merge=lfs -text
*.hdf5 filter=lfs diff=lfs merge=lfs -text
*.pt filter=lfs diff=lfs merge=lfs -text
*.pth filter=lfs diff=lfs merge=lfs -text
*.onnx filter=lfs diff=lfs merge=lfs -text
*.pb filter=lfs diff=lfs merge=lfs -text
*.tflite filter=lfs diff=lfs merge=lfs -text
*.joblib filter=lfs diff=lfs merge=lfs -text
# 큰 데이터 파일 (선택사항 - 필요한 경우 주석 해제)
# *.csv filter=lfs diff=lfs merge=lfs -text
# *.parquet filter=lfs diff=lfs merge=lfs -text
# *.feather filter=lfs diff=lfs merge=lfs -text
# 큰 이미지/비디오 파일 (필요한 경우)
# *.jpg filter=lfs diff=lfs merge=lfs -text
# *.png filter=lfs diff=lfs merge=lfs -text
# *.mp4 filter=lfs diff=lfs merge=lfs -text.gitattributes 파일은 프로젝트 루트 폴더에 저장합니다.
커밋 & 푸시 과정
git add .gitattributes
git add model.pt
git commit -m "Add large model with Git LFS"
git push origin mainGit LFS로 관리된 파일은 자동으로 분리되어 업로드됩니다.
확인 방법 : GitHub 저장소에 들어가 보면 모델 파일 크기 옆에 "Stored with Git LFS" 라는 문구가 표시됩니다.
주의할점 :
- GitHub 무료 계정은 1GB LFS 저장공간만 제공합니다.
(추가 용량은 유료 플랜 필요) - LFS 파일은 fork나 clone 시 자동으로 다운로드되지 않을 수 있음
- 팀 프로젝트에서는 모든 팀원이 git lfs install 을 먼저 해야 합니다.
마무리
Git LFS를 설정해두면, 대용량 모델이나 데이터 파일도 깔끔하게 버전 관리할 수 있습니다 !
100MB 넘는 모델 파일 때문에 push가 막힐 때는,
Git LFS를 사용해보세요 ~~