У API-ключа установлен лимит — почему всё равно возможен перерасход? Три бюджетные линии для тестирования AI

У API-ключа установлен лимит — почему всё равно возможен перерасход? Три бюджетные линии для тестирования AI

Если вы установили лимит для API-ключа, расходы всё равно могут оказаться выше ожидаемых. В этой статье разбираемся почему и раскладываем контроль бюджета при тестировании AI на три последовательные линии бюджета.

Сначала вывод: лимит Key на шлюзе — это мягкий потолок, и при параллельных запросах его нельзя считать жёстким лимитом счёта. На примере документации токенов APIYI: лимит проверяется в начале запроса. Несколько запросов одновременно проходят проверку, или сам по себе один запрос стоит очень дорого — в итоге фактический расход может превысить заданный лимит.

Надёжный подход — работать в три слоя:

  1. Бэкенд приложения выполняет проверку перед отправкой запроса и атомарно резервирует бюджет.
  2. На стороне шлюза для пробного трафика выпускается отдельный Key с лимитом и белым списком моделей — чтобы сузить область влияния, если этот Key начнут злоупотреблять.
  3. Оповещение о балансе аккаунта отвечает только за уведомление — оно запускает ручную реакцию.

Эти три слоя не заменяют друг друга. Настоящий допуск к бюджету происходит в собственном учёте приложения.

api-key-quota-overspend-three-budget-lines-ru-image-0


Table of Contents

Карта знаний и указатель: порядок и разделение обязанностей трёх бюджетных линий

Таблица ниже одновременно служит картой знаний и указателем. В ней перечислены три бюджетные линии: в каком порядке они вступают в силу, за что каждая отвечает, почему они расположены именно так, а также соответствующие номера разделов основного текста.

Порядок Бюджетная линия За что отвечает Почему находится здесь Цель Раздел
Предпосылка Понимание мягкой квоты Различать проверку перед запросом, предварительное удержание и фактическое списание Без понимания порядка списания невозможно проектировать остальные три уровня Понять, как происходит перерасход 1, 1.1
Первая линия Бюджет на стороне бэкенда приложения Атомарное резервирование и расчёт по пользователям и пробным пулам Только приложение знает, «кто использует и сколько может использовать» Чтобы перерасход блокировался до отправки запроса 2.1, 3
Вторая линия Отдельный пробный ключ Квота, белый список моделей, изоляция от основного трафика Если в приложении возникнет ошибка, шлюз становится вторым уровнем защиты Сократить область подверженности одного ключа 2.2
Третья линия Уведомление о балансе账户 Уведомление при падении баланса ниже порога Уведомление — это сигнал после факта, оно не умеет блокировать Чтобы человек мог своевременно вмешаться 2.3
Реализация Параллельный учёт и проверка перед запуском Резервирование, расчёт, обработка ошибок, сверка, дружелюбные подсказки Воплотить предыдущие принципы в проверяемый процесс Проверить по пунктам перед запуском 3, 4

Рекомендуемый порядок чтения: сначала читайте раздел 1, чтобы понять последовательность, затем раздел 2, чтобы уточнить распределение обязанностей, раздел 3 — практическая часть. Раздел 4 удобно использовать отдельно для сверки перед запуском.


To Know: необходимые термины перед разговором о бюджетной линии

Термин Краткое пояснение
Мягкий лимит Лимит проверяется в начале запроса, но успешная проверка не гарантирует, что суммарный расход не выйдет за черту
Предварительное удержание Шлюз сначала удерживает часть лимита по оценке, а после завершения запроса расчёт идёт по фактическому расходу
Атомарное резервирование «Проверка остатка и занятие» выполняются одной неделимой операцией, чтобы параллельные запросы не прошли одновременно
Резерв в обработке Та часть бюджета, которая остаётся занятой в учётной книге, когда запрос уже отправлен, но фактические затраты ещё не подтверждены
remain_quota Поле разового общего лимита токена APIYI; по документации значение 500000 соответствует $1
Сверка Построчное сопоставление логов шлюза с собственным учётом для исправления расхождений между оценкой и фактическими данными

1 Почему лимит API-ключа может быть превышен из-за параллельных запросов

Документация APIYI по токенам говорит об этом прямо: лимит ключа — это мягкий потолок, который проверяется в момент начала запроса. Поэтому параллельные запросы или один дорогой запрос могут вывести фактическое потребление за пределы заданного лимита. Это особенность самой схемы биллинга «проверка на старте, расчёт в конце», и здесь нет никакой связи с тем, есть ли на конкретной платформе баг.

Проще понять на гипотетическом примере (все числа условные, не из реальных замеров). Допустим, у тестового ключа остаток эквивалентен $1, и в один и тот же момент приходит 20 запросов. Каждый запрос на старте видит «баланс положительный» — и все 20 пропускаются. Когда они постепенно завершаются и расчёт идёт по фактическому расходу, суммарное потребление уже давно превышает $1. Даже без параллельности один запрос с длинным контекстом и большим объёмом вывода может по стоимости за один раз превысить оставшийся лимит.

Есть ещё два распространённых заблуждения, которые стоит прояснить:

  • Лимит не восстанавливается автоматически каждый день. В документации указано, что remain_quota — это единый однократный лимит, а «ежедневный сброс» должен реализовать сам разработчик приложения через скрипт по расписанию.
  • Белый список моделей — это не потолок расходов. Он ограничивает только то, какие модели можно вызывать, и никак не ограничивает число обращений к одной и той же модели или масштаб каждого обращения.

api-key-quota-overspend-three-budget-lines-ru-image-1

1.1 Три момента в биллинге лимита API-ключа: проверка до запроса, оценка и фактическое списание

У одного вызова с точки зрения биллинга есть три момента, и каждый отвечает на свой вопрос:

Момент Где происходит На какой вопрос отвечает Годится ли как жёсткий лимит
Проверка до запроса Шлюз, в начале запроса Есть ли у этого ключа прямо сейчас остаток Нет, при параллельности проверку проходят одновременно
Оценка и предварительное списание Шлюз, на основе оценки Сколько примерно займёт этот запрос Нет, оценка расходится с фактом
Фактическое списание Шлюз, после завершения запроса Сколько этот запрос реально потратил Данные постфактум, для допуска не годятся

Пояснение APIYI о предварительном списании такое: шлюз делает предварительное списание на основе оценки и потом рассчитывает по фактическому расходу, но этот механизм не заменяет атомарное резервирование на стороне бизнес-логики. Предварительное списание шлюза нужно для его собственного биллинга и ничего не знает о том, сколько дневного лимита осталось у конкретного вашего пользователя. Поэтому на вопрос «может этот пользователь отправить ещё один запрос» ответить может только бэкенд приложения.


2. Три бюджетные линии для пробного использования AI

Эти три линии закрывают три типа рисков: перерасход на уровне бизнес-логики, злоупотребление или утечку на уровне ключа и исчерпание баланса на уровне аккаунта. Пункт API4 «Unrestricted Resource Consumption» из OWASP API Security Top 10 (2023) — про ту же проблему: интерфейсы без ограничений на потребление ресурсов создают риски сразу и для сервиса, и для затрат. Для AI-интерфейсов риск затрат обычно выходит на первый план.

2.1. Первая бюджетная линия: бюджеты пользователей и пробного пула в бэкенде приложения

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

  • Бюджет пользователя: общий лимит на каждого пробного пользователя или дневной лимит. Дневной лимит сбрасывается собственным планировщиком приложения, без опоры на шлюз.
  • Бюджет пробного пула: общий потолок, который делят все пробные пользователи. Даже если ни один пользователь не вышел за свои рамки, при резком росте числа пользователей у общих затрат всё равно должен быть потолок.

Запрос пропускается только тогда, когда он одновременно прошёл резервирование и на уровне пользователя, и на уровне пула, причём оба шага должны выполняться в одной атомарной операции или в одной транзакции. Иначе возникнет гонка: «резерв для пользователя прошёл, а пул уже заполнен».

На этом же уровне нужно решать на сервере, каким будет масштаб запроса: какая модель разрешена, какой верхний предел max_tokens, какая максимальная длина ввода. Эти параметры нельзя принимать с фронтенда и просто пробрасывать дальше — иначе пользователю достаточно поменять один параметр, и оценка суммы исказится.

2.2 Вторая бюджетная линия: отдельный Key для пробного периода, лимиты и белый список моделей

На стороне шлюза для пробного трафика выдаётся отдельный Key, полностью изолированный от основного трафика. Задача этого Key — ограничить поверхность атаки: если в учёте приложения возникнет баг или Key утечёт, ущерб ограничится лимитом этого Key и не затронет основной бизнес.

При настройке обратите внимание на следующее:

  • Лимит устанавливайте по формуле «бюджет пробного пула + определённый буфер». Он должен быть чуть выше пулового бюджета на стороне приложения и служить подстраховкой — не ставьте его наравне с пулом, иначе резервирование на уровне приложения превратится в фикцию.
  • В белый список моделей включайте только те модели, которые открыты для пробного периода. Он не даёт использовать пробный Key для вызова дорогих моделей, но не ограничивает количество и объём, поэтому серверное ограничение объёма из раздела 2.1 всё равно необходимо.
  • Поскольку лимит — это мягкий потолок, эта линия допускает «небольшой перерасход». Её смысл — удержать величину перерасхода в допустимых рамках, но рассчитывать на полное отсутствие перерасхода не стоит.

Общая практика разделения Key, лимитов и логов по проектам — это отдельная тема; здесь подчеркнём только одно: для пробного трафика — отдельный Key.

2.3 Третья линия бюджета: оповещение о балансе аккаунта

В документации APIYI об оповещениях по балансу прямо сказано: оповещение — это уведомление, и запросы оно не блокирует. Когда баланс опускается ниже порога, оповещение доставляет сообщение ответственному лицу, а человек уже решает: пополнить счёт, приостановить вход для пробных пользователей или разобраться в аномальном трафике.

При работе с этим уровнем есть два совета:

  • Порог оповещения задавайте исходя из «максимального расхода за время от обнаружения до реакции», а не просто ставьте первое попавшееся целое число.
  • Оповещение должно быть привязано к конкретному действию. Например, в дежурной инструкции напишите: «после получения оповещения сначала закрыть вход для пробной регистрации». Оповещение, за которым не следует никаких действий, — пустая формальность.

3 Гипотетический журнал параллельного учёта: от атомарного резервирования до сверки

В этом разделе приведена примерная схема. Структура таблиц, цены и числа — всё вымышлено и служит лишь иллюстрацией процесса, а не отражает реальных измерений какой-либо системы. Процесс состоит из пяти шагов:

Атомарная проверка и резервирование → сервер фиксирует model и масштаб → отправка запроса
      → расчёт / обработка сбоя → офлайн-сверка и корректировка

api-key-quota-overspend-three-budget-lines-ru-image-2

3.1 Структура таблиц и состояния бюджетного реестра

В иллюстративной структуре данных две таблицы: budgets хранит лимит, израсходованную и зарезервированную суммы для каждого пользователя и пула пробного периода; reservations хранит каждое резервирование и его статус.

Статус резервирования Значение Влияние на «доступный остаток»
reserved Зарезервировано, запрос в процессе выполнения Занимает оценочную сумму
settled Получен фактический расход, расчёт завершён Переходит в израсходованное, разница освобождается
released Подтверждено, что запрос не был выполнен Освобождается полностью
unknown Тайм-аут, обрыв соединения, стоимость неизвестна Продолжает занимать, ждёт сверки

Доступный остаток вычисляется как limit - spent - reserved, где reserved включает резервирования в состоянии unknown.

3.2 Атомарная проверка и резервирование: защита от одновременного пропуска при конкурентных запросах

Ключевая идея — объединить «проверку» и «занятие» в один условный UPDATE и позволить базе данных обеспечить атомарность:

-- Пример: занимаем только если остатка достаточно, возвращаем число затронутых строк
UPDATE budgets
SET reserved = reserved + :estimate
WHERE owner_id IN (:user_id, :pool_id)
  AND limit_amount - spent - reserved >= :estimate;
-- Число затронутых строк должно быть равно 2 (успешно и для пользователя, и для пула), иначе откатываем транзакцию и отклоняем запрос

Оценочную сумму нужно брать по верхней границе: число входных токенов умножить на цену входного токена, затем прибавить max_tokens, умноженное на цену выходного токена. Фактический расход обычно ниже этой суммы — при расчёте достаточно вернуть разницу. Лучше зарезервировать чуть больше, чем недостаточно.

3.3 Блокировка модели на стороне сервера и масштаб задачи

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

ALLOWED_TRIAL_MODELS = {"trial-model-a"}   # Пример: модели, открытые для пробного режима
MAX_OUTPUT_TOKENS = 1024                   # Пример: принудительный лимит на стороне сервера
MAX_INPUT_TOKENS = 8000

def build_trial_request(user_input, requested_model):
    model = requested_model if requested_model in ALLOWED_TRIAL_MODELS \
        else "trial-model-a"
    input_tokens = count_tokens(user_input)
    if input_tokens > MAX_INPUT_TOKENS:
        raise InputTooLarge()
    estimate = price_in(model) * input_tokens \
             + price_out(model) * MAX_OUTPUT_TOKENS
    return model, MAX_OUTPUT_TOKENS, estimate

max_tokens и model, пришедшие с фронтенда, — лишь справочные значения, окончательное решение принимает сервер.

3.4 Отправка запроса, расчёт и обработка сбоев

Перед отправкой запроса генерируется уникальный ID запроса, который записывается в запись резервирования, — так его потом будет легко найти в логах. После возврата запроса возможны три варианта:

  1. Успех и получен usage: сумма рассчитывается по фактическому расходу, spent += actual, reserved -= estimate, статус резервирования меняется на settled.
  2. Явный сбой без выполнения: например, ошибки валидации параметров или аутентификации — ошибки, по которым можно подтвердить, что запрос не попал в тарификацию. В этом случае резерв освобождается, статус меняется на released.
  3. Таймаут или обрыв соединения: запрос мог уже выполниться на стороне провайдера и породить расходы, просто результат не вернулся. В этом случае не считайте стоимость нулевой: статус помечается как unknown, резерв остаётся занятым.

Третий случай — самый частый источник ошибок. Если при таймауте просто освободить резерв, это равносильно стиранию из учёта расходов, которые могли уже произойти. В периоды высокой нагрузки и частых таймаутов такая погрешность накапливается.

3.5 Офлайн-сверка: исправляем unknown и отклонения оценки

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

  • Выгружать инкрементальные журналы с момента прошлой сверки и сопоставлять их с таблицей reservations по ID запроса или временному окну.
  • Резервирования в статусе unknown, которые нашлись в журналах, переводить в settled по фактической сумме из журнала; если по истечении согласованного временного окна записи так и не появилось — переводить в released.
  • Строить распределение отклонений «оценка против факта». Если фактическая сумма регулярно подбирается к оценке или даже превышает её, стоит вернуться и проверить формулу оценки из раздела 3.3.

Результаты сверки заодно служат входными данными для третьей бюджетной линии: если итог по бухгалтерской книге и фактический расход по аккаунту постоянно не сходятся, это сам по себе сигнал, который требует ручного разбора.

api-key-quota-overspend-three-budget-lines-ru-image-3

4 Проверка бюджетных контуров перед запуском и понятные подсказки при нехватке квоты

4.1 Чек-лист перед запуском для трёх контуров бюджета

Пункт проверки Контур бюджета Как проверить
Резервирование для пользователя и пула выполняется в одной транзакции Первый Нагрузить систему параллельными запросами и убедиться, что потраченное плюс зарезервированное не превышает лимит
model, max_tokens и длина ввода определяются на сервере Первый Подменить параметры на стороне фронтенда и убедиться, что это не даёт эффекта
Запрос с таймаутом помечается как unknown и продолжает удерживать резерв Первый Смоделировать таймаут и проверить состояние леджера
Задача сверки запускается по расписанию и обрабатывает unknown Первый Проверить журнал сверки и переходы статусов
Пробный ключ независим, его квота немного выше бюджета пула Второй Сверить конфигурацию ключа и числовое значение бюджета пула
Белый список моделей для пробного ключа содержит только пробные модели Второй Вызвать модель не из белого списка и убедиться, что запрос отклонён
Скрипт сброса дневной квоты существует и находится под мониторингом Первый и второй Проверить историю выполнения задачи по расписанию
Порог оповещения о балансе соответствует регламенту действий Третий Прорепетировать процесс от срабатывания оповещения до закрытия доступа

4.2 Сообщения пользователю при нехватке квоты

Если резервирование не удалось, приложение должно вернуть понятную бизнес-ошибку, а не пропускать запрос до шлюза, где потом всплывёт трудночитаемая ошибка. В сообщении стоит указать три вещи:

  • Что произошло: например, «дневная пробная квота исчерпана» или «свободных пробных мест сейчас нет». Нехватку квоты у пользователя и переполнение пробного пула нужно показывать разными сообщениями.
  • Когда восстановится: если задана дневная квота, укажите время сброса; если разовая квота закончилась, объясните, какие есть варианты апгрейда.
  • Текущее состояние: можно показать остаток квоты, но только по доступному остатку в леджере с учётом резервов по запросам в обработке, чтобы не было ситуации «баланс показан, а запрос отклонён».

После этих проверок можно простым способом принять весь набор бюджетных контуров: смоделировать пик параллельных запросов вместе с таймаутом на стороне upstream, убедиться, что в леджере «потрачено + зарезервировано по запросам в обработке» никогда не меньше фактического расхода после сверки, а расход пробного ключа не выходит заметно за его квоту. Если выполняются оба условия, три контура бюджета действительно готовы к работе.


Справочные материалы

  1. Документация APIYI по управлению токенами: описание мягкого лимита, remain_quota, ежедневного сброса и белого списка моделей
    • Ссылка: docs.apiyi.com/api-capabilities/token-management
  2. Документация APIYI по предварительному списанию квоты: механизм оценочного резервирования и расчёта постфактум
    • Ссылка: docs.apiyi.com/faq/pre-deduction-quota
  3. Документация APIYI по оповещениям о балансе: уведомляют, но не блокируют
    • Ссылка: docs.apiyi.com/faq/balance-alerts
  4. Документация APIYI по запросам к логам: инкрементальный экспорт и офлайн-сверка
    • Ссылка: docs.apiyi.com/api-capabilities/log-query
  5. OWASP API Security Top 10 2023: API4 Unrestricted Resource Consumption
    • Ссылка: api-security.owasp.org/editions/2023/en/0xa4-unrestricted-resource-consumption/

Всё, что подготовлено заранее, — стоит; что не подготовлено — рушится. — «Ли цзи», глава «Чжун юн»

Похожие записи