How phanindra798/fastvec works
fastvec is a Go vector-similarity search engine with exact flat search and an approximate, layered HNSW index. Its main workflow reads vector data, builds or loads an index, searches queries, and measures recall and throughput against ground truth. The repository also provides dataset-subsetting support and a benchmark comparison workflow. Sampled source confirms the benchmark runner’s orchestration and core HNSW search behavior; some lower-level index and persistence wiring is represented only where documented or directly supported by the tree.
Main entry points: fastvec-bench/main.go Benchmark runner · hnsw.go HNSW index · fastvec-subset/main.go Subset generator · flat.go Exact search
Components 18
Vector data
- Subset generator
cmd/fastvec-subset/main.go - Vector parser
internal/fvecs/fvecs.go - Ground truth
internal/fvecs/fvecs.go
Search index
- Exact search
internal/index/flat.go - HNSW index
internal/index/hnsw.go - Index persistence
internal/index/store.go
Search internals
- Search workspace
internal/index/workspace.go - Candidate search
internal/index/candidates.go - Distance kernels
internal/distance/distance.go - Top-k ranking
internal/topk/topk.go
Benchmarking
- Benchmark runner
cmd/fastvec-bench/main.go - Machine metadata
internal/benchenv/benchenv.go - Benchmark results
bench/results - hnswlib baseline
py/bench_baselines.py - Recall/QPS plots
py/plots.py
Other components
- Engineer
- SIFT/GIST files
- hnswlib
Connections 27
- Engineer → Benchmark runner: runs benchmark
- SIFT/GIST files → Vector parser: vector files
- SIFT/GIST files → Ground truth: ground truth file
- Benchmark runner → Vector parser: reads vectors
- Benchmark runner → Ground truth: reads truth
- Benchmark runner → Index persistence: loads index
- Benchmark runner → HNSW index: builds index
- HNSW index → Index persistence: saves index
- Benchmark runner → HNSW index: searches queries
- HNSW index → Search workspace: uses scratch
- HNSW index → Candidate search: searches layers
- HNSW index → Distance kernels: measures vectors
- HNSW index → Top-k ranking: ranks candidates
- Benchmark runner → Distance kernels: scores recall
- Benchmark runner → Top-k ranking: uses results
- Benchmark runner → Machine metadata: captures environment
- Benchmark runner → Benchmark results: writes JSON
- Engineer → Subset generator: prepares subset
- Subset generator → Vector parser: reads vectors
- Subset generator → Exact search: computes exact neighbors
- Exact search → Distance kernels: measures vectors
- Exact search → Top-k ranking: ranks results
- Engineer → hnswlib baseline: runs baseline
- hnswlib baseline → hnswlib: benchmarks
- hnswlib baseline → Benchmark results: writes JSON
- Benchmark results → Recall/QPS plots: loads sweeps
- Recall/QPS plots → Engineer: renders comparison