feat: migrate multi-vector query and reranker logic to C++ (#405)
* feat: migrate multi-vector query and reranker logic to C++ - Add Reranker base class with RrfReRanker and WeightedReRanker implementations - Add Collection::MultiQuery interface for multi-vector queries with reranking - Add MultiVectorQuery struct in doc.h with forward declaration for Reranker - Add C API bindings for reranker and MultiQuery (zvec_reranker_*, zvec_multi_vector_query_*, zvec_collection_multi_query) - Add Python binding for reranker classes with py::function bridge for callback - Validate duplicate field names in multi-vector queries (C++ and Python consistent) - Remove TODO comment about concurrent execution (SQLEngine is not thread-safe) - Update collection.h MultiQuery doc comment from concurrently to sequentially - Add C++ collection tests (6 MultiQuery test cases) - Add C API tests (reranker functions + multi_vector_query end-to-end) - Implement Python test cases (11 previously skipped tests now active) - Simplify Python query_executor validation for unified duplicate field check * style: format Python files with ruff * fix: adapt to main branch API changes (VectorQuery->Query rename, validate_and_sanitize) * fix: multi_vector tests now use multiple same-type vector fields (dense2, sparse2) * fix: suppress RET501 for intentional default return None in RerankFunction._get_object * style: ruff format test_collection.py * refact multi vector query * format code * fix(multi-vector): expose SubVectorQuery in Python binding, fix tests - Register _SubVectorQuery in pybind11 with from_vector_query() factory - Convert _VectorQuery to _SubVectorQuery in MultiVectorQueryExecutor - Relax RRF/Weighted score assertion tolerance from 1e-10 to 1e-6 - Fix WeightedReRanker test metric to IP (matching HnswIndexParam default) * style: ruff format query_executor.py * fix: define _USE_MATH_DEFINES for M_PI on Windows (MSVC) * refactor: include reranker.h directly in query.h instead of forward declaration * refactor(reranker): move topn from member variable to rerank() parameter * refact code * style(python): fix ruff UP035/UP037 in multi_vector_reranker - import Callable from collections.abc instead of typing (UP035) - remove redundant quotes around MetricType annotations (UP037) * chore: trigger PR sync * refact code * fix(examples): restore CMakeLists.txt formatting broken by clang-format * refactor(reranker): remove redundant metrics_ map by querying schema directly, and use insert return value to avoid duplicate set lookup * refactor(reranker): defer schema binding to query time and remove C API callback reranker
This commit is contained in:
@@ -19,8 +19,8 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
|
||||
from typing import Optional, Union, final
|
||||
|
||||
import numpy as np
|
||||
from _zvec import _Collection
|
||||
from _zvec.param import _VectorQuery
|
||||
from _zvec import _Collection, _MultiQuery
|
||||
from _zvec.param import _SubQuery, _VectorQuery
|
||||
|
||||
from ..extension import ReRanker, RrfReRanker, WeightedReRanker
|
||||
from ..model.convert import convert_to_py_doc
|
||||
@@ -290,11 +290,44 @@ class MultiVectorQueryExecutor(SingleVectorQueryExecutor):
|
||||
raise ValueError(f"Query field name '{field}' appears more than once")
|
||||
seen_fields.add(field)
|
||||
|
||||
def execute(self, ctx: QueryContext, collection: _Collection) -> list[Doc]:
|
||||
# 1. validate query
|
||||
self._do_validate(ctx)
|
||||
# 2. build query vectors
|
||||
query_vectors = self._do_build(ctx, collection)
|
||||
if not query_vectors:
|
||||
raise ValueError("No query to execute")
|
||||
|
||||
# Fast path: use C++ MultiQuery for multi-vector with C++ reranker
|
||||
if len(query_vectors) > 1 and ctx.reranker is not None:
|
||||
cpp_reranker = ctx.reranker._get_object()
|
||||
if cpp_reranker is not None:
|
||||
mvq = _MultiQuery()
|
||||
mvq.queries = [self._to_sub_query(vq) for vq in query_vectors]
|
||||
mvq.topk = ctx.topk
|
||||
if ctx.filter:
|
||||
mvq.filter = ctx.filter
|
||||
mvq.include_vector = ctx.include_vector
|
||||
if ctx.output_fields:
|
||||
mvq.output_fields = ctx.output_fields
|
||||
mvq.reranker = cpp_reranker
|
||||
docs = collection.Query(mvq)
|
||||
return [convert_to_py_doc(doc, self._schema) for doc in docs]
|
||||
|
||||
# 3. execute query (fallback to Python path)
|
||||
docs = self._do_execute(query_vectors, collection)
|
||||
# 4. merge and rerank result
|
||||
return self._do_merge_rerank_results(ctx, docs)
|
||||
|
||||
def _do_execute(
|
||||
self, vectors: list[_VectorQuery], collection: _Collection
|
||||
) -> dict[str, list[Doc]]:
|
||||
return super()._do_execute(vectors, collection)
|
||||
|
||||
@staticmethod
|
||||
def _to_sub_query(vq: _VectorQuery) -> _SubQuery:
|
||||
return _SubQuery.from_vector_query(vq)
|
||||
|
||||
|
||||
class QueryExecutorFactory:
|
||||
@staticmethod
|
||||
|
||||
@@ -18,7 +18,7 @@ from .embedding_function import DenseEmbeddingFunction, SparseEmbeddingFunction
|
||||
from .http_embedding_function import HTTPDenseEmbedding
|
||||
from .jina_embedding_function import JinaDenseEmbedding
|
||||
from .jina_function import JinaFunctionBase
|
||||
from .multi_vector_reranker import RrfReRanker, WeightedReRanker
|
||||
from .multi_vector_reranker import CallbackReRanker, RrfReRanker, WeightedReRanker
|
||||
from .openai_embedding_function import OpenAIDenseEmbedding
|
||||
from .openai_function import OpenAIFunctionBase
|
||||
from .qwen_embedding_function import QwenDenseEmbedding, QwenSparseEmbedding
|
||||
@@ -34,6 +34,7 @@ from .sentence_transformer_rerank_function import DefaultLocalReRanker
|
||||
|
||||
__all__ = [
|
||||
"BM25EmbeddingFunction",
|
||||
"CallbackReRanker",
|
||||
"DefaultLocalDenseEmbedding",
|
||||
"DefaultLocalReRanker",
|
||||
"DefaultLocalSparseEmbedding",
|
||||
|
||||
@@ -16,8 +16,11 @@ from __future__ import annotations
|
||||
import heapq
|
||||
import math
|
||||
from collections import defaultdict
|
||||
from collections.abc import Callable
|
||||
from typing import Optional
|
||||
|
||||
from _zvec import _CallbackReranker, _RrfReranker, _WeightedReranker
|
||||
|
||||
from ..model.doc import Doc
|
||||
from ..typing import MetricType
|
||||
from .rerank_function import RerankFunction
|
||||
@@ -51,11 +54,17 @@ class RrfReRanker(RerankFunction):
|
||||
):
|
||||
super().__init__(topn=topn, rerank_field=rerank_field)
|
||||
self._rank_constant = rank_constant
|
||||
# Use C++ implementation for performance
|
||||
self._cpp_reranker = _RrfReranker(rank_constant)
|
||||
|
||||
@property
|
||||
def rank_constant(self) -> int:
|
||||
return self._rank_constant
|
||||
|
||||
def _get_object(self):
|
||||
"""Return the underlying C++ RrfReranker instance."""
|
||||
return self._cpp_reranker
|
||||
|
||||
def _rrf_score(self, rank: int) -> float:
|
||||
return 1.0 / (self._rank_constant + rank + 1)
|
||||
|
||||
@@ -91,8 +100,9 @@ class RrfReRanker(RerankFunction):
|
||||
class WeightedReRanker(RerankFunction):
|
||||
"""Re-ranker that combines scores from multiple vector fields using weights.
|
||||
|
||||
Each vector field's relevance score is normalized based on its metric type,
|
||||
then scaled by a user-provided weight. Final scores are summed across fields.
|
||||
Each vector field's relevance score is normalized based on its own metric
|
||||
type, then scaled by a user-provided weight. Final scores are summed across
|
||||
fields.
|
||||
|
||||
Note:
|
||||
This re-ranker is specifically designed for multi-vector scenarios where
|
||||
@@ -102,8 +112,10 @@ class WeightedReRanker(RerankFunction):
|
||||
Args:
|
||||
topn (int, optional): Number of top documents to return. Defaults to 10.
|
||||
rerank_field (Optional[str], optional): Ignored. Defaults to None.
|
||||
metric (MetricType, optional): Distance metric used for score normalization.
|
||||
Defaults to ``MetricType.L2``.
|
||||
metrics (Optional[dict[str, MetricType]], optional): Per-field distance
|
||||
metric used for score normalization. Every queried field must have
|
||||
a metric specified; missing fields will raise an error at rerank time.
|
||||
Defaults to None.
|
||||
weights (Optional[dict[str, float]], optional): Weight per vector field.
|
||||
Fields not listed use weight 1.0. Defaults to None.
|
||||
|
||||
@@ -115,12 +127,12 @@ class WeightedReRanker(RerankFunction):
|
||||
self,
|
||||
topn: int = 10,
|
||||
rerank_field: Optional[str] = None,
|
||||
metric: MetricType = MetricType.L2,
|
||||
metrics: Optional[dict[str, MetricType]] = None,
|
||||
weights: Optional[dict[str, float]] = None,
|
||||
):
|
||||
super().__init__(topn=topn, rerank_field=rerank_field)
|
||||
self._weights = weights or {}
|
||||
self._metric = metric
|
||||
self._metrics = metrics or {}
|
||||
|
||||
@property
|
||||
def weights(self) -> dict[str, float]:
|
||||
@@ -128,9 +140,13 @@ class WeightedReRanker(RerankFunction):
|
||||
return self._weights
|
||||
|
||||
@property
|
||||
def metric(self) -> MetricType:
|
||||
"""MetricType: Distance metric used for score normalization."""
|
||||
return self._metric
|
||||
def metrics(self) -> dict[str, MetricType]:
|
||||
"""dict[str, MetricType]: Per-field metric type mapping."""
|
||||
return self._metrics
|
||||
|
||||
def _get_object(self):
|
||||
"""Return a C++ WeightedReranker instance."""
|
||||
return _WeightedReranker(self._weights)
|
||||
|
||||
def rerank(self, query_results: dict[str, list[Doc]]) -> list[Doc]:
|
||||
"""Combine scores from multiple vector fields using weighted sum.
|
||||
@@ -145,10 +161,16 @@ class WeightedReRanker(RerankFunction):
|
||||
id_to_doc: dict[str, Doc] = {}
|
||||
|
||||
for vector_name, query_result in query_results.items():
|
||||
if vector_name not in self._metrics:
|
||||
raise ValueError(
|
||||
f"WeightedReRanker: no metric type specified for field "
|
||||
f"'{vector_name}'"
|
||||
)
|
||||
metric = self._metrics[vector_name]
|
||||
for _, doc in enumerate(query_result):
|
||||
doc_id = doc.id
|
||||
weighted_score = self._normalize_score(
|
||||
doc.score, self.metric
|
||||
doc.score, metric
|
||||
) * self.weights.get(vector_name, 1.0)
|
||||
weighted_scores[doc_id] += weighted_score
|
||||
if doc_id not in id_to_doc:
|
||||
@@ -172,3 +194,43 @@ class WeightedReRanker(RerankFunction):
|
||||
if metric == MetricType.COSINE:
|
||||
return 1.0 - score / 2.0
|
||||
raise ValueError("Unsupported metric type")
|
||||
|
||||
|
||||
class CallbackReRanker(RerankFunction):
|
||||
"""Re-ranker that delegates to a user-provided Python callback.
|
||||
|
||||
This bridges a Python callable into the C++ reranker interface, enabling
|
||||
custom re-ranking logic to be executed within the C++ MultiQuery path.
|
||||
|
||||
The callback receives the raw C++ Doc objects (as ``_Doc`` instances) grouped
|
||||
by vector field name, and must return a list of ``_Doc`` instances.
|
||||
|
||||
Args:
|
||||
callback: A callable with signature
|
||||
``(query_results: dict[str, list[_Doc]], topn: int) -> list[_Doc]``.
|
||||
topn (int, optional): Number of top documents to return. Defaults to 10.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
callback: Callable,
|
||||
topn: int = 10,
|
||||
):
|
||||
super().__init__(topn=topn)
|
||||
self._callback = callback
|
||||
self._cpp_reranker = _CallbackReranker(callback)
|
||||
|
||||
def _get_object(self):
|
||||
"""Return the underlying C++ CallbackReranker instance."""
|
||||
return self._cpp_reranker
|
||||
|
||||
def rerank(self, query_results: dict[str, list[Doc]]) -> list[Doc]:
|
||||
"""Invoke the callback to re-rank documents.
|
||||
|
||||
Args:
|
||||
query_results (dict[str, list[Doc]]): Results per vector field.
|
||||
|
||||
Returns:
|
||||
list[Doc]: Re-ranked documents.
|
||||
"""
|
||||
return self._callback(query_results, self.topn)
|
||||
|
||||
@@ -67,3 +67,15 @@ class RerankFunction(ABC):
|
||||
with updated ``score`` fields.
|
||||
"""
|
||||
...
|
||||
|
||||
def _get_object(self):
|
||||
"""Return the underlying C++ Reranker instance, if available.
|
||||
|
||||
This is used internally by the query executor to pass the reranker
|
||||
to the C++ MultiQuery method. Subclasses that wrap a C++ reranker
|
||||
should override this method.
|
||||
|
||||
Returns:
|
||||
The C++ Reranker shared pointer, or None if not available.
|
||||
"""
|
||||
return None # noqa: RET501
|
||||
|
||||
Reference in New Issue
Block a user