# HF URI

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

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

*HF 挂载*将 HF URI 与本地挂载路径以及可选的 `:ro` / `:rw` 标志封装在一起，供 [Spaces](../guides/manage-spaces) 和 [Jobs](../guides/jobs) 卷使用。

本页记录了 HF URI 和 HF 挂载的规范语法。该库在所有位置都使用同一个解析器，因此在一个上下文中有效的 URI（例如 [HfFileSystem](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_file_system#huggingface_hub.HfFileSystem)）在另一个上下文中会被以相同的方式解析。

[parse_hf_uri()](/docs/huggingface_hub/v2.4.0/zh/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://[<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 挂载语法

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

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

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

## 什么是 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，必须包含 `<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()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_uris#huggingface_hub.parse_hf_uri) 也接受从浏览器中复制粘贴的 Hugging Face 网页 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` 短域名、staging 主机以及自定义 `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 路径                                       |
| -------------------------------------------------------------- | ---------------------------------------------- |
| 模型仓库                                               | `/<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()](/docs/huggingface_hub/v2.4.0/zh/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/<rev>`）；对于仓库文件，指向文件查看器（`/blob/<rev>/<path>`，修订版本默认为 `main`）；对于存储桶文件，指向树路由（`/tree/<path>`）。路径中的特殊字符（空格、`#` 等）会进行百分号编码。传入 `endpoint=...` 以指定自定义主机。

## 在 Python 中解析

### 解析 URI

[parse_hf_uri()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_uris#huggingface_hub.parse_hf_uri) 是集中式的 URI 解析器。它是一个纯字符串解析器（不发起网络请求），并返回一个冻结的 [HfUri](/docs/huggingface_hub/v2.4.0/zh/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/v2.4.0/zh/package_reference/hf_uris#huggingface_hub.HfUri) 可以通过 [HfUri.to_uri()](/docs/huggingface_hub/v2.4.0/zh/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/v2.4.0/zh/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`) : 对于仓库 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/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`

Web 网址。

将 URI 渲染为 Hugging Face **网页 URL**（即在浏览器中打开的那种）。

这是使用 [parse_hf_uri()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_uris#huggingface_hub.parse_hf_uri) 解析 URL 的逆操作。返回的 URL 指向：

- 未设置路径或修订版本时，仓库 / 存储桶的落地页；
- 仅设置修订版本时，文件夹查看器（'/tree/'）；
- 用于仓库文件的文件查看器（/blob//）（revision 默认为 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 端点（例如自托管或代理的 Hub，如 'https://hub.my-company.com' 或 'http://localhost:8080/hf'）。提供后，除默认的 Hugging Face 主机外，该端点上的 Web URL 也会被识别。对 'hf://' URI 无影响。

**返回：** [HfUri](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_uris#huggingface_hub.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。

示例：
```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/zh/package_reference/hf_uris#huggingface_hub.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[[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://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[: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)
```