RAG ingestion/chunking
RAG começa antes da pergunta: documentos precisam ser obtidos, interpretados, segmentados e indexados de forma rastreável. Uma recuperação ruim pode resultar de uma ingestão que perdeu títulos ou separou a condição da regra. Nesta semana você construirá unidades de evidência que preservam significado.
O caso é uma política de ativação com seções, tabela e exceção. Você investigará parsing, chunking, overlap e relação entre trecho e documento pai. A meta é permitir que a busca encontre a parte relevante sem fazer o gerador perder o contexto necessário para interpretá-la.
JavaScriptRAGAo terminar esta aula
- Ingestão determina o que pode ser recuperado.
- Chunking equilibra precisão e contexto.
- Origem e versão acompanham cada trecho.
Antes de continuar: Laboratório: Embeddings + pgvector
Parsing e ingestion são etapas distintas
FundamentosIngestion organiza entrada de documentos, valida origem, registra versão e prepara armazenamento. Parsing extrai estrutura e conteúdo do formato original. Um PDF escaneado pode exigir reconhecimento de texto; uma página HTML contém navegação que não pertence à política; uma tabela depende de relações entre linha e coluna. Extrair uma sequência de palavras não garante preservação de significado. Verifique números, cabeçalhos e exceções antes de gerar embeddings.
Guarde referência ao original e metadados de processamento. Se um parser muda, pode ser necessário reprocessar e comparar resultados. A ingestão também precisa tratar duplicatas, atualização e remoção. Indexar a mesma política duas vezes pode reforçar um texto antigo e ocupar candidatos. Um identificador estável de documento e uma versão tornam a mudança auditável. Loader de biblioteca ajuda a conectar fontes, mas não prova que a extração atende ao seu domínio. A aceitação começa com conteúdo legível e estrutura suficiente para sustentar respostas.
Chunking divide unidades para recuperação
FundamentosChunking separa documentos em trechos para representação e busca. Tamanho pequeno favorece localização específica, mas pode perder condição; tamanho grande preserva contexto, mas pode diluir relevância e aumentar volume enviado. Não existe tamanho universal. Para uma política, separe por seção e mantenha título e exceção associados. Para código ou tabela, respeite estruturas que não podem ser cortadas arbitrariamente sem perder relação.
O limite do modelo de embedding e o orçamento de geração influenciam o desenho. Um splitter recursivo tenta dividir por delimitadores em diferentes níveis, mas ainda precisa de inspeção sobre textos reais. Não confunda número de caracteres com tokens exatos. Escolha candidatos de segmentação e avalie perguntas que dependem de fronteiras. Se a regra fica em um trecho e a exceção no seguinte, o pipeline precisa recuperar ambos ou preservar o vínculo. A segmentação é parte da qualidade da evidência, não apenas um passo técnico de preparação.
Overlap, duplicação e custo
FundamentosOverlap repete parte do conteúdo entre trechos para reduzir perda nas fronteiras. Pode ajudar quando uma frase ou referência cruza a divisão, mas também aumenta armazenamento, processamento e redundância na recuperação. Muitos trechos quase iguais podem ocupar os primeiros resultados e deixar de fora outras evidências. Deduplicação ou diversidade de candidatos pode ser necessária na etapa seguinte. Não aumente overlap sem avaliar seu efeito no conjunto relevante.
Para a política, uma pequena repetição do título ajuda a interpretar um trecho. Repetir toda a seção em cada unidade pode tornar a busca menos discriminativa. Compare uma pergunta sobre regra e outra sobre exceção. Meça quais trechos aparecem e quanto texto redundante chega ao gerador. A métrica importante não é apenas quantidade indexada, mas capacidade de recuperar a evidência suficiente. Quando overlap corrige uma fronteira específica, registre essa razão e o custo adicional em vez de generalizar que mais repetição sempre melhora RAG.
Metadata e parent-document retrieval
FundamentosMetadados registram documento, seção, ordem, versão, escopo e origem. Eles permitem recuperar adjacências, filtrar vigência e citar o original. Não inclua apenas texto e vetor: sem vínculo, um resultado pode ficar impossível de verificar. Parent-document retrieval busca unidades menores e devolve contexto maior associado, como seção ou documento pai. A ideia combina localização precisa com informação suficiente para interpretação.
↗ LangChain ParentDocumentRetriever↗ Qdrant Points↗ OpenAI Retrieval
O tamanho do pai precisa respeitar orçamento e relevância. Retornar todo um manual após qualquer match pode recriar o problema de excesso de contexto. Uma seção com regra e exceção costuma ser uma unidade mais útil. O relacionamento filho-pai deve sobreviver a atualizações e remoções. Se um trecho aponta para pai de versão antiga, você pode combinar evidências incompatíveis. Verifique também escopo: o pai não deve trazer conteúdo não autorizado apenas porque um filho passou por filtro. A implementação de biblioteca oferece um padrão, mas o contrato de dados e acesso continua sendo seu.
↗ LangChain ParentDocumentRetriever↗ Qdrant Points↗ OpenAI Retrieval
Verificação da ingestão e erros comuns
FundamentosCrie amostras para comparar original e texto extraído: título, tabela, número, condição e exceção. Verifique que caracteres e unidades não foram alterados. Depois teste consultas que dependem dessas partes. Uma resposta errada sobre prazo pode nascer no parser, não no gerador. Não ajuste prompt para compensar um documento indexado sem a palavra “exceto”. A investigação percorre original, parsing, segmentação, recuperação e geração.
↗ Document loader integrations↗ OpenAI Retrieval↗ LangChain ParentDocumentRetriever
A ingestão deve produzir relatório com documentos aceitos, rejeitados e versões. Conteúdo inacessível ou malformado precisa de tratamento explícito. Atualizações podem exigir remover embeddings anteriores e reconstruir relações. Preserve idempotência do lote de ingestão para não criar duplicatas em retries. Retome os contratos de APIs: o resultado de uma etapa deve comunicar o que foi feito e o que falhou, permitindo recuperação sem presumir conclusão. Um pipeline confiável mantém rastreabilidade do arquivo até a afirmação apresentada ao usuário.
↗ Document loader integrations↗ OpenAI Retrieval↗ LangChain ParentDocumentRetriever
Exemplo comentado e limites
FundamentosO exemplo usa seções como unidades, preservando a exceção junto da regra. Ele não extrai PDF nem gera embeddings. Essa escolha torna a estrutura inspecionável e permite avaliar o contrato filho-pai antes de conectar loaders ou banco.
const secoes = [
{id:"s1",titulo:"Ativação",texto:"Acesso após confirmação. Exceção: análise manual pode ser necessária."},
{id:"s2",titulo:"Contato",texto:"Use o canal oficial para consultar o estado."}
];
const chunks = secoes.map((s,i)=>({id:"c"+i,parentId:s.id,
documentoId:"politica-1",versao:2,tenant:"A",
texto:s.titulo+"\n"+s.texto}));
console.log(chunks);
console.log("pai",secoes.find(s=>s.id===chunks[0].parentId));Cada trecho carrega versão e escopo. O relacionamento aponta para uma seção existente. Em um armazenamento real, inclua versão no vínculo e aplique filtros também à recuperação do pai. O texto repetido do título ajuda a interpretação, mas precisa ser avaliado quanto à redundância.
Exercício aplicado
Segmente uma política mantendo regra e exceção recuperáveis e prepare vínculo ao documento pai.
- Tente definir evidências mínimas.
- Compare tamanho, estrutura e overlap.
- Valide vínculos e versões.
- Avalie perguntas e registre origem das falhas.
Abrir resolução comentada
A solução compara segmentação por tamanho com segmentação por estrutura usando perguntas sobre regra e exceção. Seleciona a opção que preserva evidência e orçamento no corpus, registrando compromissos. Parent retrieval acrescenta a seção quando um trecho curto não basta.
O relatório identifica parsing não executado e operações locais realizadas. Uma etapa real de ingestão registra origem e falhas, remove versões anteriores conforme política e verifica que a exceção sobre análise manual não desapareceu no processamento.
A resolução privilegia preservação de significado e rastreabilidade. O tamanho escolhido é justificado pelo corpus e perguntas, não por um número universal.
A implementação realiza ingestão idempotente de seções, vincula filho e pai a documento, versão e escopo e rejeita vínculo inexistente ou incompatível. A comparação por tamanho e overlap usa caracteres como unidade didática, não tokens reais. A avaliação testa a evidência mínima para regra e exceção e mostra que expansão estrutural conserva a relação. Não foram executados parsing de PDF, embeddings ou banco; esses adaptadores seguem as verificações ensinadas no corpo.
import assert from "node:assert/strict";
const pais=new Map(),filhos=new Map();
const politica={id:"politica-1",versao:2,tenant:"A",secoes:[
{id:"ativacao",texto:"Acesso após confirmação. Exceção: análise manual pode ser necessária."},
{id:"contato",texto:"Consulte o canal oficial para verificar o estado."}]};
function ingerir(documento){
for(const secao of documento.secoes){const parentId=JSON.stringify([documento.tenant,documento.id,documento.versao,secao.id]);
pais.set(parentId,{...secao,tenant:documento.tenant,documentoId:documento.id,versao:documento.versao});
filhos.set(parentId+":0",{id:parentId+":0",parentId,tenant:documento.tenant,
documentoId:documento.id,versao:documento.versao,texto:secao.texto});
}
}
function expandir(id,ctx,versao){
const filho=filhos.get(id);if(!filho)throw new Error("FILHO_AUSENTE");
if(filho.tenant!==ctx.tenant)throw new Error("SEM_PERMISSAO");
const pai=pais.get(filho.parentId);if(!pai)throw new Error("PAI_AUSENTE");
if(pai.tenant!==ctx.tenant)throw new Error("SEM_PERMISSAO");
if(pai.versao!==versao||filho.versao!==versao)throw new Error("VERSAO_INCOMPATIVEL");
return pai;
}
function porTamanho(texto,tamanho,overlap){
if(tamanho<=overlap||overlap<0)throw new Error("JANELA_INVALIDA");
const trechos=[];for(let i=0;i<texto.length;i+=tamanho-overlap)trechos.push(texto.slice(i,i+tamanho));
return trechos;
}
ingerir(politica);const quantidade=filhos.size;ingerir(politica);assert.equal(filhos.size,quantidade);
const id=[...filhos.keys()][0],pai=expandir(id,{tenant:"A"},2);
assert.ok(pai.texto.includes("Exceção"));
assert.throws(()=>expandir(id,{tenant:"B"},2),/SEM_PERMISSAO/);
assert.throws(()=>expandir(id,{tenant:"A"},1),/VERSAO_INCOMPATIVEL/);
filhos.set("quebrado",{parentId:"inexistente",tenant:"A",versao:2});
assert.throws(()=>expandir("quebrado",{tenant:"A"},2),/PAI_AUSENTE/);filhos.delete("quebrado");
const semOverlap=porTamanho(pai.texto,25,0),comOverlap=porTamanho(pai.texto,25,8);
assert.ok(comOverlap.join("").length>=semOverlap.join("").length);
// Regra e exceção ficam no mesmo pai, mesmo se uma janela pequena perde a relação.
const evidenciaMinima=["confirmação","análise manual"];
const suficiente=texto=>evidenciaMinima.every(x=>texto.includes(x));
assert.ok(suficiente(pai.texto));assert.equal(suficiente("Acesso após confirmação."),false);
const perguntas=[{id:"q1",precisa:"confirmação"},{id:"q2",precisa:"análise manual"}];
const avaliacao=perguntas.map(q=>({id:q.id,sustentada:pai.texto.includes(q.precisa),origem:pai.id}));
assert.ok(avaliacao.every(x=>x.sustentada));
console.log({status:"aprovado",trechosEstruturados:quantidade,
semOverlap:semOverlap.length,comOverlap:comOverlap.length,avaliacao});Como conferir seu resultado
- Regra e exceção permanecem recuperáveis.
- Vínculos pai respeitam versão e escopo.
- Ingestão repetida não cria duplicatas sem controle.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Preservar documento/versão/tenant.
- Relacionar chunk e pai.
Cláusula: prazo 20 dias; parágrafo seguinte perecíveis 2 dias. Chunk só recupera 20. Proponha estratégia.
Conferir raciocínio e critérios de domínio
Resposta 20 para perecível omite exceção decisiva.
Pai/estrutura deve conservar regra/exceção e origem compatível.
Overlap aumenta duplicação e não garante exceção distante; medir na pergunta.
Evidências para autoavaliação ou revisão por pares
- Evidência: Resposta 20 para perecível omite exceção decisiva.
- Integridade: Pai/estrutura deve conservar regra/exceção e origem compatível.
- Unidade: Overlap aumenta duplicação e não garante exceção distante; medir na pergunta.
Um erro frequente
Mais overlap sempre corrige ingestão.
Overlap não repara parsing, versão ou vínculos quebrados.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. Loader garante extração correta?
Não.
Conexão com a fonte e preservação de significado são verificações diferentes.
2. Mais overlap sempre melhora?
3. Pai recuperado pode ignorar filtro de escopo?
Não.
A autorização deve ser preservada na expansão de contexto.
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Document loader integrations
LangChain • consulta: 2026-10-06
FundamentosParsing e carga de documentos de formatos diferentes antes de indexar.
Limites: Documentação dinâmica; fixar a versão usada no laboratório e conferir compatibilidade antes de executar.
- OpenAI Retrieval
OpenAI • consulta: 2026-10-06
OpenAIIngestion, chunking/overlap, metadata/filtros, ranking e reescrita de consultas em vector stores.
Limites: Implementação gerenciada OpenAI; defaults não são melhores escolhas universais para pgvector.
- Text splitter integrations
LangChain • consulta: 2026-10-06
FundamentosDivisão de documentos em chunks por caracteres, tokens e estrutura.
Limites: Chunk size e overlap são hiperparâmetros a avaliar; parser e OCR podem precisar bibliotecas específicas.
- Qdrant Points
Qdrant • consulta: 2026-10-06
FundamentosPontos com vetores, IDs, payloads e operações de armazenamento.
Limites: Documentação dinâmica; fixar a versão usada no laboratório e conferir compatibilidade antes de executar.
- LangChain ParentDocumentRetriever
LangChain • consulta: 2026-10-06
FundamentosIndexar chunks pequenos e recuperar documentos/pais maiores para preservar contexto.
Limites: Referência do pacote langchain-classic; consulta web recusou content-type, página foi obtida por HTTP 200 e conteúdo examinado via Invoke-WebRequest.