← Cloudflare AI Gateway / ai-gateway / configuration

Custom Providers

Custom Providers позволяют интегрировать провайдеров ИИ, которые изначально не поддерживаются AI Gateway. Эта функция даёт возможность использовать наблюдаемость, кэширование, ограничение скорости запросов и другие возможности AI Gateway с любым провайдером ИИ, у которого есть эндпойнт HTTPS API.

• Внутренние модели ИИ: подключайтесь к AI-моделям вашей организации, размещённым на собственной инфраструктуре
• Региональные провайдеры: Интегрируйтесь с AI-провайдерами, доступными в вашем регионе
• Специализированные модели: Используйте специализированные AI-сервисы, недоступные через стандартных провайдеров
• Пользовательские эндпойнты: Направляйте запросы в собственную AI-инфраструктуру

• Активный аккаунт Cloudflare с доступом к AI Gateway
• Действительный API-ключ вашего пользовательского AI-провайдера
• Базовый URL HTTPS для API вашего провайдера

Эндпойнты API для создания, чтения, обновления и удаления custom providers требуют аутентификации. Вам нужно создать API-токен Cloudflare с соответствующими разрешениями.

Чтобы создать API-токен:

1. Перейдите в Страница токенов API в панели управления Cloudflare ↗
2. Нажмите Create Token
3. Выберите Custom Token и добавьте следующие разрешения:
   • AI Gateway - Edit
4. Нажмите Continue to summary и затем Create Token
5. Скопируйте токен, он понадобится вам в Authorization: Bearer $CLOUDFLARE_API_TOKEN заголовок

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Custom Provider",
    "slug": "some-provider",
    "base_url": "https://api.myprovider.com",
    "description": "Custom AI provider for internal models",
    "enable": true
  }'

{
  "success": true,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "abc123def456",
    "account_tag": "my-account",
    "name": "My Custom Provider",
    "slug": "some-provider",
    "base_url": "https://api.myprovider.com",
    "description": "Custom AI provider for internal models",
    "enable": true,
    "beta": false,
    "logo": "Base64 encoded SVG logo",
    "link": null,
    "curl_example": null,
    "js_example": null,
    "created_at": 1700000000,
    "modified_at": 1700000000
  }
}

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers?enable=true" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers?search=custom" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
  "success": true,
  "result": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Custom Provider",
      "slug": "some-provider",
      "base_url": "https://api.myprovider.com",
      "enable": true,
      "created_at": 1700000000,
      "modified_at": 1700000000
    }
  ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "total_count": 1,
    "total_pages": 1
  }
}

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
  "success": true,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "abc123def456",
    "account_tag": "my-account",
    "name": "My Custom Provider",
    "slug": "some-provider",
    "base_url": "https://api.myprovider.com",
    "description": "Custom AI provider for internal models",
    "enable": true,
    "beta": false,
    "logo": "Base64 encoded SVG logo",
    "link": "https://docs.myprovider.com",
    "curl_example": "curl -X POST https://api.myprovider.com/v1/chat ...",
    "js_example": "fetch('https://api.myprovider.com/v1/chat', {...})",
    "created_at": 1700000000,
    "modified_at": 1700000000
  }
}

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Provider Name",
    "enable": true,
    "description": "Updated description"
  }'

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enable": true}'

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"base_url": "https://api.newprovider.com"}'

# Run `wrangler whoami` to get your account ID to replace $CLOUDFLARE_ACCOUNT_ID,
# and `wrangler auth token` to get an auth token to replace $CLOUDFLARE_API_TOKEN.
curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-gateway/custom-providers/{provider_id}" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
  "success": true,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Custom Provider",
    "slug": "some-provider"
  }
}

После того как вы создадите custom provider, вы можете направлять запросы через AI Gateway одним из двух способов: Unified API или специфичный для провайдера эндпойнт. При обращении к вашему custom provider любым из этих способов добавляйте к slug префикс custom-.

Когда AI Gateway получает запрос для пользовательского провайдера, он формирует URL вышестоящего сервера, объединяя настроенный провайдером base_url путем, который следует после custom-{slug}/ в URL шлюза.

base_url поле должно содержать только корневой домен (или домен с фиксированным префиксом) API провайдера. Любые специфичные для API сегменты пути (например, /v1/chat/completions) указываются в URL запроса, а не в base_url.

Формула:

Gateway URL:   https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-{slug}/{provider-path}
Upstream URL:  {base_url}/{provider-path}

Всё после custom-{slug}/ в URL вашего запроса добавляется непосредственно к base_url чтобы сформировать итоговый URL вышестоящего провайдера. Это означает, что {provider-path} может включать несколько сегментов пути, параметры запроса или любую структуру пути, которую требует ваш провайдер.

Используйте Unified API если ваш пользовательский провайдер принимает совместимый с OpenAI /chat/completions формат запроса. Это самый простой вариант, который хорошо работает с OpenAI SDK.

Используйте специфичный для провайдера эндпойнт если ваш пользовательский провайдер использует нестандартный путь API или формат запроса. Это дает вам полный контроль как над путем URL, так и над телом запроса, отправляемым вышестоящему провайдеру.

Unified API отправляет запросы к эндпойнту chat completions провайдера в формате, совместимом с OpenAI. Укажите модель в формате custom-{slug}/{model-name}.

# Run `wrangler auth token` to get an auth token to replace $CF_AIG_TOKEN for use with the API.
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "cf-aig-authorization: Bearer $CF_AIG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "custom-some-provider/model-name",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Специфичный для провайдера эндпойнт даёт полный контроль над вышестоящим путём. Всё, что идёт после custom-{slug}/ в URL добавляется к base_url.

# Run `wrangler auth token` to get an auth token to replace $CF_AIG_TOKEN for use with the API.
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-some-provider/v1/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "cf-aig-authorization: Bearer $CF_AIG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model-name",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Если base_url это https://api.myprovider.com, этот запрос проксируется на: https://api.myprovider.com/v1/chat/completions

В следующих примерах показано, как настроить base_url и формировать URL-адреса запросов для разных типов провайдеров.

Многие провайдеры следуют соглашению OpenAI и размещают свой API по адресу {domain}/v1/chat/completions.

Конфигурация:

• slug: my-openai-compat
• base_url: https://api.example-provider.com

Специфичный для провайдера эндпойнт:

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-my-openai-compat/v1/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "example-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Сопоставление URL:

Поскольку этот провайдер совместим с OpenAI, вы также можете использовать Unified API:

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "custom-my-openai-compat/example-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Некоторые провайдеры используют пути API, которые не соответствуют /v1/ соглашение. Например, если эндпойнт чата провайдера находится по адресу https://api.custom-ai.com/api/coding/paas/v4/chat/completions.

Конфигурация:

• slug: custom-ai
• base_url: https://api.custom-ai.com

Специфичный для провайдера эндпойнт:

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-custom-ai/api/coding/paas/v4/chat/completions \
  -H "Authorization: Bearer $PROVIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "custom-ai-model",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Сопоставление URL:

Если ваша модель размещена за обратным прокси или на платформе, добавляющей к пути префикс, указывайте только фиксированную часть этого префикса в base_url если это значение общее для всех ваших конечных точек. В противном случае оставьте base_url просто как домен.

Конфигурация (только для домена base_url):

• slug: internal-llm
• base_url: https://ml.internal.example.com

Специфичный для провайдера эндпойнт:

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-internal-llm/serving/models/my-model:predict \
  -H "Authorization: Bearer $INTERNAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [{"prompt": "Summarize the following text:"}]
  }'

Сопоставление URL:

При использовании OpenAI SDK для подключения к пользовательскому провайдеру через AI Gateway укажите в SDK base_url к специфичному для провайдера пути конечной точки шлюза (включая префикс версии API, который ожидает ваш провайдер).

Конфигурация:

• slug: alt-provider
• base_url: https://api.alt-provider.com

Python (OpenAI SDK):

from openai import OpenAI

client = OpenAI(
    api_key="your-provider-api-key",
    base_url="https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/custom-alt-provider/v1",
    default_headers={
        "cf-aig-authorization": "Bearer {cf_aig_token}",
    },
)

# The SDK appends /chat/completions to the base_url automatically.
# Final upstream URL: https://api.alt-provider.com/v1/chat/completions
response = client.chat.completions.create(
    model="alt-model-v2",
    messages=[{"role": "user", "content": "Hello!"}],
)

Сопоставление URL:

{
	"success": false,
	"errors": [
		{
			"code": 1003,
			"message": "A custom provider with this slug already exists",
			"path": ["body", "slug"]
		}
	]
}

Слаг каждого custom provider должен быть уникальным в пределах вашего аккаунта. Выберите другой слаг или обновите существующего провайдера.

{
	"success": false,
	"errors": [
		{
			"code": 1004,
			"message": "Custom Provider not found"
		}
	]
}

Указанный ID провайдера не существует, либо у вас нет к нему доступа. Проверьте ID провайдера и свои учётные данные для аутентификации.

{
	"success": false,
	"errors": [
		{
			"code": 1002,
			"message": "base_url must be a valid HTTPS URL starting with https://",
			"path": ["body", "base_url"]
		}
	]
}

base_url поле должно содержать корректный URL с HTTPS. URL с HTTP не поддерживаются из соображений безопасности.

Если от upstream-провайдера приходит ошибка 404, наиболее частой причиной обычно является неверное сопоставление путей. Убедитесь, что:

1. Ваш base_url принимает значение поставщика: корневой домен (например, https://api.provider.com) вместо включения сегментов пути API.
2. URL запроса включает полный путь API после custom-{slug}/. Например, если вышестоящий эндпойнт https://api.provider.com/api/v2/chat, URL вашего шлюза должен заканчиваться на /custom-{slug}/api/v2/chat.
3. Нет ни дублирующихся, ни отсутствующих сегментов пути. Распространённая ошибка: включение /v1 в обоих base_url и пути запроса, в результате чего вышестоящий сервер получает /v1/v1/chat/completions.

1. Используйте описательные slugs: выбирайте slug, которые чётко идентифицируют провайдера (например, internal-gpt, regional-ai)
2. Документируйте свои интеграции: Используйте curl_example и js_example поля, чтобы привести примеры использования
3. Включайте постепенно: Протестируйте с помощью enable: false перед активацией провайдера
4. Отслеживайте использование: Используйте аналитику AI Gateway для отслеживания запросов к вашим custom providers
5. Защитите свои эндпойнты: убедитесь, что base URL вашего custom provider реализует надлежащую аутентификацию и авторизацию
6. Использование BYOK: Безопасно храните API-ключи провайдера с помощью BYOK вместо того чтобы включать их в каждый запрос

• Пользовательские провайдеры привязаны к конкретному аккаунту и не используются совместно между аккаунтами Cloudflare
• base_url должен использовать HTTPS (HTTP не поддерживается)
• Слаги провайдера должны быть уникальными в рамках каждого аккаунта
• Настройки кэширования и ограничения частоты запросов применяются глобально к провайдеру, а не к отдельной модели

• Начало работы с AI Gateway
• Настройте аутентификацию
• BYOK (Store Keys)
• Dynamic routing
• Кеширование
• Ограничение скорости запросов