Añadir una API de base de conocimiento a su aplicación: guía para desarrolladores

Añadir una API de base de conocimiento a su aplicación significa exponer, con unas pocas llamadas REST, la capacidad de buscar en sus documentos y devolver respuestas con fuentes citadas. En la práctica se reduce a tres decisiones: qué endpoint usar (respuesta o solo pasajes), cómo autenticar las peticiones con claves API, y cómo mostrar las citas en su interfaz sin que el usuario pierda confianza en lo que lee.

Qué es una API de base de conocimiento y cuándo tiene sentido añadirla

Una API de base de conocimiento (a menudo llamada API RAG, de retrieval-augmented generation) recibe una pregunta en lenguaje natural y devuelve texto generado que se apoya en documentos concretos, junto con los fragmentos exactos de donde proviene esa información. No es lo mismo que una API de búsqueda vectorial pura: esta última le da vectores y puntuaciones de similitud, pero el trabajo de recortar en fragmentos (chunking), indexar para búsqueda híbrida, redactar la respuesta y enlazar cada afirmación con su fuente lo tiene que montar usted.

Tiene sentido añadir esta API cuando su aplicación necesita responder preguntas sobre contenido propio (manuales, contratos, tickets de soporte, normativa interna) sin reentrenar ningún modelo y sin montar infraestructura de base de datos vectorial. Plataformas como Kopik funcionan como marketplace de bases de conocimiento ya indexadas: usted sube los documentos, el sistema se encarga del chunking y de la búsqueda híbrida (texto completo más expansión semántica), y su app solo consume la API o el servidor MCP.

Si quiere entender primero el mecanismo interno antes de integrar nada, conviene repasar cómo funciona RAG paso a paso: eso le ayudará a interpretar mejor los parámetros que verá en los endpoints.

Endpoints típicos: búsqueda, respuesta y pasajes

La mayoría de APIs de base de conocimiento ofrecen, con nombres distintos según el proveedor, tres tipos de operación. Conviene distinguirlas desde el diseño de su app porque tienen latencia y coste muy diferentes.

• Respuesta con fuentes: la API recibe una pregunta y devuelve un texto redactado más la lista de pasajes citados. Es lo que necesita para un chatbot o un asistente que da una respuesta directa.
• Solo pasajes (modo "passages"): la API devuelve los fragmentos más relevantes sin redactar nada. Es más barato y más rápido, y le sirve cuando usted mismo compone la respuesta o alimenta otro modelo.
• Metadatos de la base: listar documentos indexados, su fecha de actualización y el número de fragmentos, útil para mostrar un panel de estado o detectar cuándo falta reindexar algo.

Cuándo elegir respuesta y cuándo elegir pasajes

Use el modo de respuesta cuando la pregunta es libre y el usuario espera una frase redactada, como en un widget de ayuda al cliente. Use el modo de solo pasajes cuando ya tiene su propio flujo de generación (por ejemplo, un agente que combina varias fuentes) o cuando quiere mostrar directamente los extractos sin intermediar, como en un buscador documental interno.

Autenticación con claves API: buenas prácticas

Casi todas las APIs de este tipo se autentican con una clave que va en la cabecera de la petición (por ejemplo Authorization: Bearer). Lo relevante no es el mecanismo en sí, sino cómo lo gestiona dentro de su aplicación.

• Nunca incruste la clave en el código del frontend ni en una app móvil: cualquiera puede extraerla y consumir su saldo. Pásela por un backend propio que actúe de proxy.
• Use una clave distinta por entorno (desarrollo, pruebas, producción) para poder revocar una sin afectar a las demás.
• Si su base es privada, la clave es la única barrera de acceso: trátela como una contraseña, rótela periódicamente y nunca la suba a un repositorio público.
• Limite el ritmo de peticiones (rate limiting) en su propio backend para evitar que un error de bucle en el frontend dispare el consumo de créditos.

La documentación técnica con ejemplos de cabeceras, códigos de error y límites está en /developers; conviene tenerla abierta mientras integra el primer endpoint.

Latencia: qué esperar y cómo optimizarla

Una consulta de respuesta con fuentes tiene tres fases: convertir la pregunta en representación de búsqueda, recuperar los fragmentos más relevantes de la base y redactar la respuesta final citando esos fragmentos. La fase de redacción suele ser la más lenta porque depende de generar texto token a token, mientras que la recuperación con búsqueda híbrida es prácticamente instantánea si el índice está bien construido.

• Si su app necesita respuesta inmediata en una interfaz de chat, use streaming (la respuesta llega por fragmentos) para que el usuario vea texto a los pocos cientos de milisegundos en lugar de esperar la respuesta completa.
• Si solo necesita los extractos para mostrarlos o para alimentar otro proceso, pida el modo de solo pasajes: elimina por completo la fase de redacción.
• Cachee en su backend las preguntas más repetidas (por ejemplo, las cinco preguntas frecuentes de su FAQ) durante unos minutos para no pagar ni esperar por algo que ya se respondió.

La calidad de la recuperación también afecta a la latencia percibida: si el motor de búsqueda devuelve fragmentos irrelevantes, el modelo necesita más contexto o más intentos para redactar algo útil, lo que alarga la respuesta. Por eso conviene entender por qué la búsqueda híbrida combinando palabras clave y vectores suele dar mejores resultados que depender solo de similitud semántica.

Costes: cómo se factura una API RAG

Los modelos de facturación más habituales son dos: créditos prepagados por pregunta, o una suscripción mensual con un medidor de uso. En Kopik, por ejemplo, puede comprar créditos que se consumen por consulta, o contratar una suscripción de chat a 12 €/mes con un indicador de consumo, según el volumen de preguntas que espere.

Para dimensionar el gasto conviene pensar en tres variables: el número de preguntas al mes, si usa modo respuesta (más caro, porque genera texto) o modo pasajes (más barato), y si la base es pública (donde además puede cobrar usted mismo a quien la consulte) o privada. Si quiere comparar este modelo con el coste de montar su propia base de datos vectorial, el artículo sobre el precio real de una base de datos vectorial desglosa qué se paga en cada opción (infraestructura, embeddings, mantenimiento).

Cómo citar las fuentes en su interfaz

Una respuesta sin cita visible es una caja negra: el usuario no puede verificar nada y, si hay un error, no sabe de dónde viene. El patrón que mejor funciona en la mayoría de apps es mostrar marcadores numerados dentro del texto de la respuesta (como notas al pie) que, al pasar el ratón o al tocar en móvil, abren una tarjeta con el fragmento exacto citado y un enlace al documento original.

• Muestre siempre el pasaje citado, no solo el nombre del documento: el usuario debe poder leer la frase exacta que sustenta la afirmación.
• Si el documento tiene páginas o secciones, enlace al punto concreto en lugar de a la portada del PDF.
• Cuando la API no encuentre ningún pasaje relevante, muéstrelo explícitamente ("no se ha encontrado información en la base") en lugar de dejar que el modelo rellene el hueco con una suposición.
• Permita al usuario marcar una respuesta como incorrecta y enlace esa señal a los documentos citados, para detectar contenido desactualizado.

Este patrón de citas es también la base para reducir riesgos de alucinación: puede leer el procedimiento completo en cómo verificar una respuesta de IA con sus fuentes y en cómo reducir las alucinaciones de la IA con respuestas basadas en fuentes. Ambos artículos dan criterios concretos para decidir cuándo confiar en una respuesta y cuándo pedir al usuario que revise la fuente original.

Integración paso a paso

Un flujo típico para añadir la API a una aplicación nueva suele seguir este orden:

1. Cree la base de conocimiento subiendo sus documentos (PDF, Word, Markdown o texto plano) desde /dashboard/bases/new; el sistema se encarga de extraer el texto, trocearlo e indexarlo.
2. Decida si la base será pública (listada en el catálogo de /bases, con pago por pregunta y un reparto del 70 % para usted como creador) o privada, accesible solo con sus claves.
3. Genere una clave API desde el panel y guárdela en las variables de entorno de su backend, nunca en el frontend.
4. Haga una primera llamada de prueba al endpoint de pasajes para comprobar que la recuperación encuentra los fragmentos correctos antes de pasar al modo de respuesta completa.
5. Integre el modo de respuesta en su interfaz con streaming y el patrón de citas numeradas descrito más arriba.
6. Si su equipo también quiere consultar la base desde su editor o desde un asistente de IA sin tocar código, pruebe el servidor MCP: la guía conectar Claude, Cursor o ChatGPT a una base de conocimiento explica la configuración paso a paso.

Errores comunes al integrar la API

El fallo más frecuente es tratar la API de base de conocimiento como un simple generador de texto y descartar los pasajes citados en la respuesta de la API, mostrando solo el texto redactado. Esto anula la principal ventaja de RAG frente a un modelo genérico: la trazabilidad. Otro error habitual es no vigilar el tamaño de los fragmentos devueltos; si su base se indexó con un chunking demasiado grande o demasiado pequeño, las respuestas pierden precisión, algo que puede revisar en estrategias de chunking para RAG. Por último, muchos equipos olvidan probar qué ocurre cuando la pregunta no tiene respuesta en los documentos: la API debe poder decir "no lo sé" en lugar de inventar, y su interfaz debe mostrarlo con claridad en vez de tratarlo como un error técnico.