DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(rag): classify invalid persisted index errors and include re-index steps (#1702)
evan188199-tech18619e6fc64a
diff --git a/deeptutor/services/rag/pipelines/llamaindex/errors.py b/deeptutor/services/rag/pipelines/llamaindex/errors.pyindex dd1d8e157..3c0fc9d99 100644--- a/deeptutor/services/rag/pipelines/llamaindex/errors.py+++ b/deeptutor/services/rag/pipelines/llamaindex/errors.py@@ -5,28 +5,19 @@ from __future__ import annotationsfrom typing import Any, Dict+def _invalid_index_reason(message: str) -> str:+ """Extract the persisted-store failure reason recorded by the loader."""+ _, _, detail = message.partition("Details: ")+ if not detail:+ return ""+ return detail.split(". ", 1)[0].rstrip(".")++def search_error_result(query: str, exc: Exception) -> Dict[str, Any]:"""Convert retrieval failures into actionable tool output."""message = str(exc)lower = message.lower()- if "embedding provider returned invalid" in lower:- return {- "query": query,- "answer": (- "RAG search failed because the embedding provider returned an "- f"invalid query vector: {message}"- ),- "content": "",- "provider": "llamaindex",- "error": message,- "error_type": "invalid_embedding_provider_response",- "log_message": (- "Embedding provider returned an invalid query vector; check "- "the embedding provider/model configuration."- ),- }-null_vector_similarity_error = ("unsupported operand type(s) for *" in lower and "nonetype" in lower and "float" in lower)@@ -34,13 +25,22 @@ def search_error_result(query: str, exc: Exception) -> Dict[str, Any]:"shapes" in lower and "not aligned" in lower)invalid_persisted_index = "rag index contains invalid embedding vectors" in lower- if null_vector_similarity_error or shape_vector_error or invalid_persisted_index:+ if invalid_persisted_index or null_vector_similarity_error or shape_vector_error:+ # Classify the persisted-index diagnosis before the provider-response+ # branch so its "Details:" tail about stored vectors is never treated+ # as a live provider failure (issue #440).+ reason = _invalid_index_reason(message)+ reason_clause = f" ({reason})" if reason else ""return {"query": query,"answer": ("RAG search failed because this knowledge base index contains "- "invalid embedding vectors. Re-index the knowledge base with "- "the current embedding provider/model before querying it again."+ f"invalid embedding vectors{reason_clause}. Re-index the "+ "knowledge base with the current embedding provider/model "+ "before querying it again: open the knowledge base page and "+ "run its 'Re-index' action (Index versions → Re-index). "+ "Re-uploading documents reuses the damaged index and cannot "+ "repair it."),"content": "","provider": "llamaindex",@@ -50,6 +50,23 @@ def search_error_result(query: str, exc: Exception) -> Dict[str, Any]:"needs_reindex": True,}+ if "embedding provider returned invalid" in lower:+ return {+ "query": query,+ "answer": (+ "RAG search failed because the embedding provider returned an "+ f"invalid query vector: {message}"+ ),+ "content": "",+ "provider": "llamaindex",+ "error": message,+ "error_type": "invalid_embedding_provider_response",+ "log_message": (+ "Embedding provider returned an invalid query vector; check "+ "the embedding provider/model configuration."+ ),+ }+return {"query": query,"answer": f"Search failed: {message}",diff --git a/deeptutor/services/rag/pipelines/llamaindex/storage.py b/deeptutor/services/rag/pipelines/llamaindex/storage.pyindex fe9c29ed2..4dfb406ea 100644--- a/deeptutor/services/rag/pipelines/llamaindex/storage.py+++ b/deeptutor/services/rag/pipelines/llamaindex/storage.py@@ -111,16 +111,30 @@ def insert_documents(existing_storage: Path, storage_dir: Path, documents: list[return count+def _persisted_vector_fault(exc: ValueError) -> str:+ """Return the concrete fault from a shared-validator error message."""+ _, _, tail = str(exc).partition("): ")+ fault = tail.split(". ", 1)[0].rstrip(".")+ return fault or "unusable embedding data"++def _validate_embedding_dict(embedding_dict: Any, *, label: str) -> None:if not isinstance(embedding_dict, dict) or not embedding_dict:return- validate_embedding_batch(- list(embedding_dict.values()),- expected_count=len(embedding_dict),- binding="llamaindex",- model=f"persisted-index:{label}",- )+ try:+ validate_embedding_batch(+ list(embedding_dict.values()),+ expected_count=len(embedding_dict),+ binding="llamaindex",+ model=f"persisted-index:{label}",+ )+ except ValueError as exc:+ # The shared validator blames the embedding provider; persisted+ # vectors are local data, so restate the fault neutrally.+ raise ValueError(+ f"stored vector in {label} failed validation: {_persisted_vector_fault(exc)}"+ ) from excdef _iter_index_embedding_dicts(index: Any):@@ -189,9 +203,11 @@ def _validate_persisted_embeddings(index: Any, storage_dir: Path | None = None)_validate_embedding_dict(embedding_dict, label=label)except ValueError as exc:raise ValueError(- "RAG index contains invalid embedding vectors. Re-index the "- "knowledge base with the current embedding provider/model before "- f"querying it again. Details: {exc}"+ "RAG index contains invalid embedding vectors. Rebuild it with "+ "the knowledge base's 'Re-index' action (Index versions → "+ "Re-index) using the current embedding provider/model; "+ "re-uploading documents reuses the damaged store and cannot "+ f"repair it. Details: {exc}") from excdiff --git a/tests/services/rag/test_llamaindex_embedding_failures.py b/tests/services/rag/test_llamaindex_embedding_failures.pyindex 6c3eacf6d..152140e4a 100644--- a/tests/services/rag/test_llamaindex_embedding_failures.py+++ b/tests/services/rag/test_llamaindex_embedding_failures.py@@ -249,3 +249,95 @@ async def test_rag_service_hides_low_level_invalid_index_error_in_raw_logs(for event_type, message, _ in eventsif event_type == "status")+++async def test_search_answer_names_reason_and_reindex_action(+ tmp_path, monkeypatch: pytest.MonkeyPatch+) -> None:+ from deeptutor.services.rag.pipelines.llamaindex import storage as storage_module+ from deeptutor.services.rag.pipelines.llamaindex.pipeline import LlamaIndexPipeline++ storage_dir = tmp_path / "kb" / "version-1"+ storage_dir.mkdir(parents=True)+ (storage_dir / "docstore.json").write_text("{}", encoding="utf-8")+ (storage_dir / "default__vector_store.json").write_text(+ json.dumps({"embedding_dict": {"bad-node": [0.1, None, 0.3]}}),+ encoding="utf-8",+ )++ # The in-memory index looks healthy; the invalid vectors live in the+ # persisted vector-store file (the upgrade scenario from issue #440).+ fake_index = SimpleNamespace(+ vector_store=SimpleNamespace(data=SimpleNamespace(embedding_dict={}))+ )+ monkeypatch.setattr(storage_module.vector_store, "load_index", lambda _dir: fake_index)+ monkeypatch.setattr(LlamaIndexPipeline, "_configure_settings", lambda self: None)++ pipeline = LlamaIndexPipeline(kb_base_dir=str(tmp_path), signature_provider=lambda: None)++ result = await pipeline.search("what is this?", "kb")++ assert result["error_type"] == "invalid_embedding_index"+ assert result["needs_reindex"] is True+ assert "invalid embedding vectors" in result["answer"]+ assert "dimension 1 is null" in result["answer"]+ assert "default__vector_store.json" in result["answer"]+ assert "stored vector in default__vector_store.json" in result["answer"]+ assert "embedding provider returned invalid" not in result["answer"].lower()+ assert "Re-index" in result["answer"]+ assert "Index versions" in result["answer"]+ assert "re-uploading" in result["answer"].lower()+++def test_invalid_index_error_names_reindex_action_and_reupload_caveat(tmp_path) -> None:+ from deeptutor.services.rag.pipelines.llamaindex import storage as storage_module++ storage_dir = tmp_path / "kb" / "version-1"+ storage_dir.mkdir(parents=True)+ (storage_dir / "default__vector_store.json").write_text(+ json.dumps({"embedding_dict": {"bad-node": [0.1, None, 0.3]}}),+ encoding="utf-8",+ )++ with pytest.raises(ValueError) as excinfo:+ storage_module.validate_storage_embeddings(storage_dir)++ message = str(excinfo.value)+ assert "RAG index contains invalid embedding vectors" in message+ assert "dimension 1 is null" in message+ assert "stored vector in default__vector_store.json" in message+ assert "embedding provider returned invalid" not in message.lower()+ assert "Re-index" in message+ assert "re-uploading" in message.lower()+++async def test_search_answer_keeps_reindex_steps_without_low_level_details(+ tmp_path, monkeypatch: pytest.MonkeyPatch+) -> None:+ from deeptutor.services.rag.pipelines.llamaindex import storage as storage_module+ from deeptutor.services.rag.pipelines.llamaindex.pipeline import LlamaIndexPipeline++ storage_dir = tmp_path / "kb" / "version-1"+ storage_dir.mkdir(parents=True)+ (storage_dir / "docstore.json").write_text("{}", encoding="utf-8")++ monkeypatch.setattr(LlamaIndexPipeline, "_configure_settings", lambda self: None)+ monkeypatch.setattr(+ storage_module,+ "retrieve_nodes",+ lambda storage_dir, query, top_k=5: (_ for _ in ()).throw(+ TypeError("unsupported operand type(s) for *: 'NoneType' and 'float'")+ ),+ )++ pipeline = LlamaIndexPipeline(kb_base_dir=str(tmp_path), signature_provider=lambda: None)++ result = await pipeline.search("what is this?", "kb")++ assert result["error_type"] == "invalid_embedding_index"+ assert "Re-index" in result["answer"]+ assert "Index versions" in result["answer"]+ assert "unsupported operand" not in result["answer"]+ assert "Details" not in result["answer"]