如何使用 hf-cli 快速下载 Hugging Face 模型

在日常开发中，我们经常需要从 Hugging Face 平台下载模型，但由于网络原因，速度往往非常慢，甚至可能中断。为了解决这个问题，hf-cli 工具提供了一个高效下载 Hugging Face 模型的方式，支持国内镜像、断点续传以及网络容错，非常适合国内用户使用。

本文将详细介绍如何安装、配置和使用 hf-cli 工具快速下载 Hugging Face 模型。

1. hf-cli 工具简介

1.1 功能特色

•	国内镜像支持：默认使用国内镜像站（https://hf-mirror.com），速度大幅提升。
•	断点续传：支持网络中断后续传，节省时间和带宽。
•	简单易用：安装简单，命令友好，兼容 Hugging Face 的模型管理方式。
•	高效稳定：支持多线程下载，默认最大并发数为 10。

1.2 使用场景

•	快速下载 Hugging Face 模型或数据集。
•	遇到网络问题导致的下载失败或速度过慢。

2. 安装 hf-cli 工具

2.1 环境要求

确保您的系统已经安装了 Python（版本 ≥ 3.7）。

2.2 安装命令

使用 pip 安装：

pip install hf-cli

安装完成后，可以通过以下命令检查工具是否正常安装：

hf-cli --help

输出类似以下内容表示安装成功：

usage: hf-cli [-h] [--token TOKEN] [--username USERNAME] [--model-id MODEL_ID] [modelId]

3. 下载 Hugging Face 模型

以下以下载 openai-community/gpt2 模型为例，展示具体操作步骤。

3.1 基本下载

直接运行以下命令：

hf-cli openai-community/gpt2

模型会默认下载到当前目录下的 openai-community_gpt2 文件夹中。

3.2 模型需要授权

如果模型是受限访问的（如 Gated Repository），需要提供 Hugging Face 的 Access Token 和用户名：

hf-cli openai-community/gpt2 --token <your_hf_token> --username <your_username>

•	<your_hf_token>：从 Hugging Face Access Tokens 页面 获取。
•	<your_username>：您的 Hugging Face 用户名。

3.3 指定国内镜像

hf-cli 默认使用国内镜像 https://hf-mirror.com，无需手动配置。如果需要自定义镜像，可以设置环境变量：

export HF_ENDPOINT=“https://your-mirror-url”

设置完成后重新运行下载命令。

4. 验证下载结果

4.1 检查文件完整性

下载完成后，查看模型文件夹是否包含以下文件：

ls ./openai-community_gpt2

应看到如下文件：
• config.json
• pytorch_model.bin
• tokenizer.json
• vocab.json

4.2 测试模型运行

以下是一个简单的测试代码，验证模型是否正确下载并能正常工作：

from transformers import AutoTokenizer, AutoModelForCausalLM

# 加载本地模型和分词器
tokenizer = AutoTokenizer.from_pretrained("./openai-community_gpt2")
model = AutoModelForCausalLM.from_pretrained("./openai-community_gpt2")

# 测试生成文本
inputs = tokenizer("The future of AI is", return_tensors="pt")
outputs = model.generate(inputs["input_ids"], max_length=50)

# 输出结果
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

5. 常见问题

5.1 下载失败或中断

如果下载中断或失败，可以启用断点续传：

hf-cli openai-community/gpt2 --resume-download

5.2 提示权限不足

1.	检查模型是否需要授权访问（如 Gated Repository）。
2.	确保使用了正确的 Token 和用户名：

hf-cli openai-community/gpt2 --token <your_hf_token> --username <your_username>

5.3 下载速度慢

切换到其他国内镜像或检查网络连接：

export HF_ENDPOINT="https://your-backup-mirror-url"

6. 总结

hf-cli 是一款功能强大且简单易用的 Hugging Face 模型下载工具，特别适合国内开发者。通过国内镜像的支持和断点续传机制，我们可以快速、稳定地获取所需的模型或数据集，极大提升开发效率。

希望这篇文章能帮助您快速上手使用 hf-cli！如有问题，欢迎留言讨论。

更多学习内容，请关注我的 CSDN 博客！👍