URIs de HF

Un URI de HF es una cadena similar a un URI que identifica una ubicación en el Hugging Face Hub. En toda la biblioteca y la CLI, las cadenas hf://... se utilizan para señalar:

un repositorio de modelo, conjunto de datos, espacio o kernel (opcionalmente fijado en una revisión);
un archivo o subcarpeta dentro de dicho repositorio;
un bucket o una subcarpeta dentro de un bucket.

Un HF mount envuelve una URI de HF con una ruta de montaje local y una bandera opcional :ro / :rw, utilizada por los volúmenes de Spaces y Jobs.

Esta página documenta la sintaxis canónica de las URI de HF y las monturas de HF. El mismo analizador se utiliza en toda la biblioteca, por lo que una URI válida en un contexto (p. ej. HfFileSystem) se analiza de manera idéntica en otro.

parse_hf_uri() también acepta URLs web de Hugging Face (p. ej. https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv) para que puedas copiar y pegar un enlace desde el sitio web. Consulta URLs web a continuación.

Sintaxis de URI de HF

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

Componente	Obligatorio	Valores permitidos
`hf://`	sí	Prefijo de protocolo literal.
`<TYPE>/`	no	`models/`, `datasets/`, `spaces/`, `kernels/`, `buckets/` (en plural).
`<ID>`	sí	`<namespace>/<name>`
`@<REVISION>`	no	Rama, etiqueta, SHA de commit o ref especial (`refs/pr/N`, `refs/convert/...`). Solo repositorios.
`/<PATH>`	no	Ruta dentro del repositorio o cubo.

Sintaxis de montaje de HF

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

Un montaje es un URI de HF seguido de :<MOUNT_PATH> y una bandera opcional :ro / :rw.

Componente	Obligatorio	Valores permitidos
`<MOUNT_PATH>`	sí	Ruta de montaje absoluta (debe comenzar con `/`).
`:ro` / `:rw`	no	Bandera de solo lectura / lectura-escritura.

Qué es un URI de HF

Los siguientes son todos URI válidos de 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

Los siguientes son montajes de HF válidos (especificaciones de volumen):

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

Lo que no es un URI de HF

El analizador es estricto a propósito. Los siguientes elementos se rechazan:

URI no válido	Motivo
`my-org/my-model`, `./local/path`	Falta el prefijo `hf://` y no es una URL de Hugging Face reconocida.
`hf://dataset/org/m`, `hf://model/org/m`	Los tipos singulares están prohibidos; use el plural (`datasets/`, …).
`hf://datasets`, `hf://buckets/`	Un prefijo de tipo por sí solo no es una URI válida; se requiere un `<ID>`.
`hf://gpt2`, `hf://datasets/squad`	No se admiten repositorios canónicos (sin espacio de nombres).
`hf://buckets/single-segment`	Los buckets deben ser siempre `namespace/name`.
`hf://buckets/org/b@v1`	Los buckets no admiten un marcador de revisión.
`hf://org/m@`, `hf://datasets/foo/bar@/x`	Revisión vacía después de `@`.
`hf://a/b/c@v1`	Un id de repositorio debe ser `namespace/name`; los segmentos adicionales son rutas.
`hf://org/m:/`	La ruta de montaje debe ser una ruta absoluta no vacía.

URLs web

Para mayor comodidad, parse_hf_uri() también acepta URLs web de Hugging Face que copias y pegas desde tu navegador. Se normalizan al formato canónico hf://, por lo que puedes pegar una URL directamente en la CLI o en la biblioteca y “simplemente funciona”:

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

Las URL de huggingface.co (y su dominio corto hf.co, el host de staging y el host de un HF_ENDPOINT personalizado) se reconocen, con o sin el esquema https://. Las cadenas de consulta (?download=true) y los fragmentos (#L10) se ignoran.

Para analizar una URL de otra implementación de Hub (p. ej., un Hub autoalojado o proxy), pase su URL base como endpoint. Su host se reconoce además de los predeterminados, y se elimina un prefijo de ruta (p. ej., http://localhost:8080/hf) antes de analizarla:

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

Formatos de URL admitidos

La tabla siguiente enumera las rutas admitidas. Por brevedad, solo se muestra la ruta de URL (la parte después del host, p. ej. huggingface.co); el host reconocido se da por entendido.

Puntos en	Ruta de URL
Repositorio de modelos	`/<ns>/<name>`
Repositorio de conjuntos de datos (igual para `spaces/`, `kernels/`, `models/`)	`/datasets/<ns>/<name>`
Carpeta dentro de un repositorio, fijada en `<rev>`	`/<ns>/<name>/tree/<rev>[/<path>]`
Archivo dentro de un repositorio (ruta del visor de archivos)	`/<ns>/<name>/blob/<rev>/<path>`
Archivo dentro de un repositorio (ruta de descarga)	`/<ns>/<name>/resolve/<rev>/<path>`
Archivo dentro de un repositorio (ruta sin procesar)	`/<ns>/<name>/raw/<rev>/<path>`
Archivo dentro de un repositorio (ruta de blame)	`/<ns>/<name>/blame/<rev>/<path>`
Bucket	`/buckets/<ns>/<name>`
Archivo dentro de un bucket (los buckets no están versionados)	`/buckets/<ns>/<name>/resolve/<path>`
Carpeta dentro de un bucket	`/buckets/<ns>/<name>/tree/<path>`

La revisión se toma del único segmento inmediatamente después de blob/resolve/raw/tree/blame. Las referencias especiales (refs/pr/N, refs/convert/...) se coinciden de forma anticipada aunque contengan /; cualquier otro nombre de rama/etiqueta que contenga / debe codificarse en la URL (feature%2Ffoo).

URLs que no se analizan

Cuando una URL es ambigua o no apunta a una ubicación concreta del Hub, se rechaza (nunca se hace una suposición):

Las rutas siguientes se muestran nuevamente sin el host, excepto en la última fila, donde el propio host es la razón del rechazo.

Motivo	Ruta de URL
URL de un solo segmento: página de usuario/organización, página de listado o repositorio canónico — ambiguo.	`/<username>`
Página de listado, sin `<ns>/<name>`.	`/datasets`
No se admiten repositorios canónicos (sin espacio de nombres).	`/gpt2`
No es una ubicación de archivo/carpeta (lo mismo para `commits`, `discussions`, `settings`, …).	`/<ns>/<name>/commit/<rev>`
Las colecciones no son repositorios.	`/collections/<ns>/<slug>`
Host no es un host reconocido de Hugging Face.	`https://example.com/<ns>/<name>`

Renderizar una URL web

HfUri.to_url() es la operación inversa de analizar una URL: genera la URL web navegable para un URI de 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'

Indica la página de inicio del repositorio / bucket cuando no se establece ninguna ruta ni revisión, el visor de carpetas (/tree/<rev>) cuando solo se establece una revisión, el visor de archivos (/blob/<rev>/<path>, con la revisión predeterminada en main) para los archivos del repositorio y la ruta de árbol (/tree/<path>) para los archivos del bucket. Los caracteres especiales en la ruta (espacios, #, …) se codifican en porcentaje. Pasa endpoint=... para apuntar a un host personalizado.

Análisis en Python

Analizar URI

parse_hf_uri() es el parser de URI centralizado. Es un parser de cadenas puro (sin llamadas de red) y devuelve una dataclass HfUri inmutable.

>>> 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 es reversible mediante HfUri.to_uri(), que siempre emite la forma canónica (con un prefijo de tipo explícito):

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

Use los campos type y id directamente. Las propiedades booleanas is_repo y is_bucket distinguen entre URI de repositorio y URI de bucket cuando es necesario.

Analizar montajes

parse_hf_mount analiza una especificación de montaje (un URI de HF con una ruta local de montaje y una bandera opcional :ro/:rw) y devuelve una dataclass inmutable HfMount. Utiliza parse_hf_uri() internamente.

>>> 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 es reversible mediante 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'

Referencia

clase huggingface_hub.HfUri

< source >

( type: typing.Literal['model', 'dataset', 'space', 'kernel', 'bucket']id: strrevision: str | None = Nonepath_in_repo: str = ''_raw: str | None = None )

Parámetros

type (str) — Uno de ‘model’, ‘dataset’, ‘space’, ‘kernel’ o ‘bucket’.
id (str) — El identificador del repositorio (‘namespace/name’, p. ej. ‘my-org/my-model’) para las URI de repositorio, o el identificador del bucket (‘namespace/name’) para las URI de bucket.
revision (str, opcional) — La revisión especificada después de ’@’ en la URI, decodificada como URL. ‘None’ si no se especificó ninguna revisión, o para las URI de bucket (que nunca llevan una revisión). Las referencias especiales como ‘refs/pr/10’ y ‘refs/convert/parquet’ se conservan tal cual.
path_in_repo (str) — La ruta dentro del repositorio o bucket. Cadena vacía si la URI apunta a la raíz.

Representación analizada de un URI de Hugging Face Hub (‘hf://…’).

to_uri

< source >

( )

Representa la URI como una cadena canónica ‘hf://’.

El prefijo de tipo siempre se escribe de forma explícita (p. ej., ‘hf://models/my-org/my-model’).

to_url

< source >

( endpoint: str | None = None ) → str

Parámetros

endpoint (str, opcional) — Endpoint base a utilizar. El valor predeterminado es ‘constants.ENDPOINT’ (es decir, ’https://huggingface.co’).

Devuelve

str

la URL web.

Representa la URI como una URL web de Hugging Face (el tipo que se abre en un navegador).

Esta es la operación inversa de analizar una URL con parse_hf_uri(). La URL devuelta apunta a:

la página de inicio del repositorio / bucket cuando no se establece ninguna ruta ni revisión;
el visor de carpetas (‘/tree/<revision>’) cuando solo se establece una revisión;
el visor de archivos (‘/blob/<revision>/<path>’) para los archivos del repositorio (la revisión predeterminada es ‘main’);
la ruta del árbol (‘/tree/<path>’) para los archivos de cubo (los cubos no están versionados).

Ejemplo:

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

( uri: strendpoint: str | None = None ) → HfUri

Parámetros

uri (str) — La URI que se debe analizar. Debe comenzar con ‘hf://’ o ser una URL de Hugging Face (p. ej. ’https://huggingface.co/…’).
endpoint (str, opcional) — Un endpoint de Hub personalizado (p. ej., un Hub autoalojado o proxy como ’https://hub.my-company.com’ o ‘http://localhost:8080/hf’). Cuando se proporciona, las URLs web de ese endpoint se reconocen además de los hosts predeterminados de Hugging Face. No tiene efecto en las URI ‘hf://’.

Devuelve

HfUri

la URI analizada.

Lanza

HfUriError

HfUriError — Si la URI está mal formada (prefijo ausente, tipo no válido, id ausente, ruta de URL no admitida, etc.).

Analiza un URI de Hugging Face Hub (‘hf://…’) o una URL web de Hugging Face.

Una URI de HF es una cadena similar a una URI que identifica una ubicación en el Hugging Face Hub. La gramática completa es:

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

Por comodidad, las URLs web de Hugging Face (las que se copian y pegan desde el sitio web) también se aceptan y se normalizan al formato canónico ‘hf://’, por ejemplo, ‘https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv’. Solo se aceptan URLs no ambiguas (páginas de repositorio / bucket y rutas del visor de archivos/carpetas); cualquier otra ruta se rechaza.

Consulte ‘docs/source/en/package_reference/hf_uris.md’ para la especificación completa.

Ejemplos:

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

clase huggingface_hub.utils.HfMount

< source >

( source: HfUrimount_path: strread_only: bool | None = None_raw: str | None = None )

Parámetros

source (HfUri) — La URI de HF analizada que identifica el recurso del Hub que se debe montar.
mount_path (str) — La ruta de montaje local (siempre comienza con ’/’).
read_only (bool, opcional) — True si el montaje termina en ‘:ro’, False si termina en ‘:rw’, ‘None’ si no se proporcionó ninguna bandera.

Un URI de HF emparejado con una ruta de montaje local y una bandera opcional de solo lectura.

Utilizado por Spaces y Jobs para describir las monturas de volúmenes. La sintaxis completa es:

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

to_uri

< source >

( )

Representa el montaje como una cadena canónica ‘hf://’.

Ejemplo: ‘hf://models/my-org/my-model:/data:ro’

huggingface_hub.utils.parse_hf_mount

< source >

( mount_str: str ) → HfMount

Parámetros

mount_str (str) — La cadena de montaje a analizar. Debe comenzar con ‘hf://’ y contener un segmento ’:’.

Devuelve

HfMount

el montaje analizado.

Lanza

HfUriError

HfUriError — Si la cadena de montaje está mal formada (falta la ruta de montaje, URI no válida, etc.).

Analizar una especificación de montaje de HF (‘hf://…:<MOUNT_PATH>[:ro|:rw]’).

Una especificación de montaje es un URI de HF seguido de una ruta local de montaje y una bandera opcional de solo lectura/lectura-escritura.

La gramática completa es:

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

Consulte ‘docs/source/en/package_reference/hf_uris.md’ para la especificación completa.

Ejemplos:

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

Update on GitHub

Hub Python Library

URIs de HF

Sintaxis de URI de HF

Sintaxis de montaje de HF

Qué es un URI de HF

Lo que no es un URI de HF

URLs web

Formatos de URL admitidos

URLs que no se analizan

Renderizar una URL web

Análisis en Python

Analizar URI

Analizar montajes

Referencia

clase huggingface_hub.HfUri

to_uri

to_url

huggingface_hub.parse_hf_uri

clase huggingface_hub.utils.HfMount

to_uri

huggingface_hub.utils.parse_hf_mount