Skip to main content

语义搜索（向量嵌入）

advanced 🤖 LLM 友好 1 分钟 · 221 字 更新于： 2026-06-27 中文

使用向量嵌入进行概念性记忆搜索 — 按意义查找，而非仅按关键词。

阅读本文： 📄 纯文本 ⚡ JSON 🤖 LLM 格式
语言: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

语义搜索（向量嵌入）

Synapse 支持基于向量嵌入的语义搜索。与 FTS5（关键词匹配）不同，语义搜索按意义查找记忆 — 即使没有关键词匹配也能找到。

工作原理

1. 记忆存储 → 生成嵌入 → 存储向量
2. 搜索查询 → 生成嵌入 → 比较向量
3. 余弦相似度 → 返回前 N 个结果

什么是嵌入？

嵌入是文本的数值向量表示。意义相近的文本有相近的向量。Synapse 为每条记忆的内容生成一个向量（例如 1536 维）。

余弦相似度

为找到语义相似的记忆，Synapse 计算查询向量与每条记忆向量之间的余弦相似度。相似度越高 = 越相关。

何时使用语义搜索

在以下场景使用语义搜索：

  • 想要“关于 X 的记忆”，而 X 与存储时的描述不同
  • FTS5 返回零结果（无关键词匹配）
  • 想要概念聚合（例如所有“部署”相关记忆，即使有些写的是“发布”）
  • 查询是一个问题：“我们如何处理认证？”

在以下场景使用 FTS5：

  • 已知精确关键词
  • 需要布尔逻辑（AND、OR、NOT）
  • 需要亚毫秒级响应
  • 想要短语匹配

端点

GET /memory/semantic-search

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

响应：

{
  "results": [
    {
      "id": "mem_001",
      "category": "project",
      "key": "project_synapse_deployment",
      "content": "Synapse deployed using Docker Swarm on vps1...",
      "tags": ["docker", "swarm", "deployment"],
      "similarity": 0.89
    },
    {
      "id": "mem_042",
      "category": "fact",
      "key": "kubernetes_cluster",
      "content": "We use Kubernetes for production orchestration...",
      "tags": ["kubernetes", "orchestration"],
      "similarity": 0.84
    }
  ]
}

示例

查找部署相关记忆

# FTS5 可能遗漏部分 — 语义搜索能全部捕获
curl .../memory/semantic-search?q=deployment+process

返回关于 "deployment"、"release"、"publishing"、"rolling out" 等的记忆。

查找认证模式

curl .../memory/semantic-search?q=how+do+users+log+in

返回关于 login、auth、JWT、session 管理、OAuth 等的记忆。

查找相似记忆

# 查找与某条记忆相似的记忆
curl .../memory/related/mem_001

使用语义相似度（基于共享标签 + 嵌入向量）。

嵌入生成

何时生成嵌入？

  • 存储记忆时 — 若配置了嵌入服务，则同步生成嵌入
  • 批量生成 — POST /memory/embed-batch 为缺失嵌入的记忆生成
  • 异步更新 — 内容更新时重新生成嵌入

嵌入提供方

Synapse 支持可配置的嵌入提供方：

  • OpenAI（text-embedding-3-small、text-embedding-3-large）
  • 本地模型（通过 Ollama 等）
  • 自定义（实现 embeddings 接口）

通过环境变量配置：

EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_API_KEY=sk-...
EMBEDDINGS_MODEL=text-embedding-3-small

批量生成

对于很多记忆缺少嵌入的 Mind：

# 为最多 100 条记忆生成嵌入
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# 检查进度
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status

性能

操作 延迟
生成嵌入（OpenAI） 100-200ms
语义搜索（1k 条记忆） 50-100ms
语义搜索（10k 条记忆） 200-500ms
批量生成（100 条记忆） 10-20s
由于向量计算，语义搜索比 FTS5 慢。已知关键词时用 FTS5，概念查询用语义搜索。

局限性

嵌入成本

若使用 OpenAI，生成嵌入需要付费（text-embedding-3-small 约 $0.02 / 1M tokens）。对于平均每条 100 tokens 的 10,000 条记忆，约 $0.02 — 可忽略不计。

冷启动

在配置嵌入之前存储的记忆没有嵌入。请运行 POST /memory/embed-batch 补齐。

提供方依赖

如果嵌入提供方宕机，语义搜索会优雅降级（返回空结果或错误）。FTS5 仍可正常工作。

当嵌入不可用时

如果未配置嵌入服务：

  • GET /memory/semantic-search 返回 503 Service Unavailable
  • POST /memory 仍可正常工作（只是不生成嵌入）
  • FTS5 搜索仍可正常工作

最佳实践

下一步

← 返回 概念