URI HF

URI HF adalah string mirip URI yang mengidentifikasi lokasi di Hugging Face Hub. Di seluruh pustaka dan CLI, string hf://... digunakan untuk menunjuk ke:

repo model, dataset, space, atau kernel (secara opsional dikunci pada revisi tertentu);
file atau sub-folder di dalam repositori tersebut;
a bucket atau sub-folder di dalam bucket.

HF mount membungkus URI HF dengan jalur mount lokal dan flag opsional :ro / :rw, yang digunakan oleh volume Spaces dan Jobs.

Halaman ini mendokumentasikan sintaks kanonik dari URI HF dan mount HF. Parser yang sama digunakan di seluruh pustaka, sehingga URI yang valid dalam satu konteks (misalnya HfFileSystem) akan diparsing secara identik di konteks lain.

parse_hf_uri() juga menerima URL web Hugging Face (misalnya https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv) sehingga Anda dapat menyalin-tempel tautan dari situs web. Lihat URL Web di bawah.

Sintaks URI HF

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

Komponen	Wajib	Nilai yang diizinkan
`hf://`	ya	Prefiks protokol literal.
`<TYPE>/`	tidak	`models/`, `datasets/`, `spaces/`, `kernels/`, `buckets/` (jamak).
`<ID>`	ya	`<namespace>/<name>`
`@<REVISION>`	tidak	Branch, tag, commit SHA, atau ref khusus (`refs/pr/N`, `refs/convert/...`). Hanya untuk repos.
`/<PATH>`	tidak	Path di dalam repo atau bucket.

Sintaks mount HF

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

Mount adalah URI HF yang diikuti oleh :<MOUNT_PATH> dan flag opsional :ro / :rw.

Komponen	Wajib	Nilai yang diizinkan
`<MOUNT_PATH>`	ya	Path mount absolut (harus diawali dengan `/`).
`:ro` / `:rw`	tidak	Flag baca-saja / baca-tulis.

Apa itu URI HF

Berikut adalah semua URI HF yang valid:

# 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

Berikut adalah mount HF yang valid (spesifikasi 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

Bukan URI HF

Parser ini sengaja dibuat ketat. Berikut yang ditolak:

URI tidak valid	Alasan
`my-org/my-model`, `./local/path`	Prefix `hf://` tidak ada dan bukan URL Hugging Face yang dikenali.
`hf://dataset/org/m`, `hf://model/org/m`	Bentuk tipe tunggal dilarang, gunakan bentuk jamak (`datasets/`, …).
`hf://datasets`, `hf://buckets/`	Prefix tipe saja bukan URI yang valid, `<ID>` diperlukan.
`hf://gpt2`, `hf://datasets/squad`	Repo kanonik (tanpa namespace) tidak didukung.
`hf://buckets/single-segment`	Buckets harus selalu berupa `namespace/name`.
`hf://buckets/org/b@v1`	Buckets tidak mendukung penanda revisi.
`hf://org/m@`, `hf://datasets/foo/bar@/x`	Revisi kosong setelah `@`.
`hf://a/b/c@v1`	Repo id harus berupa `namespace/name`, segmen tambahan adalah path.
`hf://org/m:/`	Path mount harus berupa path absolut yang tidak kosong.

URL Web

Untuk kenyamanan, parse_hf_uri() juga menerima URL web Hugging Face yang Anda salin-tempel dari browser. URL tersebut dinormalisasi ke bentuk kanonik hf://, sehingga Anda dapat menempelkan URL langsung ke CLI atau pustaka dan “langsung berfungsi”:

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

URL dari huggingface.co (dan domain pendek hf.co, host staging, serta host dari HF_ENDPOINT kustom) dikenali, dengan atau tanpa skema https://. String kueri (?download=true) dan fragmen (#L10) diabaikan.

Untuk mengurai URL dari deployment Hub lain (misalnya Hub self-hosted atau yang diproksi), lewati URL dasarnya sebagai endpoint. Host-nya kemudian dikenali di samping host default, dan prefiks path (misalnya http://localhost:8080/hf) dihapus sebelum penguraian:

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

Format URL yang didukung

Tabel di bawah ini mencantumkan rute yang didukung. Untuk ringkas, hanya jalur URL yang ditampilkan (bagian setelah host, misalnya huggingface.co); host yang dikenali tersirat.

Menunjuk ke	Path URL
Repositori model	`/<ns>/<name>`
Repositori dataset (sama untuk `spaces/`, `kernels/`, `models/`)	`/datasets/<ns>/<name>`
Folder di dalam repo, dipatok di `<rev>`	`/<ns>/<name>/tree/<rev>[/<path>]`
File di dalam repo (route penampil file)	`/<ns>/<name>/blob/<rev>/<path>`
File di dalam repo (jalur unduhan)	`/<ns>/<name>/resolve/<rev>/<path>`
File di dalam repo (jalur mentah)	`/<ns>/<name>/raw/<rev>/<path>`
File di dalam repo (rute blame)	`/<ns>/<name>/blame/<rev>/<path>`
Bucket	`/buckets/<ns>/<name>`
File di dalam bucket (bucket tidak memiliki versi)	`/buckets/<ns>/<name>/resolve/<path>`
Folder di dalam bucket	`/buckets/<ns>/<name>/tree/<path>`

Revisi diambil dari segmen tunggal tepat setelah blob/resolve/raw/tree/blame. Ref khusus (refs/pr/N, refs/convert/...) dicocokkan secara langsung meskipun mengandung /; nama branch/tag lain yang mengandung / harus di-URL-encode (feature%2Ffoo).

URL yang tidak diurai

Ketika URL ambigu atau tidak menunjuk ke lokasi Hub yang konkret, URL tersebut ditolak (tidak pernah ditebak):

Path di bawah ini kembali ditampilkan tanpa host, kecuali pada baris terakhir di mana host itu sendiri adalah alasan penolakannya.

Alasan	Path URL
URL satu segmen: halaman user/org, halaman daftar, atau repo kanonik — ambigu.	`/<username>`
Halaman daftar, tanpa `<ns>/<name>`.	`/datasets`
Repo kanonik (tanpa namespace) tidak didukung.	`/gpt2`
Bukan lokasi file/folder (hal yang sama berlaku untuk `commits`, `discussions`, `settings`, …).	`/<ns>/<name>/commit/<rev>`
Koleksi bukan repositori.	`/collections/<ns>/<slug>`
Host tidak dikenali sebagai host Hugging Face.	`https://example.com/<ns>/<name>`

Merender URL web

HfUri.to_url() adalah kebalikan dari parsing URL: ia merender URL web yang dapat dinavigasi untuk 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'

Hal ini mengarah ke halaman utama repositori / bucket jika tidak ada path atau revision yang diset, ke penampil folder (/tree/<rev>) jika hanya revision yang diset, ke penampil file (/blob/<rev>/<path>, dengan revision default main) untuk file repositori, dan ke rute tree (/tree/<path>) untuk file bucket. Karakter khusus dalam path (spasi, #, …) di-encode secara persentase. Luluskan endpoint=... untuk menargetkan host kustom.

Parsing dalam Python

Menganalisis URI

parse_hf_uri() adalah parser URI terpusat. Ini adalah parser string murni (tanpa panggilan jaringan) dan mengembalikan dataclass HfUri yang beku.

>>> 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 dapat di-round-trip melalui HfUri.to_uri(), yang selalu menghasilkan bentuk kanonik (dengan prefiks tipe eksplisit):

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

Gunakan langsung field type dan id. Properti boolean is_repo dan is_bucket membedakan antara URI repositori dan URI bucket saat diperlukan.

Menganalisis mount

parse_hf_mount mengurai spesifikasi mount (URI HF dengan jalur mount lokal dan flag opsional :ro/:rw) dan mengembalikan dataclass HfMount yang beku. Di baliknya, fungsi ini menggunakan parse_hf_uri().

>>> 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 dapat di-round-trip melalui 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'

Referensi

kelas huggingface_hub.HfUri

< source >

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

Parameter

type (str) — Salah satu dari ‘model’, ‘dataset’, ‘space’, ‘kernel’ atau ‘bucket’.
id (str) — id repositori (‘namespace/name’, mis. ‘my-org/my-model’) untuk URI repositori, atau id bucket (‘namespace/name’) untuk URI bucket.
revision (str, opsional) — Revisi yang ditentukan setelah ’@’ dalam URI, yang telah di-decode URL. ‘None’ jika tidak ada revisi yang ditentukan, atau untuk URI bucket (yang tidak pernah membawa revisi). Referensi khusus seperti ‘refs/pr/10’ dan ‘refs/convert/parquet’ dipertahankan apa adanya.
path_in_repo (str) — Path di dalam repo atau bucket. String kosong jika URI menunjuk ke root.

Representasi terurai dari URI Hugging Face Hub (‘hf://…’).

to_uri

< source >

( )

Render URI sebagai string ‘hf://’ kanonik.

Prefiks tipe selalu ditulis secara eksplisit (misalnya ‘hf://models/my-org/my-model’).

ke_url

< source >

( endpoint: str | None = None ) → str

Parameter

endpoint (str, opsional) — Endpoint dasar yang akan digunakan. Defaultnya adalah ‘constants.ENDPOINT’ (yaitu ’https://huggingface.co’).

Mengembalikan

str

URL web.

Render URI sebagai URL web Hugging Face (jenis yang Anda buka di browser).

Ini adalah kebalikan dari parsing URL dengan parse_hf_uri(). URL yang dikembalikan menunjuk ke:

halaman utama repositori / bucket ketika tidak ada path atau revision yang diatur;
penampil folder ('/tree/<revision>') ketika hanya revisi yang diatur;
penampil berkas ('/blob/<revision>/<path>') untuk berkas repositori (revision secara default adalah 'main');
route pohon ('/tree/<path>') untuk file bucket (bucket tidak diversioning).

Contoh:

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

Parameter

uri (str) — URI yang akan diurai. Harus diawali dengan ‘hf://’, atau berupa URL Hugging Face (mis. ’https://huggingface.co/…’).
endpoint (str, opsional) — Endpoint Hub kustom (misalnya Hub yang self-hosted atau diproksi seperti ’https://hub.my-company.com’ atau ‘http://localhost:8080/hf’). Jika diberikan, URL web pada endpoint tersebut dikenali di samping host Hugging Face default. Tidak berdampak pada URI ‘hf://’.

Mengembalikan

HfUri

URI yang telah diurai.

Membuang

HfUriError

HfUriError — Jika URI tidak valid (prefix hilang, tipe tidak valid, id hilang, rute URL tidak didukung, dll.).

Parse URI Hugging Face Hub ('hf://…') atau URL web Hugging Face.

URI HF adalah string mirip URI yang mengidentifikasi lokasi di Hugging Face Hub. Tata bahasa lengkapnya adalah:

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

Untuk kenyamanan, URL web Hugging Face (yang Anda salin-tempel dari situs web) juga diterima dan dinormalisasi ke bentuk kanonik ‘hf://’, misalnya ‘https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv’. Hanya URL yang tidak ambigu (halaman repository / bucket dan rute viewer file/folder) yang diterima; rute lainnya akan ditolak.

Lihat ‘docs/source/en/package_reference/hf_uris.md’ untuk spesifikasi lengkap.

Contoh:

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

kelas huggingface_hub.utils.HfMount

< source >

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

Parameter

source (HfUri) — URI HF yang telah diurai untuk mengidentifikasi sumber daya Hub yang akan dipasang.
mount_path (str) — Jalur mount lokal (selalu diawali dengan ’/’).
read_only (bool, opsional) — True jika mount diakhiri dengan ‘:ro’, False jika diakhiri dengan ‘:rw’, ‘None’ jika tidak ada flag yang diberikan.

URI HF yang dipasangkan dengan jalur mount lokal dan flag read-only opsional.

Digunakan oleh Spaces dan Jobs untuk menjelaskan volume mounts. Sintaks lengkapnya adalah:

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

to_uri

< source >

( )

Render mount sebagai string ‘hf://’ kanonik.

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

huggingface_hub.utils.parse_hf_mount

< source >

( mount_str: str ) → HfMount

Parameter

mount_str (str) — String mount yang akan diurai. Harus diawali dengan ‘hf://’ dan mengandung segmen ’:’.

Mengembalikan

HfMount

mount yang telah diurai.

Membuang

HfUriError

HfUriError — Jika string mount tidak valid (path mount hilang, URI tidak valid, dll.).

Parse spesifikasi mount HF (‘hf://…:<MOUNT_PATH>[:ro|:rw]’).

Spesifikasi mount adalah URI HF yang diikuti oleh jalur mount lokal dan flag opsional read-only/read-write.

Tata bahasa lengkapnya adalah:

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

Lihat ‘docs/source/en/package_reference/hf_uris.md’ untuk spesifikasi lengkap.

Contoh:

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

URI HF

Sintaks URI HF

Sintaks mount HF

Apa itu URI HF

Bukan URI HF

URL Web

Format URL yang didukung

URL yang tidak diurai

Merender URL web

Parsing dalam Python

Menganalisis URI

Menganalisis mount

Referensi

kelas huggingface_hub.HfUri

to_uri

ke_url

huggingface_hub.parse_hf_uri

kelas huggingface_hub.utils.HfMount

to_uri

huggingface_hub.utils.parse_hf_mount