# HF URI *HF URI*とは、Hugging Face Hub上の場所を識別するURI風の文字列です。ライブラリおよびCLI全体で、`hf://...`文字列は以下を指すために使用されます: - モデル、データセット、スペース、またはカーネルのリポジトリ（リビジョンを固定することも可能）; - そのようなリポジトリ内のファイルまたはサブフォルダ; - [バケット](../guides/buckets)またはバケット内のサブフォルダー。 *HF マウント*は、HF URI をローカルマウントパスと任意の `:ro` / `:rw` フラグでラップしたもので、[Spaces](../guides/manage-spaces) と [Jobs](../guides/jobs) のボリュームで使用されます。 このページでは、HF URIおよびHFマウントの正規構文を説明しています。ライブラリ全体で同じパーサーが使用されるため、あるコンテキスト（例: [HfFileSystem](/docs/huggingface_hub/main/ja/package_reference/hf_file_system#huggingface_hub.HfFileSystem)）で有効なURIは、別のコンテキストでも同一に解析されます。 [parse_hf_uri()](/docs/huggingface_hub/main/ja/package_reference/hf_uris#huggingface_hub.parse_hf_uri) は Hugging Face の **Web URL**（例: `https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv`）も受け付けるため、ウェブサイトからリンクをコピー＆ペーストできます。詳細は下記の [Web URL](#web-urls) を参照してください。 ## HF URI構文 ```text hf://[/][@][/] ``` | コンポーネント | 必須 | 許可される値 | | --------------- | -------- | ------------------------------------------------------------------- | | `hf://` | はい | リテラルプロトコルプレフィックス。 | | `/` | いいえ | `models/`、`datasets/`、`spaces/`、`kernels/`、`buckets/`（複数形）。 | | `` | はい | `/` | | `@` | いいえ | ブランチ、タグ、コミット 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` | 名前空間のない正規リポジトリはサポートされていません。 | | `hf://buckets/single-segment` | バケットは常に`namespace/name`である必要があります。 | | `hf://buckets/org/b@v1` | Buckets はリビジョンマーカーをサポートしていません。 | | `hf://org/m@`, `hf://datasets/foo/bar@/x` | `@`の後に空のrevisionがあります。 | | `hf://a/b/c@v1` | リポジトリIDは`namespace/name`の形式でなければならず、追加のセグメントはパスとして扱われます。 | | `hf://org/m:/` | マウントパスは空でない絶対パスでなければなりません。 | ## Web URL 利便性のため、[parse_hf_uri()](/docs/huggingface_hub/main/ja/package_reference/hf_uris#huggingface_hub.parse_hf_uri) は、ブラウザからコピー＆ペーストした Hugging Face の Web URL も受け入れます。これらは正規の `hf://` 形式に正規化されるため、URL をそのまま CLI やライブラリに貼り付けても「そのまま動作します」: ```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`（およびその短縮ドメイン `hf.co`、ステージングホスト、カスタム `HF_ENDPOINT` のホスト）からの URL は、`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//` | | リポジトリ内のファイル（ダウンロードルート） | `///resolve//` | | リポジトリ内のファイル（rawルート） | `///raw//` | | リポジトリ内のファイル（blameルート） | `///blame//` | | バケット | `/buckets//` | | バケット内のファイル（バケットはバージョン管理されていません） | `/buckets///resolve/` | | バケット内のフォルダ | `/buckets///tree/` | リビジョンは、`blob`/`resolve`/`raw`/`tree`/`blame` の直後の単一のセグメントから取得されます。特殊なリファレンス（`refs/pr/N`、`refs/convert/...`）は、`/` を含むにもかかわらず、優先的にマッチングされます。`/` を含むその他のブランチ名やタグ名は、URLエンコード（`feature%2Ffoo`）する必要があります。 ### **解析されない**URL URLが曖昧であるか、具体的なHubの場所を指していない場合、**拒否**されます（推測は行われません）： 以下のパスは、ホストを省略して表示しています。ただし、最後の行はホスト自体が拒否理由であるため、ホストを含めて表示しています。 | 理由 | URLパス | | -------------------------------------------------------------------------------- | --------------------------------------- | | 単一セグメントのURL: ユーザー/組織ページ、一覧ページ、正規リポジトリ — 曖昧。 | `/` | | `/` がないリストページ。 | `/datasets` | | 名前空間のない正規リポジトリはサポートされていません。 | `/gpt2` | | ファイル/フォルダーの場所ではありません（`commits`、`discussions`、`settings`なども同様です）。 | `///commit/` | | コレクションはリポジトリではありません。 | `/collections//` | | Hostは認識されていないHugging Faceホストです。 | `https://example.com//` | ## Web URLのレンダリング [HfUri.to_url()](/docs/huggingface_hub/main/ja/package_reference/hf_uris#huggingface_hub.HfUri.to_url) は、URL のパースの逆操作であり、HF URI に対応するブラウザで閲覧可能な Web 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/main/ja/package_reference/hf_uris#huggingface_hub.parse_hf_uri) は中央集権的な URI パーサーです。純粋な文字列パーサーであり（ネットワーク呼び出しは行いません）、凍結された [HfUri](/docs/huggingface_hub/main/ja/package_reference/hf_uris#huggingface_hub.HfUri) データクラスを返します。 ```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/main/ja/package_reference/hf_uris#huggingface_hub.HfUri) は [HfUri.to_uri()](/docs/huggingface_hub/main/ja/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` は、マウント仕様（ローカルマウントパスと任意の `:ro`/`:rw` フラグを伴う HF URI）を解析し、凍結された `HfMount` データクラスを返します。内部では [parse_hf_uri()](/docs/huggingface_hub/main/ja/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/main/src/huggingface_hub/utils/_hf_uris.py#L79) **パラメータ:** type (`str`) : 'model'、'dataset'、'space'、'kernel'、'bucket' のいずれか。 id (`str`) : リポジトリ URI の場合はリポジトリ ID（'namespace/name'、例: 'my-org/my-model'）、バケット URI の場合はバケット ID（'namespace/name'）。 revision (`str`, *任意*) : URI内の'@'の後に指定されたリビジョンです。URLデコード済みです。リビジョンが指定されていない場合、またはバケットURI（リビジョンを持たない）の場合は'None'です。'refs/pr/10'や'refs/convert/parquet'のような特別なリファレンスはそのまま保持されます。 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/main/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/main/src/huggingface_hub/utils/_hf_uris.py#L155) **パラメータ:** endpoint (`str`, *任意*) : 使用するベースエンドポイントです。デフォルトは 'constants.ENDPOINT'（つまり 'https://huggingface.co'）です。 **戻り値:** `str` Web URL。 URIをHugging Faceの**Web URL**（ブラウザで開く形式）としてレンダリングします。 これは[parse_hf_uri()](/docs/huggingface_hub/main/ja/package_reference/hf_uris#huggingface_hub.parse_hf_uri)でURLをパースする操作の逆です。返されるURLは、以下を指します: - パスやリビジョンが設定されていない場合のリポジトリ / バケットのランディングページ; - リビジョンのみが設定されている場合のフォルダビューア ('/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 ホストに加えて、そのエンドポイント上の Web URL も認識されます。'hf://' URI には影響しません。 **戻り値:** [HfUri](/docs/huggingface_hub/main/ja/package_reference/hf_uris#huggingface_hub.HfUri) 解析されたURI。 **例外:** `HfUriError` - `HfUriError` -- URIが不正な場合（プレフィックスの欠落、無効な型、IDの欠落、サポートされていないURLルートなど）。 Hugging Face Hub URI（'hf://...'）または Hugging Face の Web URL を解析します。 HF URIは、Hugging Face Hub上の場所を識別するURI風の文字列です。完全な文法は以下の通りです。 ``` hf://[/][@][/] ``` 利便性のため、Hugging Face の**Web URL**(Web サイトからコピー & ペーストするもの)も受け入れられ、正規の 'hf://' 形式に正規化されます。例えば、'https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv' のような URL です。曖昧さのない 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/main/src/huggingface_hub/utils/_hf_uris.py#L207) **パラメータ:** source ([HfUri](/docs/huggingface_hub/main/ja/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/main/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/main/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) ```