← Cloudflare AI Gateway / ai-gateway / features
Spend limits
Лимиты расходов позволяют задавать бюджеты на основе стоимости для вашего AI Gateway. Когда совокупные расходы достигают лимита в течение заданного периода, AI Gateway блокирует дальнейшие запросы с 429 ответ, пока окно не сбросится.
В отличие от ограничение частоты запросов, который ограничивает количество запросов, лимиты расходов отслеживают фактическую стоимость каждого запроса в долларах на основе цен модели. Лимиты можно применять к любой комбинации модели, провайдера или пользовательские метаданные измерения, такие как ID пользователя, команда или приложение.
Лимиты расходов применяются как к Unified Billing запросы и BYOK запросов для моделей с известной ценой.
Как это работает
Каждое правило лимита расходов задаёт бюджет (в долларах) на скользящий или фиксированный период времени. AI Gateway рассчитывает стоимость каждого запроса на основе использования токенов и стоимости модели, а затем отслеживает совокупные расходы относительно лимита в реальном времени.
Прежде чем отправить запрос провайдеру, AI Gateway одновременно проверяет все применимые правила лимита расходов. Если хотя бы одно правило превышает бюджет, запрос блокируется с 429 ответ.
Лимиты расходов обеспечивают согласованность в конечном счёте. Стоимость текущего запроса фиксируется только после его завершения, поэтому при всплеске параллельных запросов лимит может быть кратковременно превышен, пока применение ограничения не догонит фактические траты.
Область действия по измерениям
Каждое правило можно ограничить по одному или нескольким измерениям:
- Ограничение по провайдеру, поставщик, использованный для запроса.
- Ограничение по модели, модель, использованная для запроса.
- Ограничение по метаданным, это пользовательские метаданные ключ, который вы прикрепляете к запросам. Введите имя ключа метаданных (например,
agent_idилиenvironment).
Каждое измерение можно настроить в одном из двух режимов:
| Режим | Поведение | Пример |
|---|---|---|
| Разделение по значению | Каждое уникальное значение получает собственный независимый budget bucket. | Например, если вы передадите agent_id, разбивая по agent_id дает каждому агенту собственный бюджет. |
| Фильтр по значению | Правило применяется только тогда, когда измерение равно определённому значению. | Например, если вы передадите agent_id, фильтруя agent_id к agent_42 ограничивает только запросы этого агента. |
Если для правила не настроено измерение, все значения используют один общий budget bucket. Например, правило без provider измерение отслеживает расходы по всем провайдерам вместе.
Примеры измерений
При запросе с моделью openai/gpt-5.5 и agent_id значение метаданных agent_42:
| Сценарий | Измерения | Budget bucket |
|---|---|---|
| Глобальный бюджет для всех | None | Один общий бакет |
| Бюджет на агента | agent_id метаданные: разбивка по значению |
Отдельный bucket для каждого агента |
| На провайдера, на агента | agent_id метаданные: разбивка по значению, provider: разделение по значению |
Отдельный bucket для каждой комбинации агент+провайдер |
| Только конкретная модель | model: фильтрация по значению openai/gpt-5.5 |
Применяется только к openai/gpt-5.5 запросы |
| На агента, на модель | agent_id метаданные: разбивка по значению, model: разделение по значению |
Отдельный bucket для каждой комбинации агент+модель |
Настройте лимиты расходов
Лимиты расходов настраиваются на уровне шлюза через панель управления или API. Для одного шлюза можно задать до 20 правил.
Чтобы ограничивать лимиты расходов по пользовательским измерениям, таким как ID пользователя или команда, добавьте пользовательские метаданные к вашим запросам.
Настройте лимиты расходов по пользователям
Вы можете выделить каждому пользователю собственный бюджет, привязав правило к идентификатору пользователя. То, как вы получите этот идентификатор, зависит от способа аутентификации вашего шлюза.
С Cloudflare Access
Если ваш шлюз защищён Cloudflare Access, AI Gateway автоматически добавляет ID аутентифицированного пользователя Access к каждому запросу как зарезервированный cf.user_id ключ метаданных. Передавать ID пользователей из клиентского приложения не требуется.
Чтобы задать бюджет для отдельного пользователя:
- В Панель управления Cloudflare ↗, перейдите в AI > AI Gateway и выберите свой шлюз.
- Перейдите в настройки лимитов расходов и добавьте правило.
- В разделе Ограничение по метаданным, выберите Добавить измерение метаданных и введите
cf.user_idв качестве ключа. - Установите для измерения значение Разделение по значению.
- Задайте сумму бюджета и временное окно, затем сохраните.
Теперь каждый аутентифицированный пользователь Access получает независимый бюджет. Чтобы вместо этого ограничить одного пользователя, задайте для измерения значение Фильтр по значению и введите Access JWT этого пользователя sub утверждение.
Без Cloudflare Access
Если ваш шлюз не защищён Access, передавайте собственный идентификатор пользователя как пользовательские метаданные (например, user_id ключ). Затем в разделе Ограничение по метаданным, добавьте измерение с ключом user_id и установите значение Разделение по значению.
Поведение при достижении лимита
Когда лимит расходов превышен, AI Gateway возвращает 429 Too Many Requests ответ. У вас есть два варианта:
- Блокировать запросы (по умолчанию) - запрос отклоняется до сброса окна бюджета.
- Переход на более дешёвую модель - создайте Dynamic Route с основной моделью и резервной моделью (например,
anthropic/claude-opus-4.7с резервным переходом на@cf/moonshotai/kimi-k2.6). Затем задайте лимит расходов для основной модели с помощью этой функции. Когда бюджет основной модели исчерпан, AI Gateway автоматически перенаправляет запросы на резервную модель вместо их блокировки.
Отслеживание расходов
Вы можете отслеживать расходы в разрезе модели, провайдера или любого пользовательского атрибута метаданных в Панель Analytics. Используйте эти данные, чтобы понимать структуру использования и осознанно устанавливать бюджеты.
Ограничения
- Отслеживание затрат представляет собой приблизительную оценку на основе количества токенов и цен на модели. Точные суммы к оплате уточняйте в панели управления вашего провайдера.
- Для одного шлюза можно настроить не более 20 правил лимита расходов.