Bộ đệm cục bộ của Hub

Tài liệu này mô tả cấu trúc lưu trữ trên đĩa của bộ nhớ đệm cục bộ của HF Hub. Tài liệu được thiết kế như một tài liệu tham khảo để tái triển khai hệ thống bộ nhớ đệm bằng bất kỳ ngôn ngữ nào.

Dưới đây là danh sách một phần các thư viện và ứng dụng sử dụng bố cục bộ nhớ đệm này. Vui lòng mở một PR để thêm của bạn.

Thư viện

Ứng dụng

Vị trí bộ nhớ đệm

Thư mục cache mặc định là:

~/.cache/huggingface/hub

Điều này có thể được ghi đè bằng các biến môi trường:

• HF_HUB_CACHE - đường dẫn trực tiếp đến thư mục cache (có độ ưu tiên cao hơn)
• HF_HOME - đường dẫn đến thư mục home của Hugging Face; nếu được đặt, bộ nhớ đệm sẽ nằm tại $HF_HOME/hub

Tổng quan

<CACHE_DIR>/
├── .locks/                                  # Lock files for concurrent download safety
├── blobs/                                   # Shared blob store: Xet files deduplicated across repos
├── models--<org>--<repo>/                   # Cached model repositories
├── datasets--<org>--<repo>/                 # Cached dataset repositories
└── spaces--<org>--<repo>/                   # Cached space repositories

Each downloaded repository gets a single flat folder. Inside each repo folder, files are stored once in a content-addressed blobs/ directory and accessed through snapshots/ symlinks. Named references (branches, tags) are tracked in refs/. Since huggingface_hub 1.32, files downloaded with hf_xet are stored once for the whole cache, in a shared blob store at the cache root. The repo’s blobs/ entry is then a symlink to that file.

Sơ đồ

                     ┌──────────────────────────────────────────┐
                     │           Repository folder              │
                     │  models--julien-c--EsperBERTo-small      │
                     └──────────────┬───────────────────────────┘
                                    │
              ┌─────────────┬───────┴───────┬──────────────┐
              │             │               │              │
              v             v               v              v
          ┌───────┐    ┌────────┐    ┌────────────┐   ┌──────────┐
          │ refs/ │    │ blobs/ │    │ snapshots/ │   │.no_exist/│
          └───┬───┘    └────┬───┘    └──────┬─────┘   └────┬─────┘
              │             │               │              │
              │             │               │              │
   "main" contains     Files stored     One folder     Empty marker
   commit hash         by content       per commit     files for
   e.g. "aaaaaa"       hash (SHA-1      hash, e.g.     files known
                       or SHA-256)      aaaaaa/        not to exist
   Resolves a                           bbbbbb/
   branch/tag to                            │
   a snapshot ──────────────────────►  Contains symlinks
                                       to ../../blobs/{hash}

Đặt tên thư mục kho

Các kho lưu trữ được lưu dưới dạng các thư mục phẳng tại gốc bộ nhớ đệm. Tên thư mục mã hóa loại kho và ID kho:

{type}s--{repo_id_with_slashes_replaced_by_--}

Quy tắc:

• Loại repo được số nhiều: models, datasets, spaces
• Dấu gạch chéo phía trước (/) trong ID kho sẽ được thay thế bằng --
• Ký tự phân tách giữa tất cả các phần là --
• Việc bảo toàn chữ hoa chữ thường

Ví dụ:

Buckets không được xử lý bởi bộ nhớ đệm này vì chúng không dựa trên git. Hãy sử dụng lệnh hf buckets sync chuyên dụng thay thế.

Bên trong thư mục kho

Mọi kho lưu trữ được lưu trong bộ nhớ đệm đều có cùng cấu trúc bên trong:

<repo_folder>/
├── blobs/
├── refs/
├── snapshots/
└── .no_exist/    # may not always be present

blobs/ : lưu trữ tệp theo địa chỉ nội dung

Thư mục blobs/ lưu trữ nội dung thực tế của các tệp. Mỗi tệp được đặt tên theo etag của tệp đó trên Hub:

• Các tệp được Git theo dõi: được đặt tên bằng băm SHA-1 (40 ký tự thập lục phân)
• Các tệp Git LFS: được đặt tên theo băm SHA-256 (64 ký tự thập lục phân)

Đây là một thư mục phẳng — không có thư mục con. Các tệp giống hệt nhau giữa các bản sửa đổi khác nhau chỉ được lưu trữ một lần. Một mục nhập là tệp thông thường hoặc là liên kết tương đối vào shared blob store; người đọc nên làm theo nó.

blobs/
├── 403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd   # SHA-256 (LFS)
├── 7cb18dc9bafbfcf74629a4b760af1b160957a83e                           # SHA-1 (git)
└── d7edf6bd2a681fb0175f7735299831ee1b22b812                           # SHA-1 (git)

refs/ : tham chiếu nhánh và thẻ

Thư mục refs/ ánh xạ các tham chiếu có thể đọc được bằng người (tên nhánh, thẻ, số PR) tới các băm commit.

Mỗi tham chiếu là một tệp văn bản thuần túy chứa một dòng duy nhất: mã băm commit đầy đủ (40 ký tự thập lục phân).

refs/
├── main            # contains e.g. "bbc77c8132af1cc5cf678da3f1ddf2de43606d48"
├── 2.4.0           # a tag
└── refs/
    └── pr/
        └── 1       # pull request reference

Khi một tệp được tải xuống bằng tên nhánh hoặc thẻ, tệp ref tương ứng sẽ được tạo mới hoặc cập nhật với mã băm của commit mới nhất.

snapshots/ : các bản xem theo phiên bản

Thư mục snapshots/ chứa một thư mục con cho mỗi bản sửa đổi được lưu trong bộ nhớ đệm (hash của commit). Mỗi thư mục bản sửa đổi phản ánh cấu trúc tệp của kho trên Hub, nhưng các tệp là liên kết mềm trỏ đến ../../blobs/{hash}.

snapshots/
├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
│   ├── README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
│   └── pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
└── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/
    ├── README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
    └── pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd

Các thuộc tính chính:

• Symlinks sử dụng đường dẫn tương đối: ../../blobs/{hash}
• Nếu một tệp không thay đổi giữa hai bản sửa đổi, cả hai liên kết mềm đều trỏ đến cùng một blob mà không có sự nhân bản dữ liệu
• Các tệp trong các thư mục con trên Hub được đại diện dưới dạng các thư mục con trong bản chụp (đường dẫn tương đối đầy đủ được giữ nguyên)

Việc chuyển đổi giữa các snapshot tương tự như việc sử dụng git checkout trong một kho git cục bộ.

.no_exist/ : bộ nhớ đệm cho sự không tồn tại

Thư mục .no_exist/ theo dõi các tệp đã được yêu cầu nhưng không tồn tại trên Hub. Điều này giúp tránh các yêu cầu HTTP lặp lại cho các tệp tùy chọn.

Cấu trúc mô phỏng snapshots/: mỗi commit hash có một thư mục con, chứa các tệp rỗng (không phải symlink) được đặt tên theo tệp bị thiếu.

.no_exist/
└── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
    └── config_that_does_not_exist.json    # empty file

Dung lượng ổ đĩa là không đáng kể vì đây chỉ là các tệp đánh dấu rỗng.

Kho blob dùng chung

Các tệp được tải xuống thông qua Xet sẽ được khử trùng lặp giữa các kho lưu trữ. Một tệp như vậy chỉ được lưu một lần tại gốc bộ nhớ đệm, dưới blobs/, và mỗi kho lưu trữ cần tệp đó sẽ nhận được một liên kết tương đối thay vì một bản sao:

<CACHE_DIR>/
├── blobs/
│   ├── .huggingface-shared-blobs                 # marker file, contains the layout version ("1")
│   └── 73/                                       # first two hex characters of the Xet hash
│       ├── 73b079dc7bd546aed26d20a82289bd752fc52a2fda13e7f2b551f3af73845b59                       # the file, named by its Xet hash (64 hex characters)
│       ├── 73b079dc7bd546aed26d20a82289bd752fc52a2fda13e7f2b551f3af73845b59.refs                  # manifest: one line per repo blob that references it (path relative to the cache root)
│       └── 73b079dc7bd546aed26d20a82289bd752fc52a2fda13e7f2b551f3af73845b59.lock                  # lock file
│
└── models--HuggingFaceTB--SmolLM2-135M-Instruct/
    └── blobs/
        └── 5af571cbf074e6d21a03528d2330792e532ca608f24ac70a143f6b369968ab8c -> ../../blobs/73/73b079dc7bd546aed26d20a82289bd752fc52a2fda13e7f2b551f3af73845b59

Các thuộc tính chính:

• Mục repo giữ nguyên tên etag và trở thành symlink tương đối: ../../blobs/{xet_hash[:2]}/{xet_hash}
• Bố cục snapshots/ không thay đổi, do đó phân giải tệp không bị ảnh hưởng
• Tệp đánh dấu xác định kho lưu trữ: một thư mục blobs/ không rỗng ở gốc bộ đệm mà không có tệp này sẽ không bao giờ được sử dụng hoặc sửa đổi
• Store yêu cầu symlink và hf_xet. Nếu việc chia sẻ thất bại, tệp sẽ được lưu trong thư mục repo như trước. HF_HUB_DISABLE_SHARED_BLOBS=1 vô hiệu hóa store
• Chỉ các tệp tải xuống mới đi qua store. Các tệp được ghi bởi các phiên bản cũ hơn hoặc bởi các client khác vẫn là tệp thông thường trong thư mục repo, do đó một cache có thể chứa cả

Các triển khai chỉ đọc bộ nhớ đệm không cần thay đổi: việc làm theo các liên kết biểu tượng hoạt động như trước.

Các triển khai xóa khỏi bộ nhớ đệm nên coi một blob kho là symlink như một tham chiếu vào kho lưu trữ:

• Xóa symlink trong blobs/ của repo, không phải tệp dùng chung mà nó trỏ tới
• Khóa <xet_hash>.lock trước khi kiểm tra manifest và xóa
• Xóa tệp dùng chung và .refs của nó chỉ khi không còn liên kết mềm nào được liệt kê trong manifest trỏ đến tệp đó
• Nếu manifest bị thiếu hoặc không thể đọc được, hãy giữ lại tệp dùng chung

Xem hướng dẫn cache của huggingface_hub để biết về hành vi xóa và các hạn chế với các client cũ hơn.

Tệp khóa

File khóa ngăn các tiến trình đồng thời tải xuống cùng một blob. Chúng được lưu trong thư mục .locks/ ở gốc bộ nhớ đệm (không nằm trong thư mục kho):

<CACHE_DIR>/.locks/<repo_folder_name>/<blob_hash>.lock

Ví dụ:

<CACHE_DIR>/.locks/models--julien-c--EsperBERTo-small/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd.lock

Ví dụ đầy đủ

~/.cache/huggingface/hub/
├── .locks/
│   └── models--julien-c--EsperBERTo-small/
│       └── 403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd.lock
│
└── models--julien-c--EsperBERTo-small/
    ├── blobs/
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    │
    ├── refs/
    │   └── main    # contains "bbc77c8132af1cc5cf678da3f1ddf2de43606d48"
    │
    ├── snapshots/
    │   ├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
    │   │   ├── README.md         -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
    │   │   └── pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   │
    │   └── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/
    │       ├── README.md         -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │       └── pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │
    └── .no_exist/
        └── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
            └── optional_config.json    # empty file

Lưu ý rằng pytorch_model.bin trỏ đến cùng một blob trong cả hai phiên bản. Tệp 321 MB chỉ được lưu trữ một lần trên đĩa.

Logic phân giải tệp

Để xác định vị trí một tệp đã được lưu trong bộ nhớ đệm trên đĩa:

1. Giải quyết revision thành commit hash

   • Nếu revision đã là chuỗi hex 40 ký tự, hãy sử dụng nó trực tiếp
   • Ngược lại, đọc tệp tại refs/{revision} để lấy mã băm của commit

2. Kiểm tra bản sao lưu

   • Tìm snapshots/{commit_hash}/{relative_path}
   • Nếu tệp tồn tại (dưới dạng symlink hoặc tệp), tệp sẽ được lưu vào bộ nhớ đệm. Làm theo symlink để lấy nội dung

3. Kiểm tra sự không tồn tại

   • Tìm .no_exist/{commit_hash}/{relative_path}
   • Nếu tệp tồn tại, tệp đó được biết là không tồn tại trên Hub cho phiên bản này

4. Lỗi cache

   • Nếu cả hai đường dẫn đều không tồn tại, tệp vẫn chưa được lưu vào bộ nhớ đệm

Hành vi trên Windows

Bộ nhớ đệm dựa vào liên kết biểu tượng. Trên các hệ thống Windows không hỗ trợ liên kết biểu tượng, bộ nhớ đệm sẽ hoạt động ở chế độ suy giảm: các bản sao tệp thực tế được đặt trực tiếp trong snapshots/ thay vì dùng liên kết biểu tượng. Thư mục blobs/ và bộ lưu blob dùng chung không được sử dụng ở chế độ này.

Điều này có nghĩa là nội dung tệp giống nhau có thể bị sao chép lặp lại giữa các phiên bản, làm tăng dung lượng sử dụng trên ổ đĩa. Để bật hỗ trợ symlink trên Windows, hãy kích hoạt Developer Mode hoặc chạy với quyền quản trị viên.