Skip to main content

Documentation Index

Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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 AiKAThe 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 RequirementThe 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 RecommendationThe 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 to the search plugin and select the “Modules” tab.
  3. Locate the search-backend-module-action module and stop it.
Avoid Search ConflictsRunning 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 TimeThe 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 CollatorEven 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
  • The correct base URL depends on the type of API token you are using. Scoped tokens use the Atlassian REST API URL, while classical tokens use the org wiki URL. See Authentication Types below for details.
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 a scoped API token. 
semantic:
  collators:
    confluence:
      baseUrl: https://api.atlassian.com/ex/confluence/<cloudId> # Scoped tokens use the Atlassian REST API base URL with your cloud ID
      auth:
        type: bearer
        token: ${CONFLUENCE_TOKEN} # Scoped API token

​
Basic Authentication

Use a classical, non-scoped API token, along with your email address. 
semantic:
  collators:
    confluence:
      baseUrl: https://your-org.atlassian.net/wiki # Classical tokens use your org wiki URL
      auth:
        type: basic
        token: ${CONFLUENCE_TOKEN} # Classical, non-scoped API token
        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 PracticeUsing 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.