# أنماط الوصول

بالإضافة إلى [واجهة سطر الأوامر وواجهة برمجة التطبيقات بلغة بايثون](./storage-buckets#managing-files)، هناك عدة طرق للوصول إلى بيانات الدلو من أدواتك وسير عملك الحالية.

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

| الطريقة | الأفضل ل | تفاصيل |
|--------|----------|---------|
| **hf-mount** | التركيب كنظام ملفات محلي — يعمل أي أداة | [انظر أدناه](#mount-as-a-local-filesystem) |
| **تثبيتات المجلدات** | وظائف ومساحات HF (نفس الفكرة، مُدارة من أجلك) | [انظر أدناه](#volume-mounts-in-jobs-and-spaces) |
| **DuckDB** | استعلامات SQL على ملفات الدلاء، من سطر الأوامر أو أي عميل | [انظر أدناه](#query-with-duckdb) |
| مسارات **hf://** (fsspec) | أدوات بيانات بايثون (pandas ومكتبات أخرى تدعم fsspec) | [انظر أدناه](#python-data-tools) |
| **مزامنة سطر الأوامر** | نقل الدُفعات، النسخ الاحتياطي | [مزامنة المستندات](./storage-buckets#syncing-directories) |
| **واجهة S3 البرمجية** | أدوات S3 الحالية (AWS CLI، boto3، s5cmd) | [واجهة برمجة التطبيقات المتوافقة مع S3](./storage-buckets-s3) |

بالنسبة للأدوات التي تستخدم الدلاء (buckets) كخلفية (SkyPilot، Inspect، Trackio، …)، راجع [التكاملات](./storage-buckets-integrations). لمزامنة عميل مع دلو دون الحاجة إلى الاستعلام الدوري عنه، راجع [تتبع التغييرات](./storage-buckets#tracking-changes).

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

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

قم بالتثبيت باستخدام [Homebrew](https://brew.sh/):

```bash
brew install hf-mount
```

تثبيت حاوية:

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

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

> [!TIP]
> تُركَّب الدلاء (Buckets) للقراءة والكتابة، بينما تكون المستودعات للقراءة فقط. راجع [مستودع hf-mount](https://github.com/huggingface/hf-mount) للحصول على التوثيق الكامل بما في ذلك خيارات الخلفية، والتخزين المؤقت، وأوضاع الكتابة.

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

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

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

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

لمعرفة صياغة تركيب الحجم الكامل وواجهة برمجة تطبيقات بايثون، راجع [توثيقات تكوين المهام](./jobs-configuration#volumes) ودليل [تركيب الحجم في Spaces](/docs/huggingface_hub/guides/manage-spaces#mount-volumes-in-your-space).

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

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

```sql
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`:

```sql
CREATE SECRET hf (TYPE huggingface, PROVIDER credential_chain);
```

يتطلب الكتابة إلى Hugging Face إضافة `hf` [الإضافة](https://huggingface.co/duckdb-extensions):

```sql
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';
```

> [!NOTE]
> في DuckDB 1.x، لا يتعرّف `httpfs` على مسارات `hf://buckets/`. بدلاً من ذلك، سجّل [`HfFileSystem`](/docs/huggingface_hub/guides/hf_file_system) من Python، أو استخدم [واجهة API المتوافقة مع S3](./storage-buckets-s3#query-a-bucket-with-duckdb) من سطر الأوامر والعملاء الآخرين.

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

يوفر [`HfFileSystem`](/docs/huggingface_hub/guides/hf_file_system) وصولاً متوافقاً مع [fsspec](https://filesystem-spec.readthedocs.io) إلى الدلاء (buckets) باستخدام مسارات `hf://buckets/`. يمكن لأي مكتبة بايثون تدعم fsspec قراءة بيانات الدلاء وكتابتها مباشرة.

**بايثون:**

```python
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`](/docs/huggingface_hub/guides/hf_file_system) و[دليل Python الخاص بالحاويات (Buckets)](/docs/huggingface_hub/guides/buckets).