OpenClaw + LanceDB RAG 实战 - 让Agent拥有长期记忆

📅 2026-06-05 · 🏷️ RAG · LanceDB · 向量数据库 · Agent记忆 · ☕ 阅读约10分钟

为什么 Agent 需要"长期记忆"？

你有没有遇到过这种情况：你上周跟 Agent 详细讨论了一个项目方案，这周再问它，它完全不记得了。每次都要从头解释，效率低得让人抓狂。

这是大语言模型的固有局限——它的"记忆"仅限于当前对话的上下文窗口。对话结束，记忆清零。就像一个每天失忆的助手，能力很强但记不住事。

RAG（Retrieval-Augmented Generation，检索增强生成）就是解决这个问题的核心技术。它让 Agent 能够从一个外部知识库中检索相关信息，然后把这些信息注入到上下文中，从而"记住"之前学过的知识。

而 LanceDB，就是 OpenClaw 生态中用于构建 RAG 系统的向量数据库首选。

RAG 的工作原理：先搜后答

RAG 的核心流程非常直观：

  1. 索引阶段：把你的知识文档切分成小块（chunks），每块通过 Embedding 模型转成向量，存入向量数据库。
  2. 检索阶段：当用户提问时，把问题也转成向量，在数据库中搜索最相似的文档块。
  3. 生成阶段：把检索到的相关文档块拼接到 prompt 中，让 LLM 基于这些"参考资料"生成回答。

用一个比喻：RAG 就像是给 Agent 配了一个"随身图书馆"。它不需要把所有书都背下来（那得要多大的上下文窗口），只需要在回答问题前先去图书馆查一下相关资料。

# RAG 的简化流程
用户提问: "我们项目的数据库用的什么？"
    ↓
向量化: [0.12, -0.34, 0.56, ...]
    ↓
向量搜索: 找到最相似的文档块
    → "项目使用 PostgreSQL 15，主库 host=db.prod.example.com"
    → "数据库连接池配置：max_connections=100"
    ↓
拼接 Prompt:
    "参考资料：\n1. 项目使用 PostgreSQL 15...\n2. 数据库连接池配置...\n\n用户问题：我们项目的数据库用的什么？"
    ↓
LLM 生成回答:
    "你们项目使用的是 PostgreSQL 15，主库地址是 db.prod.example.com，连接池最大连接数配置为 100。"

为什么选择 LanceDB？

向量数据库有很多选择——Milvus、Qdrant、Weaviate、Pinecone、ChromaDB……为什么 OpenClaw 推荐 LanceDB？

  • 嵌入式部署：LanceDB 不需要独立的服务进程，直接以库的形式嵌入到你的应用中。零运维成本，不需要额外的服务器。对于个人用户和小团队来说，这简直是福音。
  • 零配置启动：安装即用，不需要 Docker、不需要 Kubernetes、不需要配置集群。一个 pip install 搞定一切。
  • 性能优秀：基于 Lance 列式存储格式，支持 ANN（近似最近邻）索引，百万级向量的查询延迟在毫秒级别。
  • 多模态支持：不仅支持文本向量，还支持图片、音频等多模态数据的向量存储和检索。
  • SQL 兼容：支持 SQL-like 的查询语法，降低学习成本。你可以像写 SQL 一样查询向量数据。
  • 成本低：本地存储，没有云服务费用。数据完全在你的掌控之中。

简单说，LanceDB 就是向量数据库界的 SQLite——轻量、易用、够用。

环境搭建：从零开始

安装 LanceDB

# 通过 pip 安装
pip install lancedb

# OpenClaw 集成安装
openclaw skills install openclaw-rag-lancedb

基本配置

# ~/.openclaw/config.yaml
rag:
  enabled: true
  provider: "lancedb"
  config:
    db_path: "~/.openclaw/rag-db"
    embedding:
      provider: "openai"
      model: "text-embedding-3-small"
      dimensions: 1536
      batch_size: 100
    retrieval:
      top_k: 5
      score_threshold: 0.7
    chunking:
      strategy: "recursive"
      chunk_size: 512
      chunk_overlap: 50

构建知识库：把文档喂给 Agent

方式一：CLI 批量导入

# 导入单个文件
openclaw rag ingest ./docs/project-spec.md

# 导入整个目录
openclaw rag ingest ./docs/ --recursive

# 支持的文件格式：md, txt, pdf, docx, html, json
openclaw rag ingest ./knowledge-base/ --formats md,txt,pdf

# 导入时指定元数据
openclaw rag ingest ./docs/api-guide.md \
  --metadata '{"category": "API", "version": "2.0"}'

# 查看知识库状态
openclaw rag status
# Total documents: 47
# Total chunks: 1,234
# Total tokens: 456,789
# DB size: 23.4 MB

方式二：代码中动态添加

from openclaw.rag import RAGEngine

rag = RAGEngine()

# 添加单条知识
rag.add(
    text="项目数据库使用 PostgreSQL 15，主库地址 db.prod.example.com",
    metadata={"type": "config", "importance": "high"}
)

# 批量添加
documents = [
    {"text": "API 端点文档...", "metadata": {"type": "api"}},
    {"text": "部署流程说明...", "metadata": {"type": "devops"}},
    {"text": "用户反馈汇总...", "metadata": {"type": "feedback"}},
]
rag.add_batch(documents)

# 从 URL 抓取并添加
rag.ingest_url("https://docs.example.com/api/v2")

# 从聊天记录中提取并添加
rag.ingest_conversation(conversation_id="conv_123")

方式三：自动同步

# 配置自动同步：监控目录变化，自动更新知识库
rag:
  auto_sync:
    enabled: true
    watch_dirs:
      - "~/projects/docs/"
      - "~/notes/"
    sync_interval: 300
    on_change: "incremental"

Embedding 策略：向量化的艺术

Embedding 是 RAG 系统中最关键的环节之一。选择合适的 Embedding 模型和策略，直接影响检索质量。

模型选择

# OpenClaw 支持的 Embedding 模型
embedding_models:
  # OpenAI（推荐，质量最高）
  - name: "text-embedding-3-small"
    dimensions: 1536
    cost: "$0.02/M tokens"
    quality: "good"

  - name: "text-embedding-3-large"
    dimensions: 3072
    cost: "$0.13/M tokens"
    quality: "excellent"

  # 本地模型（零成本）
  - name: "bge-large-zh-v1.5"
    dimensions: 1024
    cost: "free (local)"
    quality: "good (中文优化)"

  - name: "jina-embeddings-v3"
    dimensions: 1024
    cost: "free (local)"
    quality: "excellent (多语言)"

混合检索（Hybrid Search）

纯向量搜索有时候会"跑偏"——语义相似但关键词不匹配。混合检索结合了向量搜索和关键词搜索的优势：

# 配置混合检索
rag:
  retrieval:
    strategy: "hybrid"
    vector_weight: 0.7
    keyword_weight: 0.3
    rerank: true
    rerank_model: "cross-encoder"

混合检索的工作流程：

  1. 同时执行向量搜索和关键词搜索
  2. 分别得到两组结果
  3. 按照权重合并分数
  4. （可选）用 Cross-Encoder 模型对合并后的结果进行重排序
  5. 返回最终的 Top-K 结果

查询模式：让 Agent 聪明地"回忆"

自动 RAG（透明集成）

# OpenClaw 会自动将 RAG 集成到 Agent 的对话流程中
# Agent 在回答问题时，会自动：
# 1. 判断是否需要从知识库中检索
# 2. 如果需要，自动生成检索查询
# 3. 检索相关文档
# 4. 将文档注入上下文
# 5. 基于检索结果生成回答

# 用户直接对话即可，无需手动操作
# 用户: "我们项目的部署流程是什么？"
# Agent 内部: [检索知识库] → [找到部署文档] → [生成回答]

手动检索（精确控制）

results = rag.search(
    query="数据库备份策略",
    top_k=3,
    filters={"category": "devops"}
)

# 返回格式
# [
#   {
#     "text": "数据库每天凌晨3点自动备份...",
#     "score": 0.92,
#     "metadata": {"source": "ops-manual.md", "category": "devops"}
#   },
#   ...
# ]

多轮对话中的 RAG

# OpenClaw 支持在多轮对话中智能使用 RAG
# 它会结合对话历史来优化检索查询

# 第1轮
# 用户: "我们的 API 限流策略是什么？"
# Agent: [检索] → "API 限流策略是每分钟100次请求..."

# 第2轮
# 用户: "如果超限了会怎样？"
# Agent: [结合上下文重写查询] → "超限后会返回 429 状态码..."

实战场景

场景一：项目知识库

# 把项目文档导入知识库，让 Agent 成为"百事通"
openclaw rag ingest ~/projects/myapp/docs/ --recursive
openclaw rag ingest ~/projects/myapp/README.md
openclaw rag ingest ~/projects/myapp/CHANGELOG.md

# 之后 Agent 就能回答项目相关的问题
# "这个项目的数据库 schema 长什么样？"
# "上次部署失败的原因是什么？"
# "API v2 和 v1 有什么区别？"

场景二：个人笔记库

# 把你的 Obsidian/Notion 笔记导入
openclaw rag ingest ~/Notes/ --formats md

# Agent 变成你的"第二大脑"
# "我之前关于 Transformer 的笔记里写了什么？"
# "我收藏的那篇关于 RAG 优化的文章在哪个目录？"

场景三：客服知识库

# 导入产品文档、FAQ、客服话术
openclaw rag ingest ./customer-service/faq.md
openclaw rag ingest ./customer-service/product-guide.pdf
openclaw rag ingest ./customer-service/scripts/

# Agent 基于知识库回答客户问题，确保回答准确一致

性能优化与最佳实践

  • 分块大小很重要：太小会丢失上下文，太大会引入噪声。512 tokens 是一个不错的起点，可以根据实际效果调整。
  • 重叠不能省：chunk_overlap 看似浪费 tokens，但它能避免关键信息被切断在两个块的边界。
  • 元数据是利器：给每个文档块打上分类、来源、时间等元数据标签，检索时可以用元数据过滤，大幅提高精度。
  • 定期清理：过期的文档要及时从知识库中删除，否则会干扰检索结果。设置文档的 TTL（生存时间）是个好习惯。
  • 测试检索质量：准备一组测试问题，定期评估检索的准确率。如果准确率下降，可能是知识库需要更新或分块策略需要调整。
  • 监控 Embedding 成本：Embedding 调用也有成本（虽然比 LLM 便宜很多），批量处理可以利用 API 的批量折扣。
  • 中文场景选中文模型：如果你的知识库主要是中文内容，用 bge-large-zh 等中文优化模型，效果比通用模型好得多。
  • 备份向量数据库：虽然 LanceDB 是本地存储很安全，但定期备份仍然是好习惯。LanceDB 支持增量备份，成本很低。

常见问题排查

Q: 检索结果不相关怎么办？

首先检查分块策略——可能是块太大或太小。然后检查 Embedding 模型——中文场景建议用中文优化模型。最后试试混合检索，关键词匹配有时候比纯向量搜索更靠谱。

Q: 知识库更新后 Agent 还是用旧信息？

检查是否启用了增量同步。如果是手动导入的，需要重新执行 openclaw rag ingest。也可以用 openclaw rag rebuild 重建整个索引。

Q: LanceDB 占用磁盘空间太大？

可以配置向量量化来压缩存储。LanceDB 支持 PQ（Product Quantization）和 SQ（Scalar Quantization），可以在几乎不影响检索质量的前提下，将存储空间压缩 4-8 倍。

# 启用向量量化
rag:
  config:
    index:
      type: "IVF_PQ"
      num_sub_vectors: 96
      num_bits: 8

总结

RAG 让 Agent 从"失忆助手"变成了"拥有图书馆的学者"。而 LanceDB 以其轻量、易用、高性能的特点，成为 OpenClaw 生态中最适合个人和小团队的向量数据库选择。

构建一个 RAG 系统并不复杂——安装、配置、导入文档、开始查询。但要做得好，需要在分块策略、Embedding 模型选择、混合检索等细节上下功夫。希望本文的实战经验能帮你少走弯路。

想了解更多 RAG 的进阶用法，可以看看我们的RAG Pipeline 架构详解和Agent 记忆系统设计指南。

相关文章