Лимиты Gemini API (rate limits) считаются на уровне проекта, и все ключи проекта делят одну квоту по запросам в минуту, токенам в минуту и запросам в сутки. Превышение любого из трёх показателей приводит к отказу, и приложению нужен заранее продуманный ответ: очередь, повтор с паузой, приоритеты и мониторинг. Конкретные значения отличаются у моделей и уровней доступа и меняются, поэтому берите их из личного кабинета, а в коде храните как настройки.
Как считаются лимиты
По документации Gemini API, ограничения измеряются запросами в минуту, токенами в минуту и запросами в сутки, применяются к проекту и зависят от уровня доступа. Превышение даёт ошибку 429 RESOURCE_EXHAUSTED, суточная квота сбрасывается по тихоокеанскому времени.
- Запросы в минуту: сколько обращений проект отправляет за минуту, независимо от их размера.
- Токены в минуту: суммарный размер входа, который проект подаёт моделям за минуту; длинные документы расходуют его быстро.
- Запросы в сутки: потолок на день; он сбрасывается раз в сутки в полночь по тихоокеанскому времени, то есть для российских команд примерно в десять-одиннадцать утра по Москве, в зависимости от сезона.
- Дополнительные показатели: для отдельных моделей и режимов, например для пакетной обработки, действуют собственные лимиты.
Уровень доступа зависит от того, подключена ли оплата и сколько времени и средств проект уже израсходовал. Более высокие уровни дают больше квоты, а повышение можно запросить. Помимо квот по запросам и токенам, на каждом уровне вендор ограничивает расход средств за скользящие десять минут. Точные пороги и значения вендор публикует на странице лимитов и в кабинете AI Studio, и статья их сознательно опускает: значения обновляются.
Общее описание интерфейса и вариантов подключения мы давали в статье Gemini API для компании, а вопросы доступа из России разбирали в материале Gemini в России. Актуальные правила по лимитам лежат на странице лимитов Gemini API.
Что видит приложение
Отдел поддержки подключил Gemini для черновиков ответов. Днём нагрузка ровная, а в начале недели приходит пачка обращений, и в понедельник утром ответы начинают задерживаться. Причина кроется в пике запросов в минуту, и сбой сервиса тут ни при чём: очередь с ограничением скорости растягивает пик во времени, и сотрудники получают ответы чуть позже, зато без ошибок. Без очереди приложение отвечало бы пользователям отказами.
Для приложения ограничение выглядит как ошибка ответа с кодом 429 и статусом исчерпания ресурса. Причин у неё несколько, и реакция зависит от причины.
| Сигнал | Что произошло | Реакция приложения |
|---|---|---|
| 429 в пиковые минуты, потом всё работает | Превышены запросы или токены в минуту | Пауза и повтор, сглаживание нагрузки очередью |
| 429 до конца суток | Исчерпана суточная квота запросов | Остановка новых задач, оповещение, перенос на утро |
| 429 на одной модели при исправных остальных | Квота конкретной модели исчерпана | Переключение на запасную модель, если она подходит по качеству |
| Ответы всё медленнее без ошибок | Нагрузка приближается к потолку, растёт ожидание | Сокращение параллелизма, проверка размера запросов |
| 429 сразу после смены ключа | Новые ключи того же проекта делят прежнюю квоту | Отдельный проект для отдельной нагрузки |
Последняя строка часто удивляет: ключ — это способ доступа, а квота принадлежит проекту. Создание второго ключа в том же проекте оставляет нагрузку на прежней квоте. Для изоляции нагрузок, например тестовой и рабочей, заводите отдельные проекты.
Очередь и повторы
Повтор запроса сразу после ошибки только усиливает перегрузку. Надёжная схема сочетает очередь на входе и осмысленные паузы между попытками.
- Поставьте перед вызовами очередь с ограничением скорости чуть ниже вашей квоты: так запросы расходуются равномерно и редко упираются в потолок.
- При ошибке 429 повторяйте запрос с растущей паузой и случайным разбросом, чтобы одновременные клиенты разошлись по времени.
- Ограничьте число повторов и общее время ожидания, после чего сообщайте пользователю о задержке либо переносите задачу в отложенную очередь.
- Разделите задачи по важности: ответы пользователям идут первыми, фоновая обработка уступает им квоту.
- Записывайте каждую попытку в журнал вместе с причиной отказа, чтобы потом видеть, какая из квот и в какие часы становится узким местом.
Для пакетной обработки больших объёмов, например расшифровок или документов, используйте пакетный режим (Batch API): у него отдельные лимиты, и он разгружает интерактивную квоту, если отложенный результат вас устраивает. Сверьте условия и ограничения в документации, потому что перечень режимов меняется.
Какую нагрузку вы планируете направить на Gemini API?
Мониторинг квот
Лимиты нельзя угадать, их нужно измерять. Без мониторинга вы узнаёте о нехватке квоты от пользователей вместо сигнала от самой системы.
- Доля отказов 429 от общего числа запросов по часам: рост в одно и то же время указывает на пик, который можно сгладить.
- Расход токенов в минуту: самый частый источник неожиданностей, потому что длинные документы съедают квоту быстрее, чем кажется.
- Глубина очереди и время ожидания в ней: растущая очередь предупреждает о перегрузке раньше, чем пойдут отказы.
- Распределение по моделям: показывает, где можно переключиться на более лёгкую модель без потери качества.
- Просмотр квот в кабинете AI Studio: раз в неделю сверяйте фактические лимиты проекта с настройками в коде.
Отдельный источник нагрузки — повторные запросы самого приложения: интерфейс, где пользователь нажимает кнопку несколько раз, умножает расход. Блокируйте повторную отправку до прихода ответа и объединяйте одинаковые запросы. Кэшируйте ответы на повторяющиеся вопросы: экономия достигается там, где один и тот же запрос приходит многократно.
Установите пороги оповещения заранее: например, когда доля отказов за последний час заметно выросла или очередь превысила допустимую глубину. Пороги подбирают по реальной нагрузке и корректируют первые недели, чтобы оповещения оставались редкими и полезными.
Рост нагрузки
Выпишите расход проекта за обычный день: число запросов, средний размер входа, часы пиков. Сравните с квотами в кабинете и определите запас. Если запас тоньше половины, начинайте с очереди, потом с запроса на повышение уровня.
Рост нагрузки лучше планировать заранее. Повышение уровня или лимитов занимает время, а подготовка очереди и отдельных проектов под нагрузки требует работы разработчика. Оба шага делайте заранее, задолго до дня запуска рассылки или сезонного пика.
Подумайте и о запасном маршруте. Когда квота исчерпана, приложение может переключиться на другую модель того же вендора или на другого поставщика, если задача допускает отправку данных наружу и качество приемлемо. Запасной путь требует отдельной проверки качества и условий по данным, и решать его надо до того, как он понадобится. Сравнение моделей для разных задач мы описывали в статье про Gemini Flash для рабочих задач.
Лимиты постоянной величиной считать нельзя: значения, вписанные в код, устареют, поэтому держите их в настройках и сверяйте при каждом обновлении моделей. Расчёт запаса, очередь и мониторинг входят в аудит нагрузки, которым занимается наш консалтинг по внедрению ИИ.