Hugging Face 캐시를 안전하게 정리하는 방법

무엇이든 삭제하기 전에 현재 hf cache 명령으로 캐시를 조사하세요. 알려진 리포지터리나 리비전은 hf cache rm로 제거하고, 더 이상 참조되지 않는 리비전에는 hf cache prune를 사용하세요. 캐시 디렉터리를 서로 독립된 파일 더미로 여기지 마세요. 스냅샷들이 같은 블롭을 공유할 수 있습니다.

수동 삭제가 보기보다 위험한 이유

Hub 캐시는 같은 콘텐츠를 두 번 다운로드하지 않도록 설계되었습니다. hub 캐시 아래에서 리포지터리는 보통 refs, snapshots, blobs를 가집니다. 스냅샷은 리비전을 사용 가능한 디렉터리로 보여 주지만 파일은 blobs의 공유 콘텐츠를 가리킬 수 있습니다. 따라서 두 리비전에 같은 대형 가중치 파일이 있는 것처럼 보여도 전체 사본 두 개만큼 공간을 쓰지 않을 수 있습니다.

이 구조는 효율적이지만 ‘가장 커 보이는 폴더를 삭제’하는 것은 나쁜 규칙입니다. 사용 중인 블롭을 직접 제거하면 둘 이상의 스냅샷이 손상될 수 있습니다. 한 스냅샷을 제거해도 다른 리비전이 같은 콘텐츠를 계속 참조하므로 표시 크기보다 훨씬 적은 공간만 확보될 수 있습니다.

실제로 사용하는 캐시 측정하기

먼저 활성 Hugging Face 캐시 디렉터리를 찾으세요. HF_HOME, HF_HUB_CACHE 및 관련 변수가 기본 위치에서 옮겼을 수 있습니다. 그런 다음 CLI에서 캐시 상태를 확인하세요.

hf cache ls
hf cache ls --revisions

첫 번째 명령은 캐시된 리포지터리를 나열하고 두 번째 명령은 개별 리비전을 보여 줍니다. 목록이 길면 현재 CLI의 필터나 정렬을 사용하세요. 결정해야 할 것은 단순히 ‘무엇이 오래되었나?’가 아니라 ‘정확히 어떤 리포지터리나 리비전을 다시 받을 수 있으며, 현재 작업을 지원하는 것은 무엇인가?’입니다.

리포지터리 또는 리비전을 신중하게 제거

캐시된 리포지터리 전체를 폐기해도 된다는 사실을 알면 그 캐시 식별자를 hf cache rm에 전달하세요. 현재 문서는 다음과 같은 리포지터리 식별자를 사용합니다.

hf cache rm model/gpt2

범위를 좁혀 정리하려면 hf cache ls --revisions가 보고한 특정 리비전 식별자를 선택하세요. 미리 보기와 확인 내용을 주의 깊게 읽으세요. CLI는 무엇이 참조되지 않게 되는지 계산할 수 있지만 파일 시스템에서 직접 선택하면 이런 관계를 설명할 수 없습니다.

작업 세트가 아니라 분리된 리비전 정리하기

hf cache prune는 더 이상 참조되지 않는 리비전을 대상으로 합니다. 브랜치나 태그 참조가 바뀌면서 남은 오래된 리비전 데이터를 정리하는 데 적합하지만, 기억나지 않는 모든 오래된 모델이 사라진다는 약속은 아닙니다. 세션이 끝날 때마다 반사적으로 자동 실행하지 말고, 제안된 제거 항목을 확인한 뒤 실행하세요.

hf cache prune

여러 사용자, 컨테이너 또는 예약 작업이 캐시를 관리한다면 먼저 진행 중인 다운로드를 중지하세요. 다른 프로세스가 스냅샷을 생성하는 동안 정리하면 캐시 구현이 복구를 고려해 설계되었더라도 불필요한 불확실성이 생깁니다.

남은 항목 검증하기

1. hf cache ls를 다시 실행하고 새 크기를 기록하세요.
2. 보존하려는 중요한 리포지터리에는 hf cache verify <repo>를 사용하세요.
3. 보존한 모델을 불러오는 실제 워크플로 하나를 시작하세요.
4. 새 다운로드가 발생하는지 살펴보세요. 조용히 다시 받아지는 모델은 로컬에 완전히 준비되어 있지 않았던 것입니다.

다시 다운로드하는 것이 항상 실패를 뜻하지는 않습니다. 캐시는 결국 캐시입니다. 하지만 오프라인으로 작업하거나 특정 리비전을 고정하거나 사라질 수 있는 업스트림 파일에 의존한다면 중요합니다.

캐시 정리와 장기 보존은 서로 다른 문제를 해결합니다

Hub 캐시는 재사용과 재다운로드에 최적화되어 있습니다. 모델, 토크나이저, 구성 또는 어댑터가 왜 한데 속하는지를 정리한 기록은 아닙니다. 재현하기 어려운 리비전을 정리하기 전에 이를 사용하는 데 필요한 전체 모델군을 파악하세요. PEFT 어댑터에는 호환 베이스 모델과 구성이 포함될 수 있고, 학습 결과에는 가중치 외의 항목이 더 필요할 수 있습니다.

Tensor Archive는 이 경계의 신중한 쪽에 있어야 합니다. 완성된 로컬 모델군을 보존하고 아카이브를 검증하며 정확한 복원을 입증하세요. 그러면 캐시는 우연히 만들어진 박물관이 아니라 다시 폐기 가능한 인프라가 됩니다.

관련 가이드

현재 캐시가 단순히 잘못된 디스크에 있다면 별도 가이드에 따라 Hugging Face 캐시 디렉터리를 변경하세요. 라이브러리가 여러 런타임에 걸쳐 있다면 무엇이 단순히 다시 받을 수 있는 캐시 상태인지 결정하기 전에 보존 체크리스트를 사용하세요.