AI导哈

检索增强生成助手

一个基于Flask的检索增强生成助手，支持本地文档的语义搜索和智能问答，并具备会话记忆功能。

  • by sahasrocks
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 sahasrocks/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
  2. 摄入(/ingest):
    • 接受文本有效载荷
    • 分块和嵌入文本
    • 将向量/块添加到FAISS
  3. 聊天(/chat):
    • 将用户消息保存到数据库
    • 加载最近的会话历史记录
    • 对查询运行检索
    • 如果最佳距离分数低于阈值(0.8)，使用检索到的上下文回答
    • 否则，路由到工具/直接LLM路径
    • 将助手响应保存到数据库

先决条件

  • Python 3.10+
  • PostgreSQL数据库
  • Ollama在当地跑步 http://localhost:11434
  • Ollama车型被召回：
    • llama3 （世代）
    • nomic-embed-text （嵌入）

设置

  1. 克隆并进入仓库：
git clone <your-repo-url>
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://<user>:<password>@localhost:5432/<db_name>
  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管道

相关 MCP