Skip to main content

Semantic Plugin

Overview​

The Semantic plugin represents the future of AiKA's knowledge retrieval capabilities. It provides advanced semantic search functionality through an MCP (Model Context Protocol) server, enabling AiKA to find contextually relevant information across your organization's documentation with greater accuracy than traditional keyword-based search.

The Future of AiKA

The Semantic plugin is the future source for AiKA's knowledge retrieval. As the semantic search ecosystem matures, this will become the primary way AiKA accesses and understands your organizational knowledge.

Semantic search uses vector embeddings to understand the meaning and context of queries, rather than just matching keywords. This allows AiKA to:

  • Find relevant information even when exact keywords don't match
  • Understand context and intent behind questions
  • Retrieve more accurate results by considering semantic relationships between concepts
  • Handle natural language queries more effectively

For example, asking "How do I take time off?" can surface documents about vacation policies, PTO, and leave management. These docs are relevant even if they don't contain the exact phrase "time off."

How It Works With AiKA​

MCP Integration​

The Semantic plugin exposes its functionality through an MCP (Model Context Protocol) server. When AiKA operates in agent mode:

  • The semantic search MCP tool is registered and available
  • AiKA's reasoning engine can decide when to invoke semantic search
  • The tool performs vector-based similarity search across your knowledge base
Agent Mode Requirement

The Semantic plugin currently only affects AiKA when running in agent mode. It provides the semantic search tool that the agent can choose to use during its reasoning process. This is different from legacy RAG experience.

For more information about AiKA's agentic approach, see the Searching for Information documentation.

Getting Started​

Prerequisites​

Before enabling the Semantic plugin, ensure you have:

  1. AiKA configured and running in your Portal instance
  2. Access to the Config Manager
  3. AI Gateway configured with at least an embedding model

Installation​

1. Configure AI Models (Required)​

The Semantic plugin requires an embedding model to function. Configure this through the Config Manager:

  1. Navigate to the Config Manager
  2. Go to AI Gateway configuration at /config-manager/ai
  3. Configure the following fields using AI Gateway for reference:
    • ai.models.textEmbeddingModel (required)
    • ai.models.rerankingModel (recommended)

Alternatively, if you want different models specifically for semantic search, configure these fields in the semantic plugin configuration at /config-manager/semantic:

  • semantic.models.embedding (required): Set to a model like openai|text-embedding-3-small
  • semantic.models.rerank (recommended): Set to a model like cohere|rerank-v3.5
Model Recommendation

The semantic plugin will work without a reranking model, but we strongly recommend configuring one for better search quality. If no reranking model is specified (neither in semantic.models.rerank nor ai.models.rerankingModel), results will be returned based solely on embedding similarity.

2. Enable the Semantic Plugin​

To enable the Semantic plugin in your Portal instance:

  1. Navigate to the Config Manager
  2. Start the semantic plugin
    • The semantic MCP server will be started automatically as part of this process. It will be immediately available for AiKA to use.
  3. The plugin will begin indexing your TechDocs automatically.
    • You will need to configure semantic-backend-module-confluence to begin indexing Confluence documents. See below for details.

3. Disable the Legacy Search Module​

To prevent conflicts between the new semantic search and the older keyword-based search tools, you should disable the search-backend-module-action:

  1. Navigate to the Config Manager
  2. Navigate the the search plugin and select the "Modules" tab.
  3. Locate the search-backend-module-action module and stop it.
Avoid Search Conflicts

Running both the legacy keyword search MCP and the new semantic MCP simultaneously can cause confusion for AiKA's decision-making process. We recommend disabling the search-backend-module-action module when enabling the semantic plugin.

Initial Data Ingestion​

When you first enable the semantic plugin, the system needs to ingest data from your configured knowledge sources and generate vector embeddings for all documents.

Initial Setup Time

The initial data ingestion and vector generation process can take time. This is a one-time process that happens when the plugin first starts. You may notice slower search performance or limited results until the indexing completes.

Indexing Confluence Documents​

Overview​

By default, the semantic plugin automatically indexes TechDocs. To include Confluence documents in your semantic search index, you need to configure the semantic-backend-module-confluence module.

Separate from Search Confluence Collator

Even if you have already configured a Confluence collator for Backstage Search, you still need to configure semantic-backend-module-confluence separately. The semantic plugin uses its own chunking and vectorization process for Confluence documents, which is different from the keyword-based search collator.

Configuration​

Configure Confluence indexing through the Config Manager under semantic.collators.confluence.

Required Fields​

The following fields are required for Confluence indexing to work:

Base URL (semantic.collators.confluence.baseUrl)

  • The base URL for accessing the Confluence API
  • Typically: https://{org-name}.atlassian.net/wiki

Authentication (semantic.collators.confluence.auth)

  • Confluence API credentials
  • Required fields depend on the authentication type selected

Authentication Types​

Choose one of the following authentication methods:

Bearer Authentication​

Use an API token:

semantic:
  collators:
    confluence:
      baseUrl: https://your-org.atlassian.net/wiki
      auth:
        type: bearer
        token: ${CONFLUENCE_TOKEN}  # API token with Read permissions

Basic Authentication​

Use an API token with your email address:

semantic:
  collators:
    confluence:
      baseUrl: https://your-org.atlassian.net/wiki
      auth:
        type: basic
        token: ${CONFLUENCE_TOKEN}  # API token with Read permissions
        email: your-email@example.com

Use username and password directly:

semantic:
  collators:
    confluence:
      baseUrl: https://your-org.atlassian.net/wiki
      auth:
        type: userpass
        username: your-username
        password: ${CONFLUENCE_PASSWORD}
Security Best Practice

Using an API token (basic or bearer authentication) is strongly preferred over username/password authentication. API tokens can be easily rotated and have more granular permission controls.

Troubleshooting​

Semantic Plugin Not Working​

If the semantic plugin isn't functioning:

  1. Verify embedding model is configured: The semantic plugin requires an embedding model. Check that you have configured either:
    • ai.models.textEmbeddingModel in your AI Gateway configuration, OR
    • semantic.models.embedding in your semantic plugin configuration
  2. Check backend logs: Look for errors related to model initialization or API credentials
  3. Verify AI Gateway setup: Ensure your AI provider credentials are properly configured
  4. Ensure data ingestion is complete: If you just enabled the plugin, give some time for the initial indexing to finish
  5. Confirm AiKA is in agent mode: The semantic plugin only works when AiKA is operating in agent mode
  6. Disable legacy search module: Make sure the search-backend-module-action is disabled to avoid conflicts

If the above troubleshooting does not work, disable the semantic plugin and enable the search-backend-module-action to revert to the legacy keyword-based search functionality.