الترحيل إلى دلاء التخزين

يُبيّن هذا الدليل كيفية نقل مجموعات البيانات الكبيرة إلى Storage Bucket من أي مكان توجد فيه حاليًا: القرص المحلي، سحابة أخرى، أو Hub. ابحث عن مصدر بياناتك في الجدول أدناه وانتقل إلى القسم المعني.

في كل مكان يمكنك فيه، اجعل بياناتك قابلة للقراءة كنظام ملفات وشغّل hf sync. فهو يُزيل التكرار على مستوى العميل، مما يعني أنك ستحمّل عددًا أقل من البايتات مقارنةً بنسخة خام.

لمحة عامة

لماذا يُعدّ hf sync الخيار الافتراضي:

• ترفع بيانات أقل. يرفع hf sync البيانات عبر عميل Xet، الذي يقسّم بياناتك ويزيل التكرار فيها أولاً، بحيث تُرسل فقط المقاطع التي لم يسبق للمركز (Hub) رؤيتها. أما النسخ الخام (على سبيل المثال، باستخدام rclone عبر بوابة S3) فينقل كل بايت.
• إنه على الأقل بنفس السرعة. في عمليات الترحيل التي دعمناها حتى الآن، حقق hf sync عبر مصدر مُثبّت أداءً مماثلاً لأداء rclone أو تفوّق عليه من حيث معدل نقل البيانات.

قبل أن تبدأ

تستخدم جميع الأوامر في هذا الدليل hf، وهو واجهة سطر الأوامر الخاصة بـ Hugging Face. مخرجات المساعدة الخاصة به قابلة للقراءة من قبل الوكلاء، لذا يمكن لوكيل البرمجة تجميع هجرة ومراقبتها نيابةً عنك (انظر واجهة سطر الأوامر لوكلاء الذكاء الاصطناعي). راجع الأوامر قبل تنفيذها على نطاق واسع.

1. ثبّت واجهة سطر الأوامر. يأتي عميل Xet مدمجًا معه.

   تم النسخ

   curl -LsSf https://hf.co/cli/install.sh | bash
   hf version

2. سجّل الدخول برمز وصول يتمتع بصلاحيات الكتابة (أنشئ رمزًا):

   تم النسخ

   hf auth login
   hf auth whoami

3. أنشئ حاوية الوجهة. <namespace> هو اسم المستخدم أو المنظمة. بدون --region، تُنشأ الحاوية في منطقة التخزين الافتراضية للمساحة، وهي دائمًا الولايات المتحدة خارج خطط Team & Enterprise. في تلك الخطط، مرّر --region us أو --region eu للاختيار.

   تم النسخ

   hf buckets create <namespace>/<bucket> --private

ابدأ بتشغيل تجريبي. بغضّ النظر عن المسار الذي تستخدمه، تدرّب عليه على مجموعة فرعية صغيرة (مجلد واحد، أو نمط --include)، وتحقق من النتيجة باستخدام --dry-run وhf buckets ls، ثم أطلق عملية الترحيل الكاملة. يمكن استئناف كل مسار في هذا الدليل، لذا فإن التشغيل التجريبي لا يكلف شيئًا.

من القرص المحلي أو نظام ملفات العنقود

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

hf sync ./data hf://buckets/<namespace>/<bucket>/data

يقارن hf sync بين المصدر والوجهة وينقل الفرق فقط، لذا فإن إعادة تشغيل نفس الأمر يستأنف عملية الترحيل المقطوعة: يتم تخطي الملفات التي تم رفعها بالفعل. المتغيرات الشائعة:

# Mirror exactly: also delete destination files that are gone from the source
hf sync ./data hf://buckets/<namespace>/<bucket>/data --delete

# Preview what would transfer, without uploading
hf sync ./data hf://buckets/<namespace>/<bucket>/data --dry-run

# Only some files
hf sync ./data hf://buckets/<namespace>/<bucket>/data --include "*.parquet" --exclude "tmp/*"

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

hf sync ./data hf://buckets/<namespace>/<bucket>/data --plan plan.jsonl   # scan once, write the plan
hf sync --apply plan.jsonl                                                # run exactly that plan

شغّل --apply من المجلد الذي أنشأت فيه الخطة، لأن الخطة تسجّل مسار المصدر كما أدخلته. لا يتحقق --apply مما تم رفعه بالفعل، لذا لاستئناف تشغيلٍ مُقاطَع، أعد تشغيل الأمر العادي hf sync بدلاً من ذلك.

للتحقق، تأكد من أن التشغيل التجريبي لا يحتوي على أي شيء متبقٍ للنقل، وقم بفحص عينات من المحتوى:

hf sync ./data hf://buckets/<namespace>/<bucket>/data --dry-run
hf buckets ls hf://buckets/<namespace>/<bucket>/data

ضبط

• احتفظ بالذاكرة المؤقتة على قرص سريع. يخزّن عميل Xet المقاطع وفهرس إزالة التكرار (ذاكرة الشرائح المؤقتة) تحت HF_HOME. وجّه HF_HOME إلى NVMe محلي إذا لم يكن مجلد المستخدم الرئيسي على NVMe.
• تفعيل وضع الأداء العالي للترحيلات الضخمة على جهاز مموّل جيدًا. يرفع HF_XET_HIGH_PERFORMANCE=1 مستوى التزامن، وحجم المخازن المؤقتة، وعدد الملفات المُدخلة في آنٍ واحد، مما يتيح للعميل استخدام كل نواة معالج CPU وإشباع الشبكة. وهو مخصص للأجهزة ذات النطاق الترددي العالي والقرص السريع؛ ومع إصدارات hf_xet السابقة عن 1.7.0، استخدمه فقط مع ذاكرة عشوائية تبلغ 64 جيجابايت على الأقل (تحقق من ذاكرتك باستخدام hf env). راجع متغيرات البيئة.
• حدّد حجم ذاكرة التخزين المؤقت للشظايا. حدّ الحجم الأقصى لها مرن: يتمّ تقليص الذاكرة المؤقتة فقط عند بدء التشغيل، لذا قد تتجاوز الحدّ بكثير خلال تشغيل واحد طويل. في عملية ترحيل كبيرة، لا سيما في وضع الأداء العالي، قد تنمو إلى مئات الجيجابايت وتملأ القرص، مما يُسبّب إنهاء التشغيل. اضبط HF_XET_SHARD_CACHE_SIZE_LIMIT بمقدار مريح دون مساحة القرص المتاحة، لكن لا تجعله أقلّ ممّا تحتاج: ذاكرة مؤقتة بحجم X تُزيل التكرار مقابل ما يقارب 1000 × X من البيانات. راجع ذاكرة التخزين المؤقت للشظايا.

اضبط هذه الإعدادات قبل بدء المزامنة. تقبل الأحجام قيمًا مقروءة من قبل الإنسان مثل 64gb:

export HF_HOME=/mnt/nvme/hf                 # chunk and shard caches on NVMe
export HF_XET_HIGH_PERFORMANCE=1            # use all cores and the full network
export HF_XET_SHARD_CACHE_SIZE_LIMIT=64gb   # keep the shard cache under free disk space

hf sync ./data hf://buckets/<namespace>/<bucket>/data

التقسيم حسب المسار الفرعي (تجريبي)

للمجموعات البيانات الكبيرة جدًا، يمكنك تقسيم المصدر إلى مسارات فرعية وتشغيل عدة عمليات hf sync في وقت واحد. تشير الاختبارات المبكرة إلى أن معدل الإنتاجية يتوسع بشكل خطي تقريبًا، لكن هذا يحتاج إلى مزيد من التحقق. قاعدتان:

• قسّم على البيانات ذات الصلة، بحيث تُزيل ملفات كل عامل التكرارات بشكل جيد فيما بينها.
• امنح كل عامل HF_HOME خاصًا به حتى لا يتنافسوا على ذاكرة التخزين المؤقت. نظرًا لأن كل ذاكرة تخزين مؤقت تستهلك مساحة على القرص، فقسّم HF_XET_SHARD_CACHE_SIZE_LIMIT بين العمال.

HF_HOME=/mnt/nvme/hf-a hf sync ./data/groupA hf://buckets/<namespace>/<bucket>/groupA &
HF_HOME=/mnt/nvme/hf-b hf sync ./data/groupB hf://buckets/<namespace>/<bucket>/groupB &
wait

تشارك عملية واحدة ذاكرة تخزين مؤقت واحدة وتُزيل التكرارات بشكل أفضل، لذا لا تقسّم إلا عندما تعجز عملية واحدة عن إشباع شبكتك.

استكشاف الأخطاء وإصلاحها

من AWS S3 أو تخزين متوافق مع S3

لا يقرأ hf sync عناوين s3://، لذا يجب تركيب حاوية المصدر كنظام ملفات باستخدام Mountpoint for Amazon S3، ثم المزامنة من نقطة التركيب. لا يزال بياناتك تمر عبر عميل Xet، مما يمنحك إزالة التكرار على جانب العميل.

mount-s3 my-source-bucket /mnt/src
hf sync /mnt/src hf://buckets/<namespace>/<bucket>
umount /mnt/src

للمخازن المتوافقة مع S3 مثل Cloudflare R2 أو MinIO، أضف --endpoint-url <url> إلى mount-s3. بالنسبة إلى دلو عام يسمح بالقراءات المجهولة، مثل تلك الموجودة في سجل AWS Open Data، أضف --no-sign-request. التحقق والضبط واستكشاف الأخطاء وإصلاحها هي نفسها بالنسبة إلى البيانات المحلية.

بديل: rclone عبر بوابة S3

استخدم هذا الخيار إذا كنت تشغّل rclone بالفعل وتفضّل عدم استخدام المونت. المفاضلة هنا: يرسل rclone كل بايت عبر بوابة S3 دون إزالة التكرار على مستوى العميل، لذا ينقل بيانات أكثر من hf sync. تحتاج إلى بيانات اعتماد S3 للبوابة.

استخدم rclone 1.70 أو أحدث (تحقق باستخدام rclone version، وقم بالترقية من تحميلات rclone). قد تستنفد الإصدارات الأقدم الذاكرة عند سرد دلاء كبيرة جداً. غالباً ما ينصح في الإرشادات القديمة باستخدام --fast-list؛ مع إصدار حديث من rclone لا تحتاج إليه، وفي حالة سرد ضخم يحتفظ بكل شيء في الذاكرة وقد يسبب نفس الفشل.

أضف البوابة كعن بُعد في ~/.config/rclone/rclone.conf، بجوار العن بُعد الخاص بمصدر البيانات (aws أدناه):

[hf]
type = s3
provider = Other
endpoint = https://s3.hf.co/<namespace>
access_key_id = HFAK...
secret_access_key = ...
region = us-east-1
force_path_style = true
list_version = 2
upload_cutoff = 256M
chunk_size = 256M

يدعم البوابة list_version = 2 فقط، لذا يُشترط استخدام list_version = 2. مع 256 مليون جزء، تُقسَّم الملفات الكبيرة إلى عدد أقل بكثير من الأجزاء مقارنةً بالقيمة الافتراضية لـ rclone البالغة 5 ملايين جزء. يحتفظ rclone بأربعة أجزاء لكل عملية نقل في الذاكرة، لذا يتطلب الأمر حوالي 16 جيجابايت من ذاكرة الوصول العشوائي عند استخدام --transfers 16 أدناه؛ قم بتقليل هذا الرقم على الأجهزة الأصغر. ثم انسخ الملفات وتحقق منها:

rclone copy aws:my-source-bucket hf:<bucket> --transfers 16 --checkers 16 --progress
rclone check aws:my-source-bucket hf:<bucket>

rclone copy ينقل فقط الكائنات المفقودة أو التي تم تغييرها، لذا فهو آمن لإعادة التشغيل لاستئناف العملية. قبل استيراد كبير، اقرأ قيود البوابة، ولا سيما قواعد تسمية مفاتيح الكائنات.

من Google Cloud Storage أو Azure Blob Storage

نفس النهج المتبع مع S3: قم بتركيب المصدر باستخدام مُشغّل سحابة المصدر الخاصة به، ثم نفّذ hf sync.

Google Cloud Storage: اربطه باستخدام gcsfuse.

gcsfuse my-gcs-bucket /mnt/src
hf sync /mnt/src hf://buckets/<namespace>/<bucket>

Azure Blob Storage: يُركَّب باستخدام blobfuse2. يحدد ملف الإعداد اسم حساب التخزين والحاوية.

blobfuse2 mount /mnt/src --config-file=./blobfuse2.yaml
hf sync /mnt/src hf://buckets/<namespace>/<bucket>

بدون نقطة تثبيت، يمكنك استخدام rclone (يقرأ GCS وAzure بشكل أصلي؛ أعد استخدام البعيد hf في الأعلى، مع نفس تنازل عدم إزالة التكرار)، أو نفّذ الترحيل كوظيفة.

شغّل عملية الترحيل في الخلفية باستخدام Jobs

Jobs يشغّل سكربت على حوسبة Hugging Face: تختار العتاد، وتطلقه من سطر الأوامر، وتدفع بالدقيقة. استخدمه عندما تريد أن تعمل هجرة طويلة متعددة التيرابايت دون إشراف، بدلاً من تشغيلها على حاسوبك المحمول أو في جلسة يجب إبقاؤها مفتوحة.

1. اكتب سكربت الترحيل (migrate.py). ينسخ هذا المثال كل كائن في بادئة S3 إلى دلو عبر عميل Xet، مما يؤدي إلى إزالة التكرار من عمليات الكتابة. يناسب هذا النهج نسخًا لمرة واحدة لبادئة متوسطة الحجم؛ أما للبادئات الكبيرة جدًا، فراجع hf-s3ream. عدّل الإعدادات في الأعلى:

# /// script
# dependencies = ["huggingface_hub", "boto3", "tqdm"]
# ///
import boto3
from botocore import UNSIGNED
from botocore.config import Config
from huggingface_hub import HfFileSystem
from tqdm.contrib.concurrent import thread_map

# --- adapt these ---
SRC_BUCKET = "my-source-bucket"
SRC_PREFIX = "some/prefix/"
DST = "buckets/<namespace>/<bucket>"
WORKERS = 8   # files copied in parallel
# -------------------

s3 = boto3.client("s3")   # AWS credentials come from the Job's secrets
# For a public bucket (for example from the AWS Open Data registry), read anonymously
# instead, and drop the AWS secrets from the launch command:
# s3 = boto3.client("s3", config=Config(signature_version=UNSIGNED))
fs = HfFileSystem()       # HF token comes from the Job's HF_TOKEN secret

# List the destination once: {path: size} of the files already copied
done = {path: info["size"] for path, info in fs.find(DST, detail=True).items()}

# List the source and keep the objects not copied yet
todo = []
pages = s3.get_paginator("list_objects_v2").paginate(Bucket=SRC_BUCKET, Prefix=SRC_PREFIX)
for page in pages:
    for obj in page.get("Contents", []):
        key = obj["Key"]
        if key.endswith("/"):
            continue  # folder marker: bucket keys can't end with "/"
        if done.get(f"{DST}/{key}") != obj["Size"]:
            todo.append(key)

def copy(key):
    body = s3.get_object(Bucket=SRC_BUCKET, Key=key)["Body"]
    with fs.open(f"{DST}/{key}", "wb") as out:
        for chunk in iter(lambda: body.read(64 << 20), b""):
            out.write(chunk)

# Copy WORKERS files at a time, with a progress bar
thread_map(copy, todo, max_workers=WORKERS)

• يُخزَّن كل كائن مؤقتًا على قرص المهمة ثم يُرفع عند إغلاقه، لذا يجب أن يتسع القرص لعدد WORKERS من أكبر الكائنات لديك في آنٍ واحد. ارفع قيمة WORKERS لتسريع رفع العديد من الكائنات الصغيرة، وخفّضها في حال كانت الكائنات كبيرة جدًا.
• تُتخطى الملفات الموجودة مسبقًا في الدلو والتي لها نفس الحجم، لذا فإن إعادة تشغيل السكربت تستأنف عملية النسخ المقطوعة. لن يعيد السكربت نسخ ملف المصدر الذي تغيّر لكنه احتفظ بحجمه: للحفاظ على مزامنة الدلو مع مصدر متغيّر، ركّب المصدر وشغّل hf sync بدلاً من ذلك.

في حال استخدام GCS أو Azure، استبدل boto3 بـ SDK الخاص بذلك السحابة (google-cloud-storage، azure-storage-blob) وعدّل استدعاءات القائمة والقراءة. يبقى الجزء المتعلق بالوجهة كما هو.

2. شغّله كمهمة في الخلفية، مع تمرير بيانات الاعتماد الخاصة بك كقيم سرية:

hf jobs uv run --detach --flavor cpu-performance --timeout 24h \
  --secrets HF_TOKEN \
  --secrets AWS_ACCESS_KEY_ID \
  --secrets AWS_SECRET_ACCESS_KEY \
  migrate.py

يمرّر كل --secrets NAME قيمة ذلك المتغير من بيئة التشغيل (في حالة HF_TOKEN، يُستخدم رمز الدخول الخاص بك إذا لم يكن مُعيَّنًا). تتوقف المهام بعد 30 دقيقة افتراضيًا، لذا عيّن --timeout بقيمة كافية لإتمام النقل بالكامل؛ وإذا توقفت مهمة مبكرًا، أعد تشغيلها وستتخطى الملفات التي تم نسخها بالفعل.

يعيد --detach معرّف المهمة (Job ID) فورًا. يمكنك متابعة التقدم باستخدام hf jobs logs -f <job_id>، وعرض قائمة التشغيلات باستخدام hf jobs ls، ومشاهدة خيارات الأجهزة باستخدام hf jobs hardware.

من مستودع Hub أو حاوية أخرى

إذا كانت البيانات موجودة مسبقًا على Hub، في مستودع نموذج أو مجموعة بيانات أو حاوية أخرى، انسخها على جانب الخادم. بالنسبة للملفات التي تتبعتها Xet فقط، تنتقل تجزئات المحتوى فقط، لذا يكون النسخ شبه فوري ولا يتم إعادة رفع أي شيء.

# From a dataset repository into a bucket
hf buckets cp hf://datasets/<org>/<dataset>/<path> hf://buckets/<namespace>/<bucket>/<path>

# From one bucket to another
hf buckets cp hf://buckets/<namespace>/<bucket-a>/<path> hf://buckets/<namespace>/<bucket-b>/<path>

• يجب أن يكون المصدر والوجهة في نفس منطقة التخزين.
• تحتاج إلى صلاحية القراءة للمصدر وصلاحية الكتابة للوجهة.
• تُحمَّل الملفات الصغيرة غير المُتتبَّعة بواسطة Xet (مثل ملفات الإعدادات وملفات README) وتُعاد رفعها تلقائيًا.
• لا يتوفر نسخ البيانات من الدلو (Bucket) إلى المستودع (Repository) بعد؛ وهو مدرج في خارطة الطريق.

راجع نسخ الملفات بين المستودعات والخزانات للحصول على ما يعادلها بلغة بايثون.

بادئات S3 كبيرة جداً مع hf-s3ream

أداة hf-s3ream هي أداة مجتمعية في مرحلة مبكرة (تجريبية) وليست منتجًا مدعومًا رسميًا من Hugging Face. اختبرها على بادئة صغيرة قبل استخدامها في هجرة كبيرة.

يعمل hf-s3ream (المصدر على GitHub، Apache-2.0) على نسخ كبير من S3 إلى bucket من واجهة ويب:

1. سجّل الدخول باستخدام Hugging Face.
2. أدخل بادئة المصدر في S3، ودلو الوجهة، ومعرّفات AWS الخاصة بك. بالنسبة لدلو عام يسمح بالقراءات المجهولة، فعّل دلو عام: لا حاجة إلى معرّفات AWS، وتقرأ Jobs من S3 دون توقيع.
3. Analyze يشغّل تجربة تشغيل منخفضة التكلفة للتحقق من الوصول، وتحديد منطقة المصدر، واقتراح تكوين. يقوم بإنشاء دلو الوجهة (خاص) إذا لم يكن موجودًا.
4. يُطلق Run مهمة مخطط. يبني المخطط خطة نسخ مبنية على نطاقات، ويبدأ مهام النسخ، ويعرض التقدم على رسم بياني حي. يستمر النسخ في العمل إذا أغلقت التبويب، لكن الصفحة لن تعيد الاتصال به. لإيقاف النسخ، انقر على Stop copy، أو ألغِ مهمة المخطط (hf jobs cancel <planner-job-id>): سيلغي المخطط مهام النسخ الخاصة به.

يعمل hf-s3ream على Jobs ضمن حسابك، لذا تُحتسب فواتير الـ Jobs عليك. لا يمكن الوصول إلى دلاء S3 التي تسمح بالوصول من شبكة خاصة (VPC) فقط من خلال الـ Jobs.

أين تُنفَّذ هجرة كبيرة

في حالة هجرة بيانات متعددة التيرابايت، ستقوم عادةً بتشغيل عملية النقل على آلة افتراضية سحابية بدلاً من حاسوب محمول. إذا كنت تفضّل عدم إدارة آلة افتراضية، قم بتشغيلها كعملية.

• شغّل العملية في نفس السحابة والمنطقة التي يوجد فيها المصدر. قراءة المصدر عبر الشبكة المحلية هي الأسرع والأرخص، وغالبًا ما تكون تكلفة الإخراج من سحابة المصدر هي التكلفة الأكبر. ثم تتم عمليات الرفع عبر الإنترنت إلى Hugging Face (تقع منطقة الولايات المتحدة في AWS us-east-1).
• استخدم عملية واحدة مع العديد من الخيوط. عملية hf sync واحدة في وضع الأداء العالي تشارك ذاكرة تخزين مؤقت واحدة لإزالة التكرار. قسّم حسب المسار الفرعي فقط عندما لا تستطيع عملية واحدة إشباع شبكتك.
• حافظ على استمرار المهام الطويلة. عند استخدام SSH، ابدأ عملية الترحيل داخل tmux (أو screen، أو nohup) حتى تبقى العملية قائمة في حال انقطاع الجلسة: tmux new -s migrate، ثم افصل عن الجلسة بالضغط على Ctrl-b ثم d، وأعد الاتصال بها لاحقًا باستخدام tmux attach -t migrate.

نقاط البداية لتحديد الحجم، للتحقق منها في تشغيل تجريبي:

الخطوات التالية

• استخدم البيانات في مكانها. قم بتركيب الدلو كنظام ملفات محلي باستخدام hf-mount، أو كـحجم في Jobs وSpaces.
• اقرأ البيانات من أدواتك. تقرأ pandas وDask وPyArrow وDaft وDuckDB و🤗 Datasets وSpark مسارات hf://buckets/... مباشرة. راجع تكاملات الدلاء.

لا تقم بتنفيذ عملية استيراد كبيرة عبر نقطة تركيب. يقوم /tmp/hf-mount-cache بتخزين عمليات الكتابة مؤقتًا في ذاكرة تخزين مؤقت على القرص (افتراضيًا في /tmp/hf-mount-cache)، وقد يؤدي تنفيذ هجرة كبيرة عبره إلى امتلاء ذلك القرص. استخدم أحد المسارات المذكورة أعلاه لوضع البيانات في الدلو. إذا كان عليك كتابة كميات كبيرة عبر نقطة تركيب، فوجّه ذاكرة التخزين المؤقت إلى قرص يتوفر فيه مساحة حرة كافية: hf-mount start --cache-dir /mnt/big bucket <namespace>/<bucket> /mnt/data (يُوضع هذا العلم قبل bucket).