Registry / llm-agents / llama-index-vector-stores-faiss

llama-index-vector-stores-faiss

JSON →
library0.6.0pypypiunverified

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.

pip install llama-index-vector-stores-faiss faiss-cpu
INSTALL
IMPORT
SIG · LLAMA-INDEX-VECTOR
L
llama-index-vector-stores-faiss
llm-agentspythonv0.6.0
Install
25.2s avg
Import
Disk
388MB
Pass rate
2/ 10
Env Coverage2 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
2/4 runs
✓ 25.05s
py 3.11
2/4 runs
3/4 runs
py 3.12
2/4 runs
3/4 runs
py 3.13
2/4 runs
3/4 runs
py 3.9
2/4 runs
✓ 25.28s
388MB installed
● package 388MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

FAISSVectorStore
from llama_index.vector_stores.faiss import FAISSVectorStore
from llama_index.vector_stores 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
import faiss
from faiss import IndexFlatL2
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

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.")
Debug
Known issues
gotchaThe 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.
affects: All versions
breakingLlamaIndex 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`.
affects: >=0.1.0 of the new modular structure (~v0.10+ of main LlamaIndex)
gotchaThe 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`).
affects: All versions
gotchaWhen 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)`
affects: All versions
Upgrade
Version history
0.6.0latest on PyPI · released Mar 12, 2026
Audit
Dependencies
llama-index-corerequiredProvides core LlamaIndex functionalities like VectorStoreIndex, StorageContext, Document, etc.
faiss-cpuoptionalThe underlying FAISS library for vector operations, required by this integration. Choose 'faiss-gpu' for GPU acceleration.
faiss-gpuoptionalThe underlying FAISS library for vector operations, required by this integration. Choose 'faiss-cpu' for CPU-only usage.
Agent activity
52 hits · last 30 days
node
46
OpenAI (training)
1
Resources
llama-index-vector-stores-faiss — pip install llama-index-vector-stores-faiss · libregistry