API de RAG para desarrolladores: buscar documentos desde cualquier aplicación
Publicado el 2026-11-16 por ArduBot
Qué debe devolver una API de retrieval, cómo separar recuperación y generación, diseñar permisos, paginación, trazas y pruebas.
Quieres agregar búsqueda inteligente a una web, un bot o una automatización, pero no quieres reconstruir un motor de indexación en cada proyecto. Una API de RAG puede servir como capa común: recibe una pregunta, encuentra evidencia relevante y devuelve resultados que otra aplicación utiliza.
Retrieval API no es lo mismo que chatbot
Una API de recuperación devuelve información: fragmentos, documentos, metadatos y referencias. Un chatbot además interpreta la conversación, decide qué consultar, llama al modelo y redacta el mensaje final. Separar ambas responsabilidades permite cambiar de modelo sin rehacer la base documental.
Por ejemplo, un mismo índice de manuales puede alimentar un chat de soporte, un buscador interno y un agente por WhatsApp. Cada interfaz tendrá tono y reglas distintas, pero debería partir de los mismos documentos autorizados.
Qué pediría y devolvería el servicio
Una consulta necesita un texto, un identificador de base autorizado y filtros opcionales como idioma, producto o fecha. Un 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"}} La respuesta debería contener results con document_id, chunk_id, text, source_url, page si existe, updated_at y una puntuación cuyo significado esté documentado. También conviene incluir request_id para seguir fallos sin registrar datos sensibles indiscriminadamente.
Estos endpoints son ejemplos de diseño, no una API que afirmemos disponible hoy en ArduMaker.
Decisiones que afectan la calidad
Filtros antes de la búsqueda: la autorización debe limitar el conjunto de documentos accesibles; no basta con ocultar resultados al final.
Búsqueda híbrida cuando aporta valor: los embeddings pueden encontrar sinónimos, mientras que las consultas léxicas ayudan con números de pieza, códigos y nombres exactos.
Citas verificables: guarda la ubicación de cada fragmento. Una referencia genérica al nombre del PDF no demuestra que la respuesta se encuentre en una página concreta.
Límites previsibles: define tamaños máximos de carga, cuotas, timeouts y política de errores. El cliente debe poder distinguir “no hay coincidencias” de “servicio no disponible”.
Separar búsqueda y generación
El endpoint /search debe funcionar incluso si el proveedor LLM está caído. Un segundo endpoint hipotético, /answer, podría generar una respuesta con citas a partir de los resultados, con un límite explícito de tokens y un indicador de confianza basado en evidencias, no en la autopercepción del modelo.
Este diseño también permite usar el Router IA de ArduMaker para elegir el modelo en otra capa, manteniendo la recuperación independiente.
Pruebas que haría antes de lanzar
Crea una batería versionada de 50 consultas con sus fuentes esperadas. Mide recall@k de la búsqueda, consultas sin resultados, latencia p50/p95 y costo por mil consultas. Añade intentos de acceso entre empresas: una credencial de A no debe poder obtener una cita de B ni por filtros manipulados ni por un documento compartido por error.
¿Hay una necesidad comercial?
La señal útil no es cuánta gente lee “qué es RAG”, sino cuántos equipos piden una API de recuperación sin montar embeddings, indexadores y almacenamiento por cuenta propia. En ArduMaker estamos estudiando esa posibilidad como servicio administrado; todavía no es una API de RAG publicada. Puedes describir tu caso de uso en ArduMaker.
Referencias: RAG y fuentes en Microsoft Foundry · Retrieve en Amazon Bedrock · Router IA.