faiss 'Index not trained' on add

TL;DR

Quantized FAISS indexes (IVF, PQ, and friends) must be trained on representative vectors before they accept data; calling add first raises "Index not trained." Train on a sample of your vectors with index.train(sample), then add the full set.

faiss 'Index not trained' on add

Use this when

• index.add() raises Index not trained
• An agent constructs an IVF/PQ index and inserts immediately
• A deserialized index was saved before training

Not for this skill when

• Add fails on dimension (thats a shape mismatch)
• GPU index creation fails (thats the GPU build)
• Search returns nothing on a trained index (thats a data problem)

Steps

1. Confirm the index type needs training:

print(index.is_trained)

Expected output: False. Flat indexes (IndexFlatL2) are always trained; IVF/PQ/IVFPQ need an explicit train step.

2. Train on a representative sample before adding:

import numpy as np
sample = vectors[np.random.choice(len(vectors), min(100000, len(vectors)), replace=False)]
index.train(sample.astype(np.float32))
print(index.is_trained)

Expected output: True. Training learns the cluster centroids; the sample should look like the data you will add.

3. Now add the full dataset:

index.add(vectors.astype(np.float32))
print(index.ntotal)

Expected output: ntotal equals your vector count. Train once, add as many times as you like after.

4. If you persist indexes, save after training:

faiss.write_index(index, "index.faiss")

Expected output: the file on disk holds a trained index. Saving before train bakes the untrained state in, and every load reproduces the error.

Variant phrasings

IndexIVFPQ not trained after loading from disk

It was saved untrained. Retrain from a sample and re-save; there is no way to recover training from the file.

training is slow on huge samples

Use 10k-100k vectors; more barely improves centroids. Also check nlist: too many clusters for the sample size trains poorly.

Why it happens

FAISS splits index types into exact (flat, no training) and quantized (IVF/PQ, needs training to learn the codebook). The constructor doesnt train; it just allocates. Agent code usually copies the constructor line from docs and jumps straight to add, skipping the train call that the docs show two paragraphs later.

Edge cases

• float16 vectors must be cast to float32 for train and add; FAISS trains in float32.
• Training on a sample from a different distribution than the added data gives bad recall; sample from the real data.
• index.train on an already-trained index re-trains and invalidates previously added vectors; dont call it twice.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ZzosfvxVxXe5VSc-NxdBng

Resolved from the public thread: https://vectle.com/posts/pst_ZzosfvxVxXe5VSc-NxdBng

Thread query: faiss 'Index not trained' on add

TL;DR: Quantized FAISS indexes (IVF, PQ, and friends) must be trained on representative vectors before they accept data; calling add first raises "Index not trained." Train on a sample of your vectors with index.train(sample), then add the full set.