Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(embedder): add non-symmetric embedding support for query/document (#608)
Wong Chihung5260b817a080
diff --git a/openviking/models/embedder/jina_embedders.py b/openviking/models/embedder/jina_embedders.pyindex 12f45e4d3..1d8420709 100644--- a/openviking/models/embedder/jina_embedders.py+++ b/openviking/models/embedder/jina_embedders.py@@ -22,18 +22,32 @@ class JinaDenseEmbedder(DenseEmbedderBase):"""Jina AI Dense Embedder ImplementationUses Jina AI embedding API via OpenAI-compatible client.- Supports task-specific embeddings and Matryoshka dimension reduction.+ Supports task-specific embeddings (non-symmetric) and Matryoshka dimension reduction.++ Jina models are non-symmetric by default and require the 'task' parameter to distinguish+ between query and document embeddings. This is different from official OpenAI models,+ which are symmetric and do not support the input_type parameter.Example:- >>> embedder = JinaDenseEmbedder(+ >>> # Query embedding+ >>> query_embedder = JinaDenseEmbedder(... model_name="jina-embeddings-v5-text-small",... api_key="jina_xxx",... dimension=512,- ... task="retrieval.query"+ ... context="query"... )- >>> result = embedder.embed("Hello world")- >>> print(len(result.dense_vector))+ >>> query_vector = query_embedder.embed("search query")+ >>> print(len(query_vector.dense_vector))512++ >>> # Document embedding+ >>> doc_embedder = JinaDenseEmbedder(+ ... model_name="jina-embeddings-v5-text-small",+ ... api_key="jina_xxx",+ ... dimension=512,+ ... context="document"+ ... )+ >>> doc_vector = doc_embedder.embed("document content")"""def __init__(@@ -42,7 +56,9 @@ class JinaDenseEmbedder(DenseEmbedderBase):api_key: Optional[str] = None,api_base: Optional[str] = None,dimension: Optional[int] = None,- task: Optional[str] = None,+ context: Optional[str] = None,+ query_param: str = "retrieval.query",+ document_param: str = "retrieval.passage",late_chunking: Optional[bool] = None,config: Optional[Dict[str, Any]] = None,):@@ -53,9 +69,15 @@ class JinaDenseEmbedder(DenseEmbedderBase):api_key: API key, requiredapi_base: API base URL, defaults to https://api.jina.ai/v1dimension: Dimension for Matryoshka reduction, optional- task: Task type for task-specific embeddings, optional.- Valid values: retrieval.query, retrieval.passage,- text-matching, classification, separation+ context: Embedding context, either 'query' or 'document'. Jina models are+ non-symmetric by default; task is always sent unless context is None.+ Pass None to disable task (e.g. for symmetric deployments via OpenAI+ compatible endpoint).+ query_param: Task value for query-side embeddings. Defaults to 'retrieval.query'.+ Override for models with different task naming conventions.+ document_param: Task value for document-side embeddings. Defaults to+ 'retrieval.passage'. Override for models with different task+ naming conventions.late_chunking: Enable late chunking via extra_body, optionalconfig: Additional configuration dict@@ -67,7 +89,12 @@ class JinaDenseEmbedder(DenseEmbedderBase):self.api_key = api_keyself.api_base = api_base or "https://api.jina.ai/v1"self.dimension = dimension- self.task = task+ if context == "query":+ self.task: Optional[str] = query_param+ elif context == "document":+ self.task = document_param+ else:+ self.task = Noneself.late_chunking = late_chunkingif not self.api_key:diff --git a/openviking/models/embedder/openai_embedders.py b/openviking/models/embedder/openai_embedders.pyindex 48805e90e..d0a0fe7f2 100644--- a/openviking/models/embedder/openai_embedders.py+++ b/openviking/models/embedder/openai_embedders.py@@ -19,11 +19,17 @@ logger = logging.getLogger(__name__)class OpenAIDenseEmbedder(DenseEmbedderBase):- """OpenAI Dense Embedder Implementation+ """OpenAI-Compatible Dense Embedder Implementation- Supports OpenAI embedding models such as text-embedding-3-small, text-embedding-3-large, etc.+ Supports OpenAI embedding models (e.g., text-embedding-3-small, text-embedding-3-large)+ and OpenAI-compatible third-party models that support non-symmetric embeddings.++ Note: Official OpenAI models are symmetric and do not support the input_type parameter.+ Non-symmetric mode (context='query'/'document') is only supported by OpenAI-compatible+ third-party models (e.g., BGE-M3, Jina, Cohere, etc.) that implement the input_type parameter.Example:+ >>> # Symmetric mode (official OpenAI models)>>> embedder = OpenAIDenseEmbedder(... model_name="text-embedding-3-small",... api_key="sk-xxx",@@ -32,6 +38,17 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):>>> result = embedder.embed("Hello world")>>> print(len(result.dense_vector))1536++ >>> # Non-symmetric mode (OpenAI-compatible third-party models)+ >>> query_embedder = OpenAIDenseEmbedder(+ ... model_name="bge-m3",+ ... api_key="your-api-key",+ ... api_base="https://your-api-endpoint.com/v1",+ ... context="query",+ ... query_param="query",+ ... document_param="passage"+ ... )+ >>> query_vector = query_embedder.embed("search query")"""def __init__(@@ -40,21 +57,46 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):api_key: Optional[str] = None,api_base: Optional[str] = None,dimension: Optional[int] = None,+ context: Optional[str] = None,+ query_param: Optional[str] = None,+ document_param: Optional[str] = None,config: Optional[Dict[str, Any]] = None,max_tokens: Optional[int] = None,):- """Initialize OpenAI Dense Embedder+ """Initialize OpenAI-Compatible Dense EmbedderArgs:- model_name: OpenAI model name, defaults to text-embedding-3-small+ model_name: Model name. For official OpenAI models (e.g., text-embedding-3-small),+ use symmetric mode (context=None, query_param=None, document_param=None).+ For OpenAI-compatible third-party models (e.g., BGE-M3, Jina, Cohere), use+ non-symmetric mode with context='query'/'document'.api_key: API key, if None will read from env vars (OPENVIKING_EMBEDDING_API_KEY or OPENAI_API_KEY)- api_base: API base URL, optional+ api_base: API base URL, optional. Required for third-party OpenAI-compatible APIs.dimension: Dimension (if model supports), optional+ context: Embedding context, either 'query' or 'document'. When both query_param+ and document_param are None (the default), the model is treated as symmetric+ and no input_type is sent to the API. Set query_param and/or document_param+ to enable non-symmetric mode. Only supported by OpenAI-compatible third-party+ models, not official OpenAI models.+ query_param: The input_type value for query-side embeddings, e.g. 'query' or+ 'search_query'. Defaults to 'query' when non-symmetric mode is active.+ Setting this (or document_param) activates non-symmetric mode.+ Only supported by OpenAI-compatible third-party models.+ document_value: The input_type value for document-side embeddings, e.g. 'passage'+ or 'document'. Defaults to 'passage' when non-symmetric mode is+ active. Setting this (or query_value) activates non-symmetric mode.+ Only supported by OpenAI-compatible third-party models.config: Additional configuration dictmax_tokens: Maximum token count per embedding request, None to use default (8000)Raises:ValueError: If api_key is not provided and env vars are not set++ Note:+ Official OpenAI models (e.g., text-embedding-3-small, text-embedding-3-large) are+ symmetric and do not support the input_type parameter. Non-symmetric mode is only+ supported by OpenAI-compatible third-party models (e.g., BGE-M3, Jina, Cohere) that+ implement the input_type parameter."""super().__init__(model_name, config, max_tokens=max_tokens)@@ -62,6 +104,19 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):self.api_base = api_baseself.dimension = dimension+ # Symmetric by default: only activate input_type if user explicitly sets either value+ non_symmetric = query_param is not None or document_param is not None+ if not non_symmetric:+ self.input_type: Optional[str] = None+ elif context == "query":+ self.input_type = query_param if query_param is not None else "query"+ elif context == "document":+ self.input_type = document_param if document_param is not None else "passage"+ else:+ self.input_type = None++ if not self.api_key:+ raise ValueError("api_key is required")# Allow missing api_key when api_base is set (e.g. local OpenAI-compatible servers)if not self.api_key and not self.api_base:raise ValueError("api_key is required (or set api_base for local servers)")@@ -134,6 +189,18 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):output_tokens,)+ def _build_extra_body(self) -> Optional[Dict[str, Any]]:+ """Build extra_body dict for OpenAI-compatible parameters++ Returns:+ Dict containing input_type if non-symmetric mode is active.+ Only supported by OpenAI-compatible third-party models.+ """+ extra_body = {}+ if self.input_type is not None:+ extra_body["input_type"] = self.input_type+ return extra_body if extra_body else None+def _embed_single(self, text: str) -> EmbedResult:"""Perform raw embedding without chunking logic.@@ -147,9 +214,11 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):RuntimeError: When API call fails"""try:- kwargs = {"input": text, "model": self.model_name}- if self.dimension:- kwargs["dimensions"] = self.dimension+ kwargs: Dict[str, Any] = {"input": text, "model": self.model_name}++ extra_body = self._build_extra_body()+ if extra_body:+ kwargs["extra_body"] = extra_bodyresponse = self.client.embeddings.create(**kwargs)self._update_telemetry_token_usage(response)@@ -211,9 +280,11 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):if short_texts:try:- kwargs = {"input": short_texts, "model": self.model_name}- if self.dimension:- kwargs["dimensions"] = self.dimension+ kwargs: Dict[str, Any] = {"input": short_texts, "model": self.model_name}++ extra_body = self._build_extra_body()+ if extra_body:+ kwargs["extra_body"] = extra_bodyresponse = self.client.embeddings.create(**kwargs)self._update_telemetry_token_usage(response)diff --git a/openviking/service/core.py b/openviking/service/core.pyindex 11f20037c..b07bdb840 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -96,7 +96,7 @@ class OpenVikingService:)# Initialize embedder- self._embedder = config.embedding.get_embedder()+ self._embedder = config.embedding.get_query_embedder()logger.info(f"Initialized embedder (dim {config.embedding.dimension}, sparse {self._embedder.is_sparse})")@@ -132,15 +132,15 @@ class OpenVikingService:logger.warning("AGFS client not initialized, skipping queue manager")# Initialize VikingDBManager with QueueManager- self._vikingdb_manager = VikingDBManager(- vectordb_config=config.vectordb, queue_manager=self._queue_manager- )+ self._vikingdb_manager = VikingDBManager(vectordb_config=config.vectordb, queue_manager=self._queue_manager)# Configure queues if QueueManager is availableif self._queue_manager:self._queue_manager.setup_standard_queues(self._vikingdb_manager)- # Initialize TransactionManager+ # Initialize TransactionManager (fail-fast if AGFS missing)+ if self._agfs_client is None:+ raise RuntimeError("AGFS client not initialized for TransactionManager")self._transaction_manager = init_transaction_manager(agfs=self._agfs_client)@property@@ -236,8 +236,15 @@ class OpenVikingService:enable_recorder = os.environ.get("OPENVIKING_ENABLE_RECORDER", "").lower() == "true"# Create context collection+ if self._vikingdb_manager is None:+ raise RuntimeError("VikingDBManager not initialized")await init_context_collection(self._vikingdb_manager)+ if self._agfs_client is None:+ raise RuntimeError("AGFS client not initialized")+ if self._embedder is None:+ raise RuntimeError("Embedder not initialized")+self._viking_fs = init_viking_fs(agfs=self._agfs_client,query_embedder=self._embedder,@@ -261,7 +268,9 @@ class OpenVikingService:)# Initialize processors- self._resource_processor = ResourceProcessor(vikingdb=self._vikingdb_manager)+ self._resource_processor = ResourceProcessor(+ vikingdb=self._vikingdb_manager,+ )self._skill_processor = SkillProcessor(vikingdb=self._vikingdb_manager)self._session_compressor = SessionCompressor(vikingdb=self._vikingdb_manager)diff --git a/openviking/session/memory_deduplicator.py b/openviking/session/memory_deduplicator.pyindex b04f37067..c38be27e0 100644--- a/openviking/session/memory_deduplicator.py+++ b/openviking/session/memory_deduplicator.py@@ -85,7 +85,8 @@ class MemoryDeduplicator:):"""Initialize deduplicator."""self.vikingdb = vikingdb- self.embedder = self.vikingdb.get_embedder()+ config = get_openviking_config()+ self.embedder = config.embedding.get_query_embedder()async def deduplicate(self,diff --git a/openviking/storage/collection_schemas.py b/openviking/storage/collection_schemas.pyindex 944f121c2..ea33b5d9b 100644--- a/openviking/storage/collection_schemas.py+++ b/openviking/storage/collection_schemas.py@@ -124,8 +124,11 @@ async def init_context_collection(storage) -> bool:config = get_openviking_config()name = config.storage.vectordb.namevector_dim = config.embedding.dimension- schema = CollectionSchemas.context_collection(name, vector_dim)- return await storage.create_collection(name, schema)+ if not name:+ raise ValueError("Vector DB collection name is required")+ collection_name = name+ schema = CollectionSchemas.context_collection(collection_name, vector_dim)+ return await storage.create_collection(collection_name, schema)class TextEmbeddingHandler(DequeueHandlerBase):@@ -162,7 +165,7 @@ class TextEmbeddingHandler(DequeueHandlerBase):def _initialize_embedder(self, config: "OpenVikingConfig"):"""Initialize the embedder instance from config."""- self._embedder = config.embedding.get_embedder()+ self._embedder = config.embedding.get_document_embedder()@classmethoddef _merge_request_stats(diff --git a/openviking_cli/utils/config/embedding_config.py b/openviking_cli/utils/config/embedding_config.pyindex 59215eb72..f45e88287 100644--- a/openviking_cli/utils/config/embedding_config.py+++ b/openviking_cli/utils/config/embedding_config.py@@ -1,6 +1,6 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: Apache-2.0-from typing import Any, Optional+from typing import Any, Optional, castfrom pydantic import BaseModel, Field, model_validator@@ -14,6 +14,30 @@ class EmbeddingModelConfig(BaseModel):dimension: Optional[int] = Field(default=None, description="Embedding dimension")batch_size: int = Field(default=32, description="Batch size for embedding generation")input: str = Field(default="multimodal", description="Input type: 'text' or 'multimodal'")+ input_type: Optional[str] = Field(+ default=None,+ description="Input type for non-contextual OpenAI embeddings: 'query', 'document', or 'passage'",+ )+ query_param: Optional[str] = Field(+ default=None,+ description=(+ "Parameter value for query-side embeddings when using get_query_embedder(). "+ "For OpenAI-compatible models, this maps to 'input_type' (e.g., 'query', 'search_query'). "+ "For Jina models, this maps to 'task' (e.g., 'retrieval.query'). "+ "Setting this or document_param activates non-symmetric mode. "+ "Leave both unset for symmetric models."+ ),+ )+ document_param: Optional[str] = Field(+ default=None,+ description=(+ "Parameter value for document-side embeddings when using get_document_embedder(). "+ "For OpenAI-compatible models, this maps to 'input_type' (e.g., 'passage', 'document'). "+ "For Jina models, this maps to 'task' (e.g., 'retrieval.passage'). "+ "Setting this or query_param activates non-symmetric mode. "+ "Leave both unset for symmetric models."+ ),+ )provider: Optional[str] = Field(default="volcengine",description="Provider type: 'openai', 'volcengine', 'vikingdb', 'jina', 'ollama'",@@ -43,6 +67,10 @@ class EmbeddingModelConfig(BaseModel):if backend is not None and provider is None:data["provider"] = backend+ for key in ("input_type", "query_value", "document_value", "query_task", "document_task"):+ value = data.get(key)+ if isinstance(value, str):+ data[key] = value.lower()return data@model_validator(mode="after")@@ -128,13 +156,16 @@ class EmbeddingConfig(BaseModel):)return self- def _create_embedder(self, provider: str, embedder_type: str, config: EmbeddingModelConfig):+ def _create_embedder(self, provider: str, embedder_type: str, config: EmbeddingModelConfig, context: Optional[str] = None):"""Factory method to create embedder instance based on provider and type.Args:- provider: Provider type ('openai', 'volcengine', 'vikingdb')+ provider: Provider type ('openai', 'volcengine', 'vikingdb', 'jina')embedder_type: Embedder type ('dense', 'sparse', 'hybrid')config: EmbeddingModelConfig instance+ context: Optional embedding context ('query' or 'document') for non-symmetric models.+ When provided, the embedder will apply the appropriate input_type or task.+ Leave None for symmetric models or when using a single embedder for all inputs.Returns:Embedder instance@@ -162,6 +193,9 @@ class EmbeddingConfig(BaseModel):"api_key": cfg.api_key or "no-key", # Placeholder for local OpenAI-compatible servers"api_base": cfg.api_base,"dimension": cfg.dimension,+ "context": context,+ **({"query_param": cfg.query_param} if cfg.query_param else {}),+ **({"document_param": cfg.document_param} if cfg.document_param else {}),"max_tokens": cfg.max_tokens,},),@@ -237,6 +271,9 @@ class EmbeddingConfig(BaseModel):"api_key": cfg.api_key,"api_base": cfg.api_base,"dimension": cfg.dimension,+ "context": context,+ **({"query_param": cfg.query_param} if cfg.query_param else {}),+ **({"document_param": cfg.document_param} if cfg.document_param else {}),},),# Ollama: local OpenAI-compatible embedding server, no real API key needed@@ -273,22 +310,57 @@ class EmbeddingConfig(BaseModel):ValueError: If configuration is invalid or unsupported"""from openviking.models.embedder import CompositeHybridEmbedder+ from openviking.models.embedder.base import DenseEmbedderBase, SparseEmbedderBaseif self.hybrid:- return self._create_embedder(self.hybrid.provider.lower(), "hybrid", self.hybrid)+ provider = self._require_provider(self.hybrid.provider)+ return self._create_embedder(provider, "hybrid", self.hybrid)if self.dense and self.sparse:- dense_embedder = self._create_embedder(self.dense.provider.lower(), "dense", self.dense)+ dense_provider = self._require_provider(self.dense.provider)+ dense_embedder = cast(+ DenseEmbedderBase,+ self._create_embedder(dense_provider, "dense", self.dense),+ )sparse_embedder = self._create_embedder(- self.sparse.provider.lower(), "sparse", self.sparse+ self._require_provider(self.sparse.provider), "sparse", self.sparse)+ sparse_embedder = cast(SparseEmbedderBase, sparse_embedder)return CompositeHybridEmbedder(dense_embedder, sparse_embedder)if self.dense:- return self._create_embedder(self.dense.provider.lower(), "dense", self.dense)+ provider = self._require_provider(self.dense.provider)+ return self._create_embedder(provider, "dense", self.dense)raise ValueError("No embedding configuration found (dense, sparse, or hybrid)")+ def get_query_embedder(self):+ """Get embedder instance for query embeddings."""+ return self._get_contextual_embedder("query")++ def get_document_embedder(self):+ """Get embedder instance for document/passage embeddings."""+ return self._get_contextual_embedder("document")++ def _get_contextual_embedder(self, context: str):+ if not self.dense:+ return self.get_embedder()++ provider = (self.dense.provider or "").lower()+ if provider == "openai":+ # OpenAI models are symmetric by default (no input_type sent).+ # Non-symmetric mode is activated implicitly when the user sets+ # query_param or document_param in the config.+ non_symmetric = self.dense.query_param is not None or self.dense.document_param is not None+ effective_context = context if non_symmetric else None+ return self._create_embedder(provider, "dense", self.dense, context=effective_context)++ if provider == "jina":+ # Jina models are non-symmetric by default (task is always sent).+ return self._create_embedder(provider, "dense", self.dense, context=context)++ return self.get_embedder()+@propertydef dimension(self) -> int:"""Get dimension from active config."""@@ -301,3 +373,9 @@ class EmbeddingConfig(BaseModel):if self.dense:return self.dense.dimension or 2048return 2048++ @staticmethod+ def _require_provider(provider: Optional[str]) -> str:+ if not provider:+ raise ValueError("Embedding provider is required")+ return provider.lower()diff --git a/openviking_cli/utils/config/vlm_config.py b/openviking_cli/utils/config/vlm_config.pyindex 4e5942075..eea7682bf 100644--- a/openviking_cli/utils/config/vlm_config.py+++ b/openviking_cli/utils/config/vlm_config.py@@ -148,9 +148,11 @@ class VLMConfig(BaseModel):return self.get_vlm_instance().get_completion(prompt, thinking)async def get_completion_async(- self, prompt: str, thinking: bool = False, max_retries: int = 0+ self, prompt: str, thinking: bool = False, max_retries: int | None = None) -> str:- """Get LLM completion asynchronously, max_retries=0 means no retry."""+ """Get LLM completion asynchronously. Uses self.max_retries if not specified."""+ if max_retries is None:+ max_retries = self.max_retriesreturn await self.get_vlm_instance().get_completion_async(prompt, thinking, max_retries)def is_available(self) -> bool:diff --git a/tests/misc/test_embedding_input_type.py b/tests/misc/test_embedding_input_type.pynew file mode 100644index 000000000..4ee8f6607--- /dev/null+++ b/tests/misc/test_embedding_input_type.py@@ -0,0 +1,384 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: Apache-2.0+"""Tests for non-symmetric query/document embedding passthrough.++Tests EmbeddingConfig's ability to create context-specific embedders:+- OpenAI: fixed query input_type when document input_type is set+- Jina: fixed query task when task_document is set+"""++from unittest.mock import MagicMock, patch++import pytest++from openviking_cli.utils.config.embedding_config import EmbeddingConfig, EmbeddingModelConfig+++class TestEmbeddingModelConfigContextFields:+ """Test EmbeddingModelConfig fields for context-specific parameters."""++ def test_openai_query_document_param_fields_accept_values(self):+ """OpenAI config should accept query_param and document_param."""+ config = EmbeddingModelConfig(+ model="text-embedding-3-small",+ provider="openai",+ api_key="sk-test",+ query_param="search_query",+ document_param="search_document",+ )+ assert config.query_param == "search_query"+ assert config.document_param == "search_document"++ def test_openai_legacy_input_type_field_accept_value(self):+ """OpenAI config should accept legacy input_type field."""+ config = EmbeddingModelConfig(+ model="text-embedding-3-small",+ provider="openai",+ api_key="sk-test",+ input_type="search_query",+ )+ assert config.input_type == "search_query"++ def test_jina_query_document_param_fields_accept_values(self):+ """Jina config should accept query_param and document_param."""+ config = EmbeddingModelConfig(+ model="jina-embeddings-v5-text-small",+ provider="jina",+ api_key="jina-test",+ query_param="retrieval.query",+ document_param="retrieval.passage",+ )+ assert config.query_param == "retrieval.query"+ assert config.document_param == "retrieval.passage"++ def test_context_fields_default_to_none(self):+ """Fields should default to None when not specified."""+ config = EmbeddingModelConfig(+ model="text-embedding-3-small",+ provider="openai",+ api_key="sk-test",+ )+ assert config.input_type is None+ assert config.query_param is None+ assert config.document_param is None+ assert config.query_param is None+ assert config.document_param is None++ def test_query_document_param_lowercase_normalization(self):+ """Query/document value should be normalized to lowercase."""+ config = EmbeddingModelConfig(+ model="text-embedding-3-small",+ provider="openai",+ api_key="sk-test",+ query_param="SEARCH_QUERY",+ document_param="Search_Document",+ )+ assert config.query_param == "search_query"+ assert config.document_param == "search_document"++ def test_legacy_input_type_lowercase_normalization(self):+ """Legacy input_type should be normalized to lowercase."""+ config = EmbeddingModelConfig(+ model="text-embedding-3-small",+ provider="openai",+ api_key="sk-test",+ input_type="SEARCH_QUERY",+ )+ assert config.input_type == "search_query"++ def test_query_document_param_lowercase_normalization(self):+ """Query/document task values should be normalized to lowercase."""+ config = EmbeddingModelConfig(+ model="jina-embeddings-v5-text-small",+ provider="jina",+ api_key="jina-test",+ query_param="RETRIEVAL.QUERY",+ document_param="Retrieval.Passage",+ )+ assert config.query_param == "retrieval.query"+ assert config.document_param == "retrieval.passage"+++class TestEmbeddingConfigContextualEmbedders:+ """Test EmbeddingConfig get_query_embedder and get_document_embedder."""++ @patch("openviking.models.embedder.OpenAIDenseEmbedder")+ def test_get_query_embedder_openai_passes_context_query(self, mock_embedder_class):+ """get_query_embedder should pass context='query' when query_param is set."""+ mock_embedder_class.return_value = MagicMock()+ config = EmbeddingConfig(+ dense=EmbeddingModelConfig(+ model="text-embedding-3-small",+ provider="openai",+ api_key="sk-test",+ query_param="search_query",+ document_param="search_document",+ )+ )++ config.get_query_embedder()++ mock_embedder_class.assert_called_once()+ call_kwargs = mock_embedder_class.call_args[1]+ assert call_kwargs.get("context") == "query"+ assert call_kwargs.get("query_param") == "search_query"++ @patch("openviking.models.embedder.OpenAIDenseEmbedder")+ def test_get_document_embedder_openai_passes_context_document(self, mock_embedder_class):+ """get_document_embedder should pass context='document' when document_param is set."""+ mock_embedder_class.return_value = MagicMock()+ config = EmbeddingConfig(+ dense=EmbeddingModelConfig(+ model="text-embedding-3-small",+ provider="openai",+ api_key="sk-test",+ query_param="search_query",+ document_param="search_document",+ )+ )++ config.get_document_embedder()++ mock_embedder_class.assert_called_once()+ call_kwargs = mock_embedder_class.call_args[1]+ assert call_kwargs.get("context") == "document"+ assert call_kwargs.get("document_param") == "search_document"++ @patch("openviking.models.embedder.JinaDenseEmbedder")+ def test_get_query_embedder_jina_passes_context_query(self, mock_embedder_class):+ """get_query_embedder should pass context='query' when query_param is set."""+ mock_embedder_class.return_value = MagicMock()+ config = EmbeddingConfig(+ dense=EmbeddingModelConfig(+ model="jina-embeddings-v5-text-small",+ provider="jina",+ api_key="jina-test",+ query_param="retrieval.query",+ document_param="retrieval.passage",+ )+ )++ config.get_query_embedder()++ mock_embedder_class.assert_called_once()+ call_kwargs = mock_embedder_class.call_args[1]+ assert call_kwargs.get("context") == "query"+ assert call_kwargs.get("query_param") == "retrieval.query"++ @patch("openviking.models.embedder.JinaDenseEmbedder")+ def test_get_document_embedder_jina_passes_context_document(self, mock_embedder_class):+ """get_document_embedder should pass context='document' when document_param is set."""+ mock_embedder_class.return_value = MagicMock()+ config = EmbeddingConfig(+ dense=EmbeddingModelConfig(+ model="jina-embeddings-v5-text-small",+ provider="jina",+ api_key="jina-test",+ query_param="retrieval.query",+ document_param="retrieval.passage",+ )+ )++ config.get_document_embedder()++ mock_embedder_class.assert_called_once()+ call_kwargs = mock_embedder_class.call_args[1]+ assert call_kwargs.get("context") == "document"+ assert call_kwargs.get("document_param") == "retrieval.passage"++ @patch("openviking.models.embedder.OpenAIDenseEmbedder")+ def test_get_query_embedder_openai_no_context_when_not_set(self, mock_embedder_class):+ """get_query_embedder should pass None context when query_param is not set."""+ mock_embedder_class.return_value = MagicMock()+ config = EmbeddingConfig(+ dense=EmbeddingModelConfig(+ model="text-embedding-3-small",+ provider="openai",+ api_key="sk-test",+ )+ )++ config.get_query_embedder()++ mock_embedder_class.assert_called_once()+ call_kwargs = mock_embedder_class.call_args[1]+ assert call_kwargs.get("context") is None++ @patch("openviking.models.embedder.OpenAIDenseEmbedder")+ def test_get_document_embedder_openai_no_context_when_not_set(self, mock_embedder_class):+ """get_document_embedder should pass None context when document_param is not set."""+ mock_embedder_class.return_value = MagicMock()+ config = EmbeddingConfig(+ dense=EmbeddingModelConfig(+ model="text-embedding-3-small",+ provider="openai",+ api_key="sk-test",+ )+ )++ config.get_document_embedder()++ mock_embedder_class.assert_called_once()+ call_kwargs = mock_embedder_class.call_args[1]+ assert call_kwargs.get("context") is None++ @patch("openviking.models.embedder.JinaDenseEmbedder")+ def test_get_query_embedder_jina_no_context_when_not_set(self, mock_embedder_class):+ """get_query_embedder should pass None context when query_param is not set."""+ mock_embedder_class.return_value = MagicMock()+ config = EmbeddingConfig(+ dense=EmbeddingModelConfig(+ model="jina-embeddings-v5-text-small",+ provider="jina",+ api_key="jina-test",+ )+ )++ config.get_query_embedder()++ mock_embedder_class.assert_called_once()+ call_kwargs = mock_embedder_class.call_args[1]+ assert call_kwargs.get("context") is None++ @patch("openviking.models.embedder.JinaDenseEmbedder")+ def test_get_document_embedder_jina_no_context_when_not_set(self, mock_embedder_class):+ """get_document_embedder should pass None context when document_param is not set."""+ mock_embedder_class.return_value = MagicMock()+ config = EmbeddingConfig(+ dense=EmbeddingModelConfig(+ model="jina-embeddings-v5-text-small",+ provider="jina",+ api_key="jina-test",+ )+ )++ config.get_document_embedder()++ mock_embedder_class.assert_called_once()+ call_kwargs = mock_embedder_class.call_args[1]+ assert call_kwargs.get("task") is None+++class TestOpenAIDenseEmbedderInputType:+ """Test OpenAIDenseEmbedder input_type support in embed and embed_batch."""++ @patch("openai.OpenAI")+ def test_embed_passes_input_type_in_extra_body(self, mock_openai_class):+ """embed should pass input_type in extra_body when provided."""+ from openviking.models.embedder import OpenAIDenseEmbedder++ mock_client = MagicMock()+ mock_response = MagicMock()+ mock_response.data = [MagicMock(embedding=[0.1] * 1536)]+ mock_client.embeddings.create.return_value = mock_response+ mock_openai_class.return_value = mock_client++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="sk-test",+ dimension=1536,+ input_type="search_query",+ )++ embedder.embed("test query")++ mock_client.embeddings.create.assert_called_once()+ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert call_kwargs.get("extra_body") == {"input_type": "search_query"}++ @patch("openai.OpenAI")+ def test_embed_batch_passes_input_type_in_extra_body(self, mock_openai_class):+ """embed_batch should pass input_type in extra_body when provided."""+ from openviking.models.embedder import OpenAIDenseEmbedder++ mock_client = MagicMock()+ mock_response = MagicMock()+ mock_response.data = [MagicMock(embedding=[0.1] * 1536), MagicMock(embedding=[0.2] * 1536)]+ mock_client.embeddings.create.return_value = mock_response+ mock_openai_class.return_value = mock_client++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="sk-test",+ dimension=1536,+ input_type="search_document",+ )++ embedder.embed_batch(["doc 1", "doc 2"])++ mock_client.embeddings.create.assert_called_once()+ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert call_kwargs.get("extra_body") == {"input_type": "search_document"}++ @patch("openai.OpenAI")+ def test_embed_no_extra_body_when_input_type_not_set(self, mock_openai_class):+ """embed should not set extra_body when input_type is None."""+ from openviking.models.embedder import OpenAIDenseEmbedder++ mock_client = MagicMock()+ mock_response = MagicMock()+ mock_response.data = [MagicMock(embedding=[0.1] * 1536)]+ mock_client.embeddings.create.return_value = mock_response+ mock_openai_class.return_value = mock_client++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="sk-test",+ dimension=1536,+ )++ embedder.embed("test query")++ mock_client.embeddings.create.assert_called_once()+ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert "extra_body" not in call_kwargs+++class TestJinaDenseEmbedderTask:+ """Test JinaDenseEmbedder task passthrough (already exists, verify behavior)."""++ @patch("openai.OpenAI")+ def test_embed_passes_task_in_extra_body(self, mock_openai_class):+ """embed should pass task in extra_body when provided."""+ from openviking.models.embedder import JinaDenseEmbedder++ mock_client = MagicMock()+ mock_response = MagicMock()+ mock_response.data = [MagicMock(embedding=[0.1] * 1024)]+ mock_client.embeddings.create.return_value = mock_response+ mock_openai_class.return_value = mock_client++ embedder = JinaDenseEmbedder(+ model_name="jina-embeddings-v5-text-small",+ api_key="jina-test",+ task="retrieval.query",+ )++ embedder.embed("test query")++ mock_client.embeddings.create.assert_called_once()+ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert call_kwargs.get("extra_body") == {"task": "retrieval.query"}++ @patch("openai.OpenAI")+ def test_embed_batch_passes_task_in_extra_body(self, mock_openai_class):+ """embed_batch should pass task in extra_body when provided."""+ from openviking.models.embedder import JinaDenseEmbedder++ mock_client = MagicMock()+ mock_response = MagicMock()+ mock_response.data = [MagicMock(embedding=[0.1] * 1024), MagicMock(embedding=[0.2] * 1024)]+ mock_client.embeddings.create.return_value = mock_response+ mock_openai_class.return_value = mock_client++ embedder = JinaDenseEmbedder(+ model_name="jina-embeddings-v5-text-small",+ api_key="jina-test",+ task="retrieval.passage",+ )++ embedder.embed_batch(["doc 1", "doc 2"])++ mock_client.embeddings.create.assert_called_once()+ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert call_kwargs.get("extra_body") == {"task": "retrieval.passage"}diff --git a/tests/unit/test_jina_embedder.py b/tests/unit/test_jina_embedder.pyindex 67a926681..557de0e24 100644--- a/tests/unit/test_jina_embedder.py+++ b/tests/unit/test_jina_embedder.py@@ -137,7 +137,8 @@ class TestJinaDenseEmbedder:embedder = JinaDenseEmbedder(model_name="jina-embeddings-v5-text-small",api_key="test-api-key",- task="retrieval.query",+ context="query",+ query_param="retrieval.query",)embedder.embed("Hello world")@@ -244,7 +245,8 @@ class TestJinaDenseEmbedder:embedder = JinaDenseEmbedder(model_name="jina-embeddings-v5-text-small",api_key="test-api-key",- task="retrieval.passage",+ context="document",+ document_param="retrieval.passage",late_chunking=True,)extra_body = embedder._build_extra_body()diff --git a/tests/unit/test_openai_embedder.py b/tests/unit/test_openai_embedder.pynew file mode 100644index 000000000..8e9b72a82--- /dev/null+++ b/tests/unit/test_openai_embedder.py@@ -0,0 +1,304 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: Apache-2.0+"""Tests for OpenAI Embedder"""++from unittest.mock import MagicMock, patch++import pytest++from openviking.models.embedder import OpenAIDenseEmbedder+++class TestOpenAIDenseEmbedder:+ """Test cases for OpenAIDenseEmbedder"""++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_embed_does_not_send_dimensions(self, mock_openai_class):+ """OpenAI embed should omit dimensions param"""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ mock_embedding = MagicMock()+ mock_embedding.embedding = [0.1] * 1536++ mock_response = MagicMock()+ mock_response.data = [mock_embedding]+ mock_client.embeddings.create.return_value = mock_response++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="test-api-key",+ dimension=1024,+ )++ embedder.embed("Hello world")++ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert "dimensions" not in call_kwargs++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_embed_batch_does_not_send_dimensions(self, mock_openai_class):+ """OpenAI embed_batch should omit dimensions param"""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ mock_embedding1 = MagicMock()+ mock_embedding1.embedding = [0.1] * 1536+ mock_embedding2 = MagicMock()+ mock_embedding2.embedding = [0.2] * 1536++ mock_response = MagicMock()+ mock_response.data = [mock_embedding1, mock_embedding2]+ mock_client.embeddings.create.return_value = mock_response++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="test-api-key",+ dimension=512,+ )++ embedder.embed_batch(["Hello", "World"])++ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert "dimensions" not in call_kwargs++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_embed_with_input_type_none(self, mock_openai_class):+ """OpenAI embed should not include extra_body when input_type is None"""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ mock_embedding = MagicMock()+ mock_embedding.embedding = [0.1] * 1536++ mock_response = MagicMock()+ mock_response.data = [mock_embedding]+ mock_client.embeddings.create.return_value = mock_response++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="test-api-key",+ )++ embedder.embed("Hello world")++ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert "extra_body" not in call_kwargs++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_embed_with_context_query(self, mock_openai_class):+ """OpenAI embed should include extra_body with input_type='query' when context='query'"""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ mock_embedding = MagicMock()+ mock_embedding.embedding = [0.1] * 1536++ mock_response = MagicMock()+ mock_response.data = [mock_embedding]+ mock_client.embeddings.create.return_value = mock_response++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="test-api-key",+ context="query",+ query_param="query",+ )++ embedder.embed("Hello world")++ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert "extra_body" in call_kwargs+ assert call_kwargs["extra_body"] == {"input_type": "query"}++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_embed_with_context_document(self, mock_openai_class):+ """OpenAI embed should include extra_body with input_type='passage' when context='document'"""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ mock_embedding = MagicMock()+ mock_embedding.embedding = [0.1] * 1536++ mock_response = MagicMock()+ mock_response.data = [mock_embedding]+ mock_client.embeddings.create.return_value = mock_response++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="test-api-key",+ context="document",+ document_param="passage",+ )++ embedder.embed("Hello world")++ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert "extra_body" in call_kwargs+ assert call_kwargs["extra_body"] == {"input_type": "passage"}++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_embed_batch_with_input_type_none(self, mock_openai_class):+ """OpenAI embed_batch should not include extra_body when input_type is None"""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ mock_embedding1 = MagicMock()+ mock_embedding1.embedding = [0.1] * 1536+ mock_embedding2 = MagicMock()+ mock_embedding2.embedding = [0.2] * 1536++ mock_response = MagicMock()+ mock_response.data = [mock_embedding1, mock_embedding2]+ mock_client.embeddings.create.return_value = mock_response++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="test-api-key",+ )++ embedder.embed_batch(["Hello", "World"])++ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert "extra_body" not in call_kwargs++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_embed_batch_with_context_query(self, mock_openai_class):+ """OpenAI embed_batch should include extra_body with input_type='query' when context='query'"""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ mock_embedding1 = MagicMock()+ mock_embedding1.embedding = [0.1] * 1536+ mock_embedding2 = MagicMock()+ mock_embedding2.embedding = [0.2] * 1536++ mock_response = MagicMock()+ mock_response.data = [mock_embedding1, mock_embedding2]+ mock_client.embeddings.create.return_value = mock_response++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="test-api-key",+ context="query",+ query_param="query",+ )++ embedder.embed_batch(["Hello", "World"])++ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert "extra_body" in call_kwargs+ assert call_kwargs["extra_body"] == {"input_type": "query"}++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_embed_batch_with_context_document(self, mock_openai_class):+ """OpenAI embed_batch should include extra_body with input_type='passage' when context='document'"""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ mock_embedding1 = MagicMock()+ mock_embedding1.embedding = [0.1] * 1536+ mock_embedding2 = MagicMock()+ mock_embedding2.embedding = [0.2] * 1536++ mock_response = MagicMock()+ mock_response.data = [mock_embedding1, mock_embedding2]+ mock_client.embeddings.create.return_value = mock_response++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="test-api-key",+ context="document",+ document_param="passage",+ )++ embedder.embed_batch(["Hello", "World"])++ call_kwargs = mock_client.embeddings.create.call_args[1]+ assert "extra_body" in call_kwargs+ assert call_kwargs["extra_body"] == {"input_type": "passage"}++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_telemetry_skipped_when_no_usage(self, mock_openai_class):+ """_update_telemetry_token_usage should no-op when response has no usage"""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ mock_embedding = MagicMock()+ mock_embedding.embedding = [0.1] * 1536++ mock_response = MagicMock()+ mock_response.data = [mock_embedding]+ mock_response.usage = None+ mock_client.embeddings.create.return_value = mock_response++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="test-api-key",+ dimension=1536,+ )+ result = embedder.embed("Hello world")+ assert result.dense_vector is not None++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_telemetry_skipped_when_module_missing(self, mock_openai_class):+ """_update_telemetry_token_usage should silently no-op when telemetry module is not available"""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ mock_embedding = MagicMock()+ mock_embedding.embedding = [0.1] * 1536++ mock_usage = MagicMock()+ mock_usage.prompt_tokens = 10+ mock_usage.total_tokens = 10++ mock_response = MagicMock()+ mock_response.data = [mock_embedding]+ mock_response.usage = mock_usage+ mock_client.embeddings.create.return_value = mock_response++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="test-api-key",+ dimension=1536,+ )++ with patch("importlib.import_module", side_effect=ImportError("no telemetry")):+ result = embedder.embed("Hello world")++ assert result.dense_vector is not None++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_telemetry_called_when_module_available(self, mock_openai_class):+ """_update_telemetry_token_usage should call telemetry when module is available"""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ mock_embedding = MagicMock()+ mock_embedding.embedding = [0.1] * 1536++ mock_usage = MagicMock()+ mock_usage.prompt_tokens = 8+ mock_usage.total_tokens = 8++ mock_response = MagicMock()+ mock_response.data = [mock_embedding]+ mock_response.usage = mock_usage+ mock_client.embeddings.create.return_value = mock_response++ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="test-api-key",+ dimension=1536,+ )++ mock_telemetry = MagicMock()+ mock_telemetry_module = MagicMock()+ mock_telemetry_module.get_current_telemetry.return_value = mock_telemetry++ with patch("importlib.import_module", return_value=mock_telemetry_module):+ result = embedder.embed("Hello world")++ assert result.dense_vector is not None+ mock_telemetry.add_token_usage_by_source.assert_called_once_with("embedding", 8, 0)