> ## 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.

# Semantic Plugin

> Enable semantic search in AiKA using an MCP server for contextually relevant retrieval across your organization's documentation.

## 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.

<Tip>
  **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.
</Tip>

## What is Semantic Search?

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

<Info>
  **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.
</Info>

For more information about AiKA's agentic approach, see the [Searching for Information](./searching-for-information#agentic-search-vs-single-step-rag) documentation.

## Getting Started

### Prerequisites

Before enabling the Semantic plugin, ensure you have:

1. AiKA configured and running in your Portal instance
2. Access to **Plugins**
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 App Settings:

1. Navigate to App Settings
2. Go to AI Gateway configuration at `/admin/app-settings/ai-models`
3. Configure the following fields using [AI Gateway](../ai-gateway/index) 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 `/admin/plugin-settings/plugin/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`

<Info>
  **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.
</Info>

#### 2. Enable the Semantic Plugin

To enable the Semantic plugin in your Portal instance:

1. Navigate to **Plugins**
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](#indexing-confluence-documents) 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 **Plugins**
2. Navigate to the `search` plugin and select the "Modules" tab.
3. Locate the `search-backend-module-action` module and stop it.

<Warning>
  **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.
</Warning>

### 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.

<Note>
  **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.
</Note>

## 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.

<Warning>
  **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.
</Warning>

### Configuration

Configure Confluence indexing through **Plugins** 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](#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 based on your Confluence deployment.

#### Confluence Cloud

##### Personal API Token (classic / unscoped)

Create a [Personal Access Token (PAT)](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) with `Read` permissions.

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
semantic:
  collators:
    confluence:
      baseUrl: https://<your-domain>.atlassian.net/wiki # Classic tokens use your org wiki URL
      auth:
        type: basic
        token: ${CONFLUENCE_TOKEN} # Classic, non-scoped API token
        email: '<your-atlassian-account-email>'
```

##### Personal Scoped API Token

[Scoped API tokens](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/#Create-an-API-token-with-scopes) allow limiting the permissions of the token.

> **Important:** Scoped tokens require a different `baseUrl` — `https://api.atlassian.com/ex/confluence/<your-cloud-id>/wiki` instead of `https://<your-domain>.atlassian.net/wiki`. You can find your `cloudId` by visiting `https://<your-domain>.atlassian.net/_edge/tenant_info`.

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
semantic:
  collators:
    confluence:
      baseUrl: https://api.atlassian.com/ex/confluence/<your-cloud-id>/wiki # Scoped tokens use the Atlassian REST API base URL with your cloud ID
      auth:
        type: basic
        token: ${CONFLUENCE_SCOPED_TOKEN} # Scoped API token
        email: '<your-atlassian-account-email>'
```

##### Service Account Scoped API Token

For production use, a [service account](https://support.atlassian.com/organization-administration/docs/manage-api-tokens-for-service-accounts/) is recommended over a personal token, as it is not tied to an individual user. Create a service account in your Atlassian organization and generate a scoped API token for it with the same scopes listed above.

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
semantic:
  collators:
    confluence:
      baseUrl: https://api.atlassian.com/ex/confluence/<your-cloud-id>/wiki # Scoped tokens use the Atlassian REST API base URL with your cloud ID
      auth:
        type: basic
        token: ${CONFLUENCE_SERVICE_ACCOUNT_TOKEN} # Scoped API token
        email: '<generated-id>@serviceaccount.atlassian.com'
```

#### Confluence Self-Hosted (Server / Data Center)

##### Personal Access Token

Create a [Personal Access Token (PAT)](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) in your Confluence Server or Data Center instance.

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
semantic:
  collators:
    confluence:
      baseUrl: https://<your-confluence-host>
      auth:
        type: bearer
        token: ${CONFLUENCE_TOKEN}
```

##### Username and Password

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
semantic:
  collators:
    confluence:
      baseUrl: https://<your-confluence-host>
      auth:
        type: userpass
        username: ${CONFLUENCE_USERNAME}
        password: ${CONFLUENCE_PASSWORD}
```

<Tip>
  **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.
</Tip>

## 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.