أنماط الوصول

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

اختيار طريقة الوصول

بالنسبة للأدوات التي تستخدم الدلاء (buckets) كخلفية (SkyPilot، Inspect، …)، راجع التكاملات. للحفاظ على مزامنة العميل مع الدلو دون الاستعلام الدوري عنه، راجع تتبع التغييرات.

التركيب كنظام ملفات محلي

يتيح لك hf-mount تركيب الدلاء (والمستودعات) كنظم ملفات محلية عبر NFS (موصى به) أو FUSE. يتم جلب الملفات بشكل كسول — حيث تصل إلى الشبكة فقط البايتات التي تقرأها شيفرتك.

قم بالتثبيت باستخدام Homebrew:

brew install hf-mount

تثبيت حاوية:

hf-mount start bucket username/my-bucket /mnt/data

بمجرد التركيب، تعمل أي أداة تقرأ الملفات أو تكتبها مع دلوّك — pandas وDuckDB وvLLM وسكربتات التدريب وأوامر shell وغيرها.

تُركَّب الدلاء (Buckets) للقراءة والكتابة، بينما تكون المستودعات للقراءة فقط. راجع مستودع hf-mount للحصول على التوثيق الكامل بما في ذلك خيارات الخلفية، والتخزين المؤقت، وأوضاع الكتابة.

وحدات التخزين المرفقة في المهام والمساحات

تُعدّ وحدات التخزين (Volume mounts) في Jobs وSpaces هي الفكرة ذاتها الخاصة بـhf-mount، حيث تُدار نيابةً عنك من قِبل المنصة — دون الحاجة إلى أي إعداد إضافي. تُركَّب الدلاء (Buckets) للقراءة والكتابة افتراضيًا.

hf jobs run -v hf://buckets/username/my-bucket:/data python:3.12 python script.py

يمكن أن تتخذ المهام أيضًا مجلدًا محليًا كمصدر للحجم (-v ./training-data:/data): حيث يُزامَن المجلد مع دلو jobs-artifacts الخاص بك ويُركَّب من هناك، مما يوفر مزامنة متزايدة وجلبًا للمخرجات مجانًا.

لمعرفة صياغة تركيب الحجم الكامل وواجهة برمجة تطبيقات بايثون، راجع توثيقات تكوين المهام ودليل تركيب الحجم في Spaces.

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

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

INSTALL httpfs;
LOAD httpfs;

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

تعمل أنماط Glob كما هي الحال مع مجموعات البيانات، على سبيل المثال 'hf://buckets/username/my-bucket/data/**/*.parquet'. لا تخضع الدلاء للإصدارات، لذا لا ينطبق صياغة @revision على مسارات الدلاء. يقرأ httpfs فقط؛ ولكتابة نتائج الاستعلام إلى دلو، حمّل الامتداد hf (انظر أدناه).

الدلاء الخاصة: أنشئ سراً لحساب Hugging Face أولاً. يتم اختيار الرمز من hf auth login أو متغير البيئة HF_TOKEN:

CREATE SECRET hf (TYPE huggingface, PROVIDER credential_chain);

يتطلب الكتابة إلى Hugging Face إضافة hf الإضافة:

SET allow_extension_repositories = 'allowed';
CREATE OR REPLACE EXTENSION REPOSITORY hf_repo WITH PREFIX 'https://hf.co/buckets/duckdb-extensions/builds/resolve';
INSTALL hf FROM hf_repo;
LOAD hf FROM hf_repo;

COPY tbl TO 'hf://buckets/username/my-bucket/out.parquet';

في DuckDB 1.x، لا يتعرّف httpfs على مسارات hf://buckets/. بدلاً من ذلك، سجّل HfFileSystem من Python، أو استخدم واجهة API المتوافقة مع S3 من سطر الأوامر والعملاء الآخرين.

أدوات بيانات بايثون

يوفر HfFileSystem وصولاً متوافقاً مع fsspec إلى الدلاء (buckets) باستخدام مسارات hf://buckets/. يمكن لأي مكتبة بايثون تدعم fsspec قراءة بيانات الدلاء وكتابتها مباشرة.

بايثون:

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")

لمزيد من المعلومات حول مسارات hf:// والعمليات المدعومة، راجع دليل HfFileSystem ودليل Python الخاص بالحاويات (Buckets).