访问模式

除了 CLI 和 Python SDK，还有多种方式可以从现有工具和工作流中访问存储桶数据。

选择访问方法

对于使用 bucket 作为后端的工具（SkyPilot、Inspect 等），请参阅 集成。若要在不轮询 bucket 的情况下保持客户端与 bucket 同步，请参阅 跟踪更改。

挂载为本地文件系统

hf-mount 允许你通过 NFS（推荐）或 FUSE 将存储桶（以及仓库）挂载为本地文件系统。文件采用惰性获取——只有你的代码实际读取的字节才会触发网络请求。

使用 Homebrew 安装：

brew install hf-mount

挂载存储桶：

hf-mount start bucket username/my-bucket /mnt/data

挂载完成后，任何读取或写入文件的工具都可以与您的存储桶配合使用——例如 pandas、DuckDB、vLLM、训练脚本、shell 命令等。

Buckets 以读写方式挂载；repos 为只读。有关后端选项、缓存和写入模式的完整文档，请参阅 hf-mount 仓库。

作业和空间中的卷挂载

Jobs 和 Spaces 中的卷挂载与 hf-mount 的原理相同，由平台为您管理——无需额外配置。存储桶默认以读写方式挂载。

hf jobs run -v hf://buckets/username/my-bucket:/data python:3.12 python script.py

任务还可以将本地目录作为卷源（-v ./training-data:/data）：该目录会同步到您的私有 jobs-artifacts 存储桶并从中挂载，因此增量重新同步和输出拉取均可免费实现。

有关完整的卷挂载语法和 Python API，请参阅 Jobs 配置文档 和 Spaces 卷挂载指南。

使用 DuckDB 进行查询

DuckDB 2.0 及更高版本通过 httpfs 扩展（读取）或 hf 扩展（读写）原生支持 hf://buckets/ 路径。在 DuckDB CLI 或任何客户端中，安装并加载 httpfs，然后查询存储桶：

INSTALL httpfs;
LOAD httpfs;

SELECT * FROM 'hf://buckets/username/my-bucket/data.parquet' LIMIT 10;

Glob 模式与数据集中的用法相同，例如 'hf://buckets/username/my-bucket/data/**/*.parquet'。Bucket 不支持版本控制，因此 @revision 语法不适用于 bucket 路径。httpfs 仅支持读取；若要将查询结果写入 bucket，请加载 hf 扩展（见下文）。

私有存储桶：首先创建一个 Hugging Face 密钥。它会从 hf auth login 或 HF_TOKEN 环境变量中获取令牌：

CREATE SECRET hf (TYPE huggingface, PROVIDER credential_chain);

向 Hugging Face 写入需要 hf 扩展：

SET allow_extension_repositories = 'allowed';
CREATE OR REPLACE EXTENSION REPOSITORY hf_repo WITH PREFIX 'https://hf.co/buckets/duckdb-extensions/builds/resolve';
INSTALL hf FROM hf_repo;
LOAD hf FROM hf_repo;

COPY tbl TO 'hf://buckets/username/my-bucket/out.parquet';

在 DuckDB 1.x 中，httpfs 无法识别 hf://buckets/ 路径。请改为从 Python 中注册 HfFileSystem，或从 CLI 及其他客户端使用 S3 兼容 API。

Python 数据工具

HfFileSystem 通过 hf://buckets/ 路径提供与 fsspec 兼容的存储桶访问。任何支持 fsspec 的 Python 库都可以直接读取和写入存储桶数据。

pandas：

import pandas as pd

df = pd.read_parquet("hf://buckets/username/my-bucket/data.parquet")
df.to_parquet("hf://buckets/username/my-bucket/output.parquet")

有关 hf:// 路径和支持的操作的更多信息，请参阅 HfFileSystem 指南 和 Buckets Python 指南。