RAG助理
一种基于Flask的检索增强生成（RAG）助手，它：
- 摄入当地
.txt和.pdf文件 - 使用FAISS构建内存中的语义搜索
- 使用检索到的上下文和Ollama LLM回答查询
- 回归到简单的MCP风格工具(
code_tool,architecture_tool) - 通过SQLAlchemy在PostgreSQL中存储对话历史记录
特性
- 具有分块、嵌入和相似性搜索的RAG管道
- 使用以下命令查询路由代理：
- 检索第一答案策略 - 代码/设计请求的工具决策层 - 直接LLM回退
- 基于会话的聊天记忆保存在数据库中
- 用于健康、摄入和聊天的REST API端点
技术栈
- python
- 烧瓶
- FAISS(
faiss-cpu) - 数值Python
- SQLAlchemy+PostgreSQL(
psycopg2-binary) - Ollama HTTP API
- PyPDF(
pypdf)
项目结构
backend/
app.py # Flask entrypoint
api/routes.py # API routes
agent/orchestrator.py # Agent orchestration + tool decisions
rag/
loader.py # Loads text/pdf documents
chunker.py # Character-based chunking
embedder.py # Ollama embeddings client
retriever.py # FAISS vector store
store.py # Ingestion helpers + global vector store
llm.py # Ollama generation client
memory/
database.py # DB engine/session setup
models.py # Conversation model + init_db
service.py # Save/fetch conversation messages
mcp/server.py # Minimal in-process MCP-like tool registry
tools/
code_tool.py
architecture_tool.py
documents/ # Seed docs auto-ingested at startup运作原理
- 应用程序启动(
backend/app.py):
- 初始化数据库表 - 摄入 backend/documents 走进FAISS
- 摄入(
/ingest):
- 接受文本有效载荷 - 分块和嵌入文本 - 将向量/块添加到FAISS
- 聊天(
/chat):
- 将用户消息保存到数据库 - 加载最近的会话历史记录 - 对查询运行检索 - 如果最佳距离分数低于阈值(0.8)，使用检索到的上下文回答 - 否则，路由到工具/直接LLM路径 - 将助手响应保存到数据库
先决条件
- Python 3.10+
- PostgreSQL数据库
- Ollama在当地跑步
http://localhost:11434 - Ollama车型被召回：
- llama3 （世代） - nomic-embed-text （嵌入）
设置
- 克隆并进入仓库：
git clone
cd rag-assistant- 创建并激活虚拟环境：
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate- 安装依赖项：
pip install -r backend/requirements.txt- 创建
.env里面backend/:
DATABASE_URL=postgresql+psycopg2://:
@localhost:5432/- 启动Olama并拉取模型：
ollama pull llama3
ollama pull nomic-embed-text- 运行应用程序（从
backend/):
cd backend
python app.py服务器默认值： http://127.0.0.1:5000
API
GET /health
返回服务状态。
答复：
{"status":"OK"}POST /ingest
将原始文本摄取到矢量存储中。
请求正文：
{"text":"CAP theorem states that ..."}答复：
{
"message": "Document ingested successfully",
"chunks_added": 3
}POST /chat
用可选对话提问 session_id.
请求正文：
{"session_id":"user1","query":"Explain CAP theorem"}答复：
{"answer":"..."}cURL命令示例
curl -X GET http://127.0.0.1:5000/health
curl -X POST http://127.0.0.1:5000/ingest \
-H "Content-Type: application/json" \
-d "{\"text\": \"CAP theorem states that a distributed system can only guarantee two of consistency, availability, and partition tolerance.\"}"
curl -X POST http://127.0.0.1:5000/chat \
-H "Content-Type: application/json" \
-d "{\"query\": \"Explain CAP theorem\"}"
curl -X POST http://127.0.0.1:5000/chat \
-H "Content-Type: application/json" \
-d "{\"session_id\": \"user1\", \"query\": \"Why is system design used in 20 words?\"}"注释和当前限制
- 矢量存储仅在内存中；重新启动时嵌入丢失。
- 启动摄取从运行一次
backend/documents. - 检索使用具有固定阈值的原始L2距离
0.8；可能需要调整。 - 在当前实现中，在FAISS搜索之前没有空索引保护。
- 上游Ollama/DB故障的最小输入验证和错误处理。
- 在LLM回退之前，工具路由由关键字驱动
Agent.decide.
故障排除
DATABASE_URL缺失或无效：
- 确保 .env 存在于 backend/ 并且具有有效的SQLAlchemy PostgreSQL URL。
- Ollama连接错误：
- 确认Ollama正在运行 localhost:11434. - 验证所需模型是否已提取。
- 导入/模块错误：
- 从内部运行应用程序 backend/ 因此，本地进口正确解决。
- 没有有用的RAG答案：
- 在中添加更高质量的源文档 backend/documents. - 调整代码中的块大小/重叠和阈值。
未来改进
- 将FAISS索引持久化到磁盘并在启动时重新加载
- 大型文档的异步/后台摄取
- 更好的检索评分和重新排名
- 更坚固的护栏和结构化的工具调用格式
- 单元/集成测试和CI管道