HF URI

HF URI는 Hugging Face Hub의 위치를 식별하는 URI 유사 문자열입니다. 라이브러리와 CLI 전반에서 hf://... 문자열은 다음을 가리키기 위해 사용됩니다:

모델, 데이터셋, 스페이스 또는 커널 저장소(선택적으로 리비전으로 고정);
이러한 저장소 내부의 파일 또는 하위 폴더;
bucket 또는 bucket 내부의 하위 폴더

HF 마운트는 HF URI를 로컬 마운트 경로와 선택적인 :ro / :rw 플래그로 감싸며, Spaces와 Jobs 볼륨에서 사용됩니다.

이 페이지는 HF URI와 HF 마운트의 표준 문법을 문서화합니다. 라이브러리 전반에서 동일한 파서가 사용되므로, 한 컨텍스트(예: HfFileSystem)에서 유효한 URI는 다른 컨텍스트에서도 동일하게 파싱됩니다.

parse_hf_uri()는 Hugging Face 웹 URL(예: https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv)도 허용하므로 웹사이트에서 링크를 복사하여 붙여넣을 수 있습니다. 아래 웹 URL을 참조하세요.

HF URI 문법

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

컴포넌트	필수	허용되는 값
`hf://`	네	리터럴 프로토콜 접두사.
`<TYPE>/`	아니요	`models/`, `datasets/`, `spaces/`, `kernels/`, `buckets/` (복수형).
`<ID>`	네	`<namespace>/<name>`
`@<REVISION>`	아니요	Branch, tag, commit SHA 또는 특수 ref(`refs/pr/N`, `refs/convert/...`). 저장소만 해당됩니다.
`/<PATH>`	아니요	리포지토리 또는 버킷 내부의 경로.

HF 마운트 문법

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

마운트는 HF URI 뒤에 :<MOUNT_PATH>와 선택적인 :ro / :rw 플래그가 따라오는 형태입니다.

컴포넌트	필수	허용되는 값
`<MOUNT_PATH>`	네	절대 마운트 경로(`/`로 시작해야 합니다).
`:ro` / `:rw`	아니요	읽기 전용 / 읽기-쓰기 플래그.

HF URI란

다음은 모두 유효한 HF URI입니다:

# 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

다음은 유효한 HF 마운트(볼륨 사양)입니다:

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

HF URI가 아닌 것

파서는 의도적으로 엄격하게 동작합니다. 다음 항목은 거부됩니다:

잘못된 URI	이유
`my-org/my-model`, `./local/path`	`hf://` 접두사가 없으며, 인식되지 않는 Hugging Face URL입니다.
`hf://dataset/org/m`, `hf://model/org/m`	단수형 형식은 사용할 수 없으며, 복수형(`datasets/`, …)을 사용해야 합니다.
`hf://datasets`, `hf://buckets/`	타입 접두어만으로는 유효한 URI가 될 수 없으며, `<ID>`가 필요합니다.
`hf://gpt2`, `hf://datasets/squad`	네임스페이스가 없는 Canonical 레포지토리는 지원되지 않습니다.
`hf://buckets/single-segment`	Buckets는 항상 `namespace/name` 형식이어야 합니다.
`hf://buckets/org/b@v1`	Buckets는 revision 마커를 지원하지 않습니다.
`hf://org/m@`, `hf://datasets/foo/bar@/x`	`@` 뒤에 빈 revision이 있습니다.
`hf://a/b/c@v1`	리포지토리 ID는 `namespace/name` 형식이어야 하며, 추가 세그먼트는 경로입니다.
`hf://org/m:/`	마운트 경위는 비어 있지 않은 절대 경로여야 합니다.

웹 URL

편의상 parse_hf_uri()는 브라우저에서 복사한 Hugging Face 웹 URL도 받아들입니다. 이러한 URL은 정형화된 hf:// 형식으로 정규화되므로, CLI나 라이브러리에 URL을 그대로 붙여넣으면 바로 동작합니다:

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

huggingface.co의 URL(그리고 hf.co 짧은 도메인, 스테이징 호스트, 사용자 정의 HF_ENDPOINT의 호스트)은 https:// 스킴이 있든 없든 인식됩니다. 쿼리 문자열(?download=true)과 조각(#L10)은 무시됩니다.

다른 Hub 배포(예: 자체 호스팅 또는 프록시된 Hub)의 URL을 파싱하려면 기본 URL을 endpoint로 전달합니다. 그러면 기본 호스트 외에 해당 호스트도 인식되며, 파싱 전에 경로 접두사(예: http://localhost:8080/hf)가 제거됩니다:

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

지원되는 URL 형식

아래 표에는 지원되는 라우트가 나열되어 있습니다. 간결성을 위해 URL 경로만 표시합니다(호스트 이후의 부분, 예: huggingface.co). 인식되는 호스트는 암시됩니다.

포인터	URL 경로
모델 저장소	`/<ns>/<name>`
데이터셋 저장소(`spaces/`, `kernels/`, `models/`도 동일)	`/datasets/<ns>/<name>`
`<rev>`에 고정된 저장소 안의 폴더	`/<ns>/<name>/tree/<rev>[/<path>]`
리포지토리 내부의 파일 (파일 뷰어 경로)	`/<ns>/<name>/blob/<rev>/<path>`
File inside a repo (download route)	`/<ns>/<name>/resolve/<rev>/<path>`
File inside a repo (raw route)	`/<ns>/<name>/raw/<rev>/<path>`
blame 루트를 사용하는 저장소 내 파일	`/<ns>/<name>/blame/<rev>/<path>`
버킷	`/buckets/<ns>/<name>`
버킷 내부의 파일(버킷은 버전 관리되지 않음)	`/buckets/<ns>/<name>/resolve/<path>`
bucket 안의 폴더	`/buckets/<ns>/<name>/tree/<path>`

Revision은 blob/resolve/raw/tree/blame 바로 뒤의 단일 세그먼트에서 가져옵니다. /를 포함하더라도 특수 ref(refs/pr/N, refs/convert/...)는 즉시 매칭됩니다. /를 포함하는 기타 branch/tag 이름은 URL-encode(feature%2Ffoo)해야 합니다.

해석되지 않은 URL

URL이 모호하거나 Hub의 구체적인 위치를 가리키지 않는 경우, 해당 URL은 거부됩니다(추측하지 않음):

아래의 경로들은 마지막 행을 제외하고 호스트 없이 표시됩니다. 마지막 행에서는 호스트 자체가 거부 사유입니다.

이유	URL 경로
단일 세그먼트 URL: 사용자/조직 페이지, 목록 페이지 또는 정준 저장소 — 모호함.	`/<username>`
`<ns>/<name>`가 없는 목록 페이지.	`/datasets`
네임스페이스가 없는 Canonical 레포지토리는 지원되지 않습니다.	`/gpt2`
`commits`, `discussions`, `settings` 등 파일/폴더 위치가 아닙니다.	`/<ns>/<name>/commit/<rev>`
Collections은 저장소가 아닙니다.	`/collections/<ns>/<slug>`
Host는 인식되지 않는 Hugging Face 호스트입니다.	`https://example.com/<ns>/<name>`

웹 URL 렌더링

HfUri.to_url()은 URL을 파싱하는 것의 역연산으로, HF URI에 대한 브라우저에서 열람 가능한 웹 URL을 생성합니다.

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

경로나 리비전이 설정되지 않은 경우 저장소/버킷 랜딩 페이지를, 리비지만 설정된 경우 폴더 뷰어(/tree/<rev>)를, 저장소 파일의 경우 파일 뷰어(/blob/<rev>/<path>, 리비전은 기본적으로 main)를, 버킷 파일의 경우 트리 루트(/tree/<path>)를 가리킵니다. 경로에 포함된 특수 문자(공백, #, …)는 퍼센트 인코딩됩니다. 커스텀 호스트를 대상으로 하려면 endpoint=...를 전달하세요.

Python에서 파싱

URI 파싱

parse_hf_uri()는 중앙 집중식 URI 파서입니다. 순수 문자열 파서(네트워크 호출 없음)이며, 동결된 HfUri dataclass를 반환합니다.

>>> 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는 HfUri.to_uri()를 통해 왕복 변환이 가능하며, 이 메서드는 항상 명시적인 타입 접두사가 포함된 정규화된 형식을 출력합니다:

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

type와 id 필드를 직접 사용하세요. 불리언 속성 is_repo와 is_bucket은 필요할 때 리포지토리 URI와 버킷 URI를 구별합니다.

마운트 파싱

parse_hf_mount는 마운트 사양(HF URI, 로컬 마운트 경로, 선택적 :ro/:rw 플래그)을 파싱하여 동결된 HfMount dataclass를 반환합니다. 내부적으로 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는 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'

참고

class huggingface_hub.HfUri

< source >

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

매개변수

type (str) — ‘model’, ‘dataset’, ‘space’, ‘kernel’, ‘bucket’ 중 하나입니다.
id (str) — repo URI의 경우 저장소 id(‘namespace/name’, 예: ‘my-org/my-model’), bucket URI의 경우 bucket id(‘namespace/name’)입니다.
revision (str, 선택 사항) — URI에서 ’@’ 뒤에 지정된 리비전으로, URL 디코딩이 적용된 값입니다. 리비전이 지정되지 않았거나 버킷 URI인 경우(리비전을 포함하지 않음)에는 ‘None’입니다. ‘refs/pr/10’, ‘refs/convert/parquet’과 같은 특수한 ref는 그대로 유지됩니다.
path_in_repo (str) — 리포지토리 또는 버킷 내부의 경로입니다. URI가 루트를 가리키는 경우 빈 문자열입니다.

Hugging Face Hub URI(‘hf://…’)의 파싱된 표현

to_uri

< source >

( )

URI를 정형화된 ‘hf://’ 문자열로 렌더링합니다.

타입 접두사는 항상 명시적으로 작성됩니다(예: ‘hf://models/my-org/my-model’).

to_url

< source >

( endpoint: str | None = None ) → str

매개변수

endpoint (str, 선택 사항) — 사용할 기본 endpoint입니다. 기본값은 ‘constants.ENDPOINT’(즉, ’https://huggingface.co’)입니다.

반환값

str

웹 URL.

URI를 Hugging Face 웹 URL(브라우저에서 여는 형태)로 렌더링합니다.

이것은 parse_hf_uri()로 URL을 파싱하는 것의 역연산입니다. 반환되는 URL은 다음을 가리킵니다:

경로나 리비전이 설정되지 않은 경우 저장소/버킷 랜딩 페이지;
리비전만 설정된 경우 폴더 뷰어(‘/tree/<revision>’);
리포지토리 파일의 파일 뷰어(‘/blob/<revision>/<path>’)(revision은 기본적으로 ‘main’입니다);
버킷 파일의 트리 라우트(‘/tree/<path>’)(버킷은 버전 관리되지 않음).

예:

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

매개변수

uri (str) — 파싱할 URI입니다. ‘hf://’로 시작하거나 Hugging Face URL(예: ’https://huggingface.co/…’)이어야 합니다.
endpoint (str, 선택) — 사용자 정의 Hub 엔드포인트(예: ‘https://hub.my-company.com’ 또는 ‘http://localhost:8080/hf’와 같은 자체 호스팅 또는 프록시된 Hub)입니다. 이 값이 제공되면 기본 Hugging Face 호스트 외에도 해당 엔드포인트의 웹 URL이 인식됩니다. ‘hf://’ URI에는 영향을 미치지 않습니다.

반환값

HfUri

해석된 URI.

다음 예외가 발생합니다

HfUriError

HfUriError — URI가 잘못된 형식인 경우(접두어 누락, 잘못된 유형, id 누락, 지원되지 않는 URL 루트 등).

Hugging Face Hub URI(‘hf://…’) 또는 Hugging Face 웹 URL을 파싱합니다.

HF URI는 Hugging Face Hub의 위치를 식별하는 URI 유사 문자열입니다. 전체 문법은 다음과 같습니다:

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

편의상 Hugging Face 웹 URL(웹사이트에서 복사하여 붙여넣는 것)도 허용되며, 정형화된 ‘hf://’ 형식으로 정규화됩니다. 예를 들어, ‘https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv’’와 같습니다. 모호하지 않은 URL(리포지토리/버킷 페이지 및 파일/폴더 뷰어 경로)만 허용되며, 기타 경로는 거부됩니다.

전체 사양은 docs/source/en/package_reference/hf_uris.md를 참조하세요.

예:

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

class huggingface_hub.utils.HfMount

< source >

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

매개변수

source (HfUri) — 마운트할 Hub 리소스를 식별하는 파싱된 HF URI입니다.
mount_path (str) — 로컬 마운트 경로(항상 ’/’로 시작합니다).
read_only (bool, 선택 사항) — 마운트가 ‘:ro’로 끝나면 True, ‘:rw’로 끝나면 False, 플래그가 제공되지 않으면 ‘None’입니다.

로컬 마운트 경로와 선택적 읽기 전용 플래그와 함께 사용되는 HF URI입니다.

Spaces와 Jobs에서 볼륨 마운트를 설명하는 데 사용됩니다. 전체 구문은 다음과 같습니다:

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

to_uri

< source >

( )

마운트를 정형화된 ‘hf://’ 문자열로 렌더링합니다.

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

huggingface_hub.utils.parse_hf_mount

< source >

( mount_str: str ) → HfMount

매개변수

mount_str (str) — 파싱할 마운트 문자열입니다. ‘hf://’로 시작하고 ’:’ 세그먼트를 포함해야 합니다.

반환값

HfMount

해석된 마운트

다음 예외가 발생합니다

HfUriError

HfUriError — 마운트 문자열이 잘못된 형식인 경우(마운트 경로 누락, 잘못된 URI 등).

HF 마운트 사양(‘hf://…:<MOUNT_PATH>[:ro|:rw]’)을 파싱합니다.

마운트 사양은 HF URI, 로컬 마운트 경로, 선택적인 읽기 전용/읽기-쓰기 플래그로 구성됩니다.

전체 문법은 다음과 같습니다:

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

전체 사양은 docs/source/en/package_reference/hf_uris.md를 참조하세요.

예:

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

HF URI

HF URI 문법

HF 마운트 문법

HF URI란

HF URI가 아닌 것

웹 URL

지원되는 URL 형식

해석되지 않은 URL

웹 URL 렌더링

Python에서 파싱

URI 파싱

마운트 파싱

참고

class huggingface_hub.HfUri

to_uri

to_url

huggingface_hub.parse_hf_uri

class huggingface_hub.utils.HfMount

to_uri

huggingface_hub.utils.parse_hf_mount