HF URI

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

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

HF mount объединяет HF URI с локальным путём монтирования и необязательным флагом :ro / :rw, используется в томах Spaces и Jobs.

На этой странице описан канонический синтаксис HF URI и HF mounts. Один и тот же парсер используется во всех частях библиотеки, поэтому URI, корректный в одном контексте (например, HfFileSystem), будет распознан идентично в другом.

parse_hf_uri() также принимает веб-URL Hugging Face (например, https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv), поэтому вы можете скопировать и вставить ссылку с сайта. См. раздел Веб-URL ниже.

Синтаксис URI HF

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

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

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

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

Что такое HF URI

Ниже приведены все допустимые URI HF:

# 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 (спецификации томов):

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

Парсер намеренно строг. Следующие варианты отклоняются:

Веб-URL

Для удобства parse_hf_uri() также принимает веб-URL Hugging Face, которые можно скопировать из браузера. Они приводятся к канонической форме hf://, поэтому URL можно вставить прямо в CLI или библиотеку, и «всё заработает»:

>>> 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) будет удалён перед разбором:

>>> 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); распознаваемый хост подразумевается.

Ревизия берётся из единственного сегмента сразу после blob/resolve/raw/tree/blame. Специальные ссылки (refs/pr/N, refs/convert/...) сопоставляются жадно, даже если они содержат /; любое другое имя ветки или тега, содержащее /, должно быть закодировано в URL (feature%2Ffoo).

URL, которые не были распознаны

Если URL неоднозначен или не указывает на конкретное расположение в Hub, он отклоняется (предположения не делаются):

Пути ниже снова показаны без хоста, за исключением последней строки, где сам хост является причиной отклонения.

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

HfUri.to_url() — это обратная операция к разбору URL: она формирует браузерный веб-URL для HF URI.

>>> 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() — это централизованный парсер URI. Это чистый строковый парсер (без сетевых вызовов), возвращающий неизменяемый dataclass HfUri.

>>> 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 можно преобразовать обратно через HfUri.to_uri(), который всегда выводит каноническую форму (с явным префиксом типа):

>>> 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().

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

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

Справочник

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

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

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

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

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

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