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 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 e 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) é analisado de forma idêntica em outro.

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

Sintaxe de URI do HF

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

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:

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

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() 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”:

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

>>> 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() é o inverso da análise de uma URL: ele renderiza a URL web navegável para um URI do 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'

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 sendo 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() é o parser de URI centralizado. É um parser de string puro (sem chamadas de rede) e retorna uma dataclass HfUri imutável.

>>> 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 é conversível de ida e volta por meio de HfUri.to_uri(), que sempre emite a forma canônica (com um prefixo 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 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() por baixo dos panos.

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

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

Referência

classe 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) — 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 o ’@’ 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

< source >

( )

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

< source >

( endpoint: str | None = None ) → str

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(). 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/<revision>’) quando apenas uma revisão é definida;
o visualizador de arquivos (‘/blob/<revision>/<path>’) para arquivos do repositório (a revisão padrão é ‘main’);
a rota da árvore (‘/tree/<path>’) para arquivos de bucket (buckets não são versionados).

Exemplo:

>>> 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) — A URI a ser analisada. Deve começar com ‘hf://’, ou ser uma URL do Hugging Face (por exemplo, ‘https://huggingface.co/…’).
endpoint (str, opcional) — Um endpoint de Hub personalizado (por exemplo, um Hub auto-hospedado ou proxificado 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

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

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

classe huggingface_hub.utils.HfMount

< source >

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

Parâmetros

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

< source >

( )

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

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

huggingface_hub.utils.parse_hf_mount

< source >

( mount_str: str ) → HfMount

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://…:<MOUNT_PATH>[: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:

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

Sintaxe de URI do HF

Sintaxe de montagem do HF

O que é um URI do HF

O que não é um URI do HF

URLs da Web

Formatos de URL suportados

URLs que não são analisadas

Renderizando uma URL da web

Análise em Python

Analisando URIs

Analisando montagens

Referência

classe huggingface_hub.HfUri

to_uri

to_url

huggingface_hub.parse_hf_uri

classe huggingface_hub.utils.HfMount

to_uri

huggingface_hub.utils.parse_hf_mount