Giới hạn tần suất Hub

Để bảo vệ tính toàn vẹn của nền tảng và đảm bảo khả năng truy cập cho nhiều thành viên nhất có thể trong cộng đồng AI, chúng tôi áp dụng giới hạn tần suất (rate limit) cho tất cả các yêu cầu gửi đến Hugging Face Hub.

Chúng tôi xác định các giới hạn tốc độ khác nhau cho các lớp yêu cầu khác nhau. Chúng tôi phân biệt ba nhóm chính:

• Hub APIs
  • ví dụ: tìm kiếm model hoặc dataset, tạo repo, quản lý người dùng, v.v. Tất cả các endpoint thuộc nhóm này được tài liệu hóa trong Hub API Endpoints.
• Resolvers
  • Tất cả đều là các URL có chứa đoạn /resolve/ trong đường dẫn, dùng để phục vụ nội dung do người dùng tạo từ Hub. Cụ thể, đó là các URL được xây dựng bởi các thư viện mã nguồn mở (transformers, datasets, vLLM, llama.cpp, …) hoặc các ứng dụng AI (LM Studio, Jan, ollama, …) để tải xuống các tệp model/dataset từ HF.
  • Cụ thể, đây là “Resolve a file” endpoint được tài liệu hóa trong spec OpenAPI của chúng tôi.
  • Resolve requests được cộng đồng sử dụng rất nhiều, và vì chúng tôi tối ưu hóa cơ sở hạ tầng để phục vụ chúng với hiệu quả cao nhất, nên giới hạn tần suất (rate limits) cho Resolvers là cao nhất.
• Pages
  • Tất cả các trang Web mà chúng tôi lưu trữ trên huggingface.co.
  • Thông thường, các yêu cầu duyệt web được thực hiện bởi con người, do đó giới hạn tần suất không cần cao như các điểm cuối lập trình được đề cập ở trên.

Tất cả các giá trị được xác định trên các cửa sổ 5 phút, cho phép một mức độ nhất định về “tính đột biến” từ góc nhìn của ứng dụng hoặc nhà phát triển.

Nếu bạn, tổ chức của bạn, hoặc ứng dụng của bạn cần giới hạn tần suất (rate limit) cao hơn, chúng tôi khuyến khích bạn nâng cấp tài khoản lên PRO, Team hoặc Enterprise. Chúng tôi ưu tiên các yêu cầu hỗ trợ từ khách hàng PRO, Team và Enterprise – xem các giới hạn tích hợp trong Các cấp độ giới hạn tần suất.

Bảng điều khiển thanh toán

Vào bất kỳ thời điểm nào, bạn có thể kiểm tra trạng thái giới hạn tần suất (rate limit) của mình trên trang Billing (của bạn hoặc của tổ chức bạn): https://huggingface.co/settings/billing

Ở phía bên phải, bạn sẽ thấy ba đồng hồ đo, mỗi đồng hồ đo tương ứng với một nhóm của Requests.

Mỗi bucket hiển thị số lượng yêu cầu hiện tại (trong 5 phút qua) và số lượng yêu cầu được phép dựa trên gói người dùng hoặc tổ chức của bạn.

Mỗi khi bạn vượt quá giới hạn trong 5 phút qua (giao diện được cập nhật theo thời gian thực), thanh sẽ chuyển sang màu đỏ.

Lưu ý: Bạn có thể sử dụng công cụ chuyển ngữ cảnh để dễ dàng chuyển đổi giữa tài khoản người dùng của bạn và các tổ chức của bạn.

Tiêu đề HTTP

Mỗi khi bạn hoặc tổ chức của bạn chạm đến giới hạn tần suất, bạn sẽ nhận được lỗi HTTP 429 Too Many Requests.

Chúng tôi triển khai cơ chế được mô tả trong bản thảo IETF (Phiên bản 9) có tiêu đề “RateLimit HTTP header fields for HTTP” (còn được biết đến với tên draft-ietf-httpapi-ratelimit-headers).

Mục tiêu là định nghĩa các tiêu đề HTTP chuẩn hóa để máy chủ có thể quảng bá các chính sách hạn mức / giới hạn tốc độ và truyền đạt mức sử dụng / giới hạn hiện tại cho các client, giúp chúng tránh bị giảm tốc.

Cụ thể, chúng tôi triển khai các tiêu đề sau:

Tiêu đề	Mục đích / Ý nghĩa
RateLimit	Giới hạn tốc độ tối đa được phép cho cửa sổ hiện tại. “Số lượng yêu cầu (thuộc loại này) mà bạn được phép thực hiện.”
RateLimit-Policy	Chứa chính sách giới hạn tần suất truy cập (ví dụ: “100 yêu cầu trong 5 phút”). Đây là thông tin tham khảo; cho thấy chính sách mà client phải tuân theo.

Một tập hợp các ví dụ như sau:

Tiêu đề	Ví dụ
RateLimit	"api\|pages\|resolvers";r=[remaining];t=[seconds remaining until reset]
RateLimit-Policy	"fixed window";"api\|\pages\|resolvers";q=[total allowed for window];w=[window duration in seconds]

Các cấp giới hạn tốc độ

Dưới đây là các giới hạn tần suất hiện tại (tính đến tháng 9 năm 2025) dựa trên gói của bạn:

Kế hoạch	API	Trình phân giải	Trang
Người dùng ẩn danh (theo địa chỉ IP)	500 *	3,000 *	100 *
Người dùng miễn phí	1,000 *	5,000 *	200 *
Người dùng PRO	2,500	12,000	400
Tổ chức nhóm	3,000	20,000	400
Tổ chức doanh nghiệp	6,000	50,000	600
Tổ chức Enterprise Plus	10,000	100,000	1,000
Tổ chức Enterprise Plus Với “Higher Hub Rate Limits” được bật	100,000	500,000	10,000
Tổ chức Academia Hub	3,000	20,000	400

* Người dùng ẩn danh và miễn phí có thể thay đổi theo thời gian tùy thuộc vào tình trạng hoạt động của nền tảng 🤞

Tất cả các hạn mức được tính trên các cửa sổ cố định 5 phút.

Lưu ý: Đối với các tổ chức, giới hạn tần suất được áp dụng riêng lẻ cho từng thành viên, không được chia sẻ giữa các thành viên.

Nếu tôi bị giới hạn tần suất truy cập thì sao

Đầu tiên, hãy đảm bảo bạn luôn truyền HF_TOKEN, và token này được truyền xuống các thư viện hoặc ứng dụng tải thứ từ Hub.

Đây là lý do số một khiến người dùng bị giới hạn tần suất truy cập và có thể khắc phục rất dễ dàng.

Mặc dù đã truyền HF_TOKEN nhưng bạn vẫn bị giới hạn tần suất, bạn có thể:

• phân bổ các yêu cầu của bạn trong khoảng thời gian dài hơn
• thay thế các cuộc gọi Hub API bằng các cuộc gọi Resolver, bất cứ khi nào có thể (giới hạn tần suất của Resolver cao hơn nhiều và được tối ưu hóa tốt hơn nhiều).
• nâng cấp lên PRO, Team hoặc Enterprise.

Xử lý giới hạn tốc độ thông minh với huggingface_hub

Thư viện Python của Hub huggingface_hub (phiên bản 1.2.0+) bao gồm xử lý thử lại thông minh cho các lỗi giới hạn tần suất.

Khi xảy ra lỗi 429, SDK tự động phân tích header RateLimit để trích xuất chính xác số giây cho đến khi giới hạn tần suất được đặt lại, sau đó chờ đúng khoảng thời gian đó trước khi thử lại. Điều này áp dụng cho việc tải xuống tệp (tức là Resolvers) và các cuộc gọi API Hub phân trang (liệt kê models, datasets, spaces, v.v.).

Chúng tôi khuyến nghị mạnh mẽ việc sử dụng huggingface_hub cho mọi truy cập lập trình vào Hub để tận dụng hành vi thử lại được tối ưu hóa này và tránh việc triển khai xử lý giới hạn tốc độ tùy chỉnh.

Giới hạn tần suất thao tác người dùng chi tiết

Ngoài các loại giới hạn tần suất chính đó, chúng tôi áp dụng giới hạn đối với một số loại hành động người dùng cụ thể, chẳng hạn như:

• tạo kho
• các commit của repo
• thảo luận và bình luận
• các hành động kiểm duyệt
• v.v.

Hiện tại, chúng tôi không tài liệu hóa giới hạn tần suất cho các thao tác cụ thể đó, vì chúng có xu hướng thay đổi thường xuyên hơn theo thời gian. Nếu bạn gặp lỗi hạn mức, chúng tôi khuyến khích bạn nâng cấp tài khoản lên PRO, Team hoặc Enterprise. Hãy liên hệ với chúng tôi thông qua đội ngũ hỗ trợ.

Update on GitHub