LlamaIndex FAISS Vector Store

Common errors

• ModuleNotFoundError: No module named 'faiss'

  cause The FAISS library (`faiss-cpu` or `faiss-gpu`) is not installed.
  fix Install FAISS: `pip install faiss-cpu` (for CPU) or `pip install faiss-gpu` (for GPU).

• ModuleNotFoundError: No module named 'llama_index.vector_stores.faiss'

  cause The `llama-index-vector-stores-faiss` package is not installed. This integration is now a separate package.
  fix Install the integration package: `pip install llama-index-vector-stores-faiss`.

• RuntimeError: Error in faiss::IndexFlat::add: size == d

  cause The dimension (`d`) provided to `faiss.IndexFlatL2(d)` does not match the dimension of the embeddings generated by your LlamaIndex embedding model.
  fix Ensure the `d` parameter for the FAISS index matches your embedding model's output dimension. You can get this programmatically with `len(embed_model.get_text_embedding("text"))`.

• TypeError: __init__ received an invalid combination of arguments

  cause This generic TypeError, or similar, can occur if the `faiss_index` object passed to `FAISSVectorStore` is not a valid FAISS index instance (e.g., `faiss.IndexFlatL2`).
  fix Verify that `faiss_index` is correctly initialized as a `faiss.Index` object, such as `faiss_index = faiss.IndexFlatL2(d)`.

Warnings

• gotcha The underlying FAISS library (`faiss-cpu` or `faiss-gpu`) is a separate dependency and must be installed alongside `llama-index-vector-stores-faiss`. Forgetting this leads to `ModuleNotFoundError`.
  Fix: Ensure you run `pip install llama-index-vector-stores-faiss faiss-cpu` (or `faiss-gpu`) to get both packages.
• breaking LlamaIndex restructured its packages, moving integrations like FAISS to separate libraries. Importing `FAISSVectorStore` directly from `llama_index.vector_stores` without installing `llama-index-vector-stores-faiss` will fail.
  Fix: Install the dedicated integration package (`pip install llama-index-vector-stores-faiss`) and use `from llama_index.vector_stores.faiss import FAISSVectorStore`.
• gotcha The FAISS index must be initialized with the correct embedding dimension (`d`) that matches the output of your LlamaIndex embedding model. A mismatch will cause `RuntimeError: Error in faiss::IndexFlat::add: size == d` when adding vectors.
  Fix: Dynamically determine the embedding dimension using `len(embed_model.get_text_embedding("dummy text"))` or ensure `d` is set to the known dimension of your chosen embedding model (e.g., 1536 for OpenAI `text-embedding-ada-002`).
• gotcha When persisting and loading a LlamaIndex with a FAISS vector store, you must explicitly load the `vector_store.faiss` file and initialize `FAISSVectorStore` with it *before* loading the LlamaIndex `StorageContext`.
  Fix: Follow the pattern: 1. `loaded_faiss_index = faiss.read_index(os.path.join(persist_dir, "vector_store.faiss"))` 2. `loaded_vector_store = FAISSVectorStore(faiss_index=loaded_faiss_index)` 3. `loaded_storage_context = StorageContext.from_defaults(vector_store=loaded_vector_store, persist_dir=persist_dir)` 4. `loaded_index = load_index_from_storage(loaded_storage_context)`

Install

• pip install llama-index-vector-stores-faiss faiss-cpu Basic Installation (CPU)
• pip install llama-index-vector-stores-faiss faiss-gpu GPU Installation (if NVIDIA GPU available)

Imports

• FAISSVectorStore
  wrong:

  from llama_index.vector_stores import FAISSVectorStore

  correct:

  from llama_index.vector_stores.faiss import FAISSVectorStore

  FAISSVectorStore is now in a separate integration package; previous import paths will cause ModuleNotFoundError if the integration package is not installed.
• VectorStoreIndex

  from llama_index.core import VectorStoreIndex

• StorageContext

  from llama_index.core import StorageContext

• SimpleDirectoryReader

  from llama_index.core import SimpleDirectoryReader

• load_index_from_storage

  from llama_index.core import load_index_from_storage

• faiss
  wrong:

  from faiss import IndexFlatL2

  correct:

  import faiss

  Common practice is to import the faiss module directly and access components via 'faiss.IndexFlatL2'.
• resolve_embed_model

  from llama_index.core.embeddings import resolve_embed_model

Quickstart

This quickstart demonstrates how to initialize a FAISS vector store, create a LlamaIndex VectorStoreIndex, add documents, query it, and then persist and load the index. It includes steps for handling embedding dimensions and API key setup.

import os
import faiss
from llama_index.core import VectorStoreIndex, StorageContext, SimpleDirectoryReader, load_index_from_storage
from llama_index.vector_stores.faiss import FAISSVectorStore
from llama_index.core.embeddings import resolve_embed_model

# --- Setup: Install necessary packages and configure API key ---
# pip install llama-index-vector-stores-faiss faiss-cpu llama-index-llms-openai llama-index-embeddings-openai

# Set up OpenAI API key for default embedding model, or configure another model
os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "sk-YOUR_OPENAI_KEY")

# Create a dummy directory with a text file for demonstration
if not os.path.exists("./data"):
    os.makedirs("./data")
with open("./data/example.txt", "w") as f:
    f.write("The quick brown fox jumps over the lazy dog. LlamaIndex is powerful.\n")
    f.write("FAISS is a library for efficient similarity search and clustering of dense vectors.\n")
    f.write("RAG combines retrieval with large language models.")

# 1. Load documents from the dummy directory
documents = SimpleDirectoryReader("./data").load_data()

# 2. Determine embedding dimension using the default embedding model
# This is crucial for initializing the FAISS index correctly.
embed_model = resolve_embed_model("default") # Uses OpenAI by default
dummy_embedding = embed_model.get_text_embedding("hello world")
d = len(dummy_embedding) # e.g., 1536 for OpenAI's text-embedding-ada-002

# 3. Initialize FAISS index (e.g., a simple L2 distance index)
faiss_index = faiss.IndexFlatL2(d)

# 4. Initialize FAISSVectorStore with the created FAISS index
vector_store = FAISSVectorStore(faiss_index=faiss_index)

# 5. Create StorageContext, linking it to the FAISSVectorStore
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# 6. Create VectorStoreIndex from documents, using the defined storage context
index = VectorStoreIndex.from_documents(
    documents,
    storage_context=storage_context,
)

# 7. Query the index
query_engine = index.as_query_engine()
response = query_engine.query("What is RAG?")
print(f"\nQuery Response: {response}\n")

# 8. Example of persistence and loading
persist_dir = "./faiss_storage"
if not os.path.exists(persist_dir):
    os.makedirs(persist_dir)

# Persist the index, including the FAISS index file
index.storage_context.persist(persist_dir=persist_dir)
print(f"Index persisted to {persist_dir}\n")

# Load the index back from storage
# First, load the FAISS index itself
loaded_faiss_index = faiss.read_index(os.path.join(persist_dir, "vector_store.faiss"))
loaded_vector_store = FAISSVectorStore(faiss_index=loaded_faiss_index)

# Then, load the LlamaIndex StorageContext and the index
loaded_storage_context = StorageContext.from_defaults(
    vector_store=loaded_vector_store,
    persist_dir=persist_dir
)
loaded_index = load_index_from_storage(loaded_storage_context)
loaded_query_engine = loaded_index.as_query_engine()
loaded_response = loaded_query_engine.query("What did the fox do?")
print(f"Loaded Index Query Response: {loaded_response}\n")

# --- Clean up dummy data and directories ---
import shutil
shutil.rmtree("./data")
shutil.rmtree(persist_dir)
print("Cleaned up dummy data and storage directories.")