# HF URIs

يُعدّ *معرّف URI الخاص بـ HF* سلسلةً تشبه URI تحدد موقعًا على Hugging Face Hub. في جميع أنحاء المكتبة وأداة سطر الأوامر، تُستخدم سلاسل `hf://...` للإشارة إلى:

- مستودع نموذج أو مجموعة بيانات أو مساحة أو نواة (مع إمكانية التثبيت عند إصدار محدد بشكل اختياري)؛
- ملف أو مجلد فرعي داخل مستودع من هذا النوع؛
- a [bucket](../guides/buckets) or a sub-folder inside a bucket.

يُغلّف *HF mount* عنوان URI الخاص بـ HF مع مسار تثبيت محلي وعلامة اختيارية `:ro` / `:rw`، وتُستخدم هذه العلامة في أحجام [Spaces](../guides/manage-spaces) و[Jobs](../guides/jobs).

توثّق هذه الصفحة الصياغة القياسية لمعرّفات HF URI والجبال HF. يُستخدم نفس المُحلِّل في جميع أنحاء المكتبة، لذا فإن أي URI صالح في سياق واحد (مثل [HfFileSystem](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_file_system#huggingface_hub.HfFileSystem)) يُحلَّل بنفس الطريقة في سياق آخر.

يقبل [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_uris#huggingface_hub.parse_hf_uri) أيضًا **روابط ويب** من Hugging Face (مثل `https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv`) بحيث يمكنك نسخ رابط من الموقع ولصقه. راجع [روابط الويب](#web-urls) أدناه.

## صياغة URI الخاصة بـ HF

```text
hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]
```

| مكوّن       | مطلوب | القيم المسموح بها                                                      |
| --------------- | -------- | ------------------------------------------------------------------- |
| `hf://`         | نعم      | بادئة البروتوكول الحرفية.                                            |
| `<TYPE>/`       | لا       | `models/`، `datasets/`، `spaces/`، `kernels/`، `buckets/` (جمع). |
| `<ID>`          | نعم      | `<namespace>/<name>`                                                |
| `@<REVISION>`   | لا       | فرع، وسم، SHA للالتزام، أو مرجع خاص (`refs/pr/N`، `refs/convert/...`). المستودعات فقط. |
| `/<PATH>`       | لا       | المسار داخل المستودع أو الدلو.                                     |

## HF mount syntax

```text
hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]
```

المُثبّت هو URI خاص بـ HF يتبعه `:<MOUNT_PATH>` وعلامة اختيارية `:ro` / `:rw`.

| مكوّن       | مطلوب | القيم المسموح بها                                                      |
| --------------- | -------- | ------------------------------------------------------------------- |
| `<MOUNT_PATH>`  | نعم      | مسار التركيب المطلق (يجب أن يبدأ بـ `/`).                          |
| `:ro` / `:rw`   | لا       | علامة القراءة فقط / القراءة والكتابة.                                        |

## ما هو URI الخاص بـ HF

ما يلي هي **جميع URIs الصالحة لـ HF**:

```text
# Models (type prefix is optional, but the id is always 'namespace/name')
hf://my-org/my-model                            # implicit type prefix
hf://models/my-org/my-model                     # explicit type prefix
hf://models/my-org/my-model/config.json         # file inside a model repo
hf://models/my-org/my-model@v1.0/config.json    # pinned to a revision

# Datasets, Spaces, Kernels (type prefix is required)
hf://datasets/my-org/my-dataset
hf://datasets/my-org/my-dataset@dev/train.csv
hf://spaces/my-user/my-space
hf://kernels/my-org/my-kernel

# Special revisions (preserved as-is)
hf://datasets/my-org/my-dataset@refs/pr/10/data.csv
hf://datasets/my-org/my-dataset@refs/convert/parquet/data.parquet

# Buckets (always 'namespace/name', no revision)
hf://buckets/my-org/my-bucket
hf://buckets/my-org/my-bucket/sub/folder
```

ما يلي هي **وحدات HF الصالحة** (مواصفات الأحجام):

```text
hf://my-org/my-model:/data
hf://datasets/my-org/my-dataset:/mnt:ro
hf://datasets/my-org/my-dataset/train:/mnt:rw    # mount a sub-folder
hf://buckets/my-org/my-bucket:/storage:rw
```

## ما ليس **URI** خاصًا بـ HF

المحلل صارم عمداً. ما يلي **مرفوض**:

| URI غير صالح                                       | السبب                                                                  |
| ------------------------------------------------- | ----------------------------------------------------------------------- |
| `my-org/my-model`, `./local/path`                 | يفتقر إلى بادئة `hf://` وليس عنوان URL معترفًا به من Hugging Face.           |
| `hf://dataset/org/m`, `hf://model/org/m`          | يُمنع استخدام صيغة المفرد، استخدم صيغة الجمع (`datasets/`، ...).   |
| `hf://datasets`, `hf://buckets/`                  | بحد ذاته، بادئة النوع ليست عنوان URI صالحًا، بل يتطلب الأمر `<ID>`.          |
| `hf://gpt2`, `hf://datasets/squad`                | لا يتم دعم المستودعات الأساسية (بدون مساحة أسماء).                |
| `hf://buckets/single-segment`                     | يجب أن تكون الأوعية دائمًا بصيغة `namespace/name`.                                |
| `hf://buckets/org/b@v1`                           | لا تدعم الدلاء (Buckets) علامة المراجعة (revision marker).                               |
| `hf://org/m@`, `hf://datasets/foo/bar@/x`         | تعديل فارغ بعد `@`.                                               |
| `hf://a/b/c@v1`                                   | يجب أن يكون معرّف المستودع `namespace/name`، والأجزاء الإضافية هي مسارات.           |
| `hf://org/m:/`                                    | يجب أن يكون مسار التركيب مسارًا مطلقًا غير فارغ.                           |

## عناوين ويب

للسهولة، يقبل [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_uris#huggingface_hub.parse_hf_uri) أيضاً عناوين ويب الخاصة بـ Hugging Face التي تنسخها وتلصقها من متصفحك. يتم تطبيعها إلى الصيغة القياسية `hf://`، لذا يمكنك لصق عنوان URL مباشرة في سطر الأوامر أو المكتبة وسيعمل الأمر كما هو متوقع:

```python
>>> from huggingface_hub import parse_hf_uri
>>> parse_hf_uri("https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv")
HfUri(type='dataset', id='my-org/my-dataset', revision='main', path_in_repo='train.csv')
```

تُعرَّف العناوين من `huggingface.co` (ومجاله المختصر `hf.co`، ومضيف المرحلة التجريبية، ومضيف `HF_ENDPOINT` المخصص) سواءً مع بروتوكول `https://` أو بدونه. وتُتجاهل سلاسل الاستعلام (`?download=true`) والمقتطفات (`#L10`).

لتحليل عنوان URL من نشر آخر لمنصة Hub (مثل النشر الذاتي أو عبر وكيل)، مرر عنوانه الأساسي كـ`endpoint`. يتم بعد ذلك التعرف على مضيفه بالإضافة إلى المضيفين الافتراضيين، ويُستبعد بادئة المسار (مثل `http://localhost:8080/hf`) قبل التحليل:

```python
>>> parse_hf_uri("https://hub.my-company.com/datasets/my-org/my-dataset", endpoint="https://hub.my-company.com")
HfUri(type='dataset', id='my-org/my-dataset', revision=None, path_in_repo='')
```

### صيغ عناوين URL المدعومة

تُدرج الجدول أدناه المسارات المدعومة. ولإيجاز الأمر، يُعرض **مسار URL** فقط (الجزء الذي يلي المضيف، مثل `huggingface.co`)؛ ويُفهم المضيف المعترف به ضمناً.

| يشير إلى                                                      | مسار عنوان URL                                       |
| -------------------------------------------------------------- | ---------------------------------------------- |
| مستودع النموذج                                               | `/<ns>/<name>`                                 |
| مستودع مجموعة البيانات (نفس الأمر لـ `spaces/`، `kernels/`، `models/`) | `/datasets/<ns>/<name>`                        |
| مجلد داخل مستودع، مثبّت عند `<rev>`                        | `/<ns>/<name>/tree/<rev>[/<path>]`             |
| ملف داخل مستودع (مسار عارض الملفات)                         | `/<ns>/<name>/blob/<rev>/<path>`               |
| ملف داخل مستودع (مسار التنزيل)                            | `/<ns>/<name>/resolve/<rev>/<path>`            |
| ملف داخل مستودع (مسار خام)                                 | `/<ns>/<name>/raw/<rev>/<path>`                |
| ملف داخل مستودع (مسار إلقاء اللوم)                               | `/<ns>/<name>/blame/<rev>/<path>`              |
| دلو                                                         | `/buckets/<ns>/<name>`                         |
| ملف داخل دلو (الدلاء غير مُنظَّمة بالإصدارات)               | `/buckets/<ns>/<name>/resolve/<path>`          |
| مجلد داخل دلو                                         | `/buckets/<ns>/<name>/tree/<path>`             |

يُستخلص التعديل من الجزء الفردي الذي يلي مباشرةً `blob`/`resolve`/`raw`/`tree`/`blame`. تُطابَق المراجع الخاصة (`refs/pr/N`، `refs/convert/...`) بحماس حتى وإن احتوت على `/`؛ أما أي اسم فرع/وسم آخر يحتوي على `/` فيجب ترميزه في عنوان URL (`feature%2Ffoo`).

### عناوين URL التي **لم يتم** تحليلها

عندما يكون عنوان URL غامضاً أو لا يشير إلى موقع محدد على Hub، يتم **رفضه** (لا يتم التخمين أبداً):

تُعرض المسارات أدناه مرة أخرى دون تضمين المضيف، باستثناء الصف الأخير حيث يكون المضيف نفسه هو سبب الرفض.

| السبب                                                                           | مسار عنوان URL                                |
| -------------------------------------------------------------------------------- | --------------------------------------- |
| رابط أحادي المقطع: صفحة مستخدم/منظمة، صفحة قائمة، أو مستودع قياسي — غير محدد. | `/<username>`                           |
| صفحة القائمة، بدون `<ns>/<name>`.                                                  | `/datasets`                             |
| لا يتم دعم المستودعات الأساسية (بدون مساحة أسماء).                         | `/gpt2`                                 |
| ليس موقع ملف/مجلد (نفس الشيء ينطبق على `commits`، `discussions`، `settings`، …).   | `/<ns>/<name>/commit/<rev>`             |
| المجموعات ليست مستودعات.                                                | `/collections/<ns>/<slug>`              |
| المضيف ليس مضيفًا معترفًا به من قبل Hugging Face.                                      | `https://example.com/<ns>/<name>`       |

## عرض عنوان ويب

[HfUri.to_url()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_uris#huggingface_hub.HfUri.to_url) is the inverse of parsing a URL: it renders the browsable web URL for a HF URI.

```python
>>> uri = parse_hf_uri("hf://datasets/my-org/my-dataset@v1/train.csv")
>>> uri.to_url()
'https://huggingface.co/datasets/my-org/my-dataset/blob/v1/train.csv'
```

يشير إلى صفحة هبوط المستودع / الدلو عند عدم تعيين مسار أو مراجعة، وإلى عارض المجلد (`/tree/<rev>`) عند تعيين مراجعة فقط، وإلى عارض الملف (`/blob/<rev>/<path>`، حيث تكون المراجعة الافتراضية `main`) لملفات المستودع، وإلى مسار الشجرة (`/tree/<path>`) لملفات الدلو. يتم ترميز الأحرف الخاصة في المسار (المسافات، `#`، ...) باستخدام النسبة المئوية. مرّر `endpoint=...` لاستهداف مضيف مخصص.

## التحليل في Python

### تحليل معرّفات الموارد الموحّدة

[parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_uris#huggingface_hub.parse_hf_uri) هو محلل URI المركزي. إنه محلل نصوص خالص (لا يتضمن أي استدعاءات شبكة) ويعيد كائن [HfUri](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_uris#huggingface_hub.HfUri) من نوع dataclass غير قابل للتعديل.

```python
>>> from huggingface_hub import parse_hf_uri
>>> parse_hf_uri("hf://datasets/my-org/my-dataset@refs/pr/3/train.json")
HfUri(type='dataset', id='my-org/my-dataset', revision='refs/pr/3', path_in_repo='train.json')
```

[HfUri](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_uris#huggingface_hub.HfUri) قابل للتحويل ذهاباً وإياباً عبر [HfUri.to_uri()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_uris#huggingface_hub.HfUri.to_uri)، والذي يُخرج دائماً الشكل القياسي (مع بادئة نوع صريحة):

```python
>>> uri = parse_hf_uri("hf://my-org/my-model@v1/config.json")
>>> uri.to_uri()
'hf://models/my-org/my-model@v1/config.json'
```

استخدم حقلي `type` و`id` مباشرةً. وتُوضِّح الخصائص المنطقية `is_repo` و`is_bucket` الفرق بين معرِّفات المستودعات ومعرِّفات الدلاء عند الحاجة.

### تحليل نقاط التركيب

`parse_hf_mount` يحلل مواصفة نقطة التثبيت (URI خاص بـ HF مع مسار تثبيت محلي وعلامة اختيارية `:ro`/`:rw`) ويعيد كائن `HfMount` من نوع dataclass غير قابل للتعديل. يستخدم [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_uris#huggingface_hub.parse_hf_uri) في الخلفية.

```python
>>> from huggingface_hub.utils import parse_hf_mount
>>> parse_hf_mount("hf://buckets/my-org/my-bucket/sub/dir:/mnt:ro")
HfMount(source=HfUri(type='bucket', id='my-org/my-bucket', revision=None, path_in_repo='sub/dir'), mount_path='/mnt', read_only=True)
```

`HfMount` قابل للتحويل ذهاباً وإياباً عبر `HfMount.to_uri`:

```python
>>> mount = parse_hf_mount("hf://my-org/my-model:/data:ro")
>>> mount.to_uri()
'hf://models/my-org/my-model:/data:ro'
```

## مرجع[[huggingface_hub.HfUri]]

#### huggingface_hub.HfUri[[huggingface_hub.HfUri]]

```python
huggingface_hub.HfUri(type: typing.Literal['model', 'dataset', 'space', 'kernel', 'bucket'], id: str, revision: str | None = None, path_in_repo: str = '', _raw: str | None = None)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L79)

**المعاملات:**

type (`str`) : أحد القيم التالية: 'model' أو 'dataset' أو 'space' أو 'kernel' أو 'bucket'.

id (`str`) : معرّف المستودع ('namespace/name'، مثل 'my-org/my-model') لمعرّفات المستودعات، أو معرّف الدلو ('namespace/name') لمعرّفات الدلاء.

revision (`str`, *اختياري*) : المراجعة المحددة بعد '@' في عنوان URI، بعد فك ترميز URL. تكون 'None' إذا لم تُحدد مراجعة، أو في حالة عناوين URI الخاصة بالخزانات (التي لا تحمل مراجعة أبدًا). تُحفظ المراجع الخاصة مثل 'refs/pr/10' و 'refs/convert/parquet' كما هي.

path_in_repo (`str`) : المسار داخل المستودع أو الدلو. سلسلة فارغة إذا كان المعرّف الموحّد (URI) يشير إلى الجذر.

تمثيل مُحلَّل لـ URI الخاص بـ Hugging Face Hub ('hf://...').

#### to_uri[[huggingface_hub.HfUri.to_uri]]

```python
to_uri()
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L137)

اعرض عنوان URI كنص 'hf://' قياسي.

يُكتب بادئة النوع دائمًا بشكل صريح (مثل 'hf://models/my-org/my-model').

#### to_url[[huggingface_hub.HfUri.to_url]]

```python
to_url(endpoint: str | None = None)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L155)

**المعاملات:**

endpoint (`str`، *اختياري*) : نقطة النهاية الأساسية للاستخدام. القيمة الافتراضية هي 'constants.ENDPOINT' (أي 'https://huggingface.co').

**يعيد:** `str`

عنوان URL على الويب.

اعرض عنوان URI كـ **رابط ويب** خاص بـ Hugging Face (النوع الذي تفتحه في المتصفح).

هذا هو عكس تحليل عنوان URL باستخدام [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_uris#huggingface_hub.parse_hf_uri). يشير العنوان المُعاد إلى:

- صفحة هبوط المستودع / الدلو عند عدم تعيين مسار أو مراجعة؛
- عارض المجلد ('/tree/') عند تعيين نسخة محددة فقط؛
- عارض الملفات ('/blob//') لملفات المستودع (يُعدَّل المراجعة الافتراضية إلى 'main')؛
- مسار الشجرة ('/tree/') لملفات الدلاء (الدلاء غير مُنَزَّلة).

مثال:
```py
>>> from huggingface_hub import parse_hf_uri
>>> parse_hf_uri("hf://datasets/my-org/my-dataset@v1/train.csv").to_url()
'https://huggingface.co/datasets/my-org/my-dataset/blob/v1/train.csv'
```

#### huggingface_hub.parse_hf_uri[[huggingface_hub.parse_hf_uri]]

```python
huggingface_hub.parse_hf_uri(uri: str, endpoint: str | None = None)
```

**المعاملات:**

uri (`str`) : عنوان URI الذي سيتم تحليله. يجب أن يبدأ بـ 'hf://'، أو يكون رابطًا من Hugging Face (مثل 'https://huggingface.co/...').

endpoint (`str`, *اختياري*) : نقطة نهاية مخصصة للـ Hub (مثل Hub مُستضاف ذاتيًا أو عبر وكيل مثل 'https://hub.my-company.com' أو 'http://localhost:8080/hf'). عند تقديمها، يتم التعرف على عناوين الويب على تلك النقطة النهائية بالإضافة إلى مضيفي Hugging Face الافتراضيين. لا يؤثر ذلك على معرفات 'hf://'.

**يعيد:** [HfUri](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_uris#huggingface_hub.HfUri)

المعرف الموحّد محللًا.

**يرفع:** `HfUriError`

- `HfUriError` -- إذا كانت URI غير صحيحة (نقص البادئة، نوع غير صالح، نقص المعرّف، مسار URL غير مدعوم، إلخ).

تحليل عنوان URI لمركز Hugging Face ('hf://...') أو عنوان ويب لموقع Hugging Face.

URI الخاص بـ HF هو نص يشبه URI يحدد موقعًا على Hugging Face Hub. القواعد الكاملة هي:

```
hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]
```

للسهولة، تقبل روابط **ويب** الخاصة بـ Hugging Face (التي تُنسخ وتُلصق من الموقع) وتُطبع إلى الصيغة القياسية 'hf://'، على سبيل المثال 'https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv'. لا تُقبل إلا الروابط غير الغامضة (صفحات المستودعات/الدلاء ومسارات عارض الملفات/المجلدات)، وتُرفض أي مسارات أخرى.

راجع docs/source/en/package_reference/hf_uris.md للاطلاع على المواصفات الكاملة.

أمثلة:
```py
>>> from huggingface_hub.utils import parse_hf_uri
>>> parse_hf_uri("hf://my-org/my-model")
HfUri(type='model', id='my-org/my-model', revision=None, path_in_repo='')
>>> parse_hf_uri("hf://datasets/my-org/my-dataset@refs/pr/3/train.json")
HfUri(type='dataset', id='my-org/my-dataset', revision='refs/pr/3', path_in_repo='train.json')
>>> parse_hf_uri("https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv")
HfUri(type='dataset', id='my-org/my-dataset', revision='main', path_in_repo='train.csv')
```

#### huggingface_hub.utils.HfMount[[huggingface_hub.utils.HfMount]]

```python
huggingface_hub.utils.HfMount(source: HfUri, mount_path: str, read_only: bool | None = None, _raw: str | None = None)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L207)

**المعاملات:**

source ([HfUri](/docs/huggingface_hub/v2.4.0/ar/package_reference/hf_uris#huggingface_hub.HfUri)) : URI الخاص بـ HF المُحلَّل الذي يحدد مورد Hub المطلوب تركيبه.

mount_path (`str`) : مسار التركيب المحلي (يبدأ دائمًا بـ '/').

read_only (`bool`، *اختياري*) : True إذا كان التثبيت ينتهي بـ ':ro'، وFalse إذا كان ينتهي بـ ':rw'، و'None' إذا لم يُوفَّر أي علم.

URI خاص بـ HF مقترن بمسار تثبيت محلي وعلامة اختيارية للقراءة فقط.

يُستخدم في Spaces وJobs لوصف تركيبات التخزين. الصيغة الكاملة هي:

```
hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]
```

#### to_uri[[huggingface_hub.utils.HfMount.to_uri]]

```python
to_uri()
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L238)

اعرض نقطة التركيب كنص 'hf://' قياسي.

مثال: 'hf://models/my-org/my-model:/data:ro'

#### huggingface_hub.utils.parse_hf_mount[[huggingface_hub.utils.parse_hf_mount]]

```python
huggingface_hub.utils.parse_hf_mount(mount_str: str)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L443)

**المعاملات:**

mount_str (`str`) : سلسلة التركيب التي سيتم تحليلها. يجب أن تبدأ بـ 'hf://' وأن تحتوي على مقطع ':'.

**يعيد:** `HfMount`

التركيب المُحلَّل.

**يرفع:** `HfUriError`

- `HfUriError` -- إذا كانت سلسلة التركيب غير صحيحة (مثل غياب مسار التركيب، أو وجود URI غير صالح، وما إلى ذلك).

تحليل مواصفة تركيب HF ('hf://...:[:ro|:rw]').

تتكون مواصفة التركيب من URI خاص بـ HF يتبعه مسار تركيب محلي، مع علم اختياري للقراءة فقط أو للقراءة والكتابة.

القواعد الكاملة هي:

```
hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]
```

راجع docs/source/en/package_reference/hf_uris.md للاطلاع على المواصفات الكاملة.

أمثلة:
```py
>>> from huggingface_hub.utils import parse_hf_mount
>>> parse_hf_mount("hf://my-org/my-model:/data:ro")
HfMount(source=HfUri(type='model', id='my-org/my-model', revision=None, path_in_repo=''), mount_path='/data', read_only=True)
>>> parse_hf_mount("hf://buckets/my-org/my-bucket/sub/dir:/mnt:rw")
HfMount(source=HfUri(type='bucket', id='my-org/my-bucket', revision=None, path_in_repo='sub/dir'), mount_path='/mnt', read_only=False)
```