Как вызвать модель Cloudflare Workers AI через REST API

Результат считается готовым не после первого HTTP 200, а после проверки формального ответа и контрольного бизнес-условия. Зафиксируйте дату теста, полный model ID, способ вызова — binding, native REST или OpenAI-compatible endpoint — и версии Wrangler/SDK. Это позволяет отличить изменение кода от обновления сервиса.

Проверенные параметры

• Endpoint имеет вид /client/v4/accounts/{ACCOUNT_ID}/ai/run/{model}.
• Токен передаётся как Authorization: Bearer {API_TOKEN}.
• Для токена, создаваемого не из готового шаблона, документация требует Workers AI - Read и Workers AI - Edit.
• Cloudflare envelope содержит result, success, errors и messages; одного HTTP 200 недостаточно без проверки success.

Не переносите параметры между моделями автоматически. Text generation, embeddings, reranking и batch имеют разные формы входа и результата. Значения <ACCOUNT_ID>, <MODEL_ID> и <GATEWAY_ID> в шаблонах заменяют фактическими идентификаторами, а не догадками.

Контрольный пример

Вход: Account ID, backend-переменная токена и короткий prompt с маркером REST_OK.

Ожидаемый результат: HTTP-ответ парсится как JSON, success=true, массив errors пуст, а result.response содержит REST_OK.

Сохраните очищенное тело запроса, HTTP-код, Cloudflare success, массив errors, request ID, model ID и время выполнения. API token, персональные данные и закрытые документы в тестовый артефакт не попадают. Для модельного ответа разделяйте технический PASS и смысловой PASS: корректный JSON может содержать неверный факт.

Настройка по шагам

1. Создайте отдельный тестовый проект. Секрет передайте через CLOUDFLARE_API_TOKEN; Account ID можно хранить как конфигурацию, но токен нельзя помещать во frontend, репозиторий или скриншот.
2. Откройте актуальную карточку модели и подтвердите требуемую функцию. Поддержка обычного inference не означает автоматически JSON Mode, function calling, batch или prompt caching.
3. Выберите один интерфейс для первого теста. Для Worker binding имя в Wrangler должно совпадать с полем env; для REST проверьте Account ID, endpoint и Bearer header; для OpenAI SDK — base URL.
4. Отключите автоматические retry на диагностическом запуске. Выполните минимальный пример и запишите исходную ошибку целиком после маскировки токена.
5. Проверьте Cloudflare envelope и предметный контракт. Пустой result, success=false, неполный массив или неверный тип поля — это FAIL даже при успешном транспорте.
6. Добавьте отрицательный тест: неверный тип, отсутствующее обязательное поле, неизвестный resource либо превышенный локальный лимит. Приложение должно отказать безопасно и не повторять неисправимый запрос.
7. Прогоните 20–50 обезличенных случаев реального распределения: кириллицу, пустые строки, длинный вход, граничные числа и ожидаемые отказы. Только затем включайте concurrency, cache и retry.

Рабочий шаблон

curl -sS "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run/@cf/meta/llama-3.1-8b-instruct" \
+ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+ -H "Content-Type: application/json" \
+ --data '{"prompt":"Ответь ровно: REST_OK"}'

Шаблон показывает проверяемый контракт, но не заменяет production-обвязку. Добавьте timeout, ограничение размера тела, централизованное удаление секретов из логов, correlation ID и allowlist ресурсов. Любая операция, меняющая данные, требует отдельной авторизации и идемпотентности.

Готовый промпт для проверки

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

Вход: {CONTROL_INPUT}
Ожидаемые маркеры: {EXPECTED_MARKERS}

Промпт — воспроизводимый fixture, а не средство безопасности. JSON Schema, проверка типов, авторизация tool arguments и фильтрация результата выполняются кодом. Инструкцию из загруженного документа нельзя повышать до системной команды.

Как проверить результат

• Account ID не пуст
• токен не попал в лог
• HTTP-код проверен
• success равен true
• result.response проверен