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

AI Gateway — это общий HTTP-шлюз между приложениями и провайдерами моделей. Для команды он удобен: клиенты получают единый OpenAI-совместимый API, а маршрутизация, лимиты и обработка ошибок остаются в одном месте.
Проблема появляется, когда один ключ начинает расходовать общий лимит или провайдер временно отвечает ошибками. Шлюз должен остановить конкретное приложение, не затронув остальные, и повторять только те запросы, которые безопасно повторять. Ниже — схема для ECS Fargate с Amazon Bedrock, бюджетами на ключ, retry/fallback и тестами изоляции.
Что строим
Минимальная схема состоит из четырёх частей:
- приложения вызывают один OpenAI-совместимый endpoint;
- шлюз извлекает идентификатор приложения из API-ключа;
- Redis или совместимое хранилище атомарно учитывает бюджет и rate limit;
- адаптер Bedrock выполняет запрос, применяя ограниченную retry-политику.
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)
Если провайдер не вернул фактическое использование, не списывайте «примерное» значение молча. Запишите событие с признаком неполного учёта и выберите заранее определённое правило: например, закрывать резерв по верхней границе или отправлять запрос на ручную сверку.
Почему нужен резерв
Без резерва два параллельных запроса могут одновременно увидеть один и тот же остаток. Оба пройдут проверку, а итоговый расход превысит лимит. Резерв не делает оценку точной, но предотвращает очевидное перепродавание доступного бюджета.
Отдельно храните:
- использованный объём;
- объём, временно зарезервированный активными запросами;
- идентификатор операции и время её изменения;
- причину отказа: бюджет, rate limit, провайдер или внутренняя ошибка.
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 должны быть как минимум:
- образ шлюза с фиксированным тегом или digest;
- порт приложения;
- health check;
- лимиты CPU и памяти;
- переменные конфигурации без секретных значений;
- логирование stdout/stderr;
- task role для вызова Bedrock и чтения нужных секретов.
Пример фрагмента конфигурации:
{
"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. Значения лимитов — часть тестового стенда, а не универсальная рекомендация.
Сценарий проверки:
- Отправьте запрос от
app-aи убедитесь, что бюджет уменьшился только у него. - Создайте параллельную нагрузку от
app-a, достаточную для перехода в состояние budget exceeded. - Проверьте, что новые запросы
app-aполучают 429 без обращения к Bedrock. - Сразу отправьте запрос от
app-b. - Убедитесь, что
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 он создаёт реальный трафик.
Тест считается успешным, если одновременно выполнены четыре условия:
- все отклонённые запросы принадлежат только исчерпавшему лимит ключу;
- после отказа нет новых вызовов Bedrock для этого ключа;
- второй ключ продолжает обслуживаться;
- итоговые счётчики сходятся с журналом операций и резервов.
Тесты 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 дополнительно проверьте, что ответ содержит признак использованного маршрута, если это нужно клиенту и не раскрывает внутреннюю конфигурацию.
Наблюдаемость
Минимальный набор метрик:
gateway_requests_totalс разрезом по приложению и финальному статусу;gateway_retry_attempts_totalс разрезом по причине;gateway_budget_usedиgateway_budget_remaining;gateway_provider_latency_seconds;gateway_fallback_total;gateway_inflight_reservations.
Не помещайте полный 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, лимиты контекста и поведение при перезапуске задачи. Эти случаи часто меняют правила резервирования и повторов.
Итоговая проверка
Шлюз можно считать готовым к следующему этапу, когда:
- клиенты используют единый OpenAI-совместимый endpoint;
- каждый ключ имеет отдельный счётчик и атомарный резерв;
- исчерпание бюджета возвращает 429 до вызова провайдера;
- retry ограничен типами ошибок, числом попыток и общим deadline;
- fallback включается только для разрешённых маршрутов;
- тестовый ключ с исчерпанным лимитом не блокирует другой ключ;
- логи и метрики не раскрывают секреты и пользовательские prompts;
- ресурсы тестового окружения можно безопасно удалить.
Сохраните сценарии изоляции и retry как автоматические интеграционные тесты. Тогда изменение адаптера Bedrock, лимитов или retry-политики не останется непроверенным до первой реальной аварии.
Продолжение: другие практические гайды Agent Lab Journal и определения терминов в глоссарии.