Hyperresearch FTS5全文搜索实现详解状态感知的排序策略让检索更聪明【免费下载链接】hyperresearchAgent-driven research knowledge base. Agents collect, search, and synthesize web research into a persistent, searchable wiki.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperresearchHyperresearch是一个由 AI Agent 驱动的研究知识库Agent 负责收集、抓取并综合网络研究资料沉淀为持久化、可全文搜索的 Wiki。它的核心检索能力建立在 SQLite 的FTS5 全文搜索引擎之上——但真正让它与众不同的是状态感知的排序策略同一个关键词常青笔记会被加权置顶已弃用的内容则自动沉底。本文带你无需深入代码也能看懂这套搜索是怎么工作的。 索引层一张表管住全部笔记Hyperresearch 在初始化数据库时创建了一张 FTS5 虚拟表notes_fts见 core/db.py它把每篇笔记拆成 5 个字段分别建索引字段内容是否参与排序权重id笔记 ID否仅用于关联主表title标题✅ 权重最高body_plain正文纯文本✅ 权重最低tags标签✅aliases别名✅分词器选用porter unicode61既支持中文等 Unicode 字符又能做英文词干还原——搜 running 能匹配到 run。笔记内容每次同步都会增量刷新这张索引表见 core/sync.py保证搜索永远是所见即所存。 查询预处理让随手一搜变成合法搜索用户输入往往很随意preprocess_query函数search/fts.py在查询送入 FTS5 前做了三件贴心事前缀匹配搜python自动变成python*能同时命中 Python、Pythonic、pythonic 等词形不必拼完整单词字母数字粘合拆分gpt4o会被拆成gpt 4 omamba3拆成mamba 3——这对搜模型名、版本号特别有用短语与操作符保护双引号短语保持精确匹配AND / OR / NOT / NEAR等 FTS5 原生操作符则原样直通高级用户不被好心办坏事。所有裸词还会被剥掉* ( ) { } 等会破坏 FTS5 语法的特殊字符——这意味着普通用户随便打什么都不会把搜索引擎打崩。⚖️ 状态感知排序本文的核心单纯的全文搜索只回答哪里提到了这个词而研究知识库还需要回答哪个结果现在仍然可信。Hyperresearch 的排序分三层前两层由 SQL 直接完成第一层BM25 字段加权SQLite FTS5 内置的bm25()打分函数按字段加权权重可在配置中调整默认值见 core/config.py标题 ×10 标签 ×5 别名 ×3 正文 ×1直觉很简单标题命中比正文命中更相关一篇笔记标题就写着你要找的关键词理应排在只在正文角落提了一嘴的笔记前面。第二层status 状态调整状态感知的灵魂每篇笔记都有生命周期状态取出 BM25 排序后的结果集再按状态对分数做乘性调整search/fts.py笔记状态含义分数调整默认evergreen常青内容长期有效×1.5 加权⚠️stale可能过时×0.7 轻微惩罚deprecated已弃用×0.3 大幅惩罚也就是说一篇弃用笔记哪怕 BM25 相关性再高分数也会被压到只有常青笔记的三分之一左右自动沉到结果列表底部。这正是状态感知四个字的含义排序策略感知了知识的新鲜度与可信度而不只是字面匹配。第三层来源质量重排可选加上--ranked参数后再叠加一层来源质量分重排分数乘以0.5 quality_score。设计很克制——没有质量分的笔记按中性 1.0 倍处理保证它们不会被冤枉而顶级权威来源≈1.0 分的笔记得分约为被撤稿来源≈0.05 分的近三倍。相关性是入场券权威性决定最终名次。️ 错误处理设计坏查询绝不伪装成没有结果这是实现里一个容易被忽略但很关键的细节。传统写法中查询语法错误、索引损坏都会被吞掉、返回空列表——用户看到无结果根本分不清是库里没有还是系统坏了。Hyperresearch 明确区分了三种情况配套测试见 tests/test_search/test_fts.py无可搜索词如***、空查询→ 抛出SearchQueryError提示请至少提供一个词合法查询但无命中→ 正常返回空列表这才是真正的没搜到FTS 索引损坏/缺失→ 直接向上抛出底层错误绝不伪装成空结果。对知识必须可信的研究工具来说查无结果和系统坏了是两种性质完全不同的信号这个设计保证了前者的语义永远干净。 过滤组合拳从全文搜索到精确定位全文匹配之外search/filters.py 提供了结构化过滤器与 FTS 查询叠加成WHERE条件属性过滤标签、状态、笔记类型、认知层级tier、内容种类content_type、时间范围、路径通配符、字数区间图谱过滤linked_from/linked_to沿双向链接找笔记、min_inbound找被引用次数达标的枢纽笔记、has_backlinks只留有反链的内容——这让搜索从文字平面延伸到了知识图谱维度。 快速上手安装后在任何包含 vault 的目录下# 基础全文搜索默认 20 条自动应用状态感知排序 hyper search python async # 叠加标签与状态过滤 hyper search memory --tag rust --status evergreen # 启用来源质量重排 JSON 输出Agent 常用 hyper search transformer --ranked --json命令行入口在 cli/search.py还支持--semantic语义混合搜索用 RRF 把向量相似度与 FTS 排名融合以及--max-tokens按 Token 预算截断结果专为 Agent 消费场景设计。 相关文件导航核心搜索实现src/hyperresearch/search/fts.py结构化过滤器src/hyperresearch/search/filters.pyFTS5 索引表定义src/hyperresearch/core/db.py排序权重默认配置src/hyperresearch/core/config.py搜索命令行入口src/hyperresearch/cli/search.py行为测试用例tests/test_search/test_fts.py总结Hyperresearch 的 FTS5 全文搜索 宽进严出的查询预处理BM25 字段加权状态感知的生命周期调整可选的来源质量重排再配上错误绝不伪装成空结果的严谨语义。四层排序层层递进让研究知识库的每一次搜索都同时回答哪里提到了与哪个结果值得信——这就是状态感知排序策略的全部价值。【免费下载链接】hyperresearchAgent-driven research knowledge base. Agents collect, search, and synthesize web research into a persistent, searchable wiki.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperresearch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考