On this page
Transform a question¶
Add a transform when the relevant passage misses the candidate pool. Compare retrieval for the same questions before and after the change. Transforms run at query time, so keep the existing document index. The reranker and generator still receive the original question.
Put the node in the pipeline’s query_transform list or in a
query branch. See the pipeline catalog for all fields.
Model-backed nodes inherit the space’s settings and provider credentials.
Set model, api_base or temperature to override those settings.
The fallback to the original question and the ranking rules for
asked_lead and subquestion_passages below apply to the top-level
transform list. Inside a branch, final retrieval uses only changed
formulations and merges their results through the branch path. Add an
untransformed branch to keep searching the original question when a
rewrite succeeds or yields no changed text.
Dictionary expansion (dictionary)¶
To make a term searchable by an abbreviation, open Space dictionary and choose Create entry. Enter “pressure sensor” as the Canonical name and “PS” under Aliases (one per line). Choose Published and click Save. You can also extract names and aliases from documents.
In the pipeline builder, choose Add original and dictionary branches
if the pipeline has no branches yet. The original branch starts with
an empty transform list, and the dictionary branch starts with only
dictionary. Move any top-level transforms you still need into the
branches where they should run. If branches already exist, add
Dictionary transformation to the branch where you want expansion.
Save the pipeline and test a question that uses “PS”. The transform
reads published entries at query time. In the result, open
Search and evidence trace and check the selected entry IDs and
resulting query in Dictionary transformation. The API exposes
these details in dictionary_trace.
An API client with permission to add documents to the space can send
POST /api/v1/spaces/{space_id}/dictionary with
{"canonical":"pressure sensor","aliases":["PS"],"status":"published"}.
Use this pipeline entry for the rules mode.
{"node": "dictionary", "params": {"mode": "rules"}}
Use published dictionary entries for domain terminology, product aliases
and abbreviations. With mode="rules" (the default), the transform
preserves the question and adds matched meanings without a model call.
Russian matches can use known unambiguous inflections. Other languages
use exact phrases and explicit aliases. Acronyms and codes retain case.
In mode="llm", the model rewrites the question using only the selected
dictionary entries and the node’s prompt. It needs a model. The
default limits are max_entries=20, max_input_chars=8000 and
max_tokens=512 for model output. When there is no usable match,
the original question proceeds unchanged.
Hypothetical passage (hyde)¶
Use HyDE when the question and its supporting text are phrased differently. The model writes a hypothetical passage in answer to the question and the retrievers search with that text. It is a search hint. Check the real sources separately.
hyde_mode="substitute" (the default) searches the generated passage
alone. augment searches both forms and keeps the first asked_lead
original-query hits ahead of the combined ranking. asked_lead defaults
to 1 and accepts 0. The node uses its prompt and a max_tokens
ceiling that defaults to the space’s fragment length. An empty model reply
leaves the question unchanged. A provider refusal can fail the query.
For a symptom described differently in maintenance instructions, start with augmentation so you can retain useful exact matches:
{"node": "hyde", "params": {"hyde_mode": "augment", "asked_lead": 1}}
Question splitting (decompose)¶
Use this for a question that needs evidence from several places, such as
“Which equipment requires quarterly checks, and who signs the record?”
The model plans subquestions. Retrieval still includes the original.
The combined list keeps its first asked_lead hits (1), then the first
subquestion_passages hits from each subquestion (1), then the rest.
Duplicated sources appear once and the resulting score follows rank.
Place this node first. In split_decision="separate" (the default), a
short decision call uses decide_prompt and decide_max_tokens=16.
in_plan lets the planning call decide. Set max_subquestions
(default 3) and use prompt to tune splitting while keeping the
platform’s expected response structure. The default
split_mode="chain" resolves dependencies using resolve_prompt
and up to chain_passages=2 passages from an earlier search.
parallel uses the independent questions and drops dependent ones.
If planning fails, the original question is searched.
{"node": "decompose", "params": {"split_mode": "parallel"}}
Alternative wording (rephrase)¶
Use this when documentation uses synonyms for the same concept. The model
generates up to rephrasings=3 alternatives under prompt and
rephrase_max_tokens=256. The platform searches the original and each
distinct wording. The first asked_lead original hits (1) stay ahead
of a rank-fusion vote over the remaining candidates. A failed or empty
rewrite falls back to the original question.
For example, ask for two alternatives to “How do I restart the control unit?” and compare whether the search also finds “power cycle” instructions:
{"node": "rephrase", "params": {"rephrasings": 2}}
Place it before HyDE and use it once per path.
Expansion from early results (feedback)¶
Use feedback to pick up specialist terms from the corpus without a
generative model. It first searches the original question, then adds
terms from up to feedback_passages=10 leading results. It selects at
most expansion_terms=10 terms, omitting common English and Russian
grammar words and terms already in the question. Final retrieval combines
the original and the expanded search, with asked_lead=1 original
hits kept ahead. Choose a clean candidate set: irrelevant early results
can steer the expansion away from the topic.
{"node": "feedback", "params": {"feedback_passages": 5}}
Place it before HyDE and use it once per path. Preflight warns if the requested feedback depth exceeds the fusion candidate depth.
Keep the contribution visible¶
Transforms run in order. In the top-level transform list, keep
asked_lead below the number of hits the next stage uses so that
additional searches can contribute. Use
branches when you want multiple independent formulations. For example,
let a plain lexical branch look for an exact model code while a HyDE
branch looks for descriptions of the same error. See
Retrieve and combine passages for branch budgets and merging.