تكاملات الدلاء

يمكن لمعظم الأدوات بالفعل استخدام دلو، بأحد طريقتين:

• تقرأ مكتبات Python المبنية على fsspec (pandas وDask وPyArrow وغيرها) المسارات hf://buckets/ وتكتبها عبر واجهة نظام الملفات huggingface_hub.
• Tools that talk to S3 (boto3, the AWS CLI, rclone, DVC, and others) work against the S3-compatible API.

تغطي هذه الصفحة المكتبات التي تدعم الأوعية (buckets) بشكل مدمج، بالإضافة إلى أمثلة لمكتبات البيانات الشائعة. أما فيما يتعلق بالتثبيتات (mounts) وتثبيتات الأحجام (volume mounts)، فراجع أنماط الوصول.

pandas

import pandas as pd

df = pd.read_parquet("hf://buckets/username/my-bucket/data.parquet")
df.to_parquet("hf://buckets/username/my-bucket/output.parquet")

Dask

تقرأ Dask وتكتب بشكل كسول (lazy)، حيث تُعالَج كل وحدة (partition) في ملف مستقل، مما يتيح لك معالجة مجموعات بيانات أكبر من الذاكرة مباشرةً من حاوية (bucket):

import dask.dataframe as dd

df = dd.read_parquet("hf://buckets/username/my-bucket/data/")
df.to_parquet("hf://buckets/username/my-bucket/output/")

راجع Dask على Hub لمزيد من التفاصيل.

Daft

يدعم Daft مسارات hf://buckets/ بشكل أصلي، مع تفعيل قراءات مُسرَّعة بواسطة Xet افتراضيًا:

import daft
from daft.io import IOConfig, HuggingFaceConfig
from huggingface_hub import get_token

io_config = IOConfig(hf=HuggingFaceConfig(token=get_token()))
df = daft.read_parquet("hf://buckets/username/my-bucket/data.parquet", io_config=io_config)

PyArrow

import pyarrow.parquet as pq

table = pq.read_table("hf://buckets/username/my-bucket/data.parquet")

PySpark

مع تثبيت pyspark_huggingface :

df = (
    spark.read.format("huggingface")
    .option("data_files", '["data.parquet"]')
    .load("buckets/username/my-bucket")
)

راجع PySpark على Hub لمزيد من التفاصيل.

🤗 مجموعات البيانات

from datasets import load_dataset

ds = load_dataset("buckets/username/my-bucket", data_files=["data.parquet"])

datatrove

يقبل قارئات وكاتبات datatrove مسارات hf://buckets/. يرفع HuggingFaceBucketWriter المخرجات الكبيرة باستخدام Xet:

from datatrove.pipeline.readers import ParquetReader
from datatrove.pipeline.writers import HuggingFaceBucketWriter

reader = ParquetReader(data_folder="hf://buckets/username/my-bucket/raw/")
writer = HuggingFaceBucketWriter(bucket="username/my-bucket", prefix="filtered")

راجع README الخاص بـ datatrove لمزيد من التفاصيل.

LeRobot

يمكن لـ LeRobot بث مجموعة بيانات التدريب من دلو. يجب أن يحتوي الدلو على مجموعة البيانات الكاملة (meta/، وملفات Parquet وملفات الفيديو) في جذره:

lerobot-train \
  --dataset.repo_id=username/my-bucket \
  --dataset.repo_type=bucket \
  --dataset.streaming=true \
  --policy.type=act

Diffusers

يرفع diffusers-cli run مخرجاته إلى دلو باستخدام --push-to. يتم إنشاء الدلو إذا لم يكن موجودًا:

diffusers-cli run --model black-forest-labs/FLUX.1-dev --dtype bf16 \
  --pipeline-kwargs '{"prompt": "an astronaut riding a horse"}' \
  --push-to hf://buckets/username/my-bucket/outputs

راجع دليل سطر أوامر Diffusers لمزيد من التفاصيل.

Trackio

عندما يسجّل Trackio في مساحة، فإنه يخزّن بيانات التشغيل في دلو يُنشأ من معرّف المساحة. مرّر bucket_id إلى trackio.init() لاستخدام دلو تختاره.

Inspect AI

يمكن لـ Inspect AI كتابة سجلات التقييم مباشرةً إلى دلو — وجّه مجلد السجلات الخاص به إلى مسار hf://buckets/ (يتطلب huggingface_hub>=1.6.0). أنشئ الدلو ووثّق نفسك أولاً (لن يقوم Inspect بإنشائه نيابةً عنك):

hf auth login
hf buckets create username/my-bucket --private

export INSPECT_LOG_DIR=hf://buckets/username/my-bucket/eval-logs
inspect eval popularity.py --model openai/gpt-4
inspect view

راجع دليل سجلات تقييم Inspect للحصول على التفاصيل.

SkyPilot

يعمل SkyPilot على تشغيل مهام الذكاء الاصطناعي عبر أكثر من 20 سحابة، وKubernetes، والبنية التحتية المحلية، ويمكنه استخدام تخزين Hugging Face كخلفية — بحيث يمكن قراءة حاوية واحدة من كل سحابة دون الحاجة إلى نسخ لكل سحابة على حدة. اضبط store: hf على عنصر file_mounts لتركيب حاوية للقراءة والكتابة أو مستودع للقراءة فقط:

# qwen-sft.yaml — launch anywhere: sky launch qwen-sft.yaml --infra aws|gcp|...
resources:
  accelerators: H100:1

file_mounts:
  /base-model:
    source: hf://Qwen/Qwen2.5-3B           # model repo, read-only
    store: hf
    mode: MOUNT
  /data:
    source: hf://datasets/username/my-data@v1.0   # dataset repo, pinned to a tag, read-only
    store: hf
    mode: MOUNT
  /checkpoints:
    source: hf://buckets/username/qwen-sft   # bucket, read-write — checkpoints sync back
    store: hf
    mode: MOUNT

run: |
  python train.py --model /base-model --output_dir /checkpoints

المصادقة مرة واحدة - hf auth login (أو export HF_TOKEN=<your-token>) هو كل ما يحتاجه SkyPilot. يقوم بتحويل رمز Hugging Face المحلي الخاص بك إلى كل سحابة، بحيث تتم مصادقة تركيبات الدلو والمستودع تلقائيًا:

pip install "skypilot[huggingface]"
hf auth login                              # or: export HF_TOKEN=<your-token>
sky launch qwen-sft.yaml

إذا كان كود run الخاص بك يجلب مستودعات مقيدة، أضف --secret HF_TOKEN إلى أمر التشغيل لعرض الرمز أيضاً كمتغير بيئة.

يتصرف MOUNT وMOUNT_CACHED بشكل متطابق في حالة hf، ويستخدمان واجهة hf-mount من نوع FUSE، والتي تتطلب صورة أساسية تحتوي على glibc ≥ 2.34 و/dev/fuse. توفر سحابة الأجهزة الافتراضية العارية كلاهما. أما صورة Kubernetes الافتراضية في SkyPilot فتأتي بنسخة أقدم من glibc، لذا يجب تعيين image_id أحدث (مثل docker:mirror.gcr.io/ubuntu:22.04). راجع توثيق التخزين في SkyPilot للاطلاع على متطلبات البيئة الحالية.

اطّلع على منشور المدونة الخاص بتخزين SkyPilot + Hugging Face للاطلاع على معايير الأداء وشرح كامل.

عمليات نظام الملفات

للعمليات المباشرة على الملفات، يعرّف huggingface_hub كائن نظام ملفات مُهيّأ مسبقاً، hffs:

from huggingface_hub import hffs

with hffs.open("buckets/username/my-bucket/hello.txt", "w") as f:
    f.write("Hello world!")

hffs.cp("buckets/username/my-bucket/hello.txt", "buckets/username/my-bucket/hello2.txt")
hffs.rm("buckets/username/my-bucket/hello2.txt")
files = hffs.ls("buckets/username/my-bucket")
text_files = hffs.glob("buckets/username/my-bucket/*.txt")

DuckDB

تقرأ DuckDB 2.0 وما بعدها مسارات hf://buckets/ بشكل أصلي عبر امتداد httpfs (ومع امتداد hf للكتابة)، من سطر الأوامر وكل عميل:

SELECT * FROM 'hf://buckets/username/my-bucket/data/**/*.parquet' LIMIT 10;
COPY tbl TO 'hf://buckets/username/my-bucket/out.parquet';

راجع الاستعلام باستخدام DuckDB للحاويات الخاصة وإصدارات DuckDB الأقدم.

لغات أخرى

يوفر OpenDAL واجهة نظام ملفات مشابهة للغة Rust ولغة Java ولغة Go ولغة JavaScript وغيرها.

قريباً

تدعم روابط hf:// الأصلية المزيد من المكتبات — بما في ذلك WebDataset — قريبًا. وفي غضون ذلك، تعمل جميع هذه المكتبات حاليًا من خلال واجهة برمجة التطبيقات المتوافقة مع S3.