Querying and Relevance

POST /lmkit/v1/search/search is one endpoint with a deep relevance toolbox. This guide walks it in the order a query actually executes: how the query is understood, how candidates are retrieved and fused, how they are re-scored and diversified, and how results are filtered, faceted, paged, and shaped for RAG. Exact request fields live in the API reference; this is the map of what to reach for and when.

1The three modes#

Two collection-level dials tune the arms without re-indexing: bm25_b adjusts full-text length normalization (lower it for corpora whose relevant documents are inherently long), and fusion_semantic_share shifts the hybrid balance per collection.

2Hybrid fusion#

Hybrid retrieves a candidate pool from each arm (candidates, default 100) and fuses:

• Convex (the default): a weighted combination of normalized scores, preserving each arm's confidence. The default weighting deliberately favors the semantic arm (1:9), which measures best on most corpora; override per request with the arm weights or per collection with the fusion share.
• RRF (Reciprocal Rank Fusion): rank-based, ignores score magnitudes, equal arms by default. The robust choice when the two arms' score scales cannot be trusted.

name_boost additionally lifts documents whose title matches the query, closing a fraction of each hit's remaining score headroom so title hits outrank body-only hits without breaking the 0..1 scale.

3Reranking: the quality pass#

Setting rerank: true re-scores the top candidates with the tenant's cross-encoder model, which reads query and document TOGETHER and judges relevance directly, something no first-stage retriever can do. Mechanics worth knowing:

• It over-fetches. rerank_top_n (default 50) candidates are retrieved and re-scored so a document the first stage placed below the cut can still surface in the final top_k.
• It blends, not replaces. rerank_alpha (default 0.5) mixes the reranker's judgment with the retrieval score over the candidate pool. Full replacement (alpha 1) measured WORSE than not reranking at all on every corpus tried, so the default tempers an overconfident cross-encoder with retrieval evidence.
• It costs one inference pass over the candidates, so it is per-request opt-in: on for quality-sensitive queries, off for latency-sensitive ones.

4Query understanding: fixing the query itself#

Retrieval can only be as good as the query, and query_mode runs the tenant's small query-understanding model before retrieval:

Every mode degrades gracefully: with no query model configured, the search runs on the original query and the response says so. Cost is one small-model generation pass (MultiQuery also multiplies retrieval by the variant count).

5Precision, diversity, freshness#

• min_score drops the weak tail (text rank for full-text, cosine for semantic, normalized RRF for hybrid).
• mmr re-selects results with Maximal Marginal Relevance: each pick balances relevance against similarity to what is already picked, so near-duplicate passages stop crowding out distinct ones. Semantic mode only; mmr_lambda sets the balance.
• Freshness comes in two shapes. sort: Recency is a hard newest-first ordering (full-text only). recency_bias folds an exponential decay INTO relevance for every mode, with a configurable half-life, and recency_key can point the decay at a metadata date so a bulk-imported archive is aged by its CONTENT dates, not its import day.

6Filters and facets#

Two filter shapes over custom_metadata, mutually exclusive:

• filters: a flat key/value map, exact equality on every pair. The simple case, simply.
• filter: a typed operator algebra: comparison nodes (eq, ne, gt, gte, lt, lte, in, nin, exists) composed under and/or, with typed values (text, number, boolean, ISO 8601 dates). The comparison shape is a superset of the OpenAI attribute-filter format, so vector-store filter code ports directly. Depth and size are bounded (8 levels, 128 conditions).

Both apply DURING ranking, so top_k still returns the best matches that pass, and both are query scoping, never access control (the boundary story is the Access Model).

facets returns document counts per value for named metadata fields, over the whole match set (exactly for full-text; over the deepened candidate pool for semantic and hybrid, with an exactness flag in the response). Built for low-cardinality fields: status, department, type.

7Shaping results for RAG#

Three fields turn search hits into prompt-ready context:

• max_chunks_per_document (default 1): raise it to let a strongly matching document surface several of its best pages as separate hits, which is usually what a RAG prompt wants.
• context_expansion: Chunk attaches the matched chunk plus its neighbors; Page attaches the full stored Markdown of the matched page. Request it when the caller assembles prompts from the results.
• include_page_layout attaches the stored text blocks and positions of the matched page, for callers that render or highlight.

Pagination is offset plus top_k as the page size; hybrid paging depth is bounded by the candidate pool. When the consumer is a person rather than a pipeline, skip the assembly entirely: Grounded Answers runs retrieval and cited synthesis in one call.

8Stated plainly#

• Hybrid plus reranking is the strong default for quality; full-text alone for codes and exact language; semantic alone rarely.
• The pipeline is compositional: query understanding fixes the query, fusion combines the arms, reranking fixes the order, MMR fixes redundancy, filters and facets shape the set.
• Every knob here is per-request or per-collection and none requires re-indexing; changes are cheap to try and cheap to measure.