Приложение с ИИ на Cloudflare Workers: запрос к модели, секреты и лимиты среды

Cloudflare Worker может выступать серверной границей между браузером и моделью: принять запрос, проверить его, добавить секрет провайдера и вернуть ответ. Но сам факт, что код написан на Worker, не означает наличие базы, очереди, авторизации или долгого фонового процесса. Это отдельные части решения.

Раздели страницу и API

Статическую страницу можно разместить отдельно, а путь /api/generate направить в Worker. Входящий HTTP Request приходит в fetch handler; переменные и bindings доступны обработчику через env. В этой точке проверь метод, Content-Type, размер и форму тела, допустимую длину текста и право пользователя на действие. Отдавай понятные коды ошибок и не пересылай произвольные URL из тела запроса.

Секрет модели добавляется через механизм secrets платформы и читается серверным кодом из env. Не записывай его в JavaScript-бандл, конфигурационный файл репозитория, сообщение об ошибке или лог. Если сайт вызывает API с браузера, CORS — это политика браузера, а не авторизация. Проверка пользователя и лимит расхода должны быть отдельными явными механизмами.

Пример потока генерации

1. Клиент отправляет JSON с prompt и случайным ключом повторной отправки.
2. Worker отклоняет некорректный JSON, пустой или чрезмерно большой запрос.
3. Сервер проверяет авторизацию и лимит, затем вызывает API модели с секретом.
4. Worker разбирает ответ провайдера и преобразует ошибки в безопасный формат.
5. Клиент показывает результат либо возможность повторить запрос; повтор не должен незаметно создавать платные дубликаты.

Пример иллюстративный: он не проверен запуском и не задаёт готовую политику авторизации, хранения или биллинга.

Не угадывай лимиты runtime

Прочитай актуальные лимиты Workers и ограничения домена для тела запроса перед проектированием. Внешний вызов модели может быть медленнее обычной проверки кода; измерь длительность и предусмотрись с таймаутом. Для длинной пакетной задачи подумай о Queues, а для состояния, требующего координации, — о подходящей базе или объекте состояния. Обычный HTTP Worker не превращается автоматически в очередь.

Для проверки подготовь сценарии: неверный JSON, слишком большой prompt, отсутствие сессии, провайдер ответил 429, провайдер не отвечает, запрос повторили, браузер получил 500. В лог записывай технический статус и correlation ID, но не prompt целиком и не секреты. Локальный preview и факт получения HTTP 200 сами по себе не доказывают корректную оплату, ограничение злоупотреблений или продовую доставку.

Где разместить данные и фоновые действия

Если Worker должен сохранить заявку, реши, какое хранилище отвечает за источник истины. KV подходит не для всякой модели согласованности; SQL-данные, файлы и координация имеют разные примитивы Cloudflare. Не выбирай продукт только по тому, что он находится в той же панели. Опиши чтение/запись и требования к согласованности, затем проверь подходящий binding и его локальную настройку.

Для долгой генерации можно сразу вернуть 202 Accepted с ID задачи, а статус хранить отдельно. Но одной записи queued мало: определи поведение для повторной доставки, ядовитого сообщения, максимального числа попыток и окончательной ошибки. Cloudflare Queues документирует batching, retries/delays и dead-letter маршруты; фактические настройки всё равно зависят от выбранной архитектуры. Не запускай задачу «в фоне» без механизма подтверждения завершения.

Сначала проверь endpoint локально с фиктивным провайдером и синтетическим prompt, затем staging с ограниченным ключом и тестовой квотой. Наблюдай коды ответа, длительность, число обращений к провайдеру и отсутствие секрета в логах. Только отдельная сверка ответа модели/записи докажет, что workflow завершился; статья не выполняла такую проверку.

Официальные разделы: Fetch API, Fetch handler, Secrets, Limits.

Сначала отдели Pages и Worker

Cloudflare Pages может раздавать статические assets и поддерживать Functions; standalone Workers — другой runtime и модель публикации. Статья о Workers не подразумевает, что проект размещён в Pages. Уточни, где собран frontend, какой Worker обслуживает API и как маршрутизируется запрос. В приложении с Workers Static Assets код Worker и статические файлы могут сосуществовать, но проверь текущую схему по документации выбранного продукта.

Локальный путь тоже важен. Пропиши dev script, bindings и фиктивные значения отдельно от production. Локальный secret может быть доступен только локальному процессу; не добавляй его в git. Проверь, что staging Worker подключён к тестовой базе, а не к production D1/R2. Cloudflare docs перечисляет отдельные разделы local development, environments, bindings и secrets; именно их нужно сверить для своего wrangler configuration.

Для первого deploy опиши способ rollback и проверь, как вернуться к версии API, совместимой с frontend. Если статическая страница раскатывается раньше backend, пользователь может вызвать новый endpoint на старой версии. Версионируй контракт или выкатывай совместимую последовательность. Worker deployment успешен — это факт инфраструктуры, не гарантия корректности продуктового сценария.