Semantic code search administration

With semantic code search, AI-native GitLab Duo features can find relevant code snippets in your repository.

Prerequisites

• Access to the GitLab AI Gateway or GitLab Duo Self-Hosted.
• Beta and experimental features turned on for the instance.
• A vector store configured:
  • Elasticsearch 8.0 and later.
  • OpenSearch 2.0 and later.
  • PostgreSQL with the pgvector extension.
• For GitLab Duo Self-Hosted, an embedding model configured.

Vector storage

You should use Elasticsearch or OpenSearch for medium to large repositories. Use PostgreSQL with pgvector only for setups with a few small repositories. Indexing and querying performance might be limited with pgvector.

Connect to the advanced search cluster

If your GitLab instance uses Elasticsearch or OpenSearch for advanced search, you can turn on semantic code search by connecting to the same cluster:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Settings > Search.
3. Expand Semantic search.
4. For Vector storage, select Configure.
5. On the Vector storage page, under Advanced search cluster, select Connect.

Configure a custom vector store

To configure a custom vector store connection:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Settings > Search.
3. Expand Semantic search.
4. For Vector storage, select Configure.
5. From the Search adapter dropdown list, select Elasticsearch, OpenSearch, or PostgreSQL.
6. Complete the fields for your adapter.
7. Select Save changes.

Elasticsearch

OpenSearch

To use AWS OpenSearch Service, select Use AWS OpenSearch Service with IAM credentials and complete the fields:

PostgreSQL with pgvector

Prerequisites:

• Enable the pgvector extension in your PostgreSQL database:

  CREATE EXTENSION vector;

Configure an embedding model

To configure an embedding model:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Settings > Search.
3. Expand Semantic search.
4. For Code embeddings, select Set model. If you already configured an embedding model, Change model appears instead.
5. On the Semantic search code embeddings page, select the embedding model, embedding dimensions, and the chunking strategy.
6. Select Set embeddings. If you already configured an embedding model, Update embeddings and start backfill process appears instead.

Embedding models

GitLab-managed models

Prerequisites:

• Access to both the GitLab AI Gateway and GitLab Duo Self-Hosted.

GitLab-managed models are offered on the GitLab AI Gateway. Select the text-embedding-005 model provided by the Gemini Enterprise Agent Platform.

For more information about GitLab-managed models with a GitLab Duo Self-Hosted setup, see hybrid AI Gateway and model configuration.

Self-hosted models

Prerequisites:

• Access to GitLab Duo Self-Hosted.
• Self-hosted beta models and features turned on.

Self-hosted models are AI models hosted on your own infrastructure.

To select a self-hosted model:

1. Set up GitLab Duo Self-Hosted.
2. Add a self-hosted model with an EMBEDDING model family.

Chunking strategy

The chunking strategy is the algorithm used to split code files into smaller snippets for embeddings. Select one of the following strategies:

• Code bytes: Splits code into fixed-size byte chunks without considering code structure or semantics. Chunk size refers to the maximum number of bytes per chunk. Use this strategy for the following:
  • Faster indexing and more predictable chunk size.
  • Repositories with diverse file types and languages.
• Code pre-BERT: Splits code by using semantic boundaries optimized for BERT-based embedding models. Chunk size refers to the maximum number of tokens per chunk. Use this strategy for the following:
  • Better search quality and more meaningful chunks that respect code structure.
  • Repositories with well-structured code.

Check semantic code search status

To check the status of semantic code search, including indexing status, vector store connection details, repository statistics, and embedding queue sizes, run this Rake task:

sudo gitlab-rake gitlab:semantic_search:code:info

To monitor status continuously, provide a watch interval in seconds:

sudo gitlab-rake "gitlab:semantic_search:code:info[5]"

This task refreshes the output at the specified interval. To stop the task, press Control+C.

Manage the dead queue

Prerequisites:

• A personal access token with the admin_mode, ai_features, and api scopes.

When embedding generation fails repeatedly, items are moved to the dead queue for manual intervention. You can check the dead queue size in the Embedding Queues section of the status Rake task output.

Clear the dead queue

To delete all items from the dead queue, run this command:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_token>" \
  "https://gitlab.example.com/api/v4/admin/active_context/dead_queue"

Replay the dead queue

To move dead queue items back into a processing queue for another attempt, use the queue parameter to specify the target. Valid values are retry_queue, code, and code_backfill.

To attempt processing once more before potentially failing back to the dead queue, use retry_queue:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_token>" \
  --data "queue=retry_queue" \
  "https://gitlab.example.com/api/v4/admin/active_context/dead_queue/replay"

To add items to the main code queue, use code:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_token>" \
  --data "queue=code" \
  "https://gitlab.example.com/api/v4/admin/active_context/dead_queue/replay"