# فهم التخزين المؤقت

`huggingface_hub` يستخدم ذاكرة تخزين مؤقت محلية مبنية على الملفات لتخزين الملفات الفردية التي تم تنزيلها من Hub وتجنّب إعادة تنزيل الملفات التي لم تتغير عند تحديث المستودع. بالإضافة إلى ذلك، يخزّن `hf_xet` ذاكرة تخزين مؤقت للتجزئة وبيانات التجهيز لتحسين عمليات الرفع (انظر [تخزين Xet المؤقت](#xet-caching)).

> [!TIP]
> يتناول هذا الدليل أدوات إدارة ذاكرة التخزين المؤقت الخاصة بلغة بايثون التي يوفرها `huggingface_hub`. للحصول على نظرة عامة لا تعتمد على لغة معينة حول كيفية عمل نظام ذاكرة التخزين المؤقت في Hugging Face Hub، راجع [توثيق Hub حول التخزين المؤقت المحلي](https://huggingface.co/docs/hub/local-cache).

## التخزين المؤقت القائم على الملفات

صُمم نظام التخزين المؤقت في Hugging Face Hub ليكون التخزين المؤقت المركزي المشترك عبر المكتبات التي تعتمد على Hub. وقد تم تحديثه في الإصدار v0.8.0 لمنع إعادة تنزيل الملفات نفسها بين المراجعات.

تم تصميم نظام التخزين المؤقت على النحو التالي:

```
<CACHE_DIR>
├─ <MODELS>
├─ <DATASETS>
├─ <SPACES>
├─ <KERNELS>
```

القيمة الافتراضية لـ `<CACHE_DIR>` هي `~/.cache/huggingface/hub`. ومع ذلك، يمكن تخصيصها باستخدام الحجة `cache_dir` في جميع الطرق، أو عن طريق تحديد متغير البيئة `HF_HOME` أو `HF_HUB_CACHE`.

تشارك النماذج ومجموعات البيانات والمساحات والنوى جذرًا مشتركًا. يحتوي كلٌّ من هذه المستودعات على نوع المستودع، والمساحة الاسم (المنظمة أو اسم المستخدم) إن وُجدت، واسم المستودع:

```
<CACHE_DIR>
├─ models--julien-c--EsperBERTo-small
├─ models--lysandrejik--arxiv-nlp
├─ models--bert-base-cased
├─ datasets--glue
├─ datasets--huggingface--DataMeasurementsFiles
├─ spaces--dalle-mini--dalle-mini
```

تُحمَّل جميع الملفات من Hub الآن داخل هذه المجلدات. يضمن التخزين المؤقت عدم تحميل الملف مرتين إذا كان موجودًا مسبقًا ولم يتم تحديثه؛ أما إذا تم تحديثه، وكنت تطلب أحدث نسخة من الملف، فسيتم تحميل أحدث نسخة (مع الإبقاء على النسخة السابقة كما هي في حال احتجت إليها مرة أخرى).

للوصول إلى ذلك، تحتوي جميع المجلدات على الهيكل نفسه:

```
<CACHE_DIR>
├─ datasets--glue
│  ├─ refs
│  ├─ blobs
│  ├─ snapshots
│  ├─ trees
...
```

صُمم كل مجلد ليحتوي على ما يلي:

### المراجع

تحتوي مجلد `refs` على ملفات تشير إلى أحدث مراجعة للإشارة المعطاة. على سبيل المثال، إذا كنا قد استخرجنا ملفًا سابقًا من فرع `main` في مستودع، فسيحتوي مجلد `refs` على ملف باسم `main`، والذي سيحتوي بدوره على معرّف الالتزام الحالي للرأس.

إذا كان آخر التزام في `main` يحمل المعرّف `aaaaaa`، فسيحتوي على `aaaaaa`.

إذا تم تحديث ذلك الفرع نفسه بارتكاب جديد، يحمل `bbbbbb` كمعرّف، فإن إعادة تنزيل ملف من ذلك المرجع ستحدّث ملف `refs/main` ليحتوي على `bbbbbb`.

### Blobs

تحتوي مجلد `blobs` على الملفات الفعلية التي قمنا بتنزيلها. اسم كل ملف هو تجزئته (hash).

### لقطات

تحتوي مجلد `snapshots` على روابط رمزية إلى الكتل المذكورة أعلاه. ويتكون هو نفسه من عدة مجلدات: واحد لكل مراجعة معروفة!

في الشرح أعلاه، قمنا في البداية بجلب ملف من المراجعة `aaaaaa`، قبل أن نجلب ملفًا من المراجعة `bbbbbb`. في هذه الحالة، سيكون لدينا الآن مجلدان داخل مجلد `snapshots`: `aaaaaa` و`bbbbbb`.

في كلٍّ من هذه المجلدات، توجد روابط رمزية حيّة تحمل أسماء الملفات التي قمنا بتنزيلها. على سبيل المثال، إذا كنا قد قمنا بتنزيل ملف `README.md` عند المراجعة `aaaaaa`، فسيكون المسار التالي:

```
<CACHE_DIR>/<REPO_NAME>/snapshots/aaaaaa/README.md
```

في الواقع، ملف `README.md` هو رابط رمزي يشير إلى الكائن الذي يحتوي على تجزئة الملف.

من خلال إنشاء الهيكل بهذه الطريقة، نفتح آلية مشاركة الملفات: إذا تم جلب نفس الملف في المراجعة `bbbbbb`، فسيكون له نفس التوقيع الرقمي ولن تكون هناك حاجة إلى إعادة تنزيل الملف.

### الأشجار

تخزّن مجلد `trees` قائمة الملفات التي يحتويها المستودع عند نقطة التزامن المحددة. بما أن نقطة التزامن غير قابلة للتغيير، فإن قائمة ملفاتتها لا تتغير أبدًا. وهذا يعني أنه يمكن تخزين القائمة مؤقتًا إلى الأبد دون الحاجة إلى التحقق منها مرة أخرى مقابل Hub.

يُسمّى كل قائمة مخزّنة مؤقتًا باسم تجزئة التزامن (commit hash) وتُخزَّن كملف JSON، على سبيل المثال `trees/aaaaaa.json`. لكل ملف في المستودع عند ذلك التزامن، تسجّل القائمة ما يلزم لتنزيل الملف: مساره، حجمه، وتجزئته. هذه هي نفس المعلومات التي كان سيردّ بها Hub، لكنها عادةً ما تتطلب استدعاءً واحدًا للشبكة لكل ملف لجلبها.

يُكتب هذا الكاش بواسطة [snapshot_download()](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.snapshot_download). عند تنزيلك لأول مرة لالتزام (commit) معين، يتم جلب قائمة الملفات مرة واحدة وحفظها هنا. في المرة التالية التي تنزّل فيها نفس الالتزام، تُقرأ القائمة من القرص بدلاً من إعادة جلبها. ونتيجةً لذلك، فإن إعادة تشغيل عملية التنزيل عندما يكون كل شيء مخزّنًا مسبقًا في الكاش لا يكلف سوى استدعاء شبكة واحد: وهو الاستدعاء المطلوب لحل اسم الفرع أو العلامة (tag) إلى تجزئة الالتزام (commit hash).

تقرأ كلتا الدالتين [snapshot_download()](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.snapshot_download) و [hf_hub_download()](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.hf_hub_download) هذا التخزين المؤقت لتجنب استدعاءات الشبكة. عند تنزيل ملف باستخدام تجزئة الالتزام (commit hash) كإصدار (وهو ما تفعله [snapshot_download()](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.snapshot_download) داخليًا لكل ملف)، يتم قراءة بيانات التنزيل الوصفية من قائمة الملفات المخزنة مؤقتًا ويتم تجاوز استدعاء الشبكة الخاص بكل ملف. وهذا يعني أن استدعاء [hf_hub_download()](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.hf_hub_download) لملف واحد يستفيد أيضًا من قائمة الملفات التي حفظها استدعاء [snapshot_download()](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.snapshot_download) سابقًا لنفس الالتزام.

بما أن قائمة الملفات المخزنة مؤقتًا تصف بالضبط ما يجب أن يحتويه الالتزام، يمكن لـ [snapshot_download()](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.snapshot_download) أيضًا أن يحدد ما إذا كان لقطة محلية مكتملة. إذا تعذر الوصول إلى Hub (أنت غير متصل، أو فشلت الاتصال، أو مررت بـ `local_files_only=True`) وكانت بعض الملفات المتوقعة مفقودة من اللقطة المحلية، يرمي [snapshot_download()](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.snapshot_download) استثناء [IncompleteSnapshotError](/docs/huggingface_hub/main/ar/package_reference/utilities#huggingface_hub.errors.IncompleteSnapshotError) بدلاً من إرجاع مجلد جزئي. قبل ذلك، كانت اللقطة غير المكتملة تُرجع بصمت، مما قد يجعلك تعمل مع ملفات مفقودة دون علم بذلك. الملفات المستبعدة بواسطة `allow_patterns` أو `ignore_patterns` لا تُحتسب كملفات مفقودة. يكشف الاستثناء عن المسار إلى اللقطة غير المكتملة عبر خاصية `snapshot_path` الخاصة به، بحيث يمكنك تحديد موقع الملفات المخزنة مؤقتًا جزئيًا إذا لزم الأمر.

### .no_exist (متقدم)

بالإضافة إلى مجلدات `blobs` و`refs` و`snapshots`، قد تجد أيضاً مجلد `.no_exist` في ذاكرتك المؤقتة. يحتفظ هذا المجلد بسجل للملفات التي حاولت تنزيلها مرة واحدة لكنها غير موجودة على Hub. هيكلته هو نفسه هيكل مجلد `snapshots` مع مجلد فرعي واحد لكل مراجعة معروفة:

```
<CACHE_DIR>/<REPO_NAME>/.no_exist/aaaaaa/config_that_does_not_exist.json
```

على عكس مجلد `snapshots`، تكون الملفات هنا ملفات فارغة بسيطة (بدون روابط رمزية). في هذا المثال، الملف `"config_that_does_not_exist.json"` غير موجود على Hub للمراجعة `"aaaaaa"`. وبما أنه يخزن ملفات فارغة فقط، فإن هذا المجلد يُعدّ ضئيلاً من حيث استهلاك مساحة القرص.

لذا قد تتساءل الآن، لماذا تكون هذه المعلومات ذات صلة؟ في بعض الحالات، تحاول إطار العمل تحميل ملفات اختيارية لنموذج. حفظ عدم وجود الملفات الاختيارية يجعل تحميل النموذج أسرع لأنه يوفر استدعاء HTTP واحد لكل ملف اختياري محتمل. هذا هو الحال على سبيل المثال في `transformers` حيث يمكن لكل مُقسِّم (tokenizer) دعم ملفات إضافية. عند أول تحميل للمُقسِّم على جهازك، سيخزّن مؤقتًا أي الملفات الاختيارية موجودة (وأيها غير موجودة) لجعل وقت التحميل أسرع في المرات التالية من التهيئة.

To test if a file is cached locally (without making any HTTP request), you can use the [try_to_load_from_cache()](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.try_to_load_from_cache) helper. It will either return the filepath (if exists and cached), the object `_CACHED_NO_EXIST` (if non-existence is cached) or `None` (if we don't know).

```python
from huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST

filepath = try_to_load_from_cache()
if isinstance(filepath, str):
    # file exists and is cached
    ...
elif filepath is _CACHED_NO_EXIST:
    # non-existence of file is cached
    ...
else:
    # file is not cached
    ...
```

### في الممارسة العملية

عملياً، يجب أن يبدو مخزنك المؤقت (Cache) كشجرة من الشكل التالي:

```text
    [  96]  .
    └── [ 160]  models--julien-c--EsperBERTo-small
        ├── [ 160]  blobs
        │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
        │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
        ├── [  96]  refs
        │   └── [  40]  main
        ├── [ 128]  snapshots
        │   ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        │   └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
        │       ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
        │       └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [  96]  trees
            ├── [ 521]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f.json
            └── [ 521]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48.json
```

### CACHEDIR.TAG

`huggingface_hub` ينشئ تلقائيًا ملف [`CACHEDIR.TAG`](https://bford.info/cachedir/) داخل مجلد التخزين المؤقت. يتبع هذا الوسم *معيار وسم مجلدات التخزين المؤقت* ويخبر أدوات النسخ الاحتياطي (مثل Borg وrestic وrsync) أن المجلد يحتوي على بيانات تخزين مؤقت قابلة لإعادة التنزيل ويمكن استبعادها بأمان من عمليات النسخ الاحتياطي.

### القيود

لضمان نظام تخزين مؤقت فعّال، يستخدم `huggingface-hub` الروابط الرمزية. ومع ذلك، لا تدعم جميع الأجهزة الروابط الرمزية، وهي قيود معروفة خاصةً على نظام Windows. في هذه الحالة، لا يستخدم `huggingface_hub` مجلد `blobs/` بل يخزّن الملفات مباشرةً في مجلد `snapshots/` بدلاً من ذلك. تتيح هذه الطريقة البديلة للمستخدمين تنزيل الملفات وتخزينها مؤقتاً من Hub بنفس الطريقة تماماً. كما يتم دعم الأدوات الفاحصة لحذف التخزين المؤقت (انظر أدناه). ومع ذلك، يكون نظام التخزين المؤقت أقل كفاءة، إذ قد يتم تنزيل ملف واحد عدة مرات إذا تم تنزيل عدة مراجع لنفس المستودع.

إذا كنت ترغب في الاستفادة من نظام التخزين المؤقت القائم على الروابط الرمزية على جهاز ويندوز، فيجب عليك إما [تفعيل وضع المطوّر](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) أو تشغيل بايثون بصلاحيات المسؤول.

إذا كنت ترغب في استخدام وضع التخزين المؤقت بدون روابط رمزية بشكل استباقي (على سبيل المثال، على نظام ملفات مشترك لا يتعامل مع الروابط الرمزية بشكل جيد)، يمكنك تعيين متغير البيئة [`HF_HUB_DISABLE_SYMLINKS`](../package_reference/environment_variables#hfhubdisablesymlinks) إلى `1`. سيتم نسخ الملفات مباشرة إلى `snapshots/` بدلاً من إنشاء روابط رمزية إلى `blobs/`.

عندما لا تكون الروابط الرمزية مدعومة، يتم عرض رسالة تحذير للمستخدم لإعلامه بأنه يستخدم نسخة متدهورة من نظام التخزين المؤقت. يمكن تعطيل هذا التحذير عن طريق تعيين متغير البيئة `HF_HUB_DISABLE_SYMLINKS_WARNING` إلى true.

### المقاطع المشتركة بين المستودعات

بشكل افتراضي، يتم أيضًا إزالة التكرار من ملفات Xet عبر المستودعات. تُخزَّن ملف Xet الذي تم تنزيله عبر `hf_xet` مرة واحدة في `<CACHE_DIR>/blobs/<prefix>/<xet_hash>`، بينما يكون إدخال `blobs/<etag>` الخاص بالمستودع رابطًا رمزيًا نسبيًا إليه. عندما يحتاج مستودع آخر إلى نفس الملف، يحصل على رابط رمزي بدلاً من التنزيل: لا يتم نقل أي بايت ولا يُستخدم أي مساحة إضافية. لا يتغير تخطيط اللقطة. يحدد ملف علامة المخزن، لذا لا يتم المساس أبدًا بمجلد `blobs` لم يتم إنشاؤه بواسطة `huggingface_hub`.

يحتوي كل ملف مشترك على قائمة `<xet_hash>.refs` تُدرج كتل المستودع التي تستخدمه. تقرأ `hf cache rm` هذه القائمة للتحقق فقط من الملفات المشتركة المتأثرة بالحذف، وتزيل `hf cache prune` الملفات المشتركة التي لم يعد أي مستودع مخزّن مؤقتًا يستخدمها. القائمة مجرد تلميح: يتم التحقق من كل إدخال مقابل نظام الملفات، ويُحتفظ بأي ملف تكون بياناته الوصفية مفقودة أو غير قابلة للقراءة. تفضل عملية التنظيف ترك بيانات قابلة للاسترداد على كسر إدخال تخزين مؤقت صالح.

تبقى أحجام المستودعات الفردية منطقية، إذ يُحتسب الملف المشترك لكل مستودع يستخدمه. أما `size_on_disk` على مستوى الكاش بالكامل فهو فيزيائي: يُحتسب كل ملف مشترك مرة واحدة، بما في ذلك الملفات التي لم يعد أي مستودع يستخدمها.

تستمر العملاء الأقدم (`huggingface_hub`، `huggingface.js`، `hf-hub`، `llama.cpp`، وأي شيء يتبع الروابط الرمزية) في القراءة والتنزيل بشكل طبيعي، في مجلدات المستودعات نفسها. هناك قيودان:
- يترك `huggingface_hub<=1.31` الملفات المشتركة المستودع المحذوف في المخزن، حيث يحدد `hf cache ls` هذه الملفات ويحذفها `hf cache prune`. قد تحذف أدوات حذف الكاش الخاصة بالعملاء الآخرين بدلاً من ذلك ملفاً مشتركاً ما زال مستخدماً من قبل مستودعات أخرى؛ يتم إعادة تنزيل الملفات المتأثرة عند الاستخدام التالي. استخدم إصداراً محدثاً من `huggingface_hub` لأوامر `hf cache rm` و`hf cache prune` والحذف البرمجي.
- قد تُبلّغ مُسحّات ذاكرة التخزين المؤقت لديهم عن مجلد `blobs` في المستوى الأعلى كعنصر غير معروف.

يتطلب المتجر تخطيط ذاكرة التخزين المؤقت القائم على الروابط الرمزية، ويُعطَّل عبر `HF_HUB_DISABLE_XET=1`. أي فشل في مشاركة ملف، مثل نظام ملفات غير مدعوم، أو خطأ في الصلاحيات، أو وجود مسبق لمجلد `blobs` غير مُعلَّم، يؤدي بصمت إلى الرجوع إلى التخزين المحلي العادي للمستودع. اضبط [`HF_HUB_DISABLE_SHARED_BLOBS=1`](../package_reference/environment_variables#hfhubdisablesharedblobs) للاستبعاد بالكامل.

## تثبيت نسخة (متقدم)

> [!TIP]
> إذا كنت تقوم بدمج Hub في مكتبة تعلّم آلي، فإن استدعاء [snapshot_download()](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.snapshot_download) الواحد لا يزال النهج الموصى به: فهو يحلّل المراجعة مرة واحدة، ويحمّل كل شيء بالتوازي، ويخزّن قائمة الملفات مؤقتًا. ما يلي مفيد فقط للمكتبات المعقدة التي تحمّل وتحمّل العديد من المكونات بشكل منفصل (config، weights، tokenizer، processor، adapters، ...) ولا يمكنها استخدام استدعاء واحد.

عندما يقوم أحد المكتبات بتنزيل عدة ملفات واحدة تلو الأخرى، يجب على كل استدعاء أن يحل `revision="main"` إلى تجزئة التزامن من جديد. وهذا يستهلك استدعاء HTTP واحداً لكل ملف، والأسوأ من ذلك أن الاستدعاءين المنفذين بفارق ثوانٍ قليلة قد ينتهيان إلى تزامنين مختلفين إذا تم تحديث المستودع بينهما.

تحلّ [HfApi.resolve_revision()](/docs/huggingface_hub/main/ar/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision) المراجعة مرة واحدة وتعيد [ResolvedRevision](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.ResolvedRevision):

```py
>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')
```

[ResolvedRevision](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.ResolvedRevision) هو فئة فرعية من `str`، لذا يمكن تمريره إلى أي طريقة في `huggingface_hub` تقبل معامل `revision`. قيمته النصية هي ما طلبه المستخدم في البداية (`"main"` هنا، مما يجعل رسائل الخطأ قابلة للقراءة)، بينما يحتوي `.resolved` على تجزئة الالتزام:

```py
>>> revision == "main"
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'
```

تكتشف أدوات التنزيل ([hf_hub_download()](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.hf_hub_download)، [snapshot_download()](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.snapshot_download)، [get_cached_repo_tree()](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.get_cached_repo_tree)) كائن [ResolvedRevision](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.ResolvedRevision) وتستخدم تجزئة الالتزام مباشرة. يُضمن أن كل ملف يأتي من نفس الالتزام، وبمجرد تخزين الملفات مؤقتًا لا تكون هناك حاجة إلى أي استدعاء HTTP على الإطلاق:

```py
>>> from huggingface_hub import hf_hub_download
>>> config = hf_hub_download("openai-community/gpt2", "config.json", revision=revision)
>>> weights = hf_hub_download("openai-community/gpt2", "model.safetensors", revision=revision)
```

يتم أيضًا كتابة تعيين `revision` -> `commit hash` في مجلد `refs/` من ذاكرة التخزين المؤقت (انظر [Refs](#refs)). وهذا يعني أنه إذا تعذّر الوصول إلى Hub لاحقًا (وضع عدم الاتصال، خطأ في الاتصال، انتهاء المهلة، توقف Hub عن العمل)، فإن [HfApi.resolve_revision()](/docs/huggingface_hub/main/ar/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision) يلجأ بشكل شفاف إلى القيمة المخزنة مؤقتًا. وإذا لم يكن هناك أي شيء مخزن مؤقتًا، يتم رفع [RevisionResolutionError](/docs/huggingface_hub/main/ar/package_reference/utilities#huggingface_hub.errors.RevisionResolutionError).

لا يعني مُعرّف الالتزام (commit hash) شيئًا إلا بالنسبة إلى المستودع الذي تم حله ضده، وتستخدم أدوات التحميل هذا المُعرّف كما هو. لذا يجب تمرير [ResolvedRevision](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.ResolvedRevision) فقط إلى المستودع الذي تم حله من أجله. إذا كان المكتبة تقوم أيضًا بتنزيل ملفات من مستودع آخر (نموذج أساسي، مُكيّف، مكوّن موجود في مستودع مستقل به، ...)، فهي بحاجة إلى نسخة (revision) محلولَة لذلك المستودع. ما عليك سوى تمرير [ResolvedRevision](/docs/huggingface_hub/main/ar/package_reference/file_download#huggingface_hub.ResolvedRevision) مرة أخرى إلى [HfApi.resolve_revision()](/docs/huggingface_hub/main/ar/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision): فهو يتذكر المستودع الذي ينتمي إليه ويعيد حل النسخة المطلوبة في الأصل (`"main"` هنا) من جديد للمستودع الجديد.

```py
>>> other_revision = resolve_revision("openai-community/gpt2-medium", revision=revision)  # resolves "main" again
>>> other_revision.resolved
'6dcaa7a952f72f9298047fd5137cd6e4f05f41da'
>>> config = hf_hub_download("openai-community/gpt2-medium", "config.json", revision=other_revision)
```

## تخزين Xet مؤقت

لتوفير عمليات رفع أكثر كفاءة، يضيف `hf_xet` مجلد `xet` إلى ذاكرة التخزين المؤقت الحالية لـ`huggingface_hub`. يخزّن هذا المجلد الشظايا (وهي بنية بيانات تربط الملفات بالقطع) وبيانات التهيئة المستخدمة لإزالة التكرار من عمليات الرفع واستئنافها. لمزيد من المعلومات حول نظام تخزين Xet، راجع هذا [القسم](https://huggingface.co/docs/hub/xet/index).

لم يعد `hf_xet` يستخدم ذاكرة تخزين مؤقت محلية للقطع لتنزيل الملفات. لا يؤدي ضبط `HF_XET_CHUNK_CACHE_SIZE_BYTES` إلى تفعيلها. لا تزال الملفات المنزلة مخزنة مؤقتًا في [ذاكرة التخزين المؤقت القائمة على الملفات](#file-based-caching).

يمكن تكوين مجلد `xet`، الذي يقع افتراضيًا في `~/.cache/huggingface/xet`، باستخدام [`HF_XET_CACHE`](../package_reference/environment_variables#hfxetcache). ويتضمن البنية التالية:

```bash
<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ shard-cache
│  │  ├─ staging
```

مجلد `environment_identifier` هو نص مُرمَّز (قد يظهر على جهازك على شكل `https___cas_serv-tGqkUaZf_CBPHQ6h`). يُستخدم هذا أثناء التطوير مما يتيح وجود إصدارات محلية وإنتاجية من ذاكرة التخزين المؤقت جنبًا إلى جنب في الوقت نفسه. كما يُستخدم عند التنزيل من المستودعات التي تقع في [مناطق تخزين](https://huggingface.co/docs/hub/storage-regions) مختلفة. قد ترى عدة إدخالات من هذا النوع في مجلد `xet`، حيث يتوافق كل منها مع بيئة مختلفة، لكن هيكلها الداخلي متطابق.

تخدم المجلدات الداخلية الأغراض التالية:
* `shard-cache` يحتوي على شظايا مخزنة مؤقتًا تُستخدم في مسار الرفع.
* `staging` هو مساحة عمل مصممة لدعم عمليات رفع قابلة للاستئناف.

وهي موثقة أدناه.

يُدير `hf_xet` ذاكرة التخزين المؤقت للتقسيمات وبيانات الترحيل كطبقة تحسين للعمليات المرفوعة. ولإدارة الملفات المُحمّلة، استخدم واجهات برمجة التطبيقات القائمة على الملفات في `huggingface_hub`.

### `shard-cache`

يُستخدم هذا الكاش عند رفع المحتوى إلى Hub. المجلد مسطّح، ويتكوّن فقط من ملفات شُعب (shards)، حيث يستخدم كل منها معرّفًا (ID) كاسم للشعبة.

```sh
<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ shard-cache
│  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb
│  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb
│  │  │  ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb
```

تحتوي `shard-cache` على شظايا هي:

- تم توليده محلياً وتم رفعه بنجاح إلى CAS
- تم تنزيلها من CAS كجزء من خوارزمية إزالة التكرار العالمية

توفّر الشرائح (Shards) إسقاطًا بين الملفات والقطع. أثناء عمليات الرفع، تُقسَّم كل ملف إلى قطع ويُحفظ تجزئة (hash) كل قطعة. ثم يُستشار كل شريحة في ذاكرة التخزين المؤقت. إذا احتوت شريحة على تجزئة قطعة موجودة في الملف المحلي قيد الرفع، فيمكن التخلّي عن تلك قطعة لأنها مخزنة مسبقًا في نظام التخزين المركزي (CAS).

تنتهي صلاحية جميع الشرائح بعد 3-4 أسابيع من تاريخ تنزيلها. لا يتم تحميل الشرائح التي انتهت صلاحيتها أثناء الرفع، وتُحذف بعد أسبوع من انتهاء صلاحيتها.

### `staging`

عندما ينتهي الرفع قبل أن يتم تثبيت المحتوى الجديد في المستودع، ستحتاج إلى استئناف نقل الملف. ومع ذلك، من الممكن أن تكون بعض المقاطع قد تم رفعها بنجاح قبل الانقطاع.

حتى لا تضطر إلى البدء من جديد، تعمل مجلد `staging` كمساحة عمل أثناء عمليات الرفع، حيث يخزّن البيانات الوصفية للقطع التي تم رفعها بنجاح. ويتخذ مجلد `staging` الشكل التالي:

```
<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ staging
│  │  │  ├─ shard-session
│  │  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  │  ├─ xorb-metadata
│  │  │  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb
```

عند معالجة الملفات ورفع المقاطع بنجاح، تُخزَّن بياناتها الوصفية في `xorb-metadata` على شكل شريحة. عند استئناف جلسة الرفع، تُعالَج كل الملفات مرة أخرى ويُستشار محتوى الشرائح الموجودة في هذا المجلد. يتم تجاوز أي محتوى تم رفعه بنجاح، ويُرفع أي محتوى جديد (مع حفظ بياناته الوصفية).

في غضون ذلك، يخزّن `shard-session` معلومات الملفات والقطع الخاصة بالملفات المعالجة. عند اكتمال عملية الرفع بنجاح، يتم نقل المحتوى من هذه القطع إلى `shard-cache` الأكثر دوامًا.

### القيود والمحدّدات

يتمتع `shard-cache` بحد أقصى مرن يبلغ 16 جيجابايت، ويمكن ضبطه عبر متغير البيئة [`HF_XET_SHARD_CACHE_SIZE_LIMIT`](../package_reference/environment_variables#hfxetshardcachesizelimit). لا يتوفر أي واجهة برمجة تطبيقات عالية المستوى لإدارة هذا الكاش.

تُستخدم ذاكرة التخزين المؤقت للتقسيمات وبيانات الترحيل لتحسين عمليات الرفع. للتفاعل مع الأصول نفسها، يُوصى باستخدام واجهات برمجة التطبيقات الخاصة بنظام ذاكرة التخزين المؤقت في [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/guides/manage-cache).

إذا كنت بحاجة إلى استعادة المساحة التي يستخدمها Xet أو إلى تصحيح أي مشاكل محتملة متعلقة بالذاكرة المؤقتة، فما عليك سوى إزالة ذاكرة `xet` المؤقتة بالكامل عن طريق تشغيل `rm -rf ~/<cache_dir>/xet` حيث `<cache_dir>` هو موقع ذاكرة Hugging Face المؤقتة لديك، وهو عادةً `~/.cache/huggingface`

مثال على شجرة مجلد كاش `xet`:

```sh
<CACHE_DIR>
├─ xet
│  ├─ environment_identifier
│  │  ├─ shard-cache
│  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb
│  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb
│  │  │  ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb
│  │  ├─ staging
│  │  │  ├─ shard-session
│  │  │  │  ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb
│  │  │  │  ├─ xorb-metadata
│  │  │  │  │  ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb
```

للمزيد من المعلومات حول Xet Storage، راجع هذا [القسم](https://huggingface.co/docs/hub/xet/index).

## تخزين الأصول

بالإضافة إلى تخزين ملفات المستودع (Hub) مؤقتًا، تتطلب المكتبات التابعة (downstream libraries) غالبًا تخزين ملفات أخرى مرتبطة بـ HF لكنها غير مُدارة مباشرةً بواسطة `huggingface_hub` (مثل: ملف تم تنزيله من GitHub، بيانات مُعالجة مسبقًا، سجلات، ...). من أجل تخزين هذه الملفات، المسمّى بـ `assets`، يمكن استخدام [cached_assets_path()](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.cached_assets_path). يولّد هذا المساعد الصغير مسارات في ذاكرة التخزين المؤقت لـ HF بطريقة موحّدة بناءً على اسم المكتبة التي تطلب ذلك، وخيارًا بناءً على مساحة أسماء (namespace) واسم مجلد فرعي. الهدف هو السماح لكل مكتبة تابعة بإدارة أصولها بطريقتها الخاصة (مثلًا: لا توجد قاعدة على الهيكل) طالما أنها تبقى في مجلد الأصول الصحيح. يمكن لهذه المكتبات بعد ذلك الاستفادة من أدوات `huggingface_hub` لإدارة ذاكرة التخزين المؤقت، ولا سيما مسح أجزاء من الأصول وحذفها عبر أمر سطر الأوامر (CLI).

```py
from huggingface_hub import cached_assets_path

assets_path = cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="download")
something_path = assets_path / "something.json" # Do anything you like in your assets folder !
```

> [!TIP]
> يُعد [cached_assets_path()](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.cached_assets_path) الطريقة الموصى بها لتخزين الأصول، لكنه ليس إلزاميًا. إذا كانت مكتبتك تستخدم بالفعل ذاكرة تخزين مؤقت خاصة بها، فلا تتردد في استخدامها!

### الأصول في الممارسة

عملياً، يجب أن يبدو كاش الأصول لديك كشجرة مماثلة لما يلي:

```text
    assets/
    └── datasets/
    │   ├── SQuAD/
    │   │   ├── downloaded/
    │   │   ├── extracted/
    │   │   └── processed/
    │   ├── Helsinki-NLP--tatoeba_mt/
    │       ├── downloaded/
    │       ├── extracted/
    │       └── processed/
    └── transformers/
        ├── default/
        │   ├── something/
        ├── bert-base-cased/
        │   ├── default/
        │   └── training/
    hub/
    └── models--julien-c--EsperBERTo-small/
        ├── blobs/
        │   ├── (...)
        │   ├── (...)
        ├── refs/
        │   └── (...)
        └── [ 128]  snapshots/
            ├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/
            │   ├── (...)
            └── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/
                └── (...)
```

## إدارة ذاكرة التخزين المؤقت القائمة على الملفات

### فحص ذاكرتك المؤقتة

حاليًا، لا يتم حذف الملفات المخزّنة مؤقتًا من مجلدك المحلي أبدًا: عند تنزيل نسخة جديدة من فرع، تُحفظ الملفات السابقة في حال احتجت إليها مرة أخرى. لذلك، قد يكون من المفيد فحص مجلد التخزين المؤقت لمعرفة المستودعات والنسخ التي تستهلك أكبر قدر من مساحة القرص. يوفر `huggingface_hub` أدوات مساعدة يمكنك استخدامها من سطر الأوامر `hf` أو من Python.

**فحص ذاكرة التخزين المؤقت من الطرفية**

شغّل `hf cache ls` لاستكشاف ما هو مخزّن محليًا. افتراضيًا، يجمع الأمر المعلومات حسب المستودع:

```text
➜ hf cache ls
ID                                   SIZE   LAST_ACCESSED LAST_MODIFIED REFS
------------------------------------ ------- ------------- ------------- -------------------
dataset/glue                         116.3K 4 days ago     4 days ago     2.4.0 main 1.17.0
dataset/google/fleurs                 64.9M 1 week ago     1 week ago     main refs/pr/1
model/Jean-Baptiste/camembert-ner    441.0M 2 weeks ago    16 hours ago   main
model/bert-base-cased                  1.9G 1 week ago     2 years ago
model/t5-base                          10.1K 3 months ago   3 months ago   main
model/t5-small                        970.7M 3 days ago     3 days ago     main refs/pr/1

Found 6 repo(s) for a total of 12 revision(s) and 3.4G on disk.
```

أضف `--revisions` لعرض كل لقطة مخزّنة مؤقتًا، واربط عوامل التصفية للتركيز على ما يهم. تفهم عوامل التصفية الأحجام والمُدَد الصديقة للمستخدم، لذا تعمل تعبيرات مثل `size>1GB` أو `accessed>30d` مباشرةً:

```text
➜ hf cache ls --revisions --filter "size>1GB" --filter "accessed>30d"
ID                                   REVISION            SIZE   LAST_MODIFIED REFS
------------------------------------ ------------------ ------- ------------- -------------------
model/bert-base-cased                6d1d7a1a2a6cf4c2    1.9G  2 years ago
model/t5-small                       1c610f6b3f5e7d8a    1.1G  3 months ago  main

Found 2 repo(s) for a total of 2 revision(s) and 3.0G on disk.
```

هل تحتاج إلى مخرجات صالحة للآلة؟ استخدم `--format json` للحصول على كائنات منظمة أو `--format csv` للجدول الإلكتروني. أو استخدم `--quiet` لطباعة المعرّفات فقط (واحد في كل سطر) حتى تتمكن من تمريرها إلى أدوات أخرى. استخدم `--sort` لترتيب الإدخالات حسب `accessed` أو `modified` أو `name` أو `size` (أضف `:asc` أو `:desc` للتحكم في الترتيب)، و`--limit` لتقييد النتائج بأفضل N إدخالات. اجمع هذه الخيارات مع `--cache-dir` عندما تحتاج إلى فحص ذاكرة تخزين مؤقت محفوظة خارج `HF_HOME`.

**التصفية باستخدام أدوات shell الشائعة**

يعني المخرجات الجدولية أنك تستطيع مواصلة استخدام الأدوات التي تعرفها بالفعل. على سبيل المثال، يحدد المقطع أدناه كل نسخة مخزنة مؤقتاً مرتبطة بـ `t5-small`:

```text
➜ eval "hf cache ls --revisions" | grep "t5-small"
model/t5-small                       1c610f6b3f5e7d8a    1.1G  3 months ago  main
model/t5-small                       8f3ad1c90fed7a62    820.1M 2 weeks ago   refs/pr/1
```

**فحص ذاكرة التخزين المؤقت من بايثون**

للاستخدام الأكثر تقدماً، استخدم [scan_cache_dir()](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.scan_cache_dir) وهو الأداة البرمجية بلغة بايثون التي يستدعيها أداة سطر الأوامر.

يمكنك استخدامه للحصول على تقرير مفصّل مبني حول 4 فئات بيانات:

- [HFCacheInfo](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.HFCacheInfo): التقرير الكامل الذي يعيده [scan_cache_dir()](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.scan_cache_dir)
- [CachedRepoInfo](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.CachedRepoInfo): معلومات حول مستودع مخزّن مؤقتًا
- [CachedRevisionInfo](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.CachedRevisionInfo): معلومات عن نسخة مخزنة مؤقتًا (مثل "snapshot") داخل مستودع
- [CachedFileInfo](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.CachedFileInfo): معلومات حول ملف مخزّن مؤقتًا في لقطة

إليك مثالًا بسيطًا للاستخدام. راجع المرجع للتفاصيل.

```py
>>> from huggingface_hub import scan_cache_dir

>>> hf_cache_info = scan_cache_dir()
HFCacheInfo(
    size_on_disk=3398085269,
    repos=frozenset({
        CachedRepoInfo(
            repo_id='t5-small',
            repo_type='model',
            repo_path=PosixPath(...),
            size_on_disk=970726914,
            nb_files=11,
            last_accessed=1662971707.3567169,
            last_modified=1662971107.3567169,
            revisions=frozenset({
                CachedRevisionInfo(
                    commit_hash='d78aea13fa7ecd06c29e3e46195d6341255065d5',
                    size_on_disk=970726339,
                    snapshot_path=PosixPath(...),
                    # No `last_accessed` as blobs are shared among revisions
                    last_modified=1662971107.3567169,
                    files=frozenset({
                        CachedFileInfo(
                            file_name='config.json',
                            size_on_disk=1197
                            file_path=PosixPath(...),
                            blob_path=PosixPath(...),
                            blob_last_accessed=1662971707.3567169,
                            blob_last_modified=1662971107.3567169,
                        ),
                        CachedFileInfo(...),
                        ...
                    }),
                ),
                CachedRevisionInfo(...),
                ...
            }),
        ),
        CachedRepoInfo(...),
        ...
    }),
    warnings=[
        CorruptedCacheException("Snapshots dir doesn't exist in cached repo: ..."),
        CorruptedCacheException(...),
        ...
    ],
)
```

### تحقق من ذاكرتك المؤقتة

يمكن لـ`huggingface_hub` التحقق من تطابق الملفات المخزنة مؤقتًا لديك مع قيم التجزئة (checksums) على Hub. استخدم أمر `hf cache verify` في سطر الأوامر للتحقق من اتساق الملفات لإصدار محدد من مستودع محدد:

```bash
>>> hf cache verify meta-llama/Llama-3.2-1B-Instruct
✅ Verified 13 file(s) for 'meta-llama/Llama-3.2-1B-Instruct' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6
  All checksums match.
```

تحقّق من نسخة مخزّنة محددة:

```bash
>>> hf cache verify meta-llama/Llama-3.1-8B-Instruct --revision 0e9e39f249a16976918f6564b8830bc894c89659
```

> [!TIP]
> راجع [مرجع سطر الأوامر `hf cache verify`](../package_reference/cli#hf-cache-verify) لمزيد من التفاصيل حول الاستخدام وقائمة كاملة بالخيارات.

### تنظيف ذاكرة التخزين المؤقت

إن فحص ذاكرة التخزين المؤقت أمر مثير للاهتمام، لكن ما تريد فعله عادةً في الخطوة التالية هو حذف بعض الأجزاء لتحرير مساحة على القرص. وهذا ممكن باستخدام أوامر سطر الأوامر `hf cache rm` و`hf cache prune`. كما يمكن استخدام الدوال المساعدة [delete_revisions()](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.HFCacheInfo.delete_revisions) و[delete_files()](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.HFCacheInfo.delete_files) برمجياً من كائن [HFCacheInfo](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.HFCacheInfo) الذي يُعاد عند فحص ذاكرة التخزين المؤقت.

**استراتيجية الحذف**

لحذف بعض البيانات المؤقتة، يجب عليك تمرير قائمة بالمراجعات المراد حذفها. سيعرّف الأداة استراتيجية لتحرير المساحة بناءً على هذه القائمة. تُرجع الأداة كائن [DeleteCacheStrategy](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.DeleteCacheStrategy) يصف الملفات والمجلدات التي سيتم حذفها. يتيح لك كائن [DeleteCacheStrategy](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.DeleteCacheStrategy) معرفة مقدار المساحة المتوقعة للتحرير. بمجرد موافقتك على الحذف، يجب عليك تنفيذه لجعل الحذف ساري المفعول. ولتجنب أي تناقضات، لا يمكنك تعديل كائن الاستراتيجية يدويًا.

الاستراتيجية لحذف المراجعات هي كالتالي:

- يتم حذف مجلد `snapshot` الذي يحتوي على روابط الرمزات (symlinks) للإصدارات.
- تُحذف ملفات blobs التي تستهدفها فقط المراجعات المزمع حذفها.
- إذا كان هناك ارتباط بين نسخة واحدة أو أكثر من `refs`، يتم حذف المراجع.
- إذا تم حذف جميع المراجعات من مستودع، يتم حذف المستودع المخزّن مؤقتًا بالكامل.

يتبع حذف الملفات الفردية باستخدام [delete_files()](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.HFCacheInfo.delete_files) المنطق نفسه: تُحذف إدخالات اللقطة، ولا تُحذف كتل البيانات الخاصة بها إلا إذا لم تكن أي ملفات أخرى مخزنة مؤقتًا تشير إليها. وتُحافظ على المراجع ومجلدات اللقطات.

> [!TIP]
> تُعدّ تجزئات المراجعات فريدة عبر جميع المستودعات. لذلك، يقبل `hf cache rm` إما معرّف المستودع (مثل `model/bert-base-uncased`) أو تجزئة مراجعة مجردة؛ عند تمرير تجزئة، لا حاجة إلى تحديد المستودع بشكل منفصل.

> [!WARNING]
> إذا لم يُعثر على نسخة (revision) في ذاكرة التخزين المؤقت، فسيتم تجاهلها بصمت. بالإضافة إلى ذلك، إذا تعذّر العثور على ملف أو مجلد أثناء محاولة حذفه، فسيُسجَّل تحذير لكن لن يتم إطلاق خطأ. يستمر الحذف بالنسبة للمسارات الأخرى المحتوية في كائن [DeleteCacheStrategy](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.DeleteCacheStrategy).

**تنظيف ذاكرة التخزين المؤقت من الطرفية**

استخدم `hf cache rm` لحذف المستودعات أو المراجعات نهائياً من ذاكرتك المؤقتة. مرر معرّف مستودع واحد أو أكثر (على سبيل المثال `model/bert-base-uncased`) أو تجزئات المراجعة:

```text
➜ hf cache rm model/bert-base-cased
About to delete 1 repo(s) totalling 1.9G.
  - model/bert-base-cased (entire repo)
Proceed with deletion? [y/N]: y
Deleted 1 repo(s) and 1 revision(s); freed 1.9G.
```

يمكنك أيضًا استخدام `hf cache rm` بالاقتران مع `hf cache ls --quiet` لحذف العناصر المحددة بواسطة عامل تصفية دفعة واحدة:

```bash
>>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) -y
About to delete 2 repo(s) totalling 5.31G.
  - model/meta-llama/Llama-3.2-1B-Instruct (entire repo)
  - model/hexgrad/Kokoro-82M (entire repo)
Deleted 2 repo(s) and 2 revision(s); freed 5.31G.
```

اخلط المستودعات والمراجعات في نفس الاستدعاء. أضف `--dry-run` لمعاينة الأثر، أو `--yes` لتخطي مطالبة التأكيد عند استخدام السكربتات:

```text
➜ hf cache rm model/t5-small 8f3ad1c --dry-run
About to delete 1 repo(s) and 1 revision(s) totalling 1.1G.
  - model/t5-small:
      8f3ad1c [main] 1.1G
Dry run: no files were deleted.
```

لإزالة ملف واحد بدلاً من مستودع كامل، على سبيل المثال كميّة GGUF واحدة، مرّر عنوان URI للملف بصيغة `hf://`. يُزال الملف من كل نسخة مخبأة من المستودع، ولا يُحذف blob الخاص به إلا إذا لم يكن أي ملف مخبأ آخر لا يزال يشير إليه. تبقى النسخة قابلة للاستخدام، ويُعاد تنزيل الملف المحذوف في المرة التالية التي يُحتاج فيها. يجب أن تتطابق المسارات تمامًا: لا يتم دعم المجلدات أو أنماط glob.

```text
➜ hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-run
About to delete 1 file(s) totalling 16.5G.
  - model/unsloth/gemma-3-27b-it-GGUF@3f4b5c1d2e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c/gemma-3-27b-it-Q4_K_M.gguf
Dry run: no files were deleted.
```

عند العمل خارج موقع التخزين المؤقت الافتراضي، اجمع الأمر مع `--cache-dir PATH`.

لتنظيف مخلفات ذاكرة التخزين المؤقت دفعة واحدة، شغّل `hf cache prune`. يحذف تلقائيًا المراجعات التي لم تعد تشير إليها أي فرع أو وسم، وملفات `.incomplete` المتبقية من عمليات تنزيل انقطعت، والكتل المشتركة التي لم تعد تشير إليها أي مستودع مخزّن مؤقتًا:

```text
➜ hf cache prune
About to delete 3 unreferenced revision(s) and 2 incomplete download(s) (2.4G total).
  - model/t5-small:
      1c610f6b [refs/pr/1] 820.1M
      d4ec9b72 [(detached)] 640.5M
  - dataset/google/fleurs:
      2b91c8dd [(detached)] 937.6M
Proceed? [y/N]: y
Deleted 3 unreferenced revision(s) and 2 incomplete download(s); freed 2.4G.
```

ملفات `.incomplete` هي كتل جزئية تُترك خلفها عندما ينقطع التحميل. لا تتتبعها الفحصية القائمة على المراجعات، لذا فإن `hf cache ls` يكتفي بإبرازها كتنبيه (`Found X incomplete download(s) ...`) بينما الأمر الذي يزيلها فعلياً هو `hf cache prune`. أما `hf cache rm` فلا يمسّها أبداً، باستثناء حالة حذف مستودع بالكامل.

تدعم كلا الأمرين `--dry-run` و`--yes` و`--cache-dir` مما يتيح لك معاينة العمليات، وأتمتتها، وتحديد مسارات ذاكرة تخزين مؤقت بديلة حسب الحاجة.

**تنظيف ذاكرة التخزين المؤقت من بايثون**

لمزيد من المرونة، يمكنك أيضًا استخدام طريقة [delete_revisions()](/docs/huggingface_hub/main/ar/package_reference/cache#huggingface_hub.HFCacheInfo.delete_revisions) برمجياً. إليك مثالًا بسيطًا. راجع المرجع للتفاصيل.

```py
>>> from huggingface_hub import scan_cache_dir

>>> delete_strategy = scan_cache_dir().delete_revisions(
...     "81fd1d6e7847c99f5862c9fb81387956d99ec7aa"
...     "e2983b237dccf3ab4937c97fa717319a9ca1a96d",
...     "6c0e6080953db56375760c0471a8c5f2929baf11",
... )
>>> print("Will free " + delete_strategy.expected_freed_size_str)
Will free 8.6G

>>> delete_strategy.execute()
```