Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

11.4 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Gemini Embedding 2 provider using the official google-genai SDK."""

from typing import Any, Dict, Optional

from google import genai
from google.genai import types
from google.genai.errors import APIError, ClientError

try:
    from google.genai.types import HttpOptions, HttpRetryOptions

    _HTTP_RETRY_AVAILABLE = True
except ImportError:
    _HTTP_RETRY_AVAILABLE = False

from openviking.models.embedder.base import (
    DenseEmbedderBase,
    EmbedResult,
    truncate_and_normalize,
)
from openviking.models.model_error import model_error_boundary
from openviking_cli.utils import get_logger

logger = get_logger(__name__)

# Keep for backward-compat with existing unit tests that import it
_GEMINI_INPUT_TOKEN_LIMIT = 8192  # Gemini Embedding 2 hard limit

# Per-model token limits (Google API hard limits, from official docs)
_MODEL_TOKEN_LIMITS: Dict[str, int] = {
    "gemini-embedding-2": 8192,
    "gemini-embedding-2-preview": 8192,
    "gemini-embedding-001": 2048,
}
_DEFAULT_TOKEN_LIMIT = 2048  # conservative fallback for unknown future models

# Stable Embedding 2 uses text instructions instead of task_type/title fields.
# https://ai.google.dev/gemini-api/docs/embeddings#task-types
_TASK_INSTRUCTIONS: Dict[str, str] = {
    "RETRIEVAL_QUERY": "task: search result | query: {text}",
    "RETRIEVAL_DOCUMENT": "title: {title} | text: {text}",
    "SEMANTIC_SIMILARITY": "task: sentence similarity | query: {text}",
    "CLASSIFICATION": "task: classification | query: {text}",
    "CLUSTERING": "task: clustering | query: {text}",
    "QUESTION_ANSWERING": "task: question answering | query: {text}",
    "FACT_VERIFICATION": "task: fact checking | query: {text}",
    "CODE_RETRIEVAL_QUERY": "task: code retrieval | query: {text}",
}
_VALID_TASK_TYPES: frozenset = frozenset(_TASK_INSTRUCTIONS)

_ERROR_HINTS: Dict[int, str] = {
    400: "Invalid request — check model name and task_type value.",
    401: "Invalid API key. Verify your GOOGLE_API_KEY or api_key in config.",
    403: "Permission denied. API key may lack access to this model.",
    404: "Model not found: '{model}'. Check spelling (e.g. 'gemini-embedding-2').",
    429: "Resource exhausted. Wait and retry.",
    500: "Gemini service error (Google-side). Retry after a delay.",
    503: "Gemini service unavailable. Retry after a delay.",
}


def _raise_api_error(e: APIError, model: str) -> None:
    hint = _ERROR_HINTS.get(e.code, "")
    # Gemini returns HTTP 400 (not 401) when the API key is invalid
    if e.code == 400 and "api key" in str(e).lower():
        hint = "Invalid API key. Verify your GOOGLE_API_KEY or api_key in config."
    msg = f"Gemini embedding failed (HTTP {e.code})"
    if hint:
        msg += f": {hint.format(model=model)}"
    raise RuntimeError(msg) from e


class GeminiDenseEmbedder(DenseEmbedderBase):
    """Dense embedder backed by Google's Gemini Embedding models.

    REST endpoint: /v1beta/models/{model}:embedContent (SDK handles Parts format internally).
    Input token limit: per-model (8192 for gemini-embedding-2, 2048 for gemini-embedding-001).
    Output dimension: 1–3072 (MRL; recommended 768, 1536, 3072; default 3072).
    Task types: RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT, SEMANTIC_SIMILARITY, CLASSIFICATION,
                CLUSTERING, CODE_RETRIEVAL_QUERY, QUESTION_ANSWERING, FACT_VERIFICATION.
    Non-symmetric: use query_param/document_param in EmbeddingModelConfig.
    """

    # Default output dimensions per model (used when user does not specify `dimension`).
    # gemini-embedding-2:         3072 MRL model — supports 1–3072 via output_dimensionality
    # gemini-embedding-2-preview: 3072 MRL model retained for explicit legacy configurations
    # gemini-embedding-001:       3072 (native 768-dim vectors; 3072 shown as default for MRL compat)
    # text-embedding-004:         768  fixed-dim legacy model, does not support MRL truncation
    # Future gemini-embedding-*:  default 3072 via _default_dimension() fallback
    # Future text-embedding-*:    default 768  via _default_dimension() prefix rule
    supports_multimodal: bool = False  # text-only; multimodal planned separately

    KNOWN_DIMENSIONS: Dict[str, int] = {
        "gemini-embedding-2": 3072,
        "gemini-embedding-2-preview": 3072,
        "gemini-embedding-001": 3072,
        "text-embedding-004": 768,
    }

    @classmethod
    def _default_dimension(cls, model: str) -> int:
        """Return default output dimension for a Gemini model.

        Lookup order:
        1. Exact match in KNOWN_DIMENSIONS
        2. Prefix rule: text-embedding-* → 768 (legacy fixed-dim series)
        3. Fallback: 3072 (gemini-embedding-* MRL models)

        Examples:
            gemini-embedding-2         → 3072 (exact match)
            gemini-embedding-2-preview → 3072 (exact match)
            text-embedding-004         → 768  (exact match)
            text-embedding-005         → 768  (prefix rule — future model)
        """
        if model in cls.KNOWN_DIMENSIONS:
            return cls.KNOWN_DIMENSIONS[model]
        if model.startswith("text-embedding-"):
            return 768
        return 3072

    def __init__(
        self,
        model_name: str = "gemini-embedding-2",
        api_key: Optional[str] = None,
        dimension: Optional[int] = None,
        task_type: Optional[str] = None,
        query_param: Optional[str] = None,
        document_param: Optional[str] = None,
        config: Optional[Dict[str, Any]] = None,
    ):
        super().__init__(model_name, config)
        self.provider = "gemini"
        if not api_key:
            raise ValueError("Gemini provider requires api_key")
        if task_type and task_type not in _VALID_TASK_TYPES:
            raise ValueError(
                f"Invalid task_type '{task_type}'. "
                f"Valid values: {', '.join(sorted(_VALID_TASK_TYPES))}"
            )
        if dimension is not None and not (1 <= dimension <= 3072):
            raise ValueError(f"dimension must be between 1 and 3072, got {dimension}")
        self._client_kwargs: Dict[str, Any] = {"api_key": api_key}
        if _HTTP_RETRY_AVAILABLE:
            self._client_kwargs["http_options"] = HttpOptions(
                retry_options=HttpRetryOptions(attempts=1)
            )
        self.client = genai.Client(**self._client_kwargs)
        self.task_type = task_type
        self.query_param = query_param
        self.document_param = document_param
        self._dimension = dimension or self._default_dimension(model_name)
        self._token_limit = _MODEL_TOKEN_LIMITS.get(model_name, _DEFAULT_TOKEN_LIMIT)

    def _prepare_request(
        self,
        text: str,
        is_query: bool = False,
        *,
        task_type: Optional[str] = None,
        title: Optional[str] = None,
    ) -> tuple[str, types.EmbedContentConfig]:
        """Build the model-specific text and request config."""
        if task_type is None:
            task_type = self.query_param if is_query else self.document_param
        effective_task_type = task_type or self.task_type
        task_type = effective_task_type.upper() if effective_task_type else None
        config = types.EmbedContentConfig(output_dimensionality=self._dimension)
        if self.model_name == "gemini-embedding-2":
            if task_type and task_type not in _VALID_TASK_TYPES:
                raise ValueError(
                    f"Invalid task_type '{effective_task_type}'. "
                    f"Valid values: {', '.join(sorted(_VALID_TASK_TYPES))}"
                )
            if task_type or title:
                text = _TASK_INSTRUCTIONS[task_type or "RETRIEVAL_DOCUMENT"].format(
                    text=text, title=title or "none"
                )
        else:
            config.task_type = task_type
            config.title = title or None
        return text, config

    def __repr__(self) -> str:
        return (
            f"GeminiDenseEmbedder("
            f"model={self.model_name!r}, "
            f"dim={self._dimension}, "
            f"task_type={self.task_type!r})"
        )

    @model_error_boundary
    def embed(
        self,
        text: str,
        is_query: bool = False,
        *,
        task_type: Optional[str] = None,
        title: Optional[str] = None,
    ) -> EmbedResult:
        if not text or not text.strip():
            logger.warning("Empty text passed to embed(), returning zero vector")
            return EmbedResult(dense_vector=[0.0] * self._dimension)
        text, config = self._prepare_request(text, is_query, task_type=task_type, title=title)

        # SDK accepts plain str; converts to REST Parts format internally.
        def _call() -> EmbedResult:
            result = self.client.models.embed_content(
                model=self.model_name,
                contents=text,
                config=config,
            )
            vector = truncate_and_normalize(list(result.embeddings[0].values), self._dimension)
            return EmbedResult(dense_vector=vector)

        try:
            result = self._run_once(
                _call,
                logger=logger,
                operation_name="Gemini embedding",
            )
            # Estimate token usage
            estimated_tokens = self._estimate_tokens(text)
            self.update_token_usage(
                model_name=self.model_name,
                provider="gemini",
                prompt_tokens=estimated_tokens,
                completion_tokens=0,
            )
            return result
        except (APIError, ClientError) as e:
            _raise_api_error(e, self.model_name)

    @model_error_boundary
    async def embed_async(
        self,
        text: str,
        is_query: bool = False,
        *,
        task_type: Optional[str] = None,
        title: Optional[str] = None,
    ) -> EmbedResult:
        if not text or not text.strip():
            logger.warning("Empty text passed to embed_async(), returning zero vector")
            return EmbedResult(dense_vector=[0.0] * self._dimension)

        text, config = self._prepare_request(text, is_query, task_type=task_type, title=title)

        async def _call() -> EmbedResult:
            # Keep creation, use and cleanup on the calling event loop.
            # Account embedders are shared by HTTP and background worker loops.
            with genai.Client(**self._client_kwargs) as client:
                async with client.aio as async_client:
                    result = await async_client.models.embed_content(
                        model=self.model_name,
                        contents=text,
                        config=config,
                    )
            vector = truncate_and_normalize(list(result.embeddings[0].values), self._dimension)
            return EmbedResult(dense_vector=vector)

        try:
            result = await self._run_once_async(
                _call,
                is_query=is_query,
                logger=logger,
                operation_name="Gemini async embedding",
            )
            estimated_tokens = self._estimate_tokens(text)
            self.update_token_usage(
                model_name=self.model_name,
                provider="gemini",
                prompt_tokens=estimated_tokens,
                completion_tokens=0,
            )
            return result
        except (APIError, ClientError) as e:
            _raise_api_error(e, self.model_name)

    def get_dimension(self) -> int:
        return self._dimension

    def close(self):
        self.client.close()