← Cloudflare AI Gateway / ai-gateway / configuration

Custom Providers

Custom Providers vám umožňují integrovat poskytovatele AI, kteří nejsou nativně podporováni v AI Gateway. Tato funkce vám umožňuje u libovolného poskytovatele AI s koncovým bodem API přes HTTPS využívat pozorovatelnost, ukládání do mezipaměti, omezení počtu požadavků a další funkce AI Gateway.

• Interní AI modely: Připojte se k AI modelům vaší organizace hostovaným ve vlastní infrastruktuře
• Regionální poskytovatelé: Integrujte se s poskytovateli AI specifickými pro váš region
• Specializované modely: Používejte doménově specifické služby AI, které nejsou dostupné u standardních poskytovatelů
• Vlastní koncové body: Směrujte požadavky do vlastní AI infrastruktury

• Aktivní účet Cloudflare s přístupem k AI Gateway
• Platný API klíč od vašeho vlastního poskytovatele AI
• Základní HTTPS URL adresa API vašeho poskytovatele

Koncové body API pro vytváření, čtení, aktualizaci a mazání custom providers vyžadují autentizaci. Musíte vytvořit API token Cloudflare s příslušnými oprávněními.

Chcete-li vytvořit token API:

1. Přejděte na Stránka API tokenů v Cloudflare dashboardu ↗
2. Klikněte na Create Token
3. Vyberte Custom Token a přidejte následující oprávnění:
   • AI Gateway - Edit
4. Klikněte na Pokračovat k souhrnu a poté Create Token
5. Zkopírujte token, použijete ho v Authorization: Bearer $CLOUDFLARE_API_TOKEN hlavička

# 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"
  }
}

Jakmile vytvoříte custom provider, můžete požadavky směrovat přes AI Gateway jedním ze dvou způsobů: Unified API nebo koncový bod specifický pro poskytovatele. Při odkazování na vlastního poskytovatele kterýmkoli způsobem musíte slug opatřit prefixem custom-.

Když AI Gateway obdrží požadavek pro custom provider, sestaví cílovou (upstream) URL adresu kombinací nakonfigurovaného base_url cestou, která následuje za custom-{slug}/ v URL adrese brány.

base_url pole by mělo obsahovat pouze kořenovou doménu (nebo doména s pevnou předponou) rozhraní API poskytovatele. Jakékoli segmenty cesty specifické pro dané API (například /v1/chat/completions) patří do URL požadavku, nikoli do base_url.

Vzorec je následující:

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

Vše za custom-{slug}/ v URL adrese vašeho požadavku se připojí přímo k base_url k vytvoření konečné upstream URL. To znamená, že {provider-path} může obsahovat více segmentů cesty, parametry dotazu nebo jakoukoli strukturu cesty, kterou váš poskytovatel vyžaduje.

Použijte Unified API pokud váš vlastní poskytovatel přijímá formát kompatibilní s OpenAI /chat/completions formát požadavku. Jde o nejjednodušší možnost, která dobře funguje s OpenAI SDK.

Použijte koncový bod specifický pro poskytovatele pokud váš vlastní poskytovatel používá nestandardní cestu API nebo formát požadavku. Díky tomu máte plnou kontrolu nad cestou URL i tělem požadavku odesílaného upstream poskytovateli.

Unified API odesílá požadavky na koncový bod chat completions poskytovatele ve formátu kompatibilním s OpenAI. Model zadejte ve formátu 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!"}]
  }'

Koncový bod specifický pro poskytovatele vám dává plnou kontrolu nad upstream cestou. Vše za custom-{slug}/ v URL adrese se připojí k 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!"}]
  }'

Pokud base_url je https://api.myprovider.com, tento požadavek se přeposílá na: https://api.myprovider.com/v1/chat/completions

Následující příklady ukazují, jak nakonfigurovat base_url a sestavte URL adresy požadavků pro různé typy poskytovatelů.

Mnoho poskytovatelů dodržuje konvenci OpenAI a hostuje své API na {domain}/v1/chat/completions.

Konfigurace:

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

Koncový bod specifický pro poskytovatele:

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

Mapování URL:

Protože je tento poskytovatel kompatibilní s OpenAI, můžete použít také 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!"}]
  }'

Někteří poskytovatelé používají cesty API, které se neřídí /v1/ konvenci. Například poskytovatel, jehož chat endpoint se nachází na https://api.custom-ai.com/api/coding/paas/v4/chat/completions.

Konfigurace:

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

Koncový bod specifický pro poskytovatele:

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

Mapování URL:

Pokud svůj model hostujete za reverzní proxy nebo na platformě přidávající prefix cesty, uveďte pouze pevnou část prefixu v base_url pokud ji sdílejí všechny vaše koncové body. V opačném případě ponechte base_url pouze jako doménu.

Konfigurace (pouze doména base_url):

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

Koncový bod specifický pro poskytovatele:

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

Mapování URL:

Pokud pomocí OpenAI SDK připojujete custom provider přes AI Gateway, nastavte u SDK base_url na cestu koncového bodu specifickou pro poskytovatele vaší gateway (včetně prefixu verze API, který váš poskytovatel očekává).

Konfigurace:

• 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!"}],
)

Mapování URL:

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

Každý vlastní provider slug musí být v rámci vašeho účtu jedinečný. Zvolte jiný slug nebo aktualizujte stávajícího poskytovatele.

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

Zadané ID poskytovatele neexistuje, nebo k němu nemáte přístup. Zkontrolujte ID poskytovatele a své přihlašovací údaje pro autentizaci.

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

base_url pole musí být platná adresa URL s protokolem HTTPS. Adresy URL s protokolem HTTP nejsou z bezpečnostních důvodů podporovány.

Pokud od upstream poskytovatele obdržíte chybu 404, nejčastější příčinou je nesprávné mapování cest. Ověřte, že:

1. Váš base_url je nastavena na hodnotu poskytovatele kořenová doména (například https://api.provider.com) namísto zahrnutí segmentů cesty API.
2. URL adresa vašeho požadavku obsahuje úplná cesta API po custom-{slug}/. Pokud je například koncový bod na straně poskytovatele https://api.provider.com/api/v2/chat, adresa URL vaší brány by měla končit na /custom-{slug}/api/v2/chat.
3. Cesta neobsahuje žádný duplicitní ani chybějící segment. Častou chybou je zahrnutí /v1 v obou base_url a cestu požadavku, takže upstream server obdrží /v1/v1/chat/completions.

1. Používejte popisné slugy: Zvolte slugy, které jasně identifikují poskytovatele (např. internal-gpt, regional-ai)
2. Zdokumentujte své integrace: Použijte curl_example a js_example pole pro uvedení příkladů použití
3. Povolujte postupně: Otestujte pomocí enable: false před aktivací poskytovatele
4. Sledovat využití: Používejte analytiku AI Gateway ke sledování požadavků na vaše vlastní poskytovatele
5. Zabezpečte své koncové body: Ujistěte se, že základní URL adresa vašeho vlastního poskytovatele implementuje řádnou autentizaci a autorizaci
6. Použít BYOK: Bezpečně ukládejte klíče API poskytovatele pomocí BYOK místo jejich uvádění v každém požadavku

• Vlastní poskytovatelé jsou specifičtí pro daný účet a nesdílejí se mezi účty Cloudflare
• base_url musí používat HTTPS (HTTP není podporováno)
• Provider slugy musí být v rámci každého účtu jedinečné
• Nastavení mezipaměti a omezování počtu požadavků platí globálně pro poskytovatele, ne pro jednotlivé modely

• Začínáme s AI Gateway
• Nakonfigurovat ověřování
• BYOK (ukládání klíčů)
• Dynamické směrování
• Ukládání do mezipaměti
• Omezení četnosti požadavků