Skip to content

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

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.py
index 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 dict
max_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_headers
self.client = openai.OpenAI(**client_kwargs)
# Initialize tiktoken encoder
diff --git a/openviking_cli/utils/config/embedding_config.py b/openviking_cli/utils/config/embedding_config.py
index 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 None
return 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.py
new file mode 100644
index 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")