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
Add support for custom HTTP headers in VLM models (OpenAI-compatible) (#723)
KorenKritacd87c0aaa6d0
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 1a60fa894..52a55a91a 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -303,6 +303,7 @@ Vision Language Model for semantic extraction (L0/L1 generation).| `api_base` | str | API endpoint (optional) || `thinking` | bool | Enable thinking mode for VolcEngine models (default: `false`) || `max_concurrent` | int | Maximum concurrent semantic LLM calls (default: `100`) |+| `extra_headers` | object | Custom HTTP headers (for OpenAI-compatible providers, optional) |**Available Models**@@ -318,6 +319,30 @@ When resources are added, VLM generates:If VLM is not configured, L0/L1 will be generated from content directly (less semantic), and multimodal resources may have limited descriptions.+**Custom HTTP Headers**++For OpenAI-compatible providers (e.g., OpenRouter), you can add custom HTTP headers via `extra_headers`:++```json+{+ "vlm": {+ "provider": "openai",+ "api_key": "your-api-key",+ "model": "gpt-4o",+ "api_base": "https://openrouter.ai/api/v1",+ "extra_headers": {+ "HTTP-Referer": "https://your-site.com",+ "X-Title": "Your App Name"+ }+ }+}+```++Common use cases:+- **OpenRouter**: Requires `HTTP-Referer` and `X-Title` to identify your application+- **Custom proxies**: Add authentication or tracing headers+- **API gateways**: Add version or routing identifiers+### codeControls how code files are summarized via `code_summary_mode`. Both config formats are equivalent:@@ -680,7 +705,8 @@ For details on the lock mechanism, see [Path Locks and Crash Recovery](../concep"model": "string","api_base": "string","thinking": false,- "max_concurrent": 100+ "max_concurrent": 100,+ "extra_headers": {}},"rerank": {"provider": "volcengine",diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex b0954bbfe..1c83eb85c 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -276,6 +276,7 @@ OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支| `api_base` | str | API 端点(可选) || `thinking` | bool | 启用思考模式(仅对部分火山模型生效,默认:`false`) || `max_concurrent` | int | 语义处理阶段 LLM 最大并发调用数(默认:`100`) |+| `extra_headers` | object | 自定义 HTTP 请求头(OpenAI 兼容 provider 可用,可选) |**可用模型**@@ -291,6 +292,30 @@ OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支如果未配置 VLM,L0/L1 将直接从内容生成(语义性较弱),多模态资源的描述可能有限。+**自定义 HTTP Headers**++对于 OpenAI 兼容的 provider(如 OpenRouter),可以通过 `extra_headers` 添加自定义 HTTP 请求头:++```json+{+ "vlm": {+ "provider": "openai",+ "api_key": "your-api-key",+ "model": "gpt-4o",+ "api_base": "https://openrouter.ai/api/v1",+ "extra_headers": {+ "HTTP-Referer": "https://your-site.com",+ "X-Title": "Your App Name"+ }+ }+}+```++常见使用场景:+- **OpenRouter**: 需要 `HTTP-Referer` 和 `X-Title` 来标识应用+- **自定义代理**: 添加认证头或追踪头+- **API 网关**: 添加版本或路由标识+### code通过 `code_summary_mode` 控制代码文件的摘要生成方式。以下两种写法等价:@@ -655,7 +680,8 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远"model": "string","api_base": "string","thinking": false,- "max_concurrent": 100+ "max_concurrent": 100,+ "extra_headers": {}},"rerank": {"provider": "volcengine",diff --git a/openviking/models/vlm/backends/openai_vlm.py b/openviking/models/vlm/backends/openai_vlm.pyindex 862342b2e..d1f6d05d3 100644--- a/openviking/models/vlm/backends/openai_vlm.py+++ b/openviking/models/vlm/backends/openai_vlm.py@@ -29,7 +29,10 @@ class OpenAIVLM(VLMBase):import openaiexcept ImportError:raise ImportError("Please install openai: pip install openai")- self._sync_client = openai.OpenAI(api_key=self.api_key, base_url=self.api_base)+ client_kwargs = {"api_key": self.api_key, "base_url": self.api_base}+ if self.extra_headers:+ client_kwargs["default_headers"] = self.extra_headers+ self._sync_client = openai.OpenAI(**client_kwargs)return self._sync_clientdef get_async_client(self):@@ -39,7 +42,10 @@ class OpenAIVLM(VLMBase):import openaiexcept ImportError:raise ImportError("Please install openai: pip install openai")- self._async_client = openai.AsyncOpenAI(api_key=self.api_key, base_url=self.api_base)+ client_kwargs = {"api_key": self.api_key, "base_url": self.api_base}+ if self.extra_headers:+ client_kwargs["default_headers"] = self.extra_headers+ self._async_client = openai.AsyncOpenAI(**client_kwargs)return self._async_clientdef _update_token_usage_from_response(self, response):diff --git a/openviking/models/vlm/base.py b/openviking/models/vlm/base.pyindex d8641bf84..64c3d5cf8 100644--- a/openviking/models/vlm/base.py+++ b/openviking/models/vlm/base.py@@ -26,6 +26,7 @@ class VLMBase(ABC):self.temperature = config.get("temperature", 0.0)self.max_retries = config.get("max_retries", 2)self.max_tokens = config.get("max_tokens")+ self.extra_headers = config.get("extra_headers")# Token usage trackingself._token_tracker = TokenUsageTracker()diff --git a/openviking_cli/utils/config/vlm_config.py b/openviking_cli/utils/config/vlm_config.pyindex 6c42d6436..0b999ca8b 100644--- a/openviking_cli/utils/config/vlm_config.py+++ b/openviking_cli/utils/config/vlm_config.py@@ -36,6 +36,10 @@ class VLMConfig(BaseModel):default=100, description="Maximum number of concurrent LLM calls for semantic processing")+ extra_headers: Optional[Dict[str, str]] = Field(+ default=None, description="Extra HTTP headers for OpenAI-compatible providers"+ )+_vlm_instance: Optional[Any] = Nonemodel_config = {"arbitrary_types_allowed": True, "extra": "forbid"}@@ -72,6 +76,8 @@ class VLMConfig(BaseModel):self.providers[self.provider]["api_key"] = self.api_keyif self.api_base and "api_base" not in self.providers[self.provider]:self.providers[self.provider]["api_base"] = self.api_base+ if self.extra_headers and "extra_headers" not in self.providers[self.provider]:+ self.providers[self.provider]["extra_headers"] = self.extra_headersdef _has_any_config(self) -> bool:"""Check if any config is provided."""diff --git a/tests/unit/test_extra_headers_vlm.py b/tests/unit/test_extra_headers_vlm.pynew file mode 100644index 000000000..87b3e8037--- /dev/null+++ b/tests/unit/test_extra_headers_vlm.py@@ -0,0 +1,221 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: Apache-2.0+"""Tests for VLM extra_headers support."""++from unittest.mock import MagicMock, patch++from openviking.models.vlm.backends.openai_vlm import OpenAIVLM+++class TestVLMExtraHeaders:+ """Test extra_headers is passed to OpenAI client."""++ @patch("openviking.models.vlm.backends.openai_vlm.openai.OpenAI")+ def test_extra_headers_passed_to_sync_client(self, mock_openai_class):+ """extra_headers should be passed as default_headers to sync OpenAI client."""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ headers = {"HTTP-Referer": "https://example.com", "X-Title": "My App"}+ vlm = OpenAIVLM(+ {+ "api_key": "sk-test",+ "api_base": "https://api.openai.com/v1",+ "extra_headers": headers,+ }+ )++ # Trigger client creation+ _ = vlm.get_client()++ mock_openai_class.assert_called_once()+ call_kwargs = mock_openai_class.call_args[1]+ assert call_kwargs.get("default_headers") == headers++ @patch("openviking.models.vlm.backends.openai_vlm.openai.AsyncOpenAI")+ def test_extra_headers_passed_to_async_client(self, mock_async_openai_class):+ """extra_headers should be passed as default_headers to async OpenAI client."""+ mock_client = MagicMock()+ mock_async_openai_class.return_value = mock_client++ headers = {"HTTP-Referer": "https://example.com", "X-Title": "My App"}+ vlm = OpenAIVLM(+ {+ "api_key": "sk-test",+ "api_base": "https://api.openai.com/v1",+ "extra_headers": headers,+ }+ )++ # Trigger async client creation+ _ = vlm.get_async_client()++ mock_async_openai_class.assert_called_once()+ call_kwargs = mock_async_openai_class.call_args[1]+ assert call_kwargs.get("default_headers") == headers++ @patch("openviking.models.vlm.backends.openai_vlm.openai.OpenAI")+ def test_no_extra_headers_omits_default_headers(self, mock_openai_class):+ """When extra_headers is not provided, default_headers should NOT be set."""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ vlm = OpenAIVLM(+ {+ "api_key": "sk-test",+ "api_base": "https://api.openai.com/v1",+ }+ )++ # Trigger client creation+ _ = vlm.get_client()++ mock_openai_class.assert_called_once()+ call_kwargs = mock_openai_class.call_args[1]+ assert "default_headers" not in call_kwargs++ @patch("openviking.models.vlm.backends.openai_vlm.openai.OpenAI")+ def test_extra_headers_empty_dict_omits_default_headers(self, mock_openai_class):+ """When extra_headers is empty dict, default_headers should NOT be set."""+ mock_client = MagicMock()+ mock_openai_class.return_value = mock_client++ vlm = OpenAIVLM(+ {+ "api_key": "sk-test",+ "api_base": "https://api.openai.com/v1",+ "extra_headers": {},+ }+ )++ # Trigger client creation+ _ = vlm.get_client()++ mock_openai_class.assert_called_once()+ call_kwargs = mock_openai_class.call_args[1]+ # Empty dict is falsy, so default_headers should not be set+ assert "default_headers" not in call_kwargs+++class TestVLMBaseExtraHeaders:+ """Test VLMBase extracts extra_headers from config."""++ def test_extra_headers_extracted_from_config(self):+ """VLMBase should extract extra_headers from config."""++ class StubVLM(OpenAIVLM):+ def get_completion(self, prompt, thinking=False):+ return ""++ async def get_completion_async(self, prompt, thinking=False, max_retries=0):+ return ""++ def get_vision_completion(self, prompt, images, thinking=False):+ return ""++ async def get_vision_completion_async(self, prompt, images, thinking=False):+ return ""++ headers = {"X-Custom-Header": "custom-value"}+ vlm = StubVLM(+ {+ "api_key": "sk-test",+ "extra_headers": headers,+ }+ )++ assert vlm.extra_headers == headers++ def test_extra_headers_none_when_not_in_config(self):+ """VLMBase should set extra_headers to None when not in config."""++ class StubVLM(OpenAIVLM):+ def get_completion(self, prompt, thinking=False):+ return ""++ async def get_completion_async(self, prompt, thinking=False, max_retries=0):+ return ""++ def get_vision_completion(self, prompt, images, thinking=False):+ return ""++ async def get_vision_completion_async(self, prompt, images, thinking=False):+ return ""++ vlm = StubVLM(+ {+ "api_key": "sk-test",+ }+ )++ assert vlm.extra_headers is None+++class TestVLMConfigExtraHeaders:+ """Test VLMConfig passes extra_headers to VLM instance."""++ def test_vlm_config_accepts_extra_headers_in_providers(self):+ """VLMConfig should accept extra_headers in providers config."""+ from openviking_cli.utils.config.vlm_config import VLMConfig++ config = VLMConfig(+ model="gpt-4o",+ provider="openai",+ providers={+ "openai": {+ "api_key": "sk-test",+ "api_base": "https://api.openai.com/v1",+ "extra_headers": {"HTTP-Referer": "https://example.com"},+ }+ },+ )++ result = config._build_vlm_config_dict()+ assert result["extra_headers"] == {"HTTP-Referer": "https://example.com"}++ def test_vlm_config_extra_headers_none_when_not_set(self):+ """VLMConfig should not include extra_headers when not set."""+ from openviking_cli.utils.config.vlm_config import VLMConfig++ config = VLMConfig(+ model="gpt-4o",+ provider="openai",+ providers={+ "openai": {+ "api_key": "sk-test",+ "api_base": "https://api.openai.com/v1",+ }+ },+ )++ result = config._build_vlm_config_dict()+ assert result.get("extra_headers") is None++ def test_vlm_config_accepts_flat_extra_headers(self):+ """VLMConfig should accept extra_headers as flat config field (legacy style)."""+ from openviking_cli.utils.config.vlm_config import VLMConfig++ config = VLMConfig(+ model="gpt-4o",+ provider="openai",+ api_key="sk-test",+ api_base="https://openrouter.ai/api/v1",+ extra_headers={"HTTP-Referer": "https://example.com", "X-Title": "My App"},+ )++ # Verify flat extra_headers is stored+ assert config.extra_headers == {"HTTP-Referer": "https://example.com", "X-Title": "My App"}++ # Verify it's migrated to providers structure+ config._migrate_legacy_config()+ assert config.providers["openai"]["extra_headers"] == {+ "HTTP-Referer": "https://example.com",+ "X-Title": "My App",+ }++ # Verify _build_vlm_config_dict includes it+ result = config._build_vlm_config_dict()+ assert result["extra_headers"] == {+ "HTTP-Referer": "https://example.com",+ "X-Title": "My App",+ }