Semantic search and RAG
Index embeddings and query similarity for search experiences, copilots, and contextual retrieval flows with HTTP or gRPC integration.
Go • HTTP + gRPC • Vector DB
Run batch ingest and vector search with HTTP and gRPC APIs in Go
LumenVec gives you a direct path to index embeddings, query similarity, and operate locally with snapshot+WAL or disk-backed payloads, configurable cache, Prometheus metrics, and security controls for authenticated deployments.
Ideal for batch pipelines, semantic search, and internal services that need a lightweight, predictable vector layer that integrates over HTTP or gRPC.
HTTP and gRPC
Expose upsert, get, delete, search, and batch operations through the transport that fits the current process.
Durability and cache
Run with snapshot+WAL or disk-backed payloads, with a configurable in-memory cache for hot vectors.
Search and control
Choose exact or ANN and enable auth, TLS, and operational limits to match the environment.
Run with Docker
docker build -t lumenvec:latest .
docker run --rm -p 19190:19190 -p 19191:19191 \
-v "$(pwd)/data:/data" lumenvec:latest
Example (HTTP)
curl -s http://localhost:19190/health
curl -s -X POST http://localhost:19190/vectors/search \
-H "Content-Type: application/json" \
-d '{"values":[1,2,3.1],"k":2}'Proof of value
Where LumenVec fits best
The goal here is to cover the essentials of ingest and vector search with HTTP or gRPC transports, predictable operations, and less friction for self-hosted environments.
Batch pipelines and reindexing
Load batches, reprocess collections, and run recurring ingest jobs with batch operations, local durability, and exact/ANN modes.
Self-hosted services
Use it in internal tools and private services with metrics, API key auth, TLS, IP rate limiting, and trusted proxy controls.
Features
Everything you need to store and query embeddings with a focus on batch workflows, explicit transport selection, and simple ops.
HTTP and gRPC APIs
Endpoints and methods for upsert/get/delete/search and batch operations, with explicit transport selection per process.
Exact + ANN
Pick exact or approximate search via search.mode and configurable ANN profiles.
Local persistence
Use snapshot + WAL or disk-backed payloads, with startup rebuild based on the selected backend.
Observability and security
Prometheus at /metrics, API key auth on HTTP and gRPC, TLS, IP rate limiting, and trusted proxies.
Configurable limits and cache
Dimension, payload, top-k, and in-memory cache with TTL plus byte/item limits.
Go client
Go client and examples for HTTP and gRPC flows in the repository.
How it works
- The process starts in HTTP or gRPC mode, according to server.protocol.
- The server routes operations to the exact/ANN index, optional cache, and persistence backend.
- Durability uses snapshot + WAL or disk-backed payloads, with recovery on startup.
Config defaults
server:
protocol: http
port: 19190
rate_limit_rps: 100
grpc:
port: 19191
security:
profile: production
auth:
enabled: true
grpc_enabled: true
transport:
tls_enabled: trueSource: configs/config.yaml and configs/config.grpc.yaml.
Quickstart
Run with Go
Go
go mod tidy
go run ./cmd/serverHTTP at http://localhost:19190; gRPC at localhost:19191 when server.protocol=grpc.
Run with Docker Compose
Docker Compose
docker compose up --buildPublishes 19190, exposes 19191 for gRPC, includes Prometheus/Grafana, and persists to ./data.
API (examples)
/vectors
# criar/upsert
curl -X POST http://localhost:19190/vectors \
-H "Content-Type: application/json" \
-d '{"id":"doc-1","values":[1,2,3]}'
# obter
curl http://localhost:19190/vectors/doc-1
# deletar
curl -X DELETE http://localhost:19190/vectors/doc-1
/vectors/search
curl -X POST http://localhost:19190/vectors/search \
-H "Content-Type: application/json" \
-d '{"values":[1,2,3.1],"k":2}'
# batch search
curl -X POST http://localhost:19190/vectors/search/batch \
-H "Content-Type: application/json" \
-d '{"queries":[{"id":"q1","values":[1,2,3],"k":2}]}'This page shows HTTP examples, but the product also provides gRPC with explicit per-process transport selection.
Example (Go client)
Go
c := client.NewVectorClient("http://localhost:19190")
items := map[string][]float64{
"doc-1": {1, 2, 3},
"doc-2": {1.1, 2.1, 2.9},
"doc-3": {9, 8.5, 7.5},
}
for id, vec := range items {
if err := c.AddVectorWithID(id, vec); err != nil { return err }
}
hits, err := c.SearchVector([]float64{1, 2, 3.1}, 2)
if err != nil { return err }
for _, h := range hits {
fmt.Printf("%s %.4f\n", h.ID, h.Distance)
}Source: examples/ingest_example.go.
Quality
CI coverage
Workflow with coverage enforcement, race validation, and tests for HTTP, gRPC, cache, and persistence flows.
View CHANGELOG