AI Gateway és AI Search a gyakorlatban

15b.1AI Gateway: nem proxy, hanem kontrollpont

A 15. modulban „proxynak" neveztem, de ez alulértékeli. Pontosabb: az AI Gateway az a hely, ahol az összes AI-hívásod áthalad — és emiatt az egyetlen pont, ahol egységesen tudsz mérni, korlátozni, cache-elni és védeni. Ha egy multitenant SaaS-ban AI-funkciót adsz ki, három kérdés fog felmerülni az első hónapban: mennyibe kerül tenantonként? mi van, ha valaki visszaél vele? mi van, ha a szolgáltató elesik? — mindháromra ez a válasz.

Egységes API — a szolgáltatófüggetlenség gyakorlata

A Gateway ma egységes REST API-t ad az összes modellhez, szolgáltatótól függetlenül. Négy endpoint-alak közül választhatsz aszerint, hogy melyik SDK-t használod:

curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai/v1/chat/completions" \
  -H "Authorization: Bearer $CF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "model": "openai/gpt-5.5",
        "messages": [{"role":"user","content":"Foglald össze ezt a ticketet…"}] }'

Figyeld meg, mi nincs ebben a hívásban: OpenAI API-kulcs. Két modell közül választhatsz:

• Unified Billing — nem kezelsz szolgáltatói kulcsokat, a harmadik féltől jövő modellek is a Cloudflare-számládon futnak. Egy kulcs (a CF API-token), egy számla, N szolgáltató.
• BYOK (bring your own keys) — marad a saját szolgáltatói szerződésed és kulcsod, a Gateway csak elé ül. Ha meglévő OpenAI-kereted vagy enterprise-szerződésed van, ez az út.

A hat képesség — és mit adnak neked konkrétan

A gyöngyszem: tenant-szintű költségkeret custom metadatával

Ez az a képesség, amiért érdemes végigolvasni ezt a szakaszt. A spend limit szabályai egyéni metaadat-dimenziók szerint is szűkíthetők — vagyis ha minden hívásba beteszed a tenant_id-t metaadatként, akkor tenantonként tudsz napi/havi dollárkeretet szabni, a Gateway szintjén, a te kódod nélkül:

import OpenAI from "openai";

export function aiClient(env, tenantId: string, userId: string) {
  return new OpenAI({
    apiKey: env.CF_API_TOKEN,
    baseURL: `https://api.cloudflare.com/client/v4/accounts/${env.CF_ACCOUNT_ID}/ai`,
    defaultHeaders: {
      // egyéni metaadat: ezek lesznek a spend limit és a logok dimenziói
      "cf-aig-metadata": JSON.stringify({ tenant_id: tenantId, user_id: userId }),
      "cf-aig-gateway-id": "saas-prod",
    },
  });
}

Ezután a dashboardon felveszel néhány szabályt — kódmódosítás nélkül:

15b.2AI Search: mi az, amit elrejt előled?

Ahhoz, hogy értsd, mit spórolsz vele, előbb nézzük meg, mi a teljes RAG-pipeline, amit egyébként neked kellene megépítened és üzemeltetned:

Egy instance = beépített tár + vektorindex + a fenti pipeline. Nem kell hozzá R2-bucket, embedding-modell-választás, chunkolási stratégia vagy külön index-karbantartás. Amit még kapsz:

• Hibrid keresés: vektor- (jelentés) és kulcsszó-alapú találatok kombinálva — ez fontos, mert a tisztán szemantikus keresés a pontos kódokra, cikkszámokra rosszul teljesít.
• Relevancia-boosting: befolyásolhatod a rangsort (pl. frissebb dokumentum előrébb).
• Hasonlósági cache: a hasonló kérdésekre adott válaszok újrahasznosítása — az AI Search saját cache-e.
• Kétféle válasz: nyers találatok (chunkok, forrásmegjelöléssel) vagy generált szöveges válasz.

15b.3A konkrét példa: dokumentum-szeparáció shared-DB SaaS-ban

A helyzeted: közös adatbázis tenant_id oszlopokkal (5b. modul), és most jön egy funkció, hogy a felhasználók feltölthetik a saját dokumentumaikat, és kérdezhetnek belőlük. A kérdés: hogyan szeparálod?

Az architektúra-döntés

A hivatalos — és szerintem is helyes — ajánlás: tenantonként egy instance. Az üzleti adat marad a közös DB-ben, a dokumentumok viszont fizikailag külön indexbe kerülnek. A kettő nem mond ellent egymásnak: a shared DB-d marad, csak a kereshető tartalom szeparálódik.

{
  "ai_search_namespaces": [
    { "binding": "AI_SEARCH", "namespace": "default", "remote": true }
  ]
}

A remote: true itt kötelező a lokális fejlesztéshez (11. modul): az AI Search nem fut lokálisan, a wrangler dev a deployolt instance-okhoz proxyzik.

1) Tenant-onboarding: instance létrehozása

Illeszd be a meglévő onboarding-folyamatodba (7. modul Workflow-jába, ha ott van):

export const tenantIndexId = (tenantId: string) => `tenant-${tenantId}`;

export async function provisionTenantIndex(env, tenantId: string) {
  await env.AI_SEARCH.create({ id: tenantIndexId(tenantId) });
}

export async function deprovisionTenantIndex(env, tenantId: string) {
  await env.AI_SEARCH.delete(tenantIndexId(tenantId));   // GDPR-törléskor: egy hívás
}

2) Feltöltés: a fájl két helyre kerül

export default defineEventHandler(async (event) => {
  const { env } = event.context.cloudflare;
  const { tenantId, userId } = await requireSession(event);   // a saját auth-od
  const form = await readMultipartFormData(event);
  const file = form.find((f) => f.name === "file");

  const docId = crypto.randomUUID();
  const key = `${tenantId}/${docId}/${file.filename}`;

  // (a) az eredeti fájl R2-be — ez marad az igazság (6. modul)
  await env.UPLOADS.put(key, file.data, {
    httpMetadata: { contentType: file.type },
    customMetadata: { tenantId, userId, docId },
  });

  // (b) a kereshető másolat a TENANT SAJÁT indexébe
  const index = env.AI_SEARCH.get(tenantIndexId(tenantId));
  await index.items.uploadAndPoll(`${docId}__${file.filename}`, file.data);

  // (c) a metaadat a közös DB-be — itt él a jogosultság és a listázás
  await env.DB.prepare(
    `INSERT INTO documents (id, tenant_id, owner_user_id, filename, r2_key, visibility)
     VALUES (?, ?, ?, ?, ?, ?)`
  ).bind(docId, tenantId, userId, file.filename, key, "team").run();

  return { ok: true, docId };
});

A hármas felosztás szándékos, és a kurzus korábbi elveit követi: R2 az eredeti fájl (olcsó, nulla egress), AI Search a kereshető index (ez „csak" derivált adat — újraépíthető), D1/Postgres a metaadat és a jogosultság (ez a tranzakcionális igazság, 6. modul hármas felosztása).

3) Keresés: közös tudásbázis + tenant dokumentumai egyetlen hívásban

Itt jön a rész, ami elegánsabb, mint elsőre gondolnád. A namespace-szintű kereséssel több instance-t kérdezhetsz egy hívásban, és minden találat magával hozza, melyik indexből jött:

export default defineEventHandler(async (event) => {
  const { env } = event.context.cloudflare;
  const { tenantId } = await requireSession(event);
  const { question } = await readBody(event);

  const results = await env.AI_SEARCH.search({
    messages: [{ role: "user", content: question }],
    ai_search_options: {
      // a közös termék-dokumentáció ÉS a tenant saját anyagai — egy rangsorban
      instance_ids: ["product-docs", tenantIndexId(tenantId)],
    },
  });

  // forrás szerint csoportosítva adjuk vissza a UI-nak
  return {
    answer: results.response,
    sources: results.data.map((chunk) => ({
      text: chunk.content,
      from: chunk.instance_id === "product-docs" ? "Súgó" : "Saját dokumentumok",
    })),
  };
});

Ez az a pont, ahol a szeparáció szerkezeti, nem fegyelmi kérdés: a lekérdezés csak azokat az indexeket látja, amiket felsorolsz — és a tenant azonosítója a session-ből jön, nem a kliens kéréséből. Egy másik tenant adata nem attól nem jelenik meg, mert jól írtad meg a WHERE-t, hanem mert fizikailag nincs abban az indexben, amit megkérdeztél.

4) Ha a tenanton belül user-szintű szeparáció is kell

Gyakori igény: egy tenanton belül a HR-es dokumentumait ne lássa a fejlesztő. Három szintet érdemes ismerni:

// a találatokból kinyerjük a dokumentum-azonosítót (a fájlnév-prefixből)
const docIds = [...new Set(results.data.map(c => c.filename.split("__")[0]))];

// és a KÖZÖS DB dönt arról, mit láthat ez a user
const allowed = await env.DB.prepare(
  `SELECT id FROM documents
   WHERE tenant_id = ? AND id IN (${docIds.map(() => "?").join(",")})
     AND (visibility = 'team' OR owner_user_id = ?)`
).bind(tenantId, ...docIds, userId).all();

const allowedSet = new Set(allowed.results.map(r => r.id));
const visible = results.data.filter(c => allowedSet.has(c.filename.split("__")[0]));

5) Újraépítés és karbantartás

Mivel az index derivált adat, a helyreállítás egyszerű: az R2-ben ott az összes eredeti fájl, a DB-ben a lista — egy Workflow (7. modul) végigmegy rajtuk és újraindexel. Ezt érdemes megírni még az indulás előtt: ez a te „mi van, ha elromlik az index" válaszod.

15b.4Miért (és miben nem) jobb ez a Postgres full-text search-nél?

Fontos, hogy ezt tisztán lásd, mert a kettő nem ugyanazt a problémát oldja meg, és a „jobb" kérdésre az őszinte válasz: attól függ, mit keresel.

Mit csinál valójában a Postgres FTS?

A tsvector/tsquery lexikai keresés: szótövezés, stopszavak, súlyozás, rangsorolás (ts_rank), GIN-index. Kiváló, ha a felhasználó tudja a szavakat, amiket keres. Amit viszont nem tud: nem érti a jelentést. A „hogyan mondom le az előfizetést" kérdés nem fogja megtalálni a „számlázási ciklus megszüntetése" című szakaszt, mert nincs közös szótő. És nem tud PDF-et olvasni, nem darabol, nem generál választ.

Az összevetés

A verdikt — három szabály

1. Az alkalmazásod saját rekordjaira (számla, ügyfél, ticket cím szerint) maradj a Postgresnél. Ott a tranzakcionális konzisztencia, a joinok és a pontos szűrők számítanak — és az AI Search ezekben gyengébb, nem erősebb.
2. Feltöltött dokumentumokra és természetes nyelvű kérdésekre az AI Search a jobb. Nem azért, mert „AI", hanem mert a teljes pipeline-t (PDF-feldolgozás, chunkolás, embedding, hibrid keresés, rangsorolás) kapod készen — ezt pgvectorral hetekig építenéd, és utána karbantartanád.
3. Multitenant szempontból pedig van egy strukturális érv: a Postgres FTS-nél az izoláció fegyelmi kérdés (minden lekérdezésben ott a WHERE tenant_id), az AI Search-nél szerkezeti (nem is létezik a másik tenant adata abban az indexben). Egy hibás query az egyiknél adatszivárgás, a másiknál üres találatlista.

15b.5Költség és limitek — amit előre tudni kell

• Instance-limit fiókonként. Ha per-tenant instance-okat használsz, ez a szám lesz a felső korlátod a tenantszámra — nézd meg a limitet, és ha kell, kérj emelést. Alternatíva sok kis tenantnál: közös index a kicsiknek (metaadat-szűréssel), külön instance a nagyoknak — ugyanaz a hibrid gondolkodás, mint az 5b. modulban a DB-knél.
• Három költségsor: tárolás, lekérdezés és a mögöttes modellhívások (embedding + generálás). Az indexelés egyszeri, de nagy dokumentumhalmaznál nem elhanyagolható.
• A Gateway spend limitjei ide is védőháló: ha az AI Search modellhívásai a te gatewayeden mennek, ott is látod és korlátozhatod a költséget (a cache/rate limit kikapcsolása mellett — 15b.2).
• Lokális fejlesztés: az AI Search nem fut lokálisan, tehát remote: true kell — és így a dev-környezeted valódi (staging!) instance-t használ. Ügyelj rá, hogy ez ne a production namespace legyen (11. modul figyelmeztetése).

15b.6Ellenőrizd magad