# URIs do HF

Uma *URI do HF* é uma string semelhante a uma URI que identifica uma localização no Hugging Face Hub. Ao longo da biblioteca e do CLI, as strings `hf://...` são usadas para apontar para:

- um repositório de modelo, conjunto de dados, espaço ou kernel (opcionalmente fixado em uma revisão);
- um arquivo ou subpasta dentro de um repositório como esse;
- um [bucket](../guides/buckets) ou uma subpasta dentro de um bucket.

Um *HF mount* encapsula um URI do HF com um caminho de montagem local e uma flag opcional `:ro` / `:rw`, usada pelos volumes de [Spaces](../guides/manage-spaces) e [Jobs](../guides/jobs).

Esta página documenta a sintaxe canônica dos URIs do HF e dos montagens do HF. O mesmo analisador é usado em toda a biblioteca, portanto, um URI válido em um contexto (por exemplo, [HfFileSystem](/docs/huggingface_hub/main/pt/package_reference/hf_file_system#huggingface_hub.HfFileSystem)) é analisado de forma idêntica em outro.

[parse_hf_uri()](/docs/huggingface_hub/main/pt/package_reference/hf_uris#huggingface_hub.parse_hf_uri) também aceita **URLs da web** do Hugging Face (por exemplo, `https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv`), para que você possa copiar e colar um link do site. Consulte [URLs da web](#web-urls) abaixo.

## Sintaxe de URI do HF

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

| Componente       | Obrigatório | Valores permitidos                                                      |
| --------------- | -------- | ------------------------------------------------------------------- |
| `hf://`         | sim      | Prefixo de protocolo literal.                                            |
| `<TYPE>/`       | não       | `models/`, `datasets/`, `spaces/`, `kernels/`, `buckets/` (no plural). |
| `<ID>`          | sim      | `<namespace>/<name>`                                                |
| `@<REVISION>`   | não       | Branch, tag, SHA do commit ou ref especial (`refs/pr/N`, `refs/convert/...`). Somente repositórios. |
| `/<PATH>`       | não       | Caminho dentro do repositório ou bucket.                                     |

## Sintaxe de montagem do HF

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

Um mount é um URI do HF seguido por `:<MOUNT_PATH>` e uma flag opcional `:ro` / `:rw`.

| Componente       | Obrigatório | Valores permitidos                                                      |
| --------------- | -------- | ------------------------------------------------------------------- |
| `<MOUNT_PATH>`  | sim      | Caminho de montagem absoluto (deve começar com `/`).                          |
| `:ro` / `:rw`   | não       | Flag somente leitura / leitura e gravação.                                        |

## O que é um URI do HF

Os seguintes são **todos URIs válidos do 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
```

Os seguintes são **montagens HF válidas** (especificações de volume):

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

## O que **não** é um URI do HF

O parser é estrito de propósito. Os seguintes itens são **rejeitados**:

| URI inválido                                       | Motivo                                                                  |
| ------------------------------------------------- | ----------------------------------------------------------------------- |
| `my-org/my-model`, `./local/path`                 | Prefixo `hf://` ausente e não é um URL do Hugging Face reconhecido.           |
| `hf://dataset/org/m`, `hf://model/org/m`          | Formas de tipo singular são proibidas, use o plural (`datasets/`, ...).   |
| `hf://datasets`, `hf://buckets/`                  | Um prefixo de tipo sozinho não é um URI válido; é necessário um `<ID>`.          |
| `hf://gpt2`, `hf://datasets/squad`                | Repositórios canônicos (sem namespace) não são suportados.                |
| `hf://buckets/single-segment`                     | Os buckets devem ser sempre `namespace/name`.                                |
| `hf://buckets/org/b@v1`                           | Buckets não suportam um marcador de revisão.                               |
| `hf://org/m@`, `hf://datasets/foo/bar@/x`         | Revisão vazia após `@`.                                               |
| `hf://a/b/c@v1`                                   | Um id de repositório deve ser `namespace/name`; segmentos extras são caminhos.           |
| `hf://org/m:/`                                    | O caminho de montagem deve ser um caminho absoluto não vazio.                           |

## URLs da Web

Para sua conveniência, [parse_hf_uri()](/docs/huggingface_hub/main/pt/package_reference/hf_uris#huggingface_hub.parse_hf_uri) também aceita URLs web do Hugging Face que você copia e cola do seu navegador. Elas são normalizadas para o formato canônico `hf://`, então você pode colar uma URL diretamente no CLI ou na biblioteca e "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')
```

URLs de `huggingface.co` (e seu domínio curto `hf.co`, o host de staging e o host de um `HF_ENDPOINT` personalizado) são reconhecidas, com ou sem o esquema `https://`. Strings de consulta (`?download=true`) e fragmentos (`#L10`) são ignorados.

Para analisar uma URL de outra implantação do Hub (por exemplo, um Hub auto-hospedado ou proxied), passe sua URL base como `endpoint`. Seu host é então reconhecido, além dos padrões, e um prefixo de caminho (por exemplo, `http://localhost:8080/hf`) é removido antes da análise:

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

A tabela abaixo lista as rotas suportadas. Por brevidade, apenas o **caminho da URL** é exibido (a parte após o host, por exemplo, `huggingface.co`); o host reconhecido é implícito.

| Pontos em                                                      | Caminho da URL                                       |
| -------------------------------------------------------------- | ---------------------------------------------- |
| Repositório de modelos                                               | `/<ns>/<name>`                                 |
| Repositório de datasets (o mesmo para `spaces/`, `kernels/`, `models/`) | `/datasets/<ns>/<name>`                        |
| Pasta dentro de um repositório, fixada em `<rev>`                        | `/<ns>/<name>/tree/<rev>[/<path>]`             |
| Arquivo dentro de um repositório (rota do visualizador de arquivos)                         | `/<ns>/<name>/blob/<rev>/<path>`               |
| Arquivo dentro de um repositório (rota de download)                            | `/<ns>/<name>/resolve/<rev>/<path>`            |
| Arquivo dentro de um repositório (rota bruta)                                 | `/<ns>/<name>/raw/<rev>/<path>`                |
| Arquivo dentro de um repositório (rota de blame)                               | `/<ns>/<name>/blame/<rev>/<path>`              |
| Bucket                                                         | `/buckets/<ns>/<name>`                         |
| Arquivo dentro de um bucket (buckets não são versionados)               | `/buckets/<ns>/<name>/resolve/<path>`          |
| Pasta dentro de um bucket                                         | `/buckets/<ns>/<name>/tree/<path>`             |

A revisão é obtida do único segmento imediatamente após `blob`/`resolve`/`raw`/`tree`/`blame`. Refs especiais (`refs/pr/N`, `refs/convert/...`) são correspondidas de forma imediata, mesmo que contenham `/`; qualquer outro nome de branch/tag que contenha `/` deve ser codificado em URL (`feature%2Ffoo`).

### URLs que **não** são analisadas

Quando uma URL é ambígua ou não aponta para uma localização concreta no Hub, ela é **rejeitada** (nunca é feita uma suposição):

Os caminhos abaixo são novamente exibidos sem o host, exceto na última linha, onde o próprio host é a razão para a rejeição.

| Motivo                                                                           | Caminho da URL                                |
| -------------------------------------------------------------------------------- | --------------------------------------- |
| URL de segmento único: página de usuário/organização, página de listagem ou repositório canônico — ambíguo. | `/<username>`                           |
| Página de listagem, sem `<ns>/<name>`.                                                  | `/datasets`                             |
| Repositórios canônicos (sem namespace) não são suportados.                         | `/gpt2`                                 |
| Não é um local de arquivo/pasta (o mesmo vale para `commits`, `discussions`, `settings`, …).   | `/<ns>/<name>/commit/<rev>`             |
| Coleções não são repositórios.                                                | `/collections/<ns>/<slug>`              |
| Host não é um host reconhecido do Hugging Face.                                      | `https://example.com/<ns>/<name>`       |

## Renderizando uma URL da web

[HfUri.to_url()](/docs/huggingface_hub/main/pt/package_reference/hf_uris#huggingface_hub.HfUri.to_url) é o inverso da análise de uma URL: ele renderiza a URL web navegável para um URI do 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'
```

Ele aponta para a página inicial do repositório / bucket quando nenhum caminho ou revisão é definido, para o visualizador de pastas (`/tree/<rev>`) quando apenas uma revisão é definida, para o visualizador de arquivos (`/blob/<rev>/<path>`, com a revisão padrão definida como `main`) para arquivos de repositório e para a rota de árvore (`/tree/<path>`) para arquivos de bucket. Caracteres especiais no caminho (espaços, `#`, ...) são codificados em percentual. Passe `endpoint=...` para direcionar a um host personalizado.

## Análise em Python

### Analisando URIs

[parse_hf_uri()](/docs/huggingface_hub/main/pt/package_reference/hf_uris#huggingface_hub.parse_hf_uri) é o parser de URI centralizado. É um parser de string puro (sem chamadas de rede) e retorna uma dataclass [HfUri](/docs/huggingface_hub/main/pt/package_reference/hf_uris#huggingface_hub.HfUri) imutável.

```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/main/pt/package_reference/hf_uris#huggingface_hub.HfUri) é conversível de ida e volta por meio de [HfUri.to_uri()](/docs/huggingface_hub/main/pt/package_reference/hf_uris#huggingface_hub.HfUri.to_uri), que sempre emite a forma canônica (com um prefixo 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 os campos `type` e `id` diretamente. As propriedades booleanas `is_repo` e `is_bucket` distinguem entre URIs de repositório e URIs de bucket quando necessário.

### Analisando montagens

`parse_hf_mount` analisa uma especificação de montagem (um URI do HF com um caminho local de montagem e a flag opcional `:ro`/`:rw`) e retorna uma dataclass `HfMount` imutável. Ele usa [parse_hf_uri()](/docs/huggingface_hub/main/pt/package_reference/hf_uris#huggingface_hub.parse_hf_uri) por baixo dos panos.

```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` é reversível por meio de `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'
```

## Referência[[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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py#L79)

**Parâmetros:**

type (`str`) : Um dos valores 'model', 'dataset', 'space', 'kernel' ou 'bucket'.

id (`str`) : O id do repositório ('namespace/name', por exemplo, 'my-org/my-model') para URIs de repositório, ou o id do bucket ('namespace/name') para URIs de bucket.

revision (`str`, *opcional*) : A revisão especificada após '@' na URI, decodificada da URL. 'None' se nenhuma revisão foi especificada, ou para URIs de bucket (que nunca carregam uma revisão). Referências especiais como 'refs/pr/10' e 'refs/convert/parquet' são preservadas como estão.

path_in_repo (`str`) : O caminho dentro do repositório ou bucket. String vazia se a URI apontar para a raiz.

Representação analisada de um URI do Hugging Face Hub ('hf://...').

#### to_uri[[huggingface_hub.HfUri.to_uri]]

```python
to_uri()
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py#L137)

Renderize o URI como uma string canônica 'hf://'.

O prefixo de tipo é sempre escrito explicitamente (por exemplo, 'hf://models/my-org/my-model').

#### to_url[[huggingface_hub.HfUri.to_url]]

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py#L155)

**Parâmetros:**

endpoint (`str`, *opcional*) : Endpoint base a ser usado. O padrão é 'constants.ENDPOINT' (ou seja, 'https://huggingface.co').

**Retorna:** `str`

a URL da web.

Renderize o URI como uma **URL da web** do Hugging Face (o tipo que você abre em um navegador).

Este é o inverso de analisar uma URL com [parse_hf_uri()](/docs/huggingface_hub/main/pt/package_reference/hf_uris#huggingface_hub.parse_hf_uri). A URL retornada aponta para:

- a página inicial do repositório / bucket quando nenhum caminho ou revisão é definido;
- o visualizador de pastas ('/tree/') quando apenas uma revisão é definida;
- o visualizador de arquivos ('/blob//') para arquivos do repositório (a revisão padrão é 'main');
- a rota de árvore ('/tree/') para arquivos de bucket (buckets não são versionados).

Exemplo:
```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`) : O URI a ser analisado. Deve começar com 'hf://', ou ser uma URL do Hugging Face (ex.: 'https://huggingface.co/...').

endpoint (`str`, *opcional*) : Um endpoint de Hub personalizado (por exemplo, um Hub auto-hospedado ou proxied como 'https://hub.my-company.com' ou 'http://localhost:8080/hf'). Quando fornecido, as URLs da web nesse endpoint são reconhecidas, além dos hosts padrão do Hugging Face. Não tem efeito em URIs 'hf://'.

**Retorna:** [HfUri](/docs/huggingface_hub/main/pt/package_reference/hf_uris#huggingface_hub.HfUri)

a URI analisada.

**Exceções:** `HfUriError`

- `HfUriError` -- Se a URI estiver malformada (prefixo ausente, tipo inválido, id ausente, rota de URL não suportada, etc.).

Analisa um URI do Hugging Face Hub ('hf://...') ou uma URL web do Hugging Face.

Uma URI do HF é uma string semelhante a uma URI que identifica uma localização no Hugging Face Hub. A gramática completa é:

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

Para sua conveniência, as **URLs da web** do Hugging Face (aquelas que você copia e cola do site) também são aceitas e normalizadas para o formato canônico 'hf://', por exemplo, 'https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv'. Somente URLs não ambíguas (páginas de repositório/bucket e rotas do visualizador de arquivo/pasta) são aceitas; qualquer outra rota é rejeitada.

Consulte 'docs/source/en/package_reference/hf_uris.md' para a especificação completa.

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py#L207)

**Parâmetros:**

source ([HfUri](/docs/huggingface_hub/main/pt/package_reference/hf_uris#huggingface_hub.HfUri)) : O URI do HF analisado que identifica o recurso do Hub a ser montado.

mount_path (`str`) : O caminho de montagem local (sempre começa com '/').

read_only (`bool`, *opcional*) : True se o mount termina com ':ro', False se termina com ':rw', 'None' se nenhuma flag foi fornecida.

Uma URI do HF associada a um caminho de montagem local e a uma flag opcional de somente leitura.

Usado por Spaces e Jobs para descrever montagens de volume. A sintaxe completa é:

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

#### to_uri[[huggingface_hub.utils.HfMount.to_uri]]

```python
to_uri()
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py#L238)

Renderize o mount como uma string canônica 'hf://'.

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_hf_uris.py#L443)

**Parâmetros:**

mount_str (`str`) : A string de montagem a ser analisada. Deve começar com 'hf://' e conter um segmento ':'.

**Retorna:** `HfMount`

o montado analisado.

**Exceções:** `HfUriError`

- `HfUriError` -- Se a string de montagem estiver malformada (caminho de montagem ausente, URI inválido, etc.).

Analisa uma especificação de montagem do HF ('hf://...:[:ro|:rw]').

Uma especificação de montagem é um URI do HF seguido por um caminho local de montagem e uma flag opcional de somente leitura/leitura e gravação.

A gramática completa é:

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

Consulte 'docs/source/en/package_reference/hf_uris.md' para a especificação completa.

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