← Cloudflare AI Gateway / ai-gateway / usage

Universal Endpoint (Deprecated)

Universal Endpoint позволяет обращаться к любому провайдеру через единый эндпойнт.

https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}

Payload ожидает массив сообщений. Каждое сообщение представляет собой объект со следующими параметрами:

provider: имя провайдера, которому нужно направить это сообщение. Может быть OpenAI, workers-ai или любым другим поддерживаемым провайдером.
endpoint: путь API провайдера, к которому вы обращаетесь. Например, для OpenAI это может быть chat/completions, а для Workers AI это может быть @cf/meta/llama-3.1-8b-instruct. См. разделы, относящиеся к каждый провайдер.
authorization: содержимое HTTP-заголовка Authorization, которое следует использовать при обращении к этому провайдеру. Обычно оно начинается с Token или Bearer.
query: payload в том виде, в котором его ожидает официальный API провайдера.

Пример cURL

Запрос

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id} \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "provider": "workers-ai",
    "endpoint": "@cf/meta/llama-3.1-8b-instruct",
    "headers": {
      "Authorization": "Bearer {cloudflare_token}",
      "Content-Type": "application/json"
    },
    "query": {
      "messages": [
        {
          "role": "system",
          "content": "You are a friendly assistant"
        },
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ]
    }
  },
  {
    "provider": "openai",
    "endpoint": "chat/completions",
    "headers": {
      "Authorization": "Bearer {open_ai_token}",
      "Content-Type": "application/json"
    },
    "query": {
      "model": "gpt-4o-mini",
      "stream": true,
      "messages": [
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ]
    }
  }
]'

Приведённый выше пример отправит запрос в Workers AI Inference API. Если он завершится ошибкой, запрос перейдёт к OpenAI. Вы можете добавить сколько угодно резервных вариантов, добавляя ещё один объект в массив.

Fallbacks

Вы можете задать резервные модели или провайдеров на случай сбоя запросов, чтобы повысить отказоустойчивость. Массив payload определяет последовательность резервных вариантов: если первый провайдер завершается ошибкой, запрос переходит к следующему элементу массива. Подробнее см. в Fallbacks.

По умолчанию Cloudflare запускает fallback, если запрос к модели возвращает ошибку. Вы также можете настроить тайм-ауты запросов чтобы запускать резервные варианты, если провайдер отвечает слишком долго.

Заголовок ответа (`cf-aig-step`)

При использовании резервных вариантов заголовок ответа cf-aig-step показывает, какая модель успешно обработала запрос, возвращая номер шага:

cf-aig-step:0, Первая (основная) модель была использована успешно.
cf-aig-step:1, Запрос перешел на вторую модель.
cf-aig-step:2, Запрос перешел на третью модель.
Последующие шаги: каждый резервный вариант увеличивает номер шага на 1.

Тайм-ауты запроса

Тайм-аут запроса запускает переход на резервный вариант, если провайдер отвечает слишком долго.

Настройте тайм-аут, задав requestTimeout свойство (в миллисекундах) в специфичном для провайдера config объект. У каждого провайдера может быть свой requestTimeout значение.

Тайм-аут отсчитывается от момента получения первой части ответа. Пока первая часть ответа возвращается в течение заданного времени (например, при потоковой передаче ответа), ваш шлюз будет ожидать полного ответа.

Пример тайм-аута запроса

curl 'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}' \
	--header 'Content-Type: application/json' \
	--data '[
    {
        "provider": "workers-ai",
        "endpoint": "@cf/meta/llama-3.1-8b-instruct",
        "headers": {
            "Authorization": "Bearer {cloudflare_token}",
            "Content-Type": "application/json"
        },
        "config": {
            "requestTimeout": 1000
        },
        "query": {
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly assistant"
                },
                {
                    "role": "user",
                    "content": "What is Cloudflare?"
                }
            ]
        }
    },
    {
        "provider": "workers-ai",
        "endpoint": "@cf/meta/llama-3.1-8b-instruct-fast",
        "headers": {
            "Authorization": "Bearer {cloudflare_token}",
            "Content-Type": "application/json"
        },
        "query": {
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly assistant"
                },
                {
                    "role": "user",
                    "content": "What is Cloudflare?"
                }
            ]
        },
				"config": {
            "requestTimeout": 3000
        },
    }
]'

Повторные попытки запроса

Universal Endpoint поддерживает автоматические повторные попытки для неудачных запросов, максимум пять попыток. Повторные попытки выполняются до срабатывания любых настроенных резервных вариантов.

Настройте параметры повторных попыток с помощью следующих свойств в специфичном для провайдера config:

config:{
	maxAttempts?: number;
	retryDelay?: number;
	backoff?: "constant" | "linear" | "exponential";
}

maxAttempts: Максимальное количество попыток повтора (до 5).
retryDelay: задержка перед повторной попыткой в миллисекундах (не более 5 секунд).
backoff: метод отсрочки: constant, linear, или exponential.

При последней попытке повторной отправки шлюз будет ждать завершения запроса, независимо от того, сколько времени это займёт. У каждого провайдера могут быть свои настройки повторных попыток.

Пример повторной попытки запроса

curl 'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}' \
	--header 'Content-Type: application/json' \
	--data '[
    {
        "provider": "workers-ai",
        "endpoint": "@cf/meta/llama-3.1-8b-instruct",
        "headers": {
            "Authorization": "Bearer {cloudflare_token}",
            "Content-Type": "application/json"
        },
        "config": {
            "maxAttempts": 2,
						"retryDelay": 1000,
						"backoff": "constant"
        },
        "query": {
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly assistant"
                },
                {
                    "role": "user",
                    "content": "What is Cloudflare?"
                }
            ]
        }
    },
    {
        "provider": "workers-ai",
        "endpoint": "@cf/meta/llama-3.1-8b-instruct-fast",
        "headers": {
            "Authorization": "Bearer {cloudflare_token}",
            "Content-Type": "application/json"
        },
        "query": {
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly assistant"
                },
                {
                    "role": "user",
                    "content": "What is Cloudflare?"
                }
            ]
        },
				"config": {
            "maxAttempts": 4,
						"retryDelay": 1000,
						"backoff": "exponential"
        },
    }
]'

WebSockets API beta

К Universal Endpoint также можно обращаться через WebSockets API который предоставляет единое постоянное соединение, обеспечивая непрерывную связь. Этот API поддерживает всех AI-провайдеров, подключенных к AI Gateway, включая тех, кто изначально не поддерживает WebSockets.

Пример WebSockets

import WebSocket from "ws";
const ws = new WebSocket(
	"wss://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/",
	{
		headers: {
			"cf-aig-authorization": "Bearer AI_GATEWAY_TOKEN",
		},
	},
);

ws.send(
	JSON.stringify({
		type: "universal.create",
		request: {
			eventId: "my-request",
			provider: "workers-ai",
			endpoint: "@cf/meta/llama-3.1-8b-instruct",
			headers: {
				Authorization: "Bearer WORKERS_AI_TOKEN",
				"Content-Type": "application/json",
			},
			query: {
				prompt: "tell me a joke",
			},
		},
	}),
);

ws.on("message", function incoming(message) {
	console.log(message.toString());
});

Пример Workers Binding

{
	"ai": {
		"binding": "AI",
	},
}

[ai]
binding = "AI"

src/index.ts

type Env = {
	AI: Ai;
};

export default {
	async fetch(request: Request, env: Env) {
		return env.AI.gateway("my-gateway").run({
			provider: "workers-ai",
			endpoint: "@cf/meta/llama-3.1-8b-instruct",
			headers: {
				authorization: "Bearer my-api-token",
			},
			query: {
				prompt: "tell me a joke",
			},
		});
	},
};

Иерархия конфигурации заголовков

Universal Endpoint позволяет задавать резервные модели или провайдеров и настраивать заголовки для каждого провайдера или запроса. Заголовки можно настроить на трёх уровнях:

Уровень провайдера: Заголовки, специфичные для конкретного провайдера.
Уровень запроса: Заголовки, включенные в отдельные запросы.
Настройки Gateway: заголовки по умолчанию, настроенные в панели управления вашего шлюза.

Поскольку одни и те же настройки можно задать в нескольких местах, AI Gateway применяет иерархию, чтобы определить, какая конфигурация имеет приоритет:

Заголовки уровня провайдера переопределяют все остальные настройки.
Заголовки на уровне запроса используются, если заголовки уровня провайдера не заданы.
Настройки на уровне шлюза используются только в том случае, если заголовки не настроены на уровне провайдера или запроса.

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

Пример иерархии

Этот пример показывает, как заголовки, заданные на разных уровнях, влияют на поведение кэширования:

Заголовок на уровне запроса: cf-aig-cache-ttl имеет значение 3600 секунд, применяя эту длительность кеширования к запросу по умолчанию.
Заголовок уровня провайдера: Для резервного провайдера (OpenAI), cf-aig-cache-ttl явно установлено в 0 секунд, переопределяя заголовок уровня запроса и отключая кеширование ответов, если в качестве провайдера используется OpenAI.

Это показывает, что заголовки уровня провайдера имеют приоритет над заголовками уровня запроса, что даёт возможность гибко управлять поведением кэширования.

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id} \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-cache-ttl: 3600' \
  --data '[
    {
      "provider": "workers-ai",
      "endpoint": "@cf/meta/llama-3.1-8b-instruct",
      "headers": {
        "Authorization": "Bearer {cloudflare_token}",
        "Content-Type": "application/json"
      },
      "query": {
        "messages": [
          {
            "role": "system",
            "content": "You are a friendly assistant"
          },
          {
            "role": "user",
            "content": "What is Cloudflare?"
          }
        ]
      }
    },
    {
      "provider": "openai",
      "endpoint": "chat/completions",
      "headers": {
        "Authorization": "Bearer {open_ai_token}",
        "Content-Type": "application/json",
        "cf-aig-cache-ttl": "0"
      },
      "query": {
        "model": "gpt-4o-mini",
        "stream": true,
        "messages": [
          {
            "role": "user",
            "content": "What is Cloudflare?"
          }
        ]
      }
    }
  ]'