A pure Go implementation of Facebook's FAISS (Facebook AI Similarity Search) library for efficient similarity search and clustering of dense vectors.

• Multiple Index Types

  • FlatIndex: Exact brute-force search
  • IVFIndex: Inverted File Index with clustering
  • IVFPQIndex: IVF + Product Quantization (memory efficient)
  • HNSWIndex: Hierarchical Navigable Small World graphs (fastest)

• Distance Metrics

  • L2 (Euclidean distance)
  • Cosine similarity
  • Inner product

• Persistence

  • Save/Load indexes with gzip compression
  • Gob and JSON serialization support

• Benchmarking

  • Built-in ANN benchmarking framework
  • Recall@K, QPS, latency measurements
  • Synthetic dataset generation

go get github.com/tahcohcat/gofaiss

docker pull ghcr.io/tahcohcat/gofaiss:latest
# Or build locally
docker build -t gofaiss:latest .

See the Docker Guide for detailed usage.

package main

import (
    "github.com/tahcohcat/gofaiss/pkg/index/hnsw"
    "github.com/tahcohcat/gofaiss/pkg/vector"
)

func main() {
    // Create HNSW index
    idx, _ := hnsw.New(128, "l2", hnsw.Config{
        M:              16,
        EfConstruction: 200,
    })

    // Add vectors
    vectors := []vector.Vector{
        {ID: 1, Data: make([]float32, 128)},
        {ID: 2, Data: make([]float32, 128)},
    }
    idx.Add(vectors)

    // Search
    query := make([]float32, 128)
    results, _ := idx.Search(query, 10)
    
    // Save index
    idx.SaveToFile("index.faiss.gz")
}

gofaiss/
├── pkg/
│   ├── metric/       # Distance metrics
│   ├── index/        # Index implementations
│   ├── vector/       # Vector utilities
│   ├── storage/      # Serialization
│   └── search/       # Search API
├── internal/
│   ├── math/         # Low-level math
│   ├── storage/      # Internal storage
│   └── utils/        # Helpers
├── cmd/
│   ├── gofaiss-cli/     # CLI tool
│   └── gofaiss-server/  # Server
└── examples/         # Examples

• Getting Started - Installation, quick start, and usage examples
• API Reference - Complete API documentation for all packages
• Architecture - Design and implementation details
• Benchmarks - Performance comparisons and metrics
• Roadmap - Future plans and features
• Demo - Foodpanda HNSW dataset search

Dataset: 100K vectors, 128 dimensions

*Recall can be improved by tuning nprobe parameter (see benchmarks)

See detailed benchmarks for more results, scaling analysis, and tuning guidelines.

See the examples directory for more detailed usage examples.