Hub Python 函式庫文件
HF URI
並獲得增強的文件體驗
開始使用
HF URI
HF URI 是一種類似 URI 的字串，用於識別 Hugging Face Hub 上的位置。在整個函式庫與 CLI 中，hf://... 字串用於指向：
- 模型、資料集、空間 (Space) 或核心 (Kernel) 儲存庫（可選定特定修訂版本）；
- 此類儲存庫內的檔案或子資料夾；
- 一個 儲存區 (bucket) 或儲存區內的子資料夾。
HF 掛載 (HF mount) 將 HF URI 與本機掛載路徑以及選用的 :ro / :rw 旗標包裝在一起，供 Spaces 和 Jobs 磁碟區使用。
本頁面記載了 HF URI 和 HF 掛載的規範語法。函式庫中到處使用相同的解析器，因此在一個情境中有效的 URI（例如 HfFileSystem），在另一個情境中的解析方式也是相同的。
HF URI 語法
hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]
| 組件 | 必要 | 允許的值 |
|---|---|---|
hf:// | 有 | 字面協定前綴。 |
<TYPE>/ | 無 | models/, datasets/, spaces/, kernels/, buckets/（複數）。 |
<ID> | 有 | <命名空間>/<名稱> |
@<REVISION> | 無 | 分支、標籤、提交 SHA 或特殊參考 (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, huggingface.co/org/m | 缺少 hf:// 協定前綴。 |
hf://dataset/org/m, hf://model/org/m | 禁止使用單數類型的形式，請使用複數（datasets/, …）。 |
hf://datasets, hf://buckets/ | 僅類型前綴不是有效的 URI，需要 <ID>。 |
hf://gpt2, hf://datasets/squad | 不支援規範儲存庫（沒有命名空間）。 |
hf://buckets/single-segment | 儲存區必須始終為 命名空間/名稱。 |
hf://buckets/org/b@v1 | 儲存區不支援修訂版本標記。 |
hf://org/m@, hf://datasets/foo/bar@/x | @ 後面沒有修訂版本。 |
hf://a/b/c@v1 | 儲存庫 ID 必須為 命名空間/名稱，額外的區段為路徑。 |
hf://org/m:/ | 掛載路徑必須為非空的絕對路徑。 |
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 欄位。當需要區分儲存庫 URI 和儲存區 URI 時，請使用布林屬性 is_repo 和 is_bucket。
解析掛載
parse_hf_mount 會解析掛載規範（一個帶有本機掛載路徑和可選 :ro/:rw 旗標的 HF URI），並回傳一個凍結的 HfMount 資料類別。它在底層使用 parse_hf_uri()。
>>> from huggingface_hub 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
< 原始碼 >( type: typing.Literal['model', 'dataset', 'space', 'kernel', 'bucket'] id: str revision: str | None = None path_in_repo: str = '' _raw: str | None = None )
參數
- type (
str) — 下列其中之一：‘model’、‘dataset’、‘space’、‘kernel’ 或 ‘bucket’。 - id (
str) — 儲存庫 URI 的儲存庫 ID（‘命名空間/名稱’，例如 ‘my-org/my-model’），或儲存區 URI 的儲存區 ID（‘命名空間/名稱’）。 - revision (
str, 選用) — URI 中 ’@’ 後面指定的修訂版本，經過 URL 解碼。若未指定修訂版本，或對於儲存區 URI（從不帶有修訂版本），則為 ‘None’。像 ‘refs/pr/10’ 和 ‘refs/convert/parquet’ 這樣的特殊參考會原樣保留。 - path_in_repo (
str) — 儲存庫或儲存區內的路徑。若 URI 指向根目錄，則為空字串。
Hugging Face Hub URI (‘hf://...’) 的解析表示。
huggingface_hub.parse_hf_uri
( uri: str ) → HfUri
參數
返回
解析後的 URI。
引發
HfUriError
HfUriError— 若 URI 格式錯誤（缺少前綴、無效類型、缺少 ID 等）。
解析 Hugging Face Hub URI (‘hf://...’)。
請參閱 ‘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')class huggingface_hub.utils.HfMount
< 原始碼 >( source: HfUri mount_path: str read_only: bool | None = None _raw: str | None = None )
參數
- source (HfUri) — 解析後的 HF URI，識別要掛載的 Hub 資源。
- mount_path (
str) — 本機掛載路徑（始終以 ’/’ 開頭）。 - read_only (
bool, 選用) — 若掛載以 ‘:ro’ 結尾則為 True，若以 ‘:rw’ 結尾則為 False，若未提供旗標則為 ‘None’。
與本機掛載路徑和選用唯讀旗標配對的 HF URI。
huggingface_hub.utils.parse_hf_mount
< 原始碼 >( mount_str: str ) → HfMount
解析 HF 掛載規範 (‘hf://…:<MOUNT_PATH>[:ro|:rw]’)。
掛載規範是一個 HF URI 後接本機掛載路徑和選用的唯讀/可讀寫旗標。
請參閱 ‘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)