RAG 混合检索知识库助手

触发条件

当用户需要以下功能时触发：

1. 构建/管理本地知识库

   • "搭建知识库"、"创建 RAG 系统"、"索引文档"
   • "添加文档到知识库"、"更新知识库"

2. 查询知识库

   • 包含关键词：香港身份、香港签证、优才、专才、高才通、续签、永居、受养人
   • 包含关键词：公司制度、考勤、请假、报销、福利
   • 包含关键词：Python、机器学习、算法、编程
   • 通用：任何已索引文档的查询

3. 优化检索性能

   • "查询太慢"、"加速检索"、"优化 RAG"
   • "启动 API 服务"、"FastAPI 服务"

核心能力

1. 混合检索 (BM25 + 向量语义)

结合关键词精确匹配和语义理解，通过 RRF 融合排序：

查询文本
    ↓
┌─────────────────┐    ┌─────────────────┐
│   jieba 分词     │    │   BGE-M3        │
│   BM25Okapi     │    │   Chroma        │
│   关键词检索     │    │   向量检索       │
└─────────────────┘    └─────────────────┘
    ↓                         ↓
    └────────────┬────────────┘
                 ↓
           RRF 融合排序
                 ↓
           返回 Top-K 结果

三种检索模式：

2. FastAPI 服务 (毫秒级查询)

预加载模型，实现 ~40ms 查询响应：

# 启动服务
cd scripts && source venv/bin/activate
uvicorn rag_api:app --host 0.0.0.0 --port 8000

# 查询
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "问题", "top_k": 5}'

3. 自动查询集成

在 Hermes 对话中直接提问，自动调用 RAG API：

# scripts/rag_query_auto.py
if is_rag_query(user_question):
    response = query_rag_api(user_question)
    return format_results(response)

工作流程

阶段 1：构建知识库

# 1. 准备文档 (支持 md/txt/pdf/docx/xlsx)
mkdir ~/test-knowledge
cp your_docs/*.md ~/test-knowledge/

# 2. 构建索引 (含混合检索)
cd scripts && source venv/bin/activate
python index_knowledge.py \
  --knowledge-dir ~/test-knowledge \
  --output-dir ~/test-vectorstore \
  --rebuild --hybrid

阶段 2：启动服务

# 启动 FastAPI 服务 (预加载模型)
uvicorn rag_api:app --host 0.0.0.0 --port 8000

# 或后台运行
nohup uvicorn rag_api:app --host 0.0.0.0 --port 8000 > rag_api.log 2>&1 &

阶段 3：查询使用

方式 A：命令行

python rag_query.py "问题" --vectorstore ~/test-vectorstore --top-k 5

方式 B：API 调用

curl -X POST http://localhost:8000/query \
  -d '{"query": "问题", "top_k": 5, "search_mode": "hybrid"}'

方式 C：对话中直接提问

用户: 香港专才计划的签证有效期是多久？
助手: [自动查询知识库] 根据知识库信息...

关键文件

依赖安装

cd scripts && source venv/bin/activate
pip install rank-bm25 jieba fastapi uvicorn

故障处理

• 服务未启动：运行 uvicorn rag_api:app --host 0.0.0.0 --port 8000
• 查询超时：检查服务状态或简化查询
• 无结果：知识库中暂无相关信息，建议更新知识库
• 首次查询慢：服务已包含预热查询，启动时即完成初始化

性能优化

与 LLM Wiki 的协作

RAG 和 LLM Wiki 是互补的知识管理方式：

推荐工作流：

1. 日常查询 → 使用 RAG 快速获取答案
2. 有价值的信息 → 归档到 LLM Wiki（llm-wiki 技能）
3. 定期整理 → 将 RAG 高频查询结果整理为 Wiki 页面

示例：

用户问：优才和专才的区别？
→ RAG 查询 → 获得答案
→ 如果答案有价值 → 更新到 Wiki 的 [[香港移民FAQ]] 页面
→ 添加交叉引用 [[香港优才计划]]、[[香港专才计划]]

注意事项

1. 服务依赖：需要确保本地 RAG API 服务已启动（端口 8000）
2. 查询超时：API 调用超时时间为 10 秒
3. 结果限制：最多返回 5 个相关片段，避免信息过载
4. 内容截断：如果内容过长，只返回前 500 字符
5. 与 Wiki 互补：RAG 适合快速查询，Wiki 适合深度整理，两者结合效果更佳