migration guide

Migrate from FAISS to altor-vec

Bring your FAISS index to the browser. Guide for JavaScript developers replacing Python/C++ FAISS with altor-vec's browser-native WASM HNSW — no Python required, no native compilation.

When migration makes sense

• You need HNSW-quality vector search in a browser or Node.js environment where FAISS cannot run
• Your JavaScript/TypeScript team doesn't want a Python dependency in the search path
• You want to ship search as part of a static web app with no server infrastructure

What you give up

Migration is not always the right call. altor-vec cannot replace FAISS for:

• Billion-scale capacity: FAISS handles hundreds of millions to billions of vectors with IVF and PQ compression; altor-vec is designed for up to ~100K vectors in-browser
• GPU acceleration: FAISS-GPU is a significant throughput multiplier for large batch queries; WASM has no GPU access
• IVF/PQ index types: FAISS offers multiple index types for different memory/speed/recall tradeoffs; altor-vec implements HNSW only

Step-by-step migration

# 1. Export vectors from FAISS (Python)
import faiss
import numpy as np
import json

# Load your existing FAISS index
index = faiss.read_index('your-index.faiss')
print(f"Index: {index.ntotal} vectors, d={index.d}")

# Reconstruct all vectors
vectors = np.zeros((index.ntotal, index.d), dtype=np.float32)
index.reconstruct_n(0, index.ntotal, vectors)

# Save as binary (most efficient for transfer)
vectors.tofile('vectors.bin')

# Save metadata separately
with open('metadata.json', 'w') as f:
    json.dump(your_metadata_list, f)  # list of {id, title, url, etc.}

print(f"Exported {index.ntotal} vectors ({vectors.nbytes // 1024 // 1024}MB)")

# In Node.js: build altor-vec index
import init, { WasmSearchEngine } from 'altor-vec';
import { readFileSync, writeFileSync } from 'fs';
await init();

const DIM = 384; // match your FAISS index dimension
const buffer = readFileSync('vectors.bin');
const vectors = new Float32Array(buffer.buffer, buffer.byteOffset, buffer.length / 4);

const engine = WasmSearchEngine.from_vectors(vectors, DIM, 16, 200, 50);
writeFileSync('public/search-index.json', engine.to_json());
console.log(`altor-vec index ready: ${vectors.length / DIM} vectors`);

After migration

Once your index is built and deployed to public/search-index.json, load it in the browser:

import init, { WasmSearchEngine } from 'altor-vec';
import { pipeline } from '@xenova/transformers';

await init();
const embedder = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
const resp = await fetch('/search-index.json');
const engine = WasmSearchEngine.from_json(await resp.text());

async function search(query, k = 5) {
  const out = await embedder(query, { pooling: 'mean', normalize: true });
  const hits = JSON.parse(engine.search(new Float32Array(out.data), k));
  return hits; // [{id, score}] - map id back to your metadata
}

Frequently asked questions

Is FAISS available in JavaScript natively?

No. FAISS is a C++ library with Python bindings. There is no official JavaScript port. The closest browser-native equivalent is altor-vec, which implements the HNSW algorithm (also available in FAISS as IndexHNSWFlat) as a 54KB WASM binary.

How does altor-vec's WASM compare to FAISS performance?

Native FAISS C++ is 3-5x faster than altor-vec WASM for raw throughput. However, altor-vec eliminates network latency entirely — a 0.8ms WASM query beats a 0.2ms FAISS query + 30ms network round-trip for user-facing search. For batch offline processing, FAISS wins; for interactive browser search, altor-vec wins.

Can I use altor-vec without Python for AI applications?

Yes. altor-vec is pure JavaScript/TypeScript with no Python dependency. Use Transformers.js (npm install @xenova/transformers) for browser-side embeddings with the same models available in Python (all-MiniLM-L6-v2, nomic-embed-text, etc.).

How do I migrate from FAISS IndexFlatL2 to altor-vec?

altor-vec uses cosine similarity by default. If you were using FAISS IndexFlatL2 (Euclidean distance), normalize your vectors before indexing with altor-vec to get equivalent cosine similarity results. Use numpy.linalg.norm to normalize vectors before exporting.