Hugging Face 캐시 디렉터리 구조 정리

Hugging Face에서 다음을 호출할 경우, 관련 파일들이 로컬 캐시에 저장됨:

• from_pretrained()
• pipeline()

Local cache에 저장되는 관련 파일들은 다음과 같음:

• model file,
• tokenizer file,
• 전처리 설정 file

주의할 것은

이들 file을 단순히 한 폴더에 캐싱하는 것이 아니라,

Git의 저장소와 비슷한 형태의 구조로 저장됨:

• refs
• snapshots
• blobs

이같은 구조를 통해 같은 file의 중복 다운로드를 막고, branch나 revision이 달라도 이전 버전을 다시 사용할 수 있게 함.

 

대표적인 구조는 대략 다음과 같음.

~/.cache/huggingface/
 └─ hub/
    └─ models--{org}--{repo_name}/
       ├─ refs/
       │  └─ main
       ├─ snapshots/
       │  └─ <commit_hash>/
       │     ├─ config.json
       │     ├─ model.safetensors
       │     ├─ tokenizer.json
       │     ├─ preprocessor_config.json
       │     └─ README.md
       └─ blobs/

---

1. 전체 구조 살펴보기

전체 구조는 다음 3가지를 분리해서 관리하는 방식임.

• refs/
  • 사람이 읽는 branch나 tag 이름을
  • 실제 commit hash에 연결하는 인덱스 역할
• snapshots/
  • 특정 commit 시점에 해당하는
  • repository의 file tree를 재현
• blobs/
  • 실제 file 내용 자체를 저장하는 data 저장소 역할

이는 다음을 분리함:

• 이름과 revision 관리
• 보이는 디렉터리 구조
• 실제 file 내용

이를 통해

• 같은 file을 여러 revision에서 다시 저장하지 않으면서,
• 특정 시점의 상태를 쉽게 재현할 수 있음.

요약해서 refs, snapshots, blobs로 나눈 구조의 목표는 다음과 같음:

• 최신 main을 요청했을 때 현재 commit을 빠르게 찾기 위한 목적
• revision별 file 구조를 유지하기 위한 목적
• 동일한 file 내용을 중복 저장하지 않기 위한 목적
• 예전 revision도 필요하면 다시 사용할 수 있게 하기 위한 목적

단순한 다운로드 폴더가 아니라,

revision 관리 + 중복 제거 + 재사용 최적화를 함께 수행하는 cache system 을 구현하기 위해 취한 구조임.

---

2. 최상위 경로의 의미

~/.cache/huggingface/

• Hugging Face 관련 cache의 상위 루트 디렉터리임.
• 실제 Hub file cache는 보통 그 아래 hub/에 저장됨.

이 위치는 고정은 아님,

 

해당 위치는 다음의 환경변수나, 관련 함수 호출시 인자를 통해 변경 가능.

• 환경변수 HF_HOME,
• 환경변수 HF_HUB_CACHE,
• 또는 함수 호출 시 주는 cache_dir

---

hub/

Hugging Face Hub에서 내려받은 file들의 공통 cache 루트임.

• model, dataset, space 저장소가 모두 비슷한 방식의 cache 구조를 공유함.
• 즉, Hub와 관련된 실제 다운로드 cache가 모이는 핵심 위치임

---

3. models--{org}--{repo_name} 폴더의 의미

models--{org}--{repo_name}/

특정 model repository 하나에 대응하는 로컬 cache 폴더임.

• models--
  • repo type이 model이라는 뜻의 접두어
• {org}--{repo_name}
  • 원래의 {org}/{repo_name}를 파일시스템에서 다루기 쉽게 --로 바꿔 저장한 형태

예를 들어,

• google/vit-base-patch16-224 모델은
• models--google--vit-base-patch16-224 같은 이름의 cache 폴더 아래에 저장됨.
• 이 폴더 하나가 특정 Hugging Face model repo의 로컬 cache 저장소 역할을 수행함.

---

4. refs/ 폴더의 의미

refs/

branch나 tag 같은 사람이 읽는 revision 이름을 실제 commit hash에 연결해 두는 메타데이터 폴더임.

• main, v1.0, 특정 tag 이름 등이
• 지금 어느 commit을 가리키는지를 기록해 두는 인덱스 역할임.

---

refs/main

main branch가 현재 어떤 commit hash를 가리키는지를 적어 둔 file임.

• revision="main"으로 model을 불러오면,
• 내부적으로는 이 정보를 참고해서 실제 snapshot 위치를 찾는 방식임.

즉, refs/는
사람이 쓰는 이름과 실제 내부 revision을 연결하는
이름표 보관소라고 이해하면 됨.

---

5. snapshots/ 폴더의 의미

snapshots/

• 특정 revision, 정확히는 특정 commit 시점의 file tree를 보여주는 폴더 묶음임.
• revision마다 하나의 하위 폴더가 생기는 구조임.

---

snapshots/<commit_hash>/

특정 commit hash에 대응하는 snapshot 디렉터리임.

• 해당 시점의 repository에서 보이던 file 구조가 그대로 보이는 위치임.
• 예를 들어 그 시점에 config.json, README.md, model.safetensors가 있었다면,
• 해당 snapshot 안에도 그 file 이름이 보이게 됨.

---

여기서 핵심은 snapshots가 "그 revision에서 보이던 file 구조를 재현하는 역할"이라는 점임.

• 겉보기에는 file이 직접 들어 있는 것처럼 보이지만,
• 내부적으로는 실제 데이터가 아니라 blobs/ 안의 내용을 참조하는 방식을 취함.
• 즉, snapshot은 일종의 revision별 view에 가까운 의미를 가짐.

---

6. blobs/ 폴더의 의미

참고: blob의 뜻

blob 은
Binary Large Object 의 줄임말.

• blob은 일반적으로는 file의 실제 바이너리 내용, 또는 내용 그 자체를 가리키는 용어임.
• Git과 GitHub 문서에서도 blob은 repository 안의 file contents를 저장하는 object로 설명됨.

---

blobs/

실제로 다운로드된 file 내용이 저장되는 위치임.

• 각 file 내용은 해시 기반 이름으로 저장되며,
• 같은 내용의 file은 revision이 달라도 같은 blob을 재사용할 수 있음.
• 즉, 중복 저장을 줄이기 위한 핵심 구조임.

예를 들어 revision A와 revision B에서 README.md의 내용이 완전히 같다면,
굳이 두 번 저장할 필요가 없음.

 

이 경우 두 snapshot은 같은 blob을 참조하게 되어 저장 공간을 절약하게 됨.

따라서
blobs/는 실제 data 저장소라고 보면 됨.

---

7. 이 구조와 Git이 사용하는 방식의 관계

이 구조는 매우 Git의 object database 구조와 비슷함.

 

Git 내부에서도 blob, tree, commit 같은 object를 사용함.

• blob
  • file의 내용 자체를 저장하는 object
• tree
  • directory 구조를 나타내는 object
• commit
  • 특정 시점의 tree를 가리키는 object

Hugging Face cache 구조도 개념적으로는 이와 비슷한 사고방식을 가짐.

• blobs/
  • Git의 blob처럼 실제 file content를 저장하는 역할과 유사한 구조
• snapshots/<commit_hash>/
  • 특정 commit 시점의 file tree를 재현한다는 점에서 Git의 commit + tree를 펼쳐서 보는 느낌과 유사한 구조
• refs/main
  • Git의 branch ref처럼 사람이 읽는 이름을 특정 revision에 연결하는 역할과 유사한 구조

단, Hugging Face cache는 Git object database 자체를 구현한 것이 아니라,
Hub file download와 revision 재사용을 효율적으로 하기 위한 로컬 cache 구조임.

 

즉, Git과 비슷한 개념을 활용한 cache 관리 방식이라고 이해하는 것이 적절함.

---

8. snapshot 안에서 자주 보이는 file들의 의미 (중요)

snapshots/<commit_hash>/ 안에는
해당 repo에 포함되어 있던 file들이 보이게 됨.

자주 사용되는 file들은 아래에서 설명하지만
실제 repo마다 file 구성은 달라질 수 있음.
어떤 모델은 tokenizer 관련 file이 여러 개로 나뉠 수 있고,
어떤 모델은 shard된 weight file 여러 개를 가질 수도 있음.

 

자주 보이는 항목들은 다음과 같음:

config.json

모델 설정 file임.

• model architecture, hidden size, layer 수, label 정보, model type 등의 메타데이터를 담는 역할을 함.
• from_pretrained() 계열이 모델 구조를 파악할 때 핵심적으로 참고하는 file 중 하나임.

---

model.safetensors

실제 학습된 weight file임.

• 최근에는 pytorch_model.bin 대신 safetensors 형식이 널리 쓰이는 추세임.
• 모델 파라미터가 저장된 핵심 file이라고 보면 됨.

---

tokenizer.json

tokenizer의 전체 설정과 vocabulary 관련 정보를 담는 file임.

• text를 token으로 변환하고 다시 복원하는 데 필요한 데이터가 들어 있음.
• 모델에 따라 tokenizer_config.json, vocab.txt, merges.txt 같은 file이 함께 있을 수도 있음.

---

preprocessor_config.json

image, audio, multimodal 모델 등에서 입력 전처리 규칙을 담는 file임.

• resize, normalization, feature extraction 관련 설정 등이 포함될 수 있음.

---

README.md

해당 Hub repo의 model card 또는 설명 문서임.

• 모델 개요, 사용법, license, limitation, intended use 등이 적히는 경우가 많음.
• Hub 웹페이지에서 보이는 설명의 원본 역할을 하는 경우도 많음.

---

9. HF_HOME, HF_HUB_CACHE, cache_dir의 용도와 차이

Hugging Face cache 위치를 바꾸는 방법은 크게 다음의 세 가지임.
(약간의 적용 범위와 용도가 다름.)

HF_HOME

Hugging Face 관련 로컬 데이터의 상위 홈 디렉터리 를 바꾸는 환경변수임.

• 이 값을 바꾸면 보통 그 아래에 hub/ 같은 하위 폴더가 만들어지는 구조임.
• 가장 넓은 범위의 기본 위치를 통째로 바꾸고 싶을 때 사용하는 방식임.

---

HF_HUB_CACHE

Hugging Face Hub file cache의 위치만 직접 지정하는 환경변수임.

• hub cache 위치만 별도로 옮기고 싶을 때 쓰는 방식임.
• HF_HOME보다 더 구체적으로 Hub cache 에 영향을 주는 설정임.

---

cache_dir

다음의 Python 함수 호출 시 직접 넘기는 인자로 해당 호출을 통해 사용할 cache 위치를 지정.

• hf_hub_download(),
• snapshot_download(),
• from_pretrained()

전역 환경변수 대신, 특정 코드나 특정 다운로드 작업에만 개별적으로 적용하고 싶을 때 쓰는 방식임.

---

차이 요약

• HF_HOME
  • Hugging Face 전체 로컬 홈 기준 위치를 정하는 전역 설정
• HF_HUB_CACHE
  • 그중 Hub file cache 위치만 따로 정하는 전역 설정
• cache_dir
  • 특정 함수 호출 한 번에만 적용되는 지역 설정
  • 특정 호출만 별도 cache를 쓰고 싶으면 cache_dir를 사용

 

---

10. from_pretrained()에서 cache_dir를 주었을 때 영향 범위

from_pretrained()의 cache_dir는 해당 호출이 Hub에서 내려받는 file들을 어디에 cache할지를 지정하는 인자임.

• 전역 환경변수를 바꾸는 것이 아니라,
• 그 호출에서 필요한 다운로드 결과의 저장 위치를 지정하는 지역 설정이라고 이해하면 됨.

예를 들어 다음과 같음.

model = AutoModel.from_pretrained(
    "google/vit-base-patch16-224",
    cache_dir="D:/hf_cache"
)

• 이 경우 해당 model 로드에 필요한 config.json, weight file 등 Hub에서 받아오는 관련 file들은
• 환경변수 등에 의한 기본 cache 대신 D:/hf_cache 아래에 저장되는 방식이 됨.
• 전역적으로 HF_HOME이나 HF_HUB_CACHE가 설정되어 있더라도,
• 이 호출에서는 cache_dir가 우선적으로 적용된다고 이해하면 됨.

영향 범위는 "이 호출이 실제로 내려받는 Hub artifact들" 임:

• model의 from_pretrained(..., cache_dir=...)
  • model config, weight 등 model 로드에 필요한 file cache 위치에 영향
• tokenizer의 from_pretrained(..., cache_dir=...)
  • tokenizer 관련 file cache 위치에 영향
• processor의 from_pretrained(..., cache_dir=...)
  • processor가 내부적으로 부르는
  • tokenizer, image processor, feature extractor 관련 file cache 위치에 영향 가능

cache_dir는 Python 프로세스 전체의 전역 정책을 바꾸는 것이 아님.
다만, 그 호출 체인에서 내려받는 Hub file들의 cache 위치를 지정하는 것임.

 

따라서 model은 cache_dir="D:/a"로 받고, tokenizer는 따로 cache_dir="D:/b"로 받는 식의 사용도 가능함.
이는 cache_dir가 전역 설정이 아니라 호출 단위 설정이라는 뜻임.

 

참고로,

• cache_dir는 cache 위치를 바꾸는 옵션이지,
• 특정 작업 폴더에 file을 바로 풀어놓는 옵션은 아니라는 점임.

작업용 로컬 폴더에 직접 file을 배치하는 흐름은 local_dir 로 설정함.
cache_dir는 어디까지나 cache 저장 위치 제어용이라고 이해하는 것이 정확함.

 

---

참고: local_dir 옵션이란?

local_dir는 다음의 함수에서 지정가능:

• hf_hub_download()
  • Hub의 특정 file 하나를 내려받을 때 사용하는 함수
  • local_dir를 주면 cache 디렉터리 구조 대신, 지정한 로컬 폴더 쪽에 file을 배치하는 용도로 사용 가능함
• snapshot_download()
  • repo 전체 또는 패턴에 맞는 여러 file을 한 번에 내려받을 때 사용하는 함수
  • local_dir를 주면 snapshot 결과를 특정 로컬 폴더에 내려받는 방식으로 사용 가능함

---

결론

Hugging Face cache 구조는 다음처럼 이해하면 됨.

• refs/
  • branch나 tag 이름을 실제 commit hash에 연결하는 인덱스
• snapshots/
  • 특정 commit 시점의 file tree를 보여주는 revision별 view
• blobs/
  • 실제 file 내용이 해시 기반으로 저장되는 data 저장소

그리고 이 구조는 Git의 blob, tree, commit, ref와 유사하나
목적은 Git repository 자체를 재현하는 것이 아닌
Hugging Face Hub download와 revision 재사용을 효율화하는 로컬 cache를 만드는 데 있음.

---

cache 위치를 바꾸는 방법은 다음과 같음:

• HF_HOME
  • Hugging Face 전체 로컬 홈 위치를 바꾸는 전역 설정
• HF_HUB_CACHE
  • Hub file cache 위치만 바꾸는 전역 설정
• cache_dir
  • 특정 from_pretrained() 또는 다운로드 호출에만 적용되는 지역 설정