# 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](../guides/buckets) 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](../guides/manage-spaces) dan [Jobs](../guides/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](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_file_system#huggingface_hub.HfFileSystem)) akan diparsing secara identik di konteks lain.

[parse_hf_uri()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_uris#huggingface_hub.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](#web-urls) di bawah.

## Sintaks URI HF

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

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

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

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

## Apa yang **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()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_uris#huggingface_hub.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":

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

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:

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

### 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()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_uris#huggingface_hub.HfUri.to_url) adalah kebalikan dari parsing URL: ia merender URL web yang dapat dinavigasi untuk URI 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'
```

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()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_uris#huggingface_hub.parse_hf_uri) adalah parser URI terpusat. Ini adalah parser string murni (tanpa panggilan jaringan) dan mengembalikan dataclass [HfUri](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_uris#huggingface_hub.HfUri) yang beku.

```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/id/package_reference/hf_uris#huggingface_hub.HfUri) dapat di-round-trip melalui [HfUri.to_uri()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_uris#huggingface_hub.HfUri.to_uri), yang selalu menghasilkan bentuk kanonik (dengan prefiks tipe eksplisit):

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

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

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

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

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

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

```python
to_uri()
```

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

Render URI sebagai string 'hf://' yang kanonik.

Prefiks tipe selalu ditulis secara eksplisit (mis. 'hf://models/my-org/my-model').

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

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

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

**Parameter:**

endpoint (`str`, *opsional*) : Endpoint dasar yang akan digunakan. Bawaan 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()](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_uris#huggingface_hub.parse_hf_uri). URL yang dikembalikan menunjuk ke:

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

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

**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](/docs/huggingface_hub/v2.4.0/id/package_reference/hf_uris#huggingface_hub.HfUri)

URI yang telah diurai.

**Mengangkat:** `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 repositori / bucket dan rute penampil file/folder) yang diterima; rute lain ditolak.

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

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

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

**Parameter:**

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

```python
to_uri()
```

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

Render mount sebagai string 'hf://' yang kanonik.

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

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

**Parameter:**

mount_str (`str`) : String mount yang akan diurai. Harus diawali dengan 'hf://' dan mengandung segmen ':'.

**Mengembalikan:** `HfMount`

mount yang telah diurai.

**Mengangkat:** `HfUriError`

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

Parse spesifikasi mount HF ('hf://...:[: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:
```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)
```