Self-Host Private Hugging Face Mirror on VPS Cloud Vietnam: High-Speed AI Solution
Detailed guide to building a private Hugging Face mirror on a VPS Cloud in Vietnam for fast, stable AI model downloads without international connection drops. Effective solution for...
Why Use a Private Hugging Face Mirror on VPS Cloud Vietnam?
Downloading AI models from Hugging Face often suffers from slow speeds or disconnections due to reliance on international network connections. For businesses and developers in Vietnam, downloading large models like Llama, Mistral, or Stable Diffusion can take hours or fail entirely due to bandwidth limits, network interruptions, or internet censorship. The effective solution is to self-host a private Hugging Face mirror on a VPS Cloud in Vietnam—offering stable international connectivity, high bandwidth, and optimal geographic positioning.
This private mirror acts as an internal cache: the first download of a model stores it locally on your VPS, and subsequent downloads retrieve it from the local source—significantly faster and independent of international network conditions.
Requirements and Environment Setup
To deploy a private Hugging Face mirror, you will need:
- 1 VPS Cloud in Vietnam with at least 32GB RAM and 500GB SSD (optimized for storing large models)
- Operating system: Ubuntu 22.04 LTS
- Docker and Docker Compose installed
- SSH access to the VPS
Configuring the Private Mirror
We’ll use huggingface-mirror—an automated tool to download and sync models from Hugging Face to a local server. Follow these steps:
# 1. Install Docker and Docker Compose
sudo apt update
sudo apt install -y docker.io docker-compose
# 2. Create storage directory
mkdir -p ~/huggingface-mirror
cd ~/huggingface-mirror
# 3. Create docker-compose.yml file
cat < docker-compose.yml
version: '3.8'
services:
mirror:
image: ghcr.io/huggingface/huggingface-mirror:latest
container_name: huggingface-mirror
ports:
- "8080:8080"
volumes:
- ./cache:/cache
environment:
- HF_MIRROR_URL=https://huggingface.co
- HF_CACHE_DIR=/cache
restart: unless-stopped
EOF
# 4. Start the service
docker-compose up -d
# 5. Check status
docker-compose ps
After starting, the private mirror will run on port 8080. You can access http://[IP-VPS]:8080 to verify.
Downloading AI Models via the Private Mirror
To download models from your private mirror, configure your environment to use your VPS URL instead of the official Hugging Face endpoint. For example, in Python:
from huggingface_hub import snapshot_download
import os
# Configure private mirror URL
os.environ["HF_ENDPOINT"] = "http://[IP-VPS]:8080"
os.environ["HF_MIRROR"] = "http://[IP-VPS]:8080"
# Download model
model_name = "meta-llama/Llama-2-7b-chat-hf"
snapshot_download(model_name, local_dir="./models")
Replace [IP-VPS] with your VPS’s public IP address. The first download will take time, but subsequent downloads will be much faster.
Verification and Troubleshooting
Troubleshooting:
- If downloads fail: Check if port 8080 is open on the VPS (firewall, security group)
- If models are missing: Verify the
/cachedirectory on the VPS - If latency is high: Ensure the VPS has stable international connectivity
Verification:
- Run
docker logs huggingface-mirrorto check download logs - Visit
http://[IP-VPS]:8080to confirm models appear in the list - Test downloading a small model like
bert-base-uncasedfor validation
Performance Optimization
To enhance performance:
- Run multiple mirror containers if downloading multiple models simultaneously
- Host the VPS in Vietnam to minimize network latency
- Use NVMe SSD instead of HDD for faster read/write speeds
- Set up a cron job to automatically sync popular models weekly
References
High-RAM Cloud VPS Plans Optimized for AI, Databases & Cache
Enterprise RAID 10 NVMe SSDs, CMC & FPT District 9 uplinks with Anycast Anti-DDoS and 99.99% SLA.
VPS-4E
10% VAT included
- CPU: 4 vCPU
- RAM: 8 GB
- SSD: 50 GB NVMe
