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): support extra HTTP headers for OpenAI-compatible providers (#694)
AstroHande6cf2715f31
diff --git a/openviking/models/embedder/openai_embedders.py b/openviking/models/embedder/openai_embedders.pyindex d0a0fe7f2..6a87a86d0 100644--- a/openviking/models/embedder/openai_embedders.py+++ b/openviking/models/embedder/openai_embedders.py@@ -62,6 +62,7 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):document_param: Optional[str] = None,config: Optional[Dict[str, Any]] = None,max_tokens: Optional[int] = None,+ extra_headers: Optional[Dict[str, str]] = None,):"""Initialize OpenAI-Compatible Dense Embedder@@ -88,6 +89,8 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):Only supported by OpenAI-compatible third-party models.config: Additional configuration dictmax_tokens: Maximum token count per embedding request, None to use default (8000)+ extra_headers: Extra HTTP headers to include in API requests (e.g., for OpenRouter:+ {'HTTP-Referer': 'https://your-site.com', 'X-Title': 'Your App'})Raises:ValueError: If api_key is not provided and env vars are not set@@ -115,8 +118,6 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):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)")@@ -126,6 +127,9 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):client_kwargs = {"api_key": self.api_key or "no-key"}if self.api_base:client_kwargs["base_url"] = self.api_base+ # 透传自定义请求头(如 OpenRouter 要求的 HTTP-Referer / X-Title)+ if extra_headers:+ client_kwargs["default_headers"] = extra_headersself.client = openai.OpenAI(**client_kwargs)# Initialize tiktoken encoderdiff --git a/openviking_cli/utils/config/embedding_config.py b/openviking_cli/utils/config/embedding_config.pyindex 81ad64d84..55dd2a6c2 100644--- a/openviking_cli/utils/config/embedding_config.py+++ b/openviking_cli/utils/config/embedding_config.py@@ -40,7 +40,11 @@ class EmbeddingModelConfig(BaseModel):)provider: Optional[str] = Field(default="volcengine",- description="Provider type: 'openai', 'volcengine', 'vikingdb', 'jina', 'ollama', 'voyage'",+ description=(+ "Provider type: 'openai', 'volcengine', 'vikingdb', 'jina', 'ollama', 'voyage'. "+ "For OpenRouter or other OpenAI-compatible providers, use 'openai' with "+ "api_base and extra_headers."+ ),)backend: Optional[str] = Field(default="volcengine",@@ -55,6 +59,14 @@ class EmbeddingModelConfig(BaseModel):default=None,description="Maximum token count per embedding request. If None, uses model default (e.g., 8000 for OpenAI).",)+ extra_headers: Optional[dict[str, str]] = Field(+ default=None,+ description=(+ "Extra HTTP headers for API requests. Passed as default_headers to the OpenAI client. "+ "Useful for OpenRouter (e.g., {'HTTP-Referer': '...', 'X-Title': '...'}) "+ "or other OpenAI-compatible providers that require custom headers."+ ),+ )model_config = {"extra": "forbid"}@@ -67,7 +79,13 @@ 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"):+ 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()@@ -176,7 +194,13 @@ class EmbeddingConfig(BaseModel):)return self- def _create_embedder(self, provider: str, embedder_type: str, config: EmbeddingModelConfig, context: Optional[str] = None):+ 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:@@ -211,13 +235,15 @@ class EmbeddingConfig(BaseModel):OpenAIDenseEmbedder,lambda cfg: {"model_name": cfg.model,- "api_key": cfg.api_key or "no-key", # Placeholder for local OpenAI-compatible servers+ "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,+ **({"extra_headers": cfg.extra_headers} if cfg.extra_headers else {}),},),("volcengine", "dense"): (@@ -302,7 +328,8 @@ class EmbeddingConfig(BaseModel):OpenAIDenseEmbedder,lambda cfg: {"model_name": cfg.model,- "api_key": cfg.api_key or "no-key", # Ollama ignores the key, but client requires non-empty+ "api_key": cfg.api_key+ or "no-key", # Ollama ignores the key, but client requires non-empty"api_base": cfg.api_base or "http://localhost:11434/v1","dimension": cfg.dimension,"max_tokens": cfg.max_tokens,@@ -381,7 +408,9 @@ class EmbeddingConfig(BaseModel):# 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+ non_symmetric = (+ self.dense.query_param is not None or self.dense.document_param is not None+ )effective_context = context if non_symmetric else Nonereturn self._create_embedder(provider, "dense", self.dense, context=effective_context)diff --git a/tests/unit/test_extra_headers_embedding.py b/tests/unit/test_extra_headers_embedding.pynew file mode 100644index 000000000..c766debb0--- /dev/null+++ b/tests/unit/test_extra_headers_embedding.py@@ -0,0 +1,146 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: Apache-2.0+"""Tests for extra_headers support in OpenAIDenseEmbedder and EmbeddingConfig factory.++Covers:+ 1. extra_headers is passed as default_headers to openai.OpenAI client+ 2. omitting extra_headers does not inject default_headers key+ 3. factory (_create_embedder) transparently forwards extra_headers+ 4. api_key dead-code bug fix: no raise when api_base is set without api_key+"""++from unittest.mock import MagicMock, patch++import pytest++from openviking.models.embedder import OpenAIDenseEmbedder+from openviking_cli.utils.config.embedding_config import EmbeddingConfig, EmbeddingModelConfig+++def _make_mock_client():+ """Build a MagicMock openai client that returns a minimal valid embedding response."""+ mock_client = MagicMock()+ mock_client.embeddings.create.return_value = MagicMock(+ data=[MagicMock(embedding=[0.1] * 8)],+ usage=None,+ )+ return mock_client+++class TestExtraHeadersDirectConstruction:+ """Test extra_headers behaviour when constructing OpenAIDenseEmbedder directly."""++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_extra_headers_passed_as_default_headers(self, mock_openai_class):+ """extra_headers dict must arrive as default_headers kwarg in openai.OpenAI()."""+ mock_openai_class.return_value = _make_mock_client()++ headers = {"HTTP-Referer": "https://example.com", "X-Title": "My App"}+ OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="sk-test",+ extra_headers=headers,+ )++ mock_openai_class.assert_called_once()+ call_kwargs = mock_openai_class.call_args[1]+ assert call_kwargs.get("default_headers") == headers++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_no_extra_headers_omits_default_headers(self, mock_openai_class):+ """When extra_headers is not provided, default_headers must NOT appear in openai.OpenAI()."""+ mock_openai_class.return_value = _make_mock_client()++ OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_key="sk-test",+ )++ mock_openai_class.assert_called_once()+ call_kwargs = mock_openai_class.call_args[1]+ assert "default_headers" not in call_kwargs+++class TestExtraHeadersViaFactory:+ """Test extra_headers forwarding through EmbeddingConfig._create_embedder."""++ @patch("openai.OpenAI")+ def test_factory_passes_extra_headers(self, mock_openai_class):+ """Factory must forward extra_headers as default_headers to openai.OpenAI()."""+ mock_openai_class.return_value = _make_mock_client()++ headers = {"HTTP-Referer": "https://myapp.com", "X-Title": "MyApp"}+ cfg = EmbeddingModelConfig(+ provider="openai",+ model="text-embedding-3-small",+ api_key="sk-test",+ extra_headers=headers,+ )+ EmbeddingConfig(dense=cfg)._create_embedder("openai", "dense", cfg)++ mock_openai_class.assert_called_once()+ call_kwargs = mock_openai_class.call_args[1]+ assert call_kwargs.get("default_headers") == headers++ @patch("openai.OpenAI")+ def test_factory_omits_extra_headers_when_none(self, mock_openai_class):+ """Factory must NOT inject default_headers when extra_headers is None."""+ mock_openai_class.return_value = _make_mock_client()++ cfg = EmbeddingModelConfig(+ provider="openai",+ model="text-embedding-3-small",+ api_key="sk-test",+ )+ EmbeddingConfig(dense=cfg)._create_embedder("openai", "dense", cfg)++ mock_openai_class.assert_called_once()+ call_kwargs = mock_openai_class.call_args[1]+ assert "default_headers" not in call_kwargs+++class TestEmbeddingModelConfigExtraHeaders:+ """Test that EmbeddingModelConfig accepts and stores the extra_headers field."""++ def test_openai_config_accepts_extra_headers_field(self):+ """EmbeddingModelConfig should store extra_headers without validation error."""+ cfg = EmbeddingModelConfig(+ provider="openai",+ model="text-embedding-3-small",+ api_key="sk-test",+ extra_headers={"X-Custom": "value"},+ )+ assert cfg.extra_headers == {"X-Custom": "value"}++ def test_extra_headers_defaults_to_none(self):+ """extra_headers field should default to None when not supplied."""+ cfg = EmbeddingModelConfig(+ provider="openai",+ model="text-embedding-3-small",+ api_key="sk-test",+ )+ assert cfg.extra_headers is None+++class TestApiKeyValidationFix:+ """Test the api_key dead-code bug fix: validate only when both api_key and api_base are absent."""++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_api_key_not_required_when_api_base_set(self, mock_openai_class):+ """No ValueError should be raised when api_base is provided without api_key."""+ mock_openai_class.return_value = _make_mock_client()++ # Should NOT raise; api_base substitutes for api_key for local/compatible servers+ embedder = OpenAIDenseEmbedder(+ model_name="text-embedding-3-small",+ api_base="http://localhost:8080/v1",+ )+ assert embedder is not None++ @patch("openviking.models.embedder.openai_embedders.openai.OpenAI")+ def test_api_key_required_when_no_api_base(self, mock_openai_class):+ """ValueError must be raised when neither api_key nor api_base is provided."""+ mock_openai_class.return_value = _make_mock_client()++ with pytest.raises(ValueError, match="api_key is required"):+ OpenAIDenseEmbedder(model_name="text-embedding-3-small")