Web Hybrid RAG Agent

一个基于 FastAPI、LangChain、Ollama 与 Qdrant 的本地化 RAG 智能体系统，支持网页抓取、混合检索、重排、多用户多会话记忆，以及本地持久化聊天记录。

项目面向“本地可运行”的知识库问答场景：

• 抓取网页内容并自动切分为知识块
• 使用 Qdrant 稠密检索 + BM25 稀疏检索做混合召回
• 使用本地 Ollama 重排模型对召回结果再次排序
• 使用 LangChain create_react_agent 构建工具调用 Agent
• 使用 SQLite 持久化多用户、多会话聊天记录
• 提供 FastAPI API 与一个简单前端页面

功能特性

• 网页采集：/ingest/web
• 多轮会话问答：/chat
• 健康检查：/health
• 前端页面：/
• 本地向量存储：Qdrant 持久化到 data/qdrant/
• 本地会话记忆：SQLite 持久化到 data/chat_history.db

技术栈

• Python 3.12+
• FastAPI
• LangChain / LCEL
• langchain-ollama
• Qdrant
• rank-bm25
• SQLAlchemy
• SQLite

项目结构

app/
  agent/      Agent 构建
  api/        FastAPI 路由与请求响应模型
  core/       配置、日志、异常
  frontend/   简单前端页面
  memory/     会话与消息历史封装
  rag/        网页采集、混合检索、重排、工具
  main.py     应用入口
tests/        测试
data/         本地运行数据目录（已在 .gitignore 中忽略）

运行前准备

1. 创建并激活虚拟环境

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1

2. 安装依赖

python -m pip install -U pip
python -m pip install -e .[dev]

3. 配置环境变量

将 .env.example 复制为 .env，然后根据本机环境调整：

Copy-Item .env.example .env

默认配置如下：

APP_NAME=Web Hybrid RAG Agent
APP_HOST=127.0.0.1
APP_PORT=8000
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_CHAT_MODEL=qwen3:8b
OLLAMA_EMBEDDING_MODEL=bge-m3:latest
OLLAMA_RERANK_MODEL=dengcao/Qwen3-Reranker-4B:Q4_K_M
RERANKER_TIMEOUT_SECONDS=30.0
WEB_LOADER_TIMEOUT_SECONDS=20
DEFAULT_TOP_K=4
DEFAULT_COLLECTION_NAME=default_knowledge_base
QDRANT_PATH=./data/qdrant
CHAT_HISTORY_DB_PATH=./data/chat_history.db
LOG_LEVEL=INFO

4. 准备本地 Ollama 模型

请确保已经安装并启动 Ollama，然后拉取项目使用的模型：

ollama pull qwen3:8b
ollama pull bge-m3:latest
ollama pull dengcao/Qwen3-Reranker-4B:Q4_K_M

如果你希望切换模型，可以直接修改 .env 中的：

• OLLAMA_CHAT_MODEL
• OLLAMA_EMBEDDING_MODEL
• OLLAMA_RERANK_MODEL

启动项目

python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

启动后可访问：

• 前端页面：http://127.0.0.1:8000/
• 健康检查：http://127.0.0.1:8000/health

API 使用示例

1. 抓取网页并写入知识库

curl -X POST http://127.0.0.1:8000/ingest/web \
  -H "Content-Type: application/json" \
  -d "{\"url\": \"https://example.com\", \"collection_name\": \"default_knowledge_base\"}"

示例响应：

{
  "collection_name": "default_knowledge_base",
  "chunk_count": 3,
  "document_ids": [
    "6e6d9f4d-4a95-4d5b-b7a8-5d3e1d0b46c1"
  ]
}

2. 多用户、多会话对话

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d "{\"user_id\": \"alice\", \"session_id\": \"demo\", \"message\": \"总结一下刚刚抓取的网页\", \"collection_name\": \"default_knowledge_base\"}"

示例响应：

{
  "answer": "这是基于已抓取网页内容的总结。",
  "session_id": "user_alice_session_demo",
  "sources": []
}

会话与数据持久化

项目支持多用户、多会话隔离：

• user_id 用于标识用户
• session_id 用于标识该用户下的会话
• 实际内部会话键会组合为 user_{user_id}_session_{session_id}

持久化数据默认位于：

• 聊天记录：data/chat_history.db
• 向量数据：data/qdrant/

这些文件都已经加入 .gitignore，不会被提交到仓库。

测试

python -m pytest

常见问题

1. 启动时报 Ollama 连接失败

请先确认：

• Ollama 服务已启动
• OLLAMA_BASE_URL 配置正确
• 所需模型已经 pull

2. 抓取网页失败

可能原因：

• 目标网页不可访问
• 网络超时
• 网站有反爬或访问限制

可以尝试调大 .env 中的 WEB_LOADER_TIMEOUT_SECONDS。

3. 检索结果不稳定

可以从以下几个方向调整：

• 更换更强的聊天模型
• 调整 DEFAULT_TOP_K
• 替换重排模型
• 使用更高质量的网页源

开发说明

当前仓库已经忽略以下本地文件与运行产物：

• .env
• .venv/
• .vscode/
• __pycache__/
• .pytest_cache/
• *.egg-info/
• data/chat_history.db
• data/qdrant/

这意味着仓库更适合作为“源码仓库”使用，本地运行数据不会被误提交。