Skip to content

FAISSIndex

llmfy.vector_store.faiss_index.faiss_index

FAISSIndex

Source code in llmfy/vector_store/faiss_index/faiss_index.py 
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
class FAISSIndex:
    def __init__(
        self,
        dim: int,
        index_type: Literal["flat", "hnsw", "lsh", "ivfflat", "ivfpq"] = "flat",
        nlist: int = 100,
        nprobe: int = 10,
        M: int = 32,
        ef_search: int = 50,
        nbits: int = 8,
        index: Optional[Any] = None,
    ):
        """
        Initialize FAISS Index.

        Args:
            dim (int): Dimension of vectors.

            index_type (str): Type of FAISS index (flat, ivfflat, ivfpq, hnsw, lsh).

            nlist (int): Number of clusters (for ivfflat and ivfpq).
                Higher nlist → finer partition, better recall, but more memory and slower training.
                Lower nlist → faster but worse recall.
                Depends on vectors? Yes → set relative to dataset size, depends on dataset size, larger datasets need higher nlist.
                Retraining? Yes. Changing nlist requires re-training and rebuilding index.
                Tunable at query time? ❌ No.
                Rule of thumb:
                    - nlist ≈ √N (where N is the number of vectors),
                    - Example: For 1M vectors → nlist ~ 1000.

            nprobe (int): Number of clusters to search (for ivfflat and ivfpq).
                Higher nprobe → better recall, slower search.
                Lower nprobe → faster, but may miss good neighbors.
                Depends on vectors? No → only affects search speed/recall.
                Retraining? No.
                Tunable at query time? ✅ Yes.
                Rule of thumb:
                    - Start with nprobe = 1–10% of nlist,
                    - Example: nlist = 1000 → nprobe = 10–50.

            M (int): Number of neighbors per node in the HNSW graph (for hnsw).
                Higher M → better recall, more memory, longer build time.
                Lower M → smaller memory, but lower recall.
                Depends on vectors? Not directly, but larger datasets usually benefit from higher M.
                Retraining? Yes → must rebuild graph if M changes.
                Tunable at query time? ❌ No.
                Rule of thumb:
                    - Typical range: 16–64,
                    - M = 32 is a common good default.

            ef_search (int): Size of candidate list during search (search depth) (for hnsw).
                Higher ef_search → better recall, slower query.
                Lower ef_search → faster, but may miss true neighbors.
                Depends on vectors? No.
                Retraining? No.
                Tunable at query time? ✅ Yes.
                Rule of thumb:
                    - Set ef_search around k * 2–10 (where k is top neighbors).
                    - Example: for k=10, ef_search=50 is common.

            nbits (int): Number of bits  per vector used for hashing (for lsh).
                Higher nbits → more fine-grained buckets, better recall, but more memory.
                Lower nbits → fewer buckets, faster, but worse recall.
                Depends on vectors? Yes → tied to dimension.
                Retraining? Yes → index must be rebuilt if nbits changes.
                Tunable at query time? ❌ No.
                Rule of thumb:
                    - Often nbits = 2 * dim or less.
                    - Example: for dim=128, try nbits=128 or nbits=256.


        """

        if faiss is None:
            raise LLMfyException(
                'faiss package is not installed. Install it using `pip install "llmfy[faiss-cpu]"`'
            )

        if np is None:
            raise LLMfyException(
                'numpy package is not installed. Install it using `pip install "llmfy[numpy]"`'
            )

        self.dim = dim
        self.index_type = index_type.lower()
        self.index = (
            self._create_index(dim, self.index_type, nlist, M, nbits)
            if not index
            else index
        )

        # IVF params
        self.nprobe = nprobe
        if "ivfflat" in self.index_type:
            self.index.nprobe = nprobe  # type: ignore

        # HNSW params
        self.ef_search = ef_search
        if "hnsw" in self.index_type:
            self.index.hnsw.efSearch = ef_search  # type: ignore

    def _create_index(
        self,
        dim: int,
        index_type: str,
        nlist: int,
        M: int,
        nbits: int,
    ):
        if faiss is None:
            raise LLMfyException(
                'faiss package is not installed. Install it using `pip install "llmfy[faiss-cpu]"`'
            )

        if np is None:
            raise LLMfyException(
                'numpy package is not installed. Install it using `pip install "llmfy[numpy]"`'
            )

        # Use IP (Inner Product / Cosine Similarity) best for semantic search, retrieval, RAG
        # with embeddings from models like Bedrock Titan, OpenAI, Cohere, etc.
        if index_type == "flat":
            return faiss.IndexFlatIP(dim)
        elif index_type == "hnsw":
            return faiss.IndexHNSWFlat(dim, M, faiss.METRIC_INNER_PRODUCT)
        elif index_type == "lsh":
            return faiss.IndexLSH(dim, nbits)
        elif index_type == "ivfflat":
            quantizer = faiss.IndexFlatIP(dim)
            return faiss.IndexIVFFlat(quantizer, dim, nlist, faiss.METRIC_INNER_PRODUCT)
        elif index_type == "ivfpq":
            quantizer = faiss.IndexFlatIP(dim)
            return faiss.IndexIVFPQ(
                quantizer, dim, nlist, M, nbits, faiss.METRIC_INNER_PRODUCT
            )
        else:
            raise ValueError(f"Unsupported index type: {index_type}")

    def train(self, vectors):
        """
        Train the index (required for IVF).

        Args:
            vectors (np.ndarray): _description_
        """
        self.index.train(vectors)  # type: ignore

    def add(self, vectors):
        """
        Add vectors to the index.

        Args:
            vectors (np.ndarray): _description_

        Raises:
            ValueError: _description_
        """
        if not self.index:
            raise ValueError("Index not initialized.")

        # Check train if is_trained is false
        if not self.index.is_trained:
            self.train(vectors)

        self.index.add(vectors)  # type: ignore

    def search(
        self,
        query,
        k: int = 5,
        nprobe: Optional[int] = None,
        ef_search: Optional[int] = None,
    ):
        """
        Search the index.

        Args:
            query (np.ndarray): _description_
            k (int, optional): _description_. Defaults to 5.
            nprobe (Optional[int], optional): _description_. Defaults to None.
            ef_search (Optional[int], optional): _description_. Defaults to None.

        Returns:
            distances (np.ndarray), indices (np.ndarray)
        """
        # Tuning HNSW params
        if "hnsw" in self.index_type:
            if ef_search:
                self.index.hnsw.efSearch = ef_search  # type: ignore
            else:
                self.index.hnsw.efSearch = self.ef_search  # type: ignore

        # Tuning IVF params
        if "ivfflat" in self.index_type:
            if nprobe:
                self.index.nprobe = nprobe  # type: ignore
            else:
                self.index.nprobe = self.nprobe  # type: ignore

        distances, indices = self.index.search(query, k)  # type: ignore
        return distances, indices

    def save(self, path: str):
        """
        Save the FAISS index to disk.
        """
        if faiss is None:
            raise LLMfyException(
                'faiss package is not installed. Install it using `pip install "llmfy[faiss-cpu]"`'
            )

        faiss.write_index(self.index, path)

    def load(self, path: str):
        """
        Load the FAISS index from disk.
        """
        if faiss is None:
            raise LLMfyException(
                'faiss package is not installed. Install it using `pip install "llmfy[faiss-cpu]"`'
            )

        self.index = faiss.read_index(path)

dim = dim instance-attribute

index_type = index_type.lower() instance-attribute

index = self._create_index(dim, self.index_type, nlist, M, nbits) if not index else index instance-attribute

nprobe = nprobe instance-attribute

__init__(dim, index_type='flat', nlist=100, nprobe=10, M=32, ef_search=50, nbits=8, index=None)

Initialize FAISS Index.

Parameters:

Name Type Description Default
dim int

Dimension of vectors.

 required
index_type str

Type of FAISS index (flat, ivfflat, ivfpq, hnsw, lsh).

 'flat'
nlist int

Number of clusters (for ivfflat and ivfpq). Higher nlist → finer partition, better recall, but more memory and slower training. Lower nlist → faster but worse recall. Depends on vectors? Yes → set relative to dataset size, depends on dataset size, larger datasets need higher nlist. Retraining? Yes. Changing nlist requires re-training and rebuilding index. Tunable at query time? ❌ No. Rule of thumb: - nlist ≈ √N (where N is the number of vectors), - Example: For 1M vectors → nlist ~ 1000.

 100
nprobe int

Number of clusters to search (for ivfflat and ivfpq). Higher nprobe → better recall, slower search. Lower nprobe → faster, but may miss good neighbors. Depends on vectors? No → only affects search speed/recall. Retraining? No. Tunable at query time? ✅ Yes. Rule of thumb: - Start with nprobe = 1–10% of nlist, - Example: nlist = 1000 → nprobe = 10–50.

 10
M int

Number of neighbors per node in the HNSW graph (for hnsw). Higher M → better recall, more memory, longer build time. Lower M → smaller memory, but lower recall. Depends on vectors? Not directly, but larger datasets usually benefit from higher M. Retraining? Yes → must rebuild graph if M changes. Tunable at query time? ❌ No. Rule of thumb: - Typical range: 16–64, - M = 32 is a common good default.

 32
ef_search int

Size of candidate list during search (search depth) (for hnsw). Higher ef_search → better recall, slower query. Lower ef_search → faster, but may miss true neighbors. Depends on vectors? No. Retraining? No. Tunable at query time? ✅ Yes. Rule of thumb: - Set ef_search around k * 2–10 (where k is top neighbors). - Example: for k=10, ef_search=50 is common.

 50
nbits int

Number of bits per vector used for hashing (for lsh). Higher nbits → more fine-grained buckets, better recall, but more memory. Lower nbits → fewer buckets, faster, but worse recall. Depends on vectors? Yes → tied to dimension. Retraining? Yes → index must be rebuilt if nbits changes. Tunable at query time? ❌ No. Rule of thumb: - Often nbits = 2 * dim or less. - Example: for dim=128, try nbits=128 or nbits=256.

 8
Source code in llmfy/vector_store/faiss_index/faiss_index.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def __init__(
    self,
    dim: int,
    index_type: Literal["flat", "hnsw", "lsh", "ivfflat", "ivfpq"] = "flat",
    nlist: int = 100,
    nprobe: int = 10,
    M: int = 32,
    ef_search: int = 50,
    nbits: int = 8,
    index: Optional[Any] = None,
):
    """
    Initialize FAISS Index.

    Args:
        dim (int): Dimension of vectors.

        index_type (str): Type of FAISS index (flat, ivfflat, ivfpq, hnsw, lsh).

        nlist (int): Number of clusters (for ivfflat and ivfpq).
            Higher nlist → finer partition, better recall, but more memory and slower training.
            Lower nlist → faster but worse recall.
            Depends on vectors? Yes → set relative to dataset size, depends on dataset size, larger datasets need higher nlist.
            Retraining? Yes. Changing nlist requires re-training and rebuilding index.
            Tunable at query time? ❌ No.
            Rule of thumb:
                - nlist ≈ √N (where N is the number of vectors),
                - Example: For 1M vectors → nlist ~ 1000.

        nprobe (int): Number of clusters to search (for ivfflat and ivfpq).
            Higher nprobe → better recall, slower search.
            Lower nprobe → faster, but may miss good neighbors.
            Depends on vectors? No → only affects search speed/recall.
            Retraining? No.
            Tunable at query time? ✅ Yes.
            Rule of thumb:
                - Start with nprobe = 1–10% of nlist,
                - Example: nlist = 1000 → nprobe = 10–50.

        M (int): Number of neighbors per node in the HNSW graph (for hnsw).
            Higher M → better recall, more memory, longer build time.
            Lower M → smaller memory, but lower recall.
            Depends on vectors? Not directly, but larger datasets usually benefit from higher M.
            Retraining? Yes → must rebuild graph if M changes.
            Tunable at query time? ❌ No.
            Rule of thumb:
                - Typical range: 16–64,
                - M = 32 is a common good default.

        ef_search (int): Size of candidate list during search (search depth) (for hnsw).
            Higher ef_search → better recall, slower query.
            Lower ef_search → faster, but may miss true neighbors.
            Depends on vectors? No.
            Retraining? No.
            Tunable at query time? ✅ Yes.
            Rule of thumb:
                - Set ef_search around k * 2–10 (where k is top neighbors).
                - Example: for k=10, ef_search=50 is common.

        nbits (int): Number of bits  per vector used for hashing (for lsh).
            Higher nbits → more fine-grained buckets, better recall, but more memory.
            Lower nbits → fewer buckets, faster, but worse recall.
            Depends on vectors? Yes → tied to dimension.
            Retraining? Yes → index must be rebuilt if nbits changes.
            Tunable at query time? ❌ No.
            Rule of thumb:
                - Often nbits = 2 * dim or less.
                - Example: for dim=128, try nbits=128 or nbits=256.


    """

    if faiss is None:
        raise LLMfyException(
            'faiss package is not installed. Install it using `pip install "llmfy[faiss-cpu]"`'
        )

    if np is None:
        raise LLMfyException(
            'numpy package is not installed. Install it using `pip install "llmfy[numpy]"`'
        )

    self.dim = dim
    self.index_type = index_type.lower()
    self.index = (
        self._create_index(dim, self.index_type, nlist, M, nbits)
        if not index
        else index
    )

    # IVF params
    self.nprobe = nprobe
    if "ivfflat" in self.index_type:
        self.index.nprobe = nprobe  # type: ignore

    # HNSW params
    self.ef_search = ef_search
    if "hnsw" in self.index_type:
        self.index.hnsw.efSearch = ef_search  # type: ignore

train(vectors)

Train the index (required for IVF).

Parameters:

Name Type Description Default
vectors ndarray

description

 required
Source code in llmfy/vector_store/faiss_index/faiss_index.py 
154
155
156
157
158
159
160
161
def train(self, vectors):
    """
    Train the index (required for IVF).

    Args:
        vectors (np.ndarray): _description_
    """
    self.index.train(vectors)  # type: ignore

add(vectors)

Add vectors to the index.

Parameters:

Name Type Description Default
vectors ndarray

description

 required

Raises:

Type Description
ValueError

description
Source code in llmfy/vector_store/faiss_index/faiss_index.py 
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
def add(self, vectors):
    """
    Add vectors to the index.

    Args:
        vectors (np.ndarray): _description_

    Raises:
        ValueError: _description_
    """
    if not self.index:
        raise ValueError("Index not initialized.")

    # Check train if is_trained is false
    if not self.index.is_trained:
        self.train(vectors)

    self.index.add(vectors)  # type: ignore

search(query, k=5, nprobe=None, ef_search=None)

Search the index.

Parameters:

Name Type Description Default
query ndarray

description

 required
k int

description. Defaults to 5.

 5
nprobe Optional[int]

description. Defaults to None.

 None
ef_search Optional[int]

description. Defaults to None.

 None

Returns:

Type Description

distances (np.ndarray), indices (np.ndarray)
Source code in llmfy/vector_store/faiss_index/faiss_index.py 
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
def search(
    self,
    query,
    k: int = 5,
    nprobe: Optional[int] = None,
    ef_search: Optional[int] = None,
):
    """
    Search the index.

    Args:
        query (np.ndarray): _description_
        k (int, optional): _description_. Defaults to 5.
        nprobe (Optional[int], optional): _description_. Defaults to None.
        ef_search (Optional[int], optional): _description_. Defaults to None.

    Returns:
        distances (np.ndarray), indices (np.ndarray)
    """
    # Tuning HNSW params
    if "hnsw" in self.index_type:
        if ef_search:
            self.index.hnsw.efSearch = ef_search  # type: ignore
        else:
            self.index.hnsw.efSearch = self.ef_search  # type: ignore

    # Tuning IVF params
    if "ivfflat" in self.index_type:
        if nprobe:
            self.index.nprobe = nprobe  # type: ignore
        else:
            self.index.nprobe = self.nprobe  # type: ignore

    distances, indices = self.index.search(query, k)  # type: ignore
    return distances, indices

save(path)

Save the FAISS index to disk.

Source code in llmfy/vector_store/faiss_index/faiss_index.py 
218
219
220
221
222
223
224
225
226
227
def save(self, path: str):
    """
    Save the FAISS index to disk.
    """
    if faiss is None:
        raise LLMfyException(
            'faiss package is not installed. Install it using `pip install "llmfy[faiss-cpu]"`'
        )

    faiss.write_index(self.index, path)

load(path)

Load the FAISS index from disk.

Source code in llmfy/vector_store/faiss_index/faiss_index.py 
229
230
231
232
233
234
235
236
237
238
def load(self, path: str):
    """
    Load the FAISS index from disk.
    """
    if faiss is None:
        raise LLMfyException(
            'faiss package is not installed. Install it using `pip install "llmfy[faiss-cpu]"`'
        )

    self.index = faiss.read_index(path)