Semantic Search: Add Embedding Model admin page (!230649) · Merge requests · GitLab.org / GitLab

What does this MR do and why?

For Self-managed instances with Self-hosted AIGW, we want to allow users to select the embedding model through the Admin UI.

Given the amount of changes needed to support this, the change is split into several MRs:

!232069 (merged) & !232569 (merged) - Add validations through the json schema and the EmbeddingModelActivationService
This MR: introduces the Semantic Search collection embeddings page, accessible through the url: <gitlab-url>/admin/application_settings/semantic_search_embeddings/<collection_key>.
!232091 (merged): adds a link to the page in the main Admin -> Search -> Semantic Search page

Notable Scenarios

Any instance
- If instance has no AI Feature license or Duo Feature is disabled, redirects to the main Search page
- If there is no active ActiveContext connection, redirects to the main Search page
- If collection is unknown or there is no collection record, redirects to the main search page
- If the above prerequisites are satisfied, the "Semantic Search collection embeddings" page is shown
Instances: SaaS, Dedicated, or SM without Self-hosted AIGW
- model details are shown in the embeddings page BUT the model update form is not rendered/shown
Instance: SM with Self-hosted AIGW
- model details are shown in the embeddings page AND the model update form is rendered
- if current model is not set, user can set the model without warnings
- if current model is set, user can update the model but there are sufficient warnings about the backfill process
- if next model is set, the model update form is shown but all elements are disabled

For the complete breakdown of scenarios, we can refer to the output of the ee/spec/requests/admin/application_settings/semantic_search_embeddings_controller_spec.rb:

Expand for specs output

bundle exec rspec ee/spec/requests/admin/application_settings/semantic_search_embeddings_controller_spec.rb -fd

All examples were filtered out; ignoring {:focus=>true}

Test environment set up in 1.798934999969788 seconds

Admin::ApplicationSettings::SemanticSearchEmbeddingsController
  # order random
  PUT #update
    behaves like redirects logged-out users
      for logged-out user
        redirects to login page
    behaves like not available for non-admin users
      for non-admin user
        is not found
    for admin user
      behaves like checks semantic search availability and collection presence
        when License is not available
          behaves like redirects to the search admin settings page
            redirects to the search admin settings page
        when License has AI Features and Duo Features are enabled
          when there is no active ActiveContext connection
            behaves like redirects to the search admin settings page
              redirects to the search admin settings page
            when there is an active ActiveContext connection
              when collection key is invalid
                behaves like redirects to the search admin settings page
                  redirects to the search admin settings page
              when collection record is missing
                behaves like redirects to the search admin settings page
                  redirects to the search admin settings page
      when semantic search is available and collection exists
        when instance does not support user model selection
          behaves like does not update the embedding model
            does not update the embedding and shows a warning
        when user does not have permissions to update AI models
          behaves like does not update the embedding model
            does not update the embedding and shows a warning
        when user can update the embedding model
          when embedding_model is not present
            behaves like does not update the embedding model
              does not update the embedding and shows a warning
          when embedding_dimensions is not present
            behaves like does not update the embedding model
              does not update the embedding and shows a warning
          when required params are present
            sets the embedding and disables inputs
            when collection record already has a current embedding model
              updates the embedding and disables inputs
            when EmbeddingModelActivationService throws an expected error
              fails embedding update and shows the error message
            when EmbeddingModelActivationService throws an unexpected error
              fails embedding update and shows an unknown error warning
  GET #show
    behaves like redirects logged-out users
      for logged-out user
        redirects to login page
    behaves like not available for non-admin users
      for non-admin user
        is not found
    for admin user
      behaves like checks semantic search availability and collection presence
        when License is not available
          behaves like redirects to the search admin settings page
            redirects to the search admin settings page
        when License has AI Features and Duo Features are enabled
          when there is no active ActiveContext connection
            behaves like redirects to the search admin settings page
              redirects to the search admin settings page
            when there is an active ActiveContext connection
              when collection key is invalid
                behaves like redirects to the search admin settings page
                  redirects to the search admin settings page
              when collection record is missing
                behaves like redirects to the search admin settings page
                  redirects to the search admin settings page
      when semantic search is available and collection exists
        when instance does not support user model selection
          behaves like does not show the model update form
            displays the model details but does not show the update form
        when user does not have permissions to update AI models
          behaves like does not show the model update form
            displays the model details but does not show the update form
        when user can update the embedding model
          allows setting the model without warnings
          when collection record has current embedding model
            displays the correct model information, allows update with warnings
            when current model_type is nil
              displays the correct model information without the model type
          when collection record has next embedding model
            shows the next model details, but disables inputs and submit button

Finished in 29.65 seconds (files took 14.91 seconds to load)
26 examples, 0 failures

References

Main Issue: [ActiveContext Code] Select embedding model in UI (#582638 - closed)
Rollout Issue: [FF] `semantic_search_user_model_selection` -- (#597029)

Screenshots or screen recordings

When user selection is not available

This applies to:

Instances: SaaS, Dedicated, or SM instance without self-hosted AIGW
OR semantic_search_user_model_selection is disabled

Expand for screenshot

When user selection is available

This applies to:

Instance: SM instance with self-hosted AIGW
AND semantic_search_user_model_selection is enabled

Setting a new model - expand for screen recording

Updating an existing model - expand for screen recording

When there is a current model and a next model - expand for screenshot

How to set up and validate locally

Scenario: user selection is not available

Do any of the following setup:
- simulate a SaaS instance (GITLAB_SIMULATE_SAAS=1)
- nullify the Self-hosted AIGW setting (Ai::Setting.instance.update(ai_gate_url: nil))
- disable the user-selection FF (Feature.disable(:semantic_search_user_model_selection))
Navigate to the "Semantic Search Code embeddings" page by typing the following on the browser address bar:
```
http://gdk.test:3000/admin/application_settings/semantic_search_embeddings/code
```
Verify that the model details are displayed, but you cannot make updates

Scenario: user selection is available

Simulate an SM instance with Self-hosted AIGW:
- simulate a SaaS instance (GITLAB_SIMULATE_SAAS=0)
- nullify the Self-hosted AIGW setting (Ai::Setting.instance.update(ai_gate_url: 'http://gdk.test:3000'))
- enable the user-selection FF (Feature.enable(:semantic_search_user_model_selection))
Navigate to the "Semantic Search Code embeddings" page by typing the following on the browser address bar:
```
http://gdk.test:3000/admin/application_settings/semantic_search_embeddings/code
```

Add a definition for a mock model so you can test switching models

diff --git a/ee/app/models/ai/active_context/embedding.rb b/ee/app/models/ai/active_context/embedding.rb
index ceec99824a8e..e18eb9fbd46a 100644
--- a/ee/app/models/ai/active_context/embedding.rb
+++ b/ee/app/models/ai/active_context/embedding.rb
@@ -29,6 +29,9 @@ module Embedding
        'text_embedding_005_vertex' => {
          model_name: 'text-embedding-005 - Vertex',
          batch_size: TEXT_EMBEDDING_VERTEX_BATCH_SIZE
+        },
+        'embedding_001_test' => {
+          model_name: 'embedding-001 - TEST'
        }
      }.freeze

Verify that you can set or update a new model

After setting or updating the model, the EmbeddingModelActivationService will run to start the switch to the next model. Since we are not testing this service, you can bypass this by manually switching the models on the rails console:

collection_record = Ai::ActiveContext::Collections::Code.collection_record
model_metadata = collection_record.reload.next_indexing_embedding_model
collection_record.reload.update_metadata!(
  current_indexing_embedding_model: model_metadata,
  next_indexing_embedding_model: nil
)

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Related to #582638 (closed)

Edited Apr 23, 2026 by Pam Artiaga

Semantic Search: Add Embedding Model admin page