DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
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.pyindex 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 payloadexcept 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.pyindex 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.pyindex 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.MonkeyPatchconfig = 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)