HF URI

HF URI 是一种类似 URI 的字符串，用于标识 Hugging Face Hub 上的位置。在整个库和 CLI 中，hf://... 字符串用于指向：

模型、数据集、空间或内核仓库（可选地固定到某个修订版本）；
此类仓库中的文件或子文件夹;
bucket 或 bucket 内的子文件夹。

HF 挂载将 HF URI 与本地挂载路径以及可选的 :ro / :rw 标志封装在一起，供 Spaces 和 Jobs 卷使用。

本页记录了 HF URI 和 HF 挂载的规范语法。该库在所有位置都使用同一个解析器，因此在一个上下文中有效的 URI（例如 HfFileSystem）在另一个上下文中会被以相同的方式解析。

parse_hf_uri() 也接受 Hugging Face Web URL（例如 https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv），因此您可以直接从网站复制粘贴链接。请参阅下文中的 Web URL。

HF URI 语法

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

组件	必需	允许的值
`hf://`	是的	字面量协议前缀。
`<TYPE>/`	no	`models/`、`datasets/`、`spaces/`、`kernels/`、`buckets/`（复数形式）。
`<ID>`	是的	`<namespace>/<name>`
`@<REVISION>`	no	分支、标签、提交 SHA 或特殊引用（`refs/pr/N`、`refs/convert/...`）。仅限仓库。
`/<PATH>`	no	仓库或存储桶内的路径。

HF 挂载语法

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

挂载点是一个 HF URI，后跟 :<MOUNT_PATH> 以及可选的 :ro / :rw 标志。

组件	必需	允许的值
`<MOUNT_PATH>`	是的	绝对挂载路径（必须以`/`开头）。
`:ro` / `:rw`	no	只读 / 读写标志。

什么是 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`	不支持没有命名空间的规范仓库。
`hf://buckets/single-segment`	Bucket 必须始终为 `namespace/name`。
`hf://buckets/org/b@v1`	Buckets 不支持修订标记。
`hf://org/m@`, `hf://datasets/foo/bar@/x`	`@` 之后的修订版本为空。
`hf://a/b/c@v1`	仓库 ID 必须为 `namespace/name`，额外的段表示路径。
`hf://org/m:/`	挂载路径必须是非空的绝对路径。

Web 网址

为了方便起见，parse_hf_uri() 也接受从浏览器中复制粘贴的 Hugging Face 网页 URL。它们会被规范化为标准的 hf:// 格式，因此您可以直接将 URL 粘贴到 CLI 或库中，即可“开箱即用”：

>>> 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 短域名、staging 主机以及自定义 HF_ENDPOINT 的主机）的 URL 会被识别，无论是否带有 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>`
仓库内的文件（下载路由）	`/<ns>/<name>/resolve/<rev>/<path>`
仓库内的文件（原始路由）	`/<ns>/<name>/raw/<rev>/<path>`
仓库内的文件（blame 路由）	`/<ns>/<name>/blame/<rev>/<path>`
Bucket	`/buckets/<ns>/<name>`
桶内的文件（桶不支持版本控制）	`/buckets/<ns>/<name>/resolve/<path>`
存储桶内的文件夹	`/buckets/<ns>/<name>/tree/<path>`

修订版本取自 blob/resolve/raw/tree/blame 之后的单个片段。特殊引用（refs/pr/N、refs/convert/...）即使包含 / 也会被优先匹配；其他包含 / 的分支/标签名称必须进行 URL 编码（feature%2Ffoo）。

未解析的 URL

当 URL 存在歧义或未指向具体的 Hub 位置时，它会被拒绝（系统绝不会进行猜测）：

以下路径同样未显示主机名，但最后一行除外，因为该行中主机本身即为拒绝原因。

原因	URL 路径
单段 URL：用户/组织页面、列表页面或规范仓库——存在歧义。	`/<username>`
列表页面，没有 `<ns>/<name>`。	`/datasets`
不支持没有命名空间的规范仓库。	`/gpt2`
不是文件/文件夹位置（`commits`、`discussions`、`settings` 等也是如此）。	`/<ns>/<name>/commit/<rev>`
集合不是仓库。	`/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 数据类。

>>> 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 解析挂载规范（包含本地挂载路径以及可选的 :ro/:rw 标志的 HF URI），并返回一个冻结的 HfMount 数据类。其底层使用了 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'

参考

类 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) — 对于仓库 URI，为仓库 id（‘namespace/name’，例如 ‘my-org/my-model’）；对于存储桶 URI，为存储桶 id（‘namespace/name’）。
revision (str, 可选) — URI 中 ’@’ 之后指定的修订版本，已进行 URL 解码。如果未指定修订版本，或者对于 bucket URI（其从不携带修订版本），则为 ‘None’。像 ‘refs/pr/10’ 和 ‘refs/convert/parquet’ 这样的特殊引用将按原样保留。
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, 可选) — 要使用的基础端点。默认为 ‘constants.ENDPOINT’（即 ‘https://huggingface.co’）。

返回值

str

Web 网址。

将 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 端点（例如自托管或代理的 Hub，如 ‘https://hub.my-company.com’ 或 ‘http://localhost:8080/hf’）。提供该参数后，除默认的 Hugging Face 主机外，该端点上的 Web URL 也会被识别。对 ‘hf://’ URI 无影响。

返回值

HfUri

解析后的 URI。

引发

HfUriError

HfUriError — 如果 URI 格式不正确（缺少前缀、类型无效、缺少 id、不支持的 URL 路由等）。

解析 Hugging Face Hub URI（‘hf://…’）或 Hugging Face 网页 URL。

HF URI 是一种类似 URI 的字符串，用于标识 Hugging Face Hub 上的位置。完整的语法如下：

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

类 huggingface_hub.utils.HfMount

< source >

( source: HfUrimount_path: strread_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，搭配本地挂载路径以及可选的只读标志。

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

Web 网址

支持的 URL 格式

未解析的 URL

渲染网页 URL

在 Python 中解析

解析 URI

解析挂载

参考

类 huggingface_hub.HfUri

to_uri

to_url

huggingface_hub.parse_hf_uri

类 huggingface_hub.utils.HfMount

to_uri

huggingface_hub.utils.parse_hf_mount