🦞 RAG Retriever V3.0#

版本: 3.0.0

创建时间: 2026-03-27

状态: ✅ 完整实现

---

📋 简介#

RAG 3.0 (Retrieval-Augmented Generation) 高级检索系统，为 OpenClaw 提供企业级的文档检索能力：

• 🧠 语义嵌入 - 支持 OpenAI + BGE + MiniLM 多模型
• 🔍 混合检索 - 向量相似度 + BM25 关键词 + RRF 融合
• 🔄 智能重排序 - Cross-Encoder 精确重打分
• 📖 来源引用 - 自动编号 + 完整溯源
• 🇨🇳 中文优化 - jieba 分词 + 中文标点处理

---

🚀 快速开始#

安装#

bash

cd skills/rag-retriever-v3
npm install

基本使用#

1. 初始化

bash

node src/cli.js init

2. 添加文档

bash

node src/cli.js add ./document.txt '{"source":"文档来源","title":"文档标题"}'

3. 检索

bash

# 混合搜索（推荐）
node src/cli.js search "查询内容" 5

# 仅向量搜索
node src/cli.js vector-search "查询内容" 5

# 仅关键词搜索
node src/cli.js keyword-search "查询内容" 5

# RAG 查询（生成带引用的上下文）
node src/cli.js rag "什么是人工智能" 3

---

📚 API 使用#

JavaScript API#

javascript

import { RAGRetrieverV3 } from './src/core/RAGRetrieverV3.js';

// 创建检索器实例
const rag = new RAGRetrieverV3({
  dbPath: './data/lancedb-v3',
  collectionName: 'documents',

  // 嵌入配置
  embeddingProvider: 'xenova',  // 'xenova', 'openai', 'auto'
  embeddingOptions: {
    modelName: 'Xenova/all-MiniLM-L6-v2'
  },

  // 分块配置
  chunking: {
    chunkSize: 500,
    overlap: 50,
    strategy: 'recursive'  // 'fixed', 'recursive', 'semantic'
  },

  // BM25 配置
  bm25: {
    k1: 1.5,
    b: 0.75
  },

  // RRF 配置
  rrf: {
    k: 60,
    weights: { 0: 1.0, 1: 1.0 }
  },

  // 重排序配置
  rerank: {
    enabled: true,
    model: 'Xenova/ms-marco-MiniLM-L-6-v2',
    topK: 20
  },

  // 引用配置
  citation: {
    format: 'numbered',  // 'numbered', 'bracket', 'footnote'
    includeMetadata: true
  }
});

// 初始化
await rag.initialize();

// 添加文档
const result = await rag.addDocument(text, {
  title: '文档标题',
  source: '文档来源',
  author: '作者',
  date: '2024-01-01'
});

// 检索
const results = await rag.retrieve('查询内容', {
  limit: 5,
  hybrid: true,      // 使用混合搜索
  rerank: true,      // 启用重排序
  addCitations: true // 添加引用
});

// RAG 查询（生成完整提示词）
const ragResult = await rag.retrieveForRAG('什么是机器学习', {
  limit: 3
});
console.log(ragResult.fullPrompt);
console.log(ragResult.citationList);

// 获取统计信息
const stats = await rag.getStats();

// 关闭连接
await rag.close();

---

🎯 核心组件#

1. 嵌入模型 (Embeddings)#

支持多种嵌入模型：

Xenova/Transformers (本地)

javascript

import { XenovaEmbedding } from './src/embeddings/XenovaEmbedding.js';

const embedding = new XenovaEmbedding({
  modelName: 'Xenova/all-MiniLM-L6-v2'  // 384维
  // 或 'Xenova/bge-base-zh-v1.5'  // 768维，中文优化
});
await embedding.initialize();
const vector = await embedding.embed('文本内容');

支持的模型：

• Xenova/all-MiniLM-L6-v2 - 384维，轻量级英文
• Xenova/bge-small-zh-v1.5 - 512维，中文小模型
• Xenova/bge-base-zh-v1.5 - 768维，中文基础模型
• Xenova/bge-large-zh-v1.5 - 1024维，中文大模型
• Xenova/multilingual-e5-base - 768维，多语言

OpenAI (云端)

javascript

import { OpenAIEmbedding } from './src/embeddings/OpenAIEmbedding.js';

const embedding = new OpenAIEmbedding({
  apiKey: process.env.OPENAI_API_KEY,
  modelName: 'text-embedding-3-small'  // 1536维
});
await embedding.initialize();

2. 混合搜索 (Hybrid Search)#

javascript

// 向量搜索
const vectorResults = await rag.vectorSearch('查询', { limit: 20 });

// 关键词搜索（BM25）
const keywordResults = await rag.keywordSearch('查询', { limit: 20 });

// 混合搜索（RRF 融合）
const hybridResults = await rag.hybridSearch('查询', {
  vectorLimit: 20,
  keywordLimit: 20,
  limit: 10
});

3. 重排序 (Reranking)#

javascript

import { CrossEncoderReranker } from './src/rerank/CrossEncoderReranker.js';

const reranker = new CrossEncoderReranker({
  modelName: 'Xenova/ms-marco-MiniLM-L-6-v2'
});

const reranked = await reranker.rerank('查询', results, { limit: 10 });

4. 来源引用 (Citations)#

javascript

import { CitationManager } from './src/core/CitationManager.js';

const cm = new CitationManager({ format: 'numbered' });

// 添加引用
const citedResults = cm.addCitations(results);

// 生成上下文
const context = cm.generateContext(citedResults);

// 生成引用列表
const citationList = cm.generateCitationList(citedResults);

// 生成完整 RAG 提示词
const ragPrompt = cm.generateRAGPrompt('查询', citedResults);

---

🔧 配置选项#

RAGRetrieverV3 完整配置#

javascript

{
  // 基础配置
  dbPath: './data/lancedb-v3',      // LanceDB 路径
  collectionName: 'documents',       // 集合名称

  // 嵌入配置
  embeddingProvider: 'xenova',       // 'xenova', 'openai', 'auto'
  embeddingOptions: {
    modelName: 'Xenova/all-MiniLM-L6-v2',
    // OpenAI 选项
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: 'https://api.openai.com/v1'
  },

  // 分块配置
  chunking: {
    chunkSize: 500,                  // 每块字符数
    overlap: 50,                     // 重叠字符数
    strategy: 'recursive',           // 'fixed', 'recursive', 'semantic'
    separator: '\n'                  // 分隔符
  },

  // BM25 配置
  bm25: {
    k1: 1.5,                         // BM25 k1 参数
    b: 0.75                          // BM25 b 参数
  },

  // RRF 配置
  rrf: {
    k: 60,                           // RRF 常数
    weights: { 0: 1.0, 1: 1.0 }     // 各检索器权重
  },

  // 重排序配置
  rerank: {
    enabled: true,                   // 是否启用
    model: 'Xenova/ms-marco-MiniLM-L-6-v2',
    topK: 20                         // 重排序前 K 个
  },

  // 引用配置
  citation: {
    format: 'numbered',              // 'numbered', 'bracket', 'footnote'
    includeMetadata: true,           // 包含元数据
    maxContentLength: 500            // 内容最大长度
  }
}

---

🧪 测试#

运行测试#

bash

# 运行所有测试
npm test

# 运行单元测试
npm run test:unit

# 运行集成测试
npm run test:integration

# 运行中文测试
npm run test:chinese

测试覆盖#

• ✅ 分块策略（固定、递归、语义）
• ✅ 嵌入模型（Xenova、OpenAI）
• ✅ BM25 关键词搜索
• ✅ RRF 融合算法
• ✅ Cross-Encoder 重排序
• ✅ 来源引用管理
• ✅ 中文分词和搜索
• ✅ 完整 RAG 流程

---

📊 性能指标#

指标数值分块速度1000 字符/ms嵌入速度50-100 文档/s (本地)向量搜索延迟<50ms混合搜索延迟<100ms重排序延迟10-50ms/文档存储占用2-4KB/文档

---

🌟 特性对比#

特性RAG 2.0RAG 3.0嵌入模型简单 TFXenova/OpenAI向量维度固定 384384-3072 可选关键词搜索❌✅ BM25混合检索❌✅ RRF重排序❌✅ Cross-Encoder来源引用基础完整溯源中文分词基础 jieba优化 jieba

---

🔗 参考资料#

• LanceDB 文档
• Transformers.js
• BM25 算法
• RRF 融合
• Cross-Encoder

---

⚠️ 已知限制#

1. 首次加载模型 - Xenova 模型首次下载需要网络，约 50-200MB
2. 内存占用 - 大型嵌入模型需要较多内存（建议 4GB+）
3. 中文模型 - 部分中文模型效果依赖训练数据质量

---

最后更新：2026-03-27