Bases técnicas costumam falhar no RAG por um motivo menos vistoso que o modelo escolhido: a ingestão destrói a estrutura do documento. Quando um divisor corta uma função no meio, separa um endpoint do schema de resposta ou mistura exemplos de versões diferentes, o mecanismo de recuperação pode encontrar palavras relevantes sem encontrar o contexto necessário para responder.
Chunking por sintaxe trata esse problema usando a estrutura do conteúdo como sinal principal. Em vez de dividir tudo a cada quantidade fixa de caracteres, o pipeline identifica blocos como funções, classes, endpoints, schemas, tabelas e seções de referência. O objetivo não é criar chunks sempre pequenos. É manter unidades que façam sentido para uma pergunta e ainda caibam no contexto enviado ao modelo.
A técnica não elimina alucinações nem substitui avaliação. Ela melhora a evidência disponível para o modelo. Para chegar a um sistema confiável, combine segmentação estrutural, metadados, recuperação em camadas e validação da resposta.
Estratégia de ingestão de dados
Comece separando os tipos de fonte. Código, documentação conceitual, referência de API, exemplos de requisição e notas de versão têm estruturas e padrões de consulta diferentes. Um único algoritmo de chunking para todos esses materiais tende a produzir unidades inconsistentes.
Na documentação em Markdown, preserve a hierarquia de títulos. Uma seção deve carregar o caminho de seus títulos pai, por exemplo, produto, autenticação e criação de token. Esse caminho funciona como contexto adicional quando o texto da seção é recuperado isoladamente.
Para código, use um parser da linguagem sempre que houver uma gramática disponível. A unidade principal pode ser uma função, método, classe ou bloco de configuração. O parser permite identificar início e fim do nó sem depender de contagem de caracteres. Em linguagens ou formatos sem parser adequado, use uma combinação de delimitadores confiáveis, indentação e regras específicas do formato, deixando casos ambíguos para revisão ou fallback.
Na documentação de APIs, trate cada endpoint como uma unidade composta. O método HTTP, o caminho, os parâmetros, as regras de autenticação, o corpo da requisição, o schema de resposta, os códigos de erro e os exemplos devem permanecer relacionados. Se esse bloco ficar grande demais, divida por subestrutura, mas repita no metadata o método e o caminho em cada parte.
Uma estratégia prática é aplicar esta sequência:
- Detecte o formato do arquivo e a linguagem.
- Extraia a estrutura sintática ou hierárquica.
- Crie um chunk para cada unidade semântica.
- Acrescente contexto dos pais, como nome da classe ou caminho da seção.
- Divida apenas unidades que ultrapassem o limite definido.
- Gere metadados que permitam filtrar e reconstruir o contexto.
O limite de tamanho deve ser uma restrição, não o critério primário. Uma função curta deve permanecer inteira mesmo que use poucos tokens. Uma classe extensa pode exigir divisão por métodos, mas cada parte deve informar a classe de origem e as relações relevantes. Sobreposição entre chunks também precisa ser aplicada com cuidado. Em texto corrido, ela pode preservar continuidade. Em código, duplicar trechos pode aumentar ruído e custo. Prefira relações estruturais, como nome da classe, assinatura e imports relevantes, antes de copiar linhas arbitrariamente.
Registre a versão do documento, a fonte, a linguagem, o caminho no repositório, o símbolo principal, a seção pai e a data de ingestão. Esses campos ajudam a evitar que uma resposta combine uma versão antiga de uma função com uma referência atualizada de endpoint.
Configuração do vetor store
O vetor store deve guardar mais que o embedding e o texto. Cada registro precisa ter um identificador estável, o conteúdo do chunk e metadados suficientes para filtrar, ordenar e buscar unidades relacionadas.
Um conjunto inicial de metadados pode incluir source, document_version, language, content_type, section_path, symbol, http_method, endpoint_path, parent_id e chunk_index. Use os campos disponíveis de acordo com a fonte. Um endpoint não precisa de symbol, enquanto uma função não precisa de http_method.
Mantenha o texto usado no embedding legível e autocontido. Em um chunk de função, inclua a assinatura, o nome da classe e a linguagem. Em um schema, inclua o nome do recurso e a relação com o endpoint. Não transforme todos os metadados em texto repetido sem necessidade, pois isso pode aumentar tokens e fazer termos estruturais dominarem a representação.
A busca vetorial é útil para perguntas conceituais, mas não deve ser a única forma de localizar código. Consultas com nomes exatos de funções, códigos de erro, caminhos de endpoint e propriedades de schema se beneficiam de busca lexical. Uma arquitetura híbrida combina correspondência textual com similaridade semântica e depois aplica filtros estruturais.
Escolha o modelo de embeddings considerando o idioma, o tipo de conteúdo e o orçamento de inferência. Embeddings não são gratuitos em sistemas operacionais, mesmo quando o modelo pode ser executado localmente. Há custo de processamento, armazenamento, atualização e latência. O tamanho do vetor também afeta o armazenamento e a consulta. Teste com perguntas reais antes de decidir pela maior representação disponível.
Crie uma política explícita para atualização. Quando um arquivo muda, reprocese os chunks afetados e remova ou marque como inativos os registros antigos. Sem controle de versão, o sistema pode recuperar duas implementações incompatíveis. Para APIs, filtre por versão quando a pergunta indicar esse contexto. Quando não indicar, a aplicação deve declarar qual versão foi usada ou pedir esclarecimento, em vez de misturar resultados.
Retrieval estratificado
Retrieval estratificado significa recuperar evidência em etapas, usando primeiro a intenção e depois a estrutura do documento. Essa abordagem evita depender de uma única busca ampla que retorna vários trechos parecidos, mas incompletos.
Na primeira camada, classifique a pergunta de forma simples. Ela pede uma explicação conceitual, a localização de uma função, o uso de um endpoint, a comparação entre versões ou a solução de um erro? Essa classificação pode ser feita por regras, por um modelo pequeno ou pelo próprio serviço de aplicação. Não é necessário usar um modelo caro para toda decisão de roteamento.
Na segunda camada, aplique filtros disponíveis. Se a pergunta menciona uma linguagem, versão, serviço, método HTTP ou caminho, use esses sinais para reduzir o espaço de busca. Filtros não devem ser aplicados de modo rígido quando a extração for incerta. Uma alternativa é rodar uma busca filtrada e outra mais ampla, comparando os resultados.
Na terceira camada, faça a recuperação híbrida. Combine busca lexical para identificadores exatos com busca vetorial para paráfrases e conceitos. Depois, use um reranker ou uma regra de pontuação para priorizar chunks que contenham a unidade completa, a versão correta e os termos da consulta. O reranking adiciona latência e custo, então vale medir se o ganho justifica seu uso em cada tipo de pergunta.
Na quarta camada, expanda o contexto por relações. Se o resultado principal for um método, recupere a classe, a interface implementada ou os tipos usados apenas quando forem relevantes. Se for um endpoint, recupere o schema, as regras de autenticação e os erros associados. Essa expansão deve ser limitada. Enviar toda a árvore de dependências ao modelo aumenta custo, latência e a chance de distração.
Uma regra útil é separar evidência primária de evidência auxiliar. A definição do endpoint ou da função é primária. Um exemplo de uso, uma explicação conceitual e uma nota de versão podem ser auxiliares. No prompt, indique essa diferença e peça ao modelo para não tratar exemplos como contrato normativo quando houver conflito.
O limite de contexto do modelo continua sendo uma restrição concreta. Mesmo quando há espaço suficiente para muitos tokens, mais contexto não significa mais precisão. Contexto irrelevante compete com a evidência principal. Registre quantos chunks foram recuperados, quantos tokens foram enviados e quais fontes sustentaram a resposta. Esses dados ajudam a ajustar o pipeline sem depender de impressão subjetiva.
Validação da resposta
A última etapa é verificar se o sistema respondeu com base na evidência correta. Avalie o pipeline com um conjunto de perguntas reais, incluindo consultas sobre funções, parâmetros, erros, versões e casos em que a informação não existe. Para cada pergunta, registre se o chunk correto foi recuperado e se a resposta respeitou esse material. Separar qualidade de retrieval da qualidade de geração mostra onde está o problema.
Inclua testes de integridade estrutural. Uma função recuperada deve conter sua assinatura e corpo relevante. Um endpoint deve manter método, caminho e schema compatíveis. Um chunk dividido não pode perder a indicação de que é continuação. Também teste arquivos atualizados, símbolos renomeados e documentos removidos.
Na geração, exija citações internas ou referências aos documentos recuperados. A resposta deve distinguir fato encontrado, inferência e informação ausente. Quando os trechos forem insuficientes ou conflitantes, o comportamento correto é declarar a limitação e pedir contexto, não completar a lacuna com uma suposição plausível.
Acompanhe métricas de recuperação, como cobertura do chunk esperado, precisão dos primeiros resultados e taxa de respostas sem evidência suficiente. Monitore também latência, tokens enviados e custo por consulta. Um chunking melhor pode reduzir chamadas repetidas e contexto desperdiçado, mas a análise precisa considerar o custo adicional de parsing, reranking e reindexação.
Para colocar a técnica em prática, escolha um conjunto pequeno de documentos, crie uma versão por tamanho fixo como referência e compare com a segmentação por sintaxe. Use as mesmas perguntas, o mesmo modelo e a mesma regra de geração. Se a abordagem estrutural recuperar blocos mais completos e reduzir respostas sem suporte, você terá evidência para expandir a ingestão. Caso contrário, revise o parser, os metadados ou a estratégia de retrieval antes de atribuir o resultado ao modelo.
Chunking por sintaxe é uma decisão de arquitetura, não um ajuste isolado de configuração. A unidade correta depende do tipo de documento, da forma das perguntas e das relações que precisam permanecer intactas. O ganho aparece quando ingestão, armazenamento, recuperação e validação tratam essa estrutura como parte do conhecimento, em vez de enxergarem a documentação apenas como uma sequência de caracteres.
