Skip to content

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

feat: add model network service discovery hooks (#5117)

nocvalight7bf25eb89492
diff --git a/openviking/models/embedder/openai_embedders.py b/openviking/models/embedder/openai_embedders.py
index 26defb990..648240026 100644
--- a/openviking/models/embedder/openai_embedders.py
+++ b/openviking/models/embedder/openai_embedders.py
@@ -6,6 +6,7 @@ from typing import Any, Dict, List, Literal, Optional
import httpx
import openai
+from openviking_cli.utils import get_logger
from openviking.models.embedder.base import (
DenseEmbedderBase,
@@ -14,10 +15,13 @@ from openviking.models.embedder.base import (
HybridEmbedderBase,
SparseEmbedderBase,
)
+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_cli.utils import get_logger
logger = get_logger(__name__)
@@ -153,19 +157,31 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):
self._client_kwargs["api_version"] = self.api_version or DEFAULT_AZURE_API_VERSION
if extra_headers:
self._client_kwargs["default_headers"] = extra_headers
- self.client = openai.AzureOpenAI(
- http_client=openai.DefaultHttpxClient(limits=self._http_limits()),
- **self._client_kwargs,
+ 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
- self.client = openai.OpenAI(
- http_client=openai.DefaultHttpxClient(limits=self._http_limits()),
- **self._client_kwargs,
+ 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
@@ -328,16 +344,18 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):
def _get_async_client(self):
def _build_async_client():
- http_client = openai.DefaultAsyncHttpxClient(limits=self._http_limits())
- if self._provider == "azure":
- return openai.AsyncAzureOpenAI(
- http_client=http_client,
- **self._client_kwargs,
- )
- return openai.AsyncOpenAI(
- http_client=http_client,
- **self._client_kwargs,
+ 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)
diff --git a/openviking/models/embedder/volcengine_embedders.py b/openviking/models/embedder/volcengine_embedders.py
index c874fd054..6149caa77 100644
--- a/openviking/models/embedder/volcengine_embedders.py
+++ b/openviking/models/embedder/volcengine_embedders.py
@@ -7,6 +7,7 @@ import time
from typing import Any, Awaitable, Callable, Dict, List, Optional, TypeVar
import volcenginesdkarkruntime
+from openviking_cli.utils.logger import default_logger as logger
from openviking.models.embedder.base import (
DenseEmbedderBase,
@@ -17,12 +18,15 @@ from openviking.models.embedder.base import (
extract_text_from_content,
truncate_and_normalize,
)
+from openviking.models.network import (
+ create_optional_async_httpx_client,
+ create_optional_sync_httpx_client,
+)
from openviking.telemetry import get_current_telemetry
from openviking.metrics.datasources import EmbeddingEventDataSource
from openviking.observability.context import get_root_observability_context
from openviking.utils.model_retry import extract_metric_error_code
from openviking.utils.async_client_cache import LoopScopedAsyncClientCache
-from openviking_cli.utils.logger import default_logger as logger
VOLCENGINE_CLIENT_REQUEST_ID_HEADER = "X-Client-Request-Id"
VOLCENGINE_CLIENT_REQUEST_ID = "ToB-direct,OpenViking_Service,openviking-service_cn-beijing"
@@ -75,6 +79,28 @@ async def _measure_embedding_call_async(
raise
+def _create_sync_ark(kwargs: Dict[str, Any]):
+ client_kwargs = dict(kwargs)
+ http_client = create_optional_sync_httpx_client(
+ client_kwargs.get("base_url"),
+ timeout=60.0,
+ )
+ if http_client is not None:
+ client_kwargs["http_client"] = http_client
+ return volcenginesdkarkruntime.Ark(**client_kwargs)
+
+
+def _create_async_ark(kwargs: Dict[str, Any]):
+ client_kwargs = dict(kwargs)
+ http_client = create_optional_async_httpx_client(
+ client_kwargs.get("base_url"),
+ timeout=60.0,
+ )
+ if http_client is not None:
+ client_kwargs["http_client"] = http_client
+ return volcenginesdkarkruntime.AsyncArk(**client_kwargs)
+
+
def _build_volcengine_headers(extra_headers: Optional[Dict[str, str]]) -> Dict[str, str]:
headers = dict(extra_headers or {})
if not any(k.lower() == VOLCENGINE_CLIENT_REQUEST_ID_HEADER.lower() for k in headers):
@@ -174,7 +200,7 @@ class VolcengineDenseEmbedder(DenseEmbedderBase):
ark_kwargs = {"api_key": self.api_key}
if self.api_base:
ark_kwargs["base_url"] = self.api_base
- self.client = volcenginesdkarkruntime.Ark(**ark_kwargs)
+ self.client = _create_sync_ark(ark_kwargs)
self._ark_kwargs = ark_kwargs
self._async_client_cache = LoopScopedAsyncClientCache()
@@ -286,7 +312,7 @@ class VolcengineDenseEmbedder(DenseEmbedderBase):
def _get_async_client(self):
return self._async_client_cache.get(
- lambda: volcenginesdkarkruntime.AsyncArk(**self._ark_kwargs)
+ lambda: _create_async_ark(self._ark_kwargs)
)
async def embed_async(self, content: "EmbeddingInput", is_query: bool = False) -> EmbedResult:
@@ -377,7 +403,7 @@ class VolcengineSparseEmbedder(SparseEmbedderBase):
ark_kwargs = {"api_key": self.api_key}
if self.api_base:
ark_kwargs["base_url"] = self.api_base
- self.client = volcenginesdkarkruntime.Ark(**ark_kwargs)
+ self.client = _create_sync_ark(ark_kwargs)
self._ark_kwargs = ark_kwargs
self._async_client_cache = LoopScopedAsyncClientCache()
@@ -455,7 +481,7 @@ class VolcengineSparseEmbedder(SparseEmbedderBase):
def _get_async_client(self):
return self._async_client_cache.get(
- lambda: volcenginesdkarkruntime.AsyncArk(**self._ark_kwargs)
+ lambda: _create_async_ark(self._ark_kwargs)
)
async def embed_async(self, content: "EmbeddingInput", is_query: bool = False) -> EmbedResult:
@@ -545,7 +571,7 @@ class VolcengineHybridEmbedder(HybridEmbedderBase):
ark_kwargs = {"api_key": self.api_key}
if self.api_base:
ark_kwargs["base_url"] = self.api_base
- self.client = volcenginesdkarkruntime.Ark(**ark_kwargs)
+ self.client = _create_sync_ark(ark_kwargs)
self._ark_kwargs = ark_kwargs
self._async_client_cache = LoopScopedAsyncClientCache()
self._dimension = dimension or 2048
@@ -640,7 +666,7 @@ class VolcengineHybridEmbedder(HybridEmbedderBase):
def _get_async_client(self):
return self._async_client_cache.get(
- lambda: volcenginesdkarkruntime.AsyncArk(**self._ark_kwargs)
+ lambda: _create_async_ark(self._ark_kwargs)
)
async def embed_async(self, content: "EmbeddingInput", is_query: bool = False) -> EmbedResult:
diff --git a/openviking/models/network.py b/openviking/models/network.py
new file mode 100644
index 000000000..b85e211a4
--- /dev/null
+++ b/openviking/models/network.py
@@ -0,0 +1,174 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Pluggable network clients for model providers.
+
+The public OpenViking package owns only this neutral extension point. Internal
+distributions may register an adapter for additional URL schemes without
+making upstream model providers depend on private networking packages.
+"""
+
+from __future__ import annotations
+
+from threading import RLock
+from typing import Any, Mapping, Protocol, Sequence
+from urllib.parse import urlparse
+
+import httpx
+import requests
+from requests.adapters import HTTPAdapter
+
+EventHooks = Mapping[str, Sequence[Any]]
+
+
+class ModelNetworkAdapter(Protocol):
+ """Adapter implemented by a distribution-specific model network layer."""
+
+ def supports(self, url: str) -> bool: ...
+
+ def create_sync_httpx_client(
+ self,
+ url: str,
+ *,
+ client_cls: type[httpx.Client],
+ event_hooks: EventHooks | None = None,
+ **client_kwargs: Any,
+ ) -> httpx.Client: ...
+
+ def create_async_httpx_client(
+ self,
+ url: str,
+ *,
+ client_cls: type[httpx.AsyncClient],
+ event_hooks: EventHooks | None = None,
+ **client_kwargs: Any,
+ ) -> httpx.AsyncClient: ...
+
+ def create_requests_session(
+ self,
+ url: str,
+ *,
+ retry: Any = None,
+ mount_retry: bool = True,
+ ) -> requests.Session: ...
+
+
+_SERVICE_DISCOVERY_SCHEMES = frozenset({"http+sd", "https+sd"})
+_adapter: ModelNetworkAdapter | None = None
+_lock = RLock()
+
+
+def register_model_network_adapter(adapter: ModelNetworkAdapter) -> None:
+ """Register the process-wide model network adapter.
+
+ Registering the same object repeatedly is idempotent. Replacing an existing
+ adapter is rejected so unrelated extensions cannot silently take ownership.
+ """
+
+ global _adapter
+ with _lock:
+ if _adapter is adapter:
+ return
+ if _adapter is not None:
+ raise RuntimeError("A model network adapter is already registered")
+ _adapter = adapter
+
+
+def reset_model_network_adapter() -> None:
+ """Reset the adapter. Intended for tests and runtime reinitialization."""
+
+ global _adapter
+ with _lock:
+ _adapter = None
+
+
+def is_model_network_endpoint(url: str | None) -> bool:
+ """Return whether *url* explicitly requests an extended model scheme."""
+
+ if not url:
+ return False
+ return urlparse(str(url)).scheme.lower() in _SERVICE_DISCOVERY_SCHEMES
+
+
+def _adapter_for(url: str) -> ModelNetworkAdapter | None:
+ with _lock:
+ adapter = _adapter
+ if adapter is not None and adapter.supports(url):
+ return adapter
+ if is_model_network_endpoint(url):
+ if adapter is None:
+ raise RuntimeError(
+ "Model service discovery URL requires a registered model network adapter"
+ )
+ raise RuntimeError(
+ f"Registered model network adapter does not support URL scheme "
+ f"'{urlparse(url).scheme}'"
+ )
+ return None
+
+
+def create_optional_sync_httpx_client(
+ url: str | None,
+ *,
+ client_cls: type[httpx.Client] = httpx.Client,
+ event_hooks: EventHooks | None = None,
+ **client_kwargs: Any,
+) -> httpx.Client | None:
+ """Create an injected sync client only for an extended model endpoint."""
+
+ if not url:
+ return None
+ adapter = _adapter_for(url)
+ if adapter is None:
+ return None
+ return adapter.create_sync_httpx_client(
+ url,
+ client_cls=client_cls,
+ event_hooks=event_hooks,
+ **client_kwargs,
+ )
+
+
+def create_optional_async_httpx_client(
+ url: str | None,
+ *,
+ client_cls: type[httpx.AsyncClient] = httpx.AsyncClient,
+ event_hooks: EventHooks | None = None,
+ **client_kwargs: Any,
+) -> httpx.AsyncClient | None:
+ """Create an injected async client only for an extended model endpoint."""
+
+ if not url:
+ return None
+ adapter = _adapter_for(url)
+ if adapter is None:
+ return None
+ return adapter.create_async_httpx_client(
+ url,
+ client_cls=client_cls,
+ event_hooks=event_hooks,
+ **client_kwargs,
+ )
+
+
+def create_model_requests_session(
+ url: str,
+ *,
+ retry: Any = None,
+ mount_retry: bool = True,
+) -> requests.Session:
+ """Create a requests session suitable for the model endpoint."""
+
+ adapter = _adapter_for(url)
+ if adapter is not None:
+ return adapter.create_requests_session(
+ url,
+ retry=retry,
+ mount_retry=mount_retry,
+ )
+
+ session = requests.Session()
+ if mount_retry and retry is not None:
+ http_adapter = HTTPAdapter(max_retries=retry)
+ session.mount("http://", http_adapter)
+ session.mount("https://", http_adapter)
+ return session
diff --git a/openviking/models/vlm/backends/openai_vlm.py b/openviking/models/vlm/backends/openai_vlm.py
index 847d20900..ab9a62fbf 100644
--- a/openviking/models/vlm/backends/openai_vlm.py
+++ b/openviking/models/vlm/backends/openai_vlm.py
@@ -9,6 +9,10 @@ from pathlib import Path
from typing import Any, Dict, List, Optional, Union
from urllib.parse import urlparse
+from openviking.models.network import (
+ create_optional_async_httpx_client,
+ create_optional_sync_httpx_client,
+)
from openviking.telemetry import tracer
from openviking.utils.async_client_cache import LoopScopedAsyncClientCache
from openviking.utils.message_format import format_messages, sanitize_openai_messages
@@ -89,6 +93,13 @@ class OpenAIVLM(VLMBase):
self.extra_headers,
self.timeout,
)
+ http_client = create_optional_sync_httpx_client(
+ self.api_base,
+ client_cls=openai.DefaultHttpxClient,
+ timeout=self.timeout,
+ )
+ if http_client is not None:
+ kwargs["http_client"] = http_client
if self.provider == "azure":
self._sync_client = openai.AzureOpenAI(**kwargs)
else:
@@ -107,6 +118,13 @@ class OpenAIVLM(VLMBase):
self.extra_headers,
self.timeout,
)
+ http_client = create_optional_async_httpx_client(
+ self.api_base,
+ client_cls=openai.DefaultAsyncHttpxClient,
+ timeout=self.timeout,
+ )
+ if http_client is not None:
+ kwargs["http_client"] = http_client
if self.provider == "azure":
return openai.AsyncAzureOpenAI(**kwargs)
return openai.AsyncOpenAI(**kwargs)
diff --git a/openviking/models/vlm/backends/volcengine_vlm.py b/openviking/models/vlm/backends/volcengine_vlm.py
index e9806778e..208f4c8b9 100644
--- a/openviking/models/vlm/backends/volcengine_vlm.py
+++ b/openviking/models/vlm/backends/volcengine_vlm.py
@@ -10,6 +10,10 @@ import uuid
from pathlib import Path
from typing import Any, Dict, List, Optional, Union
+from openviking.models.network import (
+ create_optional_async_httpx_client,
+ create_optional_sync_httpx_client,
+)
from openviking.telemetry import tracer
from openviking.utils.message_format import format_messages, sanitize_openai_messages
from openviking.utils.multimodal import redact_image_data_urls
@@ -113,12 +117,19 @@ class VolcEngineVLM(OpenAIVLM):
raise ImportError(
"Please install volcenginesdkarkruntime: pip install volcenginesdkarkruntime"
)
- self._sync_client = volcenginesdkarkruntime.Ark(
+ kwargs = dict(
api_key=self.api_key,
base_url=self.api_base,
timeout=self.timeout,
max_retries=0,
)
+ http_client = create_optional_sync_httpx_client(
+ self.api_base,
+ timeout=self.timeout,
+ )
+ if http_client is not None:
+ kwargs["http_client"] = http_client
+ self._sync_client = volcenginesdkarkruntime.Ark(**kwargs)
return self._sync_client
def _build_async_client(self):
@@ -129,12 +140,19 @@ class VolcEngineVLM(OpenAIVLM):
raise ImportError(
"Please install volcenginesdkarkruntime: pip install volcenginesdkarkruntime"
)
- return volcenginesdkarkruntime.AsyncArk(
+ kwargs = dict(
api_key=self.api_key,
base_url=self.api_base,
timeout=self.timeout,
max_retries=0,
)
+ http_client = create_optional_async_httpx_client(
+ self.api_base,
+ timeout=self.timeout,
+ )
+ if http_client is not None:
+ kwargs["http_client"] = http_client
+ return volcenginesdkarkruntime.AsyncArk(**kwargs)
def supports_media(
self,