AI Configuration Parameters
All the following parameters must be configured in the openkm.properties file. Once configured, the OpenKM service must be restarted for the changes to take effect.
Some functionalities must be enabled in the users' Profiles for them to be available.
From Administration > AI Prompt, prompts can be defined in combination with Creating your own AI prompt plugin.
OpenKM utilizes Spring AI (specifically version 1.1.2 at the time of this documentation). The parameters shown here represent only a subset of those provided by this library. For comprehensive information, please consult the Spring AI documentation:
- Chat Models: https://docs.spring.io/spring-ai/reference/api/chatmodel.html
- Model Comparison: https://docs.spring.io/spring-ai/reference/api/chat/comparison.html
- OpenAI Chat Parameters: https://docs.spring.io/spring-ai/reference/api/chat/openai-chat.html
Currently supported models include: Anthropic Claude, Azure OpenAI, Google Vertex AI Gemini, Ollama (for running local models), and OpenAI. Additional models from the comparison list can be integrated as needed.
You should only activate one AI model at a time.
An active AI model is required for several OpenKM functionalities, including prompts, AI plugins for document processing, RAG (Retrieval-Augmented Generation), and the MCP client.
AI Provider Configuration
The following parameters define which AI model to use for chat and embedding operations.
| Property | Type | Description |
|---|---|---|
|
spring.ai.model.chat |
String |
Specifies the chat model provider. openai |
|
spring.ai.model.embedding |
String |
Specifies the embedding model provider. openai |
|
spring.ai.openai.api-key |
String |
The API key for authentication. API KEY |
|
spring.ai.openai.chat.options.model |
String |
The specific model version to use. gpt-5-mini |
|
spring.ai.openai.chat.options.temperature |
Float |
Controls randomness in responses (0.0 to 1.0). Lower values make the output more focused and deterministic. 1 |
MCP Server Configuration
The Model Context Protocol (MCP) Server allows external applications to interact with OpenKM's core functionalities.
| Property | Type | Description |
|---|---|---|
|
spring.ai.mcp.server.enabled |
Boolean |
Enables or disables the MCP server. Set to false |
|
spring.ai.mcp.server.instructions |
String |
Instructions and description for the MCP server. 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 |
Request timeout duration. 60s |
|
okm.mcp.security.allowed.ips |
String |
Restricts which IP addresses can access the MCP service. Use * to allow all IP addresses, or specify a specific IP address (e.g., 10.0.0.50) to restrict access. * |
Additional parameters for MCP-specific logging:
To enable detailed logging for the MCP service, add the following parameters to openkm.properties:
logging.level.com.openkm.mcp=DEBUGlogging.level.com.openkm.config.MCPToolSecurityAspect=DEBUG
MCP Client Configuration
OpenKM includes an MCP (Model Context Protocol) client that allows it to connect to external MCP servers.
Important: Do not enable the Spring AI auto-configuration for the MCP client. The parameter spring.ai.mcp.client.enabled must always be set to false. OpenKM uses manual configuration instead.
| Property | Type | Description |
|---|---|---|
|
spring.ai.mcp.client.enabled |
Boolean |
Spring AI MCP client auto-configuration. Must always be false |
|
okm.mcp.manual.client.enabled |
Boolean |
Enables or disables the manual MCP client configuration. false |
|
okm.mcp.manual.connections.server1.url |
String |
URL of the first MCP server to connect to. http://localhost:8080 |
|
okm.mcp.manual.connections.server1.sse-endpoint |
String |
Server-Sent Events (SSE) endpoint for the MCP server. /openkm/sse |
|
okm.mcp.manual.connections.server1.token |
String |
Authentication token for OpenKM. We recommend generating a token with a validity period of one year or more. |
The MCP client supports multiple server connections. To add additional servers, use the same parameter pattern with different server identifiers:
okm.mcp.manual.connections.server2.urlokm.mcp.manual.connections.server2.sse-endpointokm.mcp.manual.connections.server2.token
RAG (Retrieval-Augmented Generation) Configuration
RAG enhances AI responses by retrieving relevant information from a vector database. OpenKM supports different vector store backends.
MariaDB example configuration
| Property | Value |
|---|---|
|
spring.ai.model.embedding |
openai |
|
spring.ai.vectorstore.mariadb.initialize-schema |
true |
|
spring.ai.vectorstore.type |
mariadb |
PostgreSQL example configuration
The PostgreSQL server must have vector support available before enabling this option. This means the server needs the vector extension installed — either by adding the corresponding extension package to an existing PostgreSQL installation, or by using a PostgreSQL Docker image that already includes vector support. Check the documentation for your operating system or Docker distribution for the appropriate installation method.
| Property | Value |
|---|---|
|
spring.ai.model.embedding |
openai |
|
spring.ai.vectorstore.pgvector.initialize-schema |
true |
|
spring.ai.vectorstore.type |
pgvector |
|
spring.ai.vectorstore.similarity.threshold |
0.7 |
Retrieval tuning parameters
These parameters control how chunks are retrieved and ranked once a question is asked, independently of which vector store backend is used.
| Property | Type | Description |
|---|---|---|
|
spring.ai.vectorstore.similarity.threshold |
Float |
Minimum cosine similarity (0.0 to 1.0) that a chunk must reach to be considered a match for a chatbot query. OpenAI-family embedding models compress similarity into a narrow band — even relevant matches often score 0.3 to 0.6 — so keep this low and tune per embedding provider. 0.3 |
|
spring.ai.vectorstore.fetch.multiplier |
Integer |
Chunks are over-fetched by this factor (multiplied by top.k) before the final permission check runs, and also sizes the lexical candidate pool used for rank fusion when hybrid search is enabled. With acl-filter.enabled on by default, the vector store query itself already returns only accessible chunks, so this is now mostly a backstop for stale or not-yet-re-indexed ACL metadata rather than the main compensation mechanism. 2 |
|
spring.ai.vectorstore.acl-filter.enabled |
Boolean |
Filters by access permissions (requesting user or any of their roles with READ access) directly in the vector store query, instead of only discarding non-accessible candidates after fetching them. This keeps relevant results a user can read from being pushed out of the top.k window by results they can't read. The final permission check still runs regardless, as defense in depth. Documents indexed before this property existed have no ACL metadata and stay invisible to the filter until re-indexed. true |
|
spring.ai.vectorstore.top.k |
Integer |
Maximum number of chunks, after the permission filter, used as context to answer a chatbot query. 5 |
|
spring.ai.vectorstore.chunk.size |
Integer |
Target chunk size, in tokens, when feeding a document into the RAG vector store. Chunks are packed by paragraph up to this budget instead of being cut off mid-text. 800 |
|
spring.ai.vectorstore.chunk.overlap.paragraphs |
Integer |
Number of trailing paragraphs from a chunk that are carried over into the next one, so a chunk boundary doesn't strip context from what follows it. Set to 0 to disable overlap. 1 |
|
spring.ai.vectorstore.hybrid.enabled |
Boolean |
Combines the vector similarity ranking with a lexical (keyword) ranking over the same documents' extracted text, so exact terms, codes or acronyms that the embedding model doesn't match well can still surface. When disabled, retrieval is vector-only. false |
|
spring.ai.vectorstore.hybrid.rrf-k |
Integer |
Reciprocal Rank Fusion constant used to combine the vector and lexical rankings when hybrid search is enabled. Higher values flatten the influence of rank differences between the two rankings. 60 |
Indexing Documents into the RAG
Enabling the RAG through the configuration file is a necessary but not sufficient step. Simply activating it does not cause documents to be automatically vectorized or made available to the Smart Search or Chatbot features. Users must explicitly define which documents, or which areas of the repository, should be indexed in the vector store.
This selective indexing approach is intentional: indexing the entire repository is technically possible, but is generally not recommended, as it may introduce noise into AI responses and increase both storage and processing costs.
Configuring the Feed RAG Automation Rule
OpenKM ships with a built-in automation rule named Feed RAG, designed precisely for this purpose. This rule must be reviewed and activated through the Automation module and works as follows:
- Event: The rule is triggered by the Document text extraction event, at the post phase, that is, after the text has been successfully extracted from a document.
- Validation: A
PathContainscondition determines which documents qualify for indexing. Typically, this is configured with one or more repository folder paths so that only documents stored within those folders are vectorized. - Action: The
FeedRAGaction performs the actual vectorization and stores the document embeddings in the configured vector store.
The most common configuration involves targeting one or several specific folders in the repository, ensuring that only the relevant content is made available to the AI features.
The Feed RAG rule is included with OpenKM by default. Users only need to review and adapt its PathContains validation to match the folders they wish to index.
