AI Gateway: один вход для моделей, бюджета и отказоустойчивости

Типичная ситуация: сервис обращается к OpenAI напрямую, затем подключает Anthropic, потом Google — и каждый раз новый ключ, отдельная страница с логами, свой код обработки сбоев. Cloudflare соединила свой Workers AI и AI Gateway в один слой: один вызов, общий баланс, единый набор политик для любых провайдеров.

Через единую точку входа — AI binding внутри Worker или REST API по пути /ai/* — сервис получает кэширование, повторы, лимиты трафика, контроль бюджета, запасные модели и журналирование. Модели Cloudflare, OpenAI и Anthropic вызываются единообразно — отличается только идентификатор.

Важно: материал актуален на 15 августа 2026 года. Unified Billing и Dynamic Routing — свежие возможности, которые Cloudflare продолжает дорабатывать.

Что это

AI Gateway — прослойка между сервисом и поставщиками моделей. Сервис передаёт идентификатор модели, запрос и служебные параметры, а шлюз применяет настроенные политики и перенаправляет вызов нужному провайдеру. Workers AI — запуск моделей на инфраструктуре Cloudflare; через тот же шлюз доступны и внешние поставщики: OpenAI, Anthropic, Google и десятки других.

7 августа 2026 года Cloudflare сообщила о слиянии двух сервисов. Теперь один AI binding и общий набор REST-вызовов по пути /ai/* даёт доступ к моделям на инфраструктуре Cloudflare и моделям внешних поставщиков через тот же код.

Интерфейс внутри Worker выглядит одинаково. Отличие — в идентификаторе модели: модели Cloudflare носят префикс @cf/, внешние — префикс провайдера.

await env.AI.run(model, input, {
  gateway: {
    id: "default",
  },
});

Источник модели	Формат идентификатора	Пример
Workers AI	@cf/автор/модель	@cf/moonshotai/kimi-k2.6
OpenAI	openai/модель	openai/gpt-4.1-mini
Anthropic	anthropic/модель	anthropic/claude-sonnet-4
Google	google/модель	google/gemini-3-flash

Шлюз с именем default появляется сам после первого аутентифицированного запроса. При желании можно создать отдельные шлюзы для production-среды, тестов, команд или приложений: до 10 на бесплатном тарифе, до 20 на платном.

Важно: общий баланс подключается отдельным шагом. Для Workers AI нужно активировать режим Unified billing в настройках шлюза. Вызовы внешних моделей через env.AI.run() расходуют предоплаченные кредиты AI Gateway.

Зачем нужно

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

• Единый вход — модели Cloudflare, OpenAI, Anthropic и Google вызываются через один интерфейс.
• Запасные модели — если основной поставщик недоступен, шлюз переключается на резервный вариант.
• Кэш — повторные идентичные запросы не идут к провайдеру, экономя токены и время.
• Лимиты трафика — ограничение запросов за период: фиксированное или скользящее окно.
• Бюджет — предельная стоимость вызовов по модели, пользователю или команде.
• Журналирование и метрики — модель, токены, задержка, стоимость, попадания в кэш, метаданные — в единой панели.
• Атрибуция — каждый запрос привязан к пользователю, агенту или команде через метаданные.

Как устроено

Архитектура прослойки проста: сервис обращается к AI binding или REST API, запрос проходит через шлюз, шлюз применяет политики и перенаправляет вызов поставщику. Весь маршрут — от кэширования до лимитов — конфигурируется в одном месте.

flowchart LR
    A["Worker или приложение"] --> B["AI binding / REST API"]
    B --> C["AI Gateway"]
    C --> D["Workers AI"]
    C --> E["OpenAI"]
    C --> F["Anthropic"]
    C --> G["Google"]
    C --> H["Другие провайдеры"]
    C --> I["Логи и аналитика"]
    C --> J["Кэш и повтор"]
    C --> K["Лимиты и бюджеты"]

Подготовка Worker и AI binding

Для работы понадобятся: аккаунт Cloudflare, проект Workers, Wrangler, AI binding и кредиты AI Gateway для внешних моделей. Для вызовов через REST API нужен API-токен с правом Workers AI: Read.

Binding добавляется в wrangler.jsonc:

{
  "name": "ai-control-plane-demo",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-15",
  "ai": {
    "binding": "AI"
  }
}

После изменения конфигурации обновите типы:

npx wrangler types

Вызов модели Workers AI

Минимальный Worker для вызова модели Cloudflare:

interface Env {
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const result = await env.AI.run(
      "@cf/moonshotai/kimi-k2.6",
      {
        messages: [
          {
            role: "user",
            content: "Объясни, чем шлюз отличается от обычного прокси.",
          },
        ],
      },
      {
        gateway: {
          id: "default",
        },
      },
    );

    return Response.json(result);
  },
};

Запустите проект локально:

npx wrangler dev

Первый аутентифицированный запрос через default автоматически создаст шлюз. После вызова в панели AI Gateway появится журнал с моделью, временем ответа и числом токенов.

Вызов OpenAI, Anthropic и Gemini

Для внешней модели меняется лишь идентификатор — первая строка:

const result = await env.AI.run(
  "openai/gpt-4.1-mini",
  {
    messages: [
      {
        role: "user",
        content: "Составь краткий чеклист проверки API.",
      },
    ],
  },
  {
    gateway: {
      id: "default",
    },
  },
);

Для Anthropic или Google — соответствующий идентификатор:

const models = {
  openai: "openai/gpt-4.1-mini",
  anthropic: "anthropic/claude-sonnet-4",
  gemini: "google/gemini-3-flash",
};

Внимание: собственные ключи провайдеров (BYOK) через AI binding не поддерживаются. Вызовы внешних моделей через env.AI.run() расходуют Unified Billing и ключи под управлением Cloudflare. Если нужно работать со своим ключом OpenAI, Anthropic или Google — используйте нативный интерфейс провайдера в AI Gateway.

Из внешней среды модели можно вызывать через общий REST API:

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUD...OKEN" \
  --header "cf-aig-gateway-id: default" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "Что такое единый шлюз для моделей?"
      }
    ]
  }'

Под /ai/* работают четыре формата. Универсальный /ai/run принимает любые модели и типы вывода — текст, изображения, синтез речи. OpenAI-совместимый /ai/v1/chat/completions работает с OpenAI SDK. Responses API /ai/v1/responses — для агентных сценариев, также совместим с OpenAI SDK. Anthropic-совместимый /ai/v1/messages — для Anthropic SDK, но не поддерживает модели Workers AI.

Вызов	Формат	Сторонние модели	Модели Workers AI
POST /ai/run	Конверт с моделью и входными данными	Да	Да
POST /ai/v1/chat/completions	OpenAI chat completions	Да	Да
POST /ai/v1/responses	OpenAI Responses API	Да	Зависит от модели
POST /ai/v1/messages	Anthropic Messages API	Да	Нет

Важно: /ai/v1/messages строго использует схему Anthropic и не поддерживает модели @cf/. Для моделей Workers AI используйте /ai/run или /ai/v1/chat/completions.

Резервные модели

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

Последовательность через Universal Endpoint

Universal Endpoint получает массив шагов. Если первый поставщик вернул ошибку или не уложился в тайм-аут, шлюз переходит к следующему шагу. Заголовок ответа указывает, какой шаг сработал: cf-aig-step: 0 — ответила основная модель, cf-aig-step: 1 — первый резерв, cf-aig-step: 2 — второй резерв.

Внимание: Universal Endpoint помечен как устаревший. Cloudflare рекомендует использовать OpenAI-совместимый вызов для новых интеграций и Dynamic Routing для резервных моделей, повторов и условных маршрутов. Universal Endpoint продолжит работать для существующих интеграций.

Dynamic Routing

Dynamic Routing даёт возможность собрать версионируемый маршрут из условий, моделей, ограничений и переходов. В маршрут можно включить основную модель, резервную модель, лимит трафика, бюджет и процентное распределение для A/B-теста. Маршрут настраивается через визуальный интерфейс или JSON-конфигурацию, а вызывается из кода по имени — без изменения приложения.

Из Worker такой маршрут вызывается так:

const response = await env.AI.gateway("my-gateway").run({
  provider: "compat",
  endpoint: "chat/completions",
  headers: {},
  query: {
    model: "dynamic/support",
    messages: [
      {
        role: "user",
        content: "Помоги разобрать ошибку API.",
      },
    ],
  },
});

Для Dynamic Routing включите аутентификацию шлюза и сохраните ключи используемых поставщиков через BYOK. Маршрут вызывается через OpenAI-совместимый интерфейс /compat/chat/completions. На 15 августа 2026 года Dynamic Routing не доступен через новые REST-вызовы /ai/run, /ai/v1/chat/completions, /ai/v1/responses и /ai/v1/messages.

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

Кэш, повтор и ограничение трафика

Кэширование

Шлюз кэширует ответы поставщиков и отдаёт повторные идентичные запросы из своего кэша. Для AI binding доступны параметры cacheTtl, cacheKey и skipCache:

const result = await env.AI.run(
  "openai/gpt-4.1-mini",
  {
    messages: [
      {
        role: "user",
        content: "Какие форматы поддерживает API?",
      },
    ],
  },
  {
    gateway: {
      id: "default",
      cacheTtl: 3600,
    },
  },
);

Без пользовательского cacheKey шлюз формирует ключ из провайдера, интерфейса, модели, заголовка авторизации и полного тела запроса — любое отличие создаёт отдельную запись. Пользовательский cacheKey заменяет стандартный механизм, поэтому в него следует включить все параметры, влияющие на ответ: версию промпта, пользователя, язык, модель и другие значимые признаки. Минимальный TTL — 60 секунд, максимальный — один месяц.

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

Для HTTP-запроса результат кэша проверяется по заголовку: cf-aig-cache-status: HIT означает попадание, MISS — промах. Кэш работает только для текстовых и графических ответов и применяется к точно совпадающим запросам.

Повторные попытки

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

• Количество попыток — максимум 5.
• Задержка — до 5 секунд перед повтором.
• Метод задержки — постоянный, линейный или экспоненциальный.

Для REST API параметры передаются заголовками:

--header "cf-aig-request-timeout: 5000" \
--header "cf-aig-max-attempts: 3" \
--header "cf-aig-retry-delay: 500" \
--header "cf-aig-backoff: exponential"

Для binding общую политику повторов можно настроить на уровне шлюза. Повтор выполняется к текущей модели — сам по себе он не меняет модель. Переход к другой модели происходит только в явно настроенной цепочке через Universal Endpoint или Dynamic Routing. В Universal Endpoint Cloudflare сперва выполняет предусмотренные повторы, затем переходит к следующему шагу.

Ограничение трафика

Ограничение трафика (rate limiting) задаёт лимит запросов за период. Cloudflare поддерживает фиксированное и скользящее окно. При превышении лимита шлюз возвращает 429 Too Many Requests.

Глобальный лимит задаётся в настройках шлюза. Лимиты для отдельных пользователей, агентов или команд проще собирать в Dynamic Routing с ключом из метаданных.

Атрибуция по пользователям и агентам

Custom metadata привязывает каждый запрос к пользователю, агенту, команде или окружению. Метаданные появляются в журналах и служат для фильтрации, аналитики, Dynamic Routing и индивидуальных бюджетов.

const result = await env.AI.run(
  "@cf/moonshotai/kimi-k2.6",
  {
    messages: [
      {
        role: "user",
        content: "Подготовь краткое резюме документа.",
      },
    ],
  },
  {
    gateway: {
      id: "production",
      metadata: {
        user_id: "u_42",
        agent_id: "knowledge-agent",
        team: "content",
        environment: "production",
        request_kind: "summary",
      },
    },
  },
);

Шлюз сохраняет до 5 полей метаданных на запрос. Допустимые типы значений — строки, числа и логические. Объекты не поддерживаются, а ключи с префиксом cf. зарезервированы Cloudflare — шлюз удаляет такие ключи из пользовательских данных.

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

Бюджеты и наблюдаемость

Spend limits управляют расчётной стоимостью запросов по данным о токенах и известной цене модели. Правила можно разделять или фильтровать по модели, поставщику и custom metadata: пользователю, агенту, команде или приложению. При исчерпании бюджета шлюз возвращает 429.

Каждое правило задаёт бюджет в долларах на временной период — фиксированный или скользящий. Шлюз рассчитывает стоимость каждого запроса на основе токенов и цены модели, затем отслеживает накопленные расходы в реальном времени. На один шлюз разрешено до 20 правил расходов.

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

В Dynamic Routing вместо блокировки можно направить запрос в более дешёвую модель. Например, основная модель — дорогая, а при исчерпании бюджета запрос уходит на резервную. Стоимость считается по токенам и известной цене модели. При использовании собственных ключей итоговую сумму сверяйте в кабинете поставщика. При Unified Billing проверяйте списания кредитов и счёт Cloudflare.

В панели доступны:

• Количество запросов и ошибок
• Задержка
• Входные и выходные токены
• Модель и поставщик
• Примерная стоимость
• Попадания в кэш
• Метаданные
• Сохранённые промпты и ответы

Внимание: журналы по умолчанию могут содержать полные тексты промптов и ответов. Для чувствительных данных отключите журналирование либо передайте cf-aig-collect-log-payload: false, чтобы сохранить метаданные, токены, стоимость и длительность без тела запроса.

Unified Billing расходует предоплаченные кредиты Cloudflare. При покупке кредитов начисляется комиссия 5%: при покупке кредита на $100 списания составят $105. Стоимость вызова у внешнего поставщика передаётся без дополнительной наценки — те же повременные тарифы, что и напрямую у поставщика. Zero Data Retention направляет трафик через интерфейсы поставщика, которые не сохраняют промпты и ответы, но не отключает журналы самого шлюза.

Чеклист

Чеклист проверки рабочего контура

После настройки шлюза полезно проверить, что все ключевые возможности работают. Список ниже покрывает основные точки контроля.

Worker возвращает успешный JSON-ответ

— базовый вызов проходит.

Шлюз default или выбранный шлюз появился в панели

— первый запрос создал шлюз.

В журнале видны модель, токены, длительность и стоимость

— журналирование работает.

Метаданные содержат идентификатор пользователя или агента

— атрибуция настроена.

Повторный идентичный запрос возвращает HIT

— для REST по заголовку cf-aig-cache-status, для binding — в журнале шлюза.

Искусственная ошибка основной модели включает резерв

— в ответе присутствует ожидаемый заголовок cf-aig-step.

Ограничение трафика возвращает 429

— после превышения порога.

Бюджет блокирует запрос или переключает на дешёвую модель

— при исчерпании лимита.

Чувствительные данные не сохраняются в журналах — cf-aig-collect-log-payload:

false или журналирование отключено.

Когда шлюз полезен

Шлюз имеет смысл, когда в системе присутствует хотя бы одна из этих задач:

• Несколько моделей или поставщиков — единый вызов для всех.
• Нужен резерв при ошибках и тайм-аутах — автоматическое переключение.
• Расходы нужно разделять по пользователям, агентам или командам — атрибуция через метаданные.
• Требуется общий лимит бюджета — spend limits на шлюзе.
• Нужны централизованные журналы и метрики — одна панель для всех поставщиков.
• Повторяющиеся запросы можно кэшировать — экономия токенов.
• Модель должна переключаться без переписывания приложения — маршрут в Dynamic Routing.

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

Когда шлюз — лишний слой

Прямой вызов поставщика может оказаться проще, если:

• Небольшой прототип с одной моделью
• Расходы уже контролируются средствами поставщика
• Резерв и кэш не нужны
• Приложение сильно зависит от специфических возможностей нативного API
• В компании уже работает другой шлюз для моделей
• Вы не готовы учитывать ещё один слой аутентификации и конфигурации

Практичный путь — начать с шлюза default и наблюдаемости. Кэш, маршруты и бюджеты добавлять после появления понятной задачи.

Частые ошибки

Ошибка	Что проверить
401 при REST-вызове	У токена есть право Workers AI: Read
Сторонняя модель не запускается	На балансе есть кредиты AI Gateway
Собственные ключи не работают через env.AI.run()	Используйте нативный интерфейс провайдера
Запросы не видны в журналах	Включено журналирование и не достигнут лимит хранения
Кэш постоянно возвращает MISS	Проверьте полное совпадение запроса или используемый cacheKey
Шлюз отвечает 429	Превышен лимит трафика, бюджет или лимит модели
Резерв не включается	Настроена явная цепочка Universal Endpoint или Dynamic Routing, маршрут опубликован, а ошибка соответствует условию перехода
Расходы отличаются от счёта	Метрика шлюза — оценка, а не точная сумма

Если вы строите агентную платформу или подключаете к продукту несколько моделей, единый шлюз помогает заранее определить правила расходов, отказоустойчивости и доступа.

Ограничения

Ограничения

Что учитывать

Что учитывать при планировании.

Собственные ключи через AI binding не поддерживаются — Вызовы сторонних моделей через env.AI.run() используют Unified Billing и ключи, которыми управляет Cloudflare.

Для работы со своим ключом OpenAI, Anthropic или Google нужен нативный интерфейс провайдера. Это ограничение архитектуры binding, а не временный недостаток.

Dynamic Routing недоступен через новые REST-вызовы — На 15 августа 2026 года маршруты Dynamic Routing вызываются только через OpenAI-совместимый интерфейс /compat/chat/completions.

Новые вызовы /ai/run, /ai/v1/chat/completions, /ai/v1/responses и /ai/v1/messages поддержку Dynamic Routing пока не получили.

Universal Endpoint помечен как устаревший — Cloudflare рекомендует переходить на OpenAI-совместимый вызов и Dynamic Routing.

Старый интерфейс продолжит работать для существующих интеграций, но новые возможности будут добавляться в Dynamic Routing.

Учёт расходов не мгновенный — Spend limit работает с задержкой обновления счётчика.

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

Шлюзов на аккаунт — не более 20 на платном тарифе — На бесплатном — 10.

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

Кэш работает только для текста и изображений — Точные совпадения запросов кэшируются.

Семантический поиск для кэша заявлен как будущая возможность. Для динамических и персонализированных ответов кэш бесполезен.

Антипаттерны

Антипаттерны

Чего не делать

Чего не делать.

Использовать общий cacheKey для персонализированных запросов — Разные пользователи с одинаковым ключом получат один и тот же закэшированный ответ.

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

Рассчитывать на точный финансовый барьер от spend limit — Метрика шлюза — оценка по токенам и цене модели, а не точный счёт.

При использовании собственных ключей итоговую сумму нужно сверять в кабинете поставщика. При Unified Billing — в счёте Cloudflare. Spend limit — оперативный ограничитель, но не бухгалтерия.

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

Для конфиденциальных данных отключите журналирование или передайте cf-aig-collect-log-payload: false, чтобы сохранить метаданные без тела запроса.

Пользоваться AI binding с ожиданием BYOK — Через env.AI.run() собственные ключи поставщиков не работают.

Если архитектура требует свои ключи — используйте нативные интерфейсы поставщиков в шлюзе. Попытка передать ключ в заголовке через binding приведёт к падению вызова.

Чеклист

Чеклист

Проверка перед запуском

Проверка перед запуском.

AI binding добавлен в wrangler.jsonc — В конфигурации Worker есть блок ai с binding AI.

Типы обновлены через npx wrangler types.

Кредиты AI Gateway пополнены — Для вызова сторонних моделей через Unified Billing на балансе есть кредиты.

Для Workers AI в настройках шлюза выбран режим Unified billing.

API-токен имеет право Workers AI: Read — Для REST-вызовов через /ai/* нужен токен с этим разрешением.

Только разрешение AI Gateway вернёт 401.

Идентификатор модели указан верно — Модели Cloudflare — с префиксом @cf/, сторонние — с префиксом провайдера.

Актуальные идентификаторы проверяются в каталоге моделей Cloudflare.

Метаданные содержат не более 5 полей — Шлюз сохраняет до 5 записей метаданных на запрос.

Типы значений — строки, числа, логические. Объекты не поддерживаются. Ключи с префиксом cf. зарезервированы.

cacheKey учитывает все параметры ответа — Пользовательский ключ кэша включает пользователя, версию промпта, язык, модель.

Минимальный TTL — 60 секунд, максимальный — один месяц.

Резервная цепочка явно настроена — Для автоматического переключения настроен Universal Endpoint или Dynamic Routing.

Маршрут опубликован, условие перехода соответствует типу ожидаемой ошибки.

Чувствительные данные защищены в журналах — Передан заголовок cf-aig-collect-log-payload: false или журналирование отключено.

Метаданные, токены и стоимость сохраняются без тела запроса.

Ссылки

Ссылки

• Документация: Cloudflare AI Gateway — Overview
• Документация: AI Gateway — REST API
• Документация: AI Gateway — Workers Bindings
• Документация: AI Gateway — Dynamic Routing
• Документация: AI Gateway — Fallbacks
• Документация: AI Gateway — Caching
• Документация: AI Gateway — Rate Limiting
• Документация: AI Gateway — Spend Limits
• Документация: AI Gateway — Unified Billing
• Документация: AI Gateway — Custom Metadata
• Документация: AI Gateway — Limits
• Документация: AI Gateway — Pricing
• Документация: Workers AI — Overview

По теме

По теме

• База знаний: Cloudflare DNS, Workers и Tunnels — три сервиса для разработчика
• База знаний: Cloudflare Pages: хостинг из GitHub бесплатно
• База знаний: Cloudflare Agents SDK: агенты с состоянием на Durable Objects
• База знаний: API простыми словами: как сервисы разговаривают
• База знаний: Webhook: как системы получают сигналы в момент события