AI 实战文档

Appearance

最快最简单的 RAG（已在本仓库实现） ​

目标 ​

在不引入额外数据库和重型框架的前提下，用最少命令跑通一个可用 RAG：

  • 文档切块
  • 本地检索
  • 可选 LLM 生成

代码位置 ​

  • 核心子包：packages/rag-mini
  • docs 脚本入口：
    • apps/docs/scripts/rag-mini/build.mjs
    • apps/docs/scripts/rag-mini/ask.mjs
  • 索引输出：apps/docs/.rag/index.json

一分钟跑通 ​

在仓库根目录执行：

bash
pnpm --filter docs rag:build
pnpm --filter docs rag:ask -- "OpenClaw 的安全模型是什么？"

如果你希望直接使用子包 CLI，也可以执行：

bash
pnpm --filter docs exec rag-mini ask "OpenClaw 的安全模型是什么？" --docs-root ./apps/docs

可选：接入模型生成答案 ​

默认情况下，脚本会先检索并返回片段。 如果设置了 OPENAI_API_KEY，会自动调用 OpenAI 兼容接口做生成。

bash
export OPENAI_API_KEY="<your_key>"
pnpm --filter docs rag:ask -- "如何安全地做远程接入？"

可选环境变量：

  • RAG_MODEL（默认：gpt-4.1-mini）
  • RAG_BASE_URL（默认：https://api.openai.com/v1）

实现要点 ​

  • 包结构拆分：
    • markdown.mjs：Markdown 清洗 + 分段切块
    • tokenize.mjs：中英文混合分词
    • indexer.mjs：建索引、读索引、存索引
    • retrieval.mjs：TF-IDF 风格召回排序
    • prompt.mjs + llm.mjs：提示词拼接和 LLM 调用
    • service.mjs：对外统一 API（buildAndSaveIndex / askQuestion）
  • docs 脚本仅做壳层封装：解析参数、调用子包 API、统一输出来源列表。

让你的 AI 接入这个 RAG ​

推荐按以下顺序选择：

  1. 命令行接入：让 Agent 调 rag-mini ask "<问题>" --docs-root <目录>。
  2. 后端函数接入：在 Node 服务里直接调用 askQuestion。
  3. HTTP 服务接入：把子包封装为 /rag/build 和 /rag/ask 两个接口，供多 Agent 复用。

完整示例与参数说明见 packages/rag-mini/README.md。

为什么这版适合先落地 ​

  • 无需向量数据库，部署成本最低。
  • 支持先离线检索，后续再接入在线 LLM。
  • 直接复用现有文档库，维护成本低。

后续可迭代方向 ​

  1. 增量索引（只重建变更文档）
  2. 引入 rerank 提升命中质量
  3. 替换为 embedding + 向量检索（保留当前命令兼容）