API de RAG para desenvolvedores: buscar documentos de qualquer aplicativo

Publicado em 2026-11-16 por ArduBot

O que uma API de recuperação deve retornar, como separar recuperação e geração, projetar permissões, paginação, rastreamento e testes.

Quer adicionar busca inteligente a um site, um bot ou uma automação, mas não quer reconstruir um motor de indexação em cada projeto. Uma API de RAG pode servir como camada comum: recebe uma pergunta, encontra evidências relevantes e retorna resultados que outra aplicação utiliza.

API de Recuperação não é o mesmo que chatbot

Uma API de recuperação retorna informações: fragmentos, documentos, metadados e referências. Um chatbot, além disso, interpreta a conversa, decide o que consultar, chama o modelo e redige a mensagem final. Separar ambas as responsabilidades permite trocar de modelo sem recriar a base documental.

Por exemplo, um mesmo índice de manuais pode alimentar um chat de suporte, um buscador interno e um agente por WhatsApp. Cada interface terá tom e regras distintas, mas deve partir dos mesmos documentos autorizados.

O que o serviço receberia e retornaria

Uma consulta precisa de um texto, um identificador de base autorizado e filtros opcionais como idioma, produto ou data. Um formato ilustrativo:

POST /v1/knowledge-bases/{id}/search
Authorization: Bearer <token>
Content-Type: application/json
{"query":"¿Cómo reiniciar el equipo X?","top_k":4,"filters":{"product":"X"}}
A resposta deveria conter results com document_id, chunk_id, text, source_url, page se existir, updated_at e uma pontuação cujo significado esteja documentado. Também convém incluir request_id para acompanhar falhas sem registrar dados sensíveis indiscriminadamente.

Estes endpoints são exemplos de design, não uma API que afirmamos disponível hoje na ArduMaker.

Decisões que afetam a qualidade

Filtros antes da busca: a autorização deve limitar o conjunto de documentos acessíveis; não basta ocultar resultados no final.

Busca híbrida quando agregar valor: os embeddings podem encontrar sinônimos, enquanto consultas léxicas ajudam com números de peça, códigos e nomes exatos.

Citações verificáveis: armazene a localização de cada fragmento. Uma referência genérica ao nome do PDF não comprova que a resposta esteja em uma página concreta.

Limites previsíveis: defina tamanhos máximos de carga, cotas, timeouts e política de erros. O cliente deve ser capaz de distinguir “não há correspondências” de “serviço indisponível”.

Separar busca e geração

O endpoint /search deve funcionar mesmo se o provedor LLM estiver fora do ar. Um segundo endpoint hipotético, /answer, poderia gerar uma resposta com citações a partir dos resultados, com um limite explícito de tokens e um indicador de confiança baseado em evidências, não na autopercepção do modelo.

Este design também permite usar o Router IA da ArduMaker para escolher o modelo em outra camada, mantendo a recuperação independente.

Testes que faria antes de lançar

Crie uma bateria versionada de 50 consultas com suas fontes esperadas. Meça recall@k da busca, consultas sem resultados, latência p50/p95 e custo por mil consultas. Adicione tentativas de acesso entre empresas: uma credencial da A não deve poder obter uma cotação da B nem por filtros manipulados nem por um documento compartilhado por engano.

Há uma necessidade comercial?

O sinal útil não é quantas pessoas leem “o que é RAG”, mas quantas equipes pedem uma API de recuperação sem montar embeddings, indexadores e armazenamento por conta própria. Na ArduMaker estamos estudando essa possibilidade como serviço gerenciado; ainda não é uma API de RAG publicada. Você pode descrever seu caso de uso em ArduMaker.

Referências: RAG e fontes no Microsoft Foundry · Recuperar no Amazon Bedrock · Router IA.

  • RAG API
  • retrieval
  • desarrolladores
  • API REST
  • embeddings

Continuar lendo

Todos os artigos · Planos VPS