[Python] Python操作Hugging Face Hub详解：模型下载、数据集管理与API实战

Hugging Face Hub 是一个包含模型、数据集和演示应用（Spaces）的庞大社区平台。huggingface-hub 库提供了与 Hub 交互的完整 Python 客户端，本教程将详细介绍其核心功能。

安装与基础配置

通过 pip 安装官方库：

pip install huggingface-hub

对于模型推理等任务，你可能需要额外安装 huggingface-hub[inference]。

安装后，你需要一个访问令牌（Token）来进行写操作（如上传）。登录 Hugging Face，在设置中生成令牌，然后在终端配置：

huggingface-cli login

在代码中，你也可以通过环境变量 HF_TOKEN 或使用 login 函数来设置令牌。

模型下载与管理

huggingface-hub 库最常用的功能之一是下载模型文件。

下载单个文件

使用 hf_hub_download 函数可以精确下载 Hub 上的任意文件。你需要指定仓库ID、文件名，并可选择版本（通过 revision 参数指定分支或提交哈希）。

from huggingface_hub import hf_hub_download

file_path = hf_hub_download(
    repo_id="google/flan-t5-base",
    filename="config.json",
    revision="main"
)
print(f"文件已下载至：{file_path}")

下载整个仓库

若要下载整个模型仓库（包括所有文件），可以使用 snapshot_download 函数。它支持通过 ignore_patterns 参数过滤文件类型，例如跳过 .h5 或 .bin 文件以节省带宽。

from huggingface_hub import snapshot_download

snapshot_path = snapshot_download(
    repo_id="google/flan-t5-base",
    ignore_patterns=["*.h5", "*.ot", "*.msgpack"]
)
print(f"仓库快照已下载至：{snapshot_path}")

从代码中直接加载模型

该库与 transformers、diffusers、datasets 等库深度集成。通常你可以直接使用那些库的 from_pretrained 方法，它们内部会自动处理下载和缓存。huggingface-hub 为此提供了底层支持。

from transformers import AutoModelForSeq2SeqLM, AutoTokenizer

model = AutoModelForSeq2SeqLM.from_pretrained("google/flan-t5-base")
tokenizer = AutoTokenizer.from_pretrained("google/flan-t5-base")

数据集操作

Hub 上同样托管着海量的数据集，你可以方便地下载和使用它们。

下载数据集文件

与下载模型文件类似，你可以使用相同的 hf_hub_download 函数。

from huggingface_hub import hf_hub_download

data_file = hf_hub_download(
    repo_id="lhoestq/demo1",
    filename="data/train-00000-of-00001.parquet",
    repo_type="dataset"
)
print(f"数据集文件：{data_file}")

注意，当操作数据集仓库时，需要显式指定 repo_type="dataset"。

使用 datasets 库加载

更常见的方式是使用 datasets 库，它能将数据集加载为易于操作的格式。

from datasets import load_dataset

dataset = load_dataset("lhoestq/demo1", split="train")
print(dataset[0])

上传文件与创建提交

除了下载，你还可以上传文件到你的仓库，或向他人仓库提交 Pull Request。

上传到你的仓库

如果你有仓库的写入权限，可以直接上传文件。

from huggingface_hub import HfApi

api = HfApi()
api.upload_file(
    path_or_fileobj="/local/path/to/your/file.txt",
    path_in_repo="folder/file.txt",
    repo_id="your-username/your-repo-name"
)

创建 Pull Request

如果你想向一个你没有直接写入权限的仓库贡献文件，可以创建 Pull Request。

from huggingface_hub import create_commit, CommitOperationAdd

operations = [
    CommitOperationAdd(
        path_in_repo="awesome/model.safetensors",
        path_or_fileobj="/local/path/to/model.safetensors"
    )
]

commit = create_commit(
    repo_id="owner/repo-name",
    operations=operations,
    commit_message="Add my awesome model",
    create_pr=True  # 关键参数，创建PR而非直接推送
)
print(f"PR 已创建：{commit.pr_url}")

Inference API 客户端

Hugging Face 为许多模型提供了免费的 Inference API。huggingface-hub 库包含了一个易用的同步客户端。

from huggingface_hub import InferenceClient

client = InferenceClient()

# 文本生成
response = client.text_generation(
    model="google/flan-t5-base",
    prompt="Translate English to German: How are you?"
)
print(response)

# 对话 (Chat)
messages = [{"role": "user", "content": "What is AI?"}]
response = client.chat_completion(
    model="microsoft/DialoGPT-medium",
    messages=messages,
    max_tokens=50
)
print(response.choices[0].message.content)

对于异步应用，可以使用 AsyncInferenceClient。

仓库与文件信息查询

在下载或使用前，你可能想先查看仓库里有什么。

from huggingface_hub import list_repo_files, list_repo_refs, model_info

# 列出仓库所有文件
files = list_repo_files(repo_id="google/flan-t5-base")
print("文件列表：", files[:5])

# 列出所有分支和标签
refs = list_repo_refs(repo_id="google/flan-t5-base")
print("分支：", [ref.name for ref in refs.branches])
print("标签：", [tag.name for tag in refs.tags])

# 获取模型的详细信息
info = model_info("google/flan-t5-base")
print(f"模型ID: {info.modelId}")
print(f"下载次数: {info.downloads}")
print(f"许可证: {info.cardData.get('license')}")

大文件与 Git LFS

Hub 使用 Git 和 Git LFS（大文件存储）管理仓库。对于非常大的文件（如模型权重），你需要确保本地已安装 Git LFS。

• 上传大文件：库会自动检测并使用 Git LFS 处理大文件。
• 下载大文件：snapshot_download 默认会获取 LFS 文件。如果只想要小文件（如配置文件），可以设置 allow_patterns=["*.json", "*.py", "*.txt"] 或 ignore_patterns=["*.safetensors", "*.bin", "*.pth"]。

通过本教程介绍的核心功能，你应该能熟练使用 Python 客户端库与 Hugging Face Hub 进行交互，高效地下载模型与数据集、管理仓库内容，并利用 Inference API 快速验证想法。结合 Python 生态中的其他库，如 Transformers 或 Datasets，你将能更顺畅地开展 人工智能 项目。