# HF URI *HF URI*는 Hugging Face Hub의 위치를 식별하는 URI 유사 문자열입니다. 라이브러리와 CLI 전반에서 `hf://...` 문자열은 다음을 가리키기 위해 사용됩니다: - 모델, 데이터셋, 스페이스 또는 커널 저장소(선택적으로 리비전으로 고정); - 이러한 저장소 내부의 파일 또는 하위 폴더; - [bucket](../guides/buckets) 또는 bucket 내부의 하위 폴더 *HF 마운트*는 HF URI를 로컬 마운트 경로와 선택적인 `:ro` / `:rw` 플래그로 감싸며, [Spaces](../guides/manage-spaces)와 [Jobs](../guides/jobs) 볼륨에서 사용됩니다. 이 페이지는 HF URI와 HF 마운트의 표준 문법을 문서화합니다. 라이브러리 전반에서 동일한 파서가 사용되므로, 한 컨텍스트(예: [HfFileSystem](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_file_system#huggingface_hub.HfFileSystem))에서 유효한 URI는 다른 컨텍스트에서도 동일하게 파싱됩니다. [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_uris#huggingface_hub.parse_hf_uri)는 Hugging Face **웹 URL**(예: `https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv`)도 허용하므로 웹사이트에서 링크를 복사하여 붙여넣을 수 있습니다. 아래 [웹 URL](#web-urls)을 참조하세요. ## HF URI 문법 ```text hf://[/][@][/] ``` | 컴포넌트 | 필수 | 허용되는 값 | | --------------- | -------- | ------------------------------------------------------------------- | | `hf://` | 네 | 리터럴 프로토콜 접두사. | | `/` | 아니요 | `models/`, `datasets/`, `spaces/`, `kernels/`, `buckets/` (복수형). | | `` | 네 | `/` | | `@` | 아니요 | Branch, tag, commit SHA 또는 특수 ref(`refs/pr/N`, `refs/convert/...`). 저장소만 해당됩니다. | | `/` | 아니요 | 리포지토리 또는 버킷 내부의 경로. | ## HF 마운트 문법 ```text hf://[/][@][/]:[:ro|:rw] ``` 마운트는 HF URI 뒤에 `:`와 선택적인 `:ro` / `:rw` 플래그가 따라오는 형태입니다. | 컴포넌트 | 필수 | 허용되는 값 | | --------------- | -------- | ------------------------------------------------------------------- | | `` | 네 | 절대 마운트 경로(`/`로 시작해야 합니다). | | `:ro` / `:rw` | 아니요 | 읽기 전용 / 읽기-쓰기 플래그. | ## HF URI란 다음은 **모두 유효한 HF URI**입니다: ```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 ``` 다음은 **유효한 HF 마운트**(볼륨 사양)입니다: ```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 ``` ## 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가 될 수 없으며, ``가 필요합니다. | | `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()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_uris#huggingface_hub.parse_hf_uri)는 브라우저에서 복사한 Hugging Face 웹 URL도 받아들입니다. 이러한 URL은 정형화된 `hf://` 형식으로 정규화되므로, CLI나 라이브러리에 URL을 그대로 붙여넣으면 바로 동작합니다: ```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') ``` `huggingface.co`의 URL(그리고 `hf.co` 짧은 도메인, 스테이징 호스트, 사용자 정의 `HF_ENDPOINT`의 호스트)은 `https://` 스킴이 있든 없든 인식됩니다. 쿼리 문자열(`?download=true`)과 조각(`#L10`)은 무시됩니다. 다른 Hub 배포(예: 자체 호스팅 또는 프록시된 Hub)의 URL을 파싱하려면 기본 URL을 `endpoint`로 전달합니다. 그러면 기본 호스트 외에 해당 호스트도 인식되며, 파싱 전에 경로 접두사(예: `http://localhost:8080/hf`)가 제거됩니다: ```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='') ``` ### 지원되는 URL 형식 아래 표에는 지원되는 라우트가 나열되어 있습니다. 간결성을 위해 **URL 경로**만 표시합니다(호스트 이후의 부분, 예: `huggingface.co`). 인식되는 호스트는 암시됩니다. | 포인터 | URL 경로 | | -------------------------------------------------------------- | ---------------------------------------------- | | 모델 저장소 | `//` | | 데이터셋 저장소(`spaces/`, `kernels/`, `models/`도 동일) | `/datasets//` | | ``에 고정된 저장소 안의 폴더 | `///tree/[/]` | | 리포지토리 내부의 파일 (파일 뷰어 경로) | `///blob//` | | File inside a repo (download route) | `///resolve//` | | File inside a repo (raw route) | `///raw//` | | blame 루트를 사용하는 저장소 내 파일 | `///blame//` | | 버킷 | `/buckets//` | | 버킷 내부의 파일(버킷은 버전 관리되지 않음) | `/buckets///resolve/` | | bucket 안의 폴더 | `/buckets///tree/` | Revision은 `blob`/`resolve`/`raw`/`tree`/`blame` 바로 뒤의 단일 세그먼트에서 가져옵니다. `/`를 포함하더라도 특수 ref(`refs/pr/N`, `refs/convert/...`)는 즉시 매칭됩니다. `/`를 포함하는 기타 branch/tag 이름은 URL-encode(`feature%2Ffoo`)해야 합니다. ### **해석되지 않는** URL URL이 모호하거나 Hub의 구체적인 위치를 가리키지 않는 경우, 해당 URL은 **거부**됩니다(추측하지 않음): 아래의 경로들은 마지막 행을 제외하고 호스트 없이 표시됩니다. 마지막 행에서는 호스트 자체가 거부 사유입니다. | 이유 | URL 경로 | | -------------------------------------------------------------------------------- | --------------------------------------- | | 단일 세그먼트 URL: 사용자/조직 페이지, 목록 페이지 또는 정준 저장소 — 모호함. | `/` | | `/`가 없는 목록 페이지. | `/datasets` | | 네임스페이스가 없는 Canonical 레포지토리는 지원되지 않습니다. | `/gpt2` | | `commits`, `discussions`, `settings` 등 파일/폴더 위치가 아닙니다. | `///commit/` | | Collections은 저장소가 아닙니다. | `/collections//` | | Host는 인식되지 않는 Hugging Face 호스트입니다. | `https://example.com//` | ## 웹 URL 렌더링 [HfUri.to_url()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_uris#huggingface_hub.HfUri.to_url)은 URL을 파싱하는 것의 역연산으로, HF URI에 대한 브라우저에서 열람 가능한 웹 URL을 생성합니다. ```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' ``` 경로나 리비전이 설정되지 않은 경우 저장소/버킷 랜딩 페이지를, 리비지만 설정된 경우 폴더 뷰어(`/tree/`)를, 저장소 파일의 경우 파일 뷰어(`/blob//`, 리비전은 기본적으로 `main`)를, 버킷 파일의 경우 트리 루트(`/tree/`)를 가리킵니다. 경로에 포함된 특수 문자(공백, `#`, ...)는 퍼센트 인코딩됩니다. 커스텀 호스트를 대상으로 하려면 `endpoint=...`를 전달하세요. ## Python에서 파싱 ### URI 파싱 [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_uris#huggingface_hub.parse_hf_uri)는 중앙 집중식 URI 파서입니다. 순수 문자열 파서(네트워크 호출 없음)이며, 동결된 [HfUri](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_uris#huggingface_hub.HfUri) dataclass를 반환합니다. ```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/ko/package_reference/hf_uris#huggingface_hub.HfUri)는 [HfUri.to_uri()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_uris#huggingface_hub.HfUri.to_uri)를 통해 왕복 변환이 가능하며, 이 메서드는 항상 명시적인 타입 접두사가 포함된 정규화된 형식을 출력합니다: ```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' ``` `type`와 `id` 필드를 직접 사용하세요. 불리언 속성 `is_repo`와 `is_bucket`은 필요할 때 리포지토리 URI와 버킷 URI를 구별합니다. ### 마운트 파싱 `parse_hf_mount`는 마운트 사양(HF URI, 로컬 마운트 경로, 선택적 `:ro`/`:rw` 플래그)을 파싱하여 동결된 `HfMount` dataclass를 반환합니다. 내부적으로 [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ko/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`는 `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' ``` ## 참고[[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) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L79) **매개변수:** 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[[huggingface_hub.HfUri.to_uri]] ```python to_uri() ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L137) URI를 정형화된 'hf://' 문자열로 렌더링합니다. 타입 접두사는 항상 명시적으로 작성됩니다(예: 'hf://models/my-org/my-model'). #### to_url[[huggingface_hub.HfUri.to_url]] ```python to_url(endpoint: str | None = None) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L155) **매개변수:** endpoint (`str`, *선택 사항*) : 사용할 기본 엔드포인트입니다. 기본값은 'constants.ENDPOINT'(즉, 'https://huggingface.co')입니다. **반환값:** `str` 웹 URL. URI를 Hugging Face **웹 URL**(브라우저에서 여는 형태)로 렌더링합니다. 이것은 [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_uris#huggingface_hub.parse_hf_uri)로 URL을 파싱하는 것의 역연산입니다. 반환되는 URL은 다음을 가리킵니다: - 경로나 리비전이 설정되지 않은 경우 저장소/버킷 랜딩 페이지; - revision만 설정된 경우 폴더 뷰어('/tree/'); - 리포지토리 파일의 파일 뷰어 ('/blob//') (리비전 기본값은 'main'); - 버킷 파일의 트리 라우트('/tree/')(버킷은 버전 관리되지 않음). 예: ```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) ``` **매개변수:** 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](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_uris#huggingface_hub.HfUri) 해석된 URI. **예외:** `HfUriError` - `HfUriError` -- URI가 잘못된 형식인 경우(접두어 누락, 잘못된 유형, id 누락, 지원되지 않는 URL 루트 등). Hugging Face Hub URI('hf://...') 또는 Hugging Face 웹 URL을 파싱합니다. HF URI는 Hugging Face Hub의 위치를 식별하는 URI 유사 문자열입니다. 전체 문법은 다음과 같습니다: ``` hf://[/][@][/] ``` 편의상 Hugging Face **웹 URL**(웹사이트에서 복사하여 붙여넣는 URL)도 허용되며, 'hf://' 정규 형식으로 정규화됩니다. 예를 들어 'https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv'와 같습니다. 모호하지 않은 URL(리포지토리/버킷 페이지 및 파일/폴더 뷰어 경로)만 허용되며, 기타 경로는 거부됩니다. 전체 사양은 docs/source/en/package_reference/hf_uris.md를 참조하세요. 예: ```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) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L207) **매개변수:** source ([HfUri](/docs/huggingface_hub/v2.4.0/ko/package_reference/hf_uris#huggingface_hub.HfUri)) : 마운트할 Hub 리소스를 식별하는 파싱된 HF URI입니다. mount_path (`str`) : 로컬 마운트 경로(항상 '/'로 시작합니다). read_only (`bool`, *선택 사항*) : 마운트가 ':ro'로 끝나면 True, ':rw'로 끝나면 False, 플래그가 제공되지 않으면 'None'을 반환합니다. 로컬 마운트 경로와 선택적 읽기 전용 플래그와 함께 사용되는 HF URI입니다. Spaces와 Jobs에서 볼륨 마운트를 설명하는 데 사용됩니다. 전체 구문은 다음과 같습니다: ``` hf://[/][@][/]:[:ro|:rw] ``` #### to_uri[[huggingface_hub.utils.HfMount.to_uri]] ```python to_uri() ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L238) 마운트를 정형화된 'hf://' 문자열로 렌더링합니다. 예: '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) ``` [소스](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_hf_uris.py#L443) **매개변수:** mount_str (`str`) : 파싱할 마운트 문자열입니다. 'hf://'로 시작하고 ':' 세그먼트를 포함해야 합니다. **반환값:** `HfMount` 해석된 마운트 **예외:** `HfUriError` - `HfUriError` -- 마운트 문자열이 잘못된 형식인 경우(마운트 경로 누락, 잘못된 URI 등). HF 마운트 사양('hf://...:[:ro|:rw]')을 파싱합니다. 마운트 사양은 HF URI, 로컬 마운트 경로, 선택적인 읽기 전용/읽기-쓰기 플래그로 구성됩니다. 전체 문법은 다음과 같습니다: ``` hf://[/][@][/]:[:ro|:rw] ``` 전체 사양은 docs/source/en/package_reference/hf_uris.md를 참조하세요. 예: ```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) ```