Renato Augusto Tavares
English

Documentação escrita para ser recuperada

Um sistema que responde perguntas de suporte sobre a documentação de um ERP. A ideia central é simples: se quem escreve a documentação é um modelo de linguagem seguindo um contrato, o mecanismo de busca pode contar com a estrutura que o contrato garante.

O contrato de documentação

O corpus é a documentação de um ERP brasileiro com cerca de 270 telas: 473 documentos em português, de telas, relatórios, regras de negócio, integrações e estruturas de dados. Ela é gerada por um modelo de linguagem a partir do código-fonte do produto, e regenerada por integração contínua a cada versão.

O modelo escreve sob um contrato: todo documento tem os mesmos campos de cabeçalho, as mensagens de erro aparecem em tabelas com o texto exato que o sistema exibe, as permissões têm formato fixo, e há mais de mil pares de pergunta e resposta frequentes. O contrato existe para o leitor humano, mas dá ao buscador algo raro em documentação: estrutura em que se pode confiar.

A busca

Tudo roda em uma única instância de PostgreSQL, com busca vetorial (pgvector, índice HNSW) e busca textual lado a lado. Os documentos são divididos em seis tipos de trecho, cerca de 39,7 mil no total: seções, linhas de tabela, mensagens, permissões, perguntas frequentes e resumos.

  • Atalhos de correspondência exata. Se a pergunta contém uma mensagem de erro ou um nome de permissão que existe nas tabelas, a resposta vem delas, sem passar pela busca semântica.
  • Busca híbrida. Cinquenta candidatos da busca densa e cinquenta da lexical, combinados por fusão de postos recíprocos.
  • Reordenação por um modelo cross-encoder.
  • Expansão para a seção-mãe, para que a resposta seja escrita com o contexto inteiro e não com um fragmento.

Como medir

O mapa da documentação fornece pares de pergunta e documento correto, separados em um conjunto de desenvolvimento (929 perguntas) e um de teste (214), que não é usado para ajustar nada. Como essas perguntas reutilizam o vocabulário dos documentos, há um terceiro conjunto, de 214 paráfrases em linguagem coloquial, e conjuntos operacionais com mensagens de erro coladas.

Cada componente do pipeline foi removido em uma ablação, e 23 modelos de embedding foram comparados sob o mesmo protocolo. Todos os números do manuscrito estão mapeados, em um arquivo do repositório, para o arquivo e o campo de onde saíram, e um script confere os que podem ser conferidos.

Recall@10 de 24 configurações de embedding: perguntas literais contra paráfrasesNas perguntas literais, todos os modelos ficam entre 0,98 e 1,00. Nas paráfrases, o recall varia de 0,52 a 0,89.0,50,60,70,80,91,0 paráfrasesperguntas literais gte-multilingual-basegte-multilingual-base: recall@10 de 0,888 nas paráfrasesgte-multilingual-base: recall@10 de 0,995 nas perguntas literaisvoyage-3-largevoyage-3-large: recall@10 de 0,888 nas paráfrasesvoyage-3-large: recall@10 de 0,995 nas perguntas literaispipeline em produçãopipeline em produção: recall@10 de 0,874 nas paráfrasespipeline em produção: recall@10 de 1,000 nas perguntas literaisocten-embedding-0.6bocten-embedding-0.6b: recall@10 de 0,860 nas paráfrasesocten-embedding-0.6b: recall@10 de 0,995 nas perguntas literaisvoyage-context-4voyage-context-4: recall@10 de 0,860 nas paráfrasesvoyage-context-4: recall@10 de 1,000 nas perguntas literaisvoyage-4-largevoyage-4-large: recall@10 de 0,855 nas paráfrasesvoyage-4-large: recall@10 de 0,995 nas perguntas literaisgemini-embedding-2gemini-embedding-2: recall@10 de 0,846 nas paráfrasesgemini-embedding-2: recall@10 de 0,986 nas perguntas literaisgranite-embedding-311m-r2granite-embedding-311m-r2: recall@10 de 0,846 nas paráfrasesgranite-embedding-311m-r2: recall@10 de 0,995 nas perguntas literaisserafim-900m-irserafim-900m-ir: recall@10 de 0,846 nas paráfrasesserafim-900m-ir: recall@10 de 1,000 nas perguntas literaiskalm-embedding-mini-v1.5kalm-embedding-mini-v1.5: recall@10 de 0,827 nas paráfraseskalm-embedding-mini-v1.5: recall@10 de 0,995 nas perguntas literaisqwen3-embedding-0.6bqwen3-embedding-0.6b: recall@10 de 0,818 nas paráfrasesqwen3-embedding-0.6b: recall@10 de 0,995 nas perguntas literaisqwen3-embedding-4bqwen3-embedding-4b: recall@10 de 0,799 nas paráfrasesqwen3-embedding-4b: recall@10 de 0,991 nas perguntas literaismultilingual-e5-large-instructmultilingual-e5-large-instruct: recall@10 de 0,794 nas paráfrasesmultilingual-e5-large-instruct: recall@10 de 0,995 nas perguntas literaisembeddinggemma-300membeddinggemma-300m: recall@10 de 0,790 nas paráfrasesembeddinggemma-300m: recall@10 de 0,995 nas perguntas literaismultilingual-e5-basemultilingual-e5-base: recall@10 de 0,785 nas paráfrasesmultilingual-e5-base: recall@10 de 0,986 nas perguntas literaisgemini-embedding-001gemini-embedding-001: recall@10 de 0,766 nas paráfrasesgemini-embedding-001: recall@10 de 0,981 nas perguntas literaisbge-m3bge-m3: recall@10 de 0,748 nas paráfrasesbge-m3: recall@10 de 0,991 nas perguntas literaissnowflake-arctic-embed-l-v2.0snowflake-arctic-embed-l-v2.0: recall@10 de 0,743 nas paráfrasessnowflake-arctic-embed-l-v2.0: recall@10 de 0,981 nas perguntas literaisf2llm-v2-4bf2llm-v2-4b: recall@10 de 0,720 nas paráfrasesf2llm-v2-4b: recall@10 de 0,995 nas perguntas literaisjina-embeddings-v3jina-embeddings-v3: recall@10 de 0,715 nas paráfrasesjina-embeddings-v3: recall@10 de 0,986 nas perguntas literaisnomic-embed-text-v2-moenomic-embed-text-v2-moe: recall@10 de 0,710 nas paráfrasesnomic-embed-text-v2-moe: recall@10 de 0,981 nas perguntas literaismultilingual-e5-largemultilingual-e5-large: recall@10 de 0,701 nas paráfrasesmultilingual-e5-large: recall@10 de 0,986 nas perguntas literaisf2llm-v2-0.6bf2llm-v2-0.6b: recall@10 de 0,678 nas paráfrasesf2llm-v2-0.6b: recall@10 de 0,995 nas perguntas literaisparaphrase-multilingual-mpnetparaphrase-multilingual-mpnet: recall@10 de 0,519 nas paráfrasesparaphrase-multilingual-mpnet: recall@10 de 0,991 nas perguntas literais recall@10 (fração das perguntas cujo documento certo aparece entre os dez primeiros)
Figura 1. Recall@10 de 23 modelos de embedding e do pipeline em produção, com o mesmo reordenador. Nas perguntas literais (círculos vazados) todos parecem perfeitos; são as paráfrases (círculos cheios) que os separam. Um conjunto de teste que só repete o vocabulário dos documentos mediria quase nada. Dados: arquivo recall-por-modelo.csv do repositório público.

O que os números dizem

  • No conjunto de teste literal, o pipeline completo encontra o documento certo entre os dez primeiros em todas as 214 perguntas (recall@10 de 1,000; MRR de 0,927).
  • Nas paráfrases, o recall@10 cai para 0,874. É o número que descreve melhor o uso real.
  • A busca lexical sozinha vai muito bem nas perguntas literais (0,981) e desaba nas paráfrases (0,16). A busca densa sozinha perde o documento em 26 das 214 perguntas literais. Nenhuma das duas basta.
  • As tabelas de correspondência exata valem de 14 a 18 pontos de recall quando o usuário cola uma mensagem de erro: de 0,82 e 0,86 para 1,00.
  • A reescrita da pergunta por um modelo de linguagem, técnica comum em sistemas desse tipo, piorou o resultado: de 1,000 para algo entre 0,907 e 0,916 no conjunto literal, e de 0,874 para 0,855 nas paráfrases.

Limites

O repositório público contém o pacote de recuperação que está em produção, os conjuntos de referência, os resultados arquivados e um subconjunto de 30 documentos, suficiente para rodar a ingestão e a avaliação de ponta a ponta. Os outros 443 documentos e o texto integral do contrato pertencem ao fornecedor do ERP e não foram publicados; o nome do produto foi substituído por termos genéricos em todos os arquivos.

As 62 perguntas reais de clientes coletadas nos primeiros dias de uso não estão rotuladas e não entram em nenhuma métrica. O sistema foi medido em um corpus e em um idioma, e o manuscrito distingue três níveis de reprodutibilidade para dizer o que um leitor externo consegue refazer.