Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(rag): surface the hybrid to vector-only retrieval degradation (#1792) (#1801)

ZQR11010b5b254b504c
diff --git a/deeptutor/api/routers/knowledge.py b/deeptutor/api/routers/knowledge.py
index ea812e3bb..39f5d1daa 100644
--- a/deeptutor/api/routers/knowledge.py
+++ b/deeptutor/api/routers/knowledge.py
@@ -1585,11 +1585,25 @@ class LlamaIndexConfigUpdate(BaseModel):
@router.get("/knowledge-bases/rag-pipelines/llamaindex/config")
async def get_llamaindex_pipeline_config():
- """Read the LlamaIndex engine's retrieval + chunking knobs."""
+ """Read the LlamaIndex engine's retrieval + chunking knobs.
+
+ ``retrieval_profile`` is what is *configured*; ``effective_retrieval_profile``
+ is what would actually run — a hybrid configuration degrades to vector-only
+ when the BM25 package is missing (e.g. Python 3.14 installs, #1792).
+ """
try:
from deeptutor.services.config import get_runtime_settings_service
- return get_runtime_settings_service().load_llamaindex()
+ settings = get_runtime_settings_service().load_llamaindex()
+ from deeptutor.services.rag.pipelines.llamaindex.retrievers import (
+ effective_retrieval_profile,
+ )
+
+ payload = dict(settings)
+ payload["effective_retrieval_profile"] = effective_retrieval_profile(
+ settings.get("retrieval_profile")
+ )
+ return payload
except Exception as e:
logger.error(f"Error reading LlamaIndex config: {e}")
raise HTTPException(status_code=500, detail=str(e))
diff --git a/deeptutor/services/rag/pipelines/llamaindex/retrievers.py b/deeptutor/services/rag/pipelines/llamaindex/retrievers.py
index e3ccabf4b..623a204b8 100644
--- a/deeptutor/services/rag/pipelines/llamaindex/retrievers.py
+++ b/deeptutor/services/rag/pipelines/llamaindex/retrievers.py
@@ -15,6 +15,7 @@ from .config import (
HYBRID_PROFILE,
VECTOR_PROFILE,
RetrievalConfig,
+ normalize_retrieval_profile,
retrieval_config_from_settings,
)
from .rerank import rerank_nodes
@@ -52,6 +53,29 @@ def _corpus_size(index: Any) -> int | None:
return None
+def bm25_available() -> bool:
+ """Whether LlamaIndex's BM25 retriever package is importable.
+
+ Exposed so status surfaces can distinguish the *configured* retrieval
+ profile from the *effective* one: on Python 3.14 the BM25 dependency is
+ marker-excluded, and a deployment configured for hybrid then runs
+ vector-only without any signal otherwise (#1792).
+ """
+ return _import_bm25_retriever() is not None
+
+
+def effective_retrieval_profile(profile: str | None) -> str:
+ """The retrieval profile that would actually run, given BM25 availability.
+
+ A hybrid configuration degrades to vector-only when the BM25 package is
+ missing; vector-only configurations are unaffected.
+ """
+ normalized = normalize_retrieval_profile(profile)
+ if normalized == HYBRID_PROFILE and not bm25_available():
+ return VECTOR_PROFILE
+ return normalized
+
+
def build_bm25_retriever(index: Any, storage_dir: Path, *, top_k: int) -> Any | None:
"""Build or load LlamaIndex's official BM25 retriever if available."""
top_k = max(1, int(top_k))
@@ -64,8 +88,14 @@ def build_bm25_retriever(index: Any, storage_dir: Path, *, top_k: int) -> Any |
top_k = min(top_k, corpus_size)
bm25_cls = _import_bm25_retriever()
if bm25_cls is None:
- logger.info(
- "LlamaIndex BM25 retriever package is not installed; falling back to vector retrieval."
+ # #1792: an INFO line was invisible in normal runs, so deployments on
+ # Python 3.14 (where the BM25 dependency is marker-excluded) ran
+ # vector-only without ever knowing. The configured profile is not the
+ # effective one — say so at warning level.
+ logger.warning(
+ "LlamaIndex BM25 retriever package is not installed; configured "
+ "retrieval profile will run vector-only. Install "
+ "'llama-index-retrievers-bm25' to restore hybrid retrieval."
)
return None
@@ -133,6 +163,14 @@ def build_retriever(
bm25_top_k = retrieval_config.candidate_top_k(top_k, retrieval_config.bm25_top_k_multiplier)
bm25_retriever = build_bm25_retriever(index, storage_dir, top_k=bm25_top_k)
if bm25_retriever is None:
+ # Only reachable for non-vector profiles: the configured stack
+ # degrades to vector-only here, and the operator must know (#1792).
+ logger.warning(
+ "Retrieval profile %r requires BM25 but it is unavailable; "
+ "running vector-only. Install 'llama-index-retrievers-bm25' "
+ "or switch the profile to 'vector'.",
+ retrieval_config.profile,
+ )
return index.as_retriever(similarity_top_k=top_k)
if retrieval_config.profile == HYBRID_PROFILE:
@@ -182,8 +220,10 @@ def retrieve_nodes(
__all__ = [
"BM25_PERSIST_DIRNAME",
+ "bm25_available",
"build_bm25_retriever",
"build_retriever",
+ "effective_retrieval_profile",
"persist_bm25_retriever",
"retrieve_nodes",
]
diff --git a/tests/services/rag/test_llamaindex_storage_layout.py b/tests/services/rag/test_llamaindex_storage_layout.py
index 4e94ce337..59870a866 100644
--- a/tests/services/rag/test_llamaindex_storage_layout.py
+++ b/tests/services/rag/test_llamaindex_storage_layout.py
@@ -252,3 +252,57 @@ def test_retrieval_config_reads_profile_from_env(monkeypatch: pytest.MonkeyPatch
config = config_module.retrieval_config_from_env()
assert config.profile == config_module.VECTOR_PROFILE
+
+
+# ── #1792: the configured retrieval profile must not silently differ from
+# the effective one when the BM25 package is missing (Python 3.14 installs).
+
+
+def test_bm25_available_reflects_the_import_check(monkeypatch: pytest.MonkeyPatch) -> None:
+ from deeptutor.services.rag.pipelines.llamaindex import retrievers as retriever_module
+
+ monkeypatch.setattr(retriever_module, "_import_bm25_retriever", lambda: object)
+ assert retriever_module.bm25_available() is True
+
+ monkeypatch.setattr(retriever_module, "_import_bm25_retriever", lambda: None)
+ assert retriever_module.bm25_available() is False
+
+
+def test_effective_profile_degrades_hybrid_to_vector_without_bm25(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from deeptutor.services.rag.pipelines.llamaindex import retrievers as retriever_module
+
+ monkeypatch.setattr(retriever_module, "_import_bm25_retriever", lambda: None)
+ assert retriever_module.effective_retrieval_profile("hybrid") == "vector"
+ # Non-hybrid profiles are unaffected by BM25 availability.
+ assert retriever_module.effective_retrieval_profile("vector") == "vector"
+
+ monkeypatch.setattr(retriever_module, "_import_bm25_retriever", lambda: object)
+ assert retriever_module.effective_retrieval_profile("hybrid") == "hybrid"
+
+
+def test_hybrid_fallback_to_vector_warns_instead_of_staying_silent(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+ import logging
+
+ from deeptutor.services.rag.pipelines.llamaindex import retrievers as retriever_module
+ from deeptutor.services.rag.pipelines.llamaindex.config import RetrievalConfig
+
+ class _FakeIndex:
+ def as_retriever(self, similarity_top_k: int):
+ return {"top_k": similarity_top_k}
+
+ monkeypatch.setattr(retriever_module, "_import_bm25_retriever", lambda: None)
+
+ with caplog.at_level(logging.WARNING, logger=retriever_module.__name__):
+ retriever_module.build_retriever(
+ _FakeIndex(),
+ tmp_path,
+ top_k=4,
+ config=RetrievalConfig(profile="hybrid"),
+ )
+
+ warnings = [r for r in caplog.records if r.levelno == logging.WARNING]
+ assert any("vector-only" in r.getMessage() for r in warnings)