Hybrid search with citations: how a knowledge base finds the passage
· By Bee Flow · 4 min read
Every knowledge-base search runs pgvector and Postgres full text side by side, fuses the results, reranks them with a cross-encoder and returns citations that point at a page. How each step works.

A knowledge base in Bee Flow has no search mode to choose, not per instance, not per base and not per query. Every search runs the same pipeline, and your configuration only decides which reranker it can reach. The code is in server/core/kb/.
Getting text in
Documents are cut into chunks of up to 800 tokens (KB_PER_CHUNK_TOKENS). Byte-identical chunks are skipped, and a document within a simhash Hamming distance of 3 of an existing one counts as a near-duplicate. Each chunk is embedded by the configured provider, or on CPU with multilingual-e5-small when there is none, and written to a kb_chunks table with a pgvector column. That column takes the dimension of the first model you ingest with, up to the index limit of 2000. Vectors from different models are not comparable, so a switch of embedding model means embedding the existing content again.
When Privacy Shield covers knowledge bases, personal data can be replaced before the text enters the base. Studio marks such a document as "shielded".
Two retrievers in parallel
Vector and keyword retrieval always run at the same time. The vector leg is a cosine scan with pgvector's <=> operator, with a floor of 0.35 below which a chunk counts as noise. The keyword leg is Postgres full text, queried with both the Dutch and the simple configuration, so stemming helps Dutch text and exact tokens still match:
SELECT id, title, content, source_uri, document_id, chunk_id, chunk_type, page_start,
GREATEST(
ts_rank_cd(tsv, websearch_to_tsquery('dutch', $1)) * 1.5,
ts_rank_cd(tsv, websearch_to_tsquery('simple', $1))
) AS fts_score
FROM kb_chunks
WHERE knowledge_base_id = ANY($2::text[])
AND (tsv @@ websearch_to_tsquery('dutch', $1)
OR tsv @@ websearch_to_tsquery('simple', $1))
ORDER BY fts_score DESC
LIMIT 15
The query words are joined with AND first, and when that finds nothing the search retries with OR. A failure in either leg is logged and returns no rows, and the other leg still answers.
Fusing and reranking
The two lists are merged with reciprocal rank fusion (k = 60). For a query of one or two words the keyword list counts double, because a single term like "phishing" is matched better by an exact keyword than by an embedding. Table-of-contents chunks are scored down, since they match many keywords and say nothing, and a chunk whose heading contains query words is scored up. When a hit is part of a table, the chunks either side of it come along so the agent sees the whole table.
The top candidates then go to the first reranker that is configured and answers, in this order:
- llama.cpp's
/v1/rerankwithbge-reranker-v2-m3, when you switch it on - A provider rerank model, such as IONOS's
Qwen/Qwen3-VL-Reranker-8Bor a vLLM endpoint - Azure's Cohere reranker
- An in-process cross-encoder,
Xenova/bge-reranker-base(MIT), through Transformers.js - An external reranker at
RERANKER_URL - The fused order as it is
The CPU cross-encoder is on by default and runs inside the Node process, with no Python and no GPU. Its model is downloaded on first use and cached in the server's data directory, and cpu_reranker_enabled = false switches it off. llama.cpp returns raw logits, which we pass through a sigmoid so that the 0 to 1 relevance thresholds further down keep their meaning.
A reranker only decides the order. It reorders the original rows and keeps their ids, which the citations need.
Citations
Every surface that shows where an answer came from uses one citation shape: the document title, document and chunk ids, the page when the chunker knew it, a row range for a table, the date for a meeting note, the section heading, the passage itself and a relative score. The ids are what let a citation say "Personnel handbook, p. 12" and open that document.
The model receives the sources as numbered blocks:
### Source 1: Q3-2025-Report.pdf
…3 sentences from the chunk…
With source references switched on for an agent, citations render as cards below the answer, and the model is told not to put [1] markers in its prose. Clicking a card opens the document. In Studio's Test question tab a passage gets a bar relative to the best hit in the same answer, never a percentage.
Access is checked before retrieval, and the check can only remove bases. Someone who may not see a base gets the same answer with that base left out, never an error.
The knowledge base docs list the settings, and the IONOS guide shows how to set up its reranker. The platform page shows where knowledge bases fit in, and a knowledge base from your own documents covers them from the user's side.
To see the pipeline at work on your own documents, put a handful of files in a knowledge base and ask a question in the Test question tab. The passages it found appear there before the answer. Knowledge bases are in every licence, including the free one. Install Bee Flow yourself, or plan a call if you would like to see it first. To try Bee Flow without installing anything, open the live demo, and Bee Flow vs Open WebUI sets the two side by side.