WeKnora/website-docs/04-api
lyingbug 9fc08c2079
feat(retrieval): unify rerank across search APIs and expose diagnostics (#3675)
* feat(retrieval): unify rerank across search APIs and expose diagnostics

The two retrieval APIs each missed half of the job: hybrid-search could
tune recall but never reranked, knowledge-search always reranked with the
tenant config and exposed no recall parameters. Rerank itself lived in
four places with drifting thresholds, passages and composite scores.

- internal/reranking: one rerank stage (passage = title + cleaned body +
  captions/OCR + generated questions, threshold with degradation and
  top-1 fallback, composite score, MMR) used by the chat pipeline, the
  agent search_knowledge tool and both APIs.
- hybrid-search: optional `rerank` object; absent keeps the old behavior.
- knowledge-search: vector/keyword thresholds, match_count, recall-path
  switches and a `rerank` object that can override or disable rerank.
- Rerank model resolution: request > tenant RetrievalConfig > first
  rerank model; an unknown requested model is a 400. Load or call
  failures degrade to retrieval order instead of failing the search.
- Responses carry meta.rerank (outcome, model, thresholds, top score) so
  an empty result explains itself (#2391).
- Go SDK and website-docs updated, including a "which API" section.

Refs #2976

* docs(retrieval): lead with which search API to use and when

knowledge-search is the default for callers; hybrid-search is the
low-level recall interface. Add a scenario table so the choice does not
hinge on reading the whole capability comparison.
2026-09-24 20:41:49 +08:00
..
01-api-overview.md feat(retrieval): unify rerank across search APIs and expose diagnostics (#3675) 2026-09-24 20:41:49 +08:00
02-api-agent-mcp.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
02-api-auth.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
02-api-channels.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
02-api-chat.md feat(retrieval): unify rerank across search APIs and expose diagnostics (#3675) 2026-09-24 20:41:49 +08:00
02-api-chunks.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
02-api-faq-wiki.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
02-api-infra.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
02-api-knowledge.md feat(retrieval): unify rerank across search APIs and expose diagnostics (#3675) 2026-09-24 20:41:49 +08:00
02-api-memory.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
02-api-model-system.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
02-api-org.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
02-api-sandbox-skills.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00
02-api-system.md feat(models): add system admin model catalog console (#3662) 2026-09-24 16:31:45 +08:00
02-api-tenant.md docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) 2026-09-24 11:26:34 +08:00