# HF URI

*URI HF* — это строка, похожая на URI, которая идентифицирует расположение на Hugging Face Hub. В библиотеке и в CLI строки вида `hf://...` используются для указания:

- репозиторий модели, набора данных, пространства или ядра (необязательно закреплённый на определённой ревизии);
- файл или подпапка внутри такого репозитория;
- a [bucket](../guides/buckets) or a sub-folder inside a bucket.

*HF mount* объединяет HF URI с локальным путём монтирования и необязательным флагом `:ro` / `:rw`, используется в томах [Spaces](../guides/manage-spaces) и [Jobs](../guides/jobs).

На этой странице описан канонический синтаксис HF URI и HF mounts. Один и тот же парсер используется во всех частях библиотеки, поэтому URI, корректный в одном контексте (например, [HfFileSystem](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_file_system#huggingface_hub.HfFileSystem)), будет распознан идентично в другом.

[parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_uris#huggingface_hub.parse_hf_uri) также принимает **веб-URL** Hugging Face (например, `https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv`), поэтому вы можете скопировать и вставить ссылку с сайта. См. раздел [Веб-URL](#web-urls) ниже.

## Синтаксис URI HF

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

| Компонент       | Обязательный | Допустимые значения                                                      |
| --------------- | -------- | ------------------------------------------------------------------- |
| `hf://`         | да      | Литеральный префикс протокола.                                            |
| `<TYPE>/`       | нет       | `models/`, `datasets/`, `spaces/`, `kernels/`, `buckets/` (во множественном числе). |
| `<ID>`          | да      | `<namespace>/<name>`                                                |
| `@<REVISION>`   | нет       | Ветка, тег, SHA коммита или специальный ref (`refs/pr/N`, `refs/convert/...`). Только для репозиториев. |
| `/<PATH>`       | нет       | Путь внутри репозитория или хранилища.                                     |

## Синтаксис монтирования HF

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

Точка монтирования — это HF URI, за которым следует `:<MOUNT_PATH>` и необязательный флаг `:ro` / `:rw`.

| Компонент       | Обязательный | Допустимые значения                                                      |
| --------------- | -------- | ------------------------------------------------------------------- |
| `<MOUNT_PATH>`  | да      | Абсолютный путь монтирования (должен начинаться с `/`).                          |
| `:ro` / `:rw`   | нет       | Флаг только для чтения / чтения-записи.                                        |

## Что такое HF URI

Ниже приведены **все допустимые URI 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 не поддерживают маркер ревизии.                               |
| `hf://org/m@`, `hf://datasets/foo/bar@/x`         | Пустая ревизия после `@`.                                               |
| `hf://a/b/c@v1`                                   | Идентификатор репозитория должен иметь вид `namespace/name`, дополнительные сегменты являются путями.           |
| `hf://org/m:/`                                    | Путь монтирования должен быть непустым абсолютным путём.                           |

## Веб-URL

Для удобства [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_uris#huggingface_hub.parse_hf_uri) также принимает веб-URL Hugging Face, которые можно скопировать из браузера. Они приводятся к канонической форме `hf://`, поэтому URL можно вставить прямо в CLI или библиотеку, и всё заработает:

```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')
```

URL с `huggingface.co` (а также с его сокращённого домена `hf.co`, staging-хоста и хоста, заданного в `HF_ENDPOINT`) распознаются независимо от наличия схемы `https://`. Строки запроса (`?download=true`) и фрагменты (`#L10`) игнорируются.

Чтобы разобрать URL из другого развёртывания Hub (например, self-hosted или проксированного Hub), передайте его базовый URL в качестве `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>`                |
| Файл в репозитории (маршрут blame)                               | `/<ns>/<name>/blame/<rev>/<path>`              |
| Bucket                                                         | `/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                                |
| -------------------------------------------------------------------------------- | --------------------------------------- |
| URL с одним сегментом: страница user/org, страница списка или канонический репозиторий — неоднозначно. | `/<username>`                           |
| Страница списка, без `<ns>/<name>`.                                                  | `/datasets`                             |
| Канонические репозитории (без пространства имён) не поддерживаются.                         | `/gpt2`                                 |
| Не является расположением файла/папки (то же самое для `commits`, `discussions`, `settings`, …).   | `/<ns>/<name>/commit/<rev>`             |
| Коллекции — это не репозитории.                                                | `/collections/<ns>/<slug>`              |
| Host не является распознаваемым хостом Hugging Face.                                      | `https://example.com/<ns>/<name>`       |

## Отображение веб-URL

[HfUri.to_url()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_uris#huggingface_hub.HfUri.to_url) — это обратная операция к разбору URL: она формирует браузерный веб-URL для 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>`). Специальные символы в пути (пробелы, `#`, ...) кодируются в формате percent-encoding. Чтобы указать пользовательский хост, передайте `endpoint=...`.

## Разбор в Python

### Разбор URI

[parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_uris#huggingface_hub.parse_hf_uri) — это централизованный парсер URI. Это чистый строковый парсер (без сетевых вызовов), возвращающий неизменяемый dataclass [HfUri](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_uris#huggingface_hub.HfUri).

```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/ru/package_reference/hf_uris#huggingface_hub.HfUri) можно преобразовать обратно через [HfUri.to_uri()](/docs/huggingface_hub/v2.4.0/ru/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` при необходимости позволяют различать URI репозиториев и URI бакетов.

### Разбор монтирований

`parse_hf_mount` разбирает спецификацию монтирования (HF URI с локальным путём монтирования и необязательным флагом `:ro`/`:rw`) и возвращает неизменяемый dataclass `HfMount`. Внутри использует [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ru/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') для URI репозиториев или идентификатор бакета ('namespace/name') для URI бакетов.

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 в виде **веб-URL** Hugging Face (того типа, который открывается в браузере).

Это обратная операция к разбору URL с помощью [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_uris#huggingface_hub.parse_hf_uri). Возвращаемый URL указывает на:

- страница репозитория / бакета, когда не задан ни путь, ни ревизия;
- просмотрщик папок ('/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://', либо быть URL Hugging Face (например, 'https://huggingface.co/...').

endpoint (`str`, *необязательный*) : Пользовательский эндпоинт Hub (например, self-hosted или проксируемый Hub, такой как 'https://hub.my-company.com' или 'http://localhost:8080/hf'). Если указан, веб-URL на этом эндпоинте распознаются в дополнение к хостам Hugging Face по умолчанию. Не влияет на URI 'hf://'.

**Возвращает:** [HfUri](/docs/huggingface_hub/v2.4.0/ru/package_reference/hf_uris#huggingface_hub.HfUri)

разобранное URI.

**Исключения:** `HfUriError`

- `HfUriError` -- если URI имеет неверный формат (отсутствует префикс, недопустимый тип, отсутствует id, неподдерживаемый маршрут URL и т. д.).

Разбор URI Hugging Face Hub ('hf://...') или веб-URL Hugging Face.

HF URI — это строка, похожая на URI, которая идентифицирует расположение на Hugging Face Hub. Полная грамматика:

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

Для удобства Hugging Face **веб-URL** (те, что вы копируете с сайта) также принимаются и нормализуются до канонической формы 'hf://', например, 'https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv'. Принимаются только однозначные URL (страницы репозиториев / бакетов и маршруты просмотра файлов/папок); любой другой маршрут отклоняется.

Полная спецификация приведена в файле 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/ru/package_reference/hf_uris#huggingface_hub.HfUri)) : разобранный HF URI, идентифицирующий ресурс 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]').

Спецификация монтирования представляет собой HF URI, за которым следует локальный путь монтирования и необязательный флаг только для чтения/чтение-записи.

Полный синтаксис:

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