Rag MCP Assistant

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

运作原理

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. 克隆并进入仓库：

git clone 
cd rag-assistant

1. 创建并激活虚拟环境：

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

1. 安装依赖项：

pip install -r backend/requirements.txt

1. 创建 .env 里面 backend/:

DATABASE_URL=postgresql+psycopg2://:
@localhost:5432/

1. 启动Olama并拉取模型：

ollama pull llama3
ollama pull nomic-embed-text

1. 运行应用程序（从 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管道