05 / Grounded knowledge
05 / Conhecimento fundamentado
Retrieve first.
Then reason.Recupere primeiro.
Depois raciocine.
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.
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 não encontrado.
Transcript Transcrição
- 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.
- 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.
01 / the foundation
01 / os fundamentos
A model has a
library card.
Um modelo tem uma
ficha de biblioteca.
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.
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.
-
01 Ingest Ingerir Parse trusted documents, isolate headings and code fences, and attach source, tenant, ACL, and version metadata. Analise documentos confiáveis, isole cabeçalhos e blocos de código e anexe metadados de fonte, tenant, ACL e versão. -
02 Retrieve Recuperar Execute filtered lexical or vector search to select a tight candidate set (3 to 8 chunks) before generation begins. Execute busca lexical ou vetorial filtrada para selecionar um conjunto compacto de candidatos (3 a 8 trechos) antes da geração. -
03 Ground Fundamentar Synthesize the answer strictly with attributable citations, or abstain explicitly when evidence is missing or ambiguous. Sintetize a resposta estritamente com citações rastreáveis ou abstenha-se explicitamente quando a evidência for insuficiente.
02 / ARCHITECTURES 02 / ARQUITETURAS
From local files
to hybrid search. De arquivos locais
à busca híbrida.
Choose the simplest architecture that satisfies your provenance, latency, and update requirements. Measure lexical search before paying for vector infrastructure. 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.
The folder is the index
A pasta é o índice
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.
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.
Search exact words first
Busque palavras exatas primeiro
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.
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.
Search for semantic meaning
Busque pelo significado semântico
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.
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.
Let two searchers cover each other
Deixe dois buscadores se cobrirem
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.
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.
03 / INSPECT THE PIPELINE 03 / INSPECIONE O PIPELINE
From source
to answer. Da fonte
à resposta.
Select a stage to inspect the actual code, SQL schema, queries, and invariants an agent needs to operate each layer without hand-waving. 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.
RAG / BUILD LAB
The smallest useful RAG is a folder
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.
rag-demo/
├── docs/handbook.md
├── eval/questions.jsonl
└── src/
├── chunk.ts
└── ask.ts
pnpm tsx src/ask.ts "How many days of leave?" 04 / ingestion & chunking
04 / ingestão & fatiamento
Chunks need
hierarchy & provenance.
Trechos precisam de
hierarquia e proveniência.
Naive character slicing breaks tables, splits code blocks across chunks, and strips section headings. Production chunking parses document syntax, attaches breadcrumbs ('Handbook > Policies > Leave'), and calculates content hashes for idempotent re-ingestion.
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 ('Manual > Políticas > Licença') e calcula hashes para reingestão idempotente.
interface ChunkRecord {
chunk_id: string; // sha256(source + heading + content)
source_path: string; // 'docs/handbook/leave.md'
heading_path: string[]; // ['Policies', 'Annual Leave', 'Limits']
content: string; // clean markdown with code intact
tenant_id: string; // partition key "kw">for pre-retrieval ACL
version: string; // git commit sha or document revision
tokens: number; // bounded context budget (200-500 tokens)
} interface ChunkRecord {
chunk_id: string; // sha256(source + heading + content)
source_path: string; // 'docs/handbook/leave.md'
heading_path: string[]; // ['Políticas', 'Licença Anual', 'Limites']
content: string; // markdown limpo com código intacto
tenant_id: string; // chave de partição para ACL pré-busca
version: string; // commit sha ou revisão do documento
tokens: number; // orçamento de contexto (200-500 tokens)
} Idempotent upsert: hash the source text so re-ingestion does not duplicate knowledge or regenerate vector embeddings unnecessarily.
Upsert idempotente: calcule o hash do texto-fonte para que a reingestão não duplique conhecimento nem regenere embeddings desnecessariamente.
05 / evaluation & defense
05 / avaliação & defesa
Measure two tiers.
Treat input as untrusted.
Meça duas etapas.
Trate entradas como não confiáveis.
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.
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.
RETRIEVAL QUALITY (Did we find the needle?)
Recall@k -> Did gold chunks appear "kw">in top-k results?
MRR -> Position "kw">of the first relevant chunk (1/rank)
nDCG -> Graded relevance order across candidate set
GENERATION INTEGRITY (Did the answer honor the context?)
Faithfulness -> All claims verified against retrieved evidence
Relevance -> Directly answers the user question without drift
Abstention -> Model says 'not found' when evidence is missing
Security -> Pre-filtered ACLs; isolated prompt data delimiters QUALIDADE DA RECUPERAÇÃO (Encontramos a agulha?)
Recall@k -> Os trechos corretos apareceram nos top-k resultados?
MRR -> Posição do primeiro trecho relevante (1/rank)
nDCG -> Ordem de relevância graduada no conjunto
INTEGRIDADE DA GERAÇÃO (A resposta honrou o contexto?)
Fidelidade -> Todas as afirmações são comprovadas nas evidências
Relevância -> Responde diretamente sem desviar da pergunta
Abstenção -> Modelo diz 'não encontrado' quando faltam dados
Segurança -> ACLs pré-filtradas; delimitadores isolados no prompt 06 / check yourself
06 / teste seus conhecimentos
Test your
retrieval instincts.
Teste seus
instintos de recuperação.
Active retrieval builds durable intuition. Formulate your answer from memory before opening each question, then verify your mental model against the architectural rationale.
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.
Why should you benchmark BM25 lexical search before adopting vector embeddings? Por que você deve avaliar a busca lexical BM25 antes de adotar embeddings vetoriais? +
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.
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.
What is the operational difference between Bi-Encoders and Cross-Encoders in a hybrid pipeline? Qual é a diferença operacional entre Bi-Encoders e Cross-Encoders em uma arquitetura híbrida? +
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.
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.
Why is filtering by tenant and access control (ACL) after vector retrieval a critical defect? Por que filtrar permissões e tenant (ACL) após a busca vetorial é uma falha crítica? +
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.
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.
Why must retrieval metrics and generation metrics be measured separately? Por que métricas de recuperação e métricas de geração devem ser medidas separadamente? +
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.
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.