How do you persist a FAISS index with write_index and read_index, and what is not saved?

## The API FAISS persistence is deliberately minimal: ``` faiss.write_index(index, "vectors.faiss") index = faiss.read_index("vectors.faiss") ``` `write_index` serialises the concrete index type and all of its state into a single binary file; `read_index` reconstructs the right subclass from that file. There is no `index.save()` method, and FAISS index objects are not picklable — attempting to pickle one fails or produces something that will not survive a round trip, so the module-level functions are the only supported path. ## What the file contains Everything the index needs to answer queries: - the index type and dimension, - for IVF indexes, the trained coarse-quantizer centroids and the inverted lists, - for PQ indexes, the learned codebooks and every stored code, - for HNSW indexes, the graph links, - any pre-transform such as an OPQ rotation matrix, - the 64-bit ids, when the index is wrapped in `IndexIDMap` or uses `add_with_ids`. Because the trained parameters are included, a reloaded IVF or PQ index reports `is_trained == True` and must never be trained again. Re-training would discard the centroids the stored codes were computed against and silently corrupt every result. This is why the standard production shape is: train and build offline, write the file, and have serving processes only read it. ## What the file does not contain FAISS is a similarity-search library, not a database. It stores vectors and ids. It does not store the text a vector was embedded from, any metadata, any filterable attributes, or any notion of a document. That external mapping — id to payload — is your responsibility, and the operational consequence is sharper than it sounds: if the index file and the id-to-document store drift apart by even one insertion, searches return plausible distances attached to the wrong content, and nothing errors. Ship them as one versioned artifact, generated by the same build, and validate on load (for example, that `index.ntotal` matches the row count of the mapping) before the process starts serving. The file also implicitly depends on the embedding model that produced the vectors. A new model version means new vectors, which means a rebuild — record the model version alongside the index file so that a mismatch is detectable rather than silent. ## Loading large indexes `read_index` loads the whole structure into process memory by default, which is exactly what you want for an index that comfortably fits. When it does not, pass a flag: ``` index = faiss.read_index("vectors.faiss", faiss.IO_FLAG_MMAP) ``` This memory-maps the file instead of copying it, so pages are demand-loaded by the OS and several processes on the same host can share them. The tradeoff is that queries touching cold pages pay disk latency, so it suits large IVF indexes where a query scans a small fraction of the data, and suits it badly when random access is broad. ## Deployment hygiene A few habits prevent most production incidents around index files: - **Write atomically.** Write to a temporary path and rename into place, so a reader never opens a half-written file. Rename on the same filesystem is atomic; copying over a live file is not. - **Treat the file as immutable.** Never mutate a file that a serving process has open. Publish a new file, then swap. - **Version the artifact.** Name or tag it with the corpus snapshot and the embedding model version, and store the measured recall next to it, so a regression is attributable. - **Check load time and memory.** Reading a multi-gigabyte index takes real seconds and doubles nothing but does allocate the full structure; size container memory limits against the file size plus overhead, and account for the load in readiness probes. - **Rebuild rather than patch.** FAISS supports adding vectors to a loaded index, but a long-lived, repeatedly-mutated index drifts away from the distribution its centroids were trained on. Periodic full rebuilds keep recall predictable. ## The mental model to carry A FAISS index file is a compiled artifact: expensive to produce, cheap to load, and meaningless without the id mapping and the embedding model it was built with. Treating it that way — built by a pipeline, versioned, validated, swapped atomically — is what separates a FAISS deployment that behaves from one that mysteriously returns the wrong documents after a deploy.