AI Gateway

AI Gateway nedir?

AI Gateway, uygulamanla model sağlayıcıları arasına giren bir proxy’dir. Resmî tanım:

“Cloudflare’s AI Gateway allows you to gain visibility and control over your AI apps. By connecting your apps to AI Gateway, you can gather insights on how people are using your application with analytics and logging and then control how your application scales with features such as caching, rate limiting, as well as request retries, model fallback, and more. Better yet - it only takes one line of code to get started.”

Genel kullanıma açılış yazısındaki tanım daha açık:

“AI Gateway is an AI ops platform that offers a unified interface for managing and scaling your generative AI workloads. At its core, it acts as a proxy between your service and your inference provider(s), regardless of where your model runs.”

Çözdüğü somut problem şu: çıkarımın OpenAI’a, Anthropic’e, Google’a ve Workers AI’a dağılmış durumda ve “kim ne harcadı, hangi model yavaşladı, hangi prompt kişisel veri sızdırdı” sorusunun tek bir cevap yeri yok. AI Gateway o yer oluyor — üstelik SDK’nı değiştirmeden.

22 Mayıs 2024’te genel kullanıma açıldı. Resmî ifade: “we are excited to announce that AI Gateway is Generally Available as well. Since its launch to beta in September 2023 during Birthday Week, we’ve proxied over 500 million requests and are now prepared for you to use it in production.” Tüm planlarda kullanılabilir.

Nasıl çalışır?

Dört giriş yolu

1. REST API — güncel öneri. api.cloudflare.com/client/v4/accounts/{id}/ai/… üzerinden, Cloudflare token’ı standart Authorization başlığında, sağlayıcı anahtarına gerek yok.

2. Sağlayıcı-yerel geçiş. https://gateway.ai.cloudflare.com/v1/{hesap_id}/{gateway_id}/{saglayici} — sağlayıcının kendi şemasını korur, Cloudflare token’ı cf-aig-authorization başlığına gider.

3. Workers binding. env.AI.run(model, input, { gateway: { id } }) — hesap içinde önceden kimlik doğrulanmış, hiçbir başlık gerekmez.

4. WebSocket. Realtime (sağlayıcının kendi WS ucu varsa) ve Realtime olmayan. İkincisi için resmî not: “Works with all AI providers in AI Gateway. Even if your chosen provider does not support WebSockets, Cloudflare handles it for you.”

Desteklenen sağlayıcılar

Sağlayıcı-yerel geçiş listesi 24 kalem: Workers AI, Amazon Bedrock, Anthropic, Azure OpenAI, Baseten, Cartesia, Cerebras, Cohere, Deepgram, DeepSeek, ElevenLabs, Fal AI, Google AI Studio, Google Vertex AI, Groq, HuggingFace, Ideogram, Mistral AI, OpenAI, OpenRouter, Parallel, Perplexity, Replicate, xAI.

Model adlandırma: üçüncü taraf modelleri yazar/model (openai/gpt-4.1, anthropic/claude-sonnet-4, google/gemini-3-flash); Workers AI modelleri @cf/yazar/model ve her zaman cf-aig-gateway-id başlığını ister.

Cache

Varsayılan olarak kapalıdır. Açtığında anahtar şu bileşenlerin SHA-256’sıdır: sağlayıcı + uç + model + sağlayıcı auth başlığı + tüm istek gövdesi.

“This means caching is based on exact match of the entire request. Any difference in the body — including messages, tools, or model parameters — will result in a separate cache entry.”

Dört sınırı bilmek gerekiyor:

• Anlamsal cache yok. “We plan on adding semantic search for caching in the future.”
• Yalnızca metin ve görsel yanıtlar. “Currently caching is supported only for text and image responses.”
• Uçucudur. “Cache in AI Gateway is volatile. If two identical requests are sent simultaneously, the first request may not cache in time for the second request to use it.”
• Streaming yanıtlar varsayılan olarak cache’lenmez.

TTL: en az 60 saniye, en fazla bir ay. cf-aig-cache-key verip TTL vermezsen varsayılan 5 dakikadır. Sonucu cf-aig-cache-status: HIT | MISS başlığından okursun.

Rate limiting

“You can define rate limits as the number of requests that get sent in a specific time frame. For example, you can limit your application to 100 requests per 60 seconds.”

Sabit (fixed) ve kayan (sliding) pencere seçenekleri var. Aşımda 429 Too Many Requests. Önemli kısıt: “This rate limiting behavior will be uniformly applied to all requests for that gateway.” Yani gateway geneli çalışır — kullanıcı başına sınır istiyorsan ya Dynamic Routing içindeki Rate Limit düğümünü kullanacaksın ya da ayrı gateway açacaksın.

Retry ve fallback

Gateway seviyesinde: deneme sayısı (en fazla 5), gecikme (100 ms, 500 ms, 1 sn, 2 sn, 3 sn, 5 sn) ve backoff türü (sabit / doğrusal / üstel).

İstek başına başlıklar: cf-aig-max-attempts, cf-aig-retry-delay (en fazla 5000 ms), cf-aig-backoff, cf-aig-request-timeout.

İki cümle davranışı tam olarak açıklıyor:

“On the final retry attempt, your gateway will wait until the request completes, regardless of how long it takes.”

“The timeout is based on when the first part of the response comes back. As long as the first part of the response returns within the specified timeframe — such as when streaming a response — your gateway will wait for the response.”

Fallback için güncel mekanizma Dynamic Routing’dir. Hangi adımda olduğunu cf-aig-step yanıt başlığından okursun: 0 = birincil model yanıtladı, 1 = ikinciye düştü, 2 = üçüncüye.

Loglama

Varsayılan olarak açıktır. Her kayıt şunları tutar: “the user prompt, model response, provider, timestamp, request status, token usage, cost, duration, and the user agent of the client that made the request.”

İstek başına iki kademe kapatma var — KVKK açısından önemli:

Panelde filtrelenebilen alanlar: Status, Cache, Provider, AI Models, Cost, Request type, Tokens, Duration, Feedback, Metadata Key/Value, Log ID, Event ID, DLP Action, User Agent.

Maliyet takibi

İki uyarıyı birlikte okumak gerekiyor:

“Cost metrics are only available for endpoints where the models return token data and the model name in their responses.”

“The cost metric is an estimation based on the number of tokens sent and received in requests. While this metric can help you monitor and predict cost trends, refer to your provider’s dashboard for the most accurate cost details.”

Anlaşmalı bir fiyatın varsa cf-aig-custom-cost ile düzeltebilirsin.

Guardrails

İki Workers AI modeliyle çalışır: @cf/meta/llama-guard-3-8b (içerik) ve @cf/meta/prompt-guard-2-86m (prompt injection). Kategoriler S1–S13 artı P1, her biri prompt ve yanıt için ayrı ayrı Flag / Ignore / Block yapılabilir:

Hata modu da önemli: “If at least one hazard category is set to block, but AI Gateway is unable to receive a response from Workers AI, the request will be blocked.” Yani engelleme moduna aldığın kategorilerde Workers AI’a ulaşılamazsa istek reddedilir.

DLP

Cloudflare One DLP profillerini kullanır. Yalnızca gateway seviyesinde çalışır — resmî ifade: “There is no per-request header to select specific DLP profiles or to bypass DLP scanning for individual requests.” Farklı politika istiyorsan ayrı gateway açman gerekir.

Sonuç cf-aig-dlp başlığında döner, engellenen istek 400 alır. Streaming yanıtlar taranmadan önce tamponlanır. Cache etkileşimi: Pass → cache’lenir, Flag → cache’lenir, Block → cache’lenmez. Ve önemli bir yan etki: “Cache hits skip DLP scanning… if you update your DLP policies after a response has been cached, the cached response is not re-evaluated.”

BYOK — kendi anahtarını sakla

“Bring your own keys (BYOK) is a feature in Cloudflare AI Gateway that allows you to securely store your AI provider API keys directly in the Cloudflare dashboard.”

Anahtarlar Secrets Store’da tutulur. Anahtar sırası şu şekilde çalışıyor ve ezberlemekte fayda var:

1. İstekte sağlayıcı anahtarı varsa → aynen iletilir, BYOK ve Unified Billing devreye girmez
2. default takma adı altında saklanmış BYOK anahtarı
3. Unified Billing (Cloudflare’in kendi kimlik bilgileri, kredi bakiyenden düşer)

Kimlik doğrulama — en sık yapılan hata

İki uç, iki farklı başlık:

Resmî uyarı: “Make sure your Cloudflare token is in cf-aig-authorization, not Authorization. The Authorization header is reserved for provider credentials.”

Diğer özellikler

Spend limits — dolar cinsinden bütçe; model, sağlayıcı veya özel metadata boyutunda; “Split by value” ya da “Filter by value” modunda; gateway başına 20 kural. Aşımda 429.

Dynamic routing — görsel akış editörü: Start, Conditional, Percentage, Model, Rate Limit, Budget Limit, End düğümleri. Sürümlenir ve anında geri alınabilir. Kısıt: “Dynamic routing is not currently available on the REST API.”

Unified Billing — tek Cloudflare faturası. “A 5% fee is applied to all credits purchased… a $100 credit purchase will result in a $105 charge. Inference pricing from providers is passed through with no markup.”

ZDR (Zero Data Retention) — gateway ayarı veya cf-aig-zdr başlığı; yalnızca OpenAI ve Anthropic, yalnızca Unified Billing trafiğinde. Kritik uyarı: “ZDR does not control AI Gateway logging.”

Custom metadata — istek başına 5 giriş; String/Number/Boolean, “Objects are not supported”; cf.* anahtarları rezerve.

User Insights — kuruluş genelinde harcama ve anomali tespiti. Referans, kullanıcının 30 günlük oturum maliyetinin p95’i; hem bunun 2 katını hem de kuruluş p99’unu aşan oturumlar işaretlenir. Ama: “User Insights does not block requests.” Ücretsiz.

Ne zaman kullanılır, ne zaman kullanılmaz

Kullanılır

• Birden fazla sağlayıcıya dağılmış çıkarımın varsa. Tek log, tek maliyet ekranı, tek politika noktası.
• Kiracı bazında maliyet dağıtmak istiyorsan. cf-aig-metadata ile etiketle, Spend limits ile her kiracıya ayrı bütçe ver.
• Sağlayıcı kesintisine dayanıklılık gerekiyorsa. Dynamic Routing ile birincil model düşerse ikinciye geç, cf-aig-step ile hangi yolun kullanıldığını gör.
• Kod deposundan API anahtarlarını kaldırmak istiyorsan. BYOK ile bir kez sakla, panelden döndür: “Your applications will immediately start using the new key without any code changes or downtime.”
• Deterministik cache’lenebilir sorguların varsa (SSS botu, sabit özet, sabit çeviri).
• Kodlama ajanlarının (Claude Code, Codex, Copilot CLI) harcamasını kurum çapında görmek istiyorsan.

Kullanılmaz

Anlamsal cache bekliyorsan. Tam bayt eşleşmesi var, o kadar. Bir boşluk farkı bile ıskalar.

Kesin maliyet raporu üretmen gerekiyorsa. Rakam bir tahmin ve yalnızca token verisi dönen uçlarda hesaplanabiliyor. Muhasebeye gidecek sayı sağlayıcının kendi panosundan alınmalı.

Türkçe içerik moderasyonu için. Guardrails Türkçe desteklemiyor.

Streaming bir sohbet arayüzünde Guardrails veya DLP yanıt taraması açacaksan. İkisi de yanıtı tamponlar, streaming’in tüm kazancını götürür.

Token seviyesinde kiracı izolasyonu gerekiyorsa. Hesap kapsamlı yetkiler var; bir token hesaptaki tüm gateway’lere ve tüm BYOK anahtarlarına erişir.

Gün bazında log saklama süresi taahhüdü gerekiyorsa. Saklama adet üzerinden tanımlı, gün cinsinden bir süre yayımlanmamış.

Ani yükte sert bütçe tavanı gerekiyorsa. Bütçe sınırları eventually consistent.

Anlaşmalı sağlayıcı fiyatların varsa Unified Billing kullanma. %5 komisyon üstüne biner; BYOK

• kendi faturan daha ucuz.

Somut örnekler

Mevcut OpenAI uygulamasına tek satırda gözlemlenebilirlik

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: CLOUDFLARE_API_TOKEN,
  baseURL: `https://api.cloudflare.com/client/v4/accounts/${HESAP_ID}/ai/v1`,
  defaultHeaders: { 'cf-aig-gateway-id': 'prod' },
});

await openai.chat.completions.create({ model: 'openai/gpt-4.1', messages });

Kodun geri kalanı değişmez. Bundan sonra her istek loglanır, maliyeti hesaplanır ve panoda görünür.

Kiracı bazında maliyet ve bütçe (SaaS faturalandırma)

curl -X POST "https://api.cloudflare.com/client/v4/accounts/$CF_HESAP/ai/v1/chat/completions" \
  -H "Authorization: Bearer $CF_TOKEN" \
  -H "Content-Type: application/json" \
  -H 'cf-aig-metadata: {"kiraci":"acme-tr","plan":"pro","kullanici_id":"u_912"}' \
  -d '{"model":"anthropic/claude-sonnet-4-5","messages":[{"role":"user","content":"Özetle"}]}'

Ardından panelde bir Spend limit kuralı: Limit by metadata → anahtar kiraci → Split by value → aylık $50. Her kiracı kendi bütçesini alır; bütçesi biten kiracı 429 alır, diğerleri etkilenmez.

Sağlayıcı kesintisinden sağ çıkma

Dynamic route destek: birincil düğüm anthropic/claude-opus-4.7, yedek düğüm @cf/moonshotai/kimi-k2.6.

const client = new OpenAI({
  apiKey: CF_TOKEN,
  baseURL: `https://gateway.ai.cloudflare.com/v1/${HESAP_ID}/${GATEWAY_ID}/compat`,
});

const yanit = await client.chat.completions.create({
  model: 'dynamic/destek',
  messages,
});

cf-aig-step yanıt başlığı hangi modelin cevapladığını söyler.

Depodaki API anahtarlarını kaldırma (BYOK)

curl https://gateway.ai.cloudflare.com/v1/{hesap_id}/{gateway_id}/openai/chat/completions \
  -H 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [...]}'

Kodunda hiçbir yerde sk-... geçmez. Anahtar rotasyonu panelden yapılır ve deploy gerektirmez.

SSS botu için deterministik cache

curl -X POST ".../ai/v1/chat/completions" \
  -H "Authorization: Bearer $CF_TOKEN" \
  -H "Content-Type: application/json" \
  -H "cf-aig-cache-key: sss:iade-suresi:tr:v3" \
  -H "cf-aig-cache-ttl: 86400" \
  -d '{"model":"@cf/google/gemma-4-26b-a4b-it","messages":[...]}'

Kendi mantıksal anahtarını vermek, cache’i bayt-eşleşmesinden kurtarmanın tek pratik yoludur. Sürüm numarasını (v3) anahtara koymak, prompt’u değiştirdiğinde eski cevapları tek hamlede geçersiz kılmanı sağlar.

KVKK dostu loglama — metrik var, içerik yok

curl ... -H "cf-aig-collect-log-payload: false"

Token sayısı, maliyet ve süre loglanır; prompt ve yanıt gövdesi saklanmaz. OpenAI veya Anthropic kullanıyorsan üstüne cf-aig-zdr: true ekleyerek sağlayıcı tarafında da saklanmamasını sağlayabilirsin — ama ikisi ayrı ayarlar, biri diğerini kapsamaz.

Demo 1: Cache MISS’ten HIT’e — header, log ve analytics üçlüsü

Bu demoda bir başlığın değiştiğini, bir log satırının belirdiğini, maliyetin durduğunu ve gecikmenin düştüğünü aynı anda göreceğiz. Tamamı curl ile yapılabilir.

Adım 1 — Kimlik bilgilerini hazırla

export CF_HESAP=<32 karakterlik hesap kimliği>
export CF_TOKEN=<API token>

Token’ın AI Gateway → Read, AI Gateway → Edit ve Workers AI → Read yetkilerine sahip olması gerekiyor.

Adım 2 — Gateway oluştur ve başlangıç durumunu kaydet

Panelde AI → AI Gateway → Create Gateway, adı demo-tr. Alternatif olarak cf-aig-gateway-id: default başlığıyla tek bir istek atarsan gateway kendiliğinden oluşur; varsayılanları şunlardır: Authentication açık, Log collection açık, Caching kapalı (TTL 0), Rate limiting kapalı, Workers AI billing Standard.

AI → AI Gateway → Create Gateway ekranı ve oluşturulduktan sonraki ayar sayfası; Caching'in kapalı olduğu görülmeli

demo-tr gateway'inin Analytics sekmesi — Requests, Tokens, Costs, Errors ve Cached Responses yüzdesi başlangıç değerlerinde

Adım 3 — Cache’i aç

Settings → Cache Responses aç, varsayılan TTL 3600.

demo-tr Settings ekranı; Cache Responses açık ve TTL 3600 olarak ayarlanmış

Adım 4 — İlk çağrı (MISS bekleniyor)

curl -s -D basliklar1.txt -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$CF_HESAP/ai/v1/chat/completions" \
  -H "Authorization: Bearer $CF_TOKEN" \
  -H "cf-aig-gateway-id: demo-tr" \
  -H "Content-Type: application/json" \
  -H 'cf-aig-metadata: {"kiraci":"acme-tr","demo":true,"kullanici":42}' \
  -H "cf-aig-cache-key: demo-tr:merhaba:v1" \
  -H "cf-aig-cache-ttl: 3600" \
  -w '\nilk-bayt=%{time_starttransfer}s toplam=%{time_total}s\n' \
  -d '{"model":"openai/gpt-4.1-mini","messages":[{"role":"user","content":"Cloudflare nedir? Tek cümlede."}]}' \
  -o govde1.json

grep -i 'cf-aig' basliklar1.txt

cf-aig-cache-status: MISS satırı ve curl'ün yazdırdığı toplam süre (tipik olarak 1-3 saniye)

Adım 5 — Aynı çağrıyı tekrarla (HIT bekleniyor)

Tamamen aynı komutu basliklar2.txt / govde2.json çıktılarıyla çalıştır.

diff govde1.json govde2.json && echo "yanıtlar birebir aynı"

cf-aig-cache-status: HIT satırı, çok düşük toplam süre, ve diff komutunun iki yanıtın birebir aynı olduğunu göstermesi

Süre onlarca milisaniyeye düşmeli. Resmî iddia “reduced latency by up to 90%”.

Adım 6 — Cache anahtarının anlamını kanıtla

# (a) aynı gövde, FARKLI özel anahtar -> MISS, ayrı kova
... -H "cf-aig-cache-key: demo-tr:merhaba:v2" ...

# (b) aynı anahtar ama cache atlanıyor -> MISS, sağlayıcıya gider
... -H "cf-aig-cache-key: demo-tr:merhaba:v1" -H "cf-aig-skip-cache: true" ...

# (c) özel anahtar YOK, gövde bir karakter değişti -> MISS

Üç curl çağrısının cf-aig-cache-status çıktıları; üçünün de MISS olduğu görülmeli

Bu adım, “exact match of the entire request” cümlesini bir paragraf anlatmaktan daha iyi öğretiyor.

Adım 7 — Logları oku

AI → AI Gateway → demo-tr → Logs.

Logs ekranı; zaman damgası, sağlayıcı, model, durum, token sayıları, maliyet, süre, user agent ve kiraci=acme-tr metadata'sı görünen satırlar

Metadata Key = kiraci ve Cache = cached filtrelerini uygulayarak HIT satırını yalnız bırakabilirsin.

Adım 8 — Gizlilik varyantı

Adım 4’ü -H "cf-aig-collect-log-payload: false" ekleyerek tekrarla.

Logs ekranında token, maliyet ve süre bilgisi olan ama prompt ve yanıt gövdesi görünmeyen bir kayıt

Bu, KVKK kaygısı olan bir ekibin ihtiyacının tam karşılığı: metrikler kalır, kişisel veri içerebilecek metin saklanmaz.

Adım 9 — Analytics’te sonucu gör

Analytics sekmesi; Requests artmış, Cached Responses yüzdesi sıfırdan büyük, Costs yalnızca MISS'lerde artmış — adım 2'deki ekran görüntüsüyle karşılaştırılabilir olmalı

Bu demoda ölçülenler: cf-aig-cache-status değeri · çağrı başına toplam ve ilk-bayt süresi · cache isabet yüzdesi · maliyet farkı · token farkı · log satır sayısı.

Demo 2: Dayanıklılık ve bütçe — timeout, retry, fallback, 429

Bu demoda kasten bozuyoruz ve gateway’in bunu nasıl emdiğini izliyoruz. Sonunda sert bir bütçe duvarına çarpıyoruz.

Adım 1 — Ön hazırlık

demo-tr gateway’inde Authentication açık olmalı. Provider Keys → Add API Key ile bir OpenAI ve bir Anthropic anahtarı sakla — Dynamic Routing bunları ister.

Provider Keys ekranı; OpenAI ve Anthropic anahtarları default takma adıyla listelenmiş

Adım 2 — Timeout’u zorla

curl -s -D b.txt -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$CF_HESAP/ai/v1/chat/completions" \
  -H "Authorization: Bearer $CF_TOKEN" \
  -H "cf-aig-gateway-id: demo-tr" \
  -H "Content-Type: application/json" \
  -H "cf-aig-request-timeout: 1" \
  -H "cf-aig-skip-cache: true" \
  -w '\nhttp=%{http_code} toplam=%{time_total}s\n' \
  -d '{"model":"openai/gpt-4.1-mini","messages":[{"role":"user","content":"Uzun bir deneme yazısı yaz."}]}'

1 milisaniyelik bütçeyle istek hemen düşer.

curl çıktısındaki hata ve Logs ekranında beliren hata satırı; Analytics'te Errors sayacının arttığı

Adım 3 — Retry ekle ve duvar saatinin uzadığını gör

... -H "cf-aig-request-timeout: 1" \
    -H "cf-aig-max-attempts: 3" \
    -H "cf-aig-retry-delay: 500" \
    -H "cf-aig-backoff: exponential" ...

Aynı isteğin retry başlıklarıyla çalıştırılmış hâli; toplam sürenin backoff gecikmeleri kadar arttığı görülmeli

Toplam süre backoff gecikmelerinin toplamı kadar uzar (500 ms, sonra ~1000 ms). Tavanlar: en fazla 5 deneme, en fazla 5000 ms gecikme.

Adım 4 — Makul bir timeout ile geçtiğini doğrula

Aynı çağrıyı cf-aig-request-timeout: 30000 ile tekrarla. http=200 ve tek temiz bir log satırı görmelisin.

Adım 5 — Dynamic Routing ile fallback kur

Panelde demo-tr → Dynamic Routes → Add Route, adı destek → Editor:

Start → Model A (Anthropic, claude-opus-4.7)
      → [hata durumunda] Model B (Workers AI, @cf/moonshotai/kimi-k2.6)
      → End

Save, ardından sürümü Deploy et.

destek route'unun görsel editörü; Model A ve Model B düğümleri ve deploy edilmiş sürüm göstergesi

Adım 6 — Route’u çağır ve cf-aig-step başlığını oku

Dikkat: dynamic route’lar yalnızca /compat üzerinde çalışır.

curl -s -D br.txt -X POST \
  "https://gateway.ai.cloudflare.com/v1/$CF_HESAP/demo-tr/compat/chat/completions" \
  -H "cf-aig-authorization: Bearer $CF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"dynamic/destek","messages":[{"role":"user","content":"Merhaba"}]}'

grep -i 'cf-aig-step' br.txt

cf-aig-step: 0 → birincil model yanıtladı. Şimdi birincili boz (Model A düğümünün timeout değerini 1 ms yap) ve tekrar çalıştır.

İki curl çıktısı yan yana: birincisinde cf-aig-step: 0, ikincisinde cf-aig-step: 1; Logs ekranında isteğin Workers AI modeline düştüğü görünmeli

Bu başlık, fallback’i anlatmanın en net yolu — tek satır, tek rakam, tartışmasız kanıt.

Adım 7 — Kiracı bazında bütçe koy ve duvara çarp

demo-tr → Spend limits → Add rule: Limit by metadata → anahtar kiraci → Split by value, bütçe $0.05, pencere günlük.

Sonra -H 'cf-aig-metadata: {"kiraci":"acme-tr"}' ile 50 çağrılık bir döngü çalıştır.

Döngünün çıktısı; belli bir noktadan sonra HTTP 429 dönmeye başladığı ve Spend limits ekranında acme-tr kiracısının bütçesinin dolduğu

Şimdi aynı döngüyü "kiraci":"beta-tr" ile çalıştır — çalışmaya devam etmeli. Split by value her kiracıya ayrı kova verir.

beta-tr metadata'sıyla yapılan çağrıların 200 dönmeye devam ettiği çıktı

Adım 8 — 429 yerine ucuz modele düşür

Bütçe sınırını destek route’unun birincil modeline bağlayıp yedek olarak ucuz bir model koy. Resmî ifade tam olarak bu senaryoyu tarif ediyor: “When the primary model’s budget is exceeded, AI Gateway automatically routes requests to the fallback model instead of blocking them.”

Bütçe aşıldığında cf-aig-step artık 0’dan 1’e döner, 429 yerine ucuz cevap gelir.

Adım 9 — Gateway geneli rate limit

Settings → Rate limiting aç, 60 saniyede 10 istek, teknik sliding. 15 hızlı çağrı at.

15 çağrılık döngünün çıktısı; ilk 10'unun 200, kalanların 429 döndüğü

fixed moduna geçip pencere sınırında tekrar denersen resmî dokümandaki 12:09/12:11 örneğini kendi gözünle görürsün.

Bu demoda ölçülenler: HTTP durum dağılımı · deneme başına toplam süre · cf-aig-step dağılımı · Errors sayacı · bütçe öncesi/sonrası maliyet · bütçe tavanının ne kadar aşıldığı · sabit ve kayan pencerede geçen istek sayısı.

Fiyatlandırma

Çekirdek ücretsiz

Resmî ifade: “AI Gateway is available to use on all plans.” ve “AI Gateway’s core features available today are offered for free, and all it takes is a Cloudflare account and one line of code to get started. Core features include: dashboard analytics, caching, and rate limiting.”

Limitler

İki dipnot önemli: ücretsiz planda log sınırı “applies to total logs across all gateways in your account”; Unified Billing hız sınırı ise yalnızca Cloudflare’in kendi kimlik bilgileriyle giden isteklere uygulanır — “This limit does not apply to requests that use your own provider keys through BYOK.”

Lisanslama ve hukuki çerçeve

Hizmet tescillidir ve Cloudflare Hizmet Şartları’na tabidir. Açık kaynak değildir.

Sağlayıcı sözleşmeleri devam eder. AI Gateway bir proxy olduğu için OpenAI, Anthropic veya Google ile olan sözleşmen aynen geçerlidir. Cloudflare bu sözleşmelerin tarafı değildir; kendi anahtarınla (BYOK) çalışıyorsan fatura ve sorumluluk sağlayıcıyla arandadır. Unified Billing kullanıyorsan Cloudflare aracı olur ama model çıktısının sorumluluğunu üstlenmez.

Guardrails garantisiz sunulur. Kullanılan Llama Guard modeli “provided as-is without any representations, warranties, or guarantees” ifadesiyle sağlanır. İçerik güvenliği yükümlülüğü altında olan bir üründe (örneğin çocuklara yönelik bir hizmette) tek savunma hattı olarak kullanılamaz — üstelik Türkçe desteklemiyor.

KVKK açısından üç araç var ve üçü de ayrı ayarlanır. cf-aig-collect-log-payload: false prompt ve yanıtın Cloudflare tarafında saklanmasını engeller. cf-aig-collect-log: false log kaydını tamamen kapatır. cf-aig-zdr: true sağlayıcı tarafında saklanmamasını sağlar — ama yalnızca OpenAI ve Anthropic için, yalnızca Unified Billing trafiğinde ve Cloudflare’in kendi loglamasını kapatmaz. Kişisel veri işleyen bir akışta üçünü birlikte değerlendir.

DLP ile aydınlatma yükümlülüğü. DLP taraması, kullanıcıların prompt’larının içerik olarak incelendiği anlamına gelir. Bu, aydınlatma metninde yer alması gereken bir işleme faaliyetidir.

Sık yapılan hatalar

Cloudflare token’ını gateway.ai.cloudflare.com üzerinde Authorization başlığına koymak. Resmî uyarı: “The Authorization header is reserved for provider credentials.” O uçta doğru başlık cf-aig-authorization. api.cloudflare.com üzerinde ise tam tersi.

Workers AI çağrılarında cf-aig-gateway-id başlığını unutmak. Resmî ifade: “Workers AI requests always require the cf-aig-gateway-id header.” Üçüncü taraf çağrılar default gateway’e düşer, @cf/ çağrıları düşmez.

Yalnızca AI Gateway yetkisi olan token’ı /ai/* uçlarında kullanmak. 401, hata kodu 10000.

BYOK anahtarını default dışında bir takma adla saklayıp binding’in onu kullanmasını beklemek. Sessizce Unified Billing’e düşer ve kredini harcar.

API ile Secrets Store gizli anahtarını yanlış adlandırmak. Ad tam olarak {gateway_id}_{provider_slug}_{alias} olmalı; Secrets Store’un döndürdüğü secret_id çalışma anında kullanılmaz.

Dynamic route sürümünü kaydedip deploy etmemek.

Dynamic route’u REST API’de çağırmak. “Dynamic routing is not currently available on the REST API.” /compat/chat/completions kullanman gerekiyor.

cf-aig-cache-ttl başlığının tek başına cache’i açtığını sanmak. Resmî ifade: “Use cf-aig-cache-ttl to set the caching duration for a request that already uses caching. To opt an individual request into caching, include cf-aig-cache-key.”

5’ten fazla metadata göndermek (“only the first five will be saved”), nesne göndermek (desteklenmiyor) veya cf.* anahtarı kullanmak (silinir).

DLP politikası değişikliğinin cache’lenmiş yanıtlara uygulandığını sanmak. Uygulanmaz; TTL dolana kadar eski yanıt döner. cf-aig-skip-cache ile aşabilirsin.

Streaming sohbet arayüzünde DLP yanıt taraması açmak. Yanıtın tamamı tamponlanır, ilk token süresi patlar.

Guardrails kategorilerini block yapıp fail-closed davranışını hesaba katmamak. Workers AI’a ulaşılamazsa istek engellenir.

Bütçe sınırlarının anlık olduğunu varsaymak. Eventually consistent.

Header Glossary’yi eksiksiz sanmak. Sayfa kendini “a complete list of all supported headers” diye tanıtıyor ama cf-aig-collect-log-payload, cf-aig-zdr ve cf-aig-byok-alias başlıkları listede yok.

Eskimiş cf-cache-ttl / cf-skip-cache yazımlarını kullanmak. Bunların yerini cf-aig-cache-ttl ve cf-aig-skip-cache aldı.