الذاكرة المؤقتة المحلية في Hub

يصف هذا المستند الترتيب على القرص لذاكرة التخزين المؤقت المحلية الخاصة بـ HF Hub. وهو مُعدّ كمرجع لإعادة تنفيذ نظام التخزين المؤقت بأي لغة.

فيما يلي قائمة جزئية بالمكتبات والتطبيقات التي تستخدم هذا التخطيط للتخزين المؤقت. يُرجى فتح طلب سحب (PR) لإضافة مكتبتك أو تطبيقك الخاص.

المكتبات

التطبيقات

موقع التخزين المؤقت

المجلد الافتراضي للمخزن المؤقت هو:

~/.cache/huggingface/hub

يمكن تجاوز ذلك باستخدام متغيرات البيئة:

• HF_HUB_CACHE - المسار المباشر إلى مجلد التخزين المؤقت (يتمتع بأولوية أعلى)
• HF_HOME - المسار إلى مجلد Hugging Face الرئيسي؛ إذا تم ضبطه، فإن ذاكرة التخزين المؤقت موجودة في $HF_HOME/hub

نظرة عامة

<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

يحصل كل مستودع مُحمَّل على مجلد مسطّح واحد. داخل مجلد كل مستودع، تُخزَّن الملفات مرة واحدة في مجلد blobs/ المعنون بالمحتوى وتُستخدَم عبر روابط snapshots/ الرمزية. وتُتتبَّع المراجع المسماة (الفرع، الوسوم) في refs/. منذ huggingface_hub 1.32، تُخزَّن الملفات المُحمَّلة عبر hf_xet مرة واحدة لكل كاش، في مخزن blobs مشترك في جذر الكاش. ثم يصبح إدخال blobs/ للمستودع رابطًا رمزيًا إلى ذلك الملف.

المخطط

                     ┌──────────────────────────────────────────┐
                     │           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}

تسمية مجلد المستودع

تُخزَّن المستودعات كمجلدات مسطحة في جذر ذاكرة التخزين المؤقت. يرمز اسم المجلد إلى نوع المستودع ومعرّف المستودع:

{type}s--{repo_id_with_slashes_replaced_by_--}

القواعد:

• نوع المستودع جمع: models، datasets، spaces
• تُستبدل علامات القوسين الأماميين (/) في معرّف المستودع بـ --
• الفاصل بين جميع الأجزاء هو --
• يتم الحفاظ على حالة الأحرف

أمثلة:

لا تُعالَج الدلاء (Buckets) بواسطة هذا المخزن المؤقت لأنها غير مدعومة بواسطة git. استخدم الأمر المخصص hf buckets sync بدلاً من ذلك.

داخل مجلد المستودع

تتمتع كل مستودع مخزّن مؤقتًا بنفس البنية الداخلية:

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

blobs/ : تخزين ملفات مبنٍ على عنوان المحتوى

تخزّن مجلد blobs/ المحتوى الفعلي للملفات. يُسمّى كل ملف باسم etag الخاص به على Hub:

• الملفات المتتبَّع بواسطة Git: تُسمَّى عبر تجزئة SHA-1 الخاصة بها (40 حرفًا سداسيًّا عشريًّا)
• ملفات Git LFS: تُسمّى بواسطة تجزئة SHA-256 (64 حرفًا سداسيًا عشريًا)

هذا مجلد مسطّح — لا توجد مجلدات فرعية. تُخزَّن الملفات المتطابقة عبر المراجعات المختلفة مرة واحدة فقط. إما أن يكون العنصر ملفًا عاديًا أو رابطًا رمزيًا نسبيًا إلى مخزن الكتل المشتركة؛ وينبغي للقُرّاء اتباعه.

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

refs/ : مراجع الفروع والوسوم

تُخزّن المجلد refs/ المراجع التي يمكن للبشر قراءتها (أسماء الفروع، الوسوم، أرقام طلبات الدمج) إلى تجزئات التواقيع.

كل مرجع هو ملف نصي بسيط يحتوي على سطر واحد: تجزئة الالتزام الكاملة (40 حرفًا سداسي العشر).

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

عند تنزيل ملف باستخدام اسم فرع أو وسم، يتم إنشاء الملف المرجعي المقابل أو تحديثه باستخدام أحدث تجزئة التزامن.

snapshots/ : عروض المراجعات

تحتوي مجلد snapshots/ على مجلد فرعي واحد لكل نسخة مخزنة مؤقتًا (تجزئة الالتزام). يعكس كل مجلد نسخة بنية ملفات المستودع على Hub، لكن الملفات هي روابط رمزية تشير إلى ../../blobs/{hash}.

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

الخصائص الرئيسية:

• تستخدم الروابط الرمزية مسارات نسبية: ../../blobs/{hash}
• إذا لم يتغير الملف بين نسختين، فإن كلا من رابطي الاختصار يشير إلى نفس الكائن دون تكرار البيانات
• تمثل الملفات الموجودة في الدلائل الفرعية على Hub كدلائل فرعية في اللقطة (حيث يُحفظ المسار النسبي الكامل)

التبديل بين اللقطات يشبه استخدام git checkout في مستودع git محلي.

.no_exist/ : ذاكرة مؤقتة لعدم الوجود

يتتبع المجلد .no_exist/ الملفات التي طُلبت لكنها غير موجودة على Hub. وهذا يتجنب تكرار طلبات HTTP للملفات الاختيارية.

تعكس البنية هيكل snapshots/: حيث يوجد مجلد فرعي واحد لكل تجزئة التزامن، ويحتوي على ملفات فارغة (وليس روابط رمزية) تحمل أسماء الملفات المفقودة.

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

استهلاك القرص ضئيل لأن هذه ملفات علامة فارغة فقط.

مخزن البيانات المشترك

الملفات التي يتم تنزيلها عبر Xet تُستبعد تكراراتها عبر المستودعات. يُخزَّن مثل هذا الملف مرة واحدة في جذر ذاكرة التخزين المؤقت، تحت blobs/، ويحصل كل مستودع يحتاج إليه على رابط رمزي نسبي بدلاً من نسخة:

<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

الخصائص الرئيسية:

• تحتفظ مدخلات المستودع باسم etag الخاص بها وتصبح رابطًا رمزيًا نسبيًا: ../../blobs/{xet_hash[:2]}/{xet_hash}
• لا يتغير تخطيط snapshots/، لذا لا يتأثر تحديد الملفات
• يحدد ملف العلامة مخزن البيانات: لا يُستخدم أو يُعدَّل أبدًا أي جذر تخزين مؤقت يحتوي على مجلد blobs/ غير فارغ دون وجود هذا الملف.
• يتطلب المخزن روابط رمزية وhf_xet. إذا فشل المشاركة، يُخزَّن الملف في مجلد المستودع كما كان من قبل. يُعطّل HF_HUB_DISABLE_SHARED_BLOBS=1 المخزن
• تخضع عمليات التنزيل الجديدة فقط للمتجر. تبقى الملفات التي كتبتها الإصدارات الأقدم أو العملاء الآخرون ملفات عادية في مجلد المستودع، لذا يمكن أن يحتوي الكاش على كلا النوعين

لا تحتاج التطبيقات التي تقرأ من ذاكرة التخزين المؤقت فقط إلى أي تغييرات: فاتباع الروابط الرمزية يعمل كما كان من قبل.

يجب على التطبيقات التي تحذف من ذاكرة التخزين المؤقت أن تعامل كتلة المستودع التي هي رابط رمزي كمرجع إلى المخزن:

• احذف الرابط الرمزي في blobs/ الخاص بالمستودع، وليس الملف المشترك الذي يشير إليه
• اقفل <xet_hash>.lock قبل التحقق من قائمة البيانات والحذف
• احذف الملف المشترك وملف .refs الخاص به فقط إذا لم يكن أي رابط رمزي مدرج في قائمة التشغيل لا يزال يشير إليه
• إذا كان ملف الوصف مفقودًا أو غير قابل للقراءة، فاحتفظ بالملف المشترك

راجع دليل ذاكرة التخزين المؤقت لـhuggingface_hub لمعرفة سلوك الحذف والقيود المرتبطة بالإصدارات الأقدم من العملاء.

ملفات القفل

تمنع ملفات القفل العمليات المتزامنة من تنزيل نفس الكائن في الوقت نفسه. تُخزَّن هذه الملفات في مجلد .locks/ في جذر ذاكرة التخزين المؤقت (وليس داخل مجلد المستودع):

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

مثال:

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

مثال كامل

~/.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

لاحظ كيف يشير pytorch_model.bin إلى نفس الكائن في كلتا النسختين. يتم تخزين الملف بحجم 321 ميغابايت مرة واحدة فقط على القرص.

منطق حل الملف

لتحديد موقع ملف مخزّن مؤقتًا على القرص:

1. حل المراجعة إلى تجزئة التزامن

   • إذا كان revision سلسلة سداسية عشرية بطول 40 حرفًا بالفعل، فاستخدمها مباشرة
   • وإلا، اقرأ الملف الموجود في refs/{revision} للحصول على تجزئة الالتزام

2. تحقق من لقطة البيانات

   • ابحث عن snapshots/{commit_hash}/{relative_path}
   • إذا كان موجودًا (كارتباط رمزي أو ملف)، يتم تخزين الملف مؤقتًا. اتبع الارتباط الرمزي للحصول على المحتوى

3. التحقق من عدم الوجود

   • ابحث عن .no_exist/{commit_hash}/{relative_path}
   • إذا كان الملف موجودًا، فإنّ الملف معروفٌ بعدم وجوده على Hub لهذا المراجعة

4. فشل في الكاش

   • إذا لم يكن أيٌّ من المسارين موجودًا، فإن الملف لم يُخزَّن مؤقتًا بعد

سلوك ويندوز

يعتمد التخزين المؤقت على الروابط الرمزية. في أنظمة ويندوز التي لا تتوفر فيها الروابط الرمزية، يعمل التخزين المؤقت في وضع متدهور: حيث تُوضع نسخ فعلية من الملفات مباشرةً في snapshots/ بدلاً من الروابط الرمزية. ولا يُستخدم مجلد blobs/ ومخزن الكتل المشترك في هذا الوضع.

هذا يعني أن محتوى الملف نفسه قد يتكرر عبر المراجعات، مما يزيد من استهلاك مساحة القرص. لتفعيل دعم الروابط الرمزية على نظام ويندوز، فعّل وضع المطور أو شغّل البرنامج بصلاحيات المسؤول.