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)
项目结构```text
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
## 运作原理
1. 应用程序启动(`backend/app.py`):
- 初始化数据库表
- 摄入 `backend/documents` 走进FAISS
1. 摄入(`/ingest`):
- 接受文本有效载荷
- 分块和嵌入文本
- 将向量/块添加到FAISS
1. 聊天(`/chat`):
- 将用户消息保存到数据库
- 加载最近的会话历史记录
- 对查询运行检索
- 如果最佳距离分数低于阈值(`0.8`)，使用检索到的上下文回答
- 否则，路由到工具/直接LLM路径
- 将助手响应保存到数据库
## 先决条件
- Python 3.10+
- PostgreSQL数据库
- Ollama在当地跑步 `http://localhost:11434`
- Ollama车型被召回：
- `llama3` （世代）
- `nomic-embed-text` （嵌入）
## 设置
1. 克隆并进入仓库：```bash
git clone
cd rag-assistant
- 创建并激活虚拟环境：```bash
python -m venv .venv
Windows
.venv\Scripts\activate
macOS/Linux
source .venv/bin/activate
3. 安装依赖项：```bash
pip install -r backend/requirements.txt
- 创建
.env里面backend/:```env
DATABASE_URL=postgresql+psycopg2://:@localhost:5432/
5. 启动Olama并拉取模型：```bash
ollama pull llama3
ollama pull nomic-embed-text
- 运行应用程序（从
backend/):```bash
cd backend
python app.py
服务器默认值： `http://127.0.0.1:5000`
## API
### `GET /health`
返回服务状态。
答复：```json
{"status":"OK"}
POST /ingest
将原始文本摄取到矢量存储中。
请求正文：```json
{"text":"CAP theorem states that ..."}
答复：```json
{
"message": "Document ingested successfully",
"chunks_added": 3
}
POST /chat
用可选对话提问 session_id.
请求正文：```json
{"session_id":"user1","query":"Explain CAP theorem"}
答复：```json
{"answer":"..."}
cURL命令示例```bash
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管道
