Cherry Studio 知识库检索模式变更移除 vector/BM25/hybrid 手动选择与 alpha 滑杆改为基于 Embedding 模型的自动推导【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本文是一份面向 Cherry Studio 开发者的知识库Knowledge Base检索模式变更技术指南聚焦 v2 重构中 RAG 检索配置的简化RAG 设置面板不再提供搜索模式选择器vector / bm25 / hybrid与 hybrid alpha 滑杆检索模式改为由知识库是否配置 Embedding 模型自动推导。读完本文你将掌握新检索模式推导规则、BM25 与 RRF 融合检索的底层机制、relevance 阈值过滤的新语义以及 v1 知识库迁移后哪些配置会被保留、哪些会被丢弃。变更概述在 2026-07-04 合并的 PR编号#16699中Cherry Studio 移除了知识库 RAG 设置中的两项人工配置搜索模式选择器此前允许用户为每个知识库手动固定vector纯向量、bm25纯词法或hybrid混合三种检索模式hybrid alpha 滑杆此前允许用户手动调整混合检索中 BM25 与向量结果的融合权重。移除之后检索模式由知识库是否配置 Embedding 模型这一事实自动决定不再存储为可调偏好未配置 Embedding 模型的知识库 →仅 BM25 检索已配置 Embedding 模型且向量契约有效的知识库 →hybrid 检索BM25 向量采用 RRF 融合。relevance 阈值threshold设置仍然保留但仅在知识库选择了 rerank 模型时显示并且只作用于带有 relevance 分数的重排结果。本变更对应的正式迁移说明位于 v2-refactor-temp/docs/breaking-changes/2026-07-04-knowledge-retrieval-mode-removed.md配套的知识库服务文档见 docs/references/knowledge/knowledge-service.md。变更前后对比维度变更前变更后搜索模式选择器vector / bm25 / hybridRAG 设置面板中手动选择移除由 Embedding 模型配置自动推导hybrid alpha 滑杆手动调节 BM25 与向量融合权重移除固定使用 RRF 融合无 Embedding 模型的知识库可手动固定为 BM25自动为 BM25-only 检索有 Embedding 模型的知识库可手动固定为 vector / hybrid 并调 alpha自动为 hybrid 检索BM25 向量 RRFrelevance 阈值对检索结果统一过滤仅当配置了 rerank 模型时可见且仅过滤relevance分数的结果已迁移 v1 知识库保留历史 search mode / hybrid alpha两者被丢弃有效的阈值threshold值保留变更的核心思路是检索模式不再是一种用户偏好而是一种可由知识库配置推导出的运行期事实。从源码结构看检索模式每次搜索调用时都会重新计算因此永远不会与知识库的 Embedding 模型配置漂移失步。自动推导的源码级实现新的推导逻辑位于查询服务 src/main/features/knowledge/query/KnowledgeQueryService.ts 的search方法中// Vector/hybrid retrieval needs an embedding model; a base without one is // BM25-only. This is a fixed runtime policy, not a stored preference — mode is // computed fresh every call, so it can never drift out of sync with the base. const mode isCompletedVectorKnowledgeBase(base) ? hybrid : bm25 // BM25 is lexical only; skip the embedding round-trip when the query wont use it. const queryEmbedding mode bm25 ? undefined : await embedKnowledgeQuery(base, query)关键点推导入口isCompletedVectorKnowledgeBase(base)判定知识库是否处于completed状态且具备有效的 Embedding 模型与向量维度embeddingModelId与dimensions同时非空见 src/shared/data/types/knowledge.ts 中的实体不变式约束。每次调用实时计算模式不是持久化字段而是每次knowledge.search时新鲜计算天然避免配置过期。性能细节BM25-only 模式直接跳过embedKnowledgeQuery的 Embedding 模型推理往返纯词法检索不产生额外模型调用。在索引存储层面引擎能力类型仍保留三种模式 src/main/features/knowledge/pipeline/vectorstore/indexStore/model.tsexport type KnowledgeIndexSearchMode vector | bm25 | hybrid但产品层策略只向引擎传递bm25或hybrid两种模式vector纯向量仅作为引擎底层能力保留带独立测试覆盖不再作为用户可选的检索模式暴露。hybrid 检索的 RRF 融合机制此前用户通过 alpha 滑杆调节混合检索中向量结果占比注释中明确记录了 0 纯 BM251 纯向量默认 0.5见 src/main/features/knowledge/pipeline/vectorstore/indexStore/model.ts。新策略移除 alpha 后融合固定采用RRFReciprocal Rank Fusion倒数排名融合BM25 通道基于search_text_fts全文索引召回对短 CJK token 存在 LIKE 兜底向量通道对查询 Embedding 执行余弦相似度扫描两条通道的结果按排名倒数加权融合为最终排序。索引存储层的行为由 src/main/features/knowledge/pipeline/vectorstore/indexStore/KnowledgeIndexStore.ts 实现其 RRF 融合逻辑有独立的单元测试 src/main/features/knowledge/pipeline/vectorstore/indexStore/tests/KnowledgeIndexStore.rrf.test.ts 与搜索测试 src/main/features/knowledge/pipeline/vectorstore/indexStore/tests/KnowledgeIndexStore.search.test.ts 验证。需要说明的是当前实现的相似度检索是暴力扫描而非 ANN 索引embedding表直接按 sqlite-vec 的vec_distance_cosine排序查询向量以原始小端 float32 BLOB 绑定。这意味着单知识库的检索成本大致随向量行数线性增长这是当前的实现边界而非可扩展的索引化 ANN 保证详见 docs/references/knowledge/knowledge-service.md 的 Current Retrieval Cost Assumption 一节。阈值过滤的新语义scoreKind 与 relevance变更最容易被忽视的部分是阈值threshold的语义收窄。搜索管道将结果分数分为两类定义在 src/main/features/knowledge/query/search.tsexport const getInitialSearchScoreKind (mode: KnowledgeIndexSearchMode): KnowledgeSearchScoreKind { return mode vector ? relevance : ranking } export const applyRelevanceThreshold ( results: KnowledgeSearchResult[], threshold DEFAULT_SEARCH_THRESHOLD ): KnowledgeSearchResult[] { return results.filter((result) result.scoreKind ! relevance || result.score threshold) }分数类型scoreKind取值为relevance或rankingsrc/shared/data/types/knowledge.tsrelevance仅由向量余弦相似度产生同类结果之间具有可比的相似度语义ranking由取负的 BM25 分数和 RRF 分数产生其量纲不可与向量 relevance 分数相互比较。因此applyRelevanceThreshold的实现刻意只过滤scoreKind relevance的结果ranking分数直接放行——这就是阈值仅对带 relevance 分数的重排结果生效的代码级含义。在完整搜索流水线 src/main/features/knowledge/query/KnowledgeQueryService.ts 中KnowledgeService.search依次执行拒绝failed状态的知识库拒绝无可搜索 token 的查询由知识库配置推导检索模式仅对 hybrid 模式计算查询 Embedding以超额拉取上限topK × 5封顶 200 条候选调用KnowledgeIndexStore.search过滤掉源材料缺失、跨库或处于deleting的命中裁剪到documentCount ?? 10当配置了rerankModelId时执行重排重排在裁剪前执行保证重排器看到完整候选集仅对relevance分数应用threshold过滤分配排名rank。对用户的影响与操作指引变更影响此前将知识库固定在纯向量检索、或自定义了 hybrid alpha 的用户将无法再在 RAG 设置面板中找到对应控件已配置 Embedding 模型的知识库检索行为可能发生变化从可调 alpha 的混合权重变为固定的 RRF 融合阈值控件仅对配置了 rerank 模型的知识库可见因为此时分数才是可比较的 relevance 分数。用户需要做什么无需任何手动操作自动生效。若希望继续使用阈值过滤请在知识库设置中选择一个 rerank 模型。对 v1 迁移库的影响v1→v2 迁移后任何此前配置的 search mode 与 hybrid alpha 均被丢弃合法的阈值在 01 范围内的数值见 src/shared/data/types/knowledge.ts 中KnowledgeThresholdSchema z.number().min(0).max(1)会被保留。迁移时若原库的 Embedding 模型无法在迁移后的user_model表中解析知识库会被标记为failed/missing_embedding_model或missing_vector_store需要通过knowledge.restore_base选择有效 Embedding 模型重建为completed库详见 docs/references/knowledge/knowledge-service.md 的 Recoverable Migrated Bases 一节。对发布管理Release Manager的说明本变更同步更新了知识库服务文档 docs/references/knowledge/knowledge-service.md其中 Search 一节已改写为自动检索模式推导的完整描述含模式推导、超额拉取、RRF 融合、scoreKind 与阈值过滤、rerank 步骤可作为本变更的行为规范参考。查询侧的行为由 src/main/features/knowledge/query/search.ts 的单元测试与 src/main/features/knowledge/query/tests/search.test.ts 覆盖回归发布前建议重点验证BM25-only 库跳过 Embedding 调用、hybrid 库 RRF 融合结果、以及阈值对ranking分数不生效三条关键路径。延伸阅读知识库服务整体架构持久化、IPC、ingestion、检索、Concept ID、Agent 工具docs/references/knowledge/knowledge-service.md知识库工作流架构概览docs/references/knowledge/workflow-architecture.md工作流运行守卫docs/references/knowledge/operation-guards.md共享知识库类型契约实体、状态机、搜索结果结构src/shared/data/types/knowledge.ts查询服务与搜索管道实现src/main/features/knowledge/query/KnowledgeQueryService.ts、src/main/features/knowledge/query/search.ts索引存储与 RRF 融合实现src/main/features/knowledge/pipeline/vectorstore/indexStore/KnowledgeIndexStore.ts、src/main/features/knowledge/pipeline/vectorstore/indexStore/model.ts【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考