Uma resposta sobre seus documentos é tão boa quanto o texto a partir do qual foi construída, e quando você cola arquivos inteiros em um chat, não pode saber qual parte o modelo realmente usou. GroupDocs.Search.Mcp, executado localmente em Docker, fornece ao Claude Desktop, Cursor ou Copilot um recurso diferente: get_text_fragments retorna apenas as passagens que correspondem a uma consulta, com algumas palavras de contexto e o arquivo de origem, de modo que o agente responde a partir de citações:

O que meus contratos dizem sobre penalidades? Cite as passagens, com contexto suficiente para entender cada uma.

A versão passo a passo com configuração e solução de problemas está na documentação: Como obter as passagens correspondentes em vez de ler arquivos inteiros.

Por que as respostas se afastam dos documentos?

Porque a janela de contexto é um orçamento, e documentos inteiros o consomem de forma ineficiente. Uma pergunta sobre penalidades pode precisar de apenas três frases de cinquenta páginas. Cole as cinquenta páginas e o modelo tem que encontrar as três frases por conta própria, entre todo o resto, e então mantê‑las enquanto escreve. Contextos longos são resumidos, o material inicial perde peso, e a resposta passa a se basear no senso geral do modelo sobre o que os contratos costumam dizer, em vez do que os seus dizem. A indústria chama a disciplina de gerenciar isso de engenharia de contexto; a forma mais simples é não carregar texto que você não precisa.

Como é um fragmento?

O índice já contém o texto de cada documento, portanto o servidor pode extrair a passagem ao redor de cada correspondência. Estas são respostas reais do nosso teste, contra cinco contratos sintéticos. Os padrões, oito palavras de cada lado, fornecem uma frase:

-> get_text_fragments {"query":"penalty","indexName":"contracts"}
<- === contracts/acme-master-services-agreement.pdf (1 occurrence(s)) ===
     [content] …before the end of the Term, a termination penalty of
   three monthly fees applies, payable within 30…

Vinte palavras de cada lado fornecem a cláusula completa:

-> get_text_fragments {"query":"penalty","indexName":"contracts",
     "termsBefore":20,"termsAfter":20,"maxFragmentsPerDocument":1}
<- === contracts/acme-master-services-agreement.pdf (1 occurrence(s)) ===
     …convenience on 90 days written notice.
   12.3 If the Client terminates before the end of the Term, a termination
   penalty of three monthly fees applies, payable within 30 days of the
   termination date.
   14.2 Force majeure: neither party is…

termsBefore e termsAfter são um ajuste: pequeno para “quais arquivos e aproximadamente onde”, grande para “cite a cláusula”. maxFragmentsPerDocument e maxDocuments limitam o tamanho da resposta, de modo que uma palavra que ocorre duzentas vezes não inunde o contexto.

O orçamento, lado a lado

Lendo os arquivos                        Pesquisando o índice
-------------------------------------    -------------------------------------
agente abre cada documento               pesquisa: quais arquivos correspondem (JSON)
  o contexto cresce com o corpus          get_text_fragments: as passagens
  arquivos longos deslocam a pergunta        (~8 palavras de cada lado, por arquivo)
  repetido para cada pergunta            resposta cita arquivo + passagem
                                         o índice é reutilizado na próxima vez

A diferença aumenta com o corpus. Para três arquivos curtos quase não importa. Para uma pasta de contratos longos, relatórios e e‑mails, os fragmentos para uma pergunta são algumas centenas de palavras, em comparação com o texto completo de cada documento candidato.

Quando as palavras diferem

A pesquisa em texto completo corresponde palavras, o que é um recurso para fundamentação (cada ocorrência é explicável) e um limite para recall (um sinônimo é uma falha). O trabalho do agente é tentar variantes, e ele pode ver o que cada variante realmente correspondeu:

-> search {"query":"renewal OR renews","indexName":"contracts"}
<- umbrella-office-lease.pdf, terms ["renewal", "renews"]

-> search {"query":"renewl","indexName":"contracts","fuzzy":true}
<- umbrella-office-lease.pdf, terms ["renewal", "renews", "rent"]

A correspondência difusa corrigiu um erro ortográfico e também trouxe rent. Como a resposta lista os termos que correspondeu, um agente, ou você, pode ver o excesso de correspondência em vez de confiar nele. Essa transparência é o que “fundamentado” deve significar: não apenas “a resposta cita uma fonte”, mas “você pode ver como a fonte foi encontrada”.

Como é uma resposta fundamentada

Peça citações, e a resposta chega em um formato que você pode verificar de relance:

Dois contratos contêm uma penalidade de rescisão. Acme MSA, cláusula 12.3: “uma penalidade de rescisão de três taxas mensais se aplica, pagável dentro de 30 dias da data de rescisão.” Contrato de consultoria da Globex, seção 9: “o Cliente paga 50 por cento das taxas restantes para a fase atual.” O NDA da Initech menciona rescisão e penalidade, mas afirma que não há penalidade.

Se um resumo interpretar erroneamente uma citação, o erro fica logo ao lado da citação.

Limites honestos

  • No modo de avaliação, um índice contém no máximo 100 documentos e uma pesquisa retorna no máximo 10. O modo de avaliação também adiciona uma linha “Evaluation only…” ao texto indexado de alguns formatos, que pode aparecer nos fragmentos; licencie o servidor e reconstrua o índice para removê‑la. Chame get_license_status primeiro.
  • O contexto do fragmento é contado em palavras, não em frases, portanto uma passagem pode começar no meio de uma frase; aumente termsBefore quando for importante.
  • Sem OCR: digitalizações sem camada de texto não têm passagens para retornar.
  • Apenas Docker; no Linux adicione --user "$(id -u):$(id -g)".

Perguntas Frequentes

Como faço para que o Claude cite fontes dos meus documentos?
Forneça-lhe uma ferramenta que retorne o texto da fonte com o nome do arquivo. get_text_fragments faz exatamente isso, e uma instrução como “cite a passagem e seu arquivo” faz disso um hábito.

Isso reduz o uso de tokens?
Isso evita carregar documentos inteiros para responder a uma pergunta: o agente lê apenas as passagens correspondentes. Quanto isso economiza depende do tamanho dos seus arquivos.

O agente ainda pode ler um arquivo inteiro quando necessário?
Sim, com suas próprias ferramentas de arquivo. Fragmentos servem para encontrar e citar; leia o arquivo inteiro quando a passagem não for suficiente.

Aprofunde-se