Chunking com Contexto

Intenção

Dividir documentos seguindo sua estrutura (seções, cláusulas, tabelas) e anexar a cada pedaço o contexto de onde ele veio: documento, seção, data e uma frase que situa o trecho. Serve para RAGs em que os pedaços, sozinhos, perdem o sentido.

Problema

Eduardo mantém a busca do manual interno de uma operadora de saúde. Os documentos foram cortados a cada 500 tokens, sem olhar a estrutura. Um dos pedaços diz apenas:

...o prazo é de 21 dias úteis, contados a partir da solicitação, e pode ser
prorrogado uma vez mediante justificativa. Nos casos previstos no item 3.2...

Prazo de quê? Para quem? De qual versão do manual? A busca acha esse trecho para a pergunta “qual o prazo de autorização de cirurgia eletiva?”, mas também para “qual o prazo de reembolso?”, porque o trecho não diz de que assunto trata. O modelo responde com confiança e às vezes erra o assunto.

O corte cego também separou uma tabela do seu título. As linhas com números de prazo ficaram num pedaço, o cabeçalho com as colunas (autorização, reembolso, recurso) ficou no pedaço anterior. O bot passou a citar “21” sem dizer de qual prazo.

Há ainda o item 3.2. Ele está em outro pedaço. Quem lê só o trecho acima não tem como saber o que o item autoriza. Na operadora, isso mistura regras da ANS com regras internas do plano.

A pergunta que este padrão responde: como dividir documentos de modo que cada pedaço seja compreensível e encontrável sozinho?

Solução

Duas mudanças no momento da indexação:

• Dividir pela estrutura: usar títulos, seções, cláusulas, itens de lista e tabelas como fronteiras. Um pedaço nunca começa no meio de uma frase nem separa uma tabela do seu cabeçalho. Tamanho máximo existe, mas é o limite, não a regra.
• Anexar contexto: cada pedaço ganha um cabeçalho com o caminho (documento, capítulo, seção), a data ou versão e, opcionalmente, uma frase gerada por um modelo que situa o trecho (“Este trecho trata do prazo de autorização de cirurgias eletivas para planos individuais”).

O cabeçalho entra no texto indexado (para a busca) e no texto enviado ao modelo (para a resposta e a citação).

A Anthropic descreveu essa ideia no texto Contextual Retrieval (setembro de 2024). Antes de indexar, um modelo lê o documento e o pedaço e escreve uma frase que situa o trecho. Essa frase entra no texto que vai para o embedding e para a busca por palavra-chave.

Exemplo trabalhado

Pegue o trecho do prazo e o documento de onde ele saiu. Depois do corte cego, o índice guarda só o miolo. Depois deste padrão, o mesmo miolo ganha um cabeçalho:

[Manual do Beneficiário | Autorizações | 4.1 Cirurgias eletivas | v7, vigência 2026-03]
Este trecho trata do prazo de autorização de cirurgias eletivas em planos individuais.
O prazo é de 21 dias úteis, contados a partir da solicitação, e pode ser
prorrogado uma vez mediante justificativa. Nos casos previstos no item 3.2
(urgência e emergência, ver seção 4.3), o prazo não se aplica.

Três coisas mudaram, e cada uma ensina uma lição.

1. O caminho. “Autorizações > 4.1 Cirurgias eletivas” entra no embedding e no BM25. A pergunta sobre reembolso deixa de competir com a mesma similaridade.
2. A frase de contexto. Ela traduz o trecho vago para o vocabulário da pergunta (“autorização”, “cirurgia eletiva”, “plano individual”).
3. A cláusula vizinha. Se a seção 4.1 cabe no limite, o item 3.2 viaja junto. Se não cabe, o cabeçalho ainda aponta para 4.3, e a citação não finge que o trecho é completo.

A conta de tokens, com números ilustrativos. Suponha 800 tokens de miolo e 80 de cabeçalho. Em 2.000 pedaços, o índice engorda uns 160 mil tokens. Na consulta, cinco pedaços passam de 4.000 para 4.400 tokens. O custo extra está na ingestão (uma chamada pequena por pedaço, com o documento em cache), não na pergunta.

O paper “Lost in the Middle” (Liu et al., 2023) mostra que modelos usam melhor o começo e o fim do contexto do que o meio. Colocar o caminho no início do pedaço ajuda duas vezes: a busca acha o assunto certo, e o modelo lê primeiro de onde o trecho veio.

Estrutura

flowchart LR
  D(["1. Documento"]):::io --> P["2. Analisar a estrutura"]:::tool
  P --> S["3. Dividir por seção e cláusula"]:::tool
  S --> C(["4. Gerar frase de contexto"]):::llm
  C --> H["5. Montar cabeçalho e trecho"]:::tool
  H --> I[("6. Índice")]:::store

1. O documento chega em PDF, HTML ou texto.
2. Um parser identifica títulos, seções, listas e tabelas.
3. A divisão segue essa estrutura, respeitando um tamanho máximo.
4. Um modelo pequeno lê o documento e o trecho e escreve uma frase que situa o trecho.
5. Cada pedaço vira cabeçalho (caminho, versão, frase de contexto) mais o texto original.
6. O pedaço completo é indexado para busca lexical e vetorial.

Pseudocódigo

schema ChunkContext { summary: string /* uma frase */ }

function index_document(doc):
    tree = parse_structure(doc)                         # 2. títulos, seções, tabelas
    for section in tree.leaves(max_tokens=800):         # 3. pela estrutura
        path = " > ".join(section.ancestors_titles())
        ctx = llm(CONTEXT_PROMPT, doc.summary, section.text, model="small") -> ChunkContext   # 4
        header = f"[{doc.title} | {path} | versão {doc.version}] {ctx.summary}"
        index.add(id=section.id, text=header + "\n" + section.text,
                  metadata={doc: doc.id, path: path, version: doc.version})               # 5 e 6

Cenários reais

• Chat com a base de conhecimento interna. Políticas divididas por seção, com o caminho e a versão em cada trecho. A busca para “prazo de reembolso” não traz mais o prazo de autorização.
• Assistente jurídico. Contratos divididos por cláusula e item, com o número da cláusula no cabeçalho, para citação exata. Em Mata v. Avianca (2023), advogados protocolaram decisões inventadas pelo ChatGPT. Um índice que guarda o número da cláusula não inventa a cláusula, mas só ajuda se o trecho certo for o que a busca devolve.
• Manuais da Receita e da ANS. Normas brasileiras citam umas às outras (“nos termos do art. 12”). Sem o caminho no pedaço, o modelo trata a remissão como se fosse a regra.

Aplicabilidade

• Documentos longos e estruturados (manuais, políticas, contratos, normas).
• Trechos que, sozinhos, usam termos vagos (“o prazo”, “neste caso”).
• Várias versões ou vários documentos parecidos no mesmo índice.
• Respostas que precisam citar a seção exata.

Quando não usar

• Documentos curtos, que cabem num pedaço só. Título e versão no começo bastam; cortar só cria fronteiras artificiais.
• Conteúdo sem estrutura (transcrições de conversa). Divida por tema ou por janelas com sobreposição.
• O material cabe inteiro no contexto. Veja RAG Desnecessário.

Como implementar

1. Olhe os documentos reais e identifique as marcas de estrutura (títulos numerados, cláusulas, tabelas).
2. Escreva o parser por tipo de documento; converta PDF para um formato com estrutura antes.
3. Defina o tamanho máximo e o que fazer com seções maiores (dividir por parágrafo, mantendo o título).
4. Monte o cabeçalho com caminho e versão.
5. Gere a frase de contexto com um modelo pequeno, com cache de prompt para o documento inteiro.
6. Reindexe e compare recall e precisão no eval de busca.
7. Use o caminho do cabeçalho nas citações da resposta.

Armadilhas comuns

• Cortar por caracteres e chamar de estrutural. Se a fronteira ignora o título da tabela, você só mudou o tamanho.
• Gerar a frase só com o pedaço. Sem o documento, o modelo escreve “este trecho fala de um prazo”, tão vago quanto o miolo. A chamada precisa ver o caminho e um resumo do documento.
• Deixar versões revogadas no índice. O cabeçalho com “v6” não impede a busca de devolver o v6. Filtre por vigência na consulta e remova o documento antigo na reindexação.
• Confiar na frase e relaxar o parser. Uma frase errada envenena o embedding. Amostra de pedaços na ingestão pega isso antes do usuário.

Variações

• Só cabeçalho estrutural. Caminho e versão, sem frase gerada. Barato e já resolve boa parte.
• Frase de contexto gerada. Melhora a busca para trechos vagos; custa uma chamada pequena por pedaço na indexação.
• Pedaços em níveis. Pedaços pequenos para a busca, e a seção inteira (pai) enviada ao modelo quando o pequeno é encontrado.
• Tabelas como pedaços próprios. Cada tabela vira um pedaço, com título e legenda, em formato de texto.

Comece pelo cabeçalho estrutural. Só ligue a frase gerada se o eval de confusão de assunto continuar falhando.

Custo, latência e falhas

Como avaliar

• Recall e precisão da busca antes e depois, no mesmo eval.
• Confusão de assunto: perguntas parecidas sobre temas diferentes (“prazo de reembolso” e “prazo de autorização”).
• Citações: a seção citada na resposta é a certa.
• Fronteira de tabela e cláusula: casos em que o corte cego partia um bloco.

{ "question": "Qual o prazo de autorização de cirurgia eletiva?", "relevant": ["manual-v7#autorizacoes-4.1"], "not_relevant": ["manual-v7#reembolso-2.3"] }

Monte o par de perguntas gêmeas de propósito. Se o trecho relevante do reembolso não está no top 5 da pergunta de autorização, o cabeçalho está funcionando.

Em produção

• Registro do caminho e da versão dos trechos usados em cada resposta.
• Rotina de reindexação quando um documento muda, removendo versões antigas.
• Amostra de pedaços para conferir parser e frases de contexto.
• Alerta para taxa de caminho vazio na ingestão: parser quebrado depois de um novo tipo de PDF.

Segurança

O pedaço indexado pode carregar dados pessoais (nome de beneficiário, número de carteirinha). Na versão brasileira, isso cai na LGPD: o índice é mais um lugar onde esses dados moram. Não mande documentos com dados pessoais para o modelo da frase de contexto se a política da empresa não permitir. Nesses casos, fique no cabeçalho estrutural, gerado só com título e seção.

Prós e contras

Relações

• Padrão de destino: RAG. Chunking com contexto é a etapa de ingestão que faz a busca devolver o trecho certo.
• Vizinhos: Busca Híbrida junta palavra-chave e embedding, o que aproveita bem o caminho no cabeçalho. Embeddings explica por que um trecho vago vira um vetor vago.
• Quando não se aplica: RAG Desnecessário, se o material cabe inteiro.

Código

As duas abas dividem um documento pelos títulos e montam o cabeçalho com o caminho; a aba Python também gera a frase de contexto, com o documento inteiro em cache.

import re

import anthropic

client = anthropic.Anthropic()


def split_by_headings(markdown: str, max_chars: int = 3000) -> list[dict]:  # 2 e 3
    chunks, path = [], []
    for block in re.split(r"\n(?=#{1,4} )", markdown):
        m = re.match(r"(#{1,4}) (.+)", block)
        if m:
            level = len(m.group(1))
            path = path[: level - 1] + [m.group(2).strip()]
        for i in range(0, len(block), max_chars):  # seção grande: divide mantendo o caminho
            chunks.append({"path": " > ".join(path), "text": block[i : i + max_chars]})
    return chunks


def situate(doc_text: str, chunk_text: str) -> str:  # 4
    reply = client.messages.create(
        model="claude-haiku-4-5", max_tokens=100,
        system=[{"type": "text", "text": f"<documento>\n{doc_text}\n</documento>",
                 "cache_control": {"type": "ephemeral"}}],  # documento cacheado entre os pedaços
        messages=[{"role": "user", "content": "Em uma frase, diga de que assunto e caso trata este trecho, "
                                              f"para ajudar a encontrá-lo numa busca.\n<trecho>{chunk_text}</trecho>"}],
    )
    return reply.content[0].text.strip()


def index_document(doc: dict) -> list[dict]:
    out = []
    for c in split_by_headings(doc["markdown"]):
        header = f"[{doc['title']} | {c['path']} | versão {doc['version']}] {situate(doc['markdown'], c['text'])}"
        out.append({"id": f"{doc['id']}#{c['path']}", "text": f"{header}\n{c['text']}", "path": c["path"]})  # 5
    return out

type Chunk = { id: string; path: string; text: string };

export function chunkByHeadings(doc: { id: string; title: string; version: string; markdown: string }, maxChars = 3000): Chunk[] {
  const chunks: Chunk[] = [];
  let path: string[] = [];
  for (const block of doc.markdown.split(/\n(?=#{1,4} )/)) {
    const m = block.match(/^(#{1,4}) (.+)/);
    if (m) path = [...path.slice(0, m[1].length - 1), m[2].trim()];
    const p = path.join(" > ");
    const header = `[${doc.title} | ${p} | versão ${doc.version}]`; // 5. cabeçalho estrutural
    for (let i = 0; i < block.length; i += maxChars) {
      chunks.push({ id: `${doc.id}#${p}#${i}`, path: p, text: `${header}\n${block.slice(i, i + maxChars)}` });
    }
  }
  return chunks;
}

Teste seu entendimento