URIs HF

Un URI HF est une chaîne de caractères de type URI qui identifie un emplacement sur le Hugging Face Hub. Tout au long de la bibliothèque et de l'interface en ligne de commande, les chaînes hf://... sont utilisées pour pointer vers :

• un dépôt de modèle, de jeu de données, d’espace ou de noyau (éventuellement épinglé à une révision) ;
• un fichier ou un sous-dossier à l'intérieur d'un tel dépôt ;
• un bucket ou un sous-dossier à l'intérieur d'un bucket.

Un montage HF encapsule un URI HF avec un chemin de montage local et un drapeau facultatif :ro / :rw, utilisé par les volumes de Spaces et de Jobs.

Cette page documente la syntaxe canonique des URI HF et des montages HF. Le même analyseur est utilisé partout dans la bibliothèque, de sorte qu'une URI valide dans un contexte (par exemple HfFileSystem) est analysée de manière identique dans un autre.

parse_hf_uri() accepte également les URL web de Hugging Face (par exemple https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv) afin que vous puissiez copier-coller un lien depuis le site web. Consultez la section URL web ci-dessous.

Syntaxe des URI HF

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

Syntaxe de montage HF

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

Un montage est un URI HF suivi de :<MOUNT_PATH> et d'un drapeau facultatif :ro / :rw.

Qu'est-ce qu'un URI HF

Les éléments suivants sont tous des URI HF valides :

# 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

Les éléments suivants sont des montages HF valides (spécifications de volume) :

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

Ce qui n'est pas une URI HF

L'analyseur est strict par conception. Les éléments suivants sont rejetés :

URLs Web

Pour plus de commodité, parse_hf_uri() accepte également les URL web de Hugging Face que vous copiez-collez depuis votre navigateur. Elles sont normalisées sous la forme canonique hf://, ce qui vous permet de coller une URL directement dans le CLI ou la bibliothèque et « ça marche » :

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

Les URL issues de huggingface.co (ainsi que de son domaine court hf.co, de l’hôte de staging et de l’hôte d’un HF_ENDPOINT personnalisé) sont reconnues, avec ou sans le schéma https://. Les chaînes de requête (?download=true) et les fragments (#L10) sont ignorés.

Pour analyser une URL provenant d'un autre déploiement du Hub (par exemple un Hub auto-hébergé ou proxifié), passez son URL de base en tant que endpoint. Son hôte est alors reconnu en plus des hôtes par défaut, et un préfixe de chemin (par exemple http://localhost:8080/hf) est retiré avant l'analyse :

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

Formats d'URL pris en charge

Le tableau ci-dessous répertorie les routes prises en charge. Pour des raisons de concision, seul le chemin d’URL est affiché (la partie située après l’hôte, par exemple huggingface.co) ; l’hôte reconnu est sous-entendu.

La révision est extraite du segment unique situé juste après blob/resolve/raw/tree/blame. Les références spéciales (refs/pr/N, refs/convert/...) sont correspondantes de manière immédiate, même si elles contiennent / ; tout autre nom de branche ou de tag contenant / doit être encodé en URL (feature%2Ffoo).

URLs non analysées

Lorsqu’une URL est ambiguë ou ne pointe pas vers un emplacement concret du Hub, elle est rejetée (elle n’est jamais devinée) :

Les chemins ci-dessous sont à nouveau affichés sans l'hôte, à l'exception de la dernière ligne où l'hôte lui-même est la raison du rejet.

Affichage d'une URL web

HfUri.to_url() est l’inverse de l’analyse d’une URL : il génère l’URL web navigable correspondant à une URI HF.

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

Il pointe vers la page d’accueil du dépôt / du bucket lorsqu’aucun chemin ni révision n’est défini, vers le visualiseur de dossier (/tree/<rev>) lorsqu’une seule révision est définie, vers le visualiseur de fichier (/blob/<rev>/<path>, la révision étant par défaut main) pour les fichiers du dépôt, et vers la route d’arborescence (/tree/<path>) pour les fichiers du bucket. Les caractères spéciaux du chemin (espaces, #, …) sont encodés en pourcentage. Passez endpoint=... pour cibler un hôte personnalisé.

Analyse en Python

Analyse des URI

parse_hf_uri() est le parseur de URI centralisé. Il s’agit d’un parseur de chaînes pur (aucun appel réseau) qui renvoie une dataclass HfUri figée.

>>> 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 est réversible via HfUri.to_uri(), qui émet toujours la forme canonique (avec un préfixe de type explicite) :

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

Utilisez directement les champs type et id. Les propriétés booléennes is_repo et is_bucket permettent de distinguer les URI de dépôt des URI de bucket le cas échéant.

Analyse des montages

parse_hf_mount analyse une spécification de montage (un URI HF avec un chemin de montage local et un drapeau facultatif :ro/:rw) et renvoie une dataclass HfMount figée. Elle utilise parse_hf_uri() en interne.

>>> 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 est réversible via 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'

Référence

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