Go • HTTP + gRPC • Vector DB

Suba ingest em lote e busca vetorial com APIs HTTP e gRPC em Go

LumenVec entrega um caminho direto para indexar embeddings, consultar por similaridade e operar localmente com snapshot+WAL ou payload em disco, cache configurável, métricas Prometheus e controles de segurança para deploy autenticado.

Ideal para pipelines batch, busca semântica e serviços internos que precisam de uma base vetorial leve, previsível e fácil de integrar por HTTP ou gRPC.

Abrir quickstart Explorar no GitHub

HTTP 19190 • gRPC 19191 • /health • /metrics • um transporte por processo

HTTP e gRPC Exponha operações de upsert, get, delete, search e batch no transporte que faz sentido para o processo atual.

Persistência e cache Rode com snapshot+WAL ou payload em disco, com cache em memória configurável para hot vectors.

Busca e controle Escolha entre exact e ANN e ative autenticação, TLS e limites operacionais conforme o ambiente.

Rodar com Docker

docker build -t lumenvec:latest .

docker run --rm -p 19190:19190 -p 19191:19191 \
  -v "$(pwd)/data:/data" lumenvec:latest

Exemplo (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}'

Prova de valor

Onde LumenVec encaixa melhor

A proposta aqui é resolver o essencial de ingest e busca vetorial com transportes HTTP ou gRPC, operação previsível e menos atrito para subir em ambientes próprios.

Busca semântica e RAG

Indexe embeddings e consulte similaridade para experiências de busca, copilots e fluxos de recuperação contextual com integração por HTTP ou gRPC.

Pipelines batch e reindexação

Carregue lotes, reprocesse coleções e rode ingestões recorrentes com operações batch, persistência local e modos exact/ANN.

Serviços self-hosted

Use em ferramentas internas e serviços privados com métricas, autenticação por API key, TLS, rate limiting por IP e controles de proxy confiável.

Recursos

Tudo o que você precisa para armazenar e consultar embeddings com foco em lote, transporte explícito e operação simples.

APIs HTTP e gRPC

Endpoints e métodos para upsert/get/delete/search e operações batch, com seleção explícita de transporte por processo.

Exact + ANN

Escolha entre busca exata e aproximada via search.mode e perfis ANN configuráveis.

Persistência local

Use snapshot + WAL ou payload em disco, com reconstrução de estado no startup conforme o backend escolhido.

Observabilidade e segurança

Prometheus em /metrics, API key no HTTP e gRPC, TLS, rate limiting por IP e trusted proxies.

Limites e cache configuráveis

Dimensão, payload, top-k e cache em memória com TTL e limites por bytes/itens.

Cliente Go

Cliente e exemplos em Go para fluxos HTTP e gRPC no repositório.

Como funciona

O processo sobe em HTTP ou gRPC, conforme server.protocol.
O servidor roteia operações para o índice exact/ANN, cache opcional e backend de persistência.
A durabilidade usa snapshot + WAL ou payload em disco, com recuperação no startup.

Ler arquitetura Ler design

Defaults de configuração

server:
  protocol: http
  port: 19190
  rate_limit_rps: 100

grpc:
  port: 19191

security:
  profile: production
  auth:
    enabled: true
    grpc_enabled: true
  transport:
    tls_enabled: true

Fonte: configs/config.yaml e configs/config.grpc.yaml.

Quickstart

Rodar com Go

go mod tidy

go run ./cmd/server

HTTP em http://localhost:19190; gRPC em localhost:19191 quando server.protocol=grpc.

Rodar com Docker Compose

Docker Compose

docker compose up --build

Publica 19190, expõe 19191 para gRPC, inclui Prometheus/Grafana e persiste em ./data.

API (exemplos)

/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}]}'

A página mostra exemplos HTTP, mas o produto também oferece gRPC com seleção explícita de transporte por processo.

Exemplo (Go client)

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)
}

Fonte: examples/ingest_example.go.

Qualidade

Cobertura em CI

Workflow com enforcement de cobertura, validação de race e testes para fluxos HTTP, gRPC, cache e persistência.

Ver CHANGELOG

Licença MIT

Uso livre para projetos comerciais e open-source.

Ler licença

Issues