0923f7c691
* refactor: make Reranker stateless with std::variant value semantics (#461) Replace class hierarchy (Reranker/ScoreBasedReranker/RrfReranker/ WeightedReranker/CallbackReranker) with std::variant<RrfParams, WeightedParams, CallbackParams> value type and a stateless free function reranker::rerank(). Key changes: - reranker.h: define RerankParams variant + reranker::rerank() API - query.h: MultiQuery::reranker (shared_ptr) -> MultiQuery::rerank (value) - schema.h: add CollectionSchema::get_field_ptr() returning FieldSchema::Ptr - collection.cc: push field lookup to caller, pass vector<FieldSchema::Ptr> - c_api: remove opaque zvec_reranker_t, add zvec_multi_query_set_rerank_* - python binding: expose _RrfParams/_WeightedParams/_CallbackParams + setters - python layer: WeightedReRanker(list[float]), remove Python rerank logic - all tests updated to new interface Benefits: - Thread-safe by design: no mutable state, safe to share across threads - Collection-decoupled: no bind_schema(), field info passed as parameter - Simpler lifecycle: value semantics, no shared_ptr management Closes #461 * chore: remove nightly_build.yml unrelated to reranker refactor * chore: remove uv.lock unrelated to reranker refactor * fix: raise ValueError when multi-query has no reranker After the reranker stateless refactor the C++ MultiQuery rerank strategy uses a std::variant with a default value, so the implicit 'reranker required' validation no longer triggered. Restore the check in QueryExecutor._execute_multi_query so that a hybrid (multi-query) request without a reranker raises ValueError. * fix(reranker): use index_type FTS check for non-vector normalization Replace dynamic_cast nullptr check with explicit IndexType::FTS check and map FTS/BM25 positive scores to (0.0, 1.0) via 2*atan(score)/pi. * refactor(reranker): move Params types into reranker namespace and qualify usages Move RrfParams, WeightedParams, CallbackParams and RerankParams into the zvec::reranker namespace, and add explicit reranker:: qualification at all usage sites outside the reranker module (query.h, python/c bindings, tests). * refactor(query): drop unused PendingQuery wrapper, use std::vector<SearchQuery> directly * refactor(reranker): make _to_cpp_params non-abstract with default NotImplementedError Remove @abstractmethod from RerankFunction._to_cpp_params and provide a default implementation raising NotImplementedError. Drop the redundant _to_cpp_params overrides from Qwen and Sentence rerankers since they use the Python rerank path and don't need the C++ conversion. |
||
|---|---|---|
| .github | ||
| cmake | ||
| examples | ||
| python | ||
| scripts | ||
| src | ||
| tests | ||
| thirdparty | ||
| tools | ||
| .clang-format | ||
| .clang-tidy | ||
| .gitattributes | ||
| .gitignore | ||
| .gitmodules | ||
| .pre-commit-config.yaml | ||
| CMakeLists.txt | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| NOTICE | ||
| README.md | ||
| README_CN.md | ||
| pyproject.toml | ||
README.md
English | 中文
🚀 Quickstart | 🏠 Home | 📚 Docs | 📊 Benchmarks | 🔎 DeepWiki | 🎮 Discord | 🐦 X (Twitter)
Zvec is an open-source, in-process vector database — lightweight, lightning-fast, and designed to embed directly into applications. Battle-tested within Alibaba Group, it delivers production-grade, low-latency and scalable similarity search with minimal setup.
[!Important] 🚀 v0.4.0 (May 9, 2026)
- Dart/Flutter SDK: Published the official zvec Flutter package with FFI bindings. Supports Android (arm64-v8a) and iOS (arm64) — no manual native compilation required.
- iOS Build Support: Added support for building on iOS platforms, expanding cross-platform coverage.
- Enlarged topK Limit: Relaxed the upper bound on topK to support larger-scale recall scenarios.
- Bug Fixes: SQ8 quantizer recall drop; Windows path handling; sparse vector index ordering.
💫 Features
- Blazing Fast: Searches billions of vectors in milliseconds.
- Simple, Just Works: Install and start searching in seconds. Pure local, no servers, no config, no fuss.
- Dense + Sparse Vectors: Work with both dense and sparse embeddings, with native support for multi-vector queries in a single call.
- Hybrid Search: Combine semantic similarity with structured filters for precise results.
- Durable Storage: Write-ahead logging (WAL) guarantees persistence — data is never lost, even on process crash or power failure.
- Concurrent Access: Multiple processes can read the same collection simultaneously; writes are single-process exclusive.
- Runs Anywhere: As an in-process library, Zvec runs wherever your code runs — notebooks, servers, CLI tools, or even edge devices.
📦 Installation
Python
Requirements: Python 3.10 - 3.14
pip install zvec
Node.js
npm install @zvec/zvec
✅ Supported Platforms
- Linux (x86_64, ARM64)
- macOS (ARM64)
- Windows (x86_64)
🛠️ Building from Source
If you prefer to build Zvec from source, please check the Building from Source guide.
⚡ One-Minute Example
import zvec
# Define collection schema
schema = zvec.CollectionSchema(
name="example",
vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 4),
)
# Create collection
collection = zvec.create_and_open(path="./zvec_example", schema=schema)
# Insert documents
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]}),
])
# Search by vector similarity
results = collection.query(
zvec.VectorQuery("embedding", vector=[0.4, 0.3, 0.3, 0.1]),
topk=10
)
# Results: list of {'id': str, 'score': float, ...}, sorted by relevance
print(results)
📈 Performance at Scale
Zvec delivers exceptional speed and efficiency, making it ideal for demanding production workloads.
For detailed benchmark methodology, configurations, and complete results, please see our Benchmarks documentation.
🤝 Join Our Community
| 💬 DingTalk | 🎮 Discord | X (Twitter) | |
|---|---|---|---|
 |
 |
 |
 |
| Scan to join | Scan to join | Click to join | Click to follow |
❤️ Contributing
We welcome and appreciate contributions from the community! Whether you're fixing a bug, adding a feature, or improving documentation, your help makes Zvec better for everyone.
Check out our Contributing Guide to get started!