Hugging Face 模型下载、代理与镜像站配置指南

本笔记记录了使用新版 hf 命令行工具下载受限模型（以 pyannote/speaker-diarization-3.1 为例）的完整流程，以及 Windows / Linux / macOS 环境下的代理配置与国内镜像站使用方法。

一、 Hugging Face 新版 CLI 工具说明

Hugging Face 已将传统的 huggingface-cli 命令行工具废弃，替换为更简短的 hf 命令。

• 登录命令：hf auth login
• 下载模型命令：hf download <repo_id> --local-dir <dir_name>

二、 受限模型（Gated Models）下载流程

下载如 pyannote/speaker-diarization-3.1 等需要权限申请的模型时，必须按以下顺序操作：

步骤 1：网页端同意模型使用协议

直接使用 Token 登录无法下载受限模型，需先在浏览器完成授权：

1. 登录 Hugging Face 账号，访问 pyannote/speaker-diarization-3.1，点击同意协议（Agree and accept）。
2. 访问该模型依赖的分割模型 pyannote/segmentation-3.0，同样点击同意协议。
3. 验证：刷新页面，能够直接查看文件列表（Files and versions）即代表权限获取成功。

步骤 2：生成 Token 并登录 CLI

1. 在 Hugging Face 个人设置的 Settings -> Access Tokens 中新建一个类型为 read 的 Token。

2. 在 CMD 中运行登录命令：

   hf auth login
   

3. 按提示输入生成的 Token。登录成功后，Token 将保存在本地缓存目录（C:\Users\<用户名>\.cache\huggingface\token）。

步骤 3：下载模型到本地目录

在终端执行下载命令：

hf download pyannote/speaker-diarization-3.1 --local-dir speaker-diarization

三、 使用国内镜像站加速（无需代理）

https://hf-mirror.com 是国内常用的 Hugging Face 镜像站。通过设置环境变量 HF_ENDPOINT，可以直连加速下载模型。

1. 启用镜像站

根据所使用的终端环境选择对应命令：

• Windows CMD：

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

• Windows PowerShell：

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

• Linux / macOS：

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

设置完成后，直接运行 hf download 或 Python 代码即可自动通过镜像站下载。

2. 取消使用镜像站（恢复官方源）

• Windows CMD：

  set HF_ENDPOINT=
  

• Windows PowerShell：

  Remove-Item Env:\HF_ENDPOINT
  

• Linux / macOS：

  unset HF_ENDPOINT
  

四、 Windows 11 CMD 代理配置与管理

当不使用镜像站而直接访问官方源时，可在 CMD 中配置临时 HTTP/HTTPS 代理。

1. 开启代理

在当前 CMD 窗口中运行以下命令（以代理端口 127.0.0.1:7890 为例）：

set http_proxy=[http://127.0.0.1:7890](http://127.0.0.1:7890)
set https_proxy=[http://127.0.0.1:7890](http://127.0.0.1:7890)

注意事项：

• set 命令中 = 两侧切勿保留空格。
• 若使用 SOCKS5 协议，可设置为 socks5://127.0.0.1:10808 形式。

2. 单条命令临时挂载代理

仅针对单条命令生效，不影响上下文环境：

set https_proxy=[http://127.0.0.1:7890](http://127.0.0.1:7890) && hf auth login

3. 关闭代理

在当前 CMD 窗口中将变量设置为空值即可移除代理：

set http_proxy=
set https_proxy=

补充：通过 set 设置的环境变量仅在当前终端窗口生存期内有效，直接关闭当前窗口亦可恢复默认状态。

五、 常见报错与排查

• 报错信息：Error: Access denied. This repository requires approval.
• 原因：未在 Hugging Face 网页端完成受限模型的协议授权，或依赖模型（如 pyannote/segmentation-3.0）未授权。
• 解决办法：重新在浏览器登录账号并同意所有关联模型的用户协议后再试。
• 报错信息：Still waiting to acquire lock on...
• 原因：上次下载意外中断导致的锁文件未释放。
• 解决办法：删除对应目录下的 .cache 锁文件夹后重新运行下载。