# 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](../guides/buckets) 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](../guides/manage-spaces) y [Jobs](../guides/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](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_file_system#huggingface_hub.HfFileSystem)) se analiza de manera idéntica en otro.

[parse_hf_uri()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_uris#huggingface_hub.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](#web-urls) a continuación.

## Sintaxis de URI de HF

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

```text
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**:

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

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

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

## Qué no es una **no** 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()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_uris#huggingface_hub.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":

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

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:

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

### 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()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_uris#huggingface_hub.HfUri.to_url) es la operación inversa de analizar una URL: genera la URL web navegable para un URI de HF.

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

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()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_uris#huggingface_hub.parse_hf_uri) es el parser de URI centralizado. Es un parser de cadenas puro (sin llamadas de red) y devuelve una dataclass [HfUri](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_uris#huggingface_hub.HfUri) inmutable.

```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/es/package_reference/hf_uris#huggingface_hub.HfUri) es reversible mediante [HfUri.to_uri()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_uris#huggingface_hub.HfUri.to_uri), que siempre emite la forma canónica (con un prefijo de tipo explícito):

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

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()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_uris#huggingface_hub.parse_hf_uri) internamente.

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

## Referencia[[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)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L79)

**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[[huggingface_hub.HfUri.to_uri]]

```python
to_uri()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L137)

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[[huggingface_hub.HfUri.to_url]]

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

[Fuente](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L155)

**Parámetros:**

endpoint (`str`, *opcional*) : Punto final 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()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_uris#huggingface_hub.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/') cuando solo se establece una revisión;
- el visor de archivos ('/blob//') para los archivos del repositorio (la revisión predeterminada es 'main');
- la ruta del árbol ('/tree/') para los archivos de cubo (los cubos no están versionados).

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

**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 punto de acceso personalizado de Hub (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 punto de acceso se reconocen además de los hosts predeterminados de Hugging Face. No tiene efecto en las URI 'hf://'.

**Devuelve:** [HfUri](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_uris#huggingface_hub.HfUri)

la URI analizada.

**Excepciones:** `HfUriError`

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

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

[Fuente](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L207)

**Parámetros:**

source ([HfUri](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_uris#huggingface_hub.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[[huggingface_hub.utils.HfMount.to_uri]]

```python
to_uri()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L238)

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

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

[Fuente](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L443)

**Parámetros:**

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

**Devuelve:** `HfMount`

el montaje analizado.

**Excepciones:** `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://...:[: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:
```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)
```