Skip to content

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

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.py
index 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 annotations
from 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.py
index 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 exc
def _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 exc
diff --git a/tests/services/rag/test_llamaindex_embedding_failures.py b/tests/services/rag/test_llamaindex_embedding_failures.py
index 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 events
if 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"]