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

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

Руководство актуально на 8 сентября 2026 года и основано на официальной документации Cloudflare. Описанные настройки не проверялись автором на отдельном рабочем аккаунте.

Содержание

1. Что объединила Cloudflare
2. Как устроен единый слой
3. Подготовка Worker и AI binding
4. Вызов Workers AI и сторонних моделей
5. REST API и совместимость конечных точек
6. Резервные вызовы и динамическая маршрутизация
7. Кэширование, повторные попытки и ограничение частоты запросов
8. Связь запросов с пользователями и агентами
9. Бюджеты, логи и расходы
10. Полезные сценарии
11. Проверка рабочего контура
12. Ограничения и частые ошибки

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

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

Основной интерфейс внутри 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["Кэш и повторные попытки"]
    C --> K["Лимиты и бюджеты"]

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

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

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

• аккаунт Cloudflare;
• проект Workers и Wrangler;
• AI binding;
• кредиты AI Gateway для Unified Billing либо сохранённый BYOK-ключ для сценариев, где он нужен;
• API-токен с правом Account > Workers AI > Read, если используется REST API /accounts/{account_id}/ai/*.

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

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ai-control-plane-demo",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-08",
  "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

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

Вызов OpenAI, Anthropic и Google

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

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

Примеры идентификаторов:

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

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

REST API и совместимость конечных точек

Из внешней среды модель можно вызвать через 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?"}]}'

Доступны четыре формата:

Все /accounts/{account_id}/ai/* endpoints требуют право Account > Workers AI > Read, в том числе при вызове сторонних моделей. Токен только с разрешением AI Gateway вернёт 401 с кодом 10000.

Для сторонних моделей запрос без cf-aig-gateway-id направляется через gateway по умолчанию. Для моделей Workers AI заголовок cf-aig-gateway-id обязателен.

Резервные вызовы и динамическая маршрутизация

Cloudflare поддерживает резервные сценарии через Universal Endpoint и Dynamic Routing.

Цепочка через Universal Endpoint

Universal Endpoint можно объединить с OpenAI-compatible endpoint для резервных вызовов между несколькими провайдерами. Используйте его, когда при сбое основного провайдера нужно перейти к следующему варианту.

Dynamic Routing

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

Для Dynamic Routing включите аутентификацию gateway и сохраните ключи upstream-провайдеров через BYOK. Маршрут вызывается через /compat/chat/completions, а его имя передаётся вместо модели, например dynamic/support.

По состоянию на 8 сентября 2026 года Dynamic Routing недоступен через REST API /ai/run, /ai/v1/chat/completions, /ai/v1/responses и /ai/v1/messages. OpenAI-compatible endpoint /compat/chat/completions помечен как deprecated для обычных одиночных вызовов, но остаётся обязательным для динамических маршрутов.

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

Кэширование

Для 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,
    },
  },
);

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

В User Insights доступна метрика cache hit rate. Используйте её, чтобы проверить, что повторяющиеся запросы действительно попадают в кэш.

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

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

AI Gateway поддерживает:

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

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

curl "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/v1/chat/completions" --header "cf-aig-request-timeout: 5000" --header "cf-aig-max-attempts: 3" --header "cf-aig-retry-delay: 500" --header "cf-aig-backoff: exponential"

Повторная попытка обращается к текущей модели. Для переключения между моделями требуется явная fallback-цепочка или Dynamic Routing.

Ограничение частоты запросов

При превышении настроенного лимита gateway может вернуть отказ или перевести запрос на fallback в соответствии с конфигурацией. Глобальный лимит задаётся в настройках gateway. Индивидуальные ограничения можно строить в Dynamic Routing с ключом из metadata.

Отдельно действует платформенный лимит Unified Billing: 200 запросов за 60 секунд на gateway для вызовов с управляемыми Cloudflare учётными данными. При превышении этого лимита AI Gateway возвращает 429. На BYOK этот лимит не распространяется.

Связь запросов с пользователями и агентами

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 принимает до пяти полей custom metadata на запрос. Они доступны для фильтрации логов, аналитики, маршрутизации и правил расходов.

Бюджеты, логи и расходы

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

При исчерпании бюджета запрос блокируется. В Dynamic Routing можно настроить переход на более дешёвую модель. Spend limits работают с Unified Billing и BYOK для моделей с известной ценой.

В логах и аналитике доступны количество запросов и ошибок, задержка, входные и выходные токены, модель, провайдер и стоимость. User Insights дополнительно показывает затраты, модели, провайдеров и cache hit rate по пользователям.

С 1 сентября 2026 года месячные счета AI Gateway показывают одну итоговую строку стоимости для каждой модели вместо отдельных строк для входных и выходных токенов. Названия моделей в счетах и логах приведены к формату provider/model. Это изменение не относится к счетам за покупку кредитов.

Полезные сценарии

Несколько провайдеров с общим контролем

Задача: приложение использует несколько моделей. Передавайте идентификатор нужной модели через один binding или REST API, а логирование, кэш и ограничения настраивайте в gateway. Результат: в логах видны модель, провайдер, токены и длительность запроса.

Ограничение: отдельные provider-native функции могут поддерживаться не во всех унифицированных endpoints.

Резервная модель при сбое

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

Ограничение: обычная повторная попытка сама по себе не переключает модель.

Расходы по пользователям и агентам

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

Ограничение: в одном запросе доступно не более пяти полей metadata.

Проверка рабочего контура

Когда AI Gateway добавляет лишний слой

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

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

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

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

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

• AI Gateway Changelog
• Workers AI binding
• REST API
• Dynamic Routing
• Лимиты AI Gateway
• Каталог моделей Cloudflare

По теме

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

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

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

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

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

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