🤗
HF-Mirror Documentation
📖 开发者完全指南

Hugging Face 镜像加速快速上手教程

本文档提供从基础环境配置、官方 CLI 命令行拉取、Python SDK 集成到企业级 Docker 缓存的端到端加速实战指引。

📑 目录导航 (Table of Contents)

1. 核心加速机制与原理 2. 环境变量配置 (多平台) 3. huggingface-cli 命令行下载 4. 受限模型 Token 鉴权 5. Python 代码中原生集成 6. Git LFS 大文件拉取 7. Docker / 云服务器持久化 8. 常见报错排障速查 (FAQ)

1. 核心加速机制与原理

在拉取 Hugging Face (huggingface.co) 的大型语言模型权重（如 DeepSeek-R1、Qwen2.5、LLaMA-3.3 等）时，常常面临 DNS 污染、跨洋高丢包率以及频繁断流等痛点。

HF-Mirror (hf-mirror.net) 通过 Cloudflare 全球 Anycast 边缘网络建立高带宽加速 PoP 点。与部分会将大文件通过 302 Found 重定向甩回海外存储的传统镜像源不同，本站针对大文件请求直接返回 HTTP 200 OK / 206 Partial Content 进行流式穿透加速，绝不二次甩锅境外，确保连接平稳不中断。

2. 环境变量配置 (Linux / macOS / Windows)

只需将系统的 HF_ENDPOINT 环境变量指向本站镜像域名即可完成全局提速：

Linux / macOS (Bash 或 Zsh) Terminal

临时生效（当前终端窗口有效）：

export HF_ENDPOINT="https://hf-mirror.net"

永久生效（写入 Shell 配置文件并重载）：

echo 'export HF_ENDPOINT="https://hf-mirror.net"' >> ~/.bashrc && source ~/.bashrc
Windows (PowerShell) PowerShell

临时生效：

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

永久生效（写入当前用户环境配置）：

[System.Environment]::SetEnvironmentVariable('HF_ENDPOINT', 'https://hf-mirror.net', [System.EnvironmentVariableTarget]::User)

3. huggingface-cli 命令行下载 (推荐)

官方推荐使用 huggingface-cli 工具下载大模型，具备自动断点续传、分块校验及指定文件过滤等特性。

1. 安装官方下载工具包：
pip install -U huggingface_hub
2. 完整模型下载命令（强烈建议携带 --resume-download）：
# 示例：下载 Qwen2.5-7B-Instruct 到本地目录
huggingface-cli download Qwen/Qwen2.5-7B-Instruct --resume-download --local-dir Qwen2.5-7B
3. 高级过滤用法（节省磁盘与带宽）：
# 仅下载特定量化精度的 GGUF 文件
huggingface-cli download bartowski/DeepSeek-R1-Distill-Qwen-7B-GGUF --include "*Q4_K_M.gguf" --local-dir ./

# 仅拉取 Safetensors 权重，跳过不需要的 .bin 或 .onnx 文件
huggingface-cli download meta-llama/Llama-3.3-70B-Instruct --include "*.safetensors" "*.json" --local-dir ./

4. 受限模型 (Gated Repo) 认证与下载

部分前沿模型（例如 meta-llama/Llama-3.3、google/gemma-2）在官网属于受限仓库，下载前需完成授权：

  1. 登录 Hugging Face 官网 申请许可；
  2. 进入账户中心生成 Read 权限的 Access Token：https://huggingface.co/settings/tokens；
  3. 在终端执行 huggingface-cli login 并粘贴 Token，或在下载命令中附带 --token hf_***。
🔒 安全说明：HF-Mirror 采用透明端到端 TLS 转发，用户的 Token 会直接传至 Hugging Face 官方认证中心校验，本加速站绝不存储、不记录用户的任何 Token 或账号凭据。

5. Python 脚本与框架中原生集成

在 Python 代码最顶端（导入 transformers / diffusers 库之前）注入环境变量： 

import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.net"

# 正常导入模型库，底层请求将自动通过镜像站加速拉取
from transformers import AutoTokenizer, AutoModelForCausalLM

model_id = "Qwen/Qwen2.5-7B-Instruct"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, device_map="auto")

6. Git LFS 大文件拉取

若需使用 Git 方式克隆整个代码与权重仓库：

# 1. 确保安装并初始化 git-lfs
git lfs install

# 2. 将官方域名替换为 hf-mirror.net
git clone https://hf-mirror.net/gpt2

* 提示：对于几十 GB 的大语言模型，推荐优先使用 huggingface-cli 下载，相比 Git 克隆能节省大量 Git 历史版本磁盘开销。

7. Docker / 云服务器持久化最佳实践

在租用 AutoDL、FeiShu、各大云厂商 GPU 容器时，建议将缓存目录挂载到持久化数据盘： 

# Docker 运行示例：注入加速端点并持久化 Hugging Face 缓存
docker run -it --gpus all   -e HF_ENDPOINT="https://hf-mirror.net"   -v /root/autodl-fs/hf_cache:/root/.cache/huggingface   pytorch/pytorch:latest

8. 常见排错速查 (Troubleshooting)

Q: 下载到 90% 断开或报 Connection Reset？

执行下载命令时务必加上 --resume-download 参数。HF-Mirror 完整支持 HTTP Range 分块，重试时会自动断点续传已下载部分。

Q: 提示 401 Client Error: Unauthorized？

该模型为受限模型（如 Llama-3），需在官网申请通过后，在终端执行 huggingface-cli login 填写 Token 授权。

Q: Git clone 下来的权重只有 1KB 的文本文件？

本地缺少 Git LFS 插件导致拉取的是指针文件。执行 git lfs install 后在仓库目录运行 git lfs pull 即可。

需要更多技术帮助？
查阅常见问题手册或联系我们的技术支持团队。
查看完整 FAQ 返回主控制台