Как подключить OpenAI SDK к Cloudflare Workers AI

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

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

• Базовый URL SDK — https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/v1.
• Chat Completions вызывается обычным client.chat.completions.create, но model ID остаётся Cloudflare-формата @cf/....
• Совместимый endpoint для embeddings — /v1/embeddings.
• Переход на Workers AI требует замены base URL и модели; это не обещание побитовой идентичности ответов разных провайдеров.

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

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

Вход: Запрос Ответь ровно: SDK_OK через OpenAI Python SDK с Cloudflare base URL.

Ожидаемый результат: SDK формирует запрос к Cloudflare, возвращает объект ChatCompletion, и первый message.content содержит SDK_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.

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

import os
from openai import OpenAI
client=OpenAI(api_key=os.environ['CLOUDFLARE_API_TOKEN'], base_url=f"https://api.cloudflare.com/client/v4/accounts/{os.environ['CLOUDFLARE_ACCOUNT_ID']}/ai/v1")
r=client.chat.completions.create(model='@cf/meta/llama-3.1-8b-instruct',messages=[{'role':'user','content':'Ответь ровно: SDK_OK'}])
assert 'SDK_OK' in r.choices[0].message.content

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

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

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

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

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

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

• base_url оканчивается на ai/v1
• ключ взят из окружения
• model ID найден в каталоге
• choices не пуст
• маркер SDK_OK найден