Skip to content

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

fix(embedder): bound OpenAI HTTP connection pools (#4475)

Onefly0f58d62a5713
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 4ebcb5d22..8bdfb2c98 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -211,7 +211,7 @@ Embedding model configuration for vector search, supporting dense, sparse, and h
| Parameter | Type | Description |
|-----------|------|-------------|
-| `max_concurrent` | int | Maximum concurrent embedding requests (`embedding.max_concurrent`, default: `10`) |
+| `max_concurrent` | int | Maximum concurrent embedding requests (`embedding.max_concurrent`, default: `10`; must be `>= 1`) |
| `max_retries` | int | Maximum retry attempts for transient embedding provider errors (`embedding.max_retries`, default: `3`; `0` disables retry) |
| `text_source` | str | Text used for vectorizing text files. `content_only` reads raw content, `summary_first` uses summary when available and falls back to content, `summary_only` uses only summary. Default: `content_only` |
| `max_input_tokens` | int | Maximum estimated raw text tokens sent to the embedding model when content is used. Default: `4096` |
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index c239d0a6b..2bd31b0f1 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -213,7 +213,7 @@ openviking-server doctor
| 参数 | 类型 | 说明 |
|------|------|------|
-| `max_concurrent` | int | 最大并发 Embedding 请求数(`embedding.max_concurrent`,默认:`10`) |
+| `max_concurrent` | int | 最大并发 Embedding 请求数(`embedding.max_concurrent`,默认:`10`;必须 `>= 1`) |
| `max_retries` | int | Embedding provider 瞬时错误的最大重试次数(`embedding.max_retries`,默认:`3`;`0` 表示禁用重试) |
| `text_source` | str | 文本文件向量化时使用的文本来源。`content_only` 读取原文内容;`summary_first` 优先使用摘要,没有摘要时回退到原文;`summary_only` 只使用摘要。默认:`content_only` |
| `max_input_tokens` | int | 使用原文内容向量化时,发送给 embedding 模型的最大估算 token 数。默认:`4096` |
diff --git a/openviking/models/embedder/openai_embedders.py b/openviking/models/embedder/openai_embedders.py
index 5a738c40c..c0dab6efc 100644
--- a/openviking/models/embedder/openai_embedders.py
+++ b/openviking/models/embedder/openai_embedders.py
@@ -4,6 +4,7 @@
from typing import Any, Dict, List, Literal, Optional
+import httpx
import openai
from openviking.models.embedder.base import (
@@ -147,13 +148,19 @@ 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(**self._client_kwargs)
+ self.client = openai.AzureOpenAI(
+ http_client=openai.DefaultHttpxClient(limits=self._http_limits()),
+ **self._client_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(**self._client_kwargs)
+ self.client = openai.OpenAI(
+ http_client=openai.DefaultHttpxClient(limits=self._http_limits()),
+ **self._client_kwargs,
+ )
self._async_client_cache = LoopScopedAsyncClientCache()
# Auto-detect dimension
@@ -173,6 +180,14 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):
# Use default value, text-embedding-3-small defaults to 1536
return 1536
+ def _http_limits(self) -> httpx.Limits:
+ pool_limit = max(1, self.max_concurrent)
+ return httpx.Limits(
+ max_connections=pool_limit,
+ max_keepalive_connections=pool_limit,
+ keepalive_expiry=5.0,
+ )
+
def _truncate_vector(self, vector: List[float]) -> List[float]:
"""Truncate vector to target dimension if needed.
@@ -297,9 +312,16 @@ 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(**self._client_kwargs)
- return openai.AsyncOpenAI(**self._client_kwargs)
+ return openai.AsyncAzureOpenAI(
+ http_client=http_client,
+ **self._client_kwargs,
+ )
+ return openai.AsyncOpenAI(
+ http_client=http_client,
+ **self._client_kwargs,
+ )
return self._async_client_cache.get(_build_async_client)
@@ -365,6 +387,11 @@ class OpenAIDenseEmbedder(DenseEmbedderBase):
"""
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
diff --git a/openviking/service/core.py b/openviking/service/core.py
index 9b832f40a..51bc2ed06 100644
--- a/openviking/service/core.py
+++ b/openviking/service/core.py
@@ -564,6 +564,12 @@ class OpenVikingService:
self._agfs_client = None
logger.info("RAGFS binding closed")
+ embedder = getattr(self, "_embedder", None)
+ if embedder is not None:
+ embedder.close()
+ self._embedder = None
+ await asyncio.sleep(0)
+
self._viking_fs = None
self._resource_processor = None
self._skill_processor = None
diff --git a/openviking_cli/utils/config/embedding_config.py b/openviking_cli/utils/config/embedding_config.py
index cd0be8468..b3205dd9a 100644
--- a/openviking_cli/utils/config/embedding_config.py
+++ b/openviking_cli/utils/config/embedding_config.py
@@ -639,7 +639,9 @@ class EmbeddingConfig(BaseModel):
)
max_concurrent: int = Field(
- default=10, description="Maximum number of concurrent embedding requests"
+ default=10,
+ ge=1,
+ description="Maximum number of concurrent embedding requests",
)
max_retries: int = Field(
default=3,
diff --git a/tests/unit/service/test_core_embedder_lifecycle.py b/tests/unit/service/test_core_embedder_lifecycle.py
new file mode 100644
index 000000000..eade47823
--- /dev/null
+++ b/tests/unit/service/test_core_embedder_lifecycle.py
@@ -0,0 +1,53 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Service lifecycle coverage for embedding clients."""
+
+import pytest
+
+from openviking.service.core import OpenVikingService
+
+
+async def test_service_closes_embedder_after_workers_and_storage_stop(monkeypatch) -> None:
+ events = []
+
+ class _ResourceService:
+ async def close_background_tasks(self) -> None:
+ events.append("background")
+
+ class _QueueManager:
+ def stop(self) -> None:
+ events.append("queue")
+
+ class _VikingDBManager:
+ def mark_closing(self) -> None:
+ events.append("storage-mark")
+
+ async def close(self) -> None:
+ events.append("storage-close")
+
+ class _Embedder:
+ def close(self) -> None:
+ events.append("embedder")
+
+ service = OpenVikingService.__new__(OpenVikingService)
+ service._resource_service = _ResourceService()
+ service._watch_scheduler = None
+ service._session_auto_commit_scheduler = None
+ service._queue_manager = _QueueManager()
+ service._vikingdb_manager = _VikingDBManager()
+ service._agfs_client = None
+ service._embedder = _Embedder()
+ service._initialized = True
+ monkeypatch.setattr(service, "_release_data_dir_lock", lambda: None)
+
+ await service.close()
+
+ assert events == [
+ "background",
+ "queue",
+ "storage-mark",
+ "storage-close",
+ "embedder",
+ ]
+ assert service._embedder is None
diff --git a/tests/unit/test_openai_embedder_http_pool.py b/tests/unit/test_openai_embedder_http_pool.py
new file mode 100644
index 000000000..e60d3592b
--- /dev/null
+++ b/tests/unit/test_openai_embedder_http_pool.py
@@ -0,0 +1,167 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Regression tests for OpenAI embedder HTTP connection ownership."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from contextlib import contextmanager
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Iterator
+
+import openai
+import pytest
+from pydantic import ValidationError
+
+from openviking.models.embedder import OpenAIDenseEmbedder
+from openviking_cli.utils.config.embedding_config import EmbeddingConfig
+
+
+class _EmbeddingServer(ThreadingHTTPServer):
+ daemon_threads = True
+ block_on_close = False
+
+ def __init__(self) -> None:
+ super().__init__(("127.0.0.1", 0), _EmbeddingHandler)
+ self.connection_count = 0
+
+ def get_request(self):
+ request, address = super().get_request()
+ self.connection_count += 1
+ return request, address
+
+
+class _EmbeddingHandler(BaseHTTPRequestHandler):
+ protocol_version = "HTTP/1.1"
+
+ def do_POST(self) -> None:
+ content_length = int(self.headers.get("Content-Length", "0"))
+ self.rfile.read(content_length)
+ payload = json.dumps(
+ {
+ "object": "list",
+ "data": [
+ {
+ "object": "embedding",
+ "index": 0,
+ "embedding": [0.1, 0.2, 0.3],
+ }
+ ],
+ "model": "test-embedding",
+ "usage": {"prompt_tokens": 1, "total_tokens": 1},
+ }
+ ).encode()
+ self.send_response(200)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(payload)))
+ self.end_headers()
+ self.wfile.write(payload)
+
+ def log_message(self, format: str, *args: object) -> None:
+ return
+
+
+@contextmanager
+def _embedding_server() -> Iterator[_EmbeddingServer]:
+ server = _EmbeddingServer()
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
+ thread.start()
+ try:
+ yield server
+ finally:
+ server.shutdown()
+ server.server_close()
+ thread.join(timeout=2)
+
+
+def _pool(client):
+ return client._client._transport._pool
+
+
[email protected]("provider", ["openai", "azure"])
+async def test_openai_embedder_bounds_sync_and_async_connection_pools(provider: str) -> None:
+ provider_kwargs = {}
+ if provider == "azure":
+ provider_kwargs = {
+ "api_base": "https://test-resource.openai.azure.com",
+ "api_version": "2025-01-01-preview",
+ }
+
+ embedder = OpenAIDenseEmbedder(
+ model_name="test-embedding",
+ api_key="test-key",
+ dimension=3,
+ config={"max_concurrent": 3},
+ provider=provider,
+ **provider_kwargs,
+ )
+ async_client = embedder._get_async_client()
+
+ try:
+ for client in (embedder.client, async_client):
+ pool = _pool(client)
+ assert pool._max_connections == 3
+ assert pool._max_keepalive_connections == 3
+ assert pool._keepalive_expiry == 5.0
+ assert client._client.timeout == openai.DEFAULT_TIMEOUT
+ finally:
+ embedder.client.close()
+ await async_client.close()
+
+
+async def test_openai_embedder_reuses_and_closes_local_connection() -> None:
+ with _embedding_server() as server:
+ embedder = OpenAIDenseEmbedder(
+ model_name="test-embedding",
+ api_key="test-key",
+ api_base=f"http://127.0.0.1:{server.server_port}/v1",
+ dimension=3,
+ encoding_format="float",
+ )
+ async_client = embedder._get_async_client()
+
+ try:
+ first = await embedder.embed_async("first")
+ second = await embedder.embed_async("second")
+
+ assert first.dense_vector == pytest.approx([0.1, 0.2, 0.3])
+ assert second.dense_vector == pytest.approx([0.1, 0.2, 0.3])
+ assert server.connection_count == 1
+
+ embedder.close()
+ await asyncio.sleep(0)
+
+ assert embedder.client.is_closed()
+ assert async_client.is_closed()
+ finally:
+ if not embedder.client.is_closed():
+ embedder.client.close()
+ if not async_client.is_closed():
+ await async_client.close()
+
+
[email protected]("max_concurrent", [0, -1])
+def test_embedding_config_rejects_non_positive_concurrency(max_concurrent: int) -> None:
+ with pytest.raises(ValidationError, match="max_concurrent"):
+ EmbeddingConfig(max_concurrent=max_concurrent)
+
+
[email protected]("max_concurrent", [0, -1])
+def test_direct_embedder_normalizes_non_positive_pool_limit(max_concurrent: int) -> None:
+ embedder = OpenAIDenseEmbedder(
+ model_name="test-embedding",
+ api_key="test-key",
+ dimension=3,
+ config={"max_concurrent": max_concurrent},
+ )
+
+ try:
+ pool = _pool(embedder.client)
+ assert pool._max_connections == 1
+ assert pool._max_keepalive_connections == 1
+ finally:
+ embedder.close()