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

FTS5 全文搜索

\n

Synapse 使用 FTS5（Full-Text Search 5）实现快速、灵活的记忆搜索。本页介绍其工作原理以及如何高效使用。

\n

什么是 FTS5？

\n

FTS5 是一个 SQLite 扩展（也可通过扩展在 PostgreSQL 中使用），提供全文搜索能力。它能够：

\n\n

Synapse 使用 FTS5 为所有记忆内容建立索引，可在数千条记忆上实现亚毫秒级搜索。

\n

Synapse 如何使用 FTS5

\n

当你 POST /memory 时：

\n
    \n
  1. 记忆内容存储到 memories 表
    2. \n
  2. 内容也插入到 FTS5 虚拟表
    3. \n
  3. FTS5 自动分词并建立索引
    4. \n
\n

当你 GET /memory/search?q=... 时：

\n
    \n
  1. Synapse 使用 FTS5 语法解析查询
    2. \n
  2. 对 FTS5 索引执行 MATCH
    3. \n
  3. 按 mind_id 过滤（租户隔离）
    4. \n
  4. 返回排序后的结果
    5. \n
\n

查询语法

\n

简单关键词搜索

\n
?q=docker

返回包含 "docker" 的记忆。

\n

多关键词（隐式 AND）

\n
?q=docker+swarm\n?q=docker%20swarm

返回同时包含 "docker" 和 "swarm" 的记忆。

\n

短语匹配

\n
?q="docker+swarm"\n?q=%22docker%20swarm%22

返回包含完整短语 "docker swarm" 的记忆。

\n

前缀匹配

\n
?q=docker*

返回包含以 "docker" 开头的词的记忆（例如 "dockers"、"dockerfile"、"dockerize"）。

\n

布尔 OR

\n
?q=docker+OR+kubernetes

返回包含 "docker" 或 "kubernetes" 的记忆。

\n

布尔 NOT

\n
?q=docker+-swarm\n?q=docker+NOT+swarm

返回包含 "docker" 但不包含 "swarm" 的记忆。

\n

分组

\n
?q=(docker+OR+kubernetes)+-test

返回包含 "docker" 或 "kubernetes" 但不包含 "test" 的记忆。

\n

实用示例

\n

查找关于某个项目的记忆

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=synapse+deployment"

查找精确短语

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22"

排除测试记忆

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=production+-test"

按技术查找

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql"

排序

\n

FTS5 使用 BM25 算法按相关性排序。影响因素：

\n\n

结果按相关性返回（最相关的在前）。

\n

性能

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
操作延迟
搜索 100 条记忆< 5ms
搜索 1,000 条记忆< 10ms
搜索 10,000 条记忆< 25ms
搜索 100,000 条记忆< 100ms
\n

FTS5 针对读密集型工作负载做了高度优化。

\n

局限性

\n

词干提取

\n

FTS5 默认不做词干提取。"running" 和 "run" 是不同的词条。

\n

变通方案： 使用前缀匹配：?q=run*

\n

拼写容错

\n

FTS5 不支持模糊匹配。拼写错误会返回零结果。

\n

变通方案： 使用语义搜索（/memory/semantic-search）进行概念匹配。

\n

停用词

\n

常见词（the、a、an、is）会被索引，但对搜索意义不大。FTS5 会自动处理。

\n

FTS5 与语义搜索对比

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
方面FTS5语义搜索
速度亚毫秒级50-100ms
匹配方式精确关键词概念
拼写容错无一定程度
词干提取无隐式
是否需要嵌入否是
适合场景具体术语概念
\n

当你知道关键词时使用 FTS5。当你想找“关于 X 的记忆”且 X 用不同方式描述时，使用语义搜索。

\n

最佳实践

\n

下一步

\n\n","urls":{"html":"/docs/concepts/fts5-search","text":"/docs/concepts/fts5-search?format=text","json":"/docs/concepts/fts5-search?format=json","llm":"/docs/concepts/fts5-search?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}