On this page
Retrieve and combine passages¶
Start with dense search for paraphrases or BM25 for exact terms and codes. If each finds useful passages the other misses, compare fusion with each retriever on the same questions, documents, filters and result depth.
Dense similarity (dense)¶
Dense retrieval embeds the question and finds nearby stored vectors. Check that the space’s embedding model matches the index, especially for attached data.
The pgvector HNSW defaults are hnsw_m=32 and
hnsw_ef_construction=200. They control connections and build search
width. An existing index must be rebuilt to apply these settings. Use
the preflight report for the deployed index’s state and backend support.
hnsw_ef_search controls the query-time probe and follows the requested
depth when unset. Increase it only after measuring latency and recall.
Lexical search (bm25)¶
Use BM25 for alarm codes, names and terms spelled in the documents.
language="multilingual" by default selects multilingual analysis.
Use english or russian for a corpus in one language.
k1=1.2 controls term-frequency saturation and b=0.75
normalizes for passage length. sparse_top_k defaults to the
shared candidate depth. Changing language, k1 or b requires
rebuilding the BM25 representation.
Learned sparse search (splade)¶
SPLADE uses a sparse encoder to add related terms to the query and
the indexed passages. Compare it with dense and BM25 when a corpus
has lexical conventions alongside synonyms. The default multilingual
model is
opensearch-project/opensearch-neural-sparse-encoding-multilingual-v1.
Ensure its weights are available to the installation. stored_terms
keeps the strongest 256 weights per passage by default (1–1000).
Changing the model or stored width rebuilds the sparse representation.
sparse_top_k defaults to the shared candidate depth.
Graph retrieval (graph)¶
The local graph retriever matches entities in the question and returns linked passages and graph context. Use it for questions about an entity and its relationships. Build a graph for the space first. See Build and query a knowledge graph for compatible storage, build settings and local and global modes.
Dense, BM25 and SPLADE are available with pgvector, Qdrant, Chroma and Weaviate. The sparse indexes are held by ContextBase. For attached stores, sparse retrieval depends on the side index being available for the attached corpus. Graph retrieval requires a managed pgvector, Qdrant or Weaviate binding. See Connections and storage for how to choose and verify the binding.
Fusion and candidate depth¶
Set candidate_top_k on the fusion node. It defaults to 50 and must
be at least 5. This sets the candidate pool before reranking. The request’s
top_k sets the number of returned sources (default 5, maximum 20).
Allow the candidate pool to be deeper than the return limit so reranking
can promote a passage from further down. Keep every reranker’s
top_n at or below the candidate depth.
One retriever (identity)¶
A single retriever requires identity. It passes that ranking
through. For example, start with dense and
{"node": "identity", "params": {"candidate_top_k": 30}}.
Merge by rank (rrf)¶
Reciprocal rank fusion combines candidates by position in each list.
Use it when scores from cosine similarity and lexical search have
different scales. k defaults to 60. Optional
retriever_weights assigns a weight to each retriever in its listed
order. Omitting weights gives equal contributions.
Merge by normalized score (relative_score)¶
This node scales each retriever’s list of scores into its own common
range before combining them. It preserves how far the leading candidates
scored above the rest of each list. Compare it with RRF on your corpus.
retriever_weights works as in RRF. Two or more different retriever
kinds require one of these merge nodes.
For a dense and lexical baseline, use this fragment of pipeline config. Keep the existing chunker and other settings when applying it:
{
"retrievers": [{"node": "dense"}, {"node": "bm25"}],
"fusion": {
"node": "relative_score",
"params": {"candidate_top_k": 30, "retriever_weights": [1, 1]}
}
}
Split search into independent branches¶
For a question about the TR-12, use BM25 on the original wording to keep the equipment code and dense search on rephrased questions to find instructions that use different terms.
Original question
Where is the reset switch on the TR-12?
Exact terms
BM25 searches for terms in the original question.
Expanded meaning
Rephrase the question, run dense search on the new formulations and combine their rankings using RRF.
Merge the branch rankings
Shared RRF builds the candidate pool. Reranking follows if configured.
Configure the two paths and their merge in the pipeline editor. To do the same through the API, apply this configuration fragment.
{
"query_branches": [
{
"id": "exact-terms",
"retrievers": [{"node": "bm25"}],
"fusion": {"node": "identity"},
"weight": 1
},
{
"id": "expanded-meaning",
"query_transform": [{"node": "rephrase", "params": {"rephrasings": 2}}],
"retrievers": [{"node": "dense"}],
"fusion": {"node": "identity"},
"max_queries": 2,
"weight": 1
}
],
"branch_fusion": {"node": "rrf", "params": {"candidate_top_k": 30}},
"branch_concurrency": 2
}
Each branch starts from the original question and has its own transforms,
retrievers and fusion. With query_branches configured, the branch lists
replace the top-level transform and retriever lists. The shared
rerank, generate and postgeneration run after the final merge.
A branch with transforms searches its changed formulations and combines
their rankings with RRF. It skips retrieval if no changed formulation
remains. Keep an untransformed branch to search the original question.
Top-level asked_lead and subquestion_passages ordering applies
only without branches.
Keep at least one branch active and give each branch a unique,
nonempty ID. A weight of zero disables the branch. max_queries
defaults to 1 and limits additional formulations per branch.
branch_concurrency defaults to 2. Set final merge weights on the
branches themselves, and use rrf (the default) or relative_score
for branch_fusion. Branches share physical indexes within the
space. If several branches use the same retriever kind, keep its
shared-index settings consistent. A successful branch can still return
results if another branch fails. When a path seems to contribute nothing,
inspect branch_trace in the search or pipeline answer response, or in
the stream’s final done event. Each entry identifies branch_id and
its status (success, skipped, or failed) and carries
queries, hit_count and any error_type.
Branch configuration · Compatibility validation · Branch planning · Branch outcomes