AI Search

AI Search nedir?

AI Search, kendi içeriğin üzerinde arama kurmanın tüm ara adımlarını üstlenen yönetilen bir servistir. Resmî tanım:

“AI Search is a managed search service. Connect a website, an R2 bucket, or upload your own documents, and AI Search indexes your content for natural language queries.”

“AI Search lets you add search to any application or agent without having to build an entire retrieval infrastructure. Create an instance, give it your data, and search it with natural language.”

Çözdüğü problem RAG’in kendisi değil, RAG’in tesisatı: belgeyi parse etmek, Markdown’a çevirmek, parçalara bölmek, embedding üretmek, saklamak, aramak, yeniden sıralamak — ve herkesin kurmayı unuttuğu kısım, içerik değiştikçe bunu sürekli tekrarlamak.

Cloudflare’in kendi karşılaştırma tablosu ayrımı net koyuyor:

Yarım kalmış isim değişikliği

Bu ürün 7 Nisan 2025’te AutoRAG adıyla açık betaya çıktı (Developer Week 2025):

“Today we’re excited to announce AutoRAG in open beta, a fully managed Retrieval-Augmented Generation (RAG) pipeline powered by Cloudflare, designed to simplify how developers integrate context-aware AI into their applications.”

25 Eylül 2025’te yeniden adlandırıldı: “AutoRAG is now AI Search!”

Ama isim değişikliği tamamlanmadı. Bugün hâlâ ikisi bir arada yaşıyor:

İsim değişmedi, API de değişti

Yeniden adlandırma bir takma ad operasyonu değildi; arkasında gerçek bir API tasarımı var:

Alan eşlemesi: data[].file_id → chunks[].id, data[].filename → chunks[].item.key, data[].content[].text → chunks[].text.

Yeni binding’ler için asgari sürümler: @cloudflare/workers-types 4.20260304.0, wrangler 4.68.1.

Nasıl çalışır?

Indexleme — asenkron, altı adım

Resmî sıra:

1. Veri alımı — bağlı kaynaktan veya Items API ile yüklenen dosyalardan
2. Markdown’a çevirme — “AI Search uses Workers AI’s Markdown Conversion to convert supported data types into structured Markdown… For images, Workers AI is used to perform object detection followed by vision-to-language transformation.”
3. Chunking — “The extracted text is chunked into smaller pieces to improve retrieval granularity.”
4. Embedding — “Each chunk is embedded using Workers AI’s embedding model.”
5. Anahtar kelime indexleme — “When keyword search is enabled, each chunk is also indexed for BM25 keyword matching.”
6. Depolama — vektörler, anahtar kelime index’i ve içerik saklanır

Sorgulama — senkron, dokuz adım

Sorgu alınır → query rewriting (opsiyonel) → sorgu embed edilir → vektör araması → anahtar kelime araması (opsiyonel, BM25, paralel) → füzyon (opsiyonel) → rerank (opsiyonel, cross-encoder) → içerik getirilir → cevap üretilir (yalnızca Chat Completions’ta).

Search ucunu kullanıyorsan sekizinci adımda durur ve parçaları ham hâlde alırsın; cevabı kendi modelinle üretebilirsin.

Veri kaynakları — sadece üç tane

D1, KV, PostgreSQL, S3, Notion, Confluence, Drive ve Slack desteklenmiyor.

Desteklenen dosya tipleri ve 4 MB sınırı

Düz metin: .txt .rst .log .md .mdx .json .yaml .yml .csv .sql .css .js .php .py .rb .java .c .cpp .go .rs .swift .dart ve benzerleri.

Zengin format (Markdown Conversion üzerinden): .pdf, görseller (.jpeg .jpg .png .webp .svg .gif .bmp), .html .htm, .xml, MS Office (.xlsx .xlsm .xls .docx), ODF (.ods .odt), Apple .numbers.

“AI Search has a file size limit of up to 4 MB. Files that exceed this limit will not be indexed and will show up in the error logs.”

Web sitesi tarama

İki tarama tipi var:

discover varsayılanları: limit 100.000, depth 5, max_age 86.400 saniye, include_external_links false, include_subdomains false.

Sitemap arama sırası: yapılandırdığın özel sitemap adresleri → robots.txt → /sitemap.xml. <priority> sıralama için, <changefreq> yeniden tarama sıklığı için kullanılıyor. İkisi de yoksa “AI Search automatically crawls each link once a day.”

Crawler user agent’ları: Cloudflare-AI-Search (kendi alan adların) ve Cloudflare-AI-Search-External. WAF’ta izin vermek için Bot Detection ID 122933950 → Skip.

Chunking

“AI Search uses recursive chunking, which breaks your content at natural boundaries (like paragraphs or sentences), and then further splits it if the chunks are too large.”

• Chunk boyutu — chunk başına token sayısı; asgari 64, üst sınır modele bağlı
• Chunk örtüşmesi — komşu chunk’lar arası örtüşen token yüzdesi; 0%–30%

Boyutlandırma kısıtı: “Generation models have a limited context window that must fit all retrieved chunks (max_num_results × chunk size), the user query, and the model’s output.”

Cloudflare’in kendi pratik önerisi: “Configure your AI Search instance with small chunk sizes (256 tokens is usually enough).”

Senkronizasyon

“Jobs run automatically on a schedule, every 6 hours by default.”

sync_interval seçenekleri: 3600 (1s), 7200 (2s), 14400 (4s), 21600 (6s, varsayılan), 43200 (12s), 86400 (24s). Elle tetikleme en fazla 30 saniyede bir.

Otomatik duraklama — kolayca gözden kaçıyor:

“If an instance receives no search request for 31 days, AI Search automatically pauses its scheduled sync jobs… A paused instance stays fully searchable, but source changes are not picked up while sync jobs are paused. After the instance receives search or chat traffic again, AI Search automatically resumes scheduled sync jobs.”

Arama modları

“AI Search supports three search modes: vector, keyword, and hybrid. By default, new instances use vector search only.”

• Vektör — anlam benzerliği. index_method.vector varsayılan true. Embedding modeli “cannot be changed after creation.”
• Anahtar kelime — BM25 tam metin araması. index_method.keyword varsayılan false. Tokenizer porter (varsayılan, doğal dil için) veya trigram (“Best for code”). keyword_match_mode: and (varsayılan, yüksek kesinlik) / or (yüksek kapsam).
• Hybrid — ikisi paralel çalışır ve birleştirilir. fusion_method: rrf (varsayılan, Reciprocal Rank Fusion) veya max.

Her parça için dönen tanılama alanları: vector_score, keyword_score (ham BM25), vector_rank, keyword_rank, fusion_method, reranking_score.

Query rewriting

“Query rewriting is an optional step… that improves retrieval quality for follow-up queries.”

“Query rewriting requires the messages format and does not apply when using the query format. The first message is always used as-is.”

Örnek: Cloudflare Workers nedir? (olduğu gibi kullanılır) → takip sorusu Nasıl deploy ederim? → deploy Cloudflare Worker getting started olarak yeniden yazılır.

Varsayılan rewrite_query false. Maliyeti: “Enabling query rewriting adds an extra LLM call to the query pipeline, which may increase latency.”

Similarity cache

AI Gateway’in tam-eşleşme cache’inden farklı çalışıyor:

“AI Search’s similarity cache uses MinHash and Locality-Sensitive Hashing (LSH)”

Varsayılan açık. Dört eşik:

TTL seçenekleri saniye cinsinden: 600, 1800, 3600, 7200, 21600, 43200, 86400, 172800 (48 saat, varsayılan), 259200, 518400. Haziran 2026’da sabit 30 günden bu listeye geçildi.

Otomatik geçersiz kılma da var: “Cached responses are tied to specific document chunks. If those chunks change or get deleted, the cache clears to keep answers fresh.”

Rerank, boost ve sonuç kontrolleri

Rerank: “By default, reranking is disabled for all AI Search instances.” Model @cf/baai/bge-reranker-base (512 token girdi, milyon token $0.003). Ayrı bir reranking.match_threshold var (0–1, varsayılan 0.4).

Boost: en fazla 3 alan. Pipeline: “AI Search retrieves up to 50 candidate chunks… The boost is additive to the original retrieval score.”

Kritik kısıt: “Boosting re-ranks the candidate set from the initial search. It cannot surface documents that were not retrieved.”

Sonuç kontrolleri: match_threshold 0–1, varsayılan 0.4 — ve önemli bir ayrıntı: “filters on the vector similarity score, not the fused score returned in the response.” max_num_results 1–50, varsayılan 10. context_expansion 0–3, varsayılan 0. “If no results meet the threshold, AI Search will not generate a response.”

Kendi modelini getirme

“All AI Search instances support models from Workers AI. You can use other providers (such as OpenAI or Anthropic) in AI Search by adding their API keys to an AI Gateway and connecting that gateway to your AI Search.”

Desteklenen üretim modelleri arasında Anthropic Claude ailesi, Google Gemini 2.5, OpenAI GPT-5 ailesi, Grok 4, Groq Llama’ları ve Workers AI modelleri var. Embedding tarafında google-ai-studio/gemini-embedding-001, openai/text-embedding-3-small / -3-large, @cf/baai/bge-m3, @cf/qwen/qwen3-embedding-0.6b (8.192 token girdi ile en geniş context’li Workers AI seçeneği) ve @cf/google/embeddinggemma-300m.

Smart Default seçeneği de var: “AI Search will select a Cloudflare recommended model and will update it automatically for you over time.” Hangi modele denk geldiği hiçbir yerde belirtilmemiş — model değişimini kontrol etmen gerekiyorsa açıkça bir model seç.

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

Kullanılır

• Elinde PDF, DOCX, XLSX ve görsel varsa. Markdown’a çevirme dahil ve ücretsiz sayılan kısımların çoğunu kapsıyor. Bunu Vectorize üstüne kendin kurmak haftalar sürer.
• İçerik sürekli değişiyorsa. Crawler, sitemap takibi, değişen dosyaların yeniden indexlenmesi, silinen dosyaların temizlenmesi, hatalı dosyaların yeniden denenmesi — hepsi otomatik.
• BM25 + füzyon + rerank istiyorsan. Vectorize yalnızca yoğun vektör araması yapıyor; bunları eklemek AI Search’ün işi.
• Kiracı başına arama kurman gerekiyorsa. Çalışma anında instance oluşturabilirsin, ücretli planda hesap başına 5.000 tane.
• Hazır arayüz veya MCP ucu istiyorsan. Gömülebilir arama bileşenleri ve tek araçlı bir MCP sunucusu kutudan çıkıyor.
• Bugün ücretsiz olması işine geliyorsa — depolama, vektör indexleme ve crawler için Browser Run kullanımı dahil.

Kullanılmaz

Dosyaların 4 MB’ın üzerindeyse. Sert sınır, iki planda da aynı, ve AI Search bölmez.

Kaynağın bir veritabanıysa. D1, KV, PostgreSQL desteklenmiyor. Veriyi R2’ye dosya olarak çıkarmak zorundasın. Vectorize’da D1’i okuyup embed etmek doğrudan mümkün.

Sorgu başına 50’den fazla parça gerekiyorsa. max_num_results üst sınırı 50; Vectorize 100 veriyor.

Embedding modelini değiştirebilmen gerekiyorsa. Instance oluşturulduktan sonra imkânsız.

5’ten fazla özel metadata alanı gerekiyorsa. Instance başına 5, üstüne üç rezerve ad (timestamp, folder, filename). Vectorize 10 metadata index’i veriyor.

Kendi chunking stratejin varsa. Yalnızca recursive chunking, boyut ve örtüşme ile ayarlanabiliyor. Markdown başlığına duyarlı, kod AST’sine duyarlı veya parent-document retrieval istiyorsan kendin kurman gerekir.

AI Search’te olmayan bir retrieval stratejisi gerekiyorsa — HyDE, çoklu sorgu dağıtımı, RAG-fusion, graph RAG, ColBERT. Ayrıca tek bir rerank modeli destekleniyor.

Öngörülebilir üretim fiyatı gerekiyorsa. Açık betada ücretsiz ve fiyatlandırma 30 gün önce duyurulacak. 2026’nın son çeyreğinde ürün çıkaracaksan bu gerçek bir iş riski.

Ücretsiz planda ayda 20.000’den fazla sorgu yapacaksan. Sert sınır.

1 milyondan fazla dosyan varsa (hybrid ile 500.000). Hata kodları ai_search_is_full ve hybrid_search_is_full; ikincisi tüm instance’ı duraklatıyor.

Dış kaynakta yazma sonrası tazelik gerekiyorsa. Varsayılan 6 saat, en sık 1 saat. Yalnızca built-in storage anında indexliyor.

Somut örnekler

wrangler.jsonc:

{
  "compatibility_date": "2026-03-27",
  "ai_search_namespaces": [
    { "binding": "AI_SEARCH", "namespace": "default", "remote": true }
  ]
}

remote: true zorunlu — resmî not: “AI Search has no local emulator, so the binding always talks to the remote service.”

Kendi doküman siten üzerinde arama

npx wrangler ai-search create dokuman --type web-crawler --source docs.sirketiniz.com.tr
npx wrangler ai-search stats dokuman
npx wrangler ai-search search dokuman --query "fatura nasıl iptal edilir"

Kaynak gösteren sohbet

const r = await env.AI_SEARCH.get('dokuman').chatCompletions({
  messages: [
    { role: 'system', content: 'Sadece verilen dokümanlara dayanarak cevapla.' },
    { role: 'user', content: soru },
  ],
  model: '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
  ai_search_options: {
    retrieval: { max_num_results: 5 },
    query_rewrite: { enabled: true },
  },
});

const cevap = r.choices[0].message.content;
const kaynaklar = r.chunks.map((c, i) => ({
  no: i + 1,
  dosya: c.item.key,
  skor: c.score,
}));

Kiracı başına instance — çalışma anında oluşturma

// Yeni müşteri kaydı
await env.AI_SEARCH.create({ id: `kiraci-${kiraciId}` });

// Belge yükleme
await env.AI_SEARCH
  .get(`kiraci-${kiraciId}`)
  .items.upload(dosya.name, await dosya.arrayBuffer());

// Arama
const sonuc = await env.AI_SEARCH.get(`kiraci-${kiraciId}`).search({ query });

// Müşteri ayrılırken
await env.AI_SEARCH.delete(`kiraci-${kiraciId}`);

Tek instance’ta kalmak istiyorsan klasör önekiyle de ayırabilirsin — “ile başlar” idiyomuna dikkat:

filters: { folder: { $gte: `${kiraciId}/`, $lt: `${kiraciId}0` } }

Genel bilgi tabanı ile kiracı verisini tek çağrıda arama

const sonuclar = await env.AI_SEARCH.search({
  query,
  ai_search_options: {
    instance_ids: ['genel-bilgi', `kiraci-${kiraciId}`],
  },
});

const kiraciSonuclari = sonuclar.chunks.filter(
  (c) => c.instance_id === `kiraci-${kiraciId}`,
);

Resmî davranış: “If one instance fails… the others still return, and the failure is reported in errors instead of throwing.” En fazla 10 instance.

Kod araması — trigram tokenizer ile hybrid

npx wrangler ai-search create kod --type r2 --source repo-bucket \
  --hybrid-search true --chunk-size 256 \
  --include-items '**/*.ts' --include-items '**/*.go' \
  --exclude-items '**/node_modules/**'

await env.AI_SEARCH.get('kod').update({
  indexing_options: { keyword_tokenizer: 'trigram' },
});

const r = await env.AI_SEARCH.get('kod').search({
  query: 'ERR_CONNECTION_REFUSED',
  ai_search_options: {
    retrieval: { retrieval_type: 'hybrid', keyword_match_mode: 'and' },
  },
});

Hata kodu, SKU veya değişken adı gibi tam eşleşme gereken sorgularda vektör araması tek başına zayıf kalır; trigram tokenizer bu boşluğu kapatır.

Retrieval al, cevabı kendi modelinle üret

const s = await env.AI_SEARCH.get('bilgi').search({
  messages: [{ role: 'user', content: soru }],
});

const baglam = s.chunks
  .map((c) => `<dosya ad="${c.item.key}">${c.text}</dosya>`)
  .join('\n\n');

// Cevabı kendi seçtiğin modelle üret

AI Search’ü yalnızca retrieval motoru olarak kullanmak, cevap üretimi üzerindeki kontrolü korumanın yoludur.

Demo 1: Gerçek bir belge setini indexlemek

Bu demoda pipeline’ın her aşamasını sayılarla izliyoruz: iş ilerlemesi, parça ve vektör sayısı, depolanan byte, aramaya hazır olma süresi ve dosya bazında hatalar.

Korpus: gerçek ve tekrar üretilebilir bir şey seç — 300–500 dosya: ürün PDF’lerin, bir docs/ Markdown ağacı ve görsel→Markdown yolunu test etmek için 20 taranmış PNG.

Adım 1 — Ön uçuş kontrolü

du -sh ./korpus && find ./korpus -type f | wc -l
find ./korpus -type f -size +4M          # BU BOŞ ÇIKMALI

du, find ve wc çıktıları; 4 MB üstü dosya araması boş dönmeli

Adım 2 — Instance oluştur ve varsayılanları kaydet

npx wrangler ai-search create demo-bilgi --json

npx wrangler ai-search get demo-bilgi --json | jq '{
  id, type, embedding_model, chunk_size, chunk_overlap,
  index_method, sync_interval, cache, cache_ttl,
  rewrite_query, reranking, max_num_results, score_threshold
}'

wrangler ai-search get --json çıktısı; chunk_size, chunk_overlap, embedding_model ve reranking değerleri görünür olmalı

Bu çıktı, bu sayfanın en değerli ekran görüntülerinden biri: varsayılan chunk_size ve chunk_overlap değerleri hiçbir resmî dokümanda yazmıyor. Burada gözlemlenen değeri not et ve “gözlemlenen” olarak etiketle.

Adım 3 — Yükle ve süreyi ölç

time (for f in ./korpus/*; do
  curl -s -X POST \
    "https://api.cloudflare.com/client/v4/accounts/$ACC/ai-search/instances/demo-bilgi/items" \
    -H "Authorization: Bearer $TOKEN" -F "file=@$f" > /dev/null
done)

Adım 4 — Indexleme ilerlemesini izle

Bu demonun çekirdek gözlemi:

while :; do
  npx wrangler ai-search stats demo-bilgi --json \
  | jq -c '{
      t: (now|todate), queued, running, completed, error, skipped, outdated,
      vektor: .engine.vectorize.vectorsCount,
      boyut:  .engine.vectorize.dimensions,
      nesne:  .engine.r2.objectCount,
      byte:   .engine.r2.payloadSizeBytes
    }'
  sleep 5
done | tee ilerleme.jsonl

ilerleme.jsonl akışının terminal çıktısı; queued azalırken completed ve vektor sayısının arttığı ardışık satırlar

Adım 5 — İş loglarını ve hataları oku

npx wrangler ai-search jobs list demo-bilgi --json
npx wrangler ai-search jobs logs demo-bilgi <IS-ID>
npx wrangler ai-search stats demo-bilgi --json | jq '.file_embed_errors'

jobs logs komutunun çıktısı ve file_embed_errors listesindeki başarısız dosyalar

Adım 6 — İlk sorguyu at

npx wrangler ai-search search demo-bilgi --query "iade politikası kaç gün" --json

search --json çıktısı; chunks dizisi, her parçanın item.key, text ve score alanları

Adım 7 — Paneli gez

AI Search → demo-bilgi → Overview; Indexed Items listesi ve dosya bazında durum göstergeleri

Jobs sekmesi; iş listesi, durumları ve gerçek zamanlı log görünümü

Metrics sekmesi; dosya indexleme, arama etkinliği ve en çok getirilen içerikler

Adım 8 — Model çağrılarının faturasını AI Gateway’de gör

Bağlı AI Gateway'in Logs ekranı; embedding çağrıları, token sayıları ve maliyetleri

Burada ayrıca AI Search’ün kullandığı etkin sistem prompt’unu da görebilirsin — resmî ifade: “You can view the effective system prompt used for any AI Search’s model call through AI Gateway logs.” Bu prompt’un tam metni dokümanlarda yayımlanmıyor.

Adım 9 — Chunk boyutunun etkisini ölç

npx wrangler ai-search create demo-bilgi-256  --chunk-size 256  --chunk-overlap 10
npx wrangler ai-search create demo-bilgi-1024 --chunk-size 1024 --chunk-overlap 10

Aynı korpusu ikisine de yükle ve ilerleme.jsonl dosyalarını karşılaştır.

256 ve 1024 token chunk boyutlu iki instance için vectorsCount karşılaştırması

256 token, 1024 token’a göre yaklaşık 4 kat parça üretir — yani yaklaşık 4 kat embedding maliyeti ve 4 kat saklanan vektör boyutu. Bu, AI Search’teki en etkili maliyet kaldıracıdır ve böyle ölçmeden görünmez.

Adım 10 — Hataları kasten üret

Hata loglarında over_size, filename_exceeds_maximum_length ve page_limit_reached kayıtları

Bu demoda ölçülenler: ilk sonuca kadar geçen süre · tam indexlemeye kadar geçen süre · dakikada dosya · dosya başına parça sayısı · embedding boyutu (hangi modelin kullanıldığını doğrular) · saklanan byte · hata oranı ve sebepleri · yükleme için harcanan Workers AI tutarı.

Demo 2: Retrieval kalitesini ayarlamak

Bu demo bir merdiven: her basamakta tek bir değişken değiştirip isabet oranını ve gecikmeyi ölçüyoruz. Sonunda hangi ayarın parasını hak ettiğini gösteren bir tablo çıkıyor.

Adım 1 — Gold set kur (bu adımı atlama)

goldset.tsv:  <soru>\t<beklenen item.key>

40–60 gerçek kullanıcı sorusu — destek gelen kutusundan veya site arama loglarından. Uydurma soru kullanma; Türkçe korpusta özellikle önemli, çünkü model kalitesini ancak gerçek dil kullanımıyla ölçebilirsin.

goldset.tsv dosyasının ilk satırları; gerçek Türkçe sorular ve karşılık gelen doküman anahtarları

Adım 2 — Ölçüm Worker’ını yaz

export default {
  async fetch(req, env): Promise<Response> {
    const u = new URL(req.url);
    const opts = JSON.parse(u.searchParams.get('opts') ?? '{}');
    const t0 = Date.now();

    const r = await env.AI_SEARCH.get('demo-bilgi').search({
      messages: [{ role: 'user', content: u.searchParams.get('q') }],
      ai_search_options: opts,
    });

    return Response.json({
      ms: Date.now() - t0,
      yeniden_yazilan: r.search_query,           // rewrite sonucu
      anahtarlar: r.chunks.map((c) => c.item.key),
      skorlar:    r.chunks.map((c) => c.score),
      detay:      r.chunks.map((c) => c.scoring_details),
    });
  },
};

scoring_details içinde vector_score, keyword_score, vector_rank, keyword_rank, fusion_method ve reranking_score döner — ayarların ne yaptığını görmenin tek yolu bu.

Adım 3 — Merdiveni çık

calistir() {   # $1 = etiket, $2 = opts JSON
  while IFS=$'\t' read -r soru dogru; do
    curl -s "https://<worker>/?q=$(printf %s "$soru" | jq -sRr @uri)&opts=$(printf %s "$2" | jq -sRr @uri)" \
    | jq -c --arg L "$1" --arg g "$dogru" \
        '{kosu:$L, ilk1:(.anahtarlar[0]==$g), ilk5:(.anahtarlar[0:5]|index($g)!=null), ms}'
  done < goldset.tsv
}

calistir R0 '{}'                                                          # temel
calistir R1 '{"retrieval":{"max_num_results":25}}'                        # daha çok aday
calistir R2 '{"retrieval":{"max_num_results":25,"match_threshold":0.2}}'  # eşiği gevşet
calistir R3 '{"retrieval":{"max_num_results":25,"match_threshold":0.6}}'  # eşiği sıkılaştır

R0-R3 koşularının jq ile özetlenmiş çıktısı; her koşu için isabet oranı ve gecikme

Adım 4 — Hybrid’e geç (tam yeniden indexleme gerektirir)

npx wrangler ai-search update demo-bilgi --hybrid-search true
# Bu tüm korpusu yeniden indexler; stats'te queued==0 && running==0 olana kadar bekle

calistir R4 '{"retrieval":{"retrieval_type":"hybrid","max_num_results":25}}'
calistir R5 '{"retrieval":{"retrieval_type":"hybrid","keyword_match_mode":"or","max_num_results":25}}'
calistir R6 '{"retrieval":{"retrieval_type":"hybrid","fusion_method":"max","max_num_results":25}}'

index_method değişikliğinden sonra başlayan tam yeniden indexleme işi ve süresi

R0 ve R4-R6 koşularının isabet oranı karşılaştırması; scoring_details içindeki vector_score ve keyword_score alanları

Adım 5 — Rerank ve query rewrite ekle

calistir R7 '{"retrieval":{"retrieval_type":"hybrid","max_num_results":25},
              "reranking":{"enabled":true,"model":"@cf/baai/bge-reranker-base","match_threshold":0.4}}'
calistir R8 '{"retrieval":{"max_num_results":25},"query_rewrite":{"enabled":true}}'
calistir R9 '{"retrieval":{"max_num_results":25,"boost_by":[{"field":"timestamp","direction":"desc"}]}}'

R7-R9 koşularının çıktısı; reranking_score alanı ve query rewrite'ın yeniden yazdığı sorgu metni

Adım 6 — Sonuç tablosunu doldur

cat kosular.jsonl | jq -s 'group_by(.kosu)[] | {
  kosu: .[0].kosu,
  n: length,
  recall1: ((map(select(.ilk1))|length)/length*100|round),
  recall5: ((map(select(.ilk5))|length)/length*100|round),
  p50: (map(.ms)|sort|.[length/2|floor]),
  p95: (map(.ms)|sort|.[length*0.95|floor])
}'

jq ile üretilmiş özet çıktısı; her koşu için recall1, recall5, p50 ve p95 değerleri

Adım 7 — Cache deneyi

# Aynı soru iki kez
curl -sD- -o /dev/null -X POST \
  ".../ai-search/instances/demo-bilgi/chat/completions" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"iade politikası kaç gün"}]}' \
  | grep -i cf-aig-cache-status

# Şimdi PARAFRAZ — dört eşikte
for E in super_strict_match close_enough flexible_friend anything_goes; do
  curl -sD- -o /dev/null ... \
    -d "{\"messages\":[{\"role\":\"user\",\"content\":\"kaç günde iade edebilirim\"}],
         \"ai_search_options\":{\"cache\":{\"enabled\":true,\"cache_threshold\":\"$E\"}}}" \
  | grep -i cf-aig-cache-status
done

Dört eşik için cf-aig-cache-status çıktıları; hangi eşikten sonra parafrazın HIT verdiği görülmeli

Bu, Türkçe için özellikle önemli bir ölçüm: Türkçe’nin eklemeli yapısı yüzünden aynı sorunun yazım varyasyonları İngilizce’dekinden daha fazla. Hangi eşiğin senin trafiğinde doğru olduğunu kendi log’unla ölçmen gerekir.

Bu demoda ölçülenler: her ayar için Recall@1 ve Recall@5 · p50 ve p95 gecikme · ek model çağrısı sayısı ve maliyeti · cache isabet oranı (eşik başına) · HIT ve MISS gecikme farkı · üretim token’ından tasarruf.

Fiyatlandırma

Bugünkü durum: açık betada ücretsiz

“During the open beta, AI Search is free within these limits. [Workers AI] and [AI Gateway] usage is billed separately. Pricing details will be communicated at least 30 days before any billing begins.”

“Storage, vector indexing, and the Browser Run usage that website crawling consumes are included with AI Search. You are not billed separately for them.”

Bu bölünme 18 Haziran 2026’da değişti. Öncesinde depolama, vektör ve crawler kullanımı da kullanıcının kendi hesabından faturalanıyordu.

Pratikte maliyet = Workers AI faturan

AI Search’ün kullandığı modellerin fiyatları:

Workers AI’ın günlük 10.000 Neuron ücretsiz kotası burada da geçerlidir — ayrıntı için Workers AI.

Limitler

Resmî not, ücretsiz planda hangi limitin bağlayıcı olduğunu açıklıyor: “A discover crawl accepts up to 100,000 pages, but the files per instance and maximum pages crawled per day limits also apply… On Workers Free, the daily limit of 500 pages is the binding one.”

Web sitesi kaynağına özgü ek limitler: özel sitemap adresi 5, kimlik doğrulama başlığı 5, içerik seçicisi 10 (her biri en fazla 200 karakter), tarama derinliği varsayılan 5.

Diğer sınırlar: dosya adı 128 karakter · boost_by 3 alan · max_num_results 50 · include_items/exclude_items 10’ar desen · public endpoint varsayılan hız sınırı dakikada 120 istek · senkronizasyon tetikleme aralığı 30 saniye.

Lisanslama ve hukuki çerçeve

Hizmet tescillidir ve Cloudflare Hizmet Şartları’na tabidir.

Beta statüsü sözleşme açısından önemlidir. Ürün 17 aydır açık betadadır, bir genel kullanım duyurusu yoktur ve fiyatlandırma yayımlanmamıştır. Müşterine AI Search üzerine kurulmuş bir arama hizmeti satıyorsan, hizmet seviyesi taahhüdü verirken bunu dikkate al. Fiyatlandırma en az 30 gün önceden duyurulacak ama tutarı bilinmiyor.

KVKK açısından üç nokta.

Birincisi, AI Search içeriğini işlemek için model çağrıları yapar ve bunların hepsi bir AI Gateway üzerinden geçer. Üçüncü taraf model kullanıyorsan (OpenAI, Anthropic, Google) içeriğin o sağlayıcıya gider. Yalnızca Workers AI modellerinde kalırsan işleme Cloudflare içinde kalır ve Workers AI’ın “does not use your Customer Content to train any AI models” taahhüdü geçerli olur.

İkincisi, Smart Default seçeneği modelleri zaman içinde otomatik değiştirir. Hangi modele denk geldiği belgelenmemiştir. Veri işleme envanterinde hangi alt işleyicinin kullanıldığını kayıt altına alman gerekiyorsa Smart Default’u kullanma, açıkça bir model seç.

Üçüncüsü, public endpoint kimlik doğrulaması yoktur — “anyone with the URL can query your indexed content.” Kişisel veri içeren bir korpusu public endpoint ile açmak, o veriyi yayımlamakla eşdeğerdir. Custom domain + Cloudflare Access kurmadan açma, ve mutlaka default_domain_enabled: false yap.

MCP ucu için aynı uyarı geçerlidir. MCP sunucusu public endpoint üzerinden çalışır ve kimlik doğrulaması yoktur.

Sık yapılan hatalar

Bağlı AI Gateway’de cache açık bırakmak. Embedding’ler cache’lenir, yanlış vektörler saklanır, arama kalitesi sessizce bozulur. Cloudflare bunu açıkça uyarıyor.

Bağlı AI Gateway’de rate limit kurmak. Indexleme sırasındaki binlerce embedding çağrısı kesilir.

Embedding modelini sonradan değiştirmeye çalışmak. Mümkün değil; yeni instance gerekir.

Tam yeniden indexleme tetikleyicilerini bilmemek. parse_type, index_method, keyword_tokenizer, custom_metadata şeması, içerik seçicisi veya kimlik doğrulama başlığı değişikliği — her biri tüm korpusu yeniden embed ettirir ve beklenmedik bir Workers AI faturası üretir.

Reranking’in açık olduğunu sanmak. Varsayılan kapalı.

query formatıyla query rewriting beklemek. Rewriting yalnızca messages formatıyla ve yalnızca takip sorularında çalışır.

match_threshold’un füzyon skoruna uygulandığını sanmak. Uygulanmaz — “filters on the vector similarity score, not the fused score returned in the response.”

Boosting ile yeni doküman getirmeye çalışmak. “It cannot surface documents that were not retrieved.” Yalnızca mevcut 50 adayı yeniden sıralar.

public_endpoint_params’ı kısmi güncellemek. Tüm nesne değiştirilir; instances_allowed alanını yazmayı unutursan endpoint sessizce boşalır.

Path filtresini hostname’siz yazmak. Web kaynaklarında filtre tam URL’ye uygulanır: /blog/** eşleşmez, **/blog/** eşleşir. Ayrıca büyük/küçük harf duyarlıdır ve /blog/ ile /blog farklı sayılır.

İçerik seçicisinin hiçbir şeyle eşleşmediğini fark etmemek. Sayfa “indexlendi” görünür ama Markdown boştur ve öğe hataya düşer.

Ücretsiz planda site taramak. Günde 500 sayfa. page_limit_reached alıp içeriğin neden eksik olduğunu anlamamak çok yaygın.

Yerel geliştirmede remote: true koymamak. AI Search’ün yerel emülatörü yok.

Migrasyondan sonra eski R2 bucket’ını silmemek. Kullanılmıyor ama depolama faturana yazılmaya devam ediyor.

Yeni binding’de aiSearch() aramak. O metot yok; yerine chatCompletions() var. Ve yanıt data[] değil chunks[] döner.