Бюджетные алерты AI API по проектам: контроль расходов без блокировки вслепую

Определите, что именно считает проект

Проект — не строка, которую клиент передал в JSON. Сервер сопоставляет аутентифицированного пользователя, API key вашего приложения и разрешённый внутренний project ID. Для каждой операции сохраните время, маршрут, model ID, тип задачи, request ID, безопасный объём измерения и версию правил расчёта. Не записывайте полный prompt или результат только ради финансовой сводки.

Выберите один источник оперативного сигнала: например, внутренний журнал завершённых операций. Он может отставать от окончательного биллинга, поэтому показывайте в интерфейсе «оценку по данным приложения» и время обновления. Не утверждайте, что она равна счёту RussiaAPI. Структуру затрат и допустимые агрегаты полезно связать с мониторингом стоимости AI API.

Пороги должны выражать действие

Три одинаковых письма на 50%, 80% и 100% мало помогают, если никто не знает, что делать. Для каждого порога определите владельца, канал и разрешённый шаг. Например, раннее предупреждение предлагает проверить новый rollout; высокий порог приостанавливает только необязательную внутреннюю очередь; критический создаёт задачу дежурному. Автоматическое отключение основного сервиса без подтверждения может причинить больше вреда, чем всплеск расходов.

Порог должен учитывать период и задержку учёта. Дневной лимит, недельная оценка и месячный бюджет отвечают на разные вопросы. Не переносите число из одной среды в другую: staging, внутренний тест и production имеют разный поток. Отправляйте одно дедуплицированное уведомление на состояние, а не событие на каждый запрос; иначе алерт сам становится источником шума.

Разберите расход до эскалации

После сигнала сначала посмотрите агрегаты: какой проект, маршрут, версия приложения, модель, код ответа и временной интервал изменились. Затем выберите небольшой набор безопасных request ID для технической проверки. Не давайте финансовому оператору доступ к чужим payload, ключам или пользовательскому контенту. Если рост пришёл из retry, ищите категорию ошибки и поведение очереди, а не обвиняйте модель без фактов.

Частая причина — двойная отправка после timeout или повтор callback. Внутренний idempotency key и состояние операции позволяют отличить новый спрос от технического дубля. Для запроса 429 действие обычно состоит в замедлении и очереди, а не в агрессивном повторе. Связанный подход приведён в разборе 429 и backoff.

Пример агрегатора и дедупликации

Пример показывает локальный счётчик предупреждения, а не биллинговый API и не гарантирует цену. Функция получает только уже авторизованное серверное событие, округляет оценку по вашим правилам и создаёт один alert на проект и период. В рабочем коде транзакция и уникальный индекс должны защищать от параллельных worker.

export async function recordUsage({ projectId, operationId, estimatedUnits }) {
  if (!projectId || !operationId || !Number.isFinite(estimatedUnits) || estimatedUnits < 0) {
    return { recorded: false };
  }
  return db.transaction(async (tx) => {
    const inserted = await tx.insertUsageOnce({ projectId, operationId, estimatedUnits });
    if (!inserted) return { recorded: true, duplicate: true };
    const total = await tx.monthToDateEstimate(projectId);
    const budget = await tx.projectBudget(projectId); // your policy, not a provider price promise
    if (budget && total >= budget * 0.8) {
      await tx.insertAlertOnce({ key: `budget-80:${projectId}:${currentMonth()}`, projectId, total, budget });
    }
    return { recorded: true, total, budget };
  });
}

Замените демонстрационные функции базы реальными транзакциями, а стоимость — значением из вашей актуальной учётной логики. Если внешний ответ не даёт нужного usage, не придумывайте число: фиксируйте неполноту данных и направляйте оператора к текущей консоли. Обзор безопасной телеметрии есть в материале об OpenTelemetry.

Сочетайте алерт с управлением спросом

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

Отдельно проверяйте права на запуск дорогих video-задач и на получение результата. Бюджет не заменяет авторизацию: проект с большим лимитом не должен видеть задачи другого tenant. Для асинхронных маршрутов сохраняйте внутреннее состояние и не создавайте новую задачу из-за одного сетевого timeout.

Регулярно сверяйте оценку и факт

Документированный контракт важнее удачного единичного запроса. Перед изменением зафиксируйте версию клиента, базовый URL, выбранный model ID, ожидаемый код ответа, обязательные поля и то, что приложение считает безопасной ошибкой. Не подменяйте проверку предположениями по чужому примеру: каталог, права, параметры и поведение конкретной модели могут измениться.

Тестовый контур должен использовать обезличенный вход, отдельный собственный ключ и ограниченный бюджет. Он не должен записывать Authorization, полный prompt, ответ с персональными данными или временную ссылку на результат. Это делает проверку воспроизводимой и одновременно уменьшает риск утечки в CI, журнале или тикете.

Наблюдаемость полезна, когда по ней можно принять решение. Храните внутренний request ID, статус, длительность, тип операции, версию маршрута и безопасный итог проверки. Связывайте их с проектом только после серверной авторизации. Не делайте метрику или очередь общим каналом для данных разных tenant.

Ошибки 400, 401, 403, 429 и 5xx имеют разные действия. Не запускайте бесконечный retry и не меняйте модель молча: timeout может означать неопределённость, а повторная асинхронная задача способна создать дубль. Для проверки сначала прочитайте своё внутреннее состояние и текущую документацию, затем выполните ограниченный шаг, разрешённый вашей политикой.

До релиза выполните короткий негативный набор: отсутствующая переменная окружения, неподходящий model ID, лишнее поле, недоступный маршрут, timeout и повтор одного запроса. Проверяйте не только HTTP-статус, но и то, что клиент не вывел секрет, не смешал владельцев и не сообщил пользователю неподтверждённую готовность результата.

Эта инженерная практика не обходит лимиты, правила поставщика, применимое право или ограничения платформ. Если контракт, цена, доступность или политика обработки данных изменились, остановите рискованный rollout, обновите тест и подтвердите сценарий в актуальном каталоге RussiaAPI и своих договорных материалах.