Hub documentation

التوافق مع S3

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

التوافق مع S3

يمكن الوصول إلى حاويات التخزين (Storage Buckets) عبر واجهة برمجية متوافقة مع S3، مما يتيح لك استخدام أدوات S3 الحالية — مثل AWS CLI وboto3 وs5cmd ومعظم حزم SDK الخاصة بـ S3 الأخرى — مع حاوياتك دون الحاجة إلى تغيير الكود. تمر الطلبات عبر خدمة بوابة (Gateway) موجودة على https://s3.hf.co.

تُعد واجهة برمجة التطبيقات S3 إحدى الطرق المتعددة للوصول إلى بيانات الدلو — وللاطلاع على الوصول الأصلي لـ Hugging Face (أداة سطر الأوامر hf، والمسارات hf://، وتثبيتات نظام الملفات) دون الحاجة إلى بيانات اعتماد S3 منفصلة، راجع أنماط الوصول.

يعمل واجهة برمجة التطبيقات S3 فقط مع Storage Buckets. ولا يكشف عن أنواع مستودعات Hugging Face الأخرى (النماذج، مجموعات البيانات، Spaces).

إنشاء بيانات اعتماد S3

يقوم البوابة بالمصادقة باستخدام مفاتيح وصول بنمط AWS مشتقة من رمز وصول المستخدم الخاص بـ Hugging Face.

انتقل إلى إعدادات رموز الوصول. أنشئ رمزًا باستخدام زر إنشاء رمز جديد إذا لم يكن لديك رمز بالفعل. تصبح صلاحيات الرمز هي صلاحيات بيانات اعتماد S3 — اختر قراءة للوصول للقراءة فقط إلى دلاءك، أو اختر كتابة للوصول للقراءة والكتابة.
ابحث عن الرمز في القائمة، ثم افتح قائمة الاختيارات المنسدلة الخاصة به واختر Generate S3 credentials.
انسخ معرّف مفتاح الوصول (المسبوق بـHFAK…) ومفتاح الوصول السري في مكان آمن — يُعرض المفتاح السري مرة واحدة فقط.

ترث بيانات اعتماد S3 أذونات رمز الوصول الأساسي. بالنسبة للرموز الدقيقة، حدّد نطاقها لتشمل فقط فضاءات الأسماء والخزانات التي تنوي استخدامها.

بالنسبة إلى سير العمل الآلية التي تصل إلى دلاء (buckets) المنظمة، يمكنك أيضًا توليد بيانات اعتماد S3 من رمز حساب الخدمة بدلاً من رمز وصول المستخدم.

إعداد عميل

وجّه عميل S3 الخاص بك إلى نقطة النهاية البوابة (gateway endpoint) وقيّم بعض الخيارات المطلوبة. استخدم namespace الخاص بك على Hugging Face (اسم المستخدم أو اسم المؤسسة) في عنوان نقطة النهاية — راجع عناوين الدلاء (Addressing buckets) أدناه.

الإعداد	القيمة	لماذا
`endpoint_url`	`https://s3.hf.co/<namespace>`	بوابة الوصول، محدودة النطاق باسم المجال الخاص بك
`region`	`us-east-1`	مطلوب؛ البوابة حاليًا أحادية المنطقة
`s3.addressing_style`	`path`	تُخاطَب الدلاء (Buckets) كأجزاء من المسار (path segments) وليس كنطاقات فرعية (subdomains)
`request_checksum_calculation`	`when_required`	يمنع العملاء الجدد من إرسال قيم التلخيص النهائية
`response_checksum_validation`	`when_required`	يمنع العملاء الجدد من توقع وجود قيم تجزئة في الاستجابات

تتعلق إعدادا الفحصين (checksum) بالعملاء الحديثين: فأوامر AWS CLI الإصدار 2.23 وما بعده، والإصدارات الحديثة من boto3، ترسل قيم الفحص CRC32 النهائية (عبر إطار aws-chunked) افتراضيًا، بينما لا يقوم البوابة بتحليل هذه القيم. تُخبر هذه الإعدادات العميل بإرسال قيم الفحص فقط عندما تتطلب العملية ذلك بشكل صارم.

ما يلي اختياري لكنه موصى به بحيث تستخدم عمليات رفع الملفات الكبيرة أقل عدد ممكن من الأجزاء متعددة الأجزاء:

الإعداد	القيمة
`s3.multipart_threshold`	`2GB`
`s3.multipart_chunksize`	`2GB`

مثال: ملف تعريف AWS CLI

أضِف ملفًا تعريفًا إلى ~/.aws/config:

[profile hf]
region = us-east-1
endpoint_url = https://s3.hf.co/<namespace>
s3 =
    addressing_style = path
    multipart_threshold = 2GB
    multipart_chunksize = 2GB
request_checksum_calculation = when_required
response_checksum_validation = when_required

ملاحظة: استبدل <namespace> أعلاه باسم المستخدم أو المنظمة التي تُخزَّن فيها دلاءك.

أضِف بيانات الاعتماد المطابقة للملف الشخصي إلى ~/.aws/credentials:

[hf]
aws_access_key_id = HFAK...
aws_secret_access_key = ...

ثم استخدم أي أمر S3 مع الملف الشخصي:

aws --profile hf s3 ls
aws --profile hf s3 mb s3://my-bucket
aws --profile hf s3 cp ./model.safetensors s3://my-bucket/models/model.safetensors

معالجة الدلاء

يعتمد AWS S3 على مساحة مسطحة واحدة وأسماء دلاء فريدة عالميًا، وتتوقع مكتبات SDK أن يكون اسم الدلو نصًا بسيطًا لا يحتوي على /. أما دلاء Hugging Face فتُعرَّف على شكل namespace/bucket، حيث يمثل namespace اسم المستخدم الخاص بك أو اسم المؤسسة. يؤدي هذا المستوى الإضافي إلى عدم توافق مع عملاء S3 — فكثير منهم لا يقبل / في اسم الدلو، أو يقوم بتشفيره في عنوان URL بشكل غير صحيح. هناك طريقتان للالتفاف على هذه المشكلة:

1. وضع مساحة الاسم في عنوان URL الخاص بالنقطة النهائية (يُنصح به في معظم الحالات). يحدد هذا النطاق كل عملية ضمن تلك مساحة الاسم، لذا فإن اسم الدلو المُمرَّر إلى العميل هو ببساطة اسم الدلو في HF. يعمل هذا جيدًا لأدولك الخاصة أو الأدول ضمن منظمة واحدة، لكنه يفشل عبر مساحات الأسماء — على سبيل المثال، النسخ من جهة الخادم من دلو شخصي إلى دلو منظمة.

aws --endpoint-url https://s3.hf.co/my-org s3api get-object \
  --bucket my-bucket --key some/object.txt ./object.txt

2. تعامل مع مساحة الأسماء (namespace) على أنها الدلو (bucket) وأضف اسم دلو HF في بداية مفتاح الكائن. يعمل هذا مع عمليات مستوى الكائن (الرفع، التنزيل) لكنه يواجه مشاكل مع عمليات مستوى الدلو مثل إنشاء الدلاء أو حذفها.

aws --endpoint-url https://s3.hf.co s3api get-object \
  --bucket my-org --key my-bucket/some/object.txt ./object.txt

القيود والاختلافات عن AWS S3

بما أن حاويات التخزين لا تُجسّد كل مفهوم في S3، فإن بعض السلوكيات تختلف أو لا تُدعَم.

تنزيلات الكائنات

البوابة حاليًا في منطقة واحدة. لتحسين أداء التنزيل، يستجيب GetObject عادةً بإعادة توجيه HTTP 302 إلى أقرب حافة شبكة توزيع المحتوى (CDN) الخاصة بـ Hugging Face بدلاً من تقديم البيانات مباشرةً.

بعض واجهات برمجة التطبيقات (SDKs) لا تتبع إعادة التوجيه من نقطة نهاية S3، لذلك يكتشف البوابة العملاء الذين يحددون أنفسهم على أنهم aws-cli أو botocore (والذي يشمل boto3) أو aws-sdk-rust، ويحوّل البيانات عبر نفسه لهم. أما جميع العملاء الآخرين (rclone، s5cmd، curl، وواجهة برمجة تطبيقات AWS بلغة Go، إلخ) فيستلمون الاستجابة 302 ويتبعونها بشكل أصلي، مما يُبقي البوابة خارج مسار البيانات لتسريع عمليات التنزيل.

تسمية مفاتيح الكائن

تخضع مفاتيح كائنات الدلو (Bucket) لقيود أكثر صرامة من S3. يجب ألا يكون المفتاح كالتالي:

تبدأ أو تنتهي بـ/
تحتوي على شرطة مائلة متتالية (//)
تحتوي على تسلسلات ../
ابدأ بـ ./
تنتهي بـ ..
تحتوي على علامات مائلة عكسية (\) أو بايتات فارغة (\0)

ListObjects

ListObjectsV1 غير مدعوم — استخدم ListObjectsV2. لاحظ أن بعض العملاء (مثل rclone) قد يحتاجون إلى تكوين لاستخدام ListObjectsV2 حصريًا.
يُسمح فقط بـ / كفاصل.

اختلافات أخرى في واجهة برمجة التطبيقات

بيانات الوصف الخاصة بالكائن: لا يتم تخزين أو إرجاع بيانات الوصف الخاصة بالمستخدم (x-amz-meta-*). يتم دعم Content-Type.
الميزات غير المدعومة: لا يتم دعم قوائم التحكم في الوصول (ACLs)، وسياسات الدلاء (bucket policies)، ووسم الكائنات (object tagging)، وإصدار الكائنات (object versioning)، وقواعد دورة الحياة (lifecycle rules)، والتشفير من جانب الخادم (SSE)، وإشعارات الدلاء (bucket notifications). يتم دائمًا الإبلاغ عن الكائنات بفئة التخزين STANDARD. يتم قبول رؤوس الطلبات (request headers) والمعاملات (parameters) ذات الصلة ولكن يتم تجاهلها.
CopyObject: يعمل النسخ من جانب الخادم فقط ضمن مساحة أسماء واحدة. لا يُدعم النسخ بين مساحات الأسماء أو UploadPartCopy (نسخ جزء من كائن موجود إلى عملية رفع متعددة الأجزاء).
الطلبات الشرطية: تُحترم شروط If-Match / If-None-Match في PutObject وفي مصدر النسخ لـ CopyObject، لكنها لا تُحترم في GetObject.
انتهاء مهلة رفع الملفات متعددة الأجزاء: تُنتهي تلقائيًا وتُزال عمليات رفع الملفات متعددة الأجزاء الجارية التي لا تُكتمل أو تُلغى أبدًا بعد 7 أيام.

أمثلة

وصفات عملية لمهام شائعة. يعتمد كل منها على إعدادات العميل المذكورة أعلاه.

القراءة والكتابة باستخدام boto3

يعمل boto3 مع البوابة باستخدام إعدادات العميل المذكورة أعلاه. استبدل <namespace> باسم المستخدم أو المؤسسة الخاصة بك:

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.hf.co/<namespace>",
    aws_access_key_id="HFAK...",
    aws_secret_access_key="...",
    config=Config(
        region_name="us-east-1",
        s3={"addressing_style": "path"},
        request_checksum_calculation="when_required",
        response_checksum_validation="when_required",
    ),
)

s3.upload_file("model.safetensors", "my-bucket", "models/model.safetensors")
s3.download_file("my-bucket", "models/model.safetensors", "model.safetensors")

استعلام عن دلو باستخدام DuckDB

في DuckDB 2.0 أو الإصدارات الأحدث، يقرأ امتداد httpfs مسارات hf://buckets/ مباشرةً، ومع امتداد hf يمكنه أيضاً الكتابة إلى Buckets. راجع الاستعلام باستخدام DuckDB.

بالنسبة إلى الإصدارات الأقدم من DuckDB، أو لكتابة نتائج الاستعلامات مرة أخرى إلى دلو باستخدام COPY ... TO دون الامتداد، استخدم بوابة S3 بدلاً من ذلك:

INSTALL httpfs;
LOAD httpfs;

CREATE SECRET hf (
    TYPE s3,
    KEY_ID 'HFAK...',
    SECRET '...',
    ENDPOINT 's3.hf.co/<namespace>',
    URL_STYLE 'path',
    REGION 'us-east-1'
);

SELECT * FROM read_parquet('s3://my-bucket/data.parquet');

URL_STYLE 'path' مطلوب. بدونه، يستخدم DuckDB عنوانًا بنمط المضيف الافتراضي (my-bucket.s3.hf.co)، وهو ما لا يقدّمه البوابة — وستظهر لك رسالة خطأ “Could not resolve hostname”.

استيراد البيانات باستخدام rclone

rclone هو وسيلة مريحة لنسخ البيانات بين مخزنين متوافقين مع S3، لذا فهو مناسب جدًا لنقل دلو AWS S3 الموجود (أو أي مصدر متوافق مع S3) إلى Storage Bucket.

الفكرة هي إعلان طرفين بعيدين — دلو المصدر وبوابة Hugging Face — والسماح لـ rclone ببث الكائنات بينهما. أضف كلا الطرفين إلى ~/.config/rclone/rclone.conf. يشير الطرف الأول إلى دلو S3 الموجود لديك؛ عدّله ليتطابق مع مصدرك (هنا، AWS S3 العادي):

[aws]
type = s3
provider = AWS
access_key_id = AKIA...
secret_access_key = ...
region = us-east-1

يشير الثاني إلى بوابة Hugging Face. وكأي عميل آخر، حدّد نطاق نقطة النهاية إلى namespace الخاص بك، واستخدم عنوان path، وأجبر استخدام ListObjectsV2 (وهي النسخة الوحيدة من الإحصاء التي تدعمها البوابة)، وحدّد أحجامًا كبيرة للأجزاء المتعددة حتى تستخدم عمليات الرفع أقل عدد ممكن من الأجزاء:

[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 = 2G
chunk_size = 2G

ملاحظة: استبدل <namespace> أعلاه باسم المستخدم أو المنظمة التي تُخزَّن فيها دلاءك، واستخدم بيانات اعتماد S3 المولَّدة من رمز الوصول الخاص بك. يجب أن يكون الدلو الوجهة موجودًا مسبقًا تحت ذلك الاسم.

الآن انسخ حاوية المصدر إلى حاوية التخزين الخاصة بك:

rclone copy aws:my-source-bucket hf:my-bucket --progress

ينقل rclone copy فقط الكائنات المفقودة أو التي تغيّرت في الوجهة، لذا فهو آمن لإعادة التشغيل لاستئناف استيرادٍ مُقاطَع أو لالتقاط كائنات جديدة. لجعل الوجهة مرآةً دقيقةً للمصدر — عبر حذف الكائنات في الوجهة التي لم تعد موجودةً في المصدر — استخدم rclone sync بدلاً من ذلك:

rclone sync aws:my-source-bucket hf:my-bucket --progress

بالنسبة إلى الاستيرادات الكبيرة، أضف --transfers و--checkers لزيادة مستوى التزامن (مثل --transfers 16 --checkers 16)، ثم نفّذ rclone check aws:my-source-bucket hf:my-bucket بعد ذلك للتأكد من وصول كل كائن بنجاح.

إدارة إصدارات البيانات باستخدام DVC

يُدير DVC إصدارات مجموعات البيانات والنماذج في git من خلال الاحتفاظ بملفات مؤشرات صغيرة في المستودع ودفع البيانات الفعلية إلى بُعد بعيد. يعمل الدلو كبعد بعيد لـ DVC عبر البوابة، بحيث تبقى كودك ومؤشرات .dvc في git بينما تقيم البيانات في دلوّك. ثبّت DVC مع دعم S3 (pip install 'dvc[s3]')، ثم أضف البعد البعيد باستخدام إعدادات العميل أعلاه:

dvc remote add -d hf-bucket s3://my-bucket/dvc-store
dvc remote modify hf-bucket endpointurl https://s3.hf.co/<namespace>
dvc remote modify hf-bucket region us-east-1

مرّر بيانات اعتماد S3 عبر البيئة، أو باستخدام dvc remote modify --local حتى لا تُخزَّن في git:

export AWS_ACCESS_KEY_ID=HFAK...
export AWS_SECRET_ACCESS_KEY=...

ثم تتبّع، ودفع، وسحب كما هو معتاد — dvc push يرفع إلى الدلو، وdvc pull على نسخة جديدة جديدة يحمّله مرة أخرى:

dvc add data/
git add data.dvc .gitignore .dvc/config && git commit -m "Track data with DVC"
dvc push

استخدم namespace الخاص بك في endpointurl واسم الدلو الصريح في عنوان s3://.

Update on GitHub

←أنماط الوصول تكاملات الدلاء→