Thông báo lỗiHãy tưởng tượng bạn đang chạy một bot production hoặc một script thực tế, và đột nhiên log của bạn tràn ngập ngoại lệ cụ thể này:
huggingface_hub.utils._errors.HfHubHTTPError: 503 Server Error: Service Unavailable for url: https://api-inference.huggingface.co/models/... {"error":"Model is currently loading","estimated_time":20.0}
Đây là một trở ngại phổ biến khi sử dụng Inference API miễn phí hoặc chia sẻ. Đây không phải là một lỗi vĩnh viễn. Tuy nhiên, nó sẽ làm sập bất kỳ script nào không được chuẩn bị cho cách HuggingFace quản lý hạ tầng của mình.
Nguyên nhân: Cold StartsHuggingFace lưu trữ hơn 500.000 mô hình. Họ không thể giữ tất cả chúng được tải vào bộ nhớ GPU 24/7 trên các máy chủ chia sẻ của mình. Nếu một mô hình không được gọi trong vài giờ, nó sẽ bị 'đẩy ra ngoài' (swapped out) để nhường chỗ cho những mô hình phổ biến hơn.
Khi bạn yêu cầu một mô hình đang tạm nghỉ, HuggingFace sẽ kích hoạt một 'cold start'. Lỗi 503 là cách họ thông báo: 'Chúng tôi đang đánh thức mô hình, nhưng nó chưa sẵn sàng. Hãy thử lại sau khoảng 20 giây.'
Bước 1: Cách khắc phục nhanh (thư viện huggingface_hub)Nếu bạn sử dụng thư viện Python chính thức huggingface_hub, bạn có thể khắc phục điều này chỉ với một tham số duy nhất. Các nhà phát triển đã xây dựng sẵn một cơ chế để tự động xử lý việc chờ đợi.
from huggingface_hub import InferenceClient
client = InferenceClient(model="bigscience/bloomz-560m")
# 'wait_for_model=True' yêu cầu client chặn và
# thử lại cho đến khi mô hình được tải hoàn toàn vào bộ nhớ.
try:
response = client.text_generation(
"How do I fix a 503 error?",
wait_for_model=True
)
print(response)
except Exception as e:
print(f"Yêu cầu thất bại: {e}")
Việc đặt tham số này thành True sẽ giúp client đọc estimated_time từ lỗi và tạm dừng script cho đến khi mô hình hoạt động.
Bước 2: Logic thử lại tùy chỉnh (Requests/Raw API)Khi gọi API qua requests hoặc fetch, bạn phải tự triển khai logic thử lại (retry). Việc bị lỗi ngay từ lần gặp 503 đầu tiên sẽ khiến ứng dụng trở nên kém ổn định, dễ thất bại chỉ vì mô hình đang "ngủ".
Dưới đây là một vòng lặp Python mạnh mẽ để xử lý việc chờ đợi:
import requests
import time
API_URL = "https://api-inference.huggingface.co/models/YOUR_MODEL_ID"
headers = {"Authorization": "Bearer YOUR_HF_TOKEN"}
def query_with_retry(payload, max_retries=3):
for i in range(max_retries):
response = requests.post(API_URL, headers=headers, json=payload)
output = response.json()
# Kiểm tra xem mô hình có đang tải không
if response.status_code == 503 and "loading" in str(output):
# Mặc định là 20 giây nếu thiếu estimated_time
wait_time = output.get("estimated_time", 20)
print(f"Mô hình đang tải. Đang chờ {wait_time}s (Lần thử {i+1}/{max_retries})...")
time.sleep(wait_time)
continue
return output
raise Exception("Mô hình không thể tải trong giới hạn số lần thử lại.")
data = query_with_retry({"inputs": "The cat sat on the mat."})
print(data)
Bước 3: Làm nóng trước (Pre-warming) mô hìnhNếu bạn không thể chấp nhận việc người dùng đầu tiên phải chờ 20 giây, bạn có thể 'làm nóng trước' mô hình. Điều này có nghĩa là gửi một yêu cầu giả trong giai đoạn khởi động ứng dụng hoặc thông qua một tác vụ được lập lịch.
- Khởi động làm nóng (Startup Warmup): Khi máy chủ của bạn khởi động, hãy gọi mô hình một lần với
wait_for_model=True. Điều này đảm bảo mô hình đã sẵn sàng trước khi người dùng thực sự đầu tiên truy cập.- Duy trì hoạt động (Keep-alive Cron): Đối với các mô hình hiếm khi được sử dụng, hãy gọi API mỗi 15 phút một lần với một yêu cầu nhỏ. Điều này giúp mô hình luôn ở trạng thái 'nóng' trong cache của HuggingFace.## Bước 4: Kiểm tra Timeout của bạnNếu bạn bậtwait_for_model, yêu cầu HTTP của bạn có thể duy trì kết nối lên đến 60 giây. Bạn phải đảm bảo rằng hạ tầng của riêng mình—như Nginx, Gunicorn hoặc Cloudflare—không ngắt kết nối trong khi đang chờ đợi. Đối vớirequestshoặchttpx, hãy tăng timeout phía client lên ít nhất 120 giây:
# Dành cho mô hình nhiều thời gian để tải
response = requests.post(API_URL, headers=headers, json=payload, timeout=120)