← Cloudflare AI Gateway / ai-gateway / usage

Universal Endpoint (zastaralý)

Universal Endpoint vám umožňuje kontaktovat všechny poskytovatele prostřednictvím jednoho koncového bodu.

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

Payload očekává pole zpráv. Každá zpráva je objekt s následujícími parametry:

provider: název poskytovatele, kterému chcete tuto zprávu odeslat. Může to být OpenAI, workers-ai nebo kterýkoli z našich podporovaných poskytovatelů.
endpoint: cesta k API poskytovatele, které se snažíte kontaktovat. Například u OpenAI to může být chat/completions, a u Workers AI to může být @cf/meta/llama-3.1-8b-instruct. Přečtěte si části, které se týkají konkrétně každý poskytovatel.
authorization: obsah HTTP hlavičky Authorization, která by měla být použita při komunikaci s tímto poskytovatelem. Obvykle začíná na Token nebo Bearer.
query: payload tak, jak ho poskytovatel očekává ve své oficiální API.

Příklad cURL

Požadavek

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?"
        }
      ]
    }
  }
]'

Výše uvedený příklad odešle požadavek na Workers AI Inference API. Pokud selže, přejde na OpenAI. Do pole můžete přidat další objekt a nastavit tak libovolný počet fallbacků.

Fallbacks

Fallbacks modelu nebo poskytovatele můžete zadat pro zvládání selhání požadavků a zajištění spolehlivosti. Pole payload určuje pořadí fallbacků: pokud první poskytovatel selže, požadavek přejde na další položku v poli. Další podrobnosti najdete v Fallbacks.

Cloudflare ve výchozím nastavení spustí váš fallback, pokud požadavek na model vrátí chybu. Můžete také nastavit časové limity požadavků k vyvolání záložních poskytovatelů, pokud poskytovatel odpovídá příliš dlouho.

Hlavička odpovědi (`cf-aig-step`)

Při použití fallbacks bude hlavička odpovědi cf-aig-step udává, který model požadavek úspěšně zpracoval, a to vrácením čísla kroku:

cf-aig-step:0 : První (primární) model byl použit úspěšně.
cf-aig-step:1 : Požadavek byl přesměrován na druhý model.
cf-aig-step:2 : Požadavek byl přesměrován na třetí model.
Následující kroky: každý fallback zvyšuje číslo kroku o 1.

Časové limity požadavků

Časový limit požadavku spustí náhradní řešení, pokud poskytovatel odpovídá příliš dlouho.

Časový limit nakonfigurujte nastavením requestTimeout vlastnost (v milisekundách) v rámci pro poskytovatele specifických config objekt. Každý poskytovatel může mít jiný requestTimeout hodnota.

Timeout se odvíjí od okamžiku, kdy dorazí první část odpovědi. Pokud se první část odpovědi vrátí ve stanoveném čase (například při streamování odpovědi), váš gateway na odpověď počká.

Příklad časového limitu požadavku

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
        },
    }
]'

Opakování požadavků

Universal Endpoint podporuje automatické opakování u neúspěšných požadavků, maximálně pětkrát. Opakování proběhne dříve, než se spustí jakékoli nakonfigurované fallbacky.

Nastavení opakování nakonfigurujte pomocí následujících vlastností ve specifickém prvku poskytovatele config:

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

maxAttempts: Maximální počet pokusů o opakování (až 5).
retryDelay: Prodleva před opakovaným pokusem v milisekundách (maximálně 5 sekund).
backoff: Backoff metoda: constant, linear, nebo exponential.

Při posledním pokusu o opakování počká váš gateway na dokončení požadavku bez ohledu na to, jak dlouho to trvá. Každý poskytovatel může mít jiná nastavení opakování.

Příklad opakování požadavku

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

K Universal Endpoint lze také přistupovat přes WebSockets API které poskytuje jediné trvalé připojení umožňující nepřetržitou komunikaci. Toto API podporuje všechny poskytovatele AI připojené k AI Gateway, včetně těch, kteří nativně nepodporují WebSockets.

Příklad 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());
});

Příklad 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",
			},
		});
	},
};

Hierarchie konfigurace hlaviček

Universal Endpoint vám umožňuje nastavit záložní modely nebo poskytovatele a přizpůsobit hlavičky pro každého poskytovatele nebo požadavek. Hlavičky můžete konfigurovat na třech úrovních:

Úroveň poskytovatele: Hlavičky specifické pro konkrétního poskytovatele.
Úroveň požadavku: Hlavičky zahrnuté v jednotlivých požadavcích.
Nastavení Gateway: Výchozí hlavičky nakonfigurované v dashboardu vaší gateway.

Protože stejná nastavení lze konfigurovat na více místech, AI Gateway používá hierarchii, která určuje, jaká konfigurace má přednost:

Hlavičky na úrovni poskytovatele přepíší všechny ostatní konfigurace.
Hlavičky na úrovni požadavku se použijí, pokud nejsou nastaveny hlavičky na úrovni poskytovatele.
Nastavení na úrovni gateway se použijí pouze v případě, že nejsou nakonfigurovány žádné hlavičky na úrovni poskytovatele nebo požadavku.

Tato hierarchie zajišťuje konzistentní chování a upřednostňuje nejkonkrétnější konfigurace. Pro jemné doladění použijte hlavičky na úrovni poskytovatele a na úrovni požadavku, obecné výchozí hodnoty pak zajistí nastavení gateway.

Příklad hierarchie

Tento příklad ukazuje, jak hlavičky nastavené na různých úrovních ovlivňují chování ukládání do mezipaměti:

Hlavička na úrovni požadavku: cf-aig-cache-ttl je nastaveno na 3600 sekund, čímž se tato doba ukládání do mezipaměti ve výchozím nastavení použije na požadavek.
Hlavička na úrovni poskytovatele: Pro záložního poskytovatele (OpenAI), cf-aig-cache-ttl je výslovně nastavena na 0 sekund, čímž se přepíše hlavička na úrovni požadavku a vypne se ukládání odpovědí do mezipaměti, pokud je jako poskytovatel použit OpenAI.

To ukazuje, jak mají hlavičky na úrovni poskytovatele přednost před hlavičkami na úrovni požadavku, což umožňuje podrobně řídit chování ukládání do mezipaměti.

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?"
          }
        ]
      }
    }
  ]'