Инфраструктура · AWS · AI Gateway

AI Gateway на ECS Fargate: бюджеты приложений, retries и проверка изоляции

AI Gateway на ECS Fargate: бюджеты приложений, retries и проверка изоляции
Temporary fallback cover; replace in editorial pass.
Уровень: продвинутый Время чтения: до 12 минут Формат: воспроизводимый практический сценарий
Самое важное из мира AI — в канале MAX AgentLabОтдельные разборы, инструменты и практические схемы Читайте Agent Lab в Telegram Разборы, кейсы и новости о практических AI-агентах без лишней воды.

AI Gateway — это общий HTTP-шлюз между приложениями и провайдерами моделей. Для команды он удобен: клиенты получают единый OpenAI-совместимый API, а маршрутизация, лимиты и обработка ошибок остаются в одном месте.

Проблема появляется, когда один ключ начинает расходовать общий лимит или провайдер временно отвечает ошибками. Шлюз должен остановить конкретное приложение, не затронув остальные, и повторять только те запросы, которые безопасно повторять. Ниже — схема для ECS Fargate с Amazon Bedrock, бюджетами на ключ, retry/fallback и тестами изоляции.

Что строим

Минимальная схема состоит из четырёх частей:

client
  │  Authorization: Bearer app_key_...
  ▼
ALB → ECS Fargate: gateway
          ├── budget store
          ├── retry policy
          └── Bedrock adapter
                    └── Amazon Bedrock

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

Модель бюджета на ключ

Для каждого приложения заведите запись с явным состоянием:

{
  "key_id": "app-a",
  "period": "2026-11",
  "limit_units": 100000,
  "used_units": 4200,
  "reserved_units": 800,
  "status": "active"
}

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

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

available = limit_units - used_units - reserved_units

if available < estimated_request_units:
    return 429, "application budget exceeded"

reserve(estimated_request_units)
send_request()
commit(actual_usage)
release(reserved_minus_actual)

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

Почему нужен резерв

Без резерва два параллельных запроса могут одновременно увидеть один и тот же остаток. Оба пройдут проверку, а итоговый расход превысит лимит. Резерв не делает оценку точной, но предотвращает очевидное перепродавание доступного бюджета.

Отдельно храните:

OpenAI-совместимый контракт

Клиенту не нужно знать, что за шлюзом находится Bedrock. Снаружи оставьте привычный маршрут, например POST /v1/chat/completions, и нормализуйте ответ в одном формате.

curl --fail-with-body \
  -X POST "https://gateway.example.invalid/v1/chat/completions" \
  -H "Authorization: Bearer ${APP_A_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "gateway-default",
    "messages": [
      {"role": "user", "content": "Проверка шлюза"}
    ],
    "max_tokens": 64
  }'

Домен и ключ в команде — placeholders. Не вставляйте секрет в shell history, CI-логи или документацию. Для ручной проверки передавайте ключ через переменную окружения, секрет-менеджер или безопасный механизм вашего CI.

Внутри шлюз должен разделять ошибки по смыслу:

Ситуация Ответ клиенту Повторять?
Бюджет приложения исчерпан 429 Нет
Неверный ключ или формат запроса 401 или 400 Нет
Временная ошибка провайдера 502 или 503 после исчерпания попыток Ограниченно
Превышен лимит провайдера 429 или 503 после обработки Retry-After Ограниченно
Сбой в шлюзе 500 Только если операция безопасна

Retry без лавины запросов

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

Практичная базовая политика:

max_attempts: 3
backoff: exponential
jitter: full
retryable:
  - timeout
  - connection_reset
  - 429
  - 502
  - 503
  - 504
never_retry:
  - 400
  - 401
  - 403
  - invalid_request
  - budget_exceeded

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

Считайте каждую попытку в метриках, но не списывайте бюджет несколько раз за один логический запрос, если провайдерская модель учёта этого не требует. На уровне журнала полезно хранить request_id, attempt, provider_status и final_status.

Fallback

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

primary model
  ├── success → return response
  ├── retryable error → bounded retry
  └── still unavailable → fallback, if allowed
                                  └── failure → normalized 503

Решение о fallback принимайте до списания окончательного usage. Если первая попытка была принята провайдером, но ответ потерялся, повтор может создать дубликат операции. Для chat completion это обычно означает повтор генерации, поэтому клиенту нужно сообщить о неопределённом результате, если ваша бизнес-логика не допускает такой риск.

Развёртывание на ECS Fargate

Для задачи Fargate задайте отдельную IAM task role с минимальными разрешениями на вызов нужных моделей Bedrock. Не помещайте долгоживущие ключи AWS в переменные окружения контейнера. Секреты приложения храните в Secrets Manager или другом согласованном хранилище, а задаче выдавайте доступ через IAM.

В task definition должны быть как минимум:

Пример фрагмента конфигурации:

{
  "name": "ai-gateway",
  "image": ["https://agentlabjournal.online/assets/covers/llm-context-window-budget-social.png"],
  "essential": true,
  "portMappings": [
    {"containerPort": 8080, "protocol": "tcp"}
  ],
  "environment": [
    {"name": "PORT", "value": "8080"},
    {"name": "BUDGET_STORE_URL", "value": "rediss://budget-store.internal"}
  ],
  "secrets": [
    {"name": "GATEWAY_SIGNING_KEY", "valueFrom": "SECRET_ARN"}
  ],
  "healthCheck": {
    "command": ["CMD-SHELL", "curl -fsS http://localhost:8080/health || exit 1"],
    "interval": 30,
    "timeout": 5,
    "retries": 3
  }
}

Значения REGISTRY, IMAGE_TAG, SECRET_ARN и URL — placeholders. Перед применением проверьте, что security group разрешает только необходимые направления: вход от балансировщика, выход к Bedrock и хранилищу бюджета.

Безопасная последовательность обновления:

# Примеры команд. Перед запуском проверьте регион и имена ресурсов.
aws ecs describe-services \
  --cluster "$ECS_CLUSTER" \
  --services "$ECS_SERVICE" \
  --region "$AWS_REGION"

aws ecs update-service \
  --cluster "$ECS_CLUSTER" \
  --service "$ECS_SERVICE" \
  --force-new-deployment \
  --region "$AWS_REGION"

aws ecs wait services-stable \
  --cluster "$ECS_CLUSTER" \
  --services "$ECS_SERVICE" \
  --region "$AWS_REGION"

Команды ничего не удаляют, но всё равно требуют проверки переменных. Не используйте --force-new-deployment как замену контролируемому rollout, если изменение образа или конфигурации должно пройти через ваш обычный pipeline.

Проверка изоляции бюджетов

Создайте минимум два тестовых ключа: app-a и app-b. Установите для них разные тестовые лимиты в вашем budget store. Значения лимитов — часть тестового стенда, а не универсальная рекомендация.

Сценарий проверки:

  1. Отправьте запрос от app-a и убедитесь, что бюджет уменьшился только у него.
  2. Создайте параллельную нагрузку от app-a, достаточную для перехода в состояние budget exceeded.
  3. Проверьте, что новые запросы app-a получают 429 без обращения к Bedrock.
  4. Сразу отправьте запрос от app-b.
  5. Убедитесь, что app-b получает нормальный ответ, а его счётчик не смешивается с app-a.
for i in $(seq 1 20); do
  curl --silent --show-error --fail-with-body \
    -X POST "$GATEWAY_URL/v1/chat/completions" \
    -H "Authorization: Bearer $APP_A_KEY" \
    -H "Content-Type: application/json" \
    --data '{"model":"gateway-default","messages":[{"role":"user","content":"budget test"}],"max_tokens":16}' &
done
wait

curl --silent --show-error --fail-with-body \
  -X POST "$GATEWAY_URL/v1/chat/completions" \
  -H "Authorization: Bearer $APP_B_KEY" \
  -H "Content-Type: application/json" \
  --data '{"model":"gateway-default","messages":[{"role":"user","content":"isolation test"}],"max_tokens":16}'

Количество запросов в примере не означает конкретную нагрузочную норму. Подберите его под искусственно уменьшенный лимит тестового стенда. Не запускайте этот цикл на рабочем ключе: даже при корректном budget guard он создаёт реальный трафик.

Тест считается успешным, если одновременно выполнены четыре условия:

Тесты retry и fallback

Не пытайтесь проверять retry реальным отключением продакшен-провайдера. В тестовом окружении используйте адаптер или управляемый mock, который возвращает последовательность статусов.

case_1:
  responses: [503, 200]
  expected_attempts: 2
  expected_result: 200

case_2:
  responses: [429, 429, 503]
  expected_attempts: 3
  expected_result: 503

case_3:
  responses: [400]
  expected_attempts: 1
  expected_result: 400

case_4:
  primary: [503, 503, 503]
  fallback: [200]
  expected_result: fallback_success

Проверьте не только финальный HTTP-код. Зафиксируйте число попыток, задержки, обработку Retry-After, списание бюджета и отсутствие retry для 400/401/403. Для fallback дополнительно проверьте, что ответ содержит признак использованного маршрута, если это нужно клиенту и не раскрывает внутреннюю конфигурацию.

Наблюдаемость

Минимальный набор метрик:

Не помещайте полный API-ключ в логи. Используйте стабильный внутренний key_id, а сам запрос связывайте с корреляционным идентификатором. Текст пользовательского prompt также не должен попадать в логи по умолчанию: он может содержать персональные или коммерческие данные.

Типовые ошибки

Лимит хранится внутри контейнера

После масштабирования каждый экземпляр видит свой счётчик. Вынесите состояние в общий store и добавьте атомарный reserve/commit.

Retry повторяет любую ошибку

Так появляются лишние запросы при неверном payload и быстрый расход бюджета. Составьте allowlist временных ошибок и ограничьте общий deadline.

Fallback меняет модель при любой проблеме

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

Бюджет списывается до проверки результата

При retry и fallback это приводит к двойному учёту или расходящимся данным. Разделите резерв, фактическое списание и освобождение остатка резерва.

Health check проверяет только процесс

Процесс может отвечать на /health, но не иметь сетевого доступа к Bedrock или store. Добавьте отдельную диагностическую проверку зависимости, не делая её причиной бесконечного рестарта при кратком внешнем сбое.

Очистка ресурсов

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

# Сначала прочитайте текущую конфигурацию.
aws ecs describe-services \
  --cluster "$TEST_CLUSTER" \
  --services "$TEST_SERVICE" \
  --region "$AWS_REGION"

# После проверки остановите сервис тестового окружения.
aws ecs update-service \
  --cluster "$TEST_CLUSTER" \
  --service "$TEST_SERVICE" \
  --desired-count 0 \
  --region "$AWS_REGION"

Очистка обычно включает временный ECS service, тестовые task definitions, load balancer listeners, security groups, временный store и тестовые секреты. Не удаляйте общую VPC, shared security group или production secret только по совпадению имени. Для каждого ресурса сначала подтвердите владельца, окружение и зависимости.

Ограничения решения

Бюджет на ключ не заменяет биллинг провайдера: фактический счёт и задержка поступления usage могут отличаться от локального счётчика. Retry не гарантирует доставку ответа и может повторить генерацию после неопределённого сетевого сбоя. Fargate упрощает запуск контейнеров, но не решает автоматически вопросы IAM, сетевой маршрутизации, секретов и наблюдаемости.

Перед рабочим запуском отдельно проверьте требования к потоковым ответам, большие payload, отмену запроса клиентом, idempotency, лимиты контекста и поведение при перезапуске задачи. Эти случаи часто меняют правила резервирования и повторов.

Итоговая проверка

Шлюз можно считать готовым к следующему этапу, когда:

Сохраните сценарии изоляции и retry как автоматические интеграционные тесты. Тогда изменение адаптера Bedrock, лимитов или retry-политики не останется непроверенным до первой реальной аварии.

Продолжение: другие практические гайды Agent Lab Journal и определения терминов в глоссарии.