# Les 14 — RAG + Embeddings ## Docenttekst (Klas A — 3 uur, fysiek, demo-driven) **Les:** 15 van 18 **Onderwerp:** RAG (Retrieval-Augmented Generation) — AI laten antwoorden op eigen documenten **Duur:** 180 minuten **Format:** Tim demonstreert klassikaal. Studenten kijken mee. Zelf bouwen = huiswerk. **Demo-app:** PDF Q&A from scratch — nieuwe kleine app --- ## Hoe deze tekst werkt - `[SLIDE X]` — klik naar slide X - `[SCHERM: slides | terminal | editor | browser | supabase]` - **Vertel:** "..." — wat je zegt - `*[stage direction]*` — instructie voor jezelf - 💬 = verwachte studentenvraag --- ## VÓÓR DE LES — Setup (45 min) ### 1. Demo-folder + Supabase - Maak vooraf werkende `pdf-qa` lokaal (backup) - Supabase project: pgvector extension AL geactiveerd - Schema (chunks tabel + match_chunks function) al gedraaid - 1 PDF al klaar om te indexeren: `polderfest-lineup-2027.pdf` (genereer met AI of pak echte) ### 2. Voorbeeld-PDF klaar - Print of genereer een PDF over Polderfest 2027 — ~10-20 pagina's - Liefst: line-up, dagschema's, locatie-info - Studenten kunnen deze ook downloaden - Backup-PDF: Wikipedia-artikel over willekeurig onderwerp als geprinte PDF ### 3. Browser-tabs - `localhost:3000` (dev server) - Supabase dashboard (Table Editor + SQL Editor) - https://ai-sdk.dev/docs/ai-sdk-core/embeddings (referentie) - https://platform.openai.com/usage (cost-monitoring) ### 4. Backup als demo crasht - Werkende eindstaat (alle code) op USB - Console-log met "voorbeeld-embedding" als slide-content - Backup-vraag-en-antwoord screenshots ### 5. Terminals - 3 tabs: dev, watch (`watch curl ...`), supabase SQL via CLI als nodig --- # HET SCRIPT — Lees mee tijdens de les ## BLOK 1 — Welkom + Terugblik (10 min) `[SLIDE 1 — Title]` `[SCHERM: slides]` **Vertel:** "Welkom bij les 15. Vandaag: RAG. Retrieval-Augmented Generation. AI laten antwoorden op basis van jouw eigen documenten." `[SLIDE 2 — Terugblik]` **Vertel:** "Lessen 11-14: AI SDK basics, tool calling, agents, externe APIs en deploy. Nu hebben we een complete stack. Wat we nog niet hadden: AI laten werken met **jouw documenten**. Stel je hebt 200 pagina's productdocumentatie of een dik handboek of een lange whitepaper. Hoe stel je daar vragen aan? Twee naïeve oplossingen. Eén: alles meesturen in context. Werkt voor 5 pagina's, niet voor 500. Te duur. Twee: AI zelf laten zoeken. Werkt voor publieke info, niet voor jouw private data. RAG is de derde oplossing. In één zin: haal de relevante stukjes uit je documenten op, geef die aan AI, AI antwoordt." `[SLIDE 3 — Planning]` **Vertel:** "Drie uur. Eerst vijftig minuten theorie — embeddings, similarity, pipeline, pgvector, chunking. Veel om te begrijpen, maar het loont. Daarna vier demos. Pauze rond minuut 100." --- ## BLOK 2 — Theorie embeddings (20 min) `[SLIDE 4 — Wat is een embedding]` **Vertel:** "Een embedding is een vector. Letterlijk een array van getallen. Voor OpenAI's small model: 1536 getallen tussen min-één en plus-één. Je stopt tekst erin, krijgt vector terug. Maar het magische zit hier — vergelijkbare betekenissen produceren vergelijkbare vectors. `*[Wijs naar slide voorbeeld]*` 'De kat zit op de mat' en 'Een poes ligt op het tapijt' hebben bijna geen woorden gemeen. Maar betekenis is hetzelfde. Hun embeddings staan dichtbij elkaar in de 1536-dimensionale ruimte. 'Voetbal in Nederland' — totaal andere kant op. Dit is fundamenteel anders dan keyword search. Keyword zou de eerste twee zinnen totaal niet matchen — geen woord overlap. Semantic search wel. Welke modellen. OpenAI 3-small en 3-large — de standaarden. Open-source alternatieven zoals nomic-embed-text als je lokaal wilt embedden. Voor vandaag: 3-small. Goedkoop, snel, prima kwaliteit voor de meeste apps." 💬 *Vraag: 'Wat doet zo'n embedding-model eigenlijk?'* **Antwoord:** "Het is een neural network, getraind om de betekenis van tekst te 'condenseren' naar een dichte vector. Vergelijkbaar met de eerste lagen van een GPT-model, maar zonder de generative head. Heel veel context distilleren tot 1536 nummers. Wiskundig: een functie die tekst projecteert in een 'semantic space'." `[SLIDE 5 — Vector similarity]` **Vertel:** "Hoe meet je 'dichtbij'? Drie metrics, één winnaar voor text. Cosine similarity — hoek tussen twee vectors. Van min-één tot plus-één. Plus-één betekent identiek georiënteerd, nul ongerelateerd, min-één tegenovergesteld. Voor genormaliseerde vectors (OpenAI's zijn dat) is cosine effectief dot product. Voor RAG: cosine. Standaard, robuust, simpel. In pgvector schrijf je `<=>` voor cosine distance. Een kleinere afstand = meer similar. Order by `<=>` ascending = top resultaten eerst. Onthoud die operator." --- ## BLOK 3 — Theorie RAG pipeline + pgvector (30 min) `[SLIDE 6 — RAG pipeline]` **Vertel:** "Twee pipelines. Index time en query time. Index time gebeurt eenmalig — wanneer je een document uploadt. PDF binnen, parsen, opknippen in chunks van ongeveer vijfhonderd tokens, elke chunk embedden, alles in Postgres. Query time gebeurt elke vraag. Vraag binnen, embedden — zelfde model als index, dat is belangrijk — similarity search in Postgres, top vijf chunks terug. Die geef je als context aan LLM, LLM antwoordt. Belangrijkste inzicht: LLM ziet nooit de hele DB. Alleen de vijf meest relevante chunks. Schaalbaar tot miljoenen documenten." 💬 *Vraag: 'Waarom moet het embedding-model hetzelfde zijn?'* **Antwoord:** "Embeddings zijn alleen vergelijkbaar binnen hetzelfde model. Model A's vector voor 'kat' staat op een totaal andere plek dan Model B's vector voor 'kat'. Hun coördinatensystemen zijn niet uitwisselbaar. Dus: zelfde model voor index én query — always." `[SLIDE 7 — pgvector]` **Vertel:** "Hoe sla je vectors op? Postgres heeft een extensie: pgvector. Voegt `vector` datatype toe, plus operators voor cosine, euclidean, dot product. In Supabase: één klik in dashboard om te activeren. `*[Toon SQL op slide]*` Schema: chunks tabel met content kolom en embedding kolom. `vector(1536)` — dimensie matcht model. Voor performance: een HNSW index. Hierarchical Navigable Small Worlds. Wiskundige magie waardoor je in miljoenen vectors in milliseconden zoekt. Bij minder dan tienduizend rows kun je het skippen — exacte search is dan al snel." `[SLIDE 8 — Chunking]` **Vertel:** "Hoe knip je een document op. Klinkt simpel — is het niet. Drie strategieën. Fixed size — vijfhonderd tokens per chunk, vijftig tokens overlap. Simpel, default. Recursive — knip eerst op paragrafen, dan zinnen, dan woorden. Behoudt structuur beter. Semantic — embed zinnen, group similar. Beste kwaliteit, duurder. Sweet spot voor chunks: tweehonderd tot vijfhonderd tokens. Te klein, je verliest context. Te groot, irrelevant info verdunt het signaal. Overlap van tien tot vijftien procent zodat info aan chunk-grenzen niet verdwijnt. Vandaag: fixed size, vijfhonderd char chunks, vijftig overlap. Werkt prima voor de meeste docs." --- ## BLOK 4 — Demo 1: pgvector setup (25 min) `[SLIDE 9 — Wat we bouwen]` **Vertel:** "Vandaag bouwen we een PDF Q&A app from scratch. Upload PDF, hij wordt geïndexeerd, je stelt vragen. Klassieke RAG-use-case." `[SLIDE 10 — DEMO 1]` `[SCHERM: terminal + editor]` **Vertel:** "Klas, kijk mee." ```bash cd ~/novi/novi-lessons/Les14-RAG-Embeddings pnpm create next-app@latest pdf-qa \ --typescript --tailwind --app --no-src-dir --import-alias "@/*" cd pdf-qa pnpm add ai @ai-sdk/openai zod @supabase/supabase-js unpdf cursor . ``` `*[Supabase dashboard]*` `[SCHERM: supabase]` **Vertel:** "Eerst pgvector activeren. Database → Extensions → zoek vector → enable. Eén click. Of via SQL:" ```sql create extension if not exists vector; ``` `*[SQL Editor — voer uit:]*` ```sql create table chunks ( id bigserial primary key, source text not null, page int, content text not null, embedding vector(1536), created_at timestamp default now() ); create index on chunks using hnsw (embedding vector_cosine_ops); alter table chunks enable row level security; create policy "demo open" on chunks for all to anon using (true) with check (true); ``` **Vertel:** "Tabel, HNSW index, RLS, open policy. Dezelfde regels als alle eerdere demos." `*[Editor → lib/embeddings.ts]*` ```typescript import { embed, embedMany } from "ai"; import { openai } from "@ai-sdk/openai"; export const embedModel = openai.textEmbeddingModel("text-embedding-3-small"); export async function embedOne(text: string) { const { embedding } = await embed({ model: embedModel, value: text }); return embedding; } export async function embedBatch(texts: string[]) { const { embeddings } = await embedMany({ model: embedModel, values: texts }); return embeddings; } ``` **Vertel:** "Twee functies. embedOne voor één string, embedBatch voor veel tegelijk. Batch is veel sneller — één API-call in plaats van een loop." `*[Voeg chunkText functie toe]*` ```typescript export function chunkText(text: string, size = 500, overlap = 50): string[] { const chunks: string[] = []; let i = 0; while (i < text.length) { chunks.push(text.slice(i, i + size).trim()); i += size - overlap; } return chunks.filter((c) => c.length > 0); } ``` **Vertel:** "Simpelste chunker mogelijk. Slice op chars. Voor productie: gebruik LangChain's RecursiveCharacterTextSplitter — handelt edge cases beter. Voor demo: dit volstaat." `*[Test embed]*` ```typescript // Eenmalig in een test-script of API route const e = await embedOne("De kat zit op de mat"); console.log(e.length, e.slice(0, 5)); // 1536 [0.012, -0.0345, 0.0123, ...] ``` **Vertel:** "Vector van 1536 nummers. Eerste vijf: kleine getallen tussen min-één en plus-één. Dat is alles." --- ## BLOK 5 — Demo 2: Index pipeline (20 min) `[SLIDE 11 — DEMO 2]` `[SCHERM: editor + terminal]` **Vertel:** "Index endpoint. POST een PDF erin, krijg chunk-count terug." `*[app/api/index/route.ts]*` ```typescript import { extractText } from "unpdf"; import { embedBatch, chunkText } from "@/lib/embeddings"; import { supabase } from "@/lib/supabase"; export async function POST(req: Request) { const formData = await req.formData(); const file = formData.get("file") as File; if (!file) return Response.json({ error: "No file" }, { status: 400 }); const buffer = new Uint8Array(await file.arrayBuffer()); const { text } = await extractText(buffer, { mergePages: true }); const chunks = chunkText(text, 500, 50); const embeddings = await embedBatch(chunks); const { error } = await supabase.from("chunks").insert( chunks.map((content, i) => ({ source: file.name, content, embedding: embeddings[i], })) ); if (error) return Response.json({ error: error.message }, { status: 500 }); return Response.json({ chunks: chunks.length, source: file.name }); } ``` **Vertel:** "Vier stappen. Eén: ontvang file via formData. Twee: parse met unpdf. Drie: chunk + embed. Vier: insert alles in Supabase." `*[Terminal:]*` ```bash pnpm dev ``` `*[Tweede terminal:]*` ```bash curl -X POST http://localhost:3000/api/index \ -F "file=@/path/to/polderfest-lineup.pdf" ``` `*[Wacht 5-10s]*` **Vertel:** "Response: chunks: 30. Dertig chunks van onze PDF in de DB." `*[Supabase Table Editor]*` `[SCHERM: supabase]` **Vertel:** "Daar staan ze. Content kolom met tekst. Embedding kolom — clickbaar voor de vector. Source filename. Klaar voor querying." 💬 *Vraag: 'Hoe lang duurt embedding van 1000 chunks?'* **Antwoord:** "Met embedMany batch: enkele seconden voor duizend chunks. OpenAI's API is snel — duizenden tokens per seconde. Voor één PDF van 200 pagina's: misschien 5-10 seconden totaal. Indexing is goedkoop én snel." --- ## BLOK 6 — Pauze (15 min) `[SLIDE 12 — Pauze]` --- ## BLOK 7 — Demo 3: Query pipeline (20 min) `[SLIDE 13 — DEMO 3]` `[SCHERM: editor + terminal + supabase]` **Vertel:** "Nu querying. We schrijven een SQL function voor de similarity search." `*[Supabase SQL Editor:]*` ```sql create or replace function match_chunks( query_embedding vector(1536), match_count int default 5 ) returns table (id bigint, content text, source text, similarity float) language sql stable as $$ select chunks.id, chunks.content, chunks.source, 1 - (chunks.embedding <=> query_embedding) as similarity from chunks order by chunks.embedding <=> query_embedding limit match_count; $$; ``` **Vertel:** "Postgres function neemt vector + count, returnt top N met similarity score. `1 - (a <=> b)` converteert distance terug naar similarity score." `*[app/api/ask/route.ts]*` ```typescript import { embedOne } from "@/lib/embeddings"; import { supabase } from "@/lib/supabase"; import { generateText } from "ai"; import { openai } from "@ai-sdk/openai"; export async function POST(req: Request) { const { question } = await req.json(); const embedding = await embedOne(question); const { data: chunks } = await supabase.rpc("match_chunks", { query_embedding: embedding, match_count: 5, }); if (!chunks?.length) { return Response.json({ answer: "Geen relevante info gevonden." }); } const context = chunks .map((c: any, i: number) => `[Source ${i + 1}: ${c.source}]\n${c.content}`) .join("\n\n---\n\n"); const { text } = await generateText({ model: openai("gpt-4o-mini"), prompt: `Beantwoord de vraag op basis van deze context. Als geen antwoord in de context staat, zeg dat eerlijk. CONTEXT: ${context} VRAAG: ${question} ANTWOORD:`, }); return Response.json({ answer: text, sources: chunks }); } ``` **Vertel:** "Vier stappen. Eén: embed de vraag. Twee: RPC call naar match_chunks — top 5 terug. Drie: bouw context-string met source-labels. Vier: generateText met prompt-template." `*[Terminal:]*` ```bash curl -X POST http://localhost:3000/api/ask \ -H "Content-Type: application/json" \ -d '{"question": "Wie zijn de headliners op Polderfest 2027?"}' \ | jq ``` `*[Wacht 2-3s]*` **Vertel:** "Antwoord: 'De headliners op Polderfest 2027 zijn... blah blah, gebaseerd op de line-up uit het document.' Plus: sources. Welke chunks waren de top vijf. Similarity scores. Volledig traceerbaar." `*[Tweede vraag voor demo:]*` ```bash curl -X POST http://localhost:3000/api/ask \ -H "Content-Type: application/json" \ -d '{"question": "Op welk podium spelen de jazz acts?"}' \ | jq ``` **Vertel:** "Andere vraag, andere chunks opgehaald, ander antwoord. Werkt." 💬 *Vraag: 'Wat als vraag niet in document staat?'* **Antwoord:** "Twee dingen. Eén: similarity scores zijn laag — top vijf is alsnog niet relevant. Twee: LLM merkt dat context het niet bevat, en zegt 'staat niet in document'. Dat tweede dwingen we af met de prompt: 'Als geen antwoord in context staat, zeg dat eerlijk.' Anders zou-ie kunnen hallucineren." --- ## BLOK 8 — Demo 4: RAG-tool in agent (15 min) `[SLIDE 14 — DEMO 4]` `[SCHERM: editor]` **Vertel:** "Laatste demo. Combineer Les 13 met Les 14. Een RAG-tool in een ToolLoopAgent." `*[lib/agent.ts]*` ```typescript import { ToolLoopAgent, tool, stepCountIs } from "ai"; import { openai } from "@ai-sdk/openai"; import { embedOne } from "./embeddings"; import { supabase } from "./supabase"; import { z } from "zod"; const ragSearch = tool({ description: "Zoek in geüploade documenten op basis van semantic similarity. " + "Gebruik voor inhoudelijke vragen over de documenten.", inputSchema: z.object({ query: z.string().describe("Wat je wilt vinden"), }), execute: async ({ query }) => { const embedding = await embedOne(query); const { data } = await supabase.rpc("match_chunks", { query_embedding: embedding, match_count: 5, }); return data; }, }); export const docAgent = new ToolLoopAgent({ model: openai("gpt-4o-mini"), system: `Je beantwoordt vragen over geüploade documenten. Werkwijze: 1. Zoek met ragSearch voor relevante info 2. Lees de chunks 3. Eventueel: tweede ragSearch met andere query voor meer context 4. Antwoord met bronvermeldingen. Verzin niets - alleen wat in de chunks staat.`, tools: { ragSearch }, stopWhen: stepCountIs(10), }); ``` **Vertel:** "Agent met één tool: ragSearch. System prompt vertelt hem multi-step te werken — zoek, lees, evalueer of nog een query nodig is. Het voordeel boven simple RAG: voor complexe vragen kan agent meerdere searches doen. 'Vergelijk de jazz- en rock-headliners' — agent doet twee searches, één voor jazz, één voor rock, dan vergelijkt." `*[Quick test in script of route:]*` ```typescript const result = await docAgent.generate({ prompt: "Vergelijk de jazz- en rock-headliners op Polderfest 2027.", }); console.log(result.text); console.log("Steps:", result.steps.length); ``` `*[Run]*` **Vertel:** "Antwoord: vergelijking van beide. Steps: drie of vier — twee searches, dan reasoning, dan finale text. Agent doet zijn werk." 💬 *Vraag: 'Wanneer agent vs simple RAG?'* **Antwoord:** "Simple RAG voor single-shot vragen. 'Wie is X?' → één search → antwoord. Agent voor vragen die multiple lookups vereisen. Vergelijkingen, multi-hop, of als gebruiker breed vraagt en je wilt dat AI verfijnt. Trade-off: agent kost 3-5x meer en duurt langer. Begin met simple, upgrade als nodig." --- ## BLOK 9 — Wanneer RAG (10 min) `[SLIDE 15 — Wanneer wel/niet]` **Vertel:** "Niet alles is RAG. Wanneer wel: veel documenten, ze veranderen, semantic search nodig, privacy belangrijk, bronvermelding gewenst. Wanneer niet: klein document — stop in prompt. Exacte data — gebruik tool-calls of SQL. Structured data — SQL is beter dan vector search. Code-base — gebruik grep en tree-sitter. In productie zie je vaak hybrid. Semantic search voor concept-vragen, keyword search voor exacte termen, metadata filter voor structured criteria. Drie technieken in één query. En: re-ranking. Top-twintig ophalen via vector, dan re-rank met Cohere of LLM-as-judge naar top-vijf. Twintig procent betere kwaliteit. Voor productie: doen. Voor demo: skip." --- ## BLOK 10 — Lesopdracht + Huiswerk (10 min) `[SLIDE 16 — Lesopdracht + Huiswerk]` **Vertel:** "Lesopdracht: zelfde app als ik liet zien. Half uur. PDF Q&A, pgvector, index, ask. Voorbeeld-PDF deel ik in de groep. Huiswerk: drie dingen. Eén: echte PDF van minimaal twintig pagina's, eigen interesse. UI met file upload + chat-interface. Twee: RAG-tool in een ToolLoopAgent. UI laat tool-invocations zien zoals Les 12. Drie: RAG.md schrijven. Document-info, vijf werkende vragen met sources, één fail-case waar RAG het verkeerd had, één chunking-experiment, één observatie. Bonus: hybrid search, streaming met citations, re-ranking, multi-document. Tien punten, voldoende zes." --- ## BLOK 11 — Afsluiting (5 min) `[SLIDE 17 — Afsluiting]` **Vertel:** "Wat hebben we vandaag gedaan. Embeddings als vectors. Cosine similarity. RAG pipeline — index + query. pgvector. Chunking. RAG-tool in een agent. Wanneer wel/niet RAG. Volgende les: Multimodal. Voice, vision, image generation. Whisper voor transcriptie. GPT-4o voor foto-analyse. Flux of DALL-E voor afbeeldingen genereren in je app. Heel visueel. Daarna: les 17 over MCP — Model Context Protocol — eigen MCP server bouwen. Les 18: browser automation en Computer Use. Spannende lessen om mee af te sluiten. Vragen?" `*[Vragenronde — minstens 5 min over laten]*` --- ## NA DE LES — Wrap-up - Push working `pdf-qa` repo naar GitHub als referentie - Deel voorbeeld-PDF voor lesopdracht in Brightspace - Brightspace: huiswerk-instructies + repo URL - Voor Klas B: check of zelfde stack werkt (Supabase free tier limiet pgvector?) --- ## Veelvoorkomende fouten tijdens live coding | Fout | Oplossing | |------|-----------| | `extension "vector" does not exist` | Supabase: enable in dashboard | | Embedding dimension mismatch | Check `vector(1536)` matcht `text-embedding-3-small` | | `match_chunks function not found` | SQL function niet aangemaakt — kopieer uit slide | | RLS error op insert | Open policy nog niet uitgevoerd | | `unpdf` geen text uit PDF | Image-based PDF (scan) — gebruik OCR of andere PDF | | HNSW index trager dan exact | Voor <10k rows: skip index of `set hnsw.ef_search = 100` | | Antwoord is generic, mist details | Top-k te laag of chunks te klein — experimenteer | | Hallucination | Strengere prompt: "Als info ontbreekt, zeg dat" | --- ## Mentale model voor de klas Als studenten verward zijn over wat embeddings doen: > Een embedding is een **adres** in de betekenis-ruimte. Twee adressen dichtbij elkaar = twee zinnen met vergelijkbare betekenis. RAG werkt door: vertaal vraag naar adres, vind alle adressen in de buurt, lees wat daar woont, geef dat aan AI. En RAG vs Agent: > RAG = bibliotheek met index. Eén vraag, één bezoek, top-vijf boeken, antwoord. > RAG-in-Agent = bibliothecaris die voor jou zoekt. Stelt eerst sub-vragen, doet meerdere zoekrondes, vergelijkt, antwoordt.