Allow SM Admins to update embeddings request batch size

What does this MR do and why?

We need to persist a batch size value for Semantic Search indexing. This value indicates the maximum number of individual content inputs for each bulk embeddings request. Currently, we have set this to 30 for all embedding models, but Self-Managed instances with their own Self-hosted models will need to specify their own batch size since this value depends on the selected model.

Change Steps Overview

  • Introduce embeddings_request_batch_size to the embeddings model metadata schema - !246671 (merged)
  • Make the batch size value editable from the Admin UI for Self-Managed instances. This change has to be split in 2 parts due to its size
    • Introduce or update Service classes to allow for batch size update - !249502 (merged)
    • Allow batch size update from the Admin UI - This MR

Changes in this MR

  • Allow the embeddings request batch size to be set when setting or updating the embedding model
    • UI: Add an embeddings_request_batch_size field in the embedding model update form.
    • When setting/updating the embedding model, pass on the batch size parameter to the EmbeddingModelActivationService
    • Ensure that the batch size parameter is passed on to the UpdateCollectionMetadata task
  • Introduce a separate action to update the embeddings request batch size only. This is needed because, unlike other embedding model data, the batch size can be updating without requiring a backfill. We need to allow users the ability to update the batch size without having to trigger a backfill.
    • UI: Add an update embeddings request batch size form
    • Add a new PUT request/action update_embeddings_request_batch_size, which calls the UpdateEmbeddingsRequestBatchSizeService introduced in !249502 (merged)

References

Issue: [Semantic Search] Persist batch_size for indexing (#600634 - closed)

Screenshots or screen recordings

Screenshots

  • The Update embedding model form has a new field for Embeddings request batch size
  • If a model is configured, there is another form to Update embeddings request batch size only for the current model
  • When switching to a new model, the Update embeddings request batch size allows update to the next model
Embedding model not yet configured Embedding model configured When switching to a new model and a backfill is in progress
Screenshot_2026-08-28_at_09.43.58 Screenshot_2026-08-28_at_09.44.40 Screenshot_2026-08-28_at_09.46.14

Screen Recordings

Scenarios description Screen recording
* Setting an embedding model for the first time with a batch size: successful
* Once the form is submitted, attempt to set the batch size of the next model: error, no backfill is needed when setting a model for the first time, so there is no need to set the embeddings request batch size
* The selected batch size exceeds the GitLab-managed model default: error, for GitLab-managed models, the configured/persisted batch size must be equal to or less than the default for that model
* The selected batch size is within the default: successful
* Updating the embedding model dimensions and batch size: successful
* While there is a backfill in the background, updating the next model batch size: successful

How to set up and validate locally

Setup

  1. Ensure you have GitLab Duo Self-hosted: set up your local AI Gateway, and follow the instructions for Self-managed/Dedicated mode

    If you already have a local AI Gateway setup, ensure the following values:

    • Environment variable: GITLAB_SIMULATE_SAAS=0
    • On the Rails console: ::Gitlab::CurrentSettings.ai_gateway_url points to your local AI Gateway

Set batch size when updating the embedding model

  1. Go to Admin -> Search -> Semantic Search section -> click the Change model or Set model button. This will lead you to the Semantic search Code embeddings page
  2. Configure or update the embedding model and make sure to set the batch size. Verify that the batch size is persisted as the "Next model" batch size, which you can see on the "Overview" section.

Set the batch size only

  1. When switching to a "Next model", verify that you can update the "Next model batch size" by itself.
  2. When not switching to a "Next model" and there is already a "Current model", verify that you can update the "Current model batch size" by itself.

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 #600634 (closed)

Edited by Pam Artiaga

Merge request reports

Loading
Loading