Skip to content

armgit / LEANN

Public Imported from GitHub
0

[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.

feat: reduce cold start latency with daemonized embedding server reuse (#258)

Andy Lee88445502942a
diff --git a/packages/leann-backend-diskann/leann_backend_diskann/diskann_embedding_server.py b/packages/leann-backend-diskann/leann_backend_diskann/diskann_embedding_server.py
index 592fddb..c354675 100644
--- a/packages/leann-backend-diskann/leann_backend_diskann/diskann_embedding_server.py
+++ b/packages/leann-backend-diskann/leann_backend_diskann/diskann_embedding_server.py
@@ -48,6 +48,8 @@ def create_diskann_embedding_server(
model_name: str = "sentence-transformers/all-mpnet-base-v2",
embedding_mode: str = "sentence-transformers",
distance_metric: str = "l2",
+ enable_warmup: bool = False,
+ daemon_ttl: int = 0,
):
"""
Create and start a ZMQ-based embedding server for DiskANN backend.
@@ -72,6 +74,19 @@ def create_diskann_embedding_server(
finally:
sys.path.pop(0)
+ if enable_warmup:
+ try:
+ logger.info("Starting warmup embedding request...")
+ _ = compute_embeddings(
+ ["__LEANN_WARMUP__"],
+ model_name,
+ mode=embedding_mode,
+ provider_options=PROVIDER_OPTIONS,
+ )
+ logger.info("Warmup complete.")
+ except Exception as exc:
+ logger.warning(f"Warmup failed (continuing): {exc}")
+
# Check port availability
import socket
@@ -259,6 +274,7 @@ def create_diskann_embedding_server(
e2e_start = time.time()
# REP socket receives single-part messages
message = rep_socket.recv()
+ last_activity[0] = time.time()
# Check for empty messages - REP socket requires response to every request
if not message:
@@ -385,6 +401,7 @@ def create_diskann_embedding_server(
# Add shutdown coordination
shutdown_event = threading.Event()
+ last_activity = [time.time()]
def shutdown_zmq_server():
"""Gracefully shutdown ZMQ server."""
@@ -437,6 +454,12 @@ def create_diskann_embedding_server(
# Keep the main thread alive
try:
while not shutdown_event.is_set():
+ if daemon_ttl > 0 and (time.time() - last_activity[0]) >= daemon_ttl:
+ logger.info(
+ f"No requests for {daemon_ttl} seconds, shutting down daemon on port {zmq_port}"
+ )
+ shutdown_zmq_server()
+ return
time.sleep(0.1) # Check shutdown more frequently
except KeyboardInterrupt:
logger.info("DiskANN Server shutting down...")
@@ -479,6 +502,22 @@ if __name__ == "__main__":
choices=["l2", "mips", "cosine"],
help="Distance metric for similarity computation",
)
+ parser.add_argument(
+ "--enable-warmup",
+ action="store_true",
+ help="Preload model by running one warmup embedding at startup",
+ )
+ parser.add_argument(
+ "--daemon-mode",
+ action="store_true",
+ help="Run as daemon mode (enables idle TTL checks)",
+ )
+ parser.add_argument(
+ "--daemon-ttl",
+ type=int,
+ default=0,
+ help="Idle TTL in seconds for daemon mode; 0 disables auto-exit",
+ )
args = parser.parse_args()
@@ -489,4 +528,6 @@ if __name__ == "__main__":
model_name=args.model_name,
embedding_mode=args.embedding_mode,
distance_metric=args.distance_metric,
+ enable_warmup=args.enable_warmup,
+ daemon_ttl=args.daemon_ttl if args.daemon_mode else 0,
)
diff --git a/packages/leann-backend-hnsw/leann_backend_hnsw/hnsw_embedding_server.py b/packages/leann-backend-hnsw/leann_backend_hnsw/hnsw_embedding_server.py
index b55fa24..c93a996 100644
--- a/packages/leann-backend-hnsw/leann_backend_hnsw/hnsw_embedding_server.py
+++ b/packages/leann-backend-hnsw/leann_backend_hnsw/hnsw_embedding_server.py
@@ -61,6 +61,8 @@ def create_hnsw_embedding_server(
model_name: str = "sentence-transformers/all-mpnet-base-v2",
distance_metric: str = "mips",
embedding_mode: str = "sentence-transformers",
+ enable_warmup: bool = False,
+ daemon_ttl: int = 0,
):
"""
Create and start a ZMQ-based embedding server for HNSW backend.
@@ -85,6 +87,19 @@ def create_hnsw_embedding_server(
finally:
sys.path.pop(0)
+ if enable_warmup:
+ try:
+ logger.info("Starting warmup embedding request...")
+ _ = compute_embeddings(
+ ["__LEANN_WARMUP__"],
+ model_name,
+ mode=embedding_mode,
+ provider_options=PROVIDER_OPTIONS,
+ )
+ logger.info("Warmup complete.")
+ except Exception as exc:
+ logger.warning(f"Warmup failed (continuing): {exc}")
+
# Check port availability
import socket
@@ -335,6 +350,7 @@ def create_hnsw_embedding_server(
try:
logger.debug("🔍 Waiting for ZMQ message...")
request_bytes = rep_socket.recv()
+ last_activity[0] = time.time()
except zmq.Again:
continue
@@ -402,6 +418,7 @@ def create_hnsw_embedding_server(
# Add shutdown coordination
shutdown_event = threading.Event()
+ last_activity = [time.time()]
def shutdown_zmq_server():
"""Gracefully shutdown ZMQ server."""
@@ -454,6 +471,12 @@ def create_hnsw_embedding_server(
# Keep the main thread alive
try:
while not shutdown_event.is_set():
+ if daemon_ttl > 0 and (time.time() - last_activity[0]) >= daemon_ttl:
+ logger.info(
+ f"No requests for {daemon_ttl} seconds, shutting down daemon on port {zmq_port}"
+ )
+ shutdown_zmq_server()
+ return
time.sleep(0.1) # Check shutdown more frequently
except KeyboardInterrupt:
logger.info("HNSW Server shutting down...")
@@ -492,6 +515,22 @@ if __name__ == "__main__":
choices=["sentence-transformers", "openai", "mlx", "ollama"],
help="Embedding backend mode",
)
+ parser.add_argument(
+ "--enable-warmup",
+ action="store_true",
+ help="Preload model by running one warmup embedding at startup",
+ )
+ parser.add_argument(
+ "--daemon-mode",
+ action="store_true",
+ help="Run as daemon mode (enables idle TTL checks)",
+ )
+ parser.add_argument(
+ "--daemon-ttl",
+ type=int,
+ default=0,
+ help="Idle TTL in seconds for daemon mode; 0 disables auto-exit",
+ )
args = parser.parse_args()
@@ -502,4 +541,6 @@ if __name__ == "__main__":
model_name=args.model_name,
distance_metric=args.distance_metric,
embedding_mode=args.embedding_mode,
+ enable_warmup=args.enable_warmup,
+ daemon_ttl=args.daemon_ttl if args.daemon_mode else 0,
)
diff --git a/packages/leann-core/src/leann/api.py b/packages/leann-core/src/leann/api.py
index f6156ca..34440cf 100644
--- a/packages/leann-core/src/leann/api.py
+++ b/packages/leann-core/src/leann/api.py
@@ -884,6 +884,8 @@ class LeannBuilder:
embedding_mode=passage_meta_mode,
passages_file=str(meta_path),
distance_metric=distance_metric,
+ use_daemon=False,
+ enable_warmup=False,
provider_options=passage_provider_options,
)
if not server_started:
@@ -946,6 +948,8 @@ class LeannSearcher:
index_path: str,
enable_warmup: bool = True,
recompute_embeddings: bool = True,
+ use_daemon: bool = True,
+ daemon_ttl_seconds: int = 900,
**backend_kwargs,
):
# Fix path resolution for Colab and other environments
@@ -985,9 +989,13 @@ class LeannSearcher:
# Warmup flag: keep using the existing enable_warmup parameter,
# but default it to True so cold-start happens earlier.
self._warmup: bool = bool(enable_warmup)
+ self._use_daemon: bool = bool(use_daemon)
+ self._daemon_ttl_seconds: int = int(daemon_ttl_seconds)
final_kwargs = {**self.meta_data.get("backend_kwargs", {}), **backend_kwargs}
final_kwargs["enable_warmup"] = self._warmup
+ final_kwargs["use_daemon"] = self._use_daemon
+ final_kwargs["daemon_ttl_seconds"] = self._daemon_ttl_seconds
if self.embedding_options:
final_kwargs.setdefault("embedding_options", self.embedding_options)
self.backend_impl: LeannBackendSearcherInterface = backend_factory.searcher(
@@ -997,23 +1005,17 @@ class LeannSearcher:
# Optional one-shot warmup at construction time to hide cold-start latency.
if self._warmup:
- try:
- _ = self.backend_impl.compute_query_embedding(
- "__LEANN_WARMUP__",
- use_server_if_available=self.recompute_embeddings,
- )
- except Exception as exc:
- logger.warning(f"Warmup embedding failed (ignored): {exc}")
+ self.warmup()
- # Optional one-shot warmup at construction time to hide cold-start latency.
- if self._warmup:
- try:
- _ = self.backend_impl.compute_query_embedding(
- "__LEANN_WARMUP__",
- use_server_if_available=self.recompute_embeddings,
- )
- except Exception as exc:
- logger.warning(f"Warmup embedding failed (ignored): {exc}")
+ def warmup(self) -> None:
+ """Warm up embedding path so first user query is faster."""
+ try:
+ _ = self.backend_impl.compute_query_embedding(
+ "__LEANN_WARMUP__",
+ use_server_if_available=self.recompute_embeddings,
+ )
+ except Exception as exc:
+ logger.warning(f"Warmup embedding failed (ignored): {exc}")
def search(
self,
@@ -1109,6 +1111,9 @@ class LeannSearcher:
zmq_port = self.backend_impl._ensure_server_running(
self.meta_path_str,
port=expected_zmq_port,
+ enable_warmup=self._warmup,
+ use_daemon=self._use_daemon,
+ daemon_ttl_seconds=self._daemon_ttl_seconds,
**kwargs,
)
del expected_zmq_port
diff --git a/packages/leann-core/src/leann/cli.py b/packages/leann-core/src/leann/cli.py
index d4d2907..59ee874 100644
--- a/packages/leann-core/src/leann/cli.py
+++ b/packages/leann-core/src/leann/cli.py
@@ -14,6 +14,7 @@ from llama_index.core.node_parser import SentenceSplitter
from tqdm import tqdm
from .api import LeannBuilder, LeannChat, LeannSearcher
+from .embedding_server_manager import EmbeddingServerManager
from .interactive_utils import create_cli_session
from .registry import register_project_directory
from .settings import (
@@ -370,6 +371,81 @@ Examples:
default=None,
help="Prompt template to prepend to query for embedding (e.g., 'query: ' for search)",
)
+ search_parser.add_argument(
+ "--daemon",
+ dest="use_daemon",
+ action=argparse.BooleanOptionalAction,
+ default=True,
+ help="Enable/disable cross-process daemon reuse for embedding server (default: enabled)",
+ )
+ search_parser.add_argument(
+ "--daemon-ttl",
+ type=int,
+ default=900,
+ help="Daemon idle TTL in seconds (default: 900, 0 = never expire)",
+ )
+ search_parser.add_argument(
+ "--warmup",
+ dest="enable_warmup",
+ action=argparse.BooleanOptionalAction,
+ default=True,
+ help="Enable/disable warmup when starting embedding server (default: enabled)",
+ )
+
+ # Warmup command
+ warmup_parser = subparsers.add_parser("warmup", help="Warm up an index embedding server")
+ warmup_parser.add_argument("index_name", help="Index name")
+ warmup_parser.add_argument(
+ "--daemon",
+ dest="use_daemon",
+ action=argparse.BooleanOptionalAction,
+ default=True,
+ help="Enable/disable daemon mode for warmup (default: enabled)",
+ )
+ warmup_parser.add_argument(
+ "--daemon-ttl",
+ type=int,
+ default=900,
+ help="Daemon idle TTL in seconds (default: 900, 0 = never expire)",
+ )
+ warmup_parser.add_argument(
+ "--warmup",
+ dest="enable_warmup",
+ action=argparse.BooleanOptionalAction,
+ default=True,
+ help="Enable/disable warmup request itself (default: enabled)",
+ )
+
+ # Daemon command
+ daemon_parser = subparsers.add_parser("daemon", help="Manage embedding daemons")
+ daemon_subparsers = daemon_parser.add_subparsers(dest="daemon_command")
+
+ daemon_start = daemon_subparsers.add_parser("start", help="Start daemon for an index")
+ daemon_start.add_argument("index_name", help="Index name")
+ daemon_start.add_argument(
+ "--daemon-ttl",
+ type=int,
+ default=900,
+ help="Daemon idle TTL in seconds (default: 900, 0 = never expire)",
+ )
+ daemon_start.add_argument(
+ "--warmup",
+ dest="enable_warmup",
+ action=argparse.BooleanOptionalAction,
+ default=True,
+ help="Enable/disable startup warmup (default: enabled)",
+ )
+
+ daemon_stop = daemon_subparsers.add_parser("stop", help="Stop daemon(s)")
+ daemon_stop.add_argument("index_name", nargs="?", help="Index name to stop")
+ daemon_stop.add_argument(
+ "--all",
+ action="store_true",
+ help="Stop all LEANN embedding daemons",
+ )
+
+ daemon_status = daemon_subparsers.add_parser("status", help="Show daemon status")
+ daemon_status.add_argument("index_name", nargs="?", help="Optional index name filter")
# Ask command
ask_parser = subparsers.add_parser("ask", help="Ask questions")
@@ -1814,111 +1890,105 @@ Examples:
print(f" - {file_path}")
print(f" chunks: {chunk_display}")
- async def search_documents(self, args):
- index_name = args.index_name
- query = args.query
-
- # First try to find the index in current project
- index_path = self.get_index_path(index_name)
+ def _resolve_index_path(
+ self,
+ index_name: str,
+ *,
+ non_interactive: bool = True,
+ purpose: str = "use",
+ ) -> Optional[str]:
+ """Resolve index path from current project or registered projects."""
if self.index_exists(index_name):
- # Found in current project, use it
- pass
- else:
- # Search across all registered projects (like list_indexes does)
- all_matches = self._find_all_matching_indexes(index_name)
- if not all_matches:
- print(
- f"Index '{index_name}' not found. Use 'leann build {index_name} --docs <dir> [<dir2> ...]' to create it."
- )
- return
- elif len(all_matches) == 1:
- # Found exactly one match, use it
- match = all_matches[0]
- if match["kind"] == "cli":
- index_path = str(match["index_dir"] / "documents.leann")
- else:
- # App format: use the meta file to construct the path
- meta_file = match["meta_file"]
- file_base = match["file_base"]
- index_path = str(meta_file.parent / f"{file_base}.leann")
+ return self.get_index_path(index_name)
+ all_matches = self._find_all_matching_indexes(index_name)
+ if not all_matches:
+ print(
+ f"Index '{index_name}' not found. Use 'leann build {index_name} --docs <dir> [<dir2> ...]' to create it."
+ )
+ return None
+
+ def _match_to_path(match: dict[str, Any]) -> str:
+ if match["kind"] == "cli":
+ return str(match["index_dir"] / "documents.leann")
+ meta_file = match["meta_file"]
+ file_base = match["file_base"]
+ return str(meta_file.parent / f"{file_base}.leann")
+
+ if len(all_matches) == 1:
+ match = all_matches[0]
+ project_info = (
+ "current project"
+ if match["is_current"]
+ else f"project '{match['project_path'].name}'"
+ )
+ print(f"Using index '{index_name}' from {project_info}")
+ return _match_to_path(match)
+
+ if non_interactive:
+ current_matches = [m for m in all_matches if m["is_current"]]
+ match = current_matches[0] if current_matches else all_matches[0]
+ location_desc = (
+ "current project"
+ if match["is_current"]
+ else f"project '{match['project_path'].name}'"
+ )
+ print(
+ f"Found {len(all_matches)} indexes named '{index_name}', using index from {location_desc}"
+ )
+ return _match_to_path(match)
+
+ print(f"Found {len(all_matches)} indexes named '{index_name}':")
+ for i, match in enumerate(all_matches, 1):
+ project_path = match["project_path"]
+ is_current = match["is_current"]
+ kind = match.get("kind", "cli")
+ if is_current:
+ print(f" {i}. 🏠 Current project ({'CLI' if kind == 'cli' else 'APP'})")
+ else:
+ print(f" {i}. 📂 {project_path.name} ({'CLI' if kind == 'cli' else 'APP'})")
+
+ try:
+ choice = input(f"Which index to {purpose}? (1-{len(all_matches)}): ").strip()
+ choice_idx = int(choice) - 1
+ if 0 <= choice_idx < len(all_matches):
+ match = all_matches[choice_idx]
project_info = (
"current project"
if match["is_current"]
else f"project '{match['project_path'].name}'"
)
print(f"Using index '{index_name}' from {project_info}")
- else:
- # Multiple matches found
- if args.non_interactive:
- # Non-interactive mode: automatically select the best match
- # Priority: current project first, then first available
- current_matches = [m for m in all_matches if m["is_current"]]
- if current_matches:
- match = current_matches[0]
- location_desc = "current project"
- else:
- match = all_matches[0]
- location_desc = f"project '{match['project_path'].name}'"
-
- if match["kind"] == "cli":
- index_path = str(match["index_dir"] / "documents.leann")
- else:
- meta_file = match["meta_file"]
- file_base = match["file_base"]
- index_path = str(meta_file.parent / f"{file_base}.leann")
+ return _match_to_path(match)
+ print("Invalid choice. Aborting.")
+ return None
+ except (ValueError, KeyboardInterrupt):
+ print("Invalid input. Aborting.")
+ return None
- print(
- f"Found {len(all_matches)} indexes named '{index_name}', using index from {location_desc}"
- )
- else:
- # Interactive mode: ask user to choose
- print(f"Found {len(all_matches)} indexes named '{index_name}':")
- for i, match in enumerate(all_matches, 1):
- project_path = match["project_path"]
- is_current = match["is_current"]
- kind = match.get("kind", "cli")
-
- if is_current:
- print(
- f" {i}. 🏠 Current project ({'CLI' if kind == 'cli' else 'APP'})"
- )
- else:
- print(
- f" {i}. 📂 {project_path.name} ({'CLI' if kind == 'cli' else 'APP'})"
- )
+ async def search_documents(self, args):
+ index_name = args.index_name
+ query = args.query
- try:
- choice = input(f"Which index to search? (1-{len(all_matches)}): ").strip()
- choice_idx = int(choice) - 1
- if 0 <= choice_idx < len(all_matches):
- match = all_matches[choice_idx]
- if match["kind"] == "cli":
- index_path = str(match["index_dir"] / "documents.leann")
- else:
- meta_file = match["meta_file"]
- file_base = match["file_base"]
- index_path = str(meta_file.parent / f"{file_base}.leann")
-
- project_info = (
- "current project"
- if match["is_current"]
- else f"project '{match['project_path'].name}'"
- )
- print(f"Using index '{index_name}' from {project_info}")
- else:
- print("Invalid choice. Aborting search.")
- return
- except (ValueError, KeyboardInterrupt):
- print("Invalid input. Aborting search.")
- return
+ index_path = self._resolve_index_path(
+ index_name,
+ non_interactive=args.non_interactive,
+ purpose="search",
+ )
+ if not index_path:
+ return
# Build provider_options for runtime override
provider_options = {}
if args.embedding_prompt_template:
provider_options["prompt_template"] = args.embedding_prompt_template
- searcher = LeannSearcher(index_path=index_path)
+ searcher = LeannSearcher(
+ index_path=index_path,
+ enable_warmup=args.enable_warmup,
+ use_daemon=args.use_daemon,
+ daemon_ttl_seconds=args.daemon_ttl,
+ )
results = searcher.search(
query,
top_k=args.top_k,
@@ -1954,6 +2024,105 @@ Examples:
print(f" Source: {result.metadata.get('source', '')}")
print()
+ async def warmup_index(self, args):
+ index_path = self._resolve_index_path(
+ args.index_name,
+ non_interactive=True,
+ purpose="warm up",
+ )
+ if not index_path:
+ return
+
+ searcher = LeannSearcher(
+ index_path=index_path,
+ recompute_embeddings=True,
+ enable_warmup=args.enable_warmup,
+ use_daemon=args.use_daemon,
+ daemon_ttl_seconds=args.daemon_ttl,
+ )
+ if args.enable_warmup:
+ searcher.warmup()
+ print(
+ f"Warmed index '{args.index_name}' (daemon={'on' if args.use_daemon else 'off'}, ttl={args.daemon_ttl}s)"
+ )
+
+ async def daemon_command(self, args):
+ if not args.daemon_command:
+ print("Please specify one of: start, stop, status")
+ return
+
+ if args.daemon_command == "status":
+ records = EmbeddingServerManager.list_daemons()
+ if args.index_name:
+ index_path = self._resolve_index_path(
+ args.index_name,
+ non_interactive=True,
+ purpose="check daemon status for",
+ )
+ if not index_path:
+ return
+ meta_path = str(Path(f"{index_path}.meta.json").resolve())
+ records = [
+ r
+ for r in records
+ if r.get("config_signature", {}).get("passages_file") == meta_path
+ ]
+
+ if not records:
+ print("No active embedding daemons.")
+ return
+
+ print(f"Active embedding daemons: {len(records)}")
+ for record in records:
+ cfg = record.get("config_signature", {})
+ print(
+ f"- pid={record.get('pid')} port={record.get('port')} backend={record.get('backend_module_name')} model={cfg.get('model_name')}"
+ )
+ return
+
+ if args.daemon_command == "start":
+ index_path = self._resolve_index_path(
+ args.index_name,
+ non_interactive=True,
+ purpose="start daemon for",
+ )
+ if not index_path:
+ return
+
+ searcher = LeannSearcher(
+ index_path=index_path,
+ recompute_embeddings=True,
+ enable_warmup=args.enable_warmup,
+ use_daemon=True,
+ daemon_ttl_seconds=args.daemon_ttl,
+ )
+ searcher.warmup()
+ print(
+ f"Daemon started for '{args.index_name}' (ttl={args.daemon_ttl}s, warmup={'on' if args.enable_warmup else 'off'})"
+ )
+ return
+
+ if args.daemon_command == "stop":
+ if args.all:
+ stopped = EmbeddingServerManager.stop_daemons()
+ print(f"Stopped {stopped} daemon(s).")
+ return
+
+ if not args.index_name:
+ print("Provide an index name or pass --all.")
+ return
+
+ index_path = self._resolve_index_path(
+ args.index_name,
+ non_interactive=True,
+ purpose="stop daemon for",
+ )
+ if not index_path:
+ return
+ meta_path = str(Path(f"{index_path}.meta.json").resolve())
+ stopped = EmbeddingServerManager.stop_daemons(passages_file=meta_path)
+ print(f"Stopped {stopped} daemon(s) for index '{args.index_name}'.")
+
async def ask_questions(self, args):
index_name = args.index_name
index_path = self.get_index_path(index_name)
@@ -2148,6 +2317,11 @@ Examples:
elif args.command == "search":
with suppress_cpp_output(suppress):
await self.search_documents(args)
+ elif args.command == "warmup":
+ with suppress_cpp_output(suppress):
+ await self.warmup_index(args)
+ elif args.command == "daemon":
+ await self.daemon_command(args)
elif args.command == "ask":
with suppress_cpp_output(suppress):
await self.ask_questions(args)
diff --git a/packages/leann-core/src/leann/embedding_server_manager.py b/packages/leann-core/src/leann/embedding_server_manager.py
index b9224ac..ac95e51 100644
--- a/packages/leann-core/src/leann/embedding_server_manager.py
+++ b/packages/leann-core/src/leann/embedding_server_manager.py
@@ -1,4 +1,6 @@
import atexit
+import contextlib
+import hashlib
import json
import logging
import os
@@ -7,7 +9,7 @@ import subprocess
import sys
import time
from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
from .settings import encode_provider_options
@@ -20,6 +22,7 @@ logging.basicConfig(
format="%(levelname)s - %(name)s - %(message)s",
)
logger = logging.getLogger(__name__)
+_LOCK_STALE_SECONDS = 600
def _is_colab_environment() -> bool:
@@ -46,6 +49,17 @@ def _check_port(port: int) -> bool:
return s.connect_ex(("localhost", port)) == 0
+def _pid_is_alive(pid: int) -> bool:
+ """Best-effort liveness check for a process id."""
+ if pid <= 0:
+ return False
+ try:
+ os.kill(pid, 0)
+ return True
+ except OSError:
+ return False
+
+
# Note: All cross-process scanning helpers removed for simplicity
@@ -146,6 +160,8 @@ class EmbeddingServerManager:
self.server_port: Optional[int] = None
# Track last-started config for in-process reuse only
self._server_config: Optional[dict] = None
+ self._daemon_mode = False
+ self._registry_path: Optional[Path] = None
self._atexit_registered = False
# Also register a weakref finalizer to ensure cleanup when manager is GC'ed
try:
@@ -166,12 +182,16 @@ class EmbeddingServerManager:
# passages_file may be present in kwargs for server CLI, but we don't need it here
provider_options = kwargs.pop("provider_options", None)
passages_file = kwargs.get("passages_file", "")
+ distance_metric = kwargs.get("distance_metric", "")
+ use_daemon = bool(kwargs.get("use_daemon", True))
+ daemon_ttl_seconds = int(kwargs.get("daemon_ttl_seconds", 900))
config_signature = self._build_config_signature(
model_name=model_name,
embedding_mode=embedding_mode,
provider_options=provider_options,
passages_file=passages_file,
+ distance_metric=distance_metric,
)
# If this manager already has a live server, just reuse it
@@ -184,11 +204,22 @@ class EmbeddingServerManager:
logger.info("Reusing in-process server")
return True, self.server_port
- # Configuration changed, stop existing server before starting a new one
- if self.server_process and self.server_process.poll() is None:
+ # Configuration changed, stop existing ephemeral server before starting a new one
+ if self.server_process and self.server_process.poll() is None and not self._daemon_mode:
logger.info("Existing server configuration differs; restarting embedding server")
self.stop_server()
+ # Reuse an already-running daemon from registry if possible.
+ if use_daemon and not _is_colab_environment():
+ with self._registry_lock(config_signature):
+ adopted = self._adopt_registered_server(config_signature)
+ if adopted is not None:
+ self.server_process = None
+ self.server_port = adopted
+ self._server_config = config_signature
+ self._daemon_mode = True
+ return True, adopted
+
# For Colab environment, use a different strategy
if _is_colab_environment():
logger.info("Detected Colab environment, using alternative startup strategy")
@@ -208,8 +239,34 @@ class EmbeddingServerManager:
logger.error("No available ports found")
return False, port
- # Start a new server
- return self._start_new_server(
+ # Start a new server (guarded by lock in daemon mode to avoid race).
+ if use_daemon and not _is_colab_environment():
+ with self._registry_lock(config_signature):
+ adopted = self._adopt_registered_server(config_signature)
+ if adopted is not None:
+ self.server_process = None
+ self.server_port = adopted
+ self._server_config = config_signature
+ self._daemon_mode = True
+ return True, adopted
+ started, actual_port = self._start_new_server(
+ actual_port,
+ model_name,
+ embedding_mode,
+ provider_options=provider_options,
+ config_signature=config_signature,
+ **kwargs,
+ )
+ if started:
+ self._daemon_mode = True
+ self._registry_path = self._write_registry_record(
+ port=actual_port,
+ config_signature=config_signature,
+ daemon_ttl_seconds=daemon_ttl_seconds,
+ )
+ return started, actual_port
+
+ started, actual_port = self._start_new_server(
actual_port,
model_name,
embedding_mode,
@@ -217,6 +274,9 @@ class EmbeddingServerManager:
config_signature=config_signature,
**kwargs,
)
+ if started:
+ self._daemon_mode = False
+ return started, actual_port
def _build_config_signature(
self,
@@ -225,12 +285,17 @@ class EmbeddingServerManager:
embedding_mode: str,
provider_options: Optional[dict],
passages_file: Optional[str],
+ distance_metric: Optional[str],
) -> dict:
"""Create a signature describing the current server configuration."""
+ passages_path = ""
+ if passages_file:
+ passages_path = _safe_resolve(Path(passages_file))
return {
"model_name": model_name,
- "passages_file": passages_file or "",
+ "passages_file": passages_path,
"embedding_mode": embedding_mode,
+ "distance_metric": distance_metric or "",
"provider_options": provider_options or {},
"passages_signature": _build_passages_signature(passages_file),
}
@@ -337,6 +402,12 @@ class EmbeddingServerManager:
command.extend(["--embedding-mode", embedding_mode])
if kwargs.get("distance_metric"):
command.extend(["--distance-metric", kwargs["distance_metric"]])
+ if kwargs.get("enable_warmup", True):
+ command.append("--enable-warmup")
+ if kwargs.get("use_daemon", True):
+ command.append("--daemon-mode")
+ ttl = int(kwargs.get("daemon_ttl_seconds", 900))
+ command.extend(["--daemon-ttl", str(ttl)])
return command
@@ -441,6 +512,15 @@ class EmbeddingServerManager:
def stop_server(self):
"""Stops the embedding server process if it's running."""
+ if self._daemon_mode:
+ # Daemon is intentionally process-global: this manager detaches by default.
+ self.server_process = None
+ self.server_port = None
+ self._server_config = None
+ self._daemon_mode = False
+ self._registry_path = None
+ return
+
if not self.server_process:
return
@@ -505,7 +585,7 @@ class EmbeddingServerManager:
pass
def _adopt_existing_server(self, *args, **kwargs) -> None:
- # Removed: cross-process adoption no longer supported
+ # Legacy no-op retained for compatibility.
return
def _launch_server_process_colab(
@@ -572,3 +652,182 @@ class EmbeddingServerManager:
logger.error(f"Colab server failed to start within {max_wait} seconds.")
self.stop_server()
return False, port
+
+ @staticmethod
+ def _registry_dir() -> Path:
+ return Path.home() / ".leann" / "servers"
+
+ @contextlib.contextmanager
+ def _registry_lock(self, config_signature: dict[str, Any]):
+ """Best-effort cross-process lock around a daemon registry key."""
+ lock_file = None
+ lock_info_path: Optional[Path] = None
+ try:
+ lock_path = self._registry_dir()
+ lock_path.mkdir(parents=True, exist_ok=True)
+ lock_key = self._registry_key(config_signature)
+ lock_file = (lock_path / f"{lock_key}.lock").open("a+")
+ lock_info_path = lock_path / f"{lock_key}.lockinfo.json"
+ self._recover_stale_lock_info(lock_info_path)
+ try:
+ import fcntl
+
+ fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+ except Exception:
+ # Non-POSIX or unavailable locking: proceed without hard lock.
+ pass
+ self._write_lock_info(lock_info_path)
+ yield
+ finally:
+ if lock_info_path is not None:
+ lock_info_path.unlink(missing_ok=True)
+ if lock_file is not None:
+ try:
+ import fcntl
+
+ fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+ except Exception:
+ pass
+ lock_file.close()
+
+ def _recover_stale_lock_info(self, lock_info_path: Path) -> None:
+ if not lock_info_path.exists():
+ return
+ try:
+ info = json.loads(lock_info_path.read_text(encoding="utf-8"))
+ pid = int(info.get("pid") or 0)
+ ts = float(info.get("ts") or 0)
+ except Exception:
+ lock_info_path.unlink(missing_ok=True)
+ return
+
+ age = (time.time() - ts) if ts else (_LOCK_STALE_SECONDS + 1)
+ if age > _LOCK_STALE_SECONDS or (pid > 0 and not _pid_is_alive(pid)):
+ lock_info_path.unlink(missing_ok=True)
+
+ def _write_lock_info(self, lock_info_path: Path) -> None:
+ payload = {"pid": os.getpid(), "ts": time.time()}
+ tmp_path = lock_info_path.with_suffix(".tmp")
+ tmp_path.write_text(json.dumps(payload), encoding="utf-8")
+ os.replace(tmp_path, lock_info_path)
+
+ def _registry_key(self, config_signature: dict[str, Any]) -> str:
+ payload = {
+ "backend_module_name": self.backend_module_name,
+ "config_signature": config_signature,
+ }
+ encoded = json.dumps(payload, sort_keys=True, ensure_ascii=True).encode("utf-8")
+ return hashlib.sha256(encoded).hexdigest()
+
+ def _write_registry_record(
+ self,
+ *,
+ port: int,
+ config_signature: dict[str, Any],
+ daemon_ttl_seconds: int,
+ ) -> Path:
+ registry_dir = self._registry_dir()
+ registry_dir.mkdir(parents=True, exist_ok=True)
+ registry_path = registry_dir / f"{self._registry_key(config_signature)}.json"
+ record = {
+ "pid": self.server_process.pid if self.server_process else None,
+ "port": port,
+ "backend_module_name": self.backend_module_name,
+ "daemon_ttl_seconds": int(daemon_ttl_seconds),
+ "created_at": time.time(),
+ "config_signature": config_signature,
+ }
+ tmp_path = registry_path.with_suffix(".json.tmp")
+ tmp_path.write_text(json.dumps(record, indent=2), encoding="utf-8")
+ os.replace(tmp_path, registry_path)
+ return registry_path
+
+ def _adopt_registered_server(self, config_signature: dict[str, Any]) -> Optional[int]:
+ registry_dir = self._registry_dir()
+ if not registry_dir.exists():
+ return None
+
+ target = registry_dir / f"{self._registry_key(config_signature)}.json"
+ if not target.exists():
+ return None
+
+ try:
+ record = json.loads(target.read_text(encoding="utf-8"))
+ except Exception:
+ target.unlink(missing_ok=True)
+ return None
+
+ if record.get("backend_module_name") != self.backend_module_name:
+ target.unlink(missing_ok=True)
+ return None
+ if record.get("config_signature") != config_signature:
+ target.unlink(missing_ok=True)
+ return None
+
+ pid = int(record.get("pid") or 0)
+ port = int(record.get("port") or 0)
+ if not _pid_is_alive(pid) or not _check_port(port):
+ target.unlink(missing_ok=True)
+ return None
+
+ self._registry_path = target
+ logger.info("Reusing daemonized embedding server on port %s", port)
+ return port
+
+ @classmethod
+ def list_daemons(cls) -> list[dict[str, Any]]:
+ registry_dir = cls._registry_dir()
+ if not registry_dir.exists():
+ return []
+
+ records: list[dict[str, Any]] = []
+ for record_path in sorted(registry_dir.glob("*.json")):
+ try:
+ record = json.loads(record_path.read_text(encoding="utf-8"))
+ except Exception:
+ record_path.unlink(missing_ok=True)
+ continue
+
+ pid = int(record.get("pid") or 0)
+ port = int(record.get("port") or 0)
+ alive = _pid_is_alive(pid) and _check_port(port)
+ if not alive:
+ record_path.unlink(missing_ok=True)
+ continue
+
+ record["record_path"] = str(record_path)
+ records.append(record)
+ return records
+
+ @classmethod
+ def stop_daemons(
+ cls,
+ *,
+ backend_module_name: Optional[str] = None,
+ passages_file: Optional[str] = None,
+ ) -> int:
+ resolved_passages_file = _safe_resolve(Path(passages_file)) if passages_file else None
+ stopped = 0
+ for record in cls.list_daemons():
+ if backend_module_name and record.get("backend_module_name") != backend_module_name:
+ continue
+
+ record_passages = (
+ record.get("config_signature", {}).get("passages_file")
+ if isinstance(record.get("config_signature"), dict)
+ else None
+ )
+ if resolved_passages_file and record_passages != resolved_passages_file:
+ continue
+
+ pid = int(record.get("pid") or 0)
+ try:
+ os.kill(pid, 15)
+ stopped += 1
+ except OSError:
+ pass
+
+ record_path = record.get("record_path")
+ if record_path:
+ Path(record_path).unlink(missing_ok=True)
+ return stopped
diff --git a/packages/leann-core/src/leann/searcher_base.py b/packages/leann-core/src/leann/searcher_base.py
index 1def0ae..a891782 100644
--- a/packages/leann-core/src/leann/searcher_base.py
+++ b/packages/leann-core/src/leann/searcher_base.py
@@ -42,6 +42,9 @@ class BaseSearcher(LeannBackendSearcherInterface, ABC):
self.embedding_mode = self.meta.get("embedding_mode", "sentence-transformers")
self.embedding_options = self.meta.get("embedding_options", {})
+ self.enable_warmup = bool(kwargs.get("enable_warmup", True))
+ self.use_daemon = bool(kwargs.get("use_daemon", True))
+ self.daemon_ttl_seconds = int(kwargs.get("daemon_ttl_seconds", 900))
self.embedding_server_manager = EmbeddingServerManager(
backend_module_name=backend_module_name,
@@ -88,7 +91,9 @@ class BaseSearcher(LeannBackendSearcherInterface, ABC):
embedding_mode=self.embedding_mode,
passages_file=passages_source_file,
distance_metric=distance_metric,
- enable_warmup=kwargs.get("enable_warmup", False),
+ enable_warmup=kwargs.get("enable_warmup", self.enable_warmup),
+ use_daemon=kwargs.get("use_daemon", self.use_daemon),
+ daemon_ttl_seconds=kwargs.get("daemon_ttl_seconds", self.daemon_ttl_seconds),
provider_options=search_provider_options,
)
if not server_started:
@@ -131,7 +136,11 @@ class BaseSearcher(LeannBackendSearcherInterface, ABC):
passages_source_file = self.index_dir / f"{self.index_path.name}.meta.json"
# Convert to absolute path to ensure server can find it
zmq_port = self._ensure_server_running(
- str(passages_source_file.resolve()), zmq_port
+ str(passages_source_file.resolve()),
+ zmq_port,
+ enable_warmup=self.enable_warmup,
+ use_daemon=self.use_daemon,
+ daemon_ttl_seconds=self.daemon_ttl_seconds,
)
return self._compute_embedding_via_server([query], zmq_port)[
diff --git a/tests/support/fake_embedding_server_module.py b/tests/support/fake_embedding_server_module.py
new file mode 100644
index 0000000..a4c64cf
--- /dev/null
+++ b/tests/support/fake_embedding_server_module.py
@@ -0,0 +1,59 @@
+import argparse
+import signal
+import socket
+import time
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Fake embedding server for e2e tests")
+ parser.add_argument("--zmq-port", type=int, required=True)
+ parser.add_argument("--model-name", type=str, required=True)
+ parser.add_argument("--passages-file", type=str, default="")
+ parser.add_argument("--distance-metric", type=str, default="")
+ parser.add_argument("--embedding-mode", type=str, default="sentence-transformers")
+ parser.add_argument("--enable-warmup", action="store_true")
+ parser.add_argument("--daemon-mode", action="store_true")
+ parser.add_argument("--daemon-ttl", type=int, default=0)
+ args = parser.parse_args()
+
+ stop = {"value": False}
+ last_activity = time.time()
+
+ def _handle_signal(signum, frame):
+ stop["value"] = True
+
+ signal.signal(signal.SIGTERM, _handle_signal)
+ signal.signal(signal.SIGINT, _handle_signal)
+
+ # Bind and keep accepting connections so _check_port sees the process as alive.
+ server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+ server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+ server.bind(("127.0.0.1", args.zmq_port))
+ server.listen(16)
+ server.settimeout(0.2)
+
+ try:
+ while not stop["value"]:
+ if args.daemon_mode and args.daemon_ttl > 0:
+ if (time.time() - last_activity) >= args.daemon_ttl:
+ break
+ try:
+ conn, _addr = server.accept()
+ # liveness probes connect+close without sending payload; do not
+ # treat them as activity so TTL expiry can still be observed.
+ try:
+ conn.settimeout(0.01)
+ payload = conn.recv(1)
+ if payload:
+ last_activity = time.time()
+ except Exception:
+ pass
+ conn.close()
+ except socket.timeout:
+ pass
+ finally:
+ server.close()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/test_cli_daemon_workflow.py b/tests/test_cli_daemon_workflow.py
new file mode 100644
index 0000000..43323e0
--- /dev/null
+++ b/tests/test_cli_daemon_workflow.py
@@ -0,0 +1,212 @@
+import argparse
+import asyncio
+from pathlib import Path
+from typing import Any
+
+from leann.cli import LeannCLI
+
+
+def test_search_passes_daemon_flags_to_searcher(monkeypatch):
+ cli = LeannCLI()
+ monkeypatch.setattr(
+ cli,
+ "_resolve_index_path",
+ lambda *args, **kwargs: "/tmp/demo/documents.leann",
+ )
+
+ captured: dict[str, dict[str, Any]] = {"init": {}, "search": {}}
+
+ class DummySearcher:
+ def __init__(self, *args, **kwargs):
+ captured["init"] = kwargs
+
+ def search(self, *args, **kwargs):
+ captured["search"] = kwargs
+ return []
+
+ monkeypatch.setattr("leann.cli.LeannSearcher", DummySearcher)
+
+ args = argparse.Namespace(
+ index_name="demo",
+ query="hello",
+ top_k=3,
+ complexity=64,
+ beam_width=1,
+ prune_ratio=0.0,
+ recompute_embeddings=True,
+ pruning_strategy="global",
+ non_interactive=True,
+ show_metadata=False,
+ embedding_prompt_template=None,
+ use_daemon=True,
+ daemon_ttl=222,
+ enable_warmup=True,
+ )
+ asyncio.run(cli.search_documents(args))
+
+ assert captured["init"]["enable_warmup"] is True
+ assert captured["init"]["use_daemon"] is True
+ assert captured["init"]["daemon_ttl_seconds"] == 222
+ assert captured["search"]["recompute_embeddings"] is True
+
+
+def test_warmup_command_calls_searcher_warmup(monkeypatch):
+ cli = LeannCLI()
+ monkeypatch.setattr(
+ cli,
+ "_resolve_index_path",
+ lambda *args, **kwargs: "/tmp/demo/documents.leann",
+ )
+
+ state: dict[str, int] = {"warmup_called": 0}
+
+ class DummySearcher:
+ def __init__(self, *args, **kwargs):
+ pass
+
+ def warmup(self):
+ state["warmup_called"] += 1
+
+ monkeypatch.setattr("leann.cli.LeannSearcher", DummySearcher)
+
+ args = argparse.Namespace(
+ index_name="demo",
+ use_daemon=True,
+ daemon_ttl=120,
+ enable_warmup=True,
+ )
+ asyncio.run(cli.warmup_index(args))
+ assert state["warmup_called"] == 1
+
+
+def test_daemon_status_filters_by_index(monkeypatch, capsys):
+ cli = LeannCLI()
+ monkeypatch.setattr(
+ cli,
+ "_resolve_index_path",
+ lambda *args, **kwargs: "/tmp/demo/documents.leann",
+ )
+ meta_path = str(Path("/tmp/demo/documents.leann.meta.json").resolve())
+
+ monkeypatch.setattr(
+ "leann.cli.EmbeddingServerManager.list_daemons",
+ lambda: [
+ {
+ "pid": 101,
+ "port": 5557,
+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",
+ "config_signature": {"passages_file": meta_path, "model_name": "m1"},
+ },
+ {
+ "pid": 202,
+ "port": 5558,
+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",
+ "config_signature": {
+ "passages_file": "/tmp/other/doc.meta.json",
+ "model_name": "m2",
+ },
+ },
+ ],
+ )
+
+ args = argparse.Namespace(daemon_command="status", index_name="demo")
+ asyncio.run(cli.daemon_command(args))
+ out = capsys.readouterr().out
+ assert "Active embedding daemons: 1" in out
+ assert "pid=101" in out
+ assert "pid=202" not in out
+
+
+def test_daemon_stop_by_index_calls_stop_daemons(monkeypatch):
+ cli = LeannCLI()
+ monkeypatch.setattr(
+ cli,
+ "_resolve_index_path",
+ lambda *args, **kwargs: "/tmp/demo/documents.leann",
+ )
+ captured: dict[str, dict[str, Any]] = {"kwargs": {}}
+
+ def fake_stop_daemons(**kwargs):
+ captured["kwargs"] = kwargs
+ return 1
+
+ monkeypatch.setattr("leann.cli.EmbeddingServerManager.stop_daemons", fake_stop_daemons)
+
+ args = argparse.Namespace(daemon_command="stop", index_name="demo", all=False)
+ asyncio.run(cli.daemon_command(args))
+
+ assert captured["kwargs"]["passages_file"].endswith("documents.leann.meta.json")
+
+
+def test_daemon_start_calls_searcher_warmup(monkeypatch):
+ cli = LeannCLI()
+ monkeypatch.setattr(
+ cli,
+ "_resolve_index_path",
+ lambda *args, **kwargs: "/tmp/demo/documents.leann",
+ )
+
+ state: dict[str, Any] = {"warmup_called": 0, "init_kwargs": {}}
+
+ class DummySearcher:
+ def __init__(self, *args, **kwargs):
+ state["init_kwargs"] = kwargs
+
+ def warmup(self):
+ state["warmup_called"] += 1
+
+ monkeypatch.setattr("leann.cli.LeannSearcher", DummySearcher)
+
+ args = argparse.Namespace(
+ daemon_command="start",
+ index_name="demo",
+ daemon_ttl=88,
+ enable_warmup=True,
+ )
+ asyncio.run(cli.daemon_command(args))
+
+ assert state["warmup_called"] == 1
+ assert state["init_kwargs"]["use_daemon"] is True
+ assert state["init_kwargs"]["daemon_ttl_seconds"] == 88
+
+
+def test_daemon_status_all_lists_records(monkeypatch, capsys):
+ cli = LeannCLI()
+ monkeypatch.setattr(
+ "leann.cli.EmbeddingServerManager.list_daemons",
+ lambda: [
+ {
+ "pid": 301,
+ "port": 6001,
+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",
+ "config_signature": {"model_name": "m-a"},
+ },
+ {
+ "pid": 302,
+ "port": 6002,
+ "backend_module_name": "leann_backend_diskann.diskann_embedding_server",
+ "config_signature": {"model_name": "m-b"},
+ },
+ ],
+ )
+ args = argparse.Namespace(daemon_command="status", index_name=None)
+ asyncio.run(cli.daemon_command(args))
+ out = capsys.readouterr().out
+ assert "Active embedding daemons: 2" in out
+ assert "pid=301" in out
+ assert "pid=302" in out
+
+
+def test_daemon_stop_all_calls_manager(monkeypatch):
+ cli = LeannCLI()
+ captured = {"called": False}
+
+ def fake_stop_daemons(**kwargs):
+ captured["called"] = True
+ assert kwargs == {}
+ return 2
+
+ monkeypatch.setattr("leann.cli.EmbeddingServerManager.stop_daemons", fake_stop_daemons)
+ args = argparse.Namespace(daemon_command="stop", index_name=None, all=True)
+ asyncio.run(cli.daemon_command(args))
+ assert captured["called"] is True
diff --git a/tests/test_embedding_server_cli_flags.py b/tests/test_embedding_server_cli_flags.py
new file mode 100644
index 0000000..5cc8281
--- /dev/null
+++ b/tests/test_embedding_server_cli_flags.py
@@ -0,0 +1,39 @@
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _run_help(module_name: str) -> str:
+ root = Path(__file__).resolve().parents[1]
+ extra_paths = [
+ str(root / "packages" / "leann-core" / "src"),
+ str(root / "packages" / "leann-backend-hnsw"),
+ str(root / "packages" / "leann-backend-diskann"),
+ ]
+ env = os.environ.copy()
+ existing = env.get("PYTHONPATH", "")
+ env["PYTHONPATH"] = os.pathsep.join(extra_paths + ([existing] if existing else []))
+
+ proc = subprocess.run(
+ [sys.executable, "-m", module_name, "--help"],
+ check=True,
+ text=True,
+ capture_output=True,
+ env=env,
+ )
+ return proc.stdout
+
+
+def test_hnsw_server_help_has_daemon_and_warmup_flags():
+ out = _run_help("leann_backend_hnsw.hnsw_embedding_server")
+ assert "--enable-warmup" in out
+ assert "--daemon-mode" in out
+ assert "--daemon-ttl" in out
+
+
+def test_diskann_server_help_has_daemon_and_warmup_flags():
+ out = _run_help("leann_backend_diskann.diskann_embedding_server")
+ assert "--enable-warmup" in out
+ assert "--daemon-mode" in out
+ assert "--daemon-ttl" in out
diff --git a/tests/test_embedding_server_manager.py b/tests/test_embedding_server_manager.py
index 71e91f3..8dd3d79 100644
--- a/tests/test_embedding_server_manager.py
+++ b/tests/test_embedding_server_manager.py
@@ -1,13 +1,16 @@
import json
+import os
+import threading
import time
+from typing import Any, cast
import pytest
from leann.embedding_server_manager import EmbeddingServerManager
class DummyProcess:
- def __init__(self):
- self.pid = 12345
+ def __init__(self, pid=12345):
+ self.pid = pid
self._terminated = False
def poll(self):
@@ -102,6 +105,7 @@ def test_server_restarts_when_metadata_changes(tmp_path, embedding_manager):
port=6000,
model_name="test-model",
passages_file=str(meta_path),
+ use_daemon=False,
)
assert ok
assert port == 6000
@@ -114,6 +118,7 @@ def test_server_restarts_when_metadata_changes(tmp_path, embedding_manager):
port=6000,
model_name="test-model",
passages_file=str(meta_path),
+ use_daemon=False,
)
assert ok
assert port_again == 6000
@@ -128,6 +133,7 @@ def test_server_restarts_when_metadata_changes(tmp_path, embedding_manager):
port=6000,
model_name="test-model",
passages_file=str(meta_path),
+ use_daemon=False,
)
assert ok
assert port_third == 6000
@@ -135,3 +141,373 @@ def test_server_restarts_when_metadata_changes(tmp_path, embedding_manager):
updated_signature = start_calls[1]["passages_signature"]
assert updated_signature != initial_signature
+
+
+def test_list_daemons_ignores_stale_records(tmp_path, monkeypatch):
+ registry_dir = tmp_path / "servers"
+ registry_dir.mkdir()
+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))
+
+ stale = registry_dir / "stale.json"
+ stale.write_text(
+ json.dumps(
+ {
+ "pid": 999999,
+ "port": 65531,
+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",
+ "config_signature": {"passages_file": "/tmp/a.meta.json"},
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ records = EmbeddingServerManager.list_daemons()
+ assert records == []
+ assert not stale.exists()
+
+
+def test_stop_daemons_filters_by_backend_and_passages(tmp_path, monkeypatch):
+ registry_dir = tmp_path / "servers"
+ registry_dir.mkdir()
+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))
+
+ meta_path = (tmp_path / "x.meta.json").resolve()
+ record = registry_dir / "daemon.json"
+ record.write_text(
+ json.dumps(
+ {
+ "pid": 12345,
+ "port": 6001,
+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",
+ "config_signature": {"passages_file": str(meta_path)},
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ monkeypatch.setattr(
+ EmbeddingServerManager,
+ "list_daemons",
+ classmethod(
+ lambda cls: [
+ {
+ "pid": 12345,
+ "port": 6001,
+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",
+ "config_signature": {"passages_file": str(meta_path)},
+ "record_path": str(record),
+ }
+ ]
+ ),
+ )
+
+ killed: list[tuple[int, int]] = []
+
+ def fake_kill(pid: int, sig: int):
+ killed.append((pid, sig))
+
+ monkeypatch.setattr(os, "kill", fake_kill)
+
+ stopped = EmbeddingServerManager.stop_daemons(
+ backend_module_name="leann_backend_hnsw.hnsw_embedding_server",
+ passages_file=str(meta_path),
+ )
+ assert stopped == 1
+ assert killed == [(12345, 15)]
+ assert not record.exists()
+
+
+def test_daemon_registry_reuse_across_manager_instances(tmp_path, monkeypatch):
+ """Second manager should adopt the daemon started by first manager."""
+ registry_dir = tmp_path / "servers"
+ registry_dir.mkdir()
+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))
+ monkeypatch.setattr(
+ "leann.embedding_server_manager._get_available_port",
+ lambda start_port: start_port,
+ )
+ monkeypatch.setattr("leann.embedding_server_manager._check_port", lambda port: True)
+ monkeypatch.setattr("leann.embedding_server_manager._pid_is_alive", lambda pid: pid == 22222)
+
+ starts = []
+
+ def fake_start_new_server(self, port, model_name, embedding_mode, **kwargs):
+ starts.append((port, model_name, embedding_mode))
+ self.server_process = DummyProcess(pid=22222)
+ self.server_port = port
+ self._server_config = kwargs.get("config_signature")
+ return True, port
+
+ monkeypatch.setattr(EmbeddingServerManager, "_start_new_server", fake_start_new_server)
+
+ manager1 = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")
+ ok1, port1 = manager1.start_server(
+ port=6011,
+ model_name="test-model",
+ use_daemon=True,
+ daemon_ttl_seconds=120,
+ )
+ assert ok1 and port1 == 6011
+ assert len(starts) == 1
+
+ manager2 = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")
+ ok2, port2 = manager2.start_server(
+ port=6011,
+ model_name="test-model",
+ use_daemon=True,
+ daemon_ttl_seconds=120,
+ )
+ assert ok2 and port2 == 6011
+ # No second process spawn: adopted from registry.
+ assert len(starts) == 1
+ assert manager2.server_process is None
+
+
+def test_stale_registry_falls_back_to_fresh_start(tmp_path, monkeypatch):
+ """If registry points to dead daemon, manager should start a new process."""
+ registry_dir = tmp_path / "servers"
+ registry_dir.mkdir()
+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))
+ monkeypatch.setattr(
+ "leann.embedding_server_manager._get_available_port",
+ lambda start_port: start_port,
+ )
+
+ starts = []
+
+ def fake_start_new_server(self, port, model_name, embedding_mode, **kwargs):
+ starts.append(port)
+ self.server_process = DummyProcess(pid=33333)
+ self.server_port = port
+ self._server_config = kwargs.get("config_signature")
+ return True, port
+
+ monkeypatch.setattr(EmbeddingServerManager, "_start_new_server", fake_start_new_server)
+
+ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")
+ signature = manager._build_config_signature(
+ model_name="test-model",
+ embedding_mode="sentence-transformers",
+ provider_options=None,
+ passages_file=None,
+ distance_metric=None,
+ )
+ stale_file = registry_dir / f"{manager._registry_key(signature)}.json"
+ stale_file.write_text(
+ json.dumps(
+ {
+ "pid": 999999,
+ "port": 6012,
+ "backend_module_name": "leann_backend_hnsw.hnsw_embedding_server",
+ "config_signature": signature,
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ monkeypatch.setattr("leann.embedding_server_manager._pid_is_alive", lambda pid: False)
+ monkeypatch.setattr("leann.embedding_server_manager._check_port", lambda port: False)
+
+ ok, port = manager.start_server(
+ port=6012,
+ model_name="test-model",
+ use_daemon=True,
+ )
+ assert ok and port == 6012
+ assert starts == [6012]
+ assert stale_file.exists()
+ refreshed = json.loads(stale_file.read_text(encoding="utf-8"))
+ assert refreshed["pid"] == 33333
+
+
+def test_build_server_command_includes_daemon_and_warmup_flags():
+ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")
+ command = manager._build_server_command(
+ port=6020,
+ model_name="m",
+ embedding_mode="sentence-transformers",
+ distance_metric="mips",
+ enable_warmup=True,
+ use_daemon=True,
+ daemon_ttl_seconds=321,
+ )
+ assert "--enable-warmup" in command
+ assert "--daemon-mode" in command
+ assert "--daemon-ttl" in command
+ ttl_idx = command.index("--daemon-ttl")
+ assert command[ttl_idx + 1] == "321"
+
+ command_no_daemon = manager._build_server_command(
+ port=6020,
+ model_name="m",
+ embedding_mode="sentence-transformers",
+ enable_warmup=False,
+ use_daemon=False,
+ )
+ assert "--daemon-mode" not in command_no_daemon
+ assert "--enable-warmup" not in command_no_daemon
+
+
+def test_corrupted_registry_file_is_recovered_on_start(tmp_path, monkeypatch):
+ """Invalid registry json should not block startup; file is replaced."""
+ registry_dir = tmp_path / "servers"
+ registry_dir.mkdir()
+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))
+ monkeypatch.setattr(
+ "leann.embedding_server_manager._get_available_port",
+ lambda start_port: start_port,
+ )
+
+ starts = []
+
+ def fake_start_new_server(self, port, model_name, embedding_mode, **kwargs):
+ starts.append(port)
+ self.server_process = DummyProcess(pid=44444)
+ self.server_port = port
+ self._server_config = kwargs.get("config_signature")
+ return True, port
+
+ monkeypatch.setattr(EmbeddingServerManager, "_start_new_server", fake_start_new_server)
+
+ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")
+ signature = manager._build_config_signature(
+ model_name="test-model",
+ embedding_mode="sentence-transformers",
+ provider_options=None,
+ passages_file=None,
+ distance_metric=None,
+ )
+ record_path = registry_dir / f"{manager._registry_key(signature)}.json"
+ record_path.write_text("{invalid-json", encoding="utf-8")
+
+ monkeypatch.setattr("leann.embedding_server_manager._pid_is_alive", lambda pid: False)
+ monkeypatch.setattr("leann.embedding_server_manager._check_port", lambda port: False)
+
+ ok, port = manager.start_server(port=6030, model_name="test-model", use_daemon=True)
+ assert ok and port == 6030
+ assert starts == [6030]
+ data = json.loads(record_path.read_text(encoding="utf-8"))
+ assert data["pid"] == 44444
+
+
+def test_stop_server_detaches_when_daemon_mode(monkeypatch):
+ """Daemon mode should detach manager without terminating shared process."""
+ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")
+ manager.server_process = cast(Any, DummyProcess(pid=55555))
+ manager.server_port = 6031
+ manager._server_config = {"model_name": "m"}
+ manager._daemon_mode = True
+
+ # If terminate is called this test should fail.
+ called = {"terminate": 0}
+
+ def fail_terminate():
+ called["terminate"] += 1
+ raise AssertionError("terminate should not be called in daemon detach path")
+
+ manager.server_process.terminate = fail_terminate # type: ignore[method-assign]
+
+ manager.stop_server()
+ assert called["terminate"] == 0
+ assert manager.server_process is None
+ assert manager.server_port is None
+ assert manager._server_config is None
+
+
+def test_concurrent_daemon_start_only_spawns_once(tmp_path, monkeypatch):
+ """Concurrent calls should be serialized by registry lock for same signature."""
+ registry_dir = tmp_path / "servers"
+ registry_dir.mkdir()
+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))
+ monkeypatch.setattr(
+ "leann.embedding_server_manager._get_available_port",
+ lambda start_port: start_port,
+ )
+ monkeypatch.setattr("leann.embedding_server_manager._check_port", lambda port: True)
+ monkeypatch.setattr("leann.embedding_server_manager._pid_is_alive", lambda pid: pid in (77777,))
+
+ starts = []
+
+ def fake_start_new_server(self, port, model_name, embedding_mode, **kwargs):
+ # Force overlap window between two starters.
+ time.sleep(0.05)
+ starts.append((self, port))
+ self.server_process = DummyProcess(pid=77777)
+ self.server_port = port
+ self._server_config = kwargs.get("config_signature")
+ return True, port
+
+ monkeypatch.setattr(EmbeddingServerManager, "_start_new_server", fake_start_new_server)
+
+ results = []
+
+ def runner():
+ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")
+ ok, port = manager.start_server(port=6040, model_name="test-model", use_daemon=True)
+ results.append((ok, port))
+
+ t1 = threading.Thread(target=runner)
+ t2 = threading.Thread(target=runner)
+ t1.start()
+ t2.start()
+ t1.join(timeout=5)
+ t2.join(timeout=5)
+
+ assert len(results) == 2
+ assert all(ok and port == 6040 for ok, port in results)
+ # Exactly one actual process start, one adopts registry record.
+ assert len(starts) == 1
+
+
+def test_registry_record_write_is_atomic(tmp_path, monkeypatch):
+ """Registry writes should go through temp file + os.replace."""
+ registry_dir = tmp_path / "servers"
+ registry_dir.mkdir()
+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))
+
+ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")
+ manager.server_process = cast(Any, DummyProcess(pid=88888))
+
+ calls = []
+ real_replace = os.replace
+
+ def tracked_replace(src, dst):
+ calls.append((str(src), str(dst)))
+ return real_replace(src, dst)
+
+ monkeypatch.setattr(os, "replace", tracked_replace)
+
+ path = manager._write_registry_record(
+ port=6060,
+ config_signature={"model_name": "m"},
+ daemon_ttl_seconds=123,
+ )
+ assert path.exists()
+ assert calls, "os.replace should be used for atomic write"
+ src, dst = calls[0]
+ assert src.endswith(".json.tmp")
+ assert dst.endswith(".json")
+
+
+def test_stale_lock_info_removed_when_pid_dead(tmp_path, monkeypatch):
+ registry_dir = tmp_path / "servers"
+ registry_dir.mkdir()
+ monkeypatch.setattr(EmbeddingServerManager, "_registry_dir", staticmethod(lambda: registry_dir))
+ monkeypatch.setattr("leann.embedding_server_manager._pid_is_alive", lambda pid: False)
+
+ manager = EmbeddingServerManager("leann_backend_hnsw.hnsw_embedding_server")
+ signature = manager._build_config_signature(
+ model_name="x",
+ embedding_mode="sentence-transformers",
+ provider_options=None,
+ passages_file=None,
+ distance_metric=None,
+ )
+ key = manager._registry_key(signature)
+ lock_info = registry_dir / f"{key}.lockinfo.json"
+ lock_info.write_text(json.dumps({"pid": 999999, "ts": time.time()}), encoding="utf-8")
+
+ with manager._registry_lock(signature):
+ pass
+
+ assert not lock_info.exists()
diff --git a/tests/test_embedding_server_manager_e2e.py b/tests/test_embedding_server_manager_e2e.py
new file mode 100644
index 0000000..f2d45f5
--- /dev/null
+++ b/tests/test_embedding_server_manager_e2e.py
@@ -0,0 +1,82 @@
+import os
+import time
+from pathlib import Path
+
+from leann.embedding_server_manager import EmbeddingServerManager
+
+
+def _configure_fake_module_env(monkeypatch):
+ root = Path(__file__).resolve().parents[1]
+ support_path = str(root / "tests" / "support")
+ existing = os.environ.get("PYTHONPATH", "")
+ joined = support_path if not existing else f"{support_path}{os.pathsep}{existing}"
+ monkeypatch.setenv("PYTHONPATH", joined)
+
+
+def _wait_until(predicate, timeout=5.0, interval=0.05):
+ deadline = time.time() + timeout
+ while time.time() < deadline:
+ if predicate():
+ return True
+ time.sleep(interval)
+ return False
+
+
+def test_daemon_reuse_with_real_subprocess(tmp_path, monkeypatch):
+ _configure_fake_module_env(monkeypatch)
+ monkeypatch.setattr(
+ EmbeddingServerManager, "_registry_dir", staticmethod(lambda: tmp_path / "servers")
+ )
+
+ manager1 = EmbeddingServerManager("fake_embedding_server_module")
+ ok1, port1 = manager1.start_server(
+ port=6151,
+ model_name="fake-model",
+ use_daemon=True,
+ daemon_ttl_seconds=60,
+ enable_warmup=True,
+ )
+ assert ok1 and port1 == 6151
+ assert manager1.server_process is not None
+ pid1 = manager1.server_process.pid
+
+ manager2 = EmbeddingServerManager("fake_embedding_server_module")
+ ok2, port2 = manager2.start_server(
+ port=6151,
+ model_name="fake-model",
+ use_daemon=True,
+ daemon_ttl_seconds=60,
+ )
+ assert ok2 and port2 == 6151
+ # Adoption path: no newly spawned process object attached.
+ assert manager2.server_process is None
+
+ records = EmbeddingServerManager.list_daemons()
+ assert len(records) == 1
+ assert int(records[0]["pid"]) == pid1
+
+ stopped = EmbeddingServerManager.stop_daemons(
+ backend_module_name="fake_embedding_server_module"
+ )
+ assert stopped == 1
+
+
+def test_daemon_ttl_expiry_with_real_subprocess(tmp_path, monkeypatch):
+ _configure_fake_module_env(monkeypatch)
+ monkeypatch.setattr(
+ EmbeddingServerManager, "_registry_dir", staticmethod(lambda: tmp_path / "servers")
+ )
+
+ manager = EmbeddingServerManager("fake_embedding_server_module")
+ ok, port = manager.start_server(
+ port=6152,
+ model_name="fake-model",
+ use_daemon=True,
+ daemon_ttl_seconds=1,
+ enable_warmup=False,
+ )
+ assert ok and port == 6152
+
+ # Fake daemon should self-exit after idle TTL.
+ expired = _wait_until(lambda: len(EmbeddingServerManager.list_daemons()) == 0, timeout=4.0)
+ assert expired
diff --git a/tests/test_prompt_template_persistence.py b/tests/test_prompt_template_persistence.py
index 56391ff..fe260ac 100644
--- a/tests/test_prompt_template_persistence.py
+++ b/tests/test_prompt_template_persistence.py
@@ -607,6 +607,9 @@ class TestQueryTemplateApplicationInComputeEmbedding:
searcher.embedding_model = searcher.meta["embedding_model"]
searcher.embedding_mode = searcher.meta.get("embedding_mode", "sentence-transformers")
searcher.embedding_options = searcher.meta.get("embedding_options", {})
+ searcher.enable_warmup = False
+ searcher.use_daemon = False
+ searcher.daemon_ttl_seconds = 0
# Mock compute_embeddings to capture the query text
captured_queries = []
@@ -662,11 +665,14 @@ class TestQueryTemplateApplicationInComputeEmbedding:
searcher.embedding_model = searcher.meta["embedding_model"]
searcher.embedding_mode = searcher.meta.get("embedding_mode", "sentence-transformers")
searcher.embedding_options = searcher.meta.get("embedding_options", {})
+ searcher.enable_warmup = False
+ searcher.use_daemon = False
+ searcher.daemon_ttl_seconds = 0
# Mock the server methods to capture the query text
captured_queries = []
- def mock_ensure_server_running(passages_file, port):
+ def mock_ensure_server_running(passages_file, port, **kwargs):
return port
def mock_compute_embedding_via_server(chunks, port):
@@ -718,6 +724,9 @@ class TestQueryTemplateApplicationInComputeEmbedding:
searcher.embedding_model = searcher.meta["embedding_model"]
searcher.embedding_mode = searcher.meta.get("embedding_mode", "sentence-transformers")
searcher.embedding_options = searcher.meta.get("embedding_options", {})
+ searcher.enable_warmup = False
+ searcher.use_daemon = False
+ searcher.daemon_ttl_seconds = 0
captured_queries = []
@@ -768,6 +777,9 @@ class TestQueryTemplateApplicationInComputeEmbedding:
searcher.embedding_model = searcher.meta["embedding_model"]
searcher.embedding_mode = searcher.meta.get("embedding_mode", "sentence-transformers")
searcher.embedding_options = searcher.meta.get("embedding_options", {})
+ searcher.enable_warmup = False
+ searcher.use_daemon = False
+ searcher.daemon_ttl_seconds = 0
query_template = "task: search result | query: "
original_query = "vector database"
@@ -791,7 +803,7 @@ class TestQueryTemplateApplicationInComputeEmbedding:
# Capture queries from server path
server_queries = []
- def mock_ensure_server_running(passages_file, port):
+ def mock_ensure_server_running(passages_file, port, **kwargs):
return port
def mock_compute_embedding_via_server(chunks, port):
@@ -843,6 +855,9 @@ class TestQueryTemplateApplicationInComputeEmbedding:
searcher.embedding_model = searcher.meta["embedding_model"]
searcher.embedding_mode = searcher.meta.get("embedding_mode", "sentence-transformers")
searcher.embedding_options = searcher.meta.get("embedding_options", {})
+ searcher.enable_warmup = False
+ searcher.use_daemon = False
+ searcher.daemon_ttl_seconds = 0
captured_queries = []