FTS5 全文搜索
Synapse 如何使用 SQLite FTS5 实现亚毫秒级的全文记忆搜索。
FTS5 全文搜索
Synapse 使用 FTS5（Full-Text Search 5）实现快速、灵活的记忆搜索。本页介绍其工作原理以及如何高效使用。
什么是 FTS5？
FTS5 是一个 SQLite 扩展（也可通过扩展在 PostgreSQL 中使用），提供全文搜索能力。它能够：
- 为文本内容建立索引以实现快速关键词搜索
- 支持布尔运算符（AND、OR、NOT）
- 支持用引号进行短语匹配
- 支持用
*进行前缀匹配 - 按相关性对结果排序
Synapse 使用 FTS5 为所有记忆内容建立索引，可在数千条记忆上实现亚毫秒级搜索。
Synapse 如何使用 FTS5
当你 POST /memory 时：
- 记忆内容存储到
memories表 - 内容也插入到 FTS5 虚拟表
- FTS5 自动分词并建立索引
当你 GET /memory/search?q=... 时：
- Synapse 使用 FTS5 语法解析查询
- 对 FTS5 索引执行
MATCH - 按
mind_id过滤（租户隔离） - 返回排序后的结果
查询语法
简单关键词搜索
?q=docker返回包含 "docker" 的记忆。
多关键词（隐式 AND）
?q=docker+swarm
?q=docker%20swarm返回同时包含 "docker" 和 "swarm" 的记忆。
短语匹配
?q="docker+swarm"
?q=%22docker%20swarm%22返回包含完整短语 "docker swarm" 的记忆。
前缀匹配
?q=docker*返回包含以 "docker" 开头的词的记忆（例如 "dockers"、"dockerfile"、"dockerize"）。
布尔 OR
?q=docker+OR+kubernetes返回包含 "docker" 或 "kubernetes" 的记忆。
布尔 NOT
?q=docker+-swarm
?q=docker+NOT+swarm返回包含 "docker" 但不包含 "swarm" 的记忆。
分组
?q=(docker+OR+kubernetes)+-test返回包含 "docker" 或 "kubernetes" 但不包含 "test" 的记忆。
实用示例
查找关于某个项目的记忆
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
"https://synapse.schaefer.zone/memory/search?q=synapse+deployment"查找精确短语
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
"https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22"排除测试记忆
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
"https://synapse.schaefer.zone/memory/search?q=production+-test"按技术查找
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
"https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql"排序
FTS5 使用 BM25 算法按相关性排序。影响因素：
- 词频（词条出现频率）
- 逆文档频率（更稀有的词条排名更高）
- 文档长度（包含该词条的较短文档排名更高）
- 列权重（标题 > 内容）
结果按相关性返回（最相关的在前）。
性能
| 操作 | 延迟 |
|---|---|
| 搜索 100 条记忆 | < 5ms |
| 搜索 1,000 条记忆 | < 10ms |
| 搜索 10,000 条记忆 | < 25ms |
| 搜索 100,000 条记忆 | < 100ms |
FTS5 针对读密集型工作负载做了高度优化。
局限性
词干提取
FTS5 默认不做词干提取。"running" 和 "run" 是不同的词条。
变通方案： 使用前缀匹配：?q=run*
拼写容错
FTS5 不支持模糊匹配。拼写错误会返回零结果。
变通方案： 使用语义搜索（/memory/semantic-search）进行概念匹配。
停用词
常见词（the、a、an、is）会被索引，但对搜索意义不大。FTS5 会自动处理。
FTS5 与语义搜索对比
| 方面 | FTS5 | 语义搜索 |
|---|---|---|
| 速度 | 亚毫秒级 | 50-100ms |
| 匹配方式 | 精确关键词 | 概念 |
| 拼写容错 | 无 | 一定程度 |
| 词干提取 | 无 | 隐式 |
| 是否需要嵌入 | 否 | 是 |
| 适合场景 | 具体术语 | 概念 |
当你知道关键词时使用 FTS5。当你想找“关于 X 的记忆”且 X 用不同方式描述时，使用语义搜索。