Skip to content

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

fix(cli): probe embedding provider in doctor (#2333)

Mingjian Que2d7d93a0a879
diff --git a/openviking_cli/doctor.py b/openviking_cli/doctor.py
index 849fffb1c..457ce67ac 100644
--- a/openviking_cli/doctor.py
+++ b/openviking_cli/doctor.py
@@ -9,6 +9,7 @@ native vector engine, AGFS, embedding provider, VLM provider, and disk space.
from __future__ import annotations
+import asyncio
import importlib
import json
import os
@@ -16,7 +17,7 @@ import platform
import shutil
import sys
from pathlib import Path
-from typing import Optional
+from typing import Any, Optional
from openviking_cli.utils.config.config_loader import resolve_config_path
from openviking_cli.utils.config.consts import OPENVIKING_CONFIG_ENV
@@ -143,6 +144,90 @@ def check_agfs() -> tuple[bool, str, Optional[str]]:
)
+def _embedding_probe_label(provider: str, model: str, dense: dict[str, Any]) -> str:
+ api_base = dense.get("api_base")
+ dimension = dense.get("dimension")
+ parts = [f"{provider}/{model}"]
+ if api_base:
+ parts.append(f"api_base={api_base}")
+ if dimension:
+ parts.append(f"dimension={dimension}")
+ return " ".join(parts)
+
+
+def _probe_embedding_provider(
+ embedding: dict[str, Any],
+ dense: dict[str, Any],
+) -> tuple[bool, str, Optional[str]]:
+ """Create the configured embedder, make one request, and validate vector shape."""
+ from openviking.models.embedder.base import embed_compat
+ from openviking_cli.utils.config.embedding_config import EmbeddingConfig, EmbeddingModelConfig
+
+ provider = dense.get("provider", "local")
+ model = dense.get("model", "bge-small-zh-v1.5-f16")
+ label = _embedding_probe_label(provider, model, dense)
+
+ try:
+ model_config = EmbeddingModelConfig(**dense)
+ config_kwargs = {
+ key: embedding[key]
+ for key in ("max_concurrent", "max_retries", "text_source", "max_input_tokens")
+ if key in embedding
+ }
+ embedding_config = EmbeddingConfig(dense=model_config, **config_kwargs)
+ embedder = embedding_config.get_embedder()
+ expected_dimension = (
+ model_config.dimension
+ if model_config.dimension is not None
+ else embedder.get_dimension()
+ )
+ except Exception as exc:
+ return (
+ False,
+ f"{label} (invalid embedding config: {exc})",
+ "Fix embedding.dense provider/model/api_base/dimension in ov.conf",
+ )
+
+ async def _run_probe():
+ return await asyncio.wait_for(
+ embed_compat(embedder, "OpenViking doctor embedding probe", is_query=True),
+ timeout=10.0,
+ )
+
+ try:
+ result = asyncio.run(_run_probe())
+ except TimeoutError:
+ return (
+ False,
+ f"{label} (probe timed out)",
+ "Check embedding.dense.api_base and make sure the embedding provider is reachable",
+ )
+ except Exception as exc:
+ return (
+ False,
+ f"{label} (probe failed: {exc})",
+ "Check the embedding provider service, model name, API key, and api_base",
+ )
+
+ vector = getattr(result, "dense_vector", None)
+ if not vector:
+ return (
+ False,
+ f"{label} (probe returned no dense vector)",
+ "Use a dense embedding model or configure embedding.dense correctly",
+ )
+
+ actual_dimension = len(vector)
+ if actual_dimension != expected_dimension:
+ return (
+ False,
+ f"{label} (dimension mismatch: expected {expected_dimension}, got {actual_dimension})",
+ "Set embedding.dense.dimension to match the provider output, or use a matching model/index",
+ )
+
+ return True, f"{label} probe ok (dimension={actual_dimension})", None
+
+
def check_embedding() -> tuple[bool, str, Optional[str]]:
"""Load embedding config and verify provider connectivity."""
config_path = _find_config()
@@ -202,19 +287,16 @@ def check_embedding() -> tuple[bool, str, Optional[str]]:
None,
)
- # Ollama doesn't need an API key
- if provider == "ollama":
- return True, f"{provider}/{model}", None
-
api_key = dense.get("api_key", "")
- if not api_key or api_key.startswith("{"):
+ api_base = dense.get("api_base", "")
+ if provider != "ollama" and not api_base and (not api_key or api_key.startswith("{")):
return (
False,
f"{provider}/{model} (no API key)",
"Set embedding.dense.api_key in ov.conf",
)
- return True, f"{provider}/{model}", None
+ return _probe_embedding_provider(embedding, dense)
def check_vlm() -> tuple[bool, str, Optional[str]]:
diff --git a/tests/cli/test_doctor.py b/tests/cli/test_doctor.py
index 43e30f642..fee08cdd0 100644
--- a/tests/cli/test_doctor.py
+++ b/tests/cli/test_doctor.py
@@ -4,6 +4,7 @@
from __future__ import annotations
+import importlib
import json
import os
import sys
@@ -11,6 +12,7 @@ from pathlib import Path
from unittest.mock import patch
from openviking_cli.doctor import (
+ _probe_embedding_provider,
check_agfs,
check_config,
check_disk,
@@ -151,10 +153,17 @@ class TestCheckEmbedding:
config = tmp_path / "ov.conf"
config.write_text(json.dumps({}))
+ real_import_module = importlib.import_module
+
+ def import_module_side_effect(name: str, *args, **kwargs):
+ if name == "llama_cpp":
+ raise ImportError("No module named 'llama_cpp'")
+ return real_import_module(name, *args, **kwargs)
+
with patch("openviking_cli.doctor._find_config", return_value=config):
with patch(
"openviking_cli.doctor.importlib.import_module",
- side_effect=ImportError("No module named 'llama_cpp'"),
+ side_effect=import_module_side_effect,
):
ok, detail, fix = check_embedding()
@@ -243,9 +252,41 @@ class TestCheckEmbedding:
)
)
with patch("openviking_cli.doctor._find_config", return_value=config):
- ok, detail, fix = check_embedding()
+ with patch(
+ "openviking_cli.doctor._probe_embedding_provider",
+ return_value=(True, "openai/text-embedding-3-small probe ok", None),
+ ):
+ ok, detail, fix = check_embedding()
assert ok
assert "openai" in detail
+ assert fix is None
+
+ def test_pass_ollama_after_provider_probe(self, tmp_path: Path):
+ config = tmp_path / "ov.conf"
+ config.write_text(
+ json.dumps(
+ {
+ "embedding": {
+ "dense": {
+ "provider": "ollama",
+ "model": "bge-m3",
+ "api_base": "http://localhost:11434/v1",
+ "dimension": 1024,
+ }
+ }
+ }
+ )
+ )
+ with patch("openviking_cli.doctor._find_config", return_value=config):
+ with patch(
+ "openviking_cli.doctor._probe_embedding_provider",
+ return_value=(True, "ollama/bge-m3 probe ok (dimension=1024)", None),
+ ) as probe:
+ ok, detail, fix = check_embedding()
+ probe.assert_called_once()
+ assert ok
+ assert "ollama/bge-m3" in detail
+ assert fix is None
def test_pass_with_api_key_from_environment_variable(self, tmp_path: Path):
config = tmp_path / "ov.conf"
@@ -264,7 +305,11 @@ class TestCheckEmbedding:
)
with patch("openviking_cli.doctor._find_config", return_value=config):
with patch.dict(os.environ, {"OPENAI_API_KEY": "sk-env-123"}, clear=False):
- ok, detail, fix = check_embedding()
+ with patch(
+ "openviking_cli.doctor._probe_embedding_provider",
+ return_value=(True, "openai/text-embedding-3-small probe ok", None),
+ ):
+ ok, detail, fix = check_embedding()
assert ok
assert "openai" in detail
@@ -298,6 +343,149 @@ class TestCheckEmbedding:
assert not ok
assert "unreadable" in detail
+ def test_embedding_probe_fails_on_provider_error(self):
+ with patch(
+ "openviking_cli.utils.config.embedding_config.EmbeddingConfig.get_embedder",
+ return_value=object(),
+ ):
+ with patch(
+ "openviking.models.embedder.base.embed_compat",
+ side_effect=RuntimeError("model not found"),
+ ):
+ ok, detail, fix = _probe_embedding_provider(
+ {"max_retries": 0},
+ {
+ "provider": "ollama",
+ "model": "missing-model",
+ "api_base": "http://localhost:11434/v1",
+ "dimension": 1024,
+ },
+ )
+
+ assert not ok
+ assert "probe failed" in detail
+ assert "model not found" in detail
+ assert "model name" in fix
+
+ def test_embedding_probe_fails_on_empty_dense_vector(self):
+ class FakeEmbedder:
+ pass
+
+ async def fake_embed_compat(*args, **kwargs):
+ return type("Result", (), {"dense_vector": []})()
+
+ with patch(
+ "openviking_cli.utils.config.embedding_config.EmbeddingConfig.get_embedder",
+ return_value=FakeEmbedder(),
+ ):
+ with patch(
+ "openviking.models.embedder.base.embed_compat",
+ side_effect=fake_embed_compat,
+ ):
+ ok, detail, fix = _probe_embedding_provider(
+ {},
+ {
+ "provider": "openai",
+ "model": "custom-embed",
+ "api_base": "http://localhost:11434/v1",
+ "dimension": 3,
+ },
+ )
+
+ assert not ok
+ assert "no dense vector" in detail
+ assert "embedding.dense" in fix
+
+ def test_embedding_probe_fails_on_dimension_mismatch(self):
+ class FakeEmbedder:
+ def get_dimension(self):
+ return 2
+
+ async def fake_embed_compat(*args, **kwargs):
+ return type("Result", (), {"dense_vector": [0.1, 0.2]})()
+
+ with patch(
+ "openviking_cli.utils.config.embedding_config.EmbeddingConfig.get_embedder",
+ return_value=FakeEmbedder(),
+ ):
+ with patch(
+ "openviking.models.embedder.base.embed_compat",
+ side_effect=fake_embed_compat,
+ ):
+ ok, detail, fix = _probe_embedding_provider(
+ {},
+ {
+ "provider": "openai",
+ "model": "custom-embed",
+ "api_base": "http://localhost:11434/v1",
+ "dimension": 3,
+ },
+ )
+
+ assert not ok
+ assert "dimension mismatch" in detail
+ assert "expected 3, got 2" in detail
+ assert "embedding.dense.dimension" in fix
+
+ def test_embedding_probe_uses_embedder_dimension_when_config_omits_dimension(self):
+ class FakeEmbedder:
+ def get_dimension(self):
+ return 2
+
+ async def fake_embed_compat(*args, **kwargs):
+ return type("Result", (), {"dense_vector": [0.1, 0.2]})()
+
+ with patch(
+ "openviking_cli.utils.config.embedding_config.EmbeddingConfig.get_embedder",
+ return_value=FakeEmbedder(),
+ ):
+ with patch(
+ "openviking.models.embedder.base.embed_compat",
+ side_effect=fake_embed_compat,
+ ):
+ ok, detail, fix = _probe_embedding_provider(
+ {},
+ {
+ "provider": "openai",
+ "model": "custom-embed",
+ "api_base": "http://localhost:11434/v1",
+ },
+ )
+
+ assert ok
+ assert "dimension=2" in detail
+ assert fix is None
+
+ def test_embedding_probe_fails_when_inferred_dimension_mismatches_probe(self):
+ class FakeEmbedder:
+ def get_dimension(self):
+ return 3
+
+ async def fake_embed_compat(*args, **kwargs):
+ return type("Result", (), {"dense_vector": [0.1, 0.2]})()
+
+ with patch(
+ "openviking_cli.utils.config.embedding_config.EmbeddingConfig.get_embedder",
+ return_value=FakeEmbedder(),
+ ):
+ with patch(
+ "openviking.models.embedder.base.embed_compat",
+ side_effect=fake_embed_compat,
+ ):
+ ok, detail, fix = _probe_embedding_provider(
+ {},
+ {
+ "provider": "openai",
+ "model": "custom-embed",
+ "api_base": "http://localhost:11434/v1",
+ },
+ )
+
+ assert not ok
+ assert "dimension mismatch" in detail
+ assert "expected 3, got 2" in detail
+ assert "embedding.dense.dimension" in fix
+
class TestCheckVlm:
def test_pass_with_config(self, tmp_path: Path):
@@ -506,7 +694,11 @@ class TestRunDoctor:
)
)
with patch("openviking_cli.doctor._find_config", return_value=config):
- code = run_doctor()
+ with patch(
+ "openviking_cli.doctor._probe_embedding_provider",
+ return_value=(True, "openai/m probe ok", None),
+ ):
+ code = run_doctor()
captured = capsys.readouterr()
assert "OpenViking Doctor" in captured.out
# May not be 0 if native engine is missing, but the function should complete