Parámetros de configuración de IA

Plantillas de prompt y límites de uso

Propiedad	Tipo	Descripción
ai.system.prompt.template	String	System prompt que se antepone a toda conversación de chat de IA general / MCP. Admite los marcadores `{userId}`, `{userName}` y `{token}`, sustituidos en tiempo de ejecución por el usuario actual y su token de autenticación. El valor por defecto integrado explica al modelo cómo se formatean las referencias a nodos de OpenKM (`@[nombre](uuid:…
ai.rag.prompt.template	String	Prompt usado para las respuestas RAG (Retrieval-Augmented Generation), es decir, el Chatbot y la Smart Search sobre documentos indexados. Debe contener los marcadores `{question_answer_context}` (donde se inyectan los fragmentos recuperados) y `{query}` (la pregunta del usuario). El valor por defecto integrado restringe al modelo a responder solo a partir del contexto proporcionado y en el idioma del usuario.
ai.usage.retention.days	Integer	Número de días que se conservan las filas de contabilidad de uso/coste de IA (`OKM_AI_USAGE`, una por llamada al proveedor) antes de que la tarea Purge AI Usage del Crontab las elimine. 365
ai.usage.budget.warn.cost	Integer	Umbral de coste estimado para el mes natural en curso. Cuando el coste estimado acumulado supera este valor, OpenKM emite una notificación de aviso pero las llamadas a IA siguen funcionando. `0` desactiva el aviso. El coste es una estimación derivada de los precios introducidos por el administrador (`OKM_AI_PRICING`), en USD por convención. 0
ai.usage.budget.limit.cost	Integer	Límite estricto de coste estimado para el mes natural en curso. Una vez que el coste estimado acumulado supera este valor, se bloquean las siguientes llamadas a IA hasta el mes siguiente. `0` desactiva el límite. Mismo matiz de estimación de coste que ai.usage.budget.warn.cost. 0

Configuración del proveedor de IA

Los siguientes parámetros definen qué modelo de IA usar para las operaciones de chat y embedding.

Propiedad	Tipo	Descripción
spring.ai.model.chat	String	Especifica el proveedor del modelo de chat. openai
spring.ai.model.embedding	String	Especifica el proveedor del modelo de embedding. openai
spring.ai.openai.api-key	String	La clave de API para autenticación. API key
spring.ai.openai.chat.options.model	String	La versión concreta del modelo a usar. gpt-5-mini
spring.ai.openai.chat.options.temperature	Float	Controla la aleatoriedad de las respuestas (0.0 a 1.0). Valores más bajos hacen la salida más enfocada y determinista. 1

Configuración del servidor MCP

El servidor MCP (Model Context Protocol) permite que aplicaciones externas interactúen con las funcionalidades centrales de OpenKM.

Propiedad	Tipo	Descripción
spring.ai.mcp.server.enabled	Boolean	Habilita o deshabilita el servidor MCP. Establezca `true` para activar el servidor MCP y reinicie el servicio. false
spring.ai.mcp.server.instructions	String	Instrucciones y descripción del servidor MCP. This server provides basic OpenKM application information and tools. OpenKM is a document management system that allows you to manage your documents. You can use this server to interact with OpenKM’s core functionalities through the MCP protocol.
spring.ai.mcp.server.request-timeout	Duration	Duración del tiempo de espera de las peticiones. 60s
okm.mcp.security.allowed.ips	String	Restringe qué direcciones IP pueden acceder al servicio MCP. Use * para permitir todas las direcciones IP, o especifique una dirección IP concreta (ej. 10.0.0.50) para restringir el acceso. *

Configuración del cliente MCP

OpenKM incluye un cliente MCP (Model Context Protocol) que le permite conectarse a servidores MCP externos.

Propiedad	Tipo	Descripción
spring.ai.mcp.client.enabled	Boolean	Autoconfiguración del cliente MCP de Spring AI. Debe ser siempre `false`. false
okm.mcp.manual.client.enabled	Boolean	Habilita o deshabilita la configuración manual del cliente MCP. false
okm.mcp.manual.connections.server1.url	String	URL del primer servidor MCP al que conectarse. http://localhost:8080
okm.mcp.manual.connections.server1.sse-endpoint	String	Endpoint Server-Sent Events (SSE) del servidor MCP. /openkm/sse
okm.mcp.manual.connections.server1.token	String	Token de autenticación para OpenKM. Recomendamos generar un token con un período de validez de un año o más.

Configuración de RAG (Retrieval-Augmented Generation)

RAG mejora las respuestas de IA recuperando información relevante de una base de datos vectorial. OpenKM soporta distintos backends de almacén vectorial.

Ejemplo de configuración con MariaDB

Propiedad	Valor
spring.ai.model.embedding	openai
spring.ai.vectorstore.mariadb.initialize-schema	true
spring.ai.vectorstore.type	mariadb

Ejemplo de configuración con PostgreSQL

Propiedad	Valor
spring.ai.model.embedding	openai
spring.ai.vectorstore.pgvector.initialize-schema	true
spring.ai.vectorstore.type	pgvector
spring.ai.vectorstore.similarity.threshold	0.7

Parámetros de ajuste de la recuperación

Estos parámetros controlan cómo se recuperan y clasifican los fragmentos una vez formulada una pregunta, independientemente del backend de almacén vectorial usado.

Propiedad	Tipo	Descripción
spring.ai.vectorstore.similarity.threshold	Float	Similitud coseno mínima (0.0 a 1.0) que debe alcanzar un fragmento para considerarse una coincidencia válida en una consulta del chatbot. Los modelos de embedding de la familia OpenAI comprimen la similitud en una banda estrecha — incluso coincidencias relevantes suelen puntuar entre 0.3 y 0.6 — así que mantenga este valor bajo y ajústelo según el proveedor de embedding. 0.3
spring.ai.vectorstore.sources.similarity.threshold	Float	Similitud coseno mínima (0.0 a 1.0) para que el documento de un fragmento se liste como “fuente” en la respuesta del chatbot. Deliberadamente más estricto que similarity.threshold anterior: un fragmento débil pero útil puede seguir incluyéndose en el contexto enviado al modelo sin presentarse al usuario final como una cita autorizada. Aplica la misma advertencia de ajuste por proveedor de embedding que similarity.threshold. 0.5
spring.ai.vectorstore.sources.citation.enabled	Boolean	Cuando está habilitado, una llamada adicional al modelo de chat comprueba cuáles de las fuentes que superaron sources.similarity.threshold citó realmente el modelo en su respuesta, y reduce la lista de “fuentes” a solo esas. Esto es necesario para corpus donde la similitud coseno no puede discriminar entre candidatos en absoluto — documentos legales/administrativos de la misma plantilla, por ejemplo, pueden puntuar todos dentro de una banda muy estrecha independientemente de su relevancia, muy por encima de cualquier umbral viable. Cuesta una llamada adicional al modelo de chat por consulta (latencia y tokens). Validado contra un corpus real donde sources.similarity.threshold por sí solo dejaba 20 candidatos no relacionados dentro de una banda de similitud de 0.008; la extracción de citas redujo correctamente eso a la única fuente en la que realmente se basaba la respuesta. true
spring.ai.vectorstore.fetch.multiplier	Integer	Los fragmentos se sobre-recuperan por este factor (multiplicado por top.k) antes de que se ejecute la comprobación final de permisos, y también dimensiona el conjunto de candidatos léxicos usado para la fusión de rangos cuando la búsqueda híbrida está habilitada. Con acl-filter.enabled activado por defecto, la propia consulta al almacén vectorial ya devuelve solo fragmentos accesibles, así que esto ahora es principalmente un respaldo para metadatos ACL obsoletos o aún no reindexados, más que el mecanismo principal de compensación. 2
spring.ai.vectorstore.acl-filter.enabled	Boolean	Filtra por permisos de acceso (usuario solicitante o cualquiera de sus roles con acceso de LECTURA) directamente en la consulta al almacén vectorial, en vez de descartar los candidatos no accesibles solo después de recuperarlos. Esto evita que resultados relevantes que un usuario puede leer sean desplazados de la ventana top.k por resultados que no puede leer. La comprobación final de permisos se sigue ejecutando de todos modos, como defensa en profundidad. Los documentos indexados antes de que existiera esta propiedad no tienen metadatos ACL y permanecen invisibles para el filtro hasta que se reindexen. true
spring.ai.vectorstore.top.k	Integer	Número máximo de fragmentos, tras el filtro de permisos, usados como contexto para responder a una consulta del chatbot. 5
spring.ai.vectorstore.chunk.size	Integer	Tamaño objetivo del fragmento, en tokens, al introducir un documento en el almacén vectorial de RAG. Los fragmentos se empaquetan por párrafo hasta este límite en vez de cortarse a mitad de texto. 800
spring.ai.vectorstore.chunk.overlap.paragraphs	Integer	Número de párrafos finales de un fragmento que se trasladan al siguiente, de modo que un límite de fragmento no elimine contexto de lo que le sigue. Establezca 0 para deshabilitar el solapamiento. 1
spring.ai.vectorstore.hybrid.enabled	Boolean	Combina la clasificación por similitud vectorial con una clasificación léxica (por palabra clave) sobre el texto extraído de los mismos documentos, de modo que términos exactos, códigos o acrónimos que el modelo de embedding no relaciona bien puedan seguir apareciendo. Cuando está deshabilitado, la recuperación es solo vectorial. false
spring.ai.vectorstore.hybrid.rrf-k	Integer	Constante de Reciprocal Rank Fusion usada para combinar las clasificaciones vectorial y léxica cuando la búsqueda híbrida está habilitada. Valores más altos suavizan la influencia de las diferencias de rango entre ambas clasificaciones. 60

Indexación de documentos en el RAG

Habilitar el RAG mediante el fichero de configuración es un paso necesario pero no suficiente. Simplemente activarlo no hace que los documentos se vectoricen automáticamente ni queden disponibles para las funcionalidades Smart Search o Chatbot. Los usuarios deben definir explícitamente qué documentos, o qué áreas del repositorio, deben indexarse en el almacén vectorial.

Este enfoque de indexación selectiva es intencional: indexar todo el repositorio es técnicamente posible, pero por lo general no se recomienda, ya que puede introducir ruido en las respuestas de IA y aumentar tanto el almacenamiento como los costes de procesamiento.

Configuración de la regla de automatización Feed RAG

OpenKM incluye una regla de automatización integrada llamada Feed RAG, diseñada precisamente para este propósito. Esta regla debe revisarse y activarse a través del módulo Automation y funciona así:

Evento: la regla se dispara con el evento Document text extraction, en la fase post, es decir, después de que el texto se haya extraído con éxito de un documento.
Validación: una condición PathContains determina qué documentos son aptos para la indexación. Normalmente, se configura con una o varias rutas de carpeta del repositorio para que solo se vectoricen los documentos almacenados dentro de esas carpetas.
Acción: la acción FeedRAG realiza la vectorización real y almacena los embeddings del documento en el almacén vectorial configurado.

La configuración más habitual consiste en apuntar a una o varias carpetas concretas del repositorio, garantizando que solo el contenido relevante quede disponible para las funcionalidades de IA.