HKUDS/DeepTutor · error · RuntimeError

This knowledge base was indexed with FAISS but the 'faiss-cp

Error message

This knowledge base was indexed with FAISS but the 'faiss-cpu' package is not installed. Install it (pip install faiss-cpu) or re-index the knowledge base to query it again.

What it means

load_index() detects a FAISS backend marker in the KB's storage directory but the faiss-cpu import failed (the cosine FAISS class factory returned None). The KB is unreadable until faiss-cpu is installed or the KB is re-indexed with the default simple vector store.

Source

Thrown at deeptutor/services/rag/pipelines/llamaindex/vector_store.py:238

            head = handle.read(1)
    except OSError:
        return BACKEND_SIMPLE
    return BACKEND_SIMPLE if head[:1] == b"{" else BACKEND_FAISS


def load_index(storage_dir: Path) -> Any:
    """Load a persisted index for retrieval.

    FAISS-persisted versions load their binary index directly. Legacy
    SimpleVectorStore versions load unchanged and stay queryable; re-indexing
    such a knowledge base rebuilds it as FAISS for the full speed-up.
    """
    storage_dir = Path(storage_dir)

    if detect_backend(storage_dir) == BACKEND_FAISS:
        cosine_cls = _cosine_faiss_cls()
        if cosine_cls is None:
            raise RuntimeError(
                "This knowledge base was indexed with FAISS but the 'faiss-cpu' "
                "package is not installed. Install it (pip install faiss-cpu) or "
                "re-index the knowledge base to query it again."
            )
        vector_store = cosine_cls.from_persist_dir(str(storage_dir))
        context = StorageContext.from_defaults(
            persist_dir=str(storage_dir), vector_store=vector_store
        )
        return load_index_from_storage(context)

    context = StorageContext.from_defaults(persist_dir=str(storage_dir))
    return load_index_from_storage(context)


__all__ = [
    "BACKEND_FAISS",
    "BACKEND_SIMPLE",
    "DEFAULT_VECTOR_STORE_FILENAME",

View on GitHub (pinned to 3e82f13042)

Solutions

1. pip install faiss-cpu in the active environment, then retry load_index().
2. If you can't install native deps, re-index the KB so it persists with the fallback simple vector store instead of FAISS.
3. Pin faiss-cpu in requirements/pyproject for deployments that will query FAISS-backed KBs.

Example fix

# before
index = load_index(storage_dir=kb_path)  # RuntimeError: faiss-cpu not installed

# after
# shell: pip install faiss-cpu
index = load_index(storage_dir=kb_path)

def faiss_available() -> bool:
    try:
        import faiss  # noqa: F401
        return True
    except ImportError:
        return False

def can_load_faiss_backend(storage_dir) -> bool:
    from deeptutor.services.rag.pipelines.llamaindex.vector_store import detect_backend, BACKEND_FAISS
    return not (detect_backend(storage_dir) == BACKEND_FAISS and not faiss_available())

try:
    index = load_index(storage_dir=d)
except RuntimeError as e:
    if "faiss-cpu" in str(e):
        subprocess.run([sys.executable, "-m", "pip", "install", "faiss-cpu"], check=True)
        index = load_index(storage_dir=d)
    else:
        raise

When it happens

Trigger: Calling load_index() on a storage_dir whose persist metadata indicates BACKEND_FAISS while the faiss-cpu package is absent from the environment (CLI-only or slim install without the faiss extra).

Common situations: Indexing on a machine with faiss-cpu, then querying on a slim Docker image / deeptutor-cli install without it; upgrading or recreating a venv that dropped faiss-cpu.

Related errors

• No existing FAISS index found at {persist_path}.
• GraphRAG is not installed. Run `pip install 'deeptutor[graph
• LightRAG is not installed. Run `pip install 'deeptutor[rag-l
• RAG index contains invalid embedding vectors. Re-index the k
• CodeGeneratorAgent generation prompts are not configured.

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/fa8f588c35d7ba61. Report an issue: GitHub.