使用 huggingface-cli 下载 Hugging Face 模型的步骤如下，结合国内网络优化策略和常见问题解决方案：

---

1. 安装工具

首先安装 huggingface_hub 库：

pip install -U huggingface_hub 

安装后可通过 huggingface-cli --help 验证是否成功。

---

2. 配置镜像加速（国内用户必选）

为提升下载速度，需设置国内镜像源：

• Linux/macOS：在终端执行：

  export HF_ENDPOINT=https://hf-mirror.com 

• Windows：在 PowerShell 执行：

  $env:HF_ENDPOINT = "https://hf-mirror.com" 

建议将此配置写入 ~/.bashrc 或系统环境变量以持久生效。

---

3. 登录账号（可选）

若需下载私有模型或上传文件，需登录账号：

huggingface-cli login 

输入从 Hugging Face 官网生成的 Token（Settings → Access Tokens）。

---

4. 基础下载命令

通用下载命令格式：

huggingface-cli download --resume-download <模型名称> --local-dir <本地路径> --local-dir-use-symlinks False 

• 参数说明：
  • --resume-download：支持断点续传。
  • --local-dir-use-symlinks False：禁用符号链接，直接保存文件（避免缓存冗余）。
  • --cache-dir：自定义缓存目录（默认 ~/.cache/huggingface）。

示例：下载 deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B 到本地目录 D:\models：

huggingface-cli download --resume-download deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B --local-dir .\models\DeepSeek-R1-Distill-Qwen-1.5B --local-dir-use-symlinks False 

---

5. 高级用法

• 代理设置（若需科学上网）：

  set HTTP_PROXY=http://127.0.0.1:1080 set HTTPS_PROXY=http://127.0.0.1:1080 

• 多线程加速：结合 hf_transfer 或 aria2 工具提升速度（需额外安装）。
• 仅下载部分文件：通过 --include 或 --exclude 参数筛选文件。

---

6. 常见问题

• 下载中断：重新执行相同命令会自动续传。
• 模型引用：下载后可直接通过模型名称加载（如 AutoModel.from_pretrained("gpt2")），工具会自动关联本地路径。
• 数据集下载：添加 --repo-type dataset 参数。

---

参考配置示例

若需统一管理模型路径，可设置环境变量：

export HF_HOME=/path/to/custom/directory # 自定义模型存储根目录 

此配置将覆盖默认缓存路径。

---

通过上述步骤，可高效下载并管理 Hugging Face 模型。若需进一步优化速度，可参考镜像站手动下载或结合多线程工具（如 hfd 脚本）。