Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Prefix semantic search queries with `query:` for Arctic embedding models (#75718)

Chris Trutera9f80db7fdcd
diff --git a/enterprise/backend/src/metabase_enterprise/semantic_search/embedding.clj b/enterprise/backend/src/metabase_enterprise/semantic_search/embedding.clj
index ad629813a2f..61e9261849e 100644
--- a/enterprise/backend/src/metabase_enterprise/semantic_search/embedding.clj
+++ b/enterprise/backend/src/metabase_enterprise/semantic_search/embedding.clj
@@ -361,6 +361,33 @@
(defmethod pull-model "openai" [_]
(log/debug "OpenAI provider does not require pulling a model"))
+;;;; Query prefixes for asymmetric retrieval models
+
+(def ^:private model-family-query-prefixes
+ "Query prefixes for embedding-model families trained for asymmetric retrieval.
+ These models expect search queries — but not the indexed documents — to carry a fixed prefix."
+ ;; Patterns must be mutually exclusive: lookup scans entries in unspecified order.
+ ;; Keep patterns narrow: a false positive is unfixable without a code change, since the
+ ;; `ee-embedding-query-prefix` setting can only replace a matched prefix, never suppress it.
+ {#"(?i)snowflake-arctic-embed" "query: "})
+
+(defn- default-query-prefix
+ [model-name]
+ (when model-name
+ (some (fn [[pattern prefix]]
+ (when (re-find pattern model-name)
+ prefix))
+ model-family-query-prefixes)))
+
+(defn prefix-search-query
+ "Prepend the query prefix expected by `embedding-model` to `search-string`.
+ The `ee-embedding-query-prefix` setting overrides the per-model-family default and is prepended verbatim.
+ Returns `search-string` unchanged when neither applies."
+ [embedding-model search-string]
+ (str (or (not-empty (semantic-settings/ee-embedding-query-prefix))
+ (default-query-prefix (:model-name embedding-model)))
+ search-string))
+
;;;; Global embedding model
(defn get-configured-model
diff --git a/enterprise/backend/src/metabase_enterprise/semantic_search/index.clj b/enterprise/backend/src/metabase_enterprise/semantic_search/index.clj
index 5544c7e7763..71235ab3c02 100644
--- a/enterprise/backend/src/metabase_enterprise/semantic_search/index.clj
+++ b/enterprise/backend/src/metabase_enterprise/semantic_search/index.clj
@@ -872,7 +872,8 @@
embedding (tracing/with-span :search "search.semantic.embedding"
{:search.semantic/provider (:provider embedding-model)
:search.semantic/model-name (:model-name embedding-model)}
- (embedding/get-embedding embedding-model search-string
+ (embedding/get-embedding embedding-model
+ (embedding/prefix-search-query embedding-model search-string)
{:type :query :record-tokens? true}))
embedding-time-ms (u/since-ms timer)
diff --git a/enterprise/backend/src/metabase_enterprise/semantic_search/settings.clj b/enterprise/backend/src/metabase_enterprise/semantic_search/settings.clj
index c1cda1803f4..ff2d055b6fb 100644
--- a/enterprise/backend/src/metabase_enterprise/semantic_search/settings.clj
+++ b/enterprise/backend/src/metabase_enterprise/semantic_search/settings.clj
@@ -34,6 +34,18 @@
:export? false
:doc false)
+(defsetting ee-embedding-query-prefix
+ (deferred-tru
+ (str "Prefix prepended to search queries (but not indexed documents) before embedding them, as expected by "
+ "asymmetric retrieval models such as the snowflake-arctic-embed family (`query: `). It is prepended "
+ "verbatim, so include any trailing separator. Leave empty to use the default for the model family."))
+ :encryption :no
+ :visibility :settings-manager
+ :default nil
+ :type :string
+ :export? false
+ :doc false)
+
(defsetting ee-embedding-model-dimensions
(deferred-tru "Set the dimension size for the selected embedding model")
:encryption :no
diff --git a/enterprise/backend/test/metabase_enterprise/semantic_search/embedding_test.clj b/enterprise/backend/test/metabase_enterprise/semantic_search/embedding_test.clj
index 023b50bd4fc..3e4ad35b222 100644
--- a/enterprise/backend/test/metabase_enterprise/semantic_search/embedding_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/semantic_search/embedding_test.clj
@@ -57,6 +57,19 @@
(mt/with-temporary-setting-values [ee-embedding-model-dimensions 768]
(is (= 768 (:vector-dimensions (embedding/get-configured-model)))))))
+(deftest prefix-search-query-test
+ (let [arctic {:provider "ai-service" :model-name "Snowflake/snowflake-arctic-embed-l-v2.0" :vector-dimensions 1024}
+ openai {:provider "openai" :model-name "text-embedding-3-small" :vector-dimensions 1536}]
+ (mt/with-temporary-setting-values [ee-embedding-query-prefix nil]
+ (testing "arctic-family models get the `query: ` prefix by default"
+ (is (= "query: hello" (embedding/prefix-search-query arctic "hello"))))
+ (testing "models without a known family default are left unprefixed"
+ (is (= "hello" (embedding/prefix-search-query openai "hello")))))
+ (testing "the setting overrides the model-family default, verbatim"
+ (mt/with-temporary-setting-values [ee-embedding-query-prefix "search_query: "]
+ (is (= "search_query: hello" (embedding/prefix-search-query arctic "hello")))
+ (is (= "search_query: hello" (embedding/prefix-search-query openai "hello")))))))
+
(deftest test-openai-provider-validation
(testing "OpenAIProvider throws when API key not configured"
(let [embedding-model {:provider "openai"