如何在Linux系统中下载Hugging Face模型及镜像加速

在Linux系统中下载Hugging Face模型，可以通过以下方法实现。

使用官方命令行工具

步骤：

1. 安装依赖库

   Bash

   pip install -U huggingface_hub

2. 配置国内镜像加速 为避免连接超时问题，需设置镜像源（如hf-mirror.com）：

   Bash

   echo 'export HF_ENDPOINT="https://hf-mirror.com"' >> ~/.bashrc

   # 写入环境变量

   source ~/.bashrc

   # 立即生效

   若仅需在当前会话中临时使用镜像源，直接运行 export 命令即可：

   Bash

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

   此方式无需重启服务器，但变量会在终端关闭或服务器重启后失效

   验证配置是否生效

   运行以下命令检查变量是否已加载：

   Bash

   echo $HF_ENDPOINT

   若输出 https://hf-mirror.com，则配置成功

   启用 hf-transfer 加速模块（官方推荐）

   1. 1. 安装加速模块
         Bash

         pip install -U hf-transfer
      2. 设置环境变量
         Bash

         export HF_HUB_ENABLE_HF_TRANSFER=1

         # Linux/MacOS


         $env:HF_HUB_ENABLE_HF_TRANSFER=1

         # Windows PowerShell
   2. 下载不稳定中途失败解决：

   3. 清理缓存后重试

      Bash

      rm -rf ~/.cache/huggingface/hub/*

      # 删除缓存目录（谨慎操作）

      适用场景：怀疑缓存文件损坏或冲突时使用

   优化 hf_transfer 使用

   1. 更新工具版本

      Bash

      pip install -U hf-transfer huggingface_hub
      • 新版可能修复了部分稳定性问题 。

   2. 限制并发线程

      Bash

       huggingface-cli download --num-workers 2 模型ID

      # --num-workers参数减少并发数
      • 高并发可能导致某些网络环境不稳定

3. 下载模型

   Bash

   huggingface-cli download --resume-download {模型ID} --local-dir {目标目录}
   • • • 示例：下载RoBERTa模型
         Bash

         huggingface-cli download --resume-download FacebookAI/roberta-base --local-dir ./roberta-base
4. 仅下载单个文件

如果只需要下载特定文件（如 diffusion_pytorch_model.safetensors）：

• 关键参数：
  • --include：指定文件名或通配符（如 *.safetensors）
  • --local-dir：指定本地存储路径（若目录不存在会自动创建）。