如何配置huggingface的镜像源
时间: 2025-05-25 20:22:27 浏览: 152
### 配置 Hugging Face 的镜像源以加速模型下载
为了提升在国内访问 Hugging Face 平台的速度并优化模型下载体验,可以通过以下几种方式进行配置:
#### 方法一:通过环境变量配置
可以在终端中临时设置 `HF_ENDPOINT` 环境变量来指向国内的镜像站点。例如:
```bash
export HF_ENDPOINT=https://hf-mirror.com
```
此命令仅在当前会话有效。如果希望永久生效,可以将其添加至用户的 `.bashrc` 文件中[^1]。
编辑 `.bashrc` 文件的方式如下:
```bash
vim ~/.bashrc
```
在文件末尾追加以下内容:
```bash
export HF_ENDPOINT=https://hf-mirror.com
```
保存后执行以下命令使更改立即生效:
```bash
source ~/.bashrc
```
#### 方法二:通过 Python 脚本动态修改
在 Python 脚本中可以直接设置环境变量,并结合 `huggingface_hub` 库实现登录和下载功能。以下是具体代码示例:
```python
import os
from huggingface_hub import login, hf_hub_download
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'
login(token="你的Token")
# 下载模型或数据集
model_path = hf_hub_download(
repo_id='openai-community/gpt2-medium',
filename='pytorch_model.bin',
local_dir='/path/to/your/directory',
resume_download=True,
token="你的Token"
)
print(f"Model downloaded to {model_path}")
```
其中,`token` 是用户的身份验证令牌,可通过 Hugging Face 官网个人账户页面获取[^2]。
#### 方法三:使用 `pip` 和清华 TUNA 源安装依赖
为了避免因网络问题导致的包管理工具无法正常工作的情况,建议优先使用清华大学开源软件镜像站作为 PyPI 的索引源。安装相关依赖时可指定该源地址:
```bash
pip install -U huggingface_hub hf_transfer -i https://pypi.tuna.tsinghua.edu.cn/simple
```
#### 方法四:利用 `huggingface-cli` 工具
对于需要批量下载多个模型或数据集的情形,推荐采用官方提供的 CLI 工具简化流程。首先确保已正确安装最新版客户端程序:
```bash
pip install -U huggingface_hub
```
随后运行以下命令完成目标资源的本地化存储操作:
```bash
huggingface-cli download --resume-download deepseek-ai/DeepSeek-R1-Distill-Qwen-7B --local-dir D:\llm\DeepSeek-R1-Distill-Qwen-7B --token 你的Token
```
注意需替换实际路径以及有效的认证密钥[^3]。
---
### 注意事项
1. 如果遇到权限不足的问题,请确认是否提供了正确的 API Token。
2. 对于某些特殊类型的仓库(如数据集而非模型),记得显式声明其类别参数 `--repo-type=dataset`。
3. 使用 `--resume-download` 可保障断点续传机制发挥作用,减少重复劳动成本。
阅读全文
相关推荐




















