{"id":9086,"library":"llama-index-vector-stores-faiss","title":"LlamaIndex FAISS Vector Store","description":"llama-index-vector-stores-faiss provides an integration for LlamaIndex to use FAISS (Facebook AI Similarity Search) as a high-performance vector store. It allows users to store and retrieve document embeddings efficiently for Retrieval-Augmented Generation (RAG) applications, leveraging FAISS's capabilities for fast similarity search. The current version is 0.6.0, and it generally follows the rapid release cadence of the broader LlamaIndex ecosystem.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/run-llama/llama-index/tree/main/llama-index-integrations/vector_stores/faiss","tags":["llama-index","faiss","vector-store","embeddings","rag","similarity-search"],"install":[{"cmd":"pip install llama-index-vector-stores-faiss faiss-cpu","lang":"bash","label":"Basic Installation (CPU)"},{"cmd":"pip install llama-index-vector-stores-faiss faiss-gpu","lang":"bash","label":"GPU Installation (if NVIDIA GPU available)"}],"dependencies":[{"reason":"Provides core LlamaIndex functionalities like VectorStoreIndex, StorageContext, Document, etc.","package":"llama-index-core"},{"reason":"The underlying FAISS library for vector operations, required by this integration. Choose 'faiss-gpu' for GPU acceleration.","package":"faiss-cpu","optional":true},{"reason":"The underlying FAISS library for vector operations, required by this integration. Choose 'faiss-cpu' for CPU-only usage.","package":"faiss-gpu","optional":true}],"imports":[{"note":"FAISSVectorStore is now in a separate integration package; previous import paths will cause ModuleNotFoundError if the integration package is not installed.","wrong":"from llama_index.vector_stores import FAISSVectorStore","symbol":"FAISSVectorStore","correct":"from llama_index.vector_stores.faiss import FAISSVectorStore"},{"symbol":"VectorStoreIndex","correct":"from llama_index.core import VectorStoreIndex"},{"symbol":"StorageContext","correct":"from llama_index.core import StorageContext"},{"symbol":"SimpleDirectoryReader","correct":"from llama_index.core import SimpleDirectoryReader"},{"symbol":"load_index_from_storage","correct":"from llama_index.core import load_index_from_storage"},{"note":"Common practice is to import the faiss module directly and access components via 'faiss.IndexFlatL2'.","wrong":"from faiss import IndexFlatL2","symbol":"faiss","correct":"import faiss"},{"symbol":"resolve_embed_model","correct":"from llama_index.core.embeddings import resolve_embed_model"}],"quickstart":{"code":"import os\nimport faiss\nfrom llama_index.core import VectorStoreIndex, StorageContext, SimpleDirectoryReader, load_index_from_storage\nfrom llama_index.vector_stores.faiss import FAISSVectorStore\nfrom llama_index.core.embeddings import resolve_embed_model\n\n# --- Setup: Install necessary packages and configure API key ---\n# pip install llama-index-vector-stores-faiss faiss-cpu llama-index-llms-openai llama-index-embeddings-openai\n\n# Set up OpenAI API key for default embedding model, or configure another model\nos.environ[\"OPENAI_API_KEY\"] = os.environ.get(\"OPENAI_API_KEY\", \"sk-YOUR_OPENAI_KEY\")\n\n# Create a dummy directory with a text file for demonstration\nif not os.path.exists(\"./data\"):\n    os.makedirs(\"./data\")\nwith open(\"./data/example.txt\", \"w\") as f:\n    f.write(\"The quick brown fox jumps over the lazy dog. LlamaIndex is powerful.\\n\")\n    f.write(\"FAISS is a library for efficient similarity search and clustering of dense vectors.\\n\")\n    f.write(\"RAG combines retrieval with large language models.\")\n\n# 1. Load documents from the dummy directory\ndocuments = SimpleDirectoryReader(\"./data\").load_data()\n\n# 2. Determine embedding dimension using the default embedding model\n# This is crucial for initializing the FAISS index correctly.\nembed_model = resolve_embed_model(\"default\") # Uses OpenAI by default\ndummy_embedding = embed_model.get_text_embedding(\"hello world\")\nd = len(dummy_embedding) # e.g., 1536 for OpenAI's text-embedding-ada-002\n\n# 3. Initialize FAISS index (e.g., a simple L2 distance index)\nfaiss_index = faiss.IndexFlatL2(d)\n\n# 4. Initialize FAISSVectorStore with the created FAISS index\nvector_store = FAISSVectorStore(faiss_index=faiss_index)\n\n# 5. Create StorageContext, linking it to the FAISSVectorStore\nstorage_context = StorageContext.from_defaults(vector_store=vector_store)\n\n# 6. Create VectorStoreIndex from documents, using the defined storage context\nindex = VectorStoreIndex.from_documents(\n    documents,\n    storage_context=storage_context,\n)\n\n# 7. Query the index\nquery_engine = index.as_query_engine()\nresponse = query_engine.query(\"What is RAG?\")\nprint(f\"\\nQuery Response: {response}\\n\")\n\n# 8. Example of persistence and loading\npersist_dir = \"./faiss_storage\"\nif not os.path.exists(persist_dir):\n    os.makedirs(persist_dir)\n\n# Persist the index, including the FAISS index file\nindex.storage_context.persist(persist_dir=persist_dir)\nprint(f\"Index persisted to {persist_dir}\\n\")\n\n# Load the index back from storage\n# First, load the FAISS index itself\nloaded_faiss_index = faiss.read_index(os.path.join(persist_dir, \"vector_store.faiss\"))\nloaded_vector_store = FAISSVectorStore(faiss_index=loaded_faiss_index)\n\n# Then, load the LlamaIndex StorageContext and the index\nloaded_storage_context = StorageContext.from_defaults(\n    vector_store=loaded_vector_store,\n    persist_dir=persist_dir\n)\nloaded_index = load_index_from_storage(loaded_storage_context)\nloaded_query_engine = loaded_index.as_query_engine()\nloaded_response = loaded_query_engine.query(\"What did the fox do?\")\nprint(f\"Loaded Index Query Response: {loaded_response}\\n\")\n\n# --- Clean up dummy data and directories ---\nimport shutil\nshutil.rmtree(\"./data\")\nshutil.rmtree(persist_dir)\nprint(\"Cleaned up dummy data and storage directories.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure you run `pip install llama-index-vector-stores-faiss faiss-cpu` (or `faiss-gpu`) to get both packages.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install the dedicated integration package (`pip install llama-index-vector-stores-faiss`) and use `from llama_index.vector_stores.faiss import FAISSVectorStore`.","message":"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.","severity":"breaking","affected_versions":">=0.1.0 of the new modular structure (~v0.10+ of main LlamaIndex)"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Follow the pattern:\n1. `loaded_faiss_index = faiss.read_index(os.path.join(persist_dir, \"vector_store.faiss\"))`\n2. `loaded_vector_store = FAISSVectorStore(faiss_index=loaded_faiss_index)`\n3. `loaded_storage_context = StorageContext.from_defaults(vector_store=loaded_vector_store, persist_dir=persist_dir)`\n4. `loaded_index = load_index_from_storage(loaded_storage_context)`","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install FAISS: `pip install faiss-cpu` (for CPU) or `pip install faiss-gpu` (for GPU).","cause":"The FAISS library (`faiss-cpu` or `faiss-gpu`) is not installed.","error":"ModuleNotFoundError: No module named 'faiss'"},{"fix":"Install the integration package: `pip install llama-index-vector-stores-faiss`.","cause":"The `llama-index-vector-stores-faiss` package is not installed. This integration is now a separate package.","error":"ModuleNotFoundError: No module named 'llama_index.vector_stores.faiss'"},{"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\"))`.","cause":"The dimension (`d`) provided to `faiss.IndexFlatL2(d)` does not match the dimension of the embeddings generated by your LlamaIndex embedding model.","error":"RuntimeError: Error in faiss::IndexFlat::add: size == d"},{"fix":"Verify that `faiss_index` is correctly initialized as a `faiss.Index` object, such as `faiss_index = faiss.IndexFlatL2(d)`.","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`).","error":"TypeError: __init__ received an invalid combination of arguments"}]}