feat: add Google embedding integration (#1304)

bwook00 · Pouyanpi · web-flow · commit c7cceeee2e10 · 2025-10-20T13:26:31.000+02:00
Co-authored-by: Pouyanpi &lt;13303554+Pouyanpi@users.noreply.github.com&gt;
diff --git a/docs/user-guides/configuration-guide.md b/docs/user-guides/configuration-guide.md
@@ -540,6 +540,7 @@ The following tables lists the supported embedding providers:
 | NVIDIA AI Endpoints  | `nvidia_ai_endpoints`  | `nv-embed-v1`, etc.                |
 | AzureOpenAI          | `AzureOpenAI`          | `text-embedding-ada-002`, etc.
 | Cohere               | `cohere`               | `embed-multilingual-v3.0`, etc.    |
+| Google Gemini        | `google`               | `gemini-embedding-001`, etc.       |
 
 ```{note}
 You can use any of the supported models for any of the supported embedding providers.
diff --git a/nemoguardrails/embeddings/providers/__init__.py b/nemoguardrails/embeddings/providers/__init__.py
@@ -18,7 +18,7 @@
 
 from typing import Optional, Type
 
-from . import azureopenai, cohere, fastembed, nim, openai, sentence_transformers
+from . import azureopenai, cohere, fastembed, google, nim, openai, sentence_transformers
 from .base import EmbeddingModel
 from .registry import EmbeddingProviderRegistry
 
@@ -69,6 +69,7 @@ def register_embedding_provider(
 register_embedding_provider(sentence_transformers.SentenceTransformerEmbeddingModel)
 register_embedding_provider(nim.NIMEmbeddingModel)
 register_embedding_provider(nim.NVIDIAAIEndpointsEmbeddingModel)
+register_embedding_provider(google.GoogleEmbeddingModel)
 register_embedding_provider(cohere.CohereEmbeddingModel)
 
 
diff --git a/nemoguardrails/embeddings/providers/google.py b/nemoguardrails/embeddings/providers/google.py
@@ -0,0 +1,115 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import asyncio
+from typing import List, Optional
+
+from .base import EmbeddingModel
+
+
+class GoogleEmbeddingModel(EmbeddingModel):
+    """Embedding model using Gemini API.
+
+    This class is a wrapper for using embedding models powered by Gemini API.
+
+    To use, you must have either:
+
+        1. The ``GOOGLE_API_KEY`` environment variable set with your API key, or
+        2. Pass your API key using the api_key kwarg to the genai.Client().
+
+    Args:
+        embedding_model (str): The name of the embedding model to be used.
+        **kwargs: Additional keyword arguments. Supports:
+            - output_dimensionality (int, optional): Desired output dimensions (128-3072 for gemini-embedding-001).
+              Recommended values: 768, 1536, or 3072. If not specified, API defaults to 3072.
+            - api_key (str, optional): API key for authentication (or use GOOGLE_API_KEY env var).
+            - Other arguments passed to genai.Client() constructor.
+
+    Attributes:
+        model (str): The name of the embedding model.
+        embedding_size (int): The size of the embeddings.
+    """
+
+    engine_name = "google"
+
+    def __init__(self, embedding_model: str, **kwargs):
+        try:
+            from google import genai
+
+        except ImportError:
+            raise ImportError(
+                "Could not import google-genai, please install it with "
+                "`pip install google-genai`."
+            )
+
+        self.model = embedding_model
+        self.output_dimensionality = kwargs.pop("output_dimensionality", None)
+
+        self.client = genai.Client(**kwargs)
+
+        embedding_size_dict = {
+            "gemini-embedding-001": 3072,
+        }
+
+        if self.model in embedding_size_dict:
+            self._embedding_size = (
+                self.output_dimensionality
+                if self.output_dimensionality is not None
+                else embedding_size_dict[self.model]
+            )
+        else:
+            self._embedding_size = None
+
+    @property
+    def embedding_size(self) -> int:
+        if self._embedding_size is None:
+            self._embedding_size = len(self.encode(["test"])[0])
+        return self._embedding_size
+
+    async def encode_async(self, documents: List[str]) -> List[List[float]]:
+        """Encode a list of documents into their corresponding sentence embeddings.
+
+        Args:
+            documents (List[str]): The list of documents to be encoded.
+
+        Returns:
+            List[List[float]]: The list of sentence embeddings, where each embedding is a list of floats.
+        """
+        loop = asyncio.get_running_loop()
+        embeddings = await loop.run_in_executor(None, self.encode, documents)
+
+        return embeddings
+
+    def encode(self, documents: List[str]) -> List[List[float]]:
+        """Encode a list of documents into their corresponding sentence embeddings.
+
+        Args:
+            documents (List[str]): The list of documents to be encoded.
+
+        Returns:
+            List[List[float]]: The list of sentence embeddings, where each embedding is a list of floats.
+
+        Raises:
+            RuntimeError: If the embedding request fails.
+        """
+        try:
+            embed_kwargs = {"model": self.model, "contents": documents}
+            if self.output_dimensionality is not None:
+                embed_kwargs["output_dimensionality"] = self.output_dimensionality
+
+            results = self.client.models.embed_content(**embed_kwargs)
+            return [emb.values for emb in results.embeddings]
+        except Exception as e:
+            raise RuntimeError(f"Failed to retrieve embeddings: {e}") from e
diff --git a/tests/test_configs/with_google_embeddings/config.co b/tests/test_configs/with_google_embeddings/config.co
@@ -0,0 +1,12 @@
+define user ask capabilities
+  "What can you do?"
+  "What can you help me with?"
+  "tell me what you can do"
+  "tell me about you"
+
+define bot inform capabilities
+  "I am an AI assistant that helps answer questions."
+
+define flow
+  user ask capabilities
+  bot inform capabilities
diff --git a/tests/test_configs/with_google_embeddings/config.yml b/tests/test_configs/with_google_embeddings/config.yml
@@ -0,0 +1,8 @@
+models:
+  - type: main
+    engine: openai
+    model: gpt-3.5-turbo-instruct
+
+  - type: embeddings
+    engine: google
+    model: gemini-embedding-001
diff --git a/tests/test_embeddings_google.py b/tests/test_embeddings_google.py
@@ -0,0 +1,95 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+
+import pytest
+
+from nemoguardrails import LLMRails, RailsConfig
+
+try:
+    from nemoguardrails.embeddings.providers.google import GoogleEmbeddingModel
+except ImportError:
+    GoogleEmbeddingModel = None
+
+CONFIGS_FOLDER = os.path.join(os.path.dirname(__file__), ".", "test_configs")
+
+LIVE_TEST_MODE = os.environ.get("LIVE_TEST")
+
+
+@pytest.fixture
+def app():
+    """Load the configuration where we replace FastEmbed with Google."""
+    config = RailsConfig.from_path(
+        os.path.join(CONFIGS_FOLDER, "with_google_embeddings")
+    )
+
+    return LLMRails(config)
+
+
+@pytest.mark.skipif(not LIVE_TEST_MODE, reason="Not in live mode.")
+def test_custom_llm_registration(app):
+    assert isinstance(
+        app.llm_generation_actions.flows_index._model, GoogleEmbeddingModel
+    )
+
+
+@pytest.mark.skipif(not LIVE_TEST_MODE, reason="Not in live mode.")
+@pytest.mark.asyncio
+async def test_live_query():
+    config = RailsConfig.from_path(
+        os.path.join(CONFIGS_FOLDER, "with_google_embeddings")
+    )
+    app = LLMRails(config)
+
+    result = await app.generate_async(
+        messages=[{"role": "user", "content": "tell me what you can do"}]
+    )
+
+    assert result == {
+        "role": "assistant",
+        "content": "I am an AI assistant that helps answer questions.",
+    }
+
+
+@pytest.mark.skipif(not LIVE_TEST_MODE, reason="Not in live mode.")
+def test_live_query_sync(app):
+    result = app.generate(
+        messages=[{"role": "user", "content": "tell me what you can do"}]
+    )
+
+    assert result == {
+        "role": "assistant",
+        "content": "I am an AI assistant that helps answer questions.",
+    }
+
+
+@pytest.mark.skipif(not LIVE_TEST_MODE, reason="Not in live mode.")
+def test_sync_embeddings():
+    model = GoogleEmbeddingModel("gemini-embedding-001")
+
+    result = model.encode(["test"])
+
+    assert len(result[0]) == 3072
+
+
+@pytest.mark.skipif(not LIVE_TEST_MODE, reason="Not in live mode.")
+@pytest.mark.asyncio
+async def test_async_embeddings():
+    model = GoogleEmbeddingModel("gemini-embedding-001")
+
+    result = await model.encode_async(["test"])
+
+    assert len(result[0]) == 3072
diff --git a/tests/test_embeddings_providers_mock.py b/tests/test_embeddings_providers_mock.py
