تنزيل الملفات من Hub

توفر مكتبة huggingface_hub دوال لتنزيل الملفات من المستودعات المخزنة على Hub. يمكنك استخدام هذه الدوال بشكل مستقل أو دمجها في مكتبتك الخاصة، مما يجعل تفاعل مستخدميك مع Hub أكثر راحة. ستوضح لك هذه الدليل كيفية:

• تنزيل ملف واحد وتخزينه مؤقتًا.
• تنزيل مستودع كامل وتخزينه مؤقتًا.
• تنزيل الملفات إلى مجلد محلي.

تنزيل ملف واحد

تُعدّ الدالة hf_hub_download() الدالة الرئيسية لتنزيل الملفات من Hub. تقوم بتنزيل الملف البعيد، وتخزينه مؤقتًا على القرص (بطريقة تراعي الإصدارات)، ثم تُرجع مسار الملف المحلي الخاص به.

مسار الملف المُعاد هو مؤشر إلى ذاكرة التخزين المؤقت المحلية لـ HF. لذلك، من المهم عدم تعديل الملف لتجنب تلف ذاكرة التخزين المؤقت. إذا كنت مهتمًا بمعرفة المزيد حول كيفية تخزين الملفات مؤقتًا، فيرجى الرجوع إلى دليل التخزين المؤقت الخاص بنا.

من أحدث إصدار

حدد الملف الذي تريد تنزيله باستخدام المعلمات repo_id وrepo_type وfilename. افتراضيًا، يُعتبر الملف جزءًا من مستودع model.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
'/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

# Download from a dataset
>>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset")
'/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py'

من إصدار محدد

بشكل افتراضي، يتم تنزيل أحدث إصدار من فرع main. ومع ذلك، في بعض الحالات قد ترغب في تنزيل ملف بإصدار معين (مثل فرع محدد، أو طلب دمج، أو وسم، أو تجزئة التزام). للقيام بذلك، استخدم معامل revision:

# Download from the `v1.0` tag
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0")

# Download from the `test-branch` branch
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch")

# Download from Pull Request #3
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3")

# Download from a specific commit hash
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a")

ملاحظة: عند استخدام تجزئة الالتزام، يجب أن تكون التجزئة بطولها الكامل وليس تجزئة التزام مكوّنة من 7 أحرف.

إنشاء رابط تنزيل

في حال رغبتك في بناء الرابط المستخدم لتنزيل ملف من مستودع، يمكنك استخدام hf_hub_url() الذي يعيد رابطًا. لاحظ أنه يُستخدم داخليًا بواسطة hf_hub_download().

تنزيل مستودع كامل

تنزّل snapshot_download() مستودعًا كاملًا عند إصدار معيّن. تستخدم داخليًا hf_hub_download() مما يعني أن جميع الملفات المنزّلة تُخزَّن مؤقتًا أيضًا على القرص المحلي لديك. تُنفَّذ عمليات التنزيل بالتوازي لتسريع العملية.

لتحميل مستودع كامل، ما عليك سوى تمرير repo_id وrepo_type:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

# Or from a dataset
>>> snapshot_download(repo_id="google/fleurs", repo_type="dataset")
'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34'

تنزّل snapshot_download() أحدث مراجعة افتراضيًا. إذا كنت ترغب في مراجعة مستودع محددة، فاستخدم معامل revision:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1")

تصفية الملفات للتنزيل

يوفر snapshot_download() طريقة سهلة لتنزيل مستودع. ومع ذلك، لا ترغب دائمًا في تنزيل المحتوى الكامل لمستودع. على سبيل المثال، قد ترغب في منع تنزيل جميع ملفات .bin إذا كنت تعلم أنك ستستخدم فقط أوزان .safetensors. يمكنك القيام بذلك باستخدام معاملي allow_patterns وignore_patterns.

تقبل هذه المعلمات نمطًا واحدًا أو قائمة بأنماط. الأنماط هي Wildcards قياسية (أنماط globbing) كما هو موثق هنا. تعتمد مطابقة الأنماط على fnmatch.

على سبيل المثال، يمكنك استخدام allow_patterns لتنزيل ملفات تكوين JSON فقط:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json")

من ناحية أخرى، يمكن لـignore_patterns استبعاد ملفات معينة من التحميل. يتجاهل المثال التالي امتدادات الملفات .msgpack و.h5:

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"])

أخيرًا، يمكنك دمج الاثنين معًا لتصفية تنزيلك بدقة. إليك مثالًا لتنزيل جميع ملفات json و markdown باستثناء vocab.json.

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json")

تنزيل ملف أو ملفات إلى مجلد محلي

نوصي افتراضياً باستخدام نظام التخزين المؤقت لتنزيل الملفات من Hub. يمكنك تحديد موقع تخزين مؤقت مخصص باستخدام معامل cache_dir في hf_hub_download() و snapshot_download()، أو عن طريق تعيين متغير البيئة HF_HOME.

ومع ذلك، إذا كنت بحاجة إلى تنزيل الملفات إلى مجلد محدد، يمكنك تمرير معامل local_dir إلى دالة التنزيل. وهذا مفيد لجعل سير العمل أقرب إلى ما يقدمه أمر git. ستحتفظ الملفات المنزلة ببنية الملفات الأصلية داخل المجلد المحدد. على سبيل المثال، إذا كان filename="data/train.csv" وlocal_dir="path/to/folder"، فسيكون مسار الملف الناتج "path/to/folder/data/train.csv".

يتم إنشاء مجلد .cache/huggingface/ في جذر مجلدك المحلي يحتوي على بيانات وصفية عن الملفات التي تم تنزيلها. يمنع هذا إعادة تنزيل الملفات إذا كانت محدّثة بالفعل. إذا تغيّرت البيانات الوصفية، يتم تنزيل النسخة الجديدة من الملف. وهذا يجعل local_dir مُحسّنًا لجلب أحدث التغييرات فقط.

بعد إتمام التنزيل، يمكنك بأمان حذف مجلد .cache/huggingface/ إذا لم تعد بحاجة إليه. ومع ذلك، كن على دراية بأن إعادة تشغيل سكريبتك دون وجود هذا المجلد قد تؤدي إلى أوقات استرداد أطول، نظراً لفقدان البيانات الوصفية. اطمئن إلى أن بياناتك المحلية ستبقى سليمة وغير متأثرة.

لا تقلق بشأن مجلد .cache/huggingface/ عند إرسال التغييرات إلى Hub! يتم تجاهل هذا المجلد تلقائيًا بواسطة كل من git وupload_folder().

التحميل من سطر الأوامر

يمكنك استخدام أمر hf download من الطرفية لتنزيل الملفات مباشرةً من Hub. داخليًا، يستخدم نفس أدوات المساعدة hf_hub_download() وsnapshot_download() الموصوفة أعلاه، ويُطبع المسار المُعاد في الطرفية.

>>> hf download gpt2 config.json
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json

يمكنك تنزيل عدة ملفات في وقت واحد، حيث يتم عرض شريط تقدم وإرجاع مسار اللقطة الذي توجد فيه الملفات:

>>> hf download gpt2 config.json model.safetensors
Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10

يمكنك أيضًا الإشارة إلى المستودع (وإختياريًا إلى نسخة وملف) باستخدام وحدة عنوان hf:// واحدة. يتبع هذا العنوان القواعد النحوية hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (راجع مرجع عناوين HF للاطلاع على الصياغة الكاملة) ويستبدل خيارَي --repo-type و--revision، حيث لا يمكن ضبطهما معًا:

# Download a single file from a dataset at a given revision
>>> hf download hf://datasets/google/fleurs@refs/pr/1/fleurs.py

# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/google/fleurs/data/

# Download an entire repo
>>> hf download hf://datasets/google/fleurs

لمزيد من التفاصيل حول أمر التنزيل عبر سطر الأوامر، يُرجى الرجوع إلى دليل سطر الأوامر.

وضع التشغيل التجريبي

في بعض الحالات، قد ترغب في التحقق من الملفات التي سيتم تنزيلها قبل تنزيلها فعليًا. يمكنك التحقق من ذلك باستخدام معامل --dry-run. يقوم هذا المعامل بإدراج جميع الملفات المراد تنزيلها في المستودع والتحقق مما إذا كانت قد تم تنزيلها بالفعل أم لا. وهذا يمنح فكرة عن عدد الملفات التي يجب تنزيلها وأحجامها.

فيما يلي مثال، للتحقق من ملف واحد:

>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 1 files (out of 1) totalling 655.2M
File                           Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx 655.2M

وإذا كان الملف مخزّنًا مؤقتًا بالفعل:

>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 0 files (out of 1) totalling 0.0.
File                           Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx -

يمكنك أيضًا تنفيذ تشغيل تجريبي على مستودع كامل:

>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00,  6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File                              Bytes to download
--------------------------------- -----------------
.gitattributes                    -
64-8bits.tflite                   125.2M
64-fp16.tflite                    248.3M
64.tflite                         495.8M
README.md                         -
config.json                       -
flax_model.msgpack                497.8M
generation_config.json            -
merges.txt                        -
model.safetensors                 548.1M
onnx/config.json                  -
onnx/decoder_model.onnx           653.7M
onnx/decoder_model_merged.onnx    655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json       -
onnx/merges.txt                   -
onnx/special_tokens_map.json      -
onnx/tokenizer.json               -
onnx/tokenizer_config.json        -
onnx/vocab.json                   -
pytorch_model.bin                 548.1M
rust_model.ot                     702.5M
tf_model.h5                       497.9M
tokenizer.json                    -
tokenizer_config.json             -
vocab.json                        -

ومع تصفية الملفات:

>>> hf download openai-community/gpt2 --include "*.json"  --dry-run
[dry-run] Fetching 11 files: 100%|█████████████| 11/11 [00:00<00:00, 80518.92it/s]
[dry-run] Will download 0 files (out of 11) totalling 0.0.
File                         Bytes to download
---------------------------- -----------------
config.json                  -
generation_config.json       -
onnx/config.json             -
onnx/generation_config.json  -
onnx/special_tokens_map.json -
onnx/tokenizer.json          -
onnx/tokenizer_config.json   -
onnx/vocab.json              -
tokenizer.json               -
tokenizer_config.json        -
vocab.json                   -

أخيرًا، يمكنك أيضًا إجراء تشغيل تجريبي برمجيًا عن طريق تمرير dry_run=True إلى hf_hub_download() و snapshot_download(). سيعيد ذلك DryRunFileInfo (أو قائمة من DryRunFileInfo على التوالي) تحتوي لكل ملف على: تجزئة الالتزام (commit hash)، واسم الملف، وحجم الملف، وما إذا كان الملف مخزّنًا مؤقتًا، وما إذا كان سيُحمَّل الملف. عمليًا، سيُحمَّل الملف إذا لم يكن مخزّنًا مؤقتًا أو إذا تم تمرير force_download=True.

تنزيلات أسرع

استفد من تنزيلات أسرع عبر hf_xet، وهي واجهة بايثون لمكتبة xet-core التي تُمكّن من إزالة التكرار على أساس المقاطع (chunks) لتنزيلات ورفوعات أسرع. يتكامل hf_xet بسلاسة مع huggingface_hub، لكنه يستخدم مكتبة xet-core بلغة Rust وتخزين Xet بدلاً من LFS.

hf_xet يستخدم نظام تخزين Xet، الذي يقسم الملفات إلى مقاطع غير قابلة للتغيير، ويخزّن مجموعات من هذه المقاطع (المعروفة باسم blocks أو xorbs) عن بُعد، ثم يستعيدها لإعادة تجميع الملف عند الطلب. عند التنزيل، وبعد التأكد من أن المستخدم مصرّح له بالوصول إلى الملفات، يستعلم hf_xet من خدمة Xet القابلة للعنوان بالمحتوى (CAS) باستخدام تجزئة LFS SHA256 الخاصة بهذا الملف، لاستلام بيانات الوصف اللازمة لإعادة البناء (النطاقات داخل xorbs) لتجميع هذه الملفات، إلى جانب روابط موقّعة مسبقًا لتنزيل xorbs مباشرة. ثم يقوم hf_xet بتنزيل نطاقات xorb اللازمة بكفاءة، وكتابة الملفات على القرص.

لتفعيله، ما عليك سوى تثبيت أحدث إصدار من huggingface_hub:

pip install -U "huggingface_hub"

بدايةً من huggingface_hub 0.32.0، سيؤدي هذا أيضًا إلى تثبيت hf_xet.

ستواصل جميع واجهات huggingface_hub الأخرى العمل دون أي تعديل. لمعرفة المزيد حول فوائد تخزين Xet وhf_xet، راجع هذا القسم.

ملاحظة: كان يُستخدم hf_transfer سابقًا مع وحدة تخزين LFS، وهو الآن غير مدعوم؛ استخدم hf_xet بدلاً منه.