Hub documentation
Bucket 集成
Bucket 集成
Storage Buckets 可以通过 hf://buckets/ 路径从许多 Python 数据库中读取和写入，其底层由 huggingface_hub 文件系统接口提供支持。
有关底层访问机制——挂载、卷挂载和 fsspec——请参阅 访问模式。
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")Dask
Dask 以惰性方式读取和写入数据，每个文件对应一个分区，因此您可以直接从存储桶中处理比内存更大的数据集：
import dask.dataframe as dd
df = dd.read_parquet("hf://buckets/username/my-bucket/data/")
df.to_parquet("hf://buckets/username/my-bucket/output/")有关更多信息，请参阅 Hub 上的 Dask。
Daft
Daft 原生支持 hf://buckets/ 路径，并默认启用 Xet 加速读取：
import daft
from daft.io import IOConfig, HuggingFaceConfig
from huggingface_hub import get_token
io_config = IOConfig(hf=HuggingFaceConfig(token=get_token()))
df = daft.read_parquet("hf://buckets/username/my-bucket/data.parquet", io_config=io_config)PyArrow
import pyarrow.parquet as pq
table = pq.read_table("hf://buckets/username/my-bucket/data.parquet")PySpark
在已安装 pyspark_huggingface 的情况下：
df = (
spark.read.format("huggingface")
.option("data_files", '["data.parquet"]')
.load("buckets/username/my-bucket")
)有关更多信息，请参阅 Hub 上的 PySpark。
🤗 Datasets
from datasets import load_dataset
ds = load_dataset("buckets/username/my-bucket", data_files=["data.parquet"])Inspect AI
Inspect AI 可以直接将评估日志写入存储桶——将其日志目录指向 hf://buckets/ 路径（需要 huggingface_hub>=1.6.0）。请先创建存储桶并完成身份验证（Inspect 不会替你创建）：
hf auth login
hf buckets create username/my-bucket --private
export INSPECT_LOG_DIR=hf://buckets/username/my-bucket/eval-logs
inspect eval popularity.py --model openai/gpt-4
inspect view有关详细信息，请参阅 Inspect 的 eval 日志指南。
SkyPilot
SkyPilot 可在 20 多家云、Kubernetes 以及本地环境中运行 AI 工作负载，并支持将 Hugging Face 存储作为后端——因此一个存储桶可在所有云中读取，无需为每个云单独复制。在 file_mounts 条目中设置 store: hf，即可将存储桶以读写方式挂载，或将仓库以只读方式挂载：
# qwen-sft.yaml — launch anywhere: sky launch qwen-sft.yaml --infra aws|gcp|...
resources:
accelerators: H100:1
file_mounts:
/base-model:
source: hf://Qwen/Qwen2.5-3B # model repo, read-only
store: hf
mode: MOUNT
/data:
source: hf://datasets/username/my-data@v1.0 # dataset repo, pinned to a tag, read-only
store: hf
mode: MOUNT
/checkpoints:
source: hf://buckets/username/qwen-sft # bucket, read-write — checkpoints sync back
store: hf
mode: MOUNT
run: |
python train.py --model /base-model --output_dir /checkpoints只需认证一次 - hf auth login（或 export HF_TOKEN=<your-token>）就是 SkyPilot 所需的全部。它会将您的本地 Hugging Face 令牌转发到每个云，因此存储桶和仓库挂载会自动完成身份验证：
pip install "skypilot[huggingface]"
hf auth login # or: export HF_TOKEN=<your-token>
sky launch qwen-sft.yaml如果您的 run 代码会拉取受门禁控制的仓库，请在启动命令中添加 --secret HF_TOKEN，以便同时将该令牌作为环境变量暴露。
MOUNT和MOUNT_CACHED在hf上的行为完全一致，它们使用 hf-mount FUSE 后端，该后端需要基础镜像的 glibc 版本 ≥ 2.34 以及/dev/fuse。裸虚拟机云环境同时提供这两者。SkyPilot 默认的 Kubernetes 镜像自带的 glibc 版本较旧，因此请设置更新的image_id（例如docker:mirror.gcr.io/ubuntu:22.04）。有关当前的环境要求，请参阅 SkyPilot 存储文档。
请参阅 SkyPilot + Hugging Face 存储博客文章，了解基准测试和完整操作指南。
文件系统操作
对于直接的文件操作，huggingface_hub 提供了一个预实例化的 文件系统对象，即 hffs：
from huggingface_hub import hffs
with hffs.open("buckets/username/my-bucket/hello.txt", "w") as f:
f.write("Hello world!")
hffs.cp("buckets/username/my-bucket/hello.txt", "buckets/username/my-bucket/hello2.txt")
hffs.rm("buckets/username/my-bucket/hello2.txt")
files = hffs.ls("buckets/username/my-bucket")
text_files = hffs.glob("buckets/username/my-bucket/*.txt")DuckDB
DuckDB 2.0 及更高版本通过 httpfs 扩展（以及用于写入的 hf 扩展）原生读取 hf://buckets/ 路径，支持从 CLI 和所有客户端使用：
SELECT * FROM 'hf://buckets/username/my-bucket/data/**/*.parquet' LIMIT 10;
COPY tbl TO 'hf://buckets/username/my-bucket/out.parquet';有关私有存储桶和旧版 DuckDB，请参阅 使用 DuckDB 查询。
其他语言
OpenDAL 为 Rust、Java、Go、JavaScript 等语言提供了类似的文件系统接口。
即将推出
对更多库（包括 Polars 和 WebDataset）的原生 hf:// URL 支持正在开发中。在此期间，所有这些库目前都可以通过 S3 兼容 API 正常工作。