Skip to content

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

Feat/configurable executor workers (#4913)

Jiahui Zhouf2832b7b9b8d
diff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.md
index fb1e0989b..462e0675f 100644
--- a/docs/en/configuration/01-server.md
+++ b/docs/en/configuration/01-server.md
@@ -259,6 +259,7 @@ When `base_url` is configured, OV sends the current user's OV API key in `X-API-
"host": "127.0.0.1",
"port": 1933,
"workers": 1,
+ "executor_threads": 0,
"auth_mode": "dev",
"cors_origins": ["http://localhost:5173"],
"profile_enabled": false,
@@ -276,6 +277,7 @@ When `base_url` is configured, OV sends the current user's OV API key in `X-API-
| `host` | IP / hostname | `"127.0.0.1"` | Listen address |
| `port` | integer | `1933` | Listen port |
| `workers` | integer | `1` | Worker process count |
+| `executor_threads` | non-negative integer | `0` | Maximum threads in each worker process's default asyncio executor; `0` uses Python's default sizing policy |
| `timeout_keep_alive` | integer (seconds) | `5` | Idle HTTP keep-alive timeout; raise it above the upstream's idle-connection lifetime |
| `auth_mode` | `dev`, `api_key`, `trusted` / `null` | `null` | Auth mode; null is inferred from `root_api_key` |
| `root_api_key` | string / `null` | `null` | Root key; setting it defaults auth to `api_key` |
diff --git a/docs/zh/configuration/01-server.md b/docs/zh/configuration/01-server.md
index c4a78f9b4..50592f531 100644
--- a/docs/zh/configuration/01-server.md
+++ b/docs/zh/configuration/01-server.md
@@ -259,6 +259,7 @@ Search 和 Find 请求的默认 `limit` 为 `10`,可以在每次 API 或 SDK
"host": "127.0.0.1",
"port": 1933,
"workers": 1,
+ "executor_threads": 0,
"auth_mode": "dev",
"cors_origins": ["http://localhost:5173"],
"profile_enabled": false,
@@ -276,6 +277,7 @@ Search 和 Find 请求的默认 `limit` 为 `10`,可以在每次 API 或 SDK
| `host` | IP / hostname | `"127.0.0.1"` | HTTP 监听地址 |
| `port` | integer | `1933` | HTTP 监听端口 |
| `workers` | integer | `1` | 服务进程数量 |
+| `executor_threads` | 非负整数 | `0` | 每个服务进程的 asyncio 默认 executor 最大线程数;`0` 表示沿用 Python 默认策略 |
| `timeout_keep_alive` | integer(秒) | `5` | 空闲 HTTP keep-alive 超时;应调大到超过上游空闲连接寿命 |
| `auth_mode` | `dev`、`api_key`、`trusted` / `null` | `null` | 鉴权模式;空值根据 `root_api_key` 自动判断 |
| `root_api_key` | string / `null` | `null` | Root API Key;配置后默认启用 `api_key` 模式 |
diff --git a/examples/ov.conf.example b/examples/ov.conf.example
index 4c1cf68a6..ac6138692 100644
--- a/examples/ov.conf.example
+++ b/examples/ov.conf.example
@@ -2,6 +2,7 @@
"server": {
"host": "0.0.0.0",
"port": 1933,
+ "executor_threads": 0,
"timeout_keep_alive": 5,
"root_api_key": null,
"cors_origins": ["*"],
diff --git a/openviking/server/app.py b/openviking/server/app.py
index 111e31a2f..766977c9a 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -6,6 +6,7 @@ import asyncio
import logging
import os
import time
+from concurrent.futures import ThreadPoolExecutor
from contextlib import asynccontextmanager
from pathlib import Path
from typing import Callable, Optional
@@ -75,6 +76,25 @@ WORKER_WITH_BOT_ENV = "OPENVIKING_WORKER_WITH_BOT"
WORKER_BOT_API_URL_ENV = "OPENVIKING_WORKER_BOT_API_URL"
+def _configure_default_executor(config: ServerConfig) -> None:
+ """Apply the configured asyncio default executor to the current worker loop.
+
+ The event loop owns the executor after ``set_default_executor`` and shuts it
+ down when the loop closes. This must run before service initialization,
+ because initialization itself can submit work through ``asyncio.to_thread``.
+ """
+ max_workers = config.executor_threads
+ if max_workers == 0:
+ return
+
+ executor = ThreadPoolExecutor(
+ max_workers=max_workers,
+ thread_name_prefix="openviking-asyncio",
+ )
+ asyncio.get_running_loop().set_default_executor(executor)
+ logger.info("Configured asyncio default executor: max_workers=%d", max_workers)
+
+
def create_worker_app() -> FastAPI:
"""Load file config and replay parent-process Bot CLI overrides."""
resolved_config_path = resolve_config_path(
@@ -310,6 +330,7 @@ def create_app(
async def lifespan(app: FastAPI):
"""Application lifespan handler."""
nonlocal service
+ _configure_default_executor(config)
owns_service = service is None
if owns_service:
service = OpenVikingService()
diff --git a/openviking/server/config.py b/openviking/server/config.py
index ed4d9c6d4..bf579d36f 100644
--- a/openviking/server/config.py
+++ b/openviking/server/config.py
@@ -328,6 +328,14 @@ class ServerConfig(BaseModel):
host: str = "127.0.0.1"
port: int = 1933
workers: int = 1
+ executor_threads: int = Field(
+ default=0,
+ ge=0,
+ description=(
+ "Maximum number of threads in each server process's default asyncio "
+ "executor. Zero keeps Python's default sizing policy."
+ ),
+ )
# Seconds an idle HTTP keep-alive connection is kept open before the server
# closes it. Defaults to 5 to match uvicorn's built-in default and preserve
# the existing service behavior. Raise it above the idle-connection lifetime
diff --git a/tests/server/test_bootstrap.py b/tests/server/test_bootstrap.py
index 65f68120f..9241411ec 100644
--- a/tests/server/test_bootstrap.py
+++ b/tests/server/test_bootstrap.py
@@ -327,3 +327,35 @@ def test_resolve_queuefs_mount_point_worker_mode_falls_back_to_pid(monkeypatch):
config = StorageConfig(agfs={"queuefs": {"mode": "worker"}})
assert resolve_queuefs_mount_point(config) == "/queue/worker-43210"
+
+
+def test_configure_default_executor_uses_configured_size(monkeypatch):
+ created: dict[str, object] = {}
+
+ class _Executor:
+ def __init__(self, *, max_workers, thread_name_prefix):
+ created["max_workers"] = max_workers
+ created["thread_name_prefix"] = thread_name_prefix
+
+ class _Loop:
+ def set_default_executor(self, executor):
+ created["executor"] = executor
+
+ monkeypatch.setattr(app_module, "ThreadPoolExecutor", _Executor)
+ monkeypatch.setattr(app_module.asyncio, "get_running_loop", lambda: _Loop())
+
+ app_module._configure_default_executor(ServerConfig(executor_threads=48))
+
+ assert created["max_workers"] == 48
+ assert created["thread_name_prefix"] == "openviking-asyncio"
+ assert created["executor"].__class__ is _Executor
+
+
+def test_configure_default_executor_keeps_python_default_when_zero(monkeypatch):
+ monkeypatch.setattr(
+ app_module.asyncio,
+ "get_running_loop",
+ lambda: pytest.fail("event loop should not be touched when the setting is zero"),
+ )
+
+ app_module._configure_default_executor(ServerConfig())
diff --git a/tests/test_server_config_loader.py b/tests/test_server_config_loader.py
index 0a670d7e7..1ad057166 100644
--- a/tests/test_server_config_loader.py
+++ b/tests/test_server_config_loader.py
@@ -61,6 +61,7 @@ def test_load_server_config_preserves_supported_fields(tmp_path):
"host": "0.0.0.0",
"port": 1944,
"workers": 2,
+ "executor_threads": 64,
"timeout_keep_alive": 120,
"auth_mode": "trusted",
"with_bot": True,
@@ -78,6 +79,7 @@ def test_load_server_config_preserves_supported_fields(tmp_path):
assert config.host == "0.0.0.0"
assert config.port == 1944
assert config.workers == 2
+ assert config.executor_threads == 64
assert config.timeout_keep_alive == 120
assert config.auth_mode == "trusted"
assert config.with_bot is True
@@ -93,6 +95,18 @@ def test_load_server_config_defaults_timeout_keep_alive(tmp_path):
config = load_server_config(str(config_path))
assert config.timeout_keep_alive == 5
+ assert config.executor_threads == 0
+
+
+def test_load_server_config_rejects_negative_default_executor_size(tmp_path):
+ config_path = tmp_path / "ov.conf"
+ config_path.write_text(json.dumps({"server": {"executor_threads": -1}}))
+
+ with pytest.raises(
+ ValueError,
+ match=r"server\.executor_threads",
+ ):
+ load_server_config(str(config_path))
def test_load_server_config_rejects_legacy_queuefs_scope(tmp_path):