zvec: run vector search inside your app, no server, offline

The Stack

Steps

1. 1

   Install zvec and run an in-process insert + query

   pip install zvec, then create a collection on a fresh path, insert two vectors, and query for the nearest neighbor. There is no server: the database lives in your process. CI runs exactly this and checks the query returns the expected nearest neighbor.

   python3 -m venv .venv
   .venv/bin/pip install -q zvec
   .venv/bin/python - <<'EOF'
   import zvec, tempfile, os
   
   schema = zvec.CollectionSchema(
       name="example",
       vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 4),
   )
   path = os.path.join(tempfile.mkdtemp(), "zvec_example")
   collection = zvec.create_and_open(path=path, schema=schema)
   
   collection.insert([
       zvec.Doc(id="doc_1", vectors={"embedding": [0.1, 0.2, 0.3, 0.4]}),
       zvec.Doc(id="doc_2", vectors={"embedding": [0.2, 0.3, 0.4, 0.1]}),
   ])
   
   results = collection.query(
       zvec.VectorQuery("embedding", vector=[0.4, 0.3, 0.3, 0.1]),
       topk=10,
   )
   ids = [r.id for r in results]
   assert len(ids) == 2, "expected 2 results, got " + str(len(ids))
   assert ids[0] == "doc_2", "nearest neighbor should be doc_2, got " + str(ids[0])
   print("zvec OK: in-process vector search returned 2 result(s) offline, no server; nearest neighbor is doc_2")
   EOF

2. 2

   Point it at your own embeddings (the retrieval step, not checked by CI)

   Swap the toy vectors for real embeddings from your model, use hybrid queries (vector plus structured filters) if you need them, and persist the collection dir so it survives restarts. What you retrieve on real data is fenced.