Workers AI и AI Gateway: модели, маршруты и контроль расходов

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

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

Руководство рассчитано на разработчика, который уже понимает Worker и HTTP. Binding — привязка сервиса к окружению Worker; gateway — промежуточный слой управления вызовами. BYOK (bring your own key) использует ключ провайдера, Unified Billing — средства 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, поддерживаемый Node.js ≥22 и 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-10-03",
  "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);
  },
};

Перед запуском учтите: AI binding вызывает удалённую модель и при wrangler dev. Локальный сервер не делает выполнение модели бесплатным или автономным. Показанная Kimi K2.6 требует Workers Paid либо предоплаченных кредитов AI Gateway. Не размещайте такой endpoint публично без проверки пользователя и ограничения запросов: посетитель сможет расходовать ваши средства.

Запустите проект, когда выбран источник оплаты:

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.6",
  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. Имя маршрута передаётся вместо модели, например dynamic/support. Вызов должен указывать gateway, которому принадлежит маршрут: gateway.id для binding или cf-aig-gateway-id для REST. Маршруты между gateway не разделяются.

На дату проверки Dynamic Routing принимает формат OpenAI Chat Completions и доступен через env.AI.run("dynamic/support", ...), REST /ai/v1/chat/completions и совместимый /compat/chat/completions. Форматы Anthropic Messages и другие несовместимые тела возвращают 400. Текущая схема вызова.

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

Кэширование

Для 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 -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" --header "cf-aig-request-timeout: 5000" --header "cf-aig-max-attempts: 3" --header "cf-aig-retry-delay: 500" --header "cf-aig-backoff: exponential" --data '{"model":"openai/gpt-4.1-mini","messages":[{"role":"user","content":"Кратко объясни HTTP 429"}]}'

Повторная попытка обращается к текущей модели. Для переключения между моделями требуется явная 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. Для правил доступны фиксированное и скользящее окно.

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

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

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

Условия хранения журналов

Для аккаунтов, создавших первый gateway 24 сентября 2026 года или позже, AI Gateway использует условия Workers Logs. Более ранние аккаунты пока используют Legacy Logs. Также опубликован переход журналов и трасс на общую схему Observability 1 декабря 2026 года. Проверьте дату первого gateway и свой план; прежние лимиты legacy нельзя автоматически переносить в новый аккаунт. Условия журналов, предстоящая схема Observability.

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

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

Задача: приложение использует несколько моделей. Передавайте идентификатор нужной модели через один 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

По теме

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

Для контроля поведения работающего агента откройте трассировку и подтверждение действий.

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

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