Workers AI + AI Gateway — единый шлюз для моделей, лимитов и расходов

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

Руководство актуально на 15 августа 2026 года.

Содержание

1. Что именно объединила Cloudflare
2. Как устроен единый слой
3. Подготовка Worker и AI binding
4. Вызов модели Workers AI
5. Вызов OpenAI, Anthropic и Gemini
6. Fallback между моделями
7. Кэширование, retry и rate limiting
8. Attribution по пользователям и агентам
9. Бюджеты и наблюдаемость
10. Проверка рабочего контура
11. Когда AI Gateway полезен
12. Ограничения и частые ошибки

Единый вход для Workers AI и внешних моделей

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

Основной интерфейс внутри Worker выглядит одинаково:

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

Различается идентификатор модели:

Gateway с именем default создаётся автоматически после первого аутентифицированного запроса. При необходимости можно завести отдельные gateway для production, тестов, команд или приложений.

Архитектура единого слоя

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["Кэш и retry"]
    C --> K["Лимиты и бюджеты"]

AI Gateway находится между приложением и моделями. Приложение передаёт модель, запрос и служебные параметры, а gateway применяет настроенные политики и отправляет вызов нужному провайдеру.

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

Понадобятся:

• аккаунт Cloudflare;
• проект Workers;
• Wrangler;
• AI binding;
• AI Gateway credits для сторонних моделей;
• API-токен с правом Workers AI: Read, если используется REST API.

Добавьте binding в wrangler.jsonc:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ai-control-plane-demo",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-15",
  "ai": {
    "binding": "AI"
  }
}

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

npx wrangler types

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

Минимальный Worker:

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: "Объясни, чем AI Gateway отличается от обычного API-прокси.",
          },
        ],
      },
      {
        gateway: {
          id: "default",
        },
      },
    );

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

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

npx wrangler dev

Первый аутентифицированный запрос через default автоматически создаст gateway. После вызова в панели 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",
};

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

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

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "cf-aig-gateway-id: default" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "Что такое AI control plane?"
      }
    ]
  }'

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

Fallback между моделями

Cloudflare поддерживает два механизма резервного вызова.

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

Universal Endpoint принимает массив шагов. Если первый провайдер вернул ошибку или не уложился в тайм-аут, gateway переходит к следующему.

Заголовок ответа показывает, какой шаг сработал:

• cf-aig-step: 0 — ответила основная модель;
• cf-aig-step: 1 — использован первый fallback;
• cf-aig-step: 2 — использован второй fallback.

Dynamic Routing

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

Из 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 включите аутентификацию gateway и сохраните ключи используемых upstream-провайдеров через BYOK. Маршрут вызывается через OpenAI-compatible endpoint /compat/chat/completions. На 15 августа 2026 года Dynamic Routing недоступен через новые REST endpoints /ai/run, /ai/v1/chat/completions, /ai/v1/responses и /ai/v1/messages.

Кэширование, retry и rate limiting

Кэширование

Для 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 AI Gateway строит ключ из провайдера, endpoint, модели, заголовка авторизации и полного тела запроса. Любое изменение этих данных создаёт отдельную запись. Пользовательский cacheKey переопределяет стандартный механизм, поэтому в него нужно включить все параметры, влияющие на ответ: версию промпта, пользователя, язык, модель и другие значимые признаки. Минимальный TTL составляет 60 секунд, максимальный — один месяц.

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

cf-aig-cache-status: HIT

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

Retry

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

• до пяти попыток;
• задержка до пяти секунд;
• постоянный, линейный или экспоненциальный backoff.

Для 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 общую политику retry можно настроить на уровне gateway. Она повторяет запрос к текущей модели, но сама по себе не переключает модель. Переход к другой модели происходит только в явно настроенной fallback-цепочке через Universal Endpoint или Dynamic Routing. В Universal Endpoint Cloudflare сначала выполняет предусмотренные retry, затем переходит к следующему шагу.

Rate limiting

Rate limiting ограничивает количество запросов за период. Cloudflare поддерживает фиксированное и скользящее окно.

При превышении лимита gateway возвращает:

429 Too Many Requests

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

Attribution по пользователям и агентам

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

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",
      },
    },
  },
);

AI Gateway сохраняет до пяти полей metadata. Значениями могут быть строки, числа и логические значения. Объекты не поддерживаются, а ключи с префиксом cf. зарезервированы Cloudflare.

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

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

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

При исчерпании бюджета AI Gateway возвращает 429. В Dynamic Routing вместо блокировки можно отправить запрос в более дешёвую модель.

На один gateway разрешено до 20 правил расходов. Учёт eventually consistent: короткий всплеск параллельных запросов способен немного превысить установленный бюджет до обновления счётчика. Spend limit работает как оперативный ограничитель, но не гарантирует абсолютную точность финансового барьера.

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

• количество запросов и ошибок;
• задержка;
• входные и выходные токены;
• модель и провайдер;
• примерная стоимость;
• попадания в кэш;
• custom metadata;
• сохранённые промпты и ответы.

Стоимость рассчитывается по токенам и известной цене модели. При BYOK итоговую сумму сверяйте в кабинете провайдера. При Unified Billing проверяйте списания кредитов и счёт Cloudflare.

Unified Billing использует предоплаченные кредиты Cloudflare. На покупку кредитов начисляется комиссия 5%, а стоимость inference внешнего провайдера передаётся без дополнительной наценки.

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

Когда AI Gateway полезен

AI Gateway оправдан, если в системе есть хотя бы одна из задач:

• используются несколько моделей или провайдеров;
• нужен fallback при ошибках и тайм-аутах;
• расходы нужно разделять по пользователям, агентам или командам;
• требуется общий лимит бюджета;
• нужны централизованные логи и метрики;
• повторяющиеся запросы можно кэшировать;
• модель должна переключаться без переписывания приложения.

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

Когда gateway добавляет ненужный слой

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

• у вас небольшой прототип с одной моделью;
• расходы уже контролируются средствами провайдера;
• fallback и кэширование не нужны;
• приложение сильно зависит от специфических возможностей нативного API;
• в компании уже работает другой LLM gateway;
• вы не готовы учитывать ещё один слой аутентификации и конфигурации.

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

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

Официальные источники

• Анонс объединения Workers AI и AI Gateway
• Workers AI binding
• REST API
• Dynamic Routing
• Fallbacks
• Request handling и retry
• Кэширование
• Rate limiting
• Custom metadata
• Spend limits
• Unified Billing
• Логирование

По теме

Следующий шаг

Cloudflare Agents SDK — stateful AI-агенты на Durable Objects

Связанные материалы

• Статья: Cloudflare OS: как компания собрала внутренний ИИ-воркспейс и раздала его всем сотрудникам
• Блог: Cloudflare готовит кошельки для ИИ-агентов
• База знаний: Cloudflare DNS, Workers и Tunnels — три сервиса, которые должен знать каждый разработчик

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov