Ограничения частоты запросов к Hub

Чтобы обеспечить целостность нашей платформы и сделать её доступной как можно большему числу участников сообщества ИИ, мы применяем ограничения частоты запросов (rate limits) ко всем запросам, отправляемым в Hugging Face Hub.

Мы устанавливаем различные лимиты частоты запросов для разных классов запросов. Мы выделяем три основные категории:

• Hub APIs
  • например, поиск моделей или датасетов, создание репозиториев, управление пользователями и т. д. Все эндпоинты, относящиеся к этой категории, описаны в Hub API Endpoints.
• Resolvers
  • Все они содержат в пути сегмент /resolve/ и предоставляют пользовательский контент из Hub. Конкретно это те URL, которые конструируются open source библиотеками (transformers, datasets, vLLM, llama.cpp, …) или AI-приложениями (LM Studio, Jan, ollama, …) для загрузки файлов моделей/датасетов с HF.
  • Конкретно, это «Resolve a file» endpoint, описанный в нашей спецификации OpenAPI.
  • Запросы Resolve активно используются сообществом, и поскольку мы оптимизируем нашу инфраструктуру для их обработки с максимальной эффективностью, лимиты частоты для Resolvers являются самыми высокими.
• Pages
  • Все веб-страницы, которые мы размещаем на huggingface.co.
  • Обычно запросы веб-обозревателя выполняются людьми, поэтому лимиты частоты для них не должны быть такими высокими, как для упомянутых выше программных конечных точек.

Все значения определяются в 5-минутных окнах, что позволяет учитывать некоторую «импульсивность» с точки зрения приложения или разработчика.

Если вам, вашей организации или вашему приложению требуются более высокие лимиты запросов, мы рекомендуем вам повысить уровень аккаунта до PRO, Team или Enterprise. Мы отдаём приоритет запросам на поддержку от клиентов PRO, Team и Enterprise – см. встроенные лимиты в Уровни лимитов запросов.

Панель управления биллингом

В любой момент вы можете проверить статус лимита запросов на странице Billing (тарифов) вашего аккаунта или организации: https://huggingface.co/settings/billing

Справа вы увидите три индикатора, по одному для каждой категории запросов.

Каждый бакет отображает количество текущих (за последние 5 минут) запросов, а также количество разрешённых запросов в соответствии с вашим тарифным планом для учётной записи или организации.

Каждый раз, когда вы превышаете лимит за последние 5 минут (отображение обновляется в реальном времени), индикатор становится красным.

Примечание: с помощью переключателя контекста вы можете легко переключаться между вашей учётной записью и вашими организациями.

HTTP-заголовки

Когда вы или ваша организация достигаете лимита запросов, вы получаете ошибку HTTP 429 Too Many Requests.

Мы реализовали механизм, описанный в черновике IETF (версия 9) под названием «RateLimit HTTP header fields for HTTP» (также известном как draft-ietf-httpapi-ratelimit-headers).

Цель состоит в том, чтобы определить стандартизированные HTTP-заголовки, которые серверы могут использовать для объявления политик квот и ограничения частоты запросов, а также для передачи клиентам информации о текущем использовании и лимитах, чтобы те могли избежать троттлинга.

Точнее, мы реализуем следующие заголовки:

Заголовок	Назначение / Значение
RateLimit	Общий допустимый лимит запросов для текущего окна. «Сколько запросов (данного типа) вам разрешено выполнить».
RateLimit-Policy	Содержит саму политику ограничения частоты запросов (например, «100 запросов в 5 минут»). Это информационное поле; показывает, какая политика применяется к клиенту.

Примеры набора:

Заголовок	Пример
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]

Уровни ограничений частоты запросов

Вот текущие лимиты запросов (на сентябрь 2025 г.) в зависимости от вашего тарифного плана:

План	API	Резолверы	Страницы
Анонимный пользователь (по IP-адресу)	500 *	3,000 *	100 *
Пользователь бесплатного тарифа	1,000 *	5,000 *	200 *
PRO-пользователь	2,500	12,000	400
Организация команды	3,000	20,000	400
Организация Enterprise	6,000	50,000	600
Организация Enterprise Plus	10,000	100,000	1,000
Организация Enterprise Plus с включенным параметром «Higher Hub Rate Limits»	100,000	500,000	10,000
Организация Academia Hub	3,000	20,000	400

* Пользователи с анонимным и бесплатным доступом могут сталкиваться с изменениями в зависимости от состояния платформы 🤞

Все квоты рассчитываются по фиксированным пятиминутным окнам.

Примечание: Для организаций лимиты запросов применяются индивидуально к каждому участнику, а не разделяются между участниками.

Что делать, если я упрёшься в лимит запросов

Сначала убедитесь, что вы всегда передаёте HF_TOKEN, и что он передаётся дальше во все библиотеки или приложения, которые скачивают данные с Hub.

Это главная причина, по которой пользователи сталкиваются с ограничением частоты запросов, и её очень легко устранить.

Даже если вы передали HF_TOKEN, но по-прежнему ограничены по частоте запросов, вы можете:

• распределяйте ваши запросы на более длительные периоды времени
• заменяйте вызовы Hub API вызовами Resolver, где это возможно (лимиты частоты запросов Resolver значительно выше и значительно более оптимизированы).
• перейдите на тариф PRO, Team или Enterprise.

Умная обработка ограничений частоты запросов с huggingface_hub

Библиотека Python для Hub huggingface_hub (версия 1.2.0+) включает интеллектуальную обработку повторных попыток при ошибках ограничения частоты запросов.

При возникновении ошибки 429 SDK автоматически анализирует заголовок RateLimit, чтобы извлечь точное количество секунд до сброса ограничения частоты запросов, а затем выжидает именно этот интервал перед повторной попыткой. Это касается загрузки файлов (т. е. Resolvers) и пагинированных вызовов Hub API (списки моделей, датасетов, spaces и т. д.).

Мы настоятельно рекомендуем использовать huggingface_hub для всего программного доступа к Hub, чтобы воспользоваться этим оптимизированным поведением повторных попыток и избежать реализации собственной обработки ограничений частоты запросов.

Ограничения частоты действий пользователей

Помимо основных классов лимитов частоты, мы устанавливаем ограничения на определённые конкретные действия пользователей, например:

• создание репозитория
• коммиты репозитория
• обсуждения и комментарии
• действия по модерации
• и т. д.

В настоящее время мы не документируем лимиты частоты для этих конкретных действий, так как они часто меняются со временем. Если вы получаете ошибки квоты, мы рекомендуем вам обновить аккаунт до PRO, Team или Enterprise. Вы можете связаться с нами через команду поддержки.

Update on GitHub