Files
masi bf2f59e292 chore: publish 4ae9c5f
Built from main 4ae9c5ffef
Merge branch 'refactor/task-21-batch1-corrections'
2026-11-06 14:10:25 -03:00

50 lines
53 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>AI For Dummies — RAG</title><meta name="description" content="Retrieval-augmented generation (RAG) gives a model a small, attributable working set of current knowledge. It is not a magic database: quality comes from the source, retrieval, evaluation, and the decision to say not found."><link rel="canonical" href="https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/rag/"><link rel="icon" type="image/svg+xml" href="/ai-for-dummies/favicon.svg"><link rel="stylesheet" href="/ai-for-dummies/_astro/tokens.BxNFvepo.css"><link rel="stylesheet" href="/ai-for-dummies/fonts/fonts.css"><link rel="stylesheet" href="/ai-for-dummies/_astro/base.u_-OWNC4.css"><link rel="stylesheet" href="/ai-for-dummies/_astro/chapters.DVZ6ptlR.css"><link rel="stylesheet" href="/ai-for-dummies/_astro/motion.CtPv1C_R.css"><link rel="stylesheet" href="/ai-for-dummies/_astro/rag@_@astro.DHmsPqE7.css">
<link rel="stylesheet" href="/ai-for-dummies/_astro/ChapterLayout.BpAlYsUl.css">
<link rel="stylesheet" href="/ai-for-dummies/_astro/ChapterHero.Bf5I54SK.css">
<link rel="stylesheet" href="/ai-for-dummies/_astro/FilmPlayer.B1nrpPmm.css">
<link rel="stylesheet" href="/ai-for-dummies/_astro/require-field.D8D5Or_Q.css"><script type="module" src="/ai-for-dummies/_astro/page.DGRhADao.js"></script></head> <body> <header class="top" id="top" data-astro-cid-xattfbdu> <div class="cell" data-astro-cid-xattfbdu><a href="/ai-for-dummies/rules/" data-astro-cid-ogwjzfbi>← rules</a></div> <div class="cell" data-astro-cid-xattfbdu><span data-astro-cid-ogwjzfbi>05 / RAG</span></div> <div class="cell" data-astro-cid-xattfbdu><div class="lang-switch" aria-label="Language" data-language-toggle> <button class="active" data-lang="en" aria-pressed="true">EN</button> <span>/</span> <button data-lang="pt" aria-pressed="false">PT</button> </div> <script type="module">function o(t){const n=t.querySelectorAll("[data-lang]");function l(e){document.documentElement.lang=e==="pt"?"pt-BR":"en",n.forEach(a=>{const u=a.dataset.lang===e;a.classList.toggle("active",u),a.setAttribute("aria-pressed",String(u))}),document.querySelectorAll("[data-language-content]").forEach(a=>{a.hidden=a.dataset.languageContent!==e}),window.dispatchEvent(new CustomEvent("ai-for-dummies:languagechange",{detail:{language:e}}))}function g(e){return e==="pt"?"pt":"en"}n.forEach(e=>{e.addEventListener("click",()=>{const a=g(e.dataset.lang);l(a);try{localStorage.setItem("ai-for-dummies-language",a)}catch{}})});let c="en";try{c=localStorage.getItem("ai-for-dummies-language")||"en"}catch{}l(g(c))}document.querySelectorAll("[data-language-toggle]").forEach(t=>{"requestIdleCallback"in window?window.requestIdleCallback(()=>o(t)):setTimeout(()=>o(t),0)});</script></div> </header> <main> <section class="hero rise-in has-aside" data-astro-cid-7xzskqga> <div class="hero-copy" data-astro-cid-7xzskqga> <div data-language-content="en" data-astro-cid-7xzskqga><p data-astro-cid-4yr5atew="true" class="eyebrow tone-red">05 / Grounded knowledge</p> </div> <div data-language-content="pt" hidden data-astro-cid-7xzskqga><p data-astro-cid-4yr5atew="true" class="eyebrow tone-red">05 / Conhecimento fundamentado</p> </div> <h1 class="parallax-near" data-astro-cid-7xzskqga><span data-language-content="en" data-astro-cid-ogwjzfbi>Retrieve first.<br><em>Then reason.</em></span><span data-language-content="pt" hidden data-astro-cid-ogwjzfbi>Recupere primeiro.<br><em>Depois raciocine.</em></span></h1> <div class="intro parallax-far" data-astro-cid-7xzskqga> <p data-language-content="en" data-astro-cid-ogwjzfbi>Retrieval-augmented generation (RAG) gives a model a small, attributable working set of current knowledge. It is not a magic database: quality comes from the source, retrieval, evaluation, and the decision to say <code>not found</code>.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi>A geração aumentada por recuperação (RAG) dá ao modelo um pequeno conjunto de conhecimento atual e atribuível. Não é um banco de dados mágico: a qualidade vem da fonte, da recuperação, da avaliação e da decisão de dizer <code>não encontrado</code>.</p> </div> </div> <div class="hero-aside rise-in-late" data-astro-cid-7xzskqga> <figure class="film film-hero" data-film data-paused="true" data-astro-cid-5bv36nto> <div class="frame" data-astro-cid-5bv36nto> <video data-language-content="en" src="/ai-for-dummies/videos/rag-en.mp4" poster="/ai-for-dummies/videos/rag-en.jpg" width="1280" height="720" muted loop playsinline preload="none" aria-label="05 / RAG. Your files, split into labelled chunks. A question is scored against every chunk. Keep only the few that match. Answer from them, and cite the source. No good match? Say so. Retrieve first. Then reason." data-astro-cid-5bv36nto></video><video data-language-content="pt" hidden src="/ai-for-dummies/videos/rag-pt.mp4" poster="/ai-for-dummies/videos/rag-pt.jpg" width="1280" height="720" muted loop playsinline preload="none" aria-label="05 / RAG. Seus arquivos, divididos em trechos rotulados. A pergunta é comparada com cada trecho. Fique só com os poucos que combinam. Responda com eles e cite a fonte. Nada combina? Diga isso. Recupere primeiro. Depois raciocine." data-astro-cid-5bv36nto></video> <button class="toggle" type="button" data-film-toggle aria-pressed="false" data-astro-cid-5bv36nto> <svg class="icon-play" viewBox="0 0 16 16" aria-hidden="true" data-astro-cid-5bv36nto><path d="M4 2.5v11l9-5.5z" fill="currentColor" data-astro-cid-5bv36nto></path></svg> <svg class="icon-pause" viewBox="0 0 16 16" aria-hidden="true" data-astro-cid-5bv36nto><path d="M3.5 2.5h3v11h-3zm6 0h3v11h-3z" fill="currentColor" data-astro-cid-5bv36nto></path></svg> <span class="sr-only" data-language-content="en" data-astro-cid-5bv36nto> <span class="when-paused" data-astro-cid-5bv36nto>Play film</span> <span class="when-playing" data-astro-cid-5bv36nto>Pause film</span> </span><span class="sr-only" data-language-content="pt" hidden data-astro-cid-5bv36nto> <span class="when-paused" data-astro-cid-5bv36nto>Reproduzir filme</span> <span class="when-playing" data-astro-cid-5bv36nto>Pausar filme</span> </span> </button> <span class="progress" aria-hidden="true" data-astro-cid-5bv36nto><span data-film-progress data-astro-cid-5bv36nto></span></span> </div> <figcaption data-astro-cid-5bv36nto> <span class="meta" data-language-content="en" data-astro-cid-5bv36nto> Film · 26 s · silent, captioned </span><span class="meta" data-language-content="pt" hidden data-astro-cid-5bv36nto> Filme · 26 s · sem som, com legendas </span> <details data-astro-cid-5bv36nto> <summary data-astro-cid-5bv36nto> <span data-language-content="en" data-astro-cid-5bv36nto> Transcript </span><span data-language-content="pt" hidden data-astro-cid-5bv36nto> Transcrição </span> </summary> <ol data-language-content="en" data-astro-cid-5bv36nto> <li data-astro-cid-5bv36nto>Your files, split into labelled chunks.</li><li data-astro-cid-5bv36nto>A question is scored against every chunk.</li><li data-astro-cid-5bv36nto>Keep only the few that match.</li><li data-astro-cid-5bv36nto>Answer from them, and cite the source.</li><li data-astro-cid-5bv36nto>No good match? Say so.</li><li data-astro-cid-5bv36nto>Retrieve first. Then reason.</li> </ol><ol data-language-content="pt" hidden data-astro-cid-5bv36nto> <li data-astro-cid-5bv36nto>Seus arquivos, divididos em trechos rotulados.</li><li data-astro-cid-5bv36nto>A pergunta é comparada com cada trecho.</li><li data-astro-cid-5bv36nto>Fique só com os poucos que combinam.</li><li data-astro-cid-5bv36nto>Responda com eles e cite a fonte.</li><li data-astro-cid-5bv36nto>Nada combina? Diga isso.</li><li data-astro-cid-5bv36nto>Recupere primeiro. Depois raciocine.</li> </ol> </details> </figcaption> </figure> <script type="module">const o=()=>window.matchMedia("(prefers-reduced-motion: reduce)").matches;function l(e){return e.videos.find(t=>!t.hidden)}function a(e){const t=e.videos.some(s=>!s.paused);e.root.dataset.paused=String(!t),e.button.setAttribute("aria-pressed",String(t))}function u(e){e.videos.forEach(s=>{s.hidden&&s.pause()});const t=l(e);t&&(t.preload="auto",t.play().catch(()=>a(e)))}function c(e){e.videos.forEach(t=>t.pause())}function d(e){e.inView&&!e.userPaused&&!o()?u(e):c(e)}function f(){const e=[];if(document.querySelectorAll("[data-film]").forEach(t=>{if(t.dataset.filmWired)return;t.dataset.filmWired="true";const s=t.querySelector("[data-film-toggle]");if(!s)return;const n={root:t,videos:[...t.querySelectorAll("video")],bar:t.querySelector("[data-film-progress]"),button:s,inView:!1,userPaused:o()};n.videos.forEach(r=>{r.addEventListener("play",()=>a(n)),r.addEventListener("pause",()=>a(n)),r.addEventListener("timeupdate",()=>{!n.bar||!r.duration||(n.bar.style.transform=`scaleX(${r.currentTime/r.duration})`)})}),s.addEventListener("click",()=>{const r=n.videos.some(i=>!i.paused);n.userPaused=r,r?c(n):u(n)}),e.push(n)}),!!e.length){if("IntersectionObserver"in window){const t=new IntersectionObserver(s=>{s.forEach(n=>{const r=e.find(i=>i.root===n.target);r&&(r.inView=n.isIntersecting,d(r))})},{threshold:.4});e.forEach(s=>t.observe(s.root))}window.addEventListener("ai-for-dummies:languagechange",()=>e.forEach(d))}}f();</script> </div> </section> <section class="practice reveal" data-astro-cid-ogwjzfbi> <div class="depth-slow" data-astro-cid-ogwjzfbi> <p class="eyebrow" data-language-content="en">01 / the foundation</p> <p class="eyebrow" data-language-content="pt" hidden>01 / os fundamentos</p> <h2 data-language-content="en" data-astro-cid-ogwjzfbi>A model has a<br><em>library card.</em></h2> <h2 data-language-content="pt" hidden data-astro-cid-ogwjzfbi>Um modelo tem uma<br><em>ficha de biblioteca.</em></h2> <p data-language-content="en" data-astro-cid-ogwjzfbi>RAG supplies fresh, verifiable evidence at inference time, then constrains the model to reason strictly from that context. Use it when facts evolve rapidly, provenance and citations matter, or private knowledge belongs to your organization—not when a static behavioral rule fits directly in prompt context.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi>RAG fornece evidências atuais e verificáveis no momento da inferência, restringindo o modelo a raciocinar estritamente a partir desse contexto. Use-o quando fatos evoluem rápido, proveniência e citações importam ou o conhecimento pertence à organização—não quando uma regra estável cabe diretamente no contexto do prompt.</p> <svg class="draw-line" viewBox="0 0 4 110" aria-hidden="true" focusable="false" style="--draw-height: 110px" data-astro-cid-n6ozym62> <path d="M 0.5 0 V 110" pathLength="100" data-astro-cid-n6ozym62></path> </svg> </div> <ol class="flow depth-fast" data-astro-cid-ld3fmquo> <li data-astro-cid-ld3fmquo> <article data-astro-cid-ld3fmquo> <b data-astro-cid-ld3fmquo>01</b> <div data-astro-cid-ld3fmquo> <strong data-language-content="en" data-astro-cid-ld3fmquo>Ingest</strong> <strong data-language-content="pt" hidden data-astro-cid-ld3fmquo>Ingerir</strong> <span data-language-content="en" data-astro-cid-ld3fmquo>Parse trusted documents, isolate headings and code fences, and attach source, tenant, ACL, and version metadata.</span> <span data-language-content="pt" hidden data-astro-cid-ld3fmquo>Analise documentos confiáveis, isole cabeçalhos e blocos de código e anexe metadados de fonte, tenant, ACL e versão.</span> </div> </article> </li><li data-astro-cid-ld3fmquo> <article data-astro-cid-ld3fmquo> <b data-astro-cid-ld3fmquo>02</b> <div data-astro-cid-ld3fmquo> <strong data-language-content="en" data-astro-cid-ld3fmquo>Retrieve</strong> <strong data-language-content="pt" hidden data-astro-cid-ld3fmquo>Recuperar</strong> <span data-language-content="en" data-astro-cid-ld3fmquo>Execute filtered lexical or vector search to select a tight candidate set (3 to 8 chunks) before generation begins.</span> <span data-language-content="pt" hidden data-astro-cid-ld3fmquo>Execute busca lexical ou vetorial filtrada para selecionar um conjunto compacto de candidatos (3 a 8 trechos) antes da geração.</span> </div> </article> </li><li data-astro-cid-ld3fmquo> <article data-astro-cid-ld3fmquo> <b data-astro-cid-ld3fmquo>03</b> <div data-astro-cid-ld3fmquo> <strong data-language-content="en" data-astro-cid-ld3fmquo>Ground</strong> <strong data-language-content="pt" hidden data-astro-cid-ld3fmquo>Fundamentar</strong> <span data-language-content="en" data-astro-cid-ld3fmquo>Synthesize the answer strictly with attributable citations, or abstain explicitly when evidence is missing or ambiguous.</span> <span data-language-content="pt" hidden data-astro-cid-ld3fmquo>Sintetize a resposta estritamente com citações rastreáveis ou abstenha-se explicitamente quando a evidência for insuficiente.</span> </div> </article> </li> </ol> </section> <section class="rag-architectures reveal" data-astro-cid-ogwjzfbi> <div class="section-head" data-astro-cid-ogwjzfbi> <p class="eyebrow" data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>02 / ARCHITECTURES</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi>02 / ARQUITETURAS</span> </p> <h2 data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>From local files<br data-astro-cid-ogwjzfbi><em data-astro-cid-ogwjzfbi>to hybrid search.</em></span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi>De arquivos locais<br data-astro-cid-ogwjzfbi><em data-astro-cid-ogwjzfbi>à busca híbrida.</em></span> </h2> <p class="section-desc" data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>Choose the simplest architecture that satisfies your provenance, latency, and update
requirements. Measure lexical search before paying for vector infrastructure.</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi>Escolha a arquitetura mais simples que atenda seus requisitos de proveniência, latência e
atualização. Meça busca lexical antes de pagar por infraestrutura vetorial.</span> </p> </div> <div class="rag-grid" data-astro-cid-ogwjzfbi> <article class="card" data-astro-cid-ogwjzfbi> <b data-language-content="en" data-astro-cid-ogwjzfbi>01 / files-only</b> <b data-language-content="pt" hidden data-astro-cid-ogwjzfbi> 01 / arquivos locais </b> <h3 data-language-content="en" data-astro-cid-ogwjzfbi>The folder is the index</h3> <h3 data-language-content="pt" hidden data-astro-cid-ogwjzfbi> A pasta é o índice </h3> <p data-language-content="en" data-astro-cid-ogwjzfbi>For private team notes and small repositories, parse local Markdown, preserve heading breadcrumbs, and rank chunks directly into prompt context. Zero infrastructure, instant local reproduction, and every input is fully inspectable in Git.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Para notas privadas de equipe e pequenos repositórios, processe Markdown local, preserve trilhas de cabeçalho e insira trechos diretamente no prompt. Zero infraestrutura, reprodução local instantânea e cada entrada é inspecionável no Git. </p> </article><article class="card" data-astro-cid-ogwjzfbi> <b data-language-content="en" data-astro-cid-ogwjzfbi>02 / lexical &amp; bm25</b> <b data-language-content="pt" hidden data-astro-cid-ogwjzfbi> 02 / busca lexical &amp; bm25 </b> <h3 data-language-content="en" data-astro-cid-ogwjzfbi>Search exact words first</h3> <h3 data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Busque palavras exatas primeiro </h3> <p data-language-content="en" data-astro-cid-ogwjzfbi>SQLite FTS5, Postgres full-text search, and BM25 score literal token matches. They excel at error codes, function names, SKU numbers, and newly coined jargon where vector models blur or hallucinate. Sub-millisecond, explainable, and zero embedding API cost.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi> SQLite FTS5, busca de texto completo no Postgres e BM25 pontuam termos literais. Destacam-se em códigos de erro, nomes de funções, SKUs e jargões novos nos quais modelos vetoriais borram ou alucinam. Submilissegundo, explicável e com custo zero de API. </p> </article><article class="card" data-astro-cid-ogwjzfbi> <b data-language-content="en" data-astro-cid-ogwjzfbi>03 / dense vectors</b> <b data-language-content="pt" hidden data-astro-cid-ogwjzfbi> 03 / vetores densos </b> <h3 data-language-content="en" data-astro-cid-ogwjzfbi>Search for semantic meaning</h3> <h3 data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Busque pelo significado semântico </h3> <p data-language-content="en" data-astro-cid-ogwjzfbi>Embedding models project queries and passages into continuous vector spaces. pgvector, Qdrant, or Chroma retrieve conceptual matches across synonyms and paraphrases. Requires pinning model versions and dimensions directly to the index lifecycle.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Modelos de embedding projetam consultas e trechos em espaços vetoriais contínuos. pgvector, Qdrant ou Chroma recuperam correspondências conceituais entre sinônimos e paráfrases. Exige vincular versões e dimensões do modelo ao ciclo de vida do índice. </p> </article><article class="card" data-astro-cid-ogwjzfbi> <b data-language-content="en" data-astro-cid-ogwjzfbi>04 / hybrid &amp; rerank</b> <b data-language-content="pt" hidden data-astro-cid-ogwjzfbi> 04 / híbrido &amp; rerank </b> <h3 data-language-content="en" data-astro-cid-ogwjzfbi>Let two searchers cover each other</h3> <h3 data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Deixe dois buscadores se cobrirem </h3> <p data-language-content="en" data-astro-cid-ogwjzfbi>Run lexical and dense retrieval in parallel, merge candidate lists with Reciprocal Rank Fusion (RRF), and score top candidates with a Cross-Encoder reranker. Delivers high recall for conceptual intent without sacrificing exact keyword precision.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Execute busca lexical e densa em paralelo, mescle candidatos com Reciprocal Rank Fusion (RRF) e pontue os melhores itens com um reranker Cross-Encoder. Oferece alto recall para intenções conceituais sem perder a precisão de termos literais. </p> </article> </div> </section> <section class="pipeline reveal" data-astro-cid-ogwjzfbi> <div class="depth-slow" data-astro-cid-ogwjzfbi> <p class="eyebrow" data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>03 / INSPECT THE PIPELINE</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi>03 / INSPECIONE O PIPELINE</span> </p> <h2 data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>From source<br data-astro-cid-ogwjzfbi><em data-astro-cid-ogwjzfbi>to answer.</em></span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi>Da fonte<br data-astro-cid-ogwjzfbi><em data-astro-cid-ogwjzfbi>à resposta.</em></span> </h2> <p class="section-note" data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>Select a stage to inspect the actual code, SQL schema, queries, and invariants an agent
needs to operate each layer without hand-waving.</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi>Selecione um estágio para inspecionar o código real, schema SQL, consultas e invariantes
que um agente precisa para operar cada camada sem improvisar.</span> </p> <svg class="draw-line" viewBox="0 0 140 140" aria-hidden="true" focusable="false" style="--draw-height: 140px" data-astro-cid-n6ozym62> <path d="M 0.5 0 V 109.5 Q 0.5 139.5 31 139.5 H 140" pathLength="100" data-astro-cid-n6ozym62></path> </svg> </div> <div class="depth-fast" data-astro-cid-ogwjzfbi><div class="rag-workbench" data-rag-workbench data-astro-cid-v2bujt2i> <div class="rag-tabs" role="tablist" aria-label="RAG learning stages" data-astro-cid-v2bujt2i> <p data-astro-cid-v2bujt2i>RAG / BUILD LAB</p> <button type="button" role="tab" aria-selected="true" aria-controls="rag-panel-files" data-rag-tab="files" data-astro-cid-v2bujt2i> <span data-astro-cid-v2bujt2i>01 / FILES</span> <small data-astro-cid-v2bujt2i>The smallest useful RAG is a folder</small> </button><button type="button" role="tab" aria-selected="false" aria-controls="rag-panel-database" data-rag-tab="database" data-astro-cid-v2bujt2i> <span data-astro-cid-v2bujt2i>02 / DATABASE</span> <small data-astro-cid-v2bujt2i>Give every chunk an address</small> </button><button type="button" role="tab" aria-selected="false" aria-controls="rag-panel-lexical" data-rag-tab="lexical" data-astro-cid-v2bujt2i> <span data-astro-cid-v2bujt2i>03 / LEXICAL</span> <small data-astro-cid-v2bujt2i>Search exact words first</small> </button><button type="button" role="tab" aria-selected="false" aria-controls="rag-panel-vector" data-rag-tab="vector" data-astro-cid-v2bujt2i> <span data-astro-cid-v2bujt2i>04 / VECTOR</span> <small data-astro-cid-v2bujt2i>Search for meaning</small> </button><button type="button" role="tab" aria-selected="false" aria-controls="rag-panel-hybrid" data-rag-tab="hybrid" data-astro-cid-v2bujt2i> <span data-astro-cid-v2bujt2i>05 / HYBRID</span> <small data-astro-cid-v2bujt2i>Let two searchers cover each other</small> </button><button type="button" role="tab" aria-selected="false" aria-controls="rag-panel-evaluate" data-rag-tab="evaluate" data-astro-cid-v2bujt2i> <span data-astro-cid-v2bujt2i>06 / EVALUATE</span> <small data-astro-cid-v2bujt2i>Make retrieval prove its claim</small> </button><button type="button" role="tab" aria-selected="false" aria-controls="rag-panel-production" data-rag-tab="production" data-astro-cid-v2bujt2i> <span data-astro-cid-v2bujt2i>07 / PRODUCTION</span> <small data-astro-cid-v2bujt2i>Operate the whole chain</small> </button> </div> <article class="rag-preview" id="rag-panel-files" role="tabpanel" aria-live="polite" data-astro-cid-v2bujt2i> <span data-astro-cid-v2bujt2i>01 / FILES</span> <h3 data-astro-cid-v2bujt2i>The smallest useful RAG is a folder</h3> <p data-astro-cid-v2bujt2i>Put a few trusted Markdown or text files beside a tiny script. Read them, split them into labelled chunks, and pass the best chunks into the model. This is ideal for a prototype because every input is inspectable in Git and there is no service to operate.</p> <pre data-astro-cid-v2bujt2i><code data-astro-cid-v2bujt2i><span class="syn-tree">rag-demo/</span>
<span class="syn-punct">├── </span>docs/handbook.md
<span class="syn-punct">├── </span>eval/questions.jsonl
<span class="syn-punct">└── </span>src/
<span class="syn-punct"> ├── </span><span class="syn-fn">chunk.ts</span>
<span class="syn-punct"> └── </span><span class="syn-fn">ask.ts</span>
<span class="syn-kw">pnpm</span> <span class="syn-fn">tsx</span> src/ask.ts <span class="syn-str">"How many days of leave?"</span></code></pre> <div class="preview-actions" data-astro-cid-v2bujt2i> <button class="copy-command" type="button" data-astro-cid-v2bujt2i>Copy example</button> </div> <div class="takeaway" data-astro-cid-v2bujt2i> <strong data-astro-cid-v2bujt2i>ENGINEERING INVARIANT</strong> <span data-astro-cid-v2bujt2i>Use files when the corpus is small, private, and changed by deploys—not when you need concurrent ingestion or user-level permissions.</span> </div> </article> </div> <script type="application/json" data-rag-panels>[{"id":"files","label":"01 / FILES","title":"The smallest useful RAG is a folder","body":"Put a few trusted Markdown or text files beside a tiny script. Read them, split them into labelled chunks, and pass the best chunks into the model. This is ideal for a prototype because every input is inspectable in Git and there is no service to operate.","code":"rag-demo/\n├── docs/handbook.md\n├── eval/questions.jsonl\n└── src/\n ├── chunk.ts\n └── ask.ts\n\npnpm tsx src/ask.ts \"How many days of leave?\"","highlighted":"<span class=\"syn-tree\">rag-demo/</span>\n<span class=\"syn-punct\">├── </span>docs/handbook.md\n<span class=\"syn-punct\">├── </span>eval/questions.jsonl\n<span class=\"syn-punct\">└── </span>src/\n<span class=\"syn-punct\"> ├── </span><span class=\"syn-fn\">chunk.ts</span>\n<span class=\"syn-punct\"> └── </span><span class=\"syn-fn\">ask.ts</span>\n\n<span class=\"syn-kw\">pnpm</span> <span class=\"syn-fn\">tsx</span> src/ask.ts <span class=\"syn-str\">\"How many days of leave?\"</span>","takeaway":"Use files when the corpus is small, private, and changed by deploys—not when you need concurrent ingestion or user-level permissions."},{"id":"database","label":"02 / DATABASE","title":"Give every chunk an address","body":"A database turns a pile of text into records you can update and inspect. Store the chunk, source, heading, version, tenant, and access policy together. An idempotent upsert lets an agent re-run ingestion without duplicating knowledge.","code":"CREATE TABLE chunks (\n id TEXT PRIMARY KEY,\n source TEXT NOT NULL,\n heading TEXT,\n content TEXT NOT NULL,\n version TEXT NOT NULL,\n tenant_id TEXT NOT NULL\n);\n\npnpm rag:ingest -- --source docs --upsert","highlighted":"<span class=\"syn-kw\">CREATE TABLE</span> <span class=\"syn-fn\">chunks</span> <span class=\"syn-punct\">(</span>\n id <span class=\"syn-type\">TEXT PRIMARY KEY</span><span class=\"syn-punct\">,</span>\n source <span class=\"syn-type\">TEXT NOT NULL</span><span class=\"syn-punct\">,</span>\n heading <span class=\"syn-type\">TEXT</span><span class=\"syn-punct\">,</span>\n content <span class=\"syn-type\">TEXT NOT NULL</span><span class=\"syn-punct\">,</span>\n version <span class=\"syn-type\">TEXT NOT NULL</span><span class=\"syn-punct\">,</span>\n tenant_id <span class=\"syn-type\">TEXT NOT NULL</span>\n<span class=\"syn-punct\">);</span>\n\n<span class=\"syn-kw\">pnpm</span> <span class=\"syn-fn\">rag:ingest</span> <span class=\"syn-punct\">-- --source</span> docs <span class=\"syn-punct\">--upsert</span>","takeaway":"The database is the source-of-truth layer. Retrieval indexes are derived views, so keep provenance here even if you later add vectors."},{"id":"lexical","label":"03 / LEXICAL","title":"Search exact words first","body":"Lexical search scores terms that literally occur in a chunk. SQLite FTS5, Postgres full-text search, or BM25 are inexpensive, fast baselines that shine for error codes, product names, IDs, and newly coined terms.","code":"SELECT source, heading, content,\n bm25(chunks_fts) AS score\nFROM chunks_fts\nWHERE chunks_fts MATCH 'leave NEAR/5 policy'\nORDER BY score\nLIMIT 5;\n\n# inspect query, score, and source before prompting","highlighted":"<span class=\"syn-kw\">SELECT</span> source<span class=\"syn-punct\">,</span> heading<span class=\"syn-punct\">,</span> content<span class=\"syn-punct\">,</span>\n <span class=\"syn-fn\">bm25</span><span class=\"syn-punct\">(</span>chunks_fts<span class=\"syn-punct\">)</span> <span class=\"syn-kw\">AS</span> score\n<span class=\"syn-kw\">FROM</span> chunks_fts\n<span class=\"syn-kw\">WHERE</span> chunks_fts <span class=\"syn-kw\">MATCH</span> <span class=\"syn-str\">'leave NEAR/5 policy'</span>\n<span class=\"syn-kw\">ORDER BY</span> score\n<span class=\"syn-kw\">LIMIT</span> <span class=\"syn-num\">5</span><span class=\"syn-punct\">;</span>\n\n<span class=\"syn-com\"># inspect query, score, and source before prompting</span>","takeaway":"Lexical search is explainable and cheap. It misses paraphrases, so measure it before assuming embeddings are necessary."},{"id":"vector","label":"04 / VECTOR","title":"Search for meaning","body":"An embedding model maps each chunk and query to vectors. A vector index finds nearby meanings even when the wording differs. Keep the embedding model and dimensions in index metadata: changing either means rebuilding the derived index.","code":"const queryVector = await embed(question);\nconst hits = await db.query(`\n SELECT content, source,\n 1 - (embedding <=> $1) AS score\n FROM chunks WHERE tenant_id = $2\n ORDER BY embedding <=> $1 LIMIT 5`,\n [queryVector, tenantId]);\n\nconsole.log(hits.map(({ source, score }) => ({ source, score })));","highlighted":"<span class=\"syn-kw\">const</span> queryVector <span class=\"syn-punct\">=</span> <span class=\"syn-kw\">await</span> <span class=\"syn-fn\">embed</span><span class=\"syn-punct\">(</span>question<span class=\"syn-punct\">);</span>\n<span class=\"syn-kw\">const</span> hits <span class=\"syn-punct\">=</span> <span class=\"syn-kw\">await</span> db<span class=\"syn-punct\">.</span><span class=\"syn-fn\">query</span><span class=\"syn-punct\">(`</span>\n <span class=\"syn-kw\">SELECT</span> content<span class=\"syn-punct\">,</span> source<span class=\"syn-punct\">,</span>\n <span class=\"syn-num\">1</span> <span class=\"syn-punct\">-</span> <span class=\"syn-punct\">(</span>embedding <span class=\"syn-punct\">&lt;=&gt;</span> <span class=\"syn-kw\">$1</span><span class=\"syn-punct\">)</span> <span class=\"syn-kw\">AS</span> score\n <span class=\"syn-kw\">FROM</span> chunks <span class=\"syn-kw\">WHERE</span> tenant_id <span class=\"syn-punct\">=</span> <span class=\"syn-kw\">$2</span>\n <span class=\"syn-kw\">ORDER BY</span> embedding <span class=\"syn-punct\">&lt;=&gt;</span> <span class=\"syn-kw\">$1</span> <span class=\"syn-kw\">LIMIT</span> <span class=\"syn-num\">5</span><span class=\"syn-punct\">`</span><span class=\"syn-punct\">,</span>\n <span class=\"syn-punct\">[</span>queryVector<span class=\"syn-punct\">,</span> tenantId<span class=\"syn-punct\">]);</span>\n\nconsole<span class=\"syn-punct\">.</span><span class=\"syn-fn\">log</span><span class=\"syn-punct\">(</span>hits<span class=\"syn-punct\">.</span><span class=\"syn-fn\">map</span><span class=\"syn-punct\">(({</span> source<span class=\"syn-punct\">,</span> score <span class=\"syn-punct\">})</span> <span class=\"syn-kw\">=&gt;</span> <span class=\"syn-punct\">({</span> source<span class=\"syn-punct\">,</span> score <span class=\"syn-punct\">})));</span>","takeaway":"Vectors recover concepts and paraphrases. They can blur exact identifiers and add model, storage, and re-embedding costs."},{"id":"hybrid","label":"05 / HYBRID","title":"Let two searchers cover each other","body":"Run lexical and vector retrieval in parallel, merge their candidates, and optionally rerank the short list. Reciprocal rank fusion is a simple first merge: a result earns credit from both rankings without requiring comparable raw scores.","code":"const [lexical, dense] = await Promise.all([\n searchBM25(question, { topK: 10 }),\n searchVector(question, { topK: 10 }),\n]);\nconst candidates = reciprocalRankFusion([lexical, dense]);\nconst evidence = await rerank(question, candidates.slice(0, 8));\n\nreturn answerFrom(evidence.slice(0, 4));","highlighted":"<span class=\"syn-kw\">const</span> <span class=\"syn-punct\">[</span>lexical<span class=\"syn-punct\">,</span> dense<span class=\"syn-punct\">]</span> <span class=\"syn-punct\">=</span> <span class=\"syn-kw\">await</span> Promise<span class=\"syn-punct\">.</span><span class=\"syn-fn\">all</span><span class=\"syn-punct\">([</span>\n <span class=\"syn-fn\">searchBM25</span><span class=\"syn-punct\">(</span>question<span class=\"syn-punct\">,</span> <span class=\"syn-punct\">{</span> topK<span class=\"syn-punct\">:</span> <span class=\"syn-num\">10</span> <span class=\"syn-punct\">}),</span>\n <span class=\"syn-fn\">searchVector</span><span class=\"syn-punct\">(</span>question<span class=\"syn-punct\">,</span> <span class=\"syn-punct\">{</span> topK<span class=\"syn-punct\">:</span> <span class=\"syn-num\">10</span> <span class=\"syn-punct\">}),</span>\n<span class=\"syn-punct\">]);</span>\n<span class=\"syn-kw\">const</span> candidates <span class=\"syn-punct\">=</span> <span class=\"syn-fn\">reciprocalRankFusion</span><span class=\"syn-punct\">([</span>lexical<span class=\"syn-punct\">,</span> dense<span class=\"syn-punct\">]);</span>\n<span class=\"syn-kw\">const</span> evidence <span class=\"syn-punct\">=</span> <span class=\"syn-kw\">await</span> <span class=\"syn-fn\">rerank</span><span class=\"syn-punct\">(</span>question<span class=\"syn-punct\">,</span> candidates<span class=\"syn-punct\">.</span><span class=\"syn-fn\">slice</span><span class=\"syn-punct\">(</span><span class=\"syn-num\">0</span><span class=\"syn-punct\">,</span> <span class=\"syn-num\">8</span><span class=\"syn-punct\">));</span>\n\n<span class=\"syn-kw\">return</span> <span class=\"syn-fn\">answerFrom</span><span class=\"syn-punct\">(</span>evidence<span class=\"syn-punct\">.</span><span class=\"syn-fn\">slice</span><span class=\"syn-punct\">(</span><span class=\"syn-num\">0</span><span class=\"syn-punct\">,</span> <span class=\"syn-num\">4</span><span class=\"syn-punct\">));</span>","takeaway":"Hybrid retrieval is a strong default for mixed knowledge. Add reranking only after Recall@k shows the first stage found the right evidence."},{"id":"evaluate","label":"06 / EVALUATE","title":"Make retrieval prove its claim","body":"A confident answer is not evidence that retrieval worked. Keep questions with gold source IDs, inspect the retrieved list, then measure retrieval and answer quality separately. Change one retrieval variable at a time.","code":"{\"question\":\"What is the leave limit?\",\"gold\":[\"handbook.md#leave\"],\"retrieved\":[\"handbook.md#leave\"],\"cited\":true}\n\nRecall@5 = 1.0\nMRR = 1.0\nFaithfulness = reviewed against cited chunks\nAbstention = expected when gold evidence is absent","highlighted":"<span class=\"syn-punct\">{</span><span class=\"syn-str\">\"question\"</span><span class=\"syn-punct\">:</span><span class=\"syn-str\">\"What is the leave limit?\"</span><span class=\"syn-punct\">,</span><span class=\"syn-str\">\"gold\"</span><span class=\"syn-punct\">:[</span><span class=\"syn-str\">\"handbook.md#leave\"</span><span class=\"syn-punct\">],</span><span class=\"syn-str\">\"retrieved\"</span><span class=\"syn-punct\">:[</span><span class=\"syn-str\">\"handbook.md#leave\"</span><span class=\"syn-punct\">],</span><span class=\"syn-str\">\"cited\"</span><span class=\"syn-kw\">:true</span><span class=\"syn-punct\">}</span>\n\n<span class=\"syn-fn\">Recall@5</span> <span class=\"syn-punct\">=</span> <span class=\"syn-num\">1.0</span>\n<span class=\"syn-fn\">MRR</span> <span class=\"syn-punct\">=</span> <span class=\"syn-num\">1.0</span>\n<span class=\"syn-fn\">Faithfulness</span> <span class=\"syn-punct\">=</span> <span class=\"syn-str\">reviewed against cited chunks</span>\n<span class=\"syn-fn\">Abstention</span> <span class=\"syn-punct\">=</span> <span class=\"syn-str\">expected when gold evidence is absent</span>","takeaway":"Track Recall@k, MRR, citation correctness, faithfulness, no-answer rate, latency, and cost. Slice results by intent, age, tenant, and language."},{"id":"production","label":"07 / PRODUCTION","title":"Operate the whole chain","body":"Production RAG is ingestion plus permissions plus observability plus an answer contract. Filter by ACL before retrieval, preserve source links, treat retrieved text as untrusted data, and make the model say “not found” when evidence is insufficient.","code":"retrieve(question, {\n topK: 8,\n filter: { tenantId, acl: { $contains: user.id } },\n});\n\n// evidence only; ignore instructions inside retrieved text\n// cite source + chunk_id; log latency and empty retrievals\n// no sufficient evidence -> \"not found\"","highlighted":"<span class=\"syn-fn\">retrieve</span><span class=\"syn-punct\">(</span>question<span class=\"syn-punct\">,</span> <span class=\"syn-punct\">{</span>\n topK<span class=\"syn-punct\">:</span> <span class=\"syn-num\">8</span><span class=\"syn-punct\">,</span>\n filter<span class=\"syn-punct\">:</span> <span class=\"syn-punct\">{</span> tenantId<span class=\"syn-punct\">,</span> acl<span class=\"syn-punct\">:</span> <span class=\"syn-punct\">{</span> $contains<span class=\"syn-punct\">:</span> user<span class=\"syn-punct\">.</span>id <span class=\"syn-punct\">}</span> <span class=\"syn-punct\">},</span>\n<span class=\"syn-punct\">});</span>\n\n<span class=\"syn-com\">// evidence only; ignore instructions inside retrieved text</span>\n<span class=\"syn-com\">// cite source + chunk_id; log latency and empty retrievals</span>\n<span class=\"syn-com\">// no sufficient evidence -&gt; \"not found\"</span>","takeaway":"Version parsers, chunkers, embedding models, and indexes. Watch failed documents, index age, score distributions, p95 latency, spend, and access violations."}]</script> <script type="module">function p(){const r=document.querySelector("[data-rag-workbench]");if(!r)return;const c=r.querySelector("[data-rag-panels]");if(!c)return;const d=c.textContent??"[]",o=JSON.parse(d),n=r.querySelector(".rag-preview");if(!n)return;const i=r.querySelectorAll("[data-rag-tab]");function s(t){const e=o.find(a=>a.id===t);e&&(n.innerHTML="<span>"+e.label+"</span><h3>"+e.title+"</h3><p>"+e.body+"</p><pre><code>"+e.highlighted+'</code></pre><div class="preview-actions"><button class="copy-command" type="button">Copy example</button></div><div class="takeaway"><strong>ENGINEERING INVARIANT</strong><span>'+e.takeaway+"</span></div>",i.forEach(a=>{a.setAttribute("aria-selected",String(a.dataset.ragTab===t))}),n.querySelector(".copy-command")?.addEventListener("click",async a=>{const l=a.currentTarget;await navigator.clipboard?.writeText(e.code),l.textContent="Copied"}))}i.forEach(t=>{t.addEventListener("click",()=>{s(t.dataset.ragTab||"files")})}),n.querySelector(".copy-command")?.addEventListener("click",async t=>{const e=t.currentTarget;await navigator.clipboard?.writeText(o[0]?.code||""),e.textContent="Copied"}),s(o[0]?.id||"files")}p();</script> </div> </section> <section class="model reveal" data-astro-cid-ogwjzfbi> <div class="depth-slow" data-astro-cid-ogwjzfbi> <p class="eyebrow" data-language-content="en">04 / ingestion &amp; chunking</p> <p class="eyebrow" data-language-content="pt" hidden>04 / ingestão &amp; fatiamento</p> <h2 data-language-content="en" data-astro-cid-ogwjzfbi>Chunks need<br><em>hierarchy & provenance.</em></h2> <h2 data-language-content="pt" hidden data-astro-cid-ogwjzfbi>Trechos precisam de<br><em>hierarquia e proveniência.</em></h2> <p data-language-content="en" data-astro-cid-ogwjzfbi>Naive character slicing breaks tables, splits code blocks across chunks, and strips section headings. Production chunking parses document syntax, attaches breadcrumbs (&#39;Handbook &gt; Policies &gt; Leave&#39;), and calculates content hashes for idempotent re-ingestion.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi>Fatiar por caracteres arbitrários quebra tabelas, divide blocos de código e remove títulos de seção. O fatiamento de produção analisa a sintaxe do documento, anexa trilhas de cabeçalho (&#39;Manual &gt; Políticas &gt; Licença&#39;) e calcula hashes para reingestão idempotente.</p> <svg class="draw-line" viewBox="0 0 110 110" aria-hidden="true" focusable="false" style="--draw-height: 110px" data-astro-cid-n6ozym62> <path d="M 0.5 0 V 86.5 Q 0.5 109.5 24 109.5 H 110" pathLength="100" data-astro-cid-n6ozym62></path> </svg> </div> <div class="panel depth-fast" data-astro-cid-ogwjzfbi> <strong data-language-content="en">CANONICAL CHUNK ENVELOPE</strong> <strong data-language-content="pt" hidden>ENVELOPE CANÔNICO DE CHUNK</strong> <code data-astro-cid-ogwjzfbi>interface ChunkRecord {
chunk_id: string; <span class="com">// sha256(source + heading + content)</span>
source_path: string; <span class="com">// <span class="str">'docs/handbook/leave.md'</span></span>
heading_path: string[]; <span class="com">// [<span class="str">'Policies'</span>, <span class="str">'Annual Leave'</span>, <span class="str">'Limits'</span>]</span>
content: string; <span class="com">// clean markdown with code intact</span>
tenant_id: string; <span class="com">// partition key <span class=<span class="str">"kw"</span>>for</span> pre-retrieval ACL</span>
version: string; <span class="com">// git commit sha or document revision</span>
tokens: number; <span class="com">// bounded context budget (200-500 tokens)</span>
}</code> <code hidden data-astro-cid-ogwjzfbi>interface ChunkRecord {
chunk_id: string; <span class="com">// sha256(source + heading + content)</span>
source_path: string; <span class="com">// <span class="str">'docs/handbook/leave.md'</span></span>
heading_path: string[]; <span class="com">// [<span class="str">'Políticas'</span>, <span class="str">'Licença Anual'</span>, <span class="str">'Limites'</span>]</span>
content: string; <span class="com">// markdown limpo com código intacto</span>
tenant_id: string; <span class="com">// chave de partição para ACL pré-busca</span>
version: string; <span class="com">// commit sha ou revisão do documento</span>
tokens: number; <span class="com">// orçamento de contexto (200-500 tokens)</span>
}</code> <p class="panel-hint" data-language-content="en">Idempotent upsert: hash the source text so re-ingestion does not duplicate knowledge or regenerate vector embeddings unnecessarily.</p> <p class="panel-hint" data-language-content="pt" hidden>Upsert idempotente: calcule o hash do texto-fonte para que a reingestão não duplique conhecimento nem regenere embeddings desnecessariamente.</p> </div> </section> <section class="model rag-metrics reveal" data-astro-cid-ogwjzfbi> <div class="depth-slow" data-astro-cid-ogwjzfbi> <p class="eyebrow" data-language-content="en">05 / evaluation &amp; defense</p> <p class="eyebrow" data-language-content="pt" hidden>05 / avaliação &amp; defesa</p> <h2 data-language-content="en" data-astro-cid-ogwjzfbi>Measure two tiers.<br><em>Treat input as untrusted.</em></h2> <h2 data-language-content="pt" hidden data-astro-cid-ogwjzfbi>Meça duas etapas.<br><em>Trate entradas como não confiáveis.</em></h2> <p data-language-content="en" data-astro-cid-ogwjzfbi>Never evaluate RAG with a single overall score. A good LLM can hallucinate a plausible answer from bad retrieval, while a poor prompt can fail even with perfect evidence. Score retrieval (Recall@k, MRR) independently from generation (Faithfulness, Relevance). Simultaneously, treat all retrieved text as untrusted data to defend against indirect prompt injection.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi>Nunca avalie RAG com uma pontuação geral única. Um bom modelo pode alucinar uma resposta plausível a partir de uma recuperação falha, e um prompt ruim pode errar mesmo com evidências perfeitas. Meça a recuperação (Recall@k, MRR) separadamente da geração (Fidelidade, Relevância). Simultaneamente, trate todo texto recuperado como dado não confiável para mitigar injeção indireta de prompt.</p> <svg class="draw-line" viewBox="0 0 4 110" aria-hidden="true" focusable="false" style="--draw-height: 110px" data-astro-cid-n6ozym62> <path d="M 0.5 0 V 110" pathLength="100" data-astro-cid-n6ozym62></path> </svg> </div> <div class="panel depth-fast" data-astro-cid-ogwjzfbi> <strong data-language-content="en">TWO-TIER METRICS MATRIX</strong> <strong data-language-content="pt" hidden>MATRIZ DE MÉTRICAS EM DUAS ETAPAS</strong> <code data-astro-cid-ogwjzfbi>RETRIEVAL QUALITY (Did we find the needle?)
Recall@k -&gt; Did gold chunks appear <span class=<span class="str">"kw"</span>>in</span> top-k results?
MRR -&gt; Position <span class=<span class="str">"kw"</span>>of</span> the first relevant chunk (1/rank)
nDCG -&gt; Graded relevance order across candidate set
GENERATION INTEGRITY (Did the answer honor the context?)
Faithfulness -&gt; All claims verified against retrieved evidence
Relevance -&gt; Directly answers the user question without drift
Abstention -&gt; Model says <span class="str">'not found'</span> when evidence is missing
Security -&gt; Pre-filtered ACLs; isolated prompt data delimiters</code> <code hidden data-astro-cid-ogwjzfbi>QUALIDADE DA RECUPERAÇÃO (Encontramos a agulha?)
Recall@k -&gt; Os trechos corretos apareceram nos top-k resultados?
MRR -&gt; Posição do primeiro trecho relevante (1/rank)
nDCG -&gt; Ordem de relevância graduada no conjunto
INTEGRIDADE DA GERAÇÃO (A resposta honrou o contexto?)
Fidelidade -&gt; Todas as afirmações são comprovadas nas evidências
Relevância -&gt; Responde diretamente sem desviar da pergunta
Abstenção -&gt; Modelo diz <span class="str">'não encontrado'</span> quando faltam dados
Segurança -&gt; ACLs pré-filtradas; delimitadores isolados no prompt</code> </div> </section> <section class="practice recall reveal" id="recall" data-astro-cid-ogwjzfbi> <div class="depth-slow" data-astro-cid-ogwjzfbi> <p class="eyebrow" data-language-content="en">06 / check yourself</p> <p class="eyebrow" data-language-content="pt" hidden>06 / teste seus conhecimentos</p> <h2 data-language-content="en" data-astro-cid-ogwjzfbi>Test your<br><em>retrieval instincts.</em></h2> <h2 data-language-content="pt" hidden data-astro-cid-ogwjzfbi>Teste seus<br><em>instintos de recuperação.</em></h2> <p data-language-content="en" data-astro-cid-ogwjzfbi>Active retrieval builds durable intuition. Formulate your answer from memory before opening each question, then verify your mental model against the architectural rationale.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi>A recuperação ativa consolida o aprendizado duradouro. Formule sua resposta de memória antes de abrir cada pergunta e confronte seu modelo mental com a justificativa técnica.</p> </div> <div class="recall-list depth-fast" data-astro-cid-ogwjzfbi> <details data-astro-cid-ogwjzfbi> <summary data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>Why should you benchmark BM25 lexical search before adopting vector embeddings?</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Por que você deve avaliar a busca lexical BM25 antes de adotar embeddings vetoriais? </span> <b aria-hidden="true" data-astro-cid-ogwjzfbi>+</b> </summary> <p data-language-content="en" data-astro-cid-ogwjzfbi>BM25 is sub-millisecond, costs nothing in GPUs or embedding APIs, and reliably matches exact error codes, IDs, function signatures, and newly introduced product names where vector representations struggle or hallucinate. Measuring BM25 establishes an explainable baseline, proving whether semantic vector search actually yields higher Recall@k on real user questions.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi> O BM25 tem latência submilissegundo, não consome GPU ou APIs de embedding e encontra perfeitamente códigos de erro exatos, identificadores, assinaturas de funções e termos novos nos quais embeddings vacilam. Testar BM25 define uma linha de base clara, provando se a busca vetorial realmente entrega ganho de Recall@k em perguntas reais. </p> </details><details data-astro-cid-ogwjzfbi> <summary data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>What is the operational difference between Bi-Encoders and Cross-Encoders in a hybrid pipeline?</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Qual é a diferença operacional entre Bi-Encoders e Cross-Encoders em uma arquitetura híbrida? </span> <b aria-hidden="true" data-astro-cid-ogwjzfbi>+</b> </summary> <p data-language-content="en" data-astro-cid-ogwjzfbi>Bi-Encoders embed query and documents separately into vectors, enabling O(1) nearest-neighbor candidate retrieval across millions of records but losing token-to-token cross-attention. Cross-Encoders process (query, passage) together through full transformer self-attention, delivering significantly higher reranking precision at much higher latency. Production systems use Bi-Encoders to select 50 candidates, then a Cross-Encoder to rerank the top 5.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Bi-Encoders geram embeddings independentes da pergunta e dos documentos, permitindo busca aproximada O(1) em milhões de itens, mas perdem a atenção cruzada entre termos. Cross-Encoders processam a pergunta e o trecho juntos em camadas completas de atenção, atingindo altíssima precisão de reranking com custo computacional superior. Sistemas reais usam Bi-Encoders para selecionar 50 candidatos e um Cross-Encoder para reordenar os 5 melhores. </p> </details><details data-astro-cid-ogwjzfbi> <summary data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>Why is filtering by tenant and access control (ACL) after vector retrieval a critical defect?</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Por que filtrar permissões e tenant (ACL) após a busca vetorial é uma falha crítica? </span> <b aria-hidden="true" data-astro-cid-ogwjzfbi>+</b> </summary> <p data-language-content="en" data-astro-cid-ogwjzfbi>If you retrieve the global top-10 vectors and then discard chunks belonging to other tenants, a query can return zero results even when valid, authorized documents exist at ranks 11–20. Post-filtering can also leak metadata or document existence through timing differentials. Pre-filtering by tenant and ACL within the index query ensures the candidate set is drawn strictly from authorized data.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Se você recupera os 10 vetores globais mais próximos e depois descarta o que pertence a outro tenant, a consulta pode retornar vazia mesmo que existam documentos autorizados excelentes nas posições 11 a 20. O pós-filtro também pode vazar a existência de documentos sigilosos por variação de tempo. A pré-filtragem por tenant e ACL dentro do índice garante que os candidatos venham exclusivamente do espaço autorizado. </p> </details><details data-astro-cid-ogwjzfbi> <summary data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>Why must retrieval metrics and generation metrics be measured separately?</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Por que métricas de recuperação e métricas de geração devem ser medidas separadamente? </span> <b aria-hidden="true" data-astro-cid-ogwjzfbi>+</b> </summary> <p data-language-content="en" data-astro-cid-ogwjzfbi>A capable LLM can fabricate a plausible, correct-looking answer from irrelevant or missing context (a latent hallucination), while an improperly structured prompt can produce a confused answer from perfect context. Measuring Retrieval (Recall@k, MRR) independently from Generation (Faithfulness, Citation precision, Negative abstention) isolates whether the index or the prompting layer needs work.</p> <p data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Um modelo avançado pode inventar uma resposta plausível a partir de um contexto irrelevante (uma alucinação latente), enquanto um prompt mal formatado pode gerar uma resposta confusa mesmo recebendo trechos perfeitos. Medir a Recuperação (Recall@k, MRR) separadamente da Geração (Fidelidade, precisão de citação, abstenção) isola com precisão se o problema está no índice ou no prompt. </p> </details> </div> <nav class="links recall-sources" aria-label="Primary sources" data-astro-cid-ogwjzfbi> <a href="https://arxiv.org/abs/2005.11401" target="_blank" rel="noreferrer" data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>RAG Foundation Paper (Lewis et al.) ↗</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Artigo Fundamental de RAG (Lewis et al.) ↗ </span> </a><a href="https://arxiv.org/abs/2104.08663" target="_blank" rel="noreferrer" data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>BEIR Information Retrieval Benchmark ↗</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Benchmark de Recuperação BEIR ↗ </span> </a><a href="https://doi.org/10.6028/NIST.AI.600-1" target="_blank" rel="noreferrer" data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>NIST GenAI Security Profile ↗</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Perfil de Segurança GenAI do NIST ↗ </span> </a><a href="https://owasp.org/www-project-top-10-for-large-language-model-applications/" target="_blank" rel="noreferrer" data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>OWASP LLM Top 10 Vulnerabilities ↗</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Top 10 Vulnerabilidades LLM da OWASP ↗ </span> </a><a href="/ai-for-dummies/docs/references/rag/" data-astro-cid-ogwjzfbi> <span data-language-content="en" data-astro-cid-ogwjzfbi>Chapter Primary Sources ↗</span> <span data-language-content="pt" hidden data-astro-cid-ogwjzfbi> Fontes Primárias do Capítulo ↗ </span> </a> </nav> </section> </main> <section class="footer" data-astro-cid-bmvnf73n> <nav class="links" aria-label="Chapter navigation" data-astro-cid-bmvnf73n> <nav class="links" aria-label="Chapter navigation" data-astro-cid-ogwjzfbi> <a href="/ai-for-dummies/full-guide/" data-astro-cid-ogwjzfbi>Field guide →</a> <a href="/ai-for-dummies/hands-on/starter/" data-astro-cid-ogwjzfbi>Practice →</a> </nav> </nav> <div class="text" data-astro-cid-bmvnf73n> </div> </section> </body></html>