Workers AI

Workers AI nedir?

Workers AI, açık ağırlıklı yapay zekâ modellerini Cloudflare’in ağındaki GPU’larda çalıştıran serverless bir çıkarım (inference) platformudur. Resmî tanım:

“Workers AI allows you to run AI models in a serverless way, without having to worry about scaling, maintaining, or paying for unused infrastructure. You can invoke models running on GPUs on Cloudflare’s network from your own code — from Workers, Pages, or anywhere via the Cloudflare API.”

Çözdüğü somut problem şu: bir LLM’i, embedding modelini veya konuşma tanıma modelini kendi altyapında çalıştırmak istediğinde önce GPU kiralaman, sonra onu ölçeklendirmen, sonra da boşta durduğu saatlerde parasını ödemen gerekir. Workers AI bu üç adımı da ortadan kaldırır. GPU görmezsin, kapasite planlamazsın, ölçekleme yazmazsın — sadece model adını ve girdiyi verirsin.

Ayrıştırıcı özelliği konumdur: model, isteğin ulaştığı şehirdeki GPU’da çalışır. Yani çıkarım kullanıcının yanında yapılır, uzak bir bölgeye gidip gelmez.

Workers AI 2 Nisan 2024’te genel kullanıma açıldı. Resmî ifade: “our Workers AI inference platform is now Generally Available. After months of being in open beta, we’ve improved our service with greater reliability and performance, unveiled pricing, and added many more models to our catalog.”

Nasıl çalışır?

Binding — tek satır config

wrangler.jsonc dosyana şunu eklersin:

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

Ardından npx wrangler types çalıştırıp tip tanımlarını yenilersin. Artık Worker’ının env nesnesinde bir AI alanı vardır.

Çağrı imzası üç parametrelidir:

await env.AI.run(modelAdi, girdiNesnesi, secenekler);

Üçüncü parametre AI Gateway ayarlarını, batch bayrağını ve ekstra başlıkları taşır:

Binding üzerinde ayrıca env.AI.aiGatewayLogId, env.AI.gateway(ad) (ve onun .patchLog(), .getLog(), .getUrl() metodları) ile env.AI.toMarkdown() bulunur.

REST API — Worker olmadan

Aynı modelleri Worker yazmadan da çağırabilirsin:

curl https://api.cloudflare.com/client/v4/accounts/{HESAP_ID}/ai/run/@cf/google/gemma-4-26b-a4b-it \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -d '{ "messages": [{"role":"user","content":"Merhaba"}] }'

Token’ın Account → Workers AI → Read yetkisine sahip olmalı. Yalnızca AI Gateway yetkisi taşıyan bir token bu uçta 401, hata kodu 10000 döndürür — bu tuzağa çok düşülüyor.

OpenAI SDK’sıyla konuşmak istersen /ai/v1/chat/completions ve /ai/v1/responses uçları da var.

Model kataloğu

Katalogda 86 model var ve görev tipine göre ayrılmış durumda:

Model kartlarında görülen yetenek etiketleri: Cloudflare-hosted, Function calling, Reasoning, Vision, Batch, LoRA, Partner, Real-time, Beta, Deprecated.

Streaming

const answer = await env.AI.run('@cf/google/gemma-4-26b-a4b-it', {
  messages,
  stream: true,
});
return new Response(answer, { headers: { 'content-type': 'text/event-stream' } });

Kazanç toplam sürede değil, ilk token’a kadar geçen sürede (TTFB) görülür. Ölçerken time_total değil time_starttransfer bak.

Batch API — kapasite hatası almadan toplu iş

Yüz binlerce satırı gömmek gibi işlerde tek tek çağrı yaparsan er ya da geç 3040 No more data centers to forward the request to alırsın. Batch API bunu çözer:

“Asynchronous batch processing lets you send a collection (batch) of inference requests in a single call. Instead of expecting immediate responses for every request, the system queues them for processing and returns the results later.”

“Using the batch API will guarantee that your requests are fulfilled eventually, rather than erroring out if Cloudflare does not have enough capacity at a given time.”

{ queueRequest: true } ile kuyruğa alırsın, {"status":"queued","request_id":"..."} alırsın, sonra aynı modeli { request_id } ile çağırıp sonucu toplarsın. Tek sınır: toplam payload 10 MB’ın altında olmalı. Poll etmek yerine Cloudflare Queues’a cf.workersAi.model.batch.succeeded olayını dinletebilirsin.

Prompt (prefix) caching

Aynı sistem prompt’unu her istekte tekrar gönderiyorsan, Cloudflare önceden hesaplanmış giriş tensörlerini yeniden kullanabilir:

“It reduces Time to First Token (TTFT) and increases Tokens Per Second (TPS) throughput by reusing previously computed input tensors.”

“Cached input tokens are billed at a discounted rate compared to regular input tokens. Workers AI enables prefix caching by default for select models.”

İki kural, ikisi de kritik:

“To maximize cache hit rates, send the x-session-affinity header with a unique identifier for your session or agent.”

“Prefix caching matches the exact token sequence from the start of the prompt. A single token difference invalidates the cache from that point onward.”

Bundan çıkan pratik sonuç: sistem prompt’unun başına timestamp koyma. Resmî uyarı da aynen bunu söylüyor: “Including a timestamp at the start of a system prompt changes the prefix on every request, defeating the cache entirely.” Statik içerik (sistem prompt’u, tool tanımları) başa, değişken içerik (kullanıcı sorusu, zaman damgası) sona.

İndirim ciddi: kimi-k2.7-code için normal giriş milyon token başına $0.950, cache’lenmiş giriş $0.190 — %80 tasarruf.

GPU’lar nerede?

Lansmanda (Eylül 2023) “running on NVIDIA GPUs on Cloudflare’s global network”, genel kullanıma geçişte (Nisan 2024) “over 150 cities with GPUs today”, Birthday Week 2024’te “we have GPUs in over 180 cities, having doubled our capacity in a year”.

Kapasite yönetimi şöyle çalışıyor: “If the request would have to wait in a queue in the current city, it can instead be routed to another location.” Bu, gecikme açısından iyi haber ama veri yerelliği açısından dikkat edilmesi gereken bir cümle — çıkarımın hangi ülkede yapılacağı garanti değil.

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

Kullanılır

• Embedding üretimi. bge-m3 milyon token başına $0.012. Ücretsiz kota günde ~9,3 milyon token gömmene yeter. RAG kurarken en pahalı adım olması gereken yer burada neredeyse bedava.
• Sınıflandırma, özetleme, yeniden sıralama (rerank). Küçük ve ucuz modellerin gerçekten iyi olduğu işler. bge-reranker-base milyon giriş token’ı $0.003.
• Konuşma tanıma. whisper-large-v3-turbo dakika başına $0.0005 → bir saatlik ses ≈ 3 sent. Çağrı merkezi arşivi işlemek için karşılaştırılabilir bir fiyat bulmak zor.
• Kullanıcının yanında çalışması gereken düşük gecikmeli işler. Model kullanıcının bulunduğu şehirde çalışır; Frankfurt’a gidip gelmez.
• Zaten Workers üzerinde olan uygulamalar. Ayrı bir API anahtarı, ayrı bir fatura, ayrı bir gizli anahtar yönetimi yok.
• Belge → Markdown dönüşümü. env.AI.toMarkdown() PDF, DOCX, ODT ve daha fazlasını çevirir ve çoğu format için ücretsizdir.

Kullanılmaz

Yüksek hacimli sohbet ürünü çalıştıracaksan. Text Generation varsayılanı hesap başına 300 istek/dakika. Güçlü frontier modellerde bu 20 rpm’e düşüyor. Panelde artırma düğmesi yok; form doldurup beklemen gerekiyor. Kullanıcı sayın büyüyorsa bu tavana çarparsın.

Belirli bir frontier modele ihtiyacın varsa. Workers AI yalnızca açık ağırlıklı modelleri çalıştırır. Claude Opus veya GPT-5 gerekiyorsa yol AI Gateway’den geçer, Workers AI’dan değil.

“Ucuz + güçlü + yüksek hacim” üçlüsünü aynı anda istiyorsan. Katalogda böyle bir hücre yok: ucuz modeller (llama-3.2-1b, granite-4.0-h-micro, milyon token $0.017–0.027) hızlı ama zayıf; güçlü modeller (glm-5.3, kimi-k2.7-code, $0.95–1.40) hem 20 rpm sınırlı hem de Workers Paid gerektiriyor.

Model kimliğinin bir yıl sabit kalmasına ihtiyacın varsa. 86 modelin 17’si zaten Deprecated; tek bir changelog girdisi 18 modeli birden kaldırdı. Sabit marjla çalışan bir SaaS için bu gerçek bir risktir.

Offline geliştirme yapman gerekiyorsa. Yerel mock yok, wrangler dev bile hesabına bağlanır ve ücret üretir.

Sözleşmeyle garantili çıktı kalitesi arıyorsan. JSON Mode açıkça garanti vermiyor; Guardrails modeli “provided as-is without any representations, warranties, or guarantees” ifadesiyle sunuluyor.

Somut örnekler

Türkçe destek sohbeti — streaming

export default {
  async fetch(request, env) {
    const stream = await env.AI.run('@cf/google/gemma-4-26b-a4b-it', {
      messages: [
        { role: 'system', content: 'Sen yardımsever bir destek asistanısın. Sadece Türkçe yanıtla.' },
        { role: 'user', content: 'Kargom nerede?' },
      ],
      stream: true,
    }, {
      gateway: { id: 'default', metadata: { musteri: 'acme-tr' } },
    });

    return new Response(stream, {
      headers: { 'content-type': 'text/event-stream' },
    });
  },
};

RAG için çok dilli embedding üretimi

const { data } = await env.AI.run('@cf/baai/bge-m3', {
  text: [
    'Ürün iade politikamız 14 gündür.',
    'Kargo ücreti 500 TL üzeri ücretsizdir.',
  ],
});

await env.VECTORIZE.upsert(
  data.map((values, i) => ({ id: String(i), values })),
);

bge-m3 çok dilli, 60.000 token context penceresine sahip ve milyon token başına 1075 neuron — katalogdaki en ucuz embedding seçeneği. Vektör tarafı için Vectorize.

İki aşamalı arama: gömme, sonra yeniden sıralama

// 1. aşama: Vectorize'dan 50 aday getir (hızlı, kaba)
const adaylar = await env.VECTORIZE.query(sorguVektoru, { topK: 50 });

// 2. aşama: reranker ile ilk 5'i seç (yavaş, isabetli)
const siralanmis = await env.AI.run('@cf/baai/bge-reranker-base', {
  query: 'iade süresi ne kadar?',
  contexts: adaylar.matches.map((m) => ({ text: m.metadata.metin })),
});
// -> [{ id: 0, score: 0.94 }, { id: 7, score: 0.88 }, ...]

Vektör araması ucuz ama kaba, reranker pahalı ama isabetli. İkisini üst üste koymak, tek başına topK: 5 çekmekten belirgin şekilde daha iyi sonuç verir ve milyon giriş token’ına $0.003’e mal olur.

Serbest metinden yapılandırılmış veri çıkarma

const sonuc = await env.AI.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
  messages: [
    { role: 'system', content: 'Faturadan alanları çıkar.' },
    { role: 'user', content: faturaMetni },
  ],
  response_format: {
    type: 'json_schema',
    json_schema: {
      type: 'object',
      properties: {
        vkn:    { type: 'string' },
        tutar:  { type: 'number' },
        tarih:  { type: 'string' },
      },
      required: ['vkn', 'tutar', 'tarih'],
    },
  },
});

İki kural: stream: true ekleme (desteklenmiyor) ve JSON Mode couldn't be met hatasını yakalamayı unutma.

Belge yığınını Markdown’a çevirme

const sonuclar = await env.AI.toMarkdown([
  { name: 'sozlesme.pdf', blob: new Blob([pdfBytes], { type: 'application/pdf' }) },
  {
    name: 'rapor.docx',
    blob: new Blob([docxBytes], {
      type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    }),
  },
]);

RAG korpusu hazırlamanın en sessiz ama en can sıkıcı adımı budur. Resmî not: “toMarkdown is free for most format conversions.” Görsel dönüşümlerde nesne tanıma ve özetleme için Workers AI modelleri devreye girebilir ve ücretlendirilir.

200 bin satırlık katalogu toplu gömme

// 1) Kuyruğa al
const is = await env.AI.run('@cf/baai/bge-m3', {
  requests: satirlar.map((s, i) => ({ text: s.baslik, external_reference: `satir-${i}` })),
}, { queueRequest: true });
// -> { status: "queued", model: "@cf/baai/bge-m3", request_id: "000-000-000" }

// 2) Sonra sonucu topla
const bitti = await env.AI.run('@cf/baai/bge-m3', { request_id: is.request_id });

Her POST 10 MB’ın altında kalmalı. Poll etmek yerine bir Queue consumer’ı cf.workersAi.model.batch.succeeded olayına bağlarsan hiç beklemezsin.

Türkçe çağrı merkezi arşivini yazıya dökme

curl https://api.cloudflare.com/client/v4/accounts/$CF_HESAP/ai/run/@cf/openai/whisper-large-v3-turbo \
  -H "Authorization: Bearer $CF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"audio": {...}, "task": "transcribe", "language": "tr", "vad_filter": true}'

Dakika başına 46,63 neuron → $0.00051. Bir saatlik kayıt yaklaşık 3 sent.

Demo 1: Sıfırdan çalışan çıkarım ve Neuron sayacını izleme

Bu demonun amacı çalışan bir Worker yazmak değil sadece — paranın nereye gittiğini görmek. Sonunda bir çağrının kaç neuron yaktığını elle doğrulayacağız.

Gereken: Node 16.17.0 veya üstü, bir Cloudflare hesabı.

Adım 1 — Başlangıç durumunu kaydet

Panelde AI → Workers AI ekranını aç. İki rakamı not et: bugün kullanılan Neuron ve bugünkü istek sayısı. Saati de not et — sayaç 00:00 UTC’de, yani Türkiye saatiyle 03:00’te sıfırlanır.

AI → Workers AI ekranı, bugün kullanılan Neuron ve istek sayısı sıfır ya da başlangıç değerinde

Adım 2 — Projeyi oluştur ve binding’i ekle

npm create cloudflare@latest -- merhaba-ai

Sorulara sırayla: Hello World example → Worker only → TypeScript → git: Yes → deploy: No.

wrangler.jsonc dosyasına binding’i ekle:

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

npx wrangler types

npx wrangler types komutunun çıktısı ve worker-configuration.d.ts içinde AI: Ai; satırı

Adım 3 — Worker kodunu yaz

src/index.ts:

export interface Env { AI: Ai }

export default {
  async fetch(request, env): Promise<Response> {
    const url = new URL(request.url);
    const messages = [
      { role: 'system', content: 'Kısa ve net yanıt ver.' },
      { role: 'user', content: 'Cloudflare Workers nedir? Tek paragraf.' },
    ];

    if (url.pathname === '/stream') {
      const stream = await env.AI.run('@cf/google/gemma-4-26b-a4b-it', {
        messages, stream: true,
      });
      return new Response(stream, {
        headers: { 'content-type': 'text/event-stream' },
      });
    }

    const yanit = await env.AI.run('@cf/google/gemma-4-26b-a4b-it', { messages });
    return Response.json(yanit);
  },
} satisfies ExportedHandler<Env>;

Adım 4 — Yerelde çalıştır ve yanıt şeklini gör

npx wrangler dev
curl -s http://localhost:8787/ | jq

Beklenen yanıt şekli:

{
  "id": "...",
  "object": "chat.completion",
  "created": 0,
  "model": "@cf/google/gemma-4-26b-a4b-it",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "...", "refusal": null },
      "finish_reason": "stop",
      "logprobs": null
    }
  ]
}

Terminalde curl + jq çıktısı, chat.completion nesnesi ve üretilen Türkçe yanıt

Adım 5 — Streaming farkını ölç

curl -s -o /dev/null -w 'toplam=%{time_total}s ilk-bayt=%{time_starttransfer}s\n' \
  http://localhost:8787/
curl -s -o /dev/null -w 'toplam=%{time_total}s ilk-bayt=%{time_starttransfer}s\n' \
  -N http://localhost:8787/stream

İki curl komutunun yan yana çıktısı; streaming olanda ilk-bayt süresinin belirgin şekilde düşük olduğu görülmeli

Ölçtüğün fark toplam sürede değil, ilk bayt süresinde olmalı. Streaming toplam üretim süresini kısaltmaz; kullanıcının beklediği süreyi kısaltır.

Adım 6 — Yayına al

npx wrangler login
npx wrangler deploy

wrangler deploy komutunun çıktısı; Uploaded ve Deployed satırları, workers.dev adresi ve Version ID

Adım 7 — Aynı modeli REST API ile çağır

curl -s -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" \
  -d '{"model":"@cf/google/gemma-4-26b-a4b-it","messages":[{"role":"user","content":"Merhaba"}]}' \
  | jq '.usage'

jq ile süzülmüş usage nesnesi — prompt_tokens, completion_tokens ve total_tokens değerleri

Adım 8 — Sayacı tekrar oku ve hesabı elle doğrula

Panelde Workers AI ekranını yenile. Neuron sayacı artmış olmalı. Şimdi aritmetiği kendin yap:

@cf/google/gemma-4-26b-a4b-it → giriş 9091, çıkış 27273 neuron/milyon token.

500 giriş + 500 çıkış token için:

(0.0005 × 9091) + (0.0005 × 27273) = 4,55 + 13,64 ≈ 18,2 neuron
18,2 × $0.011 / 1000 ≈ $0.0002

Günlük ücretsiz 10.000 neuron bu boyuttaki yaklaşık 550 tura yeter.

AI → Workers AI ekranı, artan Neuron ve istek sayısı; adım 1'deki ekran görüntüsüyle karşılaştırılabilir olmalı

Adım 9 — Kota bitince ne oluyor (opsiyonel)

Ücretsiz plandaysan bir döngüyle kotayı tüketebilirsin. Görmen gereken:

HTTP 429 — kod 3036
"You have used up your daily free allocation of 10,000 neurons.
 Please upgrade to Cloudflare's Workers Paid plan if you would like to continue usage."

Terminalde 3036 kodlu 429 yanıtı; hata mesajının tam metni görünür olmalı

Bu demoda ölçülenler: bugünkü Neuron sayısı · istek sayısı · streaming ve normal çağrının ilk-bayt süresi · usage.total_tokens · elle hesaplanan maliyet.

Demo 2: Prompt caching A/B testi — aynı isteği %80 ucuza getirmek

Bu demo bir sayı üretiyor, ve o sayı bir ajan mimarisinde aylık faturanın kaderini belirliyor.

Kullanılacak model @cf/moonshotai/kimi-k2.6 — cache’lenmiş giriş fiyatı yayımlanan sekiz modelden biri. Giriş $0.950/M, cache’li giriş $0.190/M.

Adım 1 — Büyük ve statik bir prefix hazırla

Yaklaşık 4.000 token’lık bir sistem prompt’u + tool tanımı bloğu oluştur. Kritik kural: statik içerik başa, değişken içerik sona. Resmî ifade:

“Place static content first. System prompts, tool definitions, and shared instructions should appear at the beginning of the prompt. Put user-specific or dynamic content (timestamps, user queries) at the end.”

Hazırlanan prefix.json dosyasının içeriği ve yaklaşık token sayısı

Adım 2 — Soğuk çağrı (referans ölçüm)

OTURUM="ses_$(openssl rand -hex 6)"

curl -s -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$CF_HESAP/ai/run/@cf/moonshotai/kimi-k2.6" \
  -H "Authorization: Bearer $CF_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-session-affinity: $OTURUM" \
  -w '\nilk-bayt=%{time_starttransfer}s toplam=%{time_total}s\n' \
  -d @cagri1.json | jq '.result.usage // .usage'

Cache’lenmiş token sayısı 0 ya da hiç yok olmalı. Resmî beklenti: “The first request will usually be cold, so it is expected that cached tokens are not returned on the first hit.”

İlk çağrının usage nesnesi — cache'lenmiş token yok, ilk-bayt süresi yüksek

Adım 3 — Sıcak çağrı (aynı oturum, aynı prefix, farklı son mesaj)

curl -s -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$CF_HESAP/ai/run/@cf/moonshotai/kimi-k2.6" \
  -H "Authorization: Bearer $CF_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-session-affinity: $OTURUM" \
  -w '\nilk-bayt=%{time_starttransfer}s toplam=%{time_total}s\n' \
  -d @cagri2.json | jq '.result.usage // .usage'

Şimdi usage içinde cache’lenmiş token sayısı görünmeli ve ilk-bayt süresi düşmeli.

İkinci çağrının usage nesnesi; cache'lenmiş token sayısı sıfırdan büyük, ilk-bayt süresi bir öncekinden düşük

Adım 4 — Negatif kontrol A: oturum başlığını kaldır

Adım 3’ü x-session-affinity başlığı olmadan tekrarla. Cache isabet oranı düşecek, çünkü:

“Prefix caching only works when a request routes to the same model instance that holds the cached tensors.”

x-session-affinity başlığı olmayan çağrının usage nesnesi; cache'lenmiş token sayısının düştüğü görülmeli

Adım 5 — Negatif kontrol B: prefix’i zehirle

Sistem prompt’unun ilk satırına Şu an: 2026-09-01T12:34:56Z ekle ve aynı oturum kimliğiyle tekrar çağır.

Başına timestamp eklenmiş prompt ile yapılan çağrının usage nesnesi; cache'lenmiş token sayısı sıfıra düşmüş olmalı

Bu, bu sayfadaki en öğretici ekran görüntüsü. “A single token difference invalidates the cache from that point onward” cümlesini bir paragraf anlatmaktansa bu tabloyu göstermek daha etkili.

Adım 6 — Parayı hesapla

4.000 token’lık prefix için:

Aylık 100.000 ajan turunda: $380 → $64.

Adım 7 — AI Gateway’den geçir ve panoda gör

İsteğe -H "cf-aig-gateway-id: default" ekle, sonra AI → AI Gateway → Logs ekranını aç.

AI Gateway Logs ekranı; token sayıları, maliyet, süre ve user agent sütunlarıyla birlikte demo istekleri

Bu demoda ölçülenler: cache’li ve cache’siz token sayıları · her çağrının ilk-bayt süresi · prefix zehirlenmesinin cache üzerindeki etkisi · 4.000 token’lık prefix’in çağrı başına maliyeti · aylık projeksiyon.

Fiyatlandırma

Model

Resmî tanım: “Neurons are our way of measuring AI outputs across different models, representing the GPU compute needed to perform your request.”

Model ailelerine göre birim farkı

Her model ailesi farklı bir birim üzerinden ölçülür:

• LLM’ler — milyon giriş token’ı + milyon çıkış token’ı (8 modelde ayrıca milyon cache’lenmiş giriş token’ı)
• Embedding — yalnızca milyon giriş token’ı, çıkış ücreti yok
• Görsel — 512×512 karo başına ve/veya adım (step) başına; FLUX.2 klein 9B megapiksel başına
• Ses — ses dakikası başına (Whisper, Deepgram) ya da 1.000 karakter girdi başına (Deepgram Aura TTS). Aynı modelin WebSocket sürümü HTTP’den pahalı: nova-3 $0.0052/dk, nova-3 (WebSocket) $0.0092/dk.
• Diğer — sınıflandırma ve rerank milyon giriş token’ı; ResNet-50 milyon görsel başına

Temsili fiyatlar

Rate limit tablosu

Frontier modeller, hesap ve model başına:

Diğer sabit limitler

Sık görülen hata kodları

AI Gateway kredisiyle ödeme

Resmî ifade: “You can use prepaid AI Gateway credits to pay for Workers AI inference.” İki yan etkisi var ve ikisi de işine yarayabilir: ücretsiz planda paid-gated modelleri açar ve frontier rate limit’ini 20 rpm’den 50 rpm’e çıkarır. Bedeli, satın alınan kredi üzerinden %5 komisyondur.

Lisanslama ve hukuki çerçeve

Hizmetin kendisi tescillidir ve Cloudflare Hizmet Şartları’na tabidir. Açık kaynak değildir, kendi altyapına kuramazsın.

Modeller kendi lisanslarını taşır. Katalogdaki modeller Meta (Llama), Google (Gemma), Mistral, Alibaba (Qwen), DeepSeek, Moonshot, Z.ai gibi farklı sağlayıcılardan gelir ve her birinin lisans koşulları farklıdır. Llama modelleri için Cloudflare ayrı bir onay adımı zorunlu kılar — kabul etmeden çağırırsan 5016 / 403 "User has not agreed to Llama3.2 model terms" alırsın. Ticari kullanım öncesinde kullandığın modelin lisansını kendin okumalısın; Cloudflare’in hizmet şartları model lisansının yerine geçmez.

Veri işleme. Girdilerin model eğitiminde kullanılmaz:

“Cloudflare does not use your Customer Content to (1) train any AI models made available on Workers AI or (2) improve any Cloudflare or third-party services, and would not do so unless we received your explicit consent.”

KVKK açısından üç nokta. Birincisi, yukarıdaki cümle işleme amacının sınırlandığını gösterir ve veri işleyen sözleşmene dayanak yapılabilir. İkincisi, çıkarımın hangi ülkede yapılacağı garanti edilmez — kapasite yoksa istek başka bir lokasyona yönlendirilir; bu, yurt dışına aktarım değerlendirmesi yapmanı gerektirir. Üçüncüsü, Workers AI için Data Localization Suite kapsamında bir veri yerelliği taahhüdü resmî kaynaklarda yer almamaktadır ve Cloudflare hiçbir belgesinde KVKK uyumu iddia etmez.

Prompt’larının loglanmasını kontrol etmek istiyorsan bu Workers AI’ın değil AI Gateway’in konusudur — cf-aig-collect-log-payload: false ile metrikleri tutup içeriği saklamayabilirsin.

Sık yapılan hatalar

wrangler dev’i ücretsiz sanmak. Model her durumda Cloudflare’in GPU’sunda çalışır, ücret üretir ve rate limit’e sayılır.

Resmî hızlı başlangıç örneğini kopyalamak. REST kılavuzu hâlâ @cf/meta/llama-3.1-8b-instruct gösteriyor ve o model Deprecated. Model adını her zaman katalogdan doğrula.

Sistem prompt’unun başına timestamp koymak. Prefix cache’i tamamen öldürür. Zaman bilgisi gerekiyorsa prompt’un sonuna koy.

x-session-affinity göndermemek ve sonra cache’lenmiş token sayısının neden hep sıfır olduğunu merak etmek.

max_tokens değerini context window’un üstünde vermek. Resmî ifade: “This limit cannot exceed the context window.”

JSON Mode ile stream: true kullanmak. Desteklenmiyor.

LoRA’da raw: true unutmak. Adaptörünün eğitildiği şablon yerine temel modelin sohbet şablonu uygulanır ve sonuçlar bozulur.

LoRA dosyalarını farklı adlandırmak. adapter_config.json ve adapter_model.safetensors dışında bir ad kabul edilmez.

10 MB’ı aşan batch payload göndermek.

Yalnızca AI Gateway yetkisi olan token’la /ai/* çağırmak. 401, hata kodu 10000. Gereken yetki Workers AI → Read.

@cf/ modellerini /ai/v1/messages ucunda çağırmayı denemek. Anthropic şeması yalnızca üçüncü taraf modelleri kabul eder.

JSON Mode couldn't be met hatasını yakalamamak.

Blog yazılarını güncel doküman sanmak. Neuron’ların kalktığı, LoRA sınırının 100MB olduğu, ücretsiz katmanın “günde 10.000 token” olduğu iddialarının hepsi eskimiş blog kayıtlarından geliyor.