Как запустить Asynchronous Batch API Cloudflare Workers AI

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

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

• Для REST к inference endpoint добавляют query parameter queueRequest=true.
• Тело содержит массив requests; каждому элементу можно задать уникальный external_reference.
• Общий payload должен быть меньше 10 MB.
• Первый ответ имеет status queued и request_id; тем же endpoint опрашивают результат, передавая request_id.

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

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

Вход: 100 обезличенных requests с external_reference ticket-0001…ticket-0100 и payload меньше 10 MB.

Ожидаемый результат: После queued/running появляется финальный ответ; каждый вход сопоставлен ровно с одной response по id или external_reference, сумма успехов и ошибок равна 100.

Сохраните очищенное тело запроса, 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 "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai/run/@cf/baai/bge-m3?queueRequest=true" \
+ -H "Authorization: Bearer $API_TOKEN" -H 'Content-Type: application/json' \
+ --json '{"requests":[{"query":"возврат оплаты","contexts":[{"text":"Возврат за 3 дня"}],"external_reference":"ticket-0001"}]}'
# сохранить request_id; poll тем же URL с {"request_id":"..."}

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

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

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

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

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

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

• модель batch-compatible
• payload меньше 10 MB
• references уникальны
• polling ограничен timeout
• responses+errors равны входу