refactor: change rerank interface from map-based to vector-based (#458)
* refactor: change rerank interface from map-based to vector-based (#452) - Define QueryResult = list[Doc] type alias in doc.py - Change C++ Reranker::rerank() signature from map<string, DocPtrList> to vector<DocPtrList> - Extend bind_schema() to accept field_names for index-based field lookup - Update ScoreBasedReranker/WeightedReranker/CallbackReranker implementations - Adapt collection.cc MultiQuery path to use vector<DocPtrList> - Update Python binding to expose rerank() and use vector<double> weights - Refactor Python RerankFunction interface to list[QueryResult] -> QueryResult - Remove Python-layer rerank logic from RrfReRanker/WeightedReRanker (delegate to C++) - Update query_executor to return list[list[Doc]] instead of dict - Update all related unit tests (C++ and Python) * refactor: replace list[Doc] with QueryResult type alias in executor and rerank functions * refactor: replace list[list[Doc]] with list[QueryResult] in query_executor * fix: remove unused Doc import in rerank_function.py (ruff F401) * refactor(query_executor): merge duplicate rerank return paths * refactor: RrfReRanker/WeightedReRanker.rerank() directly call C++ reranker * refactor: simplify QueryExecutor into unified class, remove Factory/subclasses/validation/concurrency * refactor: rename _VectorQuery to _SearchQuery, from_vector_query to from_search_query * refactor(query_executor): split execute into single/multi paths, rename core_vector to search_query, drop unused core_vectors * style: apply ruff formatter to test_reranker.py and query_executor.py * refactor: make rescore() private in ScoreBasedReranker hierarchy * style: apply clang-format to reranker.h * style: apply clang-format to all modified C++ files * refactor: rename private methods in QueryExecutor for clearer semantics * refactor: rename mvq to multi_query for clarity * fix: make BasicRRF test order-independent for equal scores * fix: update collection_test to use vector-based reranker interface * fix: update reranker tests to expect TypeError instead of NotImplementedError * refactor: remove PendingQuery wrapper, use SearchQuery directly in MultiQuery path * refactor: simplify MultiQuery path - remove seen_fields, merge field_names into main loop * fix: address review comments - defensive checks and remove fields param from C API - ScoreBasedReranker::rerank(): early return empty list when topn <= 0 - WeightedReranker::rescore(): null-check schema_ before use - CallbackReranker::rerank(): check callback_ is not empty before invoke - C API zvec_reranker_create_weighted(): remove unused fields parameter * fix: remove duplicate field name test (check was intentionally removed) * fix: address egolearner review comments - Rename QueryResult to DocList for clarity (见名知义) - Change docstring to #: comment for type alias - Fix output_fields check: use 'is not None' instead of truthy check (None means unset, [] means explicit empty list - different semantics) - Raise ValueError when search-by-id finds no document * refactor: remove redundant output_fields assignment in _build_search_query * refactor: address egolearner review comments (C++ refactoring) - c_api.cc: simplify weighted reranker creation with inline vector ctor - python_reranker.cc: refactor unwrap_rerank_result - take by value, early error return, move semantics - Rename C API functions for consistent naming: zvec_reranker_create_rrf -> zvec_create_rrf_reranker zvec_reranker_create_weighted -> zvec_create_weighted_reranker zvec_reranker_destroy -> zvec_destroy_reranker zvec_reranker_get_rank_constant -> zvec_get_reranker_rank_constant - reranker.h/cc: bind_schema returns Result<void>, caches vector<const FieldSchema*> to avoid repeated schema lookups in rescore - python_param.cc: rename py::arg vector_query to search_query * revert: rollback bind_schema refactoring due to thread-safety concern The field_schemas_ caching approach introduces a data race when the same WeightedReranker instance is shared across concurrent queries: bind_schema() writes field_schemas_ while rerank() reads it concurrently. Revert to storing schema_ + field_names_ and looking up fields in rescore(). Add @note thread-safety warning to WeightedReranker class documentation. * fix: unify error message format in collection.cc Change 'Vector field not found: X' to 'Invalid query: field X not found' for consistent error formatting as suggested by zhourrr. * fix: sort __all__ and remove duplicates in __init__.pyi Fix RUF022 lint error: sort __all__ alphabetically and remove duplicate entries (DenseEmbeddingFunction, ReRanker). * style: format query_executor.py with ruff formatter * fix: resolve Python test failures after FTS rebase integration - test_query_executor.py: update method names to match refactored API (_do_build -> _build_queries, _do_merge_rerank_results -> _merge_and_rerank) - test_reranker.py: fix expected exception type (TypeError from pybind11) - test_collection_fts.py: update error message match patterns - test_collection_fts_vector_hybrid.py: remove obsolete 'metrics' param, update weights from dict to positional list, adapt validation tests for multi-vector queries (now supported with reranker) - test_collection_dql.py: remove 'metrics' param, update weights format - collection.cc: distinguish FTS vs vector fields in MultiQuery path using get_fts_clause() to route field lookup correctly - reranker.cc: use get_field() instead of get_vector_field() in rescore to support FTS+vector hybrid weighted reranking * refactor: pass topn as rerank() parameter, move rerank_field to model rerankers * fix: address review comments - rename test functions and restore duplicate field check * refactor: simplify MultiQuery field lookup, let validate_and_sanitize handle type check
This commit is contained in:
@@ -71,7 +71,7 @@ from .model import schema as schema
|
||||
|
||||
# —— Core data structures ——
|
||||
from .model.collection import Collection
|
||||
from .model.doc import Doc
|
||||
from .model.doc import Doc, DocList
|
||||
|
||||
# —— Query & index parameters ——
|
||||
# —— FTS params (C++ binding) ——
|
||||
@@ -127,6 +127,7 @@ __all__ = [
|
||||
# Core classes
|
||||
"Collection",
|
||||
"Doc",
|
||||
"DocList",
|
||||
# Schema
|
||||
"CollectionSchema",
|
||||
"FieldSchema",
|
||||
|
||||
@@ -11,7 +11,7 @@ from .extension import ReRanker, RrfReRanker, WeightedReRanker
|
||||
from .extension.embedding import DenseEmbeddingFunction
|
||||
from .model import param, schema
|
||||
from .model.collection import Collection
|
||||
from .model.doc import Doc
|
||||
from .model.doc import Doc, DocList
|
||||
from .model.param import (
|
||||
AddColumnOption,
|
||||
AlterColumnOption,
|
||||
@@ -52,8 +52,8 @@ __all__: list = [
|
||||
"CollectionStats",
|
||||
"DataType",
|
||||
"DenseEmbeddingFunction",
|
||||
"DenseEmbeddingFunction",
|
||||
"Doc",
|
||||
"DocList",
|
||||
"FieldSchema",
|
||||
"FlatIndexParam",
|
||||
"HnswIndexParam",
|
||||
@@ -72,7 +72,6 @@ __all__: list = [
|
||||
"QuantizeType",
|
||||
"Query",
|
||||
"ReRanker",
|
||||
"ReRanker",
|
||||
"RrfReRanker",
|
||||
"Status",
|
||||
"StatusCode",
|
||||
@@ -127,7 +126,7 @@ class _Collection:
|
||||
def Optimize(self, arg0: param.OptimizeOption) -> None: ...
|
||||
def Options(self) -> param.CollectionOption: ...
|
||||
def Path(self) -> str: ...
|
||||
def Query(self, arg0: param._VectorQuery) -> list[_Doc]: ...
|
||||
def Query(self, arg0: param._SearchQuery) -> list[_Doc]: ...
|
||||
def Schema(self) -> schema._CollectionSchema: ...
|
||||
def Stats(self) -> schema.CollectionStats: ...
|
||||
def Update(self, arg0: collections.abc.Sequence[_Doc]) -> list[typing.Status]: ...
|
||||
|
||||
@@ -16,11 +16,9 @@ from __future__ import annotations
|
||||
from .query_executor import (
|
||||
QueryContext,
|
||||
QueryExecutor,
|
||||
QueryExecutorFactory,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"QueryContext",
|
||||
"QueryExecutor",
|
||||
"QueryExecutorFactory",
|
||||
]
|
||||
|
||||
@@ -13,18 +13,15 @@
|
||||
# limitations under the License.
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
from abc import ABC, abstractmethod
|
||||
from concurrent.futures import ThreadPoolExecutor, as_completed
|
||||
from typing import Optional, Union, final
|
||||
from typing import Optional, Union
|
||||
|
||||
import numpy as np
|
||||
from _zvec import _Collection, _MultiQuery
|
||||
from _zvec.param import _Fts, _SubQuery, _VectorQuery
|
||||
from _zvec.param import _Fts, _SearchQuery, _SubQuery
|
||||
|
||||
from ..extension import ReRanker, RrfReRanker, WeightedReRanker
|
||||
from ..extension import ReRanker
|
||||
from ..model.convert import convert_to_py_doc
|
||||
from ..model.doc import Doc
|
||||
from ..model.doc import DocList
|
||||
from ..model.param.query import Query
|
||||
from ..model.schema import CollectionSchema
|
||||
from ..typing import DataType
|
||||
@@ -32,7 +29,6 @@ from ..typing import DataType
|
||||
__all__ = [
|
||||
"QueryContext",
|
||||
"QueryExecutor",
|
||||
"QueryExecutorFactory",
|
||||
]
|
||||
|
||||
DTYPE_MAP = {
|
||||
@@ -80,9 +76,6 @@ class QueryContext:
|
||||
# reranker
|
||||
self._reranker = reranker
|
||||
|
||||
# core vectors
|
||||
self._core_vectors = []
|
||||
|
||||
@property
|
||||
def topk(self):
|
||||
return self._topk
|
||||
@@ -107,61 +100,120 @@ class QueryContext:
|
||||
def include_vector(self):
|
||||
return self._include_vector
|
||||
|
||||
@property
|
||||
def core_vectors(self):
|
||||
return self._core_vectors
|
||||
|
||||
@core_vectors.setter
|
||||
def core_vectors(self, core_vectors: list[_VectorQuery]):
|
||||
self._core_vectors = core_vectors
|
||||
class QueryExecutor:
|
||||
"""Unified query executor that routes based on query count and reranker type."""
|
||||
|
||||
|
||||
class QueryExecutor(ABC):
|
||||
def __init__(self, schema: CollectionSchema):
|
||||
self._schema = schema
|
||||
self._concurrency = max(1, int(os.getenv("ZVEC_QUERY_CONCURRENCY", "1")))
|
||||
|
||||
@abstractmethod
|
||||
def _do_validate(self, ctx: QueryContext) -> None:
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def _do_build(
|
||||
def _build_queries(
|
||||
self, ctx: QueryContext, collection: _Collection
|
||||
) -> list[_VectorQuery]:
|
||||
pass
|
||||
) -> list[_SearchQuery]:
|
||||
"""Build query vector list (no validation, conversion only)."""
|
||||
if not ctx.queries:
|
||||
return [self._build_base_search_query(ctx)]
|
||||
return [
|
||||
self._build_search_query(ctx, query, collection) for query in ctx.queries
|
||||
]
|
||||
|
||||
def _do_build_query_wo_vector(self, ctx: QueryContext) -> _VectorQuery:
|
||||
core_vector = _VectorQuery()
|
||||
core_vector.topk = ctx.topk
|
||||
core_vector.include_vector = ctx.include_vector
|
||||
def execute(self, ctx: QueryContext, collection: _Collection) -> DocList:
|
||||
"""Execute a query, routing by query count.
|
||||
|
||||
A single (or vector-less) query is sent to C++ as a ``_SearchQuery``;
|
||||
multiple queries are assembled into a ``_MultiQuery``.
|
||||
"""
|
||||
queries = self._build_queries(ctx, collection)
|
||||
if not queries:
|
||||
raise ValueError("No query to execute")
|
||||
|
||||
if len(queries) == 1:
|
||||
return self._execute_single_query(queries[0], collection)
|
||||
return self._execute_multi_query(ctx, queries, collection)
|
||||
|
||||
def _execute_single_query(
|
||||
self, query: _SearchQuery, collection: _Collection
|
||||
) -> DocList:
|
||||
"""Single/vector-less query: send a ``_SearchQuery`` to C++."""
|
||||
docs = collection.Query(query)
|
||||
return [convert_to_py_doc(doc, self._schema) for doc in docs]
|
||||
|
||||
def _execute_multi_query(
|
||||
self, ctx: QueryContext, queries: list[_SearchQuery], collection: _Collection
|
||||
) -> DocList:
|
||||
"""Multiple queries: send a ``_MultiQuery`` to C++.
|
||||
|
||||
A Python-only reranker (``_get_object()`` returns None) cannot run
|
||||
inside the C++ MultiQuery, so each route is executed individually and
|
||||
merged by the reranker in Python.
|
||||
"""
|
||||
reranker = ctx.reranker
|
||||
if reranker is not None and reranker._get_object() is None:
|
||||
docs_list = self._execute_python_pipeline(queries, collection)
|
||||
return self._merge_and_rerank(ctx, docs_list)
|
||||
|
||||
multi_query = self._build_multi_query(ctx, queries)
|
||||
docs = collection.Query(multi_query)
|
||||
return [convert_to_py_doc(doc, self._schema) for doc in docs]
|
||||
|
||||
def _build_multi_query(
|
||||
self, ctx: QueryContext, queries: list[_SearchQuery]
|
||||
) -> _MultiQuery:
|
||||
"""Assemble a C++ ``_MultiQuery`` from per-route ``_SearchQuery`` objects."""
|
||||
multi_query = _MultiQuery()
|
||||
multi_query.queries = [_SubQuery.from_search_query(query) for query in queries]
|
||||
multi_query.topk = ctx.topk
|
||||
if ctx.filter:
|
||||
core_vector.filter = ctx.filter
|
||||
if ctx.output_fields:
|
||||
core_vector.output_fields = ctx.output_fields
|
||||
return core_vector
|
||||
multi_query.filter = ctx.filter
|
||||
multi_query.include_vector = ctx.include_vector
|
||||
if ctx.output_fields is not None:
|
||||
multi_query.output_fields = ctx.output_fields
|
||||
if ctx.reranker is not None:
|
||||
multi_query.reranker = ctx.reranker._get_object()
|
||||
return multi_query
|
||||
|
||||
def _do_build_fts_query(self, query: Query, core_vector: _VectorQuery) -> None:
|
||||
"""Set FTS query on core_vector if the query has FTS parameters."""
|
||||
def _execute_python_pipeline(
|
||||
self, vectors: list[_SearchQuery], collection: _Collection
|
||||
) -> list[DocList]:
|
||||
"""Execute queries serially for the Python-only reranker path."""
|
||||
return [self._execute_single_query(query, collection) for query in vectors]
|
||||
|
||||
def _merge_and_rerank(self, ctx: QueryContext, docs_list: list[DocList]) -> DocList:
|
||||
"""Merge and rerank results from the Python pipeline path."""
|
||||
if not docs_list:
|
||||
raise ValueError("Query results is empty")
|
||||
if len(docs_list) == 1 and not ctx.reranker:
|
||||
return docs_list[0]
|
||||
return ctx.reranker.rerank(docs_list, ctx.topk)
|
||||
|
||||
def _build_base_search_query(self, ctx: QueryContext) -> _SearchQuery:
|
||||
search_query = _SearchQuery()
|
||||
search_query.topk = ctx.topk
|
||||
search_query.include_vector = ctx.include_vector
|
||||
if ctx.filter:
|
||||
search_query.filter = ctx.filter
|
||||
if ctx.output_fields is not None:
|
||||
search_query.output_fields = ctx.output_fields
|
||||
return search_query
|
||||
|
||||
def _apply_fts(self, query: Query, search_query: _SearchQuery) -> None:
|
||||
"""Set FTS query on search_query if the query has FTS parameters."""
|
||||
if query.has_fts():
|
||||
fts = _Fts()
|
||||
fts.query_string = query.fts.query_string or ""
|
||||
fts.match_string = query.fts.match_string or ""
|
||||
core_vector.fts = fts
|
||||
search_query.fts = fts
|
||||
|
||||
def _do_build_query_with_vector(
|
||||
def _build_search_query(
|
||||
self, ctx: QueryContext, query: Query, collection: _Collection
|
||||
) -> _VectorQuery:
|
||||
core_vector = self._do_build_query_wo_vector(ctx)
|
||||
core_vector.field_name = query.field_name
|
||||
) -> _SearchQuery:
|
||||
search_query = self._build_base_search_query(ctx)
|
||||
search_query.field_name = query.field_name
|
||||
if query.param:
|
||||
core_vector.query_params = query.param
|
||||
search_query.query_params = query.param
|
||||
|
||||
# set FTS query if provided
|
||||
self._do_build_fts_query(query, core_vector)
|
||||
|
||||
# set output_fields
|
||||
core_vector.output_fields = ctx.output_fields
|
||||
self._apply_fts(query, search_query)
|
||||
|
||||
vector_schema = None
|
||||
if query.has_vector() or query.has_id():
|
||||
@@ -181,189 +233,14 @@ class QueryExecutor(ABC):
|
||||
fetched = collection.Fetch([query.id])
|
||||
doc = next(iter(fetched.values()))
|
||||
if not doc:
|
||||
return core_vector
|
||||
raise ValueError(f"Document with id '{query.id}' not found")
|
||||
vec_data = doc.get_any(vector_schema.name, vector_schema.data_type)
|
||||
else:
|
||||
return core_vector
|
||||
return search_query
|
||||
|
||||
target_dtype = DTYPE_MAP.get(vector_schema.data_type.value)
|
||||
core_vector.set_vector(
|
||||
search_query.set_vector(
|
||||
vector_schema._get_object(),
|
||||
convert_to_numpy(vec_data, target_dtype) if target_dtype else vec_data,
|
||||
)
|
||||
return core_vector
|
||||
|
||||
def _do_execute(
|
||||
self, vectors: list[_VectorQuery], collection: _Collection
|
||||
) -> dict[str, list[Doc]]:
|
||||
query_cnt = len(vectors)
|
||||
if query_cnt == 0:
|
||||
raise ValueError("No query to execute")
|
||||
|
||||
if len(vectors) == 1 or self._concurrency == 1:
|
||||
results = {}
|
||||
for query in vectors:
|
||||
docs = collection.Query(query)
|
||||
results[query.field_name] = [
|
||||
convert_to_py_doc(doc, self._schema) for doc in docs
|
||||
]
|
||||
return results
|
||||
|
||||
results = {}
|
||||
with ThreadPoolExecutor(max_workers=self._concurrency) as executor:
|
||||
future_to_query = {
|
||||
executor.submit(collection.Query, query): query.field_name
|
||||
for query in vectors
|
||||
}
|
||||
|
||||
for future in as_completed(future_to_query):
|
||||
field_name = future_to_query[future]
|
||||
try:
|
||||
docs = future.result()
|
||||
results[field_name] = [
|
||||
convert_to_py_doc(doc, self._schema) for doc in docs
|
||||
]
|
||||
except Exception as e:
|
||||
raise e
|
||||
return results
|
||||
|
||||
def _do_merge_rerank_results(
|
||||
self, ctx: QueryContext, docs_map: dict[str, list[Doc]]
|
||||
) -> list[Doc]:
|
||||
query_result_cnt = len(docs_map) if docs_map else 0
|
||||
if query_result_cnt == 0:
|
||||
raise ValueError("Query results is none and dost not to rerank")
|
||||
if query_result_cnt == 1:
|
||||
if not ctx.reranker or isinstance(
|
||||
ctx.reranker, (RrfReRanker, WeightedReRanker)
|
||||
):
|
||||
return next(iter(docs_map.values()))
|
||||
return ctx.reranker.rerank(docs_map)
|
||||
return ctx.reranker.rerank(docs_map)
|
||||
|
||||
@final
|
||||
def execute(self, ctx: QueryContext, collection: _Collection) -> list[Doc]:
|
||||
# 1. validate query
|
||||
self._do_validate(ctx)
|
||||
# 2. build query vector
|
||||
query_vectors = self._do_build(ctx, collection)
|
||||
if not query_vectors:
|
||||
raise ValueError("No query to execute")
|
||||
# 3. execute query
|
||||
docs = self._do_execute(query_vectors, collection)
|
||||
# 4. merge and rerank result
|
||||
return self._do_merge_rerank_results(ctx, docs)
|
||||
|
||||
|
||||
class NoVectorQueryExecutor(QueryExecutor):
|
||||
def __init__(self, schema: CollectionSchema):
|
||||
super().__init__(schema)
|
||||
|
||||
def _do_validate(self, ctx: QueryContext) -> None:
|
||||
for query in ctx.queries:
|
||||
if query.has_vector() or query.has_id():
|
||||
raise ValueError("Collection does not support query with vector or id")
|
||||
query._validate()
|
||||
|
||||
def _do_build(
|
||||
self, ctx: QueryContext, collection: _Collection
|
||||
) -> list[_VectorQuery]:
|
||||
if len(ctx.queries) == 0:
|
||||
return [self._do_build_query_wo_vector(ctx)]
|
||||
# FTS-only branch in _do_build_query_with_vector skips vector resolution.
|
||||
return [
|
||||
self._do_build_query_with_vector(ctx, query, collection)
|
||||
for query in ctx.queries
|
||||
]
|
||||
|
||||
|
||||
class SingleVectorQueryExecutor(NoVectorQueryExecutor):
|
||||
def __init__(self, schema: CollectionSchema) -> None:
|
||||
super().__init__(schema)
|
||||
|
||||
def _validate_multi_query(self, ctx: QueryContext) -> None:
|
||||
"""Shared validation for multi-query: reranker required + no duplicate fields."""
|
||||
if ctx.reranker is None:
|
||||
raise ValueError("Reranker is required for multi-query")
|
||||
seen_fields = set()
|
||||
for query in ctx.queries:
|
||||
query._validate()
|
||||
if query.field_name in seen_fields:
|
||||
raise ValueError(
|
||||
f"Query field name '{query.field_name}' appears more than once"
|
||||
)
|
||||
seen_fields.add(query.field_name)
|
||||
|
||||
def _do_validate(self, ctx: QueryContext) -> None:
|
||||
if len(ctx.queries) > 1:
|
||||
# Allow FTS + vector hybrid multi-query (requires reranker)
|
||||
if not any(q.has_fts() for q in ctx.queries):
|
||||
raise ValueError(
|
||||
"Collection has only one vector field, cannot query with multiple vectors"
|
||||
)
|
||||
self._validate_multi_query(ctx)
|
||||
return
|
||||
for query in ctx.queries:
|
||||
query._validate()
|
||||
|
||||
def _do_build(
|
||||
self, ctx: QueryContext, collection: _Collection
|
||||
) -> list[_VectorQuery]:
|
||||
if len(ctx.queries) == 0:
|
||||
return [self._do_build_query_wo_vector(ctx)]
|
||||
vectors = []
|
||||
for query in ctx.queries:
|
||||
vectors.append(self._do_build_query_with_vector(ctx, query, collection))
|
||||
return vectors
|
||||
|
||||
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")
|
||||
|
||||
# Multi-query fast path: route FTS + vector hybrid to C++ MultiQuery
|
||||
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 = [_SubQuery.from_vector_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
|
||||
docs = self._do_execute(query_vectors, collection)
|
||||
# 4. merge and rerank result
|
||||
return self._do_merge_rerank_results(ctx, docs)
|
||||
|
||||
|
||||
class MultiVectorQueryExecutor(SingleVectorQueryExecutor):
|
||||
def __init__(self, schema: CollectionSchema) -> None:
|
||||
super().__init__(schema)
|
||||
|
||||
def _do_validate(self, ctx: QueryContext) -> None:
|
||||
if len(ctx.queries) > 1:
|
||||
self._validate_multi_query(ctx)
|
||||
return
|
||||
for query in ctx.queries:
|
||||
query._validate()
|
||||
|
||||
|
||||
class QueryExecutorFactory:
|
||||
@staticmethod
|
||||
def create(schema: CollectionSchema) -> QueryExecutor:
|
||||
vectors = schema.vectors
|
||||
if len(vectors) == 0:
|
||||
return NoVectorQueryExecutor(schema)
|
||||
if len(vectors) == 1:
|
||||
return SingleVectorQueryExecutor(schema)
|
||||
return MultiVectorQueryExecutor(schema)
|
||||
return search_query
|
||||
|
||||
@@ -13,16 +13,12 @@
|
||||
# limitations under the License.
|
||||
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 ..model.doc import DocList
|
||||
from .rerank_function import RerankFunction
|
||||
|
||||
|
||||
@@ -35,24 +31,15 @@ class RrfReRanker(RerankFunction):
|
||||
The RRF score for a document at rank ``r`` is: ``1 / (k + r + 1)``,
|
||||
where ``k`` is the rank constant.
|
||||
|
||||
Note:
|
||||
This re-ranker is specifically designed for multi-vector scenarios where
|
||||
query results from multiple vector fields need to be combined.
|
||||
|
||||
Args:
|
||||
topn (int, optional): Number of top documents to return. Defaults to 10.
|
||||
rerank_field (Optional[str], optional): Ignored by RRF. Defaults to None.
|
||||
rank_constant (int, optional): Smoothing constant ``k`` in RRF formula.
|
||||
Larger values reduce the impact of early ranks. Defaults to 60.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
topn: int = 10,
|
||||
rerank_field: Optional[str] = None,
|
||||
rank_constant: int = 60,
|
||||
):
|
||||
super().__init__(topn=topn, rerank_field=rerank_field)
|
||||
self._rank_constant = rank_constant
|
||||
# Use C++ implementation for performance
|
||||
self._cpp_reranker = _RrfReranker(rank_constant)
|
||||
@@ -65,36 +52,18 @@ class RrfReRanker(RerankFunction):
|
||||
"""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)
|
||||
|
||||
def rerank(self, query_results: dict[str, list[Doc]]) -> list[Doc]:
|
||||
"""Apply Reciprocal Rank Fusion to combine multiple query results.
|
||||
def rerank(self, query_results: list[DocList], topn: int) -> DocList:
|
||||
"""Re-rank using C++ RRF implementation.
|
||||
|
||||
Args:
|
||||
query_results (dict[str, list[Doc]]): Results from one or more vector queries.
|
||||
query_results (list[DocList]): Multi-route recall results,
|
||||
positionally aligned with queries.
|
||||
topn (int): Number of top documents to return.
|
||||
|
||||
Returns:
|
||||
list[Doc]: Re-ranked documents with RRF scores in the ``score`` field.
|
||||
DocList: Re-ranked documents.
|
||||
"""
|
||||
rrf_scores: dict[str, float] = defaultdict(float)
|
||||
id_to_doc: dict[str, Doc] = {}
|
||||
|
||||
for _, query_result in query_results.items():
|
||||
for rank, doc in enumerate(query_result):
|
||||
doc_id = doc.id
|
||||
rrf_score = self._rrf_score(rank)
|
||||
rrf_scores[doc_id] += rrf_score
|
||||
if doc_id not in id_to_doc:
|
||||
id_to_doc[doc_id] = doc
|
||||
|
||||
top_docs = heapq.nlargest(self.topn, rrf_scores.items(), key=lambda x: x[1])
|
||||
results: list[Doc] = []
|
||||
for doc_id, rrf_score in top_docs:
|
||||
doc = id_to_doc[doc_id]
|
||||
new_doc = doc._replace(score=rrf_score)
|
||||
results.append(new_doc)
|
||||
return results
|
||||
return self._cpp_reranker.rerank(query_results, topn)
|
||||
|
||||
|
||||
class WeightedReRanker(RerankFunction):
|
||||
@@ -102,98 +71,41 @@ class WeightedReRanker(RerankFunction):
|
||||
|
||||
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
|
||||
query results from multiple vector fields need to be combined with
|
||||
configurable weights.
|
||||
fields. The actual re-ranking logic lives in the C++ implementation.
|
||||
|
||||
Args:
|
||||
topn (int, optional): Number of top documents to return. Defaults to 10.
|
||||
rerank_field (Optional[str], optional): Ignored. Defaults to None.
|
||||
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.
|
||||
|
||||
Note:
|
||||
Supported metrics: L2, IP, COSINE. Scores are normalized to [0, 1].
|
||||
weights (Optional[list[float]], optional): Weight per vector field,
|
||||
aligned by position with the queries supplied to ``collection.query()``.
|
||||
Defaults to None (treated as an empty list).
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
topn: int = 10,
|
||||
rerank_field: Optional[str] = None,
|
||||
metrics: Optional[dict[str, MetricType]] = None,
|
||||
weights: Optional[dict[str, float]] = None,
|
||||
weights: Optional[list[float]] = None,
|
||||
):
|
||||
super().__init__(topn=topn, rerank_field=rerank_field)
|
||||
self._weights = weights or {}
|
||||
self._metrics = metrics or {}
|
||||
self._cpp_reranker = _WeightedReranker(weights or [])
|
||||
|
||||
@property
|
||||
def weights(self) -> dict[str, float]:
|
||||
"""dict[str, float]: Weight mapping for vector fields."""
|
||||
return self._weights
|
||||
|
||||
@property
|
||||
def metrics(self) -> dict[str, MetricType]:
|
||||
"""dict[str, MetricType]: Per-field metric type mapping."""
|
||||
return self._metrics
|
||||
def weights(self) -> list[float]:
|
||||
"""list[float]: Weight list for vector fields, aligned with queries."""
|
||||
return self._cpp_reranker.weights
|
||||
|
||||
def _get_object(self):
|
||||
"""Return a C++ WeightedReranker instance."""
|
||||
return _WeightedReranker(self._weights)
|
||||
"""Return the underlying C++ WeightedReranker instance."""
|
||||
return self._cpp_reranker
|
||||
|
||||
def rerank(self, query_results: dict[str, list[Doc]]) -> list[Doc]:
|
||||
"""Combine scores from multiple vector fields using weighted sum.
|
||||
def rerank(self, query_results: list[DocList], topn: int) -> DocList:
|
||||
"""Re-rank using C++ Weighted implementation.
|
||||
|
||||
Args:
|
||||
query_results (dict[str, list[Doc]]): Results per vector field.
|
||||
query_results (list[DocList]): Multi-route recall results,
|
||||
positionally aligned with queries.
|
||||
topn (int): Number of top documents to return.
|
||||
|
||||
Returns:
|
||||
list[Doc]: Re-ranked documents with combined scores in ``score`` field.
|
||||
DocList: Re-ranked documents.
|
||||
"""
|
||||
weighted_scores: dict[str, float] = defaultdict(float)
|
||||
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, metric
|
||||
) * self.weights.get(vector_name, 1.0)
|
||||
weighted_scores[doc_id] += weighted_score
|
||||
if doc_id not in id_to_doc:
|
||||
id_to_doc[doc_id] = doc
|
||||
|
||||
top_docs = heapq.nlargest(
|
||||
self.topn, weighted_scores.items(), key=lambda x: x[1]
|
||||
)
|
||||
results: list[Doc] = []
|
||||
for doc_id, weighted_score in top_docs:
|
||||
doc = id_to_doc[doc_id]
|
||||
new_doc = doc._replace(score=weighted_score)
|
||||
results.append(new_doc)
|
||||
return results
|
||||
|
||||
def _normalize_score(self, score: float, metric: MetricType) -> float:
|
||||
if metric == MetricType.L2:
|
||||
return 1.0 - 2 * math.atan(score) / math.pi
|
||||
if metric == MetricType.IP:
|
||||
return 0.5 + math.atan(score) / math.pi
|
||||
if metric == MetricType.COSINE:
|
||||
return 1.0 - score / 2.0
|
||||
raise ValueError("Unsupported metric type")
|
||||
return self._cpp_reranker.rerank(query_results, topn)
|
||||
|
||||
|
||||
class CallbackReRanker(RerankFunction):
|
||||
@@ -202,21 +114,18 @@ class CallbackReRanker(RerankFunction):
|
||||
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.
|
||||
The callback receives raw C++ ``_Doc`` objects grouped per query (as a
|
||||
``list[list[_Doc]]``) and must return a ``list[_Doc]``.
|
||||
|
||||
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.
|
||||
``(query_results: list[list[_Doc]], topn: int) -> list[_Doc]``.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
callback: Callable,
|
||||
topn: int = 10,
|
||||
):
|
||||
super().__init__(topn=topn)
|
||||
self._callback = callback
|
||||
self._cpp_reranker = _CallbackReranker(callback)
|
||||
|
||||
@@ -224,13 +133,15 @@ class CallbackReRanker(RerankFunction):
|
||||
"""Return the underlying C++ CallbackReranker instance."""
|
||||
return self._cpp_reranker
|
||||
|
||||
def rerank(self, query_results: dict[str, list[Doc]]) -> list[Doc]:
|
||||
def rerank(self, query_results: list[DocList], topn: int) -> DocList:
|
||||
"""Invoke the callback to re-rank documents.
|
||||
|
||||
Args:
|
||||
query_results (dict[str, list[Doc]]): Results per vector field.
|
||||
query_results (list[DocList]): Multi-route recall results,
|
||||
positionally aligned with queries.
|
||||
topn (int): Number of top documents to return.
|
||||
|
||||
Returns:
|
||||
list[Doc]: Re-ranked documents.
|
||||
DocList: Re-ranked documents.
|
||||
"""
|
||||
return self._callback(query_results, self.topn)
|
||||
return self._callback(query_results, topn)
|
||||
|
||||
@@ -15,7 +15,7 @@ from __future__ import annotations
|
||||
|
||||
from typing import Optional
|
||||
|
||||
from ..model.doc import Doc
|
||||
from ..model.doc import Doc, DocList
|
||||
from .qwen_function import QwenFunctionBase
|
||||
from .rerank_function import RerankFunction
|
||||
|
||||
@@ -32,8 +32,6 @@ class QwenReRanker(QwenFunctionBase, RerankFunction):
|
||||
|
||||
Args:
|
||||
query (str): Query text for semantic re-ranking. **Required**.
|
||||
topn (int, optional): Maximum number of documents to return after re-ranking.
|
||||
Defaults to 10.
|
||||
rerank_field (str): Document field name to use as re-ranking input text.
|
||||
**Required** (e.g., "content", "title", "body").
|
||||
model (str, optional): DashScope re-ranking model identifier.
|
||||
@@ -53,7 +51,6 @@ class QwenReRanker(QwenFunctionBase, RerankFunction):
|
||||
Example:
|
||||
>>> reranker = QwenReRanker(
|
||||
... query="machine learning algorithms",
|
||||
... topn=5,
|
||||
... rerank_field="content",
|
||||
... model="gte-rerank-v2",
|
||||
... api_key="your-api-key"
|
||||
@@ -64,7 +61,6 @@ class QwenReRanker(QwenFunctionBase, RerankFunction):
|
||||
def __init__(
|
||||
self,
|
||||
query: Optional[str] = None,
|
||||
topn: int = 10,
|
||||
rerank_field: Optional[str] = None,
|
||||
model: str = "gte-rerank-v2",
|
||||
api_key: Optional[str] = None,
|
||||
@@ -73,7 +69,6 @@ class QwenReRanker(QwenFunctionBase, RerankFunction):
|
||||
|
||||
Args:
|
||||
query (Optional[str]): Query text for semantic matching. Required.
|
||||
topn (int): Number of top results to return.
|
||||
rerank_field (Optional[str]): Document field for re-ranking input.
|
||||
model (str): DashScope model name.
|
||||
api_key (Optional[str]): API key or None to use environment variable.
|
||||
@@ -82,37 +77,45 @@ class QwenReRanker(QwenFunctionBase, RerankFunction):
|
||||
ValueError: If query is empty or API key is unavailable.
|
||||
"""
|
||||
QwenFunctionBase.__init__(self, model=model, api_key=api_key)
|
||||
RerankFunction.__init__(self, topn=topn, rerank_field=rerank_field)
|
||||
RerankFunction.__init__(self)
|
||||
|
||||
if not query:
|
||||
raise ValueError("Query is required for QwenReRanker")
|
||||
self._query = query
|
||||
self._rerank_field = rerank_field
|
||||
|
||||
@property
|
||||
def query(self) -> str:
|
||||
"""str: Query text used for semantic re-ranking."""
|
||||
return self._query
|
||||
|
||||
def rerank(self, query_results: dict[str, list[Doc]]) -> list[Doc]:
|
||||
@property
|
||||
def rerank_field(self) -> Optional[str]:
|
||||
"""Optional[str]: Field name used as re-ranking input."""
|
||||
return self._rerank_field
|
||||
|
||||
def rerank(self, query_results: list[DocList], topn: int) -> DocList:
|
||||
"""Re-rank documents using Qwen's TextReRank API.
|
||||
|
||||
Sends document texts to DashScope TextReRank service along with the query.
|
||||
Returns documents sorted by relevance scores from the cross-encoder model.
|
||||
|
||||
Args:
|
||||
query_results (dict[str, list[Doc]]): Mapping from vector field names
|
||||
to lists of retrieved documents. Documents from all fields are
|
||||
query_results (list[DocList]): Multi-route recall results,
|
||||
positionally aligned with the queries supplied to
|
||||
``collection.query()``. Documents from all routes are
|
||||
deduplicated and re-ranked together.
|
||||
topn (int): Maximum number of documents to return after re-ranking.
|
||||
|
||||
Returns:
|
||||
list[Doc]: Re-ranked documents (up to ``topn``) with updated ``score``
|
||||
fields containing relevance scores from the API.
|
||||
DocList: Re-ranked documents (up to ``topn``) with updated
|
||||
``score`` fields containing relevance scores from the API.
|
||||
|
||||
Raises:
|
||||
ValueError: If no valid documents are found or API call fails.
|
||||
|
||||
Note:
|
||||
- Duplicate documents (same ID) across fields are processed once
|
||||
- Duplicate documents (same ID) across routes are processed once
|
||||
- Documents with empty/missing ``rerank_field`` content are skipped
|
||||
- Returned scores are relevance scores from the cross-encoder model
|
||||
"""
|
||||
@@ -124,7 +127,7 @@ class QwenReRanker(QwenFunctionBase, RerankFunction):
|
||||
doc_ids: list[str] = []
|
||||
contents: list[str] = []
|
||||
|
||||
for _, query_result in query_results.items():
|
||||
for query_result in query_results:
|
||||
for doc in query_result:
|
||||
doc_id = doc.id
|
||||
if doc_id in id_to_doc:
|
||||
@@ -147,11 +150,11 @@ class QwenReRanker(QwenFunctionBase, RerankFunction):
|
||||
output = self._call_rerank_api(
|
||||
query=self.query,
|
||||
documents=contents,
|
||||
top_n=self.topn,
|
||||
top_n=topn,
|
||||
)
|
||||
|
||||
# Build result list with updated scores
|
||||
results: list[Doc] = []
|
||||
results: DocList = []
|
||||
for item in output["results"]:
|
||||
idx = item["index"]
|
||||
doc_id = doc_ids[idx]
|
||||
|
||||
@@ -14,9 +14,8 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from abc import ABC, abstractmethod
|
||||
from typing import Optional
|
||||
|
||||
from ..model.doc import Doc
|
||||
from ..model.doc import DocList
|
||||
|
||||
|
||||
class RerankFunction(ABC):
|
||||
@@ -26,44 +25,22 @@ class RerankFunction(ABC):
|
||||
a secondary scoring strategy. They are used in the ``query()`` method of
|
||||
``Collection`` via the ``reranker`` parameter.
|
||||
|
||||
Args:
|
||||
topn (int, optional): Number of top documents to return after re-ranking.
|
||||
Defaults to 10.
|
||||
rerank_field (Optional[str], optional): Field name used as input for
|
||||
re-ranking (e.g., document title or body). Defaults to None.
|
||||
|
||||
Note:
|
||||
Subclasses must implement the ``rerank()`` method.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
topn: int = 10,
|
||||
rerank_field: Optional[str] = None,
|
||||
):
|
||||
self._topn = topn
|
||||
self._rerank_field = rerank_field
|
||||
|
||||
@property
|
||||
def topn(self) -> int:
|
||||
"""int: Number of top documents to return after re-ranking."""
|
||||
return self._topn
|
||||
|
||||
@property
|
||||
def rerank_field(self) -> Optional[str]:
|
||||
"""Optional[str]: Field name used as re-ranking input."""
|
||||
return self._rerank_field
|
||||
|
||||
@abstractmethod
|
||||
def rerank(self, query_results: dict[str, list[Doc]]) -> list[Doc]:
|
||||
"""Re-rank documents from one or more vector queries.
|
||||
def rerank(self, query_results: list[DocList], topn: int) -> DocList:
|
||||
"""Re-rank documents from multi-route recall results.
|
||||
|
||||
Args:
|
||||
query_results (dict[str, list[Doc]]): Mapping from vector field name
|
||||
to list of retrieved documents (sorted by relevance).
|
||||
query_results (list[DocList]): List of query results from
|
||||
multi-route recall. Each element corresponds to a Query in the
|
||||
collection.query(queries=List[Query]) call, aligned by position.
|
||||
topn (int): Number of top documents to return after re-ranking.
|
||||
|
||||
Returns:
|
||||
list[Doc]: Re-ranked list of documents (length ≤ ``topn``),
|
||||
DocList: Re-ranked list of documents (length ≤ ``topn``),
|
||||
with updated ``score`` fields.
|
||||
"""
|
||||
...
|
||||
|
||||
@@ -15,7 +15,7 @@ from __future__ import annotations
|
||||
|
||||
from typing import Literal, Optional
|
||||
|
||||
from ..model.doc import Doc
|
||||
from ..model.doc import Doc, DocList
|
||||
from ..tool import require_module
|
||||
from .rerank_function import RerankFunction
|
||||
from .sentence_transformer_function import SentenceTransformerFunctionBase
|
||||
@@ -33,8 +33,6 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
|
||||
Args:
|
||||
query (str): Query text for semantic re-ranking. **Required**.
|
||||
topn (int, optional): Maximum number of documents to return after re-ranking.
|
||||
Defaults to 10.
|
||||
rerank_field (Optional[str], optional): Document field name to use as
|
||||
re-ranking input text. **Required** (e.g., "content", "title", "body").
|
||||
model_name (str, optional): Cross-encoder model identifier or local path.
|
||||
@@ -56,7 +54,6 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
|
||||
Attributes:
|
||||
query (str): The query text used for re-ranking.
|
||||
topn (int): Maximum number of documents to return.
|
||||
rerank_field (Optional[str]): Field name used for re-ranking input.
|
||||
model_name (str): The cross-encoder model being used.
|
||||
model_source (str): The model source ("huggingface" or "modelscope").
|
||||
@@ -113,7 +110,6 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
>>>
|
||||
>>> reranker = SentenceTransformerReRanker(
|
||||
... query="machine learning algorithms",
|
||||
... topn=5,
|
||||
... rerank_field="content"
|
||||
... )
|
||||
>>>
|
||||
@@ -127,7 +123,6 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
>>> # Using ModelScope for users in China
|
||||
>>> reranker = SentenceTransformerReRanker(
|
||||
... query="深度学习",
|
||||
... topn=10,
|
||||
... rerank_field="content",
|
||||
... model_source="modelscope"
|
||||
... )
|
||||
@@ -135,7 +130,6 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
>>> # Using larger model for better quality
|
||||
>>> reranker = SentenceTransformerReRanker(
|
||||
... query="neural networks",
|
||||
... topn=5,
|
||||
... rerank_field="content",
|
||||
... model_name="BAAI/bge-reranker-large",
|
||||
... device="cuda",
|
||||
@@ -143,13 +137,13 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
... )
|
||||
|
||||
>>> # Direct rerank call (for testing)
|
||||
>>> query_results = {
|
||||
... "vector1": [
|
||||
>>> query_results = [
|
||||
... [
|
||||
... Doc(id="1", score=0.9, fields={"content": "Machine learning is..."}),
|
||||
... Doc(id="2", score=0.8, fields={"content": "Deep learning is..."}),
|
||||
... ]
|
||||
... }
|
||||
>>> reranked = reranker.rerank(query_results)
|
||||
... ]
|
||||
>>> reranked = reranker.rerank(query_results, topn=5)
|
||||
>>> for doc in reranked:
|
||||
... print(f"ID: {doc.id}, Score: {doc.score:.4f}")
|
||||
ID: 2, Score: 0.9234
|
||||
@@ -170,7 +164,6 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
def __init__(
|
||||
self,
|
||||
query: Optional[str] = None,
|
||||
topn: int = 10,
|
||||
rerank_field: Optional[str] = None,
|
||||
model_name: str = "cross-encoder/ms-marco-MiniLM-L6-v2",
|
||||
model_source: Literal["huggingface", "modelscope"] = "huggingface",
|
||||
@@ -181,7 +174,6 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
|
||||
Args:
|
||||
query (Optional[str]): Query text for semantic matching. Required.
|
||||
topn (int): Number of top results to return.
|
||||
rerank_field (Optional[str]): Document field for re-ranking input.
|
||||
model_name (str): Cross-encoder model identifier.
|
||||
model_source (Literal["huggingface", "modelscope"]): Model source.
|
||||
@@ -197,12 +189,13 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
)
|
||||
|
||||
# Initialize rerank function
|
||||
RerankFunction.__init__(self, topn=topn, rerank_field=rerank_field)
|
||||
RerankFunction.__init__(self)
|
||||
|
||||
# Validate query
|
||||
if not query:
|
||||
raise ValueError("Query is required for DefaultLocalReRanker")
|
||||
self._query = query
|
||||
self._rerank_field = rerank_field
|
||||
self._batch_size = batch_size
|
||||
|
||||
# Load and validate cross-encoder model
|
||||
@@ -273,12 +266,17 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
"""str: Query text used for semantic re-ranking."""
|
||||
return self._query
|
||||
|
||||
@property
|
||||
def rerank_field(self) -> Optional[str]:
|
||||
"""Optional[str]: Field name used as re-ranking input."""
|
||||
return self._rerank_field
|
||||
|
||||
@property
|
||||
def batch_size(self) -> int:
|
||||
"""int: Batch size for processing query-document pairs."""
|
||||
return self._batch_size
|
||||
|
||||
def rerank(self, query_results: dict[str, list[Doc]]) -> list[Doc]:
|
||||
def rerank(self, query_results: list[DocList], topn: int) -> DocList:
|
||||
"""Re-rank documents using Sentence Transformer cross-encoder model.
|
||||
|
||||
Evaluates each query-document pair using the cross-encoder model to compute
|
||||
@@ -286,19 +284,22 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
results are returned.
|
||||
|
||||
Args:
|
||||
query_results (dict[str, list[Doc]]): Mapping from vector field names
|
||||
to lists of retrieved documents. Documents from all fields are
|
||||
query_results (list[DocList]): Multi-route recall results,
|
||||
positionally aligned with the queries supplied to
|
||||
``collection.query()``. Documents from all routes are
|
||||
deduplicated and re-ranked together.
|
||||
topn (int): Maximum number of documents to return after re-ranking.
|
||||
|
||||
Returns:
|
||||
list[Doc]: Re-ranked documents (up to ``topn``) with updated ``score``
|
||||
fields containing relevance scores from the cross-encoder model.
|
||||
DocList: Re-ranked documents (up to ``topn``) with updated
|
||||
``score`` fields containing relevance scores from the
|
||||
cross-encoder model.
|
||||
|
||||
Raises:
|
||||
ValueError: If no valid documents are found or model inference fails.
|
||||
|
||||
Note:
|
||||
- Duplicate documents (same ID) across fields are processed once
|
||||
- Duplicate documents (same ID) across routes are processed once
|
||||
- Documents with empty/missing ``rerank_field`` content are skipped
|
||||
- Returned scores are logits from the cross-encoder model
|
||||
- Higher scores indicate higher relevance
|
||||
@@ -310,13 +311,13 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
... topn=3,
|
||||
... rerank_field="content"
|
||||
... )
|
||||
>>> query_results = {
|
||||
... "vector1": [
|
||||
>>> query_results = [
|
||||
... [
|
||||
... Doc(id="1", score=0.9, fields={"content": "ML basics"}),
|
||||
... Doc(id="2", score=0.8, fields={"content": "DL tutorial"}),
|
||||
... ]
|
||||
... }
|
||||
>>> reranked = reranker.rerank(query_results)
|
||||
... ]
|
||||
>>> reranked = reranker.rerank(query_results, topn=3)
|
||||
>>> len(reranked) <= 3
|
||||
True
|
||||
"""
|
||||
@@ -328,7 +329,7 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
doc_ids: list[str] = []
|
||||
contents: list[str] = []
|
||||
|
||||
for _, query_result in query_results.items():
|
||||
for query_result in query_results:
|
||||
for doc in query_result:
|
||||
doc_id = doc.id
|
||||
if doc_id in id_to_doc:
|
||||
@@ -373,10 +374,10 @@ class DefaultLocalReRanker(SentenceTransformerFunctionBase, RerankFunction):
|
||||
|
||||
# Sort by score (descending) and take top-k
|
||||
scored_docs.sort(key=lambda x: x[2], reverse=True)
|
||||
top_scored_docs = scored_docs[: self.topn]
|
||||
top_scored_docs = scored_docs[:topn]
|
||||
|
||||
# Build result list with updated scores
|
||||
results: list[Doc] = []
|
||||
results: DocList = []
|
||||
for _, doc, score in top_scored_docs:
|
||||
new_doc = doc._replace(score=score)
|
||||
results.append(new_doc)
|
||||
|
||||
@@ -18,11 +18,11 @@ from typing import Optional, Union, overload
|
||||
|
||||
from _zvec import _Collection
|
||||
|
||||
from ..executor import QueryContext, QueryExecutorFactory
|
||||
from ..executor import QueryContext, QueryExecutor
|
||||
from ..extension import ReRanker
|
||||
from ..typing import Status
|
||||
from .convert import convert_to_cpp_doc, convert_to_py_doc
|
||||
from .doc import Doc
|
||||
from .doc import Doc, DocList
|
||||
from .param import (
|
||||
AddColumnOption,
|
||||
AlterColumnOption,
|
||||
@@ -63,7 +63,7 @@ class Collection:
|
||||
inst._obj = core_collection
|
||||
schema = CollectionSchema._from_core(core_collection.Schema())
|
||||
inst._schema = schema
|
||||
inst._querier = QueryExecutorFactory.create(schema)
|
||||
inst._querier = QueryExecutor(schema)
|
||||
return inst
|
||||
|
||||
@property
|
||||
@@ -381,7 +381,7 @@ class Collection:
|
||||
include_vector: bool = False,
|
||||
output_fields: Optional[list[str]] = None,
|
||||
reranker: Optional[ReRanker] = None,
|
||||
) -> list[Doc]:
|
||||
) -> DocList:
|
||||
"""Perform vector similarity search with optional filtering and re-ranking.
|
||||
|
||||
At least one `Query` must be provided via `queries`.
|
||||
@@ -403,7 +403,7 @@ class Collection:
|
||||
Defaults to None.
|
||||
|
||||
Returns:
|
||||
list[Doc]: Top-k matching documents, sorted by relevance score.
|
||||
DocList: Top-k matching documents, sorted by relevance score.
|
||||
|
||||
Examples:
|
||||
>>> from zvec import Query
|
||||
|
||||
@@ -20,6 +20,7 @@ from ..common import VectorType
|
||||
|
||||
__all__ = [
|
||||
"Doc",
|
||||
"DocList",
|
||||
]
|
||||
|
||||
|
||||
@@ -171,3 +172,7 @@ class Doc:
|
||||
else:
|
||||
obj.vectors = {}
|
||||
return obj
|
||||
|
||||
|
||||
#: Type alias for query results: a list of documents returned by a single query route.
|
||||
DocList = list[Doc]
|
||||
|
||||
@@ -817,7 +817,7 @@ class VectorIndexParam(IndexParam):
|
||||
QuantizeType: Vector quantization type (e.g., FP16, INT8).
|
||||
"""
|
||||
|
||||
class _VectorQuery:
|
||||
class _SearchQuery:
|
||||
field_name: str
|
||||
filter: str
|
||||
include_vector: bool
|
||||
|
||||
Reference in New Issue
Block a user