Hugging Face Mirror Acceleration Quick Start Guide
End-to-end acceleration manual covering basic environment variables, official CLI resume downloads, Python SDK integration, and enterprise Docker setups.
π Table of Contents
1. Acceleration Principles & Mechanism
Downloading large AI models (such as DeepSeek-R1, Qwen2.5, LLaMA-3.3) directly from huggingface.co frequently suffers from DNS pollution, high packet loss, and frequent connection resets.
HF-Mirror (hf-mirror.net) deploys high-bandwidth Anycast edge PoPs. Unlike traditional mirror sources that issue 302 Found redirects bouncing downloads back to overseas object stores, this platform delivers large binary chunks directly with HTTP 200 OK / 206 Partial Content streaming, ensuring stable, uninterrupted transfers.
2. Environment Configuration (Linux / macOS / Windows)
Direct your system's HF_ENDPOINT environment variable to HF-Mirror:
Temporary configuration (active shell only):
Permanent configuration (append to shell profile):
Temporary configuration:
Permanent configuration (current user environment):
3. huggingface-cli CLI Download (Recommended)
The official huggingface-cli utility provides automatic resume capability, chunk integrity verification, and precise file filtering.
pip install -U huggingface_hub
# Example: Download Qwen2.5-7B-Instruct to a local directory huggingface-cli download Qwen/Qwen2.5-7B-Instruct --resume-download --local-dir Qwen2.5-7B
# Download only specific GGUF quantizations huggingface-cli download bartowski/DeepSeek-R1-Distill-Qwen-7B-GGUF --include "*Q4_K_M.gguf" --local-dir ./ # Download only Safetensors weights, skipping .bin and .onnx huggingface-cli download meta-llama/Llama-3.3-70B-Instruct --include "*.safetensors" "*.json" --local-dir ./
4. Gated Repository Authentication & Downloads
Gated models (e.g. meta-llama/Llama-3.3, google/gemma-2) require user authorization:
- Sign in to Hugging Face and request license access on the model page;
- Generate a Read Token in your Account Settings: https://huggingface.co/settings/tokens;
- Run
huggingface-cli loginand paste your Token, or pass--token hf_***to the download command.
5. Python Script & Library Integration
Inject the environment variable at the very top of your Python file (before importing transformers or diffusers):
import os os.environ["HF_ENDPOINT"] = "https://hf-mirror.net" # Subsequent imports will automatically route requests through HF-Mirror 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 Large File Downloads
If you prefer cloning complete code and weight repositories using Git:
# 1. Ensure git-lfs is installed and initialized git lfs install # 2. Replace official domain with hf-mirror.net git clone https://hf-mirror.net/gpt2
* Note: For models larger than several gigabytes, huggingface-cli is strongly recommended over Git clone to avoid downloading bloated Git history commits.
7. Docker / Cloud Server Persistence Best Practices
When running GPU container instances, mount host cache volumes to persist models across restarts:
# Docker command: Inject mirror endpoint and mount host cache volume docker run -it --gpus all \ -e HF_ENDPOINT="https://hf-mirror.net" \ -v /data/hf_cache:/root/.cache/huggingface \ pytorch/pytorch:latest
8. Troubleshooting Quick Check
Always include --resume-download. HF-Mirror fully supports HTTP Range sharding and will resume from the exact byte offset.
The model is gated (e.g. LLaMA 3.3). Accept the license on the model page and run huggingface-cli login with your Access Token.
Git LFS was not initialized. Run git lfs install and execute git lfs pull inside the repository directory.