Skip to content

Retrieval

siglip2_toolkit.retrieval

Storage-agnostic retrieval primitives.

These helpers operate on numpy arrays and on (payload, score) result lists, so they can be reused with any vector store or directly over vectors loaded from an embeddings export (see formats).

rank_by_similarity 

rank_by_similarity(
    query, matrix, top_k=50, metric="cosine"
)

Rank the rows of matrix against query.

Returns (row_index, score) pairs ordered from best to worst, where scores are distances (lower is better) for every supported metric.

results_matrix 

results_matrix(records, key='vector')

Stack the vectors of index records into a (n, dimensions) matrix.

fuse_rrf 

fuse_rrf(result_lists, weights=None, k=60, key=None)

Reciprocal Rank Fusion over several ranked lists.

Each list contains (payload, score) pairs ordered from best to worst; the score semantics do not matter for the fusion. Returns (payload, rrf_score) pairs sorted by decreasing fused score. Ties prefer the better original score, assuming lower-is-better (distance-like) scores.

apply_similarity_drop 

apply_similarity_drop(
    results,
    max_drop_percent,
    lower_is_better=True,
    score_of=None,
)

Keep only the results within max_drop_percent of the best score.

The threshold is relative to the magnitude of the best score: best + |best| * pct/100 when lower is better (distances), or best - |best| * pct/100 when higher is better (e.g. RRF scores).