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
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""OpenAI Embedder Implementation"""
from typing import Any, Dict, List, Literal, Optional, cast
import httpx
import openai
from openviking.models.embedder.base import (
DenseEmbedderBase,
EmbeddingInput,
EmbedResult,
HybridEmbedderBase,
SparseEmbedderBase,
)
from openviking.models.model_error import model_error_boundary
from openviking.models.network import (
create_optional_async_httpx_client,
create_optional_sync_httpx_client,
)
from openviking.models.vlm.registry import DEFAULT_AZURE_API_VERSION
from openviking.telemetry import get_current_telemetry
from openviking.utils.async_client_cache import LoopScopedAsyncClientCache
from openviking.utils.embedding_input import truncate_embedding_input
from openviking_cli.utils import get_logger
logger = get_logger(__name__)
class OpenAIDenseEmbedder(DenseEmbedderBase):
"""OpenAI-Compatible Dense Embedder Implementation
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",
... dimension=1536
... )
>>> result = embedder.embed("Hello world")
>>> print(len(result.dense_vector))
1536
>>> # Non-symmetric mode (OpenAI-compatible third-party models)
>>> embedder = OpenAIDenseEmbedder(
... model_name="bge-m3",
... api_key="your-api-key",
... api_base="https://your-api-endpoint.com/v1",
... query_param="query",
... document_param="passage"
... )
>>> query_vector = embedder.embed("search query", is_query=True)
>>> doc_vector = embedder.embed("document text", is_query=False)
>>> # Multiple parameters with key=value format
>>> advanced_embedder = OpenAIDenseEmbedder(
... model_name="custom-model",
... api_key="your-api-key",
... api_base="https://your-api-endpoint.com/v1",
... query_param="input_type=query,task=search,domain=finance",
... document_param="input_type=passage,task=index,domain=finance"
... )
>>> advanced_vector = advanced_embedder.embed("financial query", is_query=True)
"""
def __init__(
self,
model_name: str = "text-embedding-3-small",
api_key: Optional[str] = None,
api_base: Optional[str] = None,
api_version: Optional[str] = None,
dimension: Optional[int] = None,
query_param: Optional[str] = None,
document_param: Optional[str] = None,
config: Optional[Dict[str, Any]] = None,
extra_headers: Optional[Dict[str, str]] = None,
input_type: Optional[str] = None,
provider: str = "openai",
configured_provider: Optional[str] = None,
encoding_format: Optional[Literal["float", "base64"]] = None,
extra_body: Optional[Dict[str, Any]] = None,
):
"""Initialize OpenAI-Compatible Dense Embedder
Args:
model_name: Model name. For official OpenAI models (e.g., text-embedding-3-small),
use symmetric mode (query_param=None, document_param=None).
For OpenAI-compatible third-party models (e.g., BGE-M3, Jina, Cohere), use
non-symmetric mode with query_param/document_param.
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. Required for third-party OpenAI-compatible APIs.
dimension: Target dimension for output vectors. If specified and the model returns vectors
with a different dimension, the output will be truncated to this dimension.
If None, uses the model's default dimension without truncation.
query_param: Parameter for query-side embeddings. Supports simple values (e.g., 'query')
or key=value format (e.g., 'input_type=query,task=search'). Defaults to None.
Setting this (or document_param) activates non-symmetric mode.
Only supported by OpenAI-compatible third-party models.
document_param: Parameter for document-side embeddings. Supports simple values (e.g., 'passage')
or key=value format (e.g., 'input_type=passage,task=index'). Defaults to None.
Setting this (or query_param) activates non-symmetric mode.
Only supported by OpenAI-compatible third-party models.
config: Additional configuration dict
extra_headers: Extra HTTP headers to include in API requests (e.g., for OpenRouter:
{'HTTP-Referer': 'https://your-site.com', 'X-Title': 'Your App'})
input_type: OpenViking embedding input mode ('text' or 'multimodal'). This controls
whether content parts are passed through, and is distinct from
query_param/document_param values sent as extra_body.input_type.
encoding_format: Wire format for embedding values. ``None`` (default) lets the
OpenAI Python SDK pick its default (currently ``base64``). Set to
``"float"`` to send/receive plain JSON arrays — the recommended
workaround when the upstream gateway cannot deserialize base64
embedding payloads correctly.
extra_body: Extra JSON body fields merged into every embeddings request
(e.g., OpenRouter provider routing:
{'provider': {'sort': 'latency'}}). Keys set explicitly via
query_param/document_param take precedence on conflict.
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)
self.api_key = api_key
self.api_base = api_base
self.api_version = api_version
self.dimension = dimension
self.query_param = query_param
self.document_param = document_param
self._supports_multimodal = input_type == "multimodal"
self.encoding_format = encoding_format
self.extra_body = extra_body
self._provider = provider.lower()
self.provider = (configured_provider or provider).lower()
self._client_kwargs: Dict[str, Any] = {
"api_key": self.api_key or "no-key",
"max_retries": 0,
}
# 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")
if self._provider == "azure":
if not self.api_base:
raise ValueError("api_base (Azure endpoint) is required for Azure provider")
self._client_kwargs["azure_endpoint"] = self.api_base
self._client_kwargs["api_version"] = self.api_version or DEFAULT_AZURE_API_VERSION
if extra_headers:
self._client_kwargs["default_headers"] = extra_headers
sync_kwargs = dict(self._client_kwargs)
http_client = create_optional_sync_httpx_client(
self.api_base,
client_cls=openai.DefaultHttpxClient,
limits=self._http_limits(),
)
if http_client is None:
http_client = openai.DefaultHttpxClient(limits=self._http_limits())
sync_kwargs["http_client"] = http_client
self.client = openai.AzureOpenAI(**sync_kwargs)
else:
if self.api_base:
self._client_kwargs["base_url"] = self.api_base
if extra_headers:
self._client_kwargs["default_headers"] = extra_headers
sync_kwargs = dict(self._client_kwargs)
http_client = create_optional_sync_httpx_client(
self.api_base,
client_cls=openai.DefaultHttpxClient,
limits=self._http_limits(),
)
if http_client is None:
http_client = openai.DefaultHttpxClient(limits=self._http_limits())
sync_kwargs["http_client"] = http_client
self.client = openai.OpenAI(**sync_kwargs)
self._async_client_cache = LoopScopedAsyncClientCache()
# Auto-detect dimension
self._dimension = dimension
self._actual_model_dimension = None
if self._dimension is None:
self._dimension = self._detect_dimension()
def _detect_dimension(self) -> int:
"""Detect dimension by making an actual API call"""
try:
result = self.embed("test")
detected_dim = len(result.dense_vector) if result.dense_vector else 1536
self._actual_model_dimension = detected_dim
return detected_dim
except Exception:
# Use default value, text-embedding-3-small defaults to 1536
return 1536
def _http_limits(self) -> httpx.Limits:
# Document concurrency is enforced before the request. Active connections
# must not reapply that limit to retrieval queries.
return httpx.Limits(
max_connections=None,
max_keepalive_connections=max(1, self.max_concurrent),
keepalive_expiry=5.0,
)
def _truncate_vector(self, vector: List[float]) -> List[float]:
"""Truncate vector to target dimension if needed.
Args:
vector: Input vector from API
Returns:
Truncated vector if dimension is set and smaller than input, otherwise original vector
"""
if self.dimension is not None and len(vector) > self.dimension:
return vector[: self.dimension]
return vector
def _update_telemetry_token_usage(self, response) -> None:
usage = getattr(response, "usage", None)
if not usage:
return
def _usage_value(key: str, default: int = 0) -> int:
if isinstance(usage, dict):
return int(usage.get(key, default) or default)
return int(getattr(usage, key, default) or default)
prompt_tokens = _usage_value("prompt_tokens", 0)
total_tokens = _usage_value("total_tokens", prompt_tokens)
completion_tokens = max(total_tokens - prompt_tokens, 0)
# Update telemetry
get_current_telemetry().add_token_usage_by_source(
"embedding",
prompt_tokens,
completion_tokens,
)
# Update token tracker
self.update_token_usage(
model_name=self.model_name,
provider=self._provider,
prompt_tokens=prompt_tokens,
completion_tokens=completion_tokens,
)
def _parse_param_string(self, param: Optional[str]) -> Dict[str, str]:
"""Parse parameter string to dictionary for key=value format
Args:
param: Parameter string (e.g., "input_type=query,task=search")
Returns:
Dictionary of parsed parameters
"""
if not param:
return {}
result = {}
# Split by comma for multiple parameters
parts = [p.strip() for p in param.split(",")]
for part in parts:
if "=" in part:
key, value = part.split("=", 1)
result[key.strip()] = value.strip()
return result
def _build_extra_body(self, is_query: bool = False) -> Optional[Dict[str, Any]]:
"""Build extra_body dict for OpenAI-compatible parameters
Starts from the configured ``extra_body`` (a general passthrough for
OpenAI-compatible gateways, e.g. OpenRouter provider routing), then
applies the query/document parameters on top so explicit
query_param/document_param keys always win on conflict.
Args:
is_query: Flag to indicate if this is for query embeddings
Returns:
Dict containing the configured extra body plus input_type and other
parameters if non-symmetric mode is active. Supports key=value
format for multiple parameters (e.g., "input_type=query,task=search").
Only supported by OpenAI-compatible third-party models.
"""
extra_body = dict(self.extra_body) if self.extra_body else {}
# Determine which parameter to use based on is_query flag
active_param = None
if is_query and self.query_param is not None:
active_param = self.query_param
elif not is_query and self.document_param is not None:
active_param = self.document_param
if active_param:
if "=" in active_param:
# Parse key=value format (e.g., "input_type=query,task=search")
parsed = self._parse_param_string(active_param)
extra_body.update(parsed)
else:
# Simple format (e.g., "query" -> {"input_type": "query"})
extra_body["input_type"] = active_param
return extra_body if extra_body else None
@property
def supports_multimodal(self) -> bool:
return self._supports_multimodal
def _prepare_embedding_input(self, text: EmbeddingInput | List[str]) -> EmbeddingInput | List[str]:
if isinstance(text, list) and all(isinstance(item, str) for item in text):
if self.max_input_tokens is None:
return text
text = cast(List[str], text)
return [truncate_embedding_input(item, self.max_input_tokens) for item in text]
return self.prepare_embedding_input(text)
def _build_kwargs(
self, text_input: EmbeddingInput | List[str], is_query: bool = False
) -> Dict[str, Any]:
kwargs: Dict[str, Any] = {"input": text_input, "model": self.model_name}
if self.dimension and self._should_send_dimensions():
kwargs["dimensions"] = self.dimension
if self.encoding_format is not None:
kwargs["encoding_format"] = self.encoding_format
extra_body = self._build_extra_body(is_query=is_query)
if extra_body:
kwargs["extra_body"] = extra_body
return kwargs
def _should_send_dimensions(self) -> bool:
# Preserve existing behavior for official OpenAI embeddings: only custom
# OpenAI-compatible backends and Azure send explicit dimensions.
if self._provider == "openai":
return False
return bool(self.api_base)
def _get_async_client(self):
def _build_async_client():
kwargs = dict(self._client_kwargs)
http_client = create_optional_async_httpx_client(
self.api_base,
client_cls=openai.DefaultAsyncHttpxClient,
limits=self._http_limits(),
)
if http_client is None:
http_client = openai.DefaultAsyncHttpxClient(limits=self._http_limits())
kwargs["http_client"] = http_client
if self._provider == "azure":
return openai.AsyncAzureOpenAI(**kwargs)
return openai.AsyncOpenAI(**kwargs)
return self._async_client_cache.get(_build_async_client)
@model_error_boundary
def embed(self, text: EmbeddingInput | List[str], is_query: bool = False) -> EmbedResult:
"""Perform dense embedding on text, text batches, or multimodal content
Args:
text: Input text, OpenAI text batch, or multimodal content parts
is_query: Flag to indicate if this is a query embedding
Returns:
EmbedResult: Result containing only dense_vector
Raises:
RuntimeError: When API call fails
"""
embedding_input = self._prepare_embedding_input(text)
def _call() -> EmbedResult:
response = self.client.embeddings.create(
**self._build_kwargs(embedding_input, is_query=is_query)
)
self._update_telemetry_token_usage(response)
vector = response.data[0].embedding
# Truncate vector if needed
vector = self._truncate_vector(vector)
return EmbedResult(dense_vector=vector)
try:
return self._run_once(
_call,
logger=logger,
operation_name="OpenAI embedding",
)
except openai.APIError as e:
raise RuntimeError(f"OpenAI API error: {e.message}") from e
except Exception as e:
raise RuntimeError(f"Embedding failed: {str(e)}") from e
@model_error_boundary
async def embed_async(self, text: EmbeddingInput | List[str], is_query: bool = False) -> EmbedResult:
client = self._get_async_client()
embedding_input = self._prepare_embedding_input(text)
async def _call() -> EmbedResult:
response = await client.embeddings.create(
**self._build_kwargs(embedding_input, is_query=is_query)
)
self._update_telemetry_token_usage(response)
return EmbedResult(dense_vector=self._truncate_vector(response.data[0].embedding))
try:
return await self._run_once_async(
_call,
is_query=is_query,
logger=logger,
operation_name="OpenAI async embedding",
)
except openai.APIError as e:
raise RuntimeError(f"OpenAI API error: {e.message}") from e
except Exception as e:
raise RuntimeError(f"Embedding failed: {str(e)}") from e
def get_dimension(self) -> int:
"""Get embedding dimension
Returns:
int: Vector dimension
"""
return self._dimension
def close(self):
"""Close the sync client and all event-loop-scoped async clients."""
self.client.close()
self._async_client_cache.close_all_with_close()
class OpenAISparseEmbedder(SparseEmbedderBase):
"""OpenAI does not support sparse embedding
This class is a placeholder for error messaging. For sparse embedding, use Volcengine or other providers.
"""
def __init__(self, *args, **kwargs):
model_name = kwargs.get("model_name")
if model_name is None and args:
model_name = str(args[0])
super().__init__(model_name=model_name or "openai-sparse-unsupported")
raise NotImplementedError(
"OpenAI does not support sparse embeddings. "
"Consider using VolcengineSparseEmbedder or other providers."
)
def embed(self, text: str, is_query: bool = False) -> EmbedResult:
raise NotImplementedError()
class OpenAIHybridEmbedder(HybridEmbedderBase):
"""OpenAI does not support hybrid embedding
This class is a placeholder for error messaging. For hybrid embedding, use Volcengine or other providers.
"""
def __init__(self, *args, **kwargs):
model_name = kwargs.get("model_name")
if model_name is None and args:
model_name = str(args[0])
super().__init__(model_name=model_name or "openai-hybrid-unsupported")
raise NotImplementedError(
"OpenAI does not support hybrid embeddings. "
"Consider using VolcengineHybridEmbedder or other providers."
)
def embed(self, text: str, is_query: bool = False) -> EmbedResult:
raise NotImplementedError()
def get_dimension(self) -> int:
raise NotImplementedError()