Skip to main content

Configuration

Altor Vec exposes a focused set of configuration options because approximate nearest-neighbor search quality depends heavily on the structure of the index. The most important settings are the HNSW graph parameters m, ef_construction, and ef_search. They control how many links each node maintains, how much work the engine performs while building the graph, and how broadly the graph is explored during querying. Small changes in these values can produce meaningful differences in recall, latency, and peak memory usage.

Treat configuration as an empirical exercise rather than a one-time guess. The best values for a documentation corpus with short chunks are often different from those for product catalogs, code search, or multimodal embeddings. Establish a baseline dataset and run repeated evaluations before standardizing on a production profile.

HNSW Parameters​

m controls the maximum number of outgoing connections per node. Higher values generally improve graph quality and recall, but they also increase memory consumption. For many text-search workloads, m values between 12 and 32 are a sensible starting range.

ef_construction controls how much search effort is spent when inserting items into the graph. A larger value typically produces a better-connected index, which improves later query quality, but indexing takes longer.

ef_search affects query-time exploration. If your results look unstable or low recall is hurting relevance, increasing ef_search is often the first adjustment to try.

const engine = await WasmSearchEngine.create({
  dimensions: 384,
  m: 16,
  efConstruction: 128,
});

const results = await engine.search(queryVector, {
  limit: 5,
  efSearch: 80,
});

Choosing Defaults​

For interactive search, start with moderate settings and measure. A common pattern is m = 16, ef_construction = 100–200, and ef_search = 40–100. If your corpus is small, you can afford larger search values without noticeable user impact. If your corpus is large or runs in a constrained browser tab, lower graph density may be the better trade-off.

Also remember that configuration does not replace good data preparation. Poor chunk boundaries, duplicate records, inconsistent metadata, or noisy embeddings can overwhelm the benefits of fine-tuned HNSW parameters. Tune the index, but keep evaluating the content pipeline that feeds it.