MDBQS

# 多数据库查询系统 一个通过统一的自然语言接口查询多个异构数据库的全栈应用程序，由谷歌Gemini AI提供支持。 ## 项目概述 **多数据库查询系统** 是一个智能查询编排平台： - ✅ 接受用户的自然语言查询 - ✅ 使用LLM辅助规划将查询分解为数据库特定的执行计划 - ✅ 在多个数据源（PostgreSQL、MongoDB、Neo4j、Milvus）上并行执行查询 - ✅ 融合异构结果并跟踪来源 - ✅ 提供字段级搜索的模式发现接口 - ✅ 提供REST API后端和React前端UI ### 主要功能 **多源查询执行** — SQL、Document（MongoDB）、Graph（Neo4j）、Vector（Milvus） **LLM驱动的规划** — 谷歌Gemini用于智能查询分解 **并行执行** — 异步任务编排以实现快速结果聚合 **模式索引** — 跨所有数据源的可搜索字段注册表 **来源跟踪** — 跟踪每个数据元素贡献的来源 **模型上下文协议（MCP）** — 数据源集成的插件架构 --- ## 项目架构 ``` 多数据库查询系统/ ├── 后端/ # FastAPI后端 + 多数据库支持 │ ├── 应用/ │ │ ├── 主文件.py # FastAPI应用设置 │ │ ├── API/v1/ # API端点（查询、模式、聊天、来源） │ │ ├── 服务/ # 核心业务逻辑（规划器、执行器、融合器） │ │ ├── MCP插件/ # 数据源适配器（SQL、NoSQL、图、向量） │ │ ├── 模型/ # Pydantic模型和数据结构 │ │ ├── 仓库/ # 数据访问层 │ │ ├── 核心/ # 配置和设置 │ │ └── 测试/ # 自动测试套件 │ ├── docker-compose.yml # 多容器设置（数据库 + 依赖项） │ ├── 初始化PostgreSQL/ # PostgreSQL初始化脚本 │ ├── 初始化MongoDB/ # MongoDB初始化脚本 │ ├── 初始化Neo4j/ # Neo4j初始化脚本 │ ├── 初始化Milvus/ # Milvus初始化脚本 │ ├── 脚本/ # 数据库种子脚本 │ ├── 需求.txt # Python依赖项 │ ├── 运行所有服务器.ps1 # Windows脚本以启动所有服务 │ ├── 运行所有服务器.sh # Unix/Linux脚本以启动所有服务 │ └── 测试.py # 简单测试运行器 │ ├── 前端/ # React + Vite + TypeScript UI │ ├── 源/ │ │ ├── API/ # API实用程序和服务 │ │ ├── 组件/ # 可重用的React组件 │ │ ├── 存储/ # Zustand状态管理 │ │ ├── 类型/ # TypeScript定义 │ │ ├── 钩子/ # 自定义React钩子 │ │ └── 应用.tsx # 主应用程序 │ ├── package.json # Node.js依赖项 │ ├── vite.config.ts # Vite配置 │ └── tsconfig.json # TypeScript配置 │ └── README.md # 此文件 ``` --- ## 准备工作 ### 系统需求 - **Docker & Docker Compose** — 用于容器化数据库 - **Python 3.11+** — 用于后端 - **Node.js 18+** — 用于前端 - **Git** — 用于版本控制 ### 后端需求 - Python 3.11或更高 - pip（Python包管理器） - 虚拟环境（venv或virtualenv） ### 前端需求 - Node.js 18或更高 - npm 9+或yarn ### API密钥 - **Grok API密钥** — 查询规划所需的LLM支持 - 从[Groq](https://console.groq.com/keys)获取 - 添加到`.env`文件为`GROQ_API_KEY` --- ## 快速开始 ### 步骤1：克隆仓库 ```bash git clone <仓库URL> cd 多数据库查询系统 ``` ### 步骤2：设置环境变量 在`后端/`目录中创建一个`.env`文件，包含以下变量： ```bash cd 后端 # 示例.env文件 GROQ_API_KEY=您的GROQ_API密钥 POSTGRES_DSN=postgresql://postgres:postgrespassword@localhost:5432/mdbs MONGO_URI=mongodb://localhost:27017/mdbs NEO4J_URI=neo4j://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=neo4jpassword MILVUS_HOST=localhost MILVUS_PORT=19530 ``` --- ## 数据库设置 该项目使用**Docker Compose**编排四个异构数据库及其依赖项。 ### 步骤1：启动所有数据库 从`后端/`目录： ```bash cd 后端 docker-compose up -d ``` 这将启动： - ✅ **PostgreSQL 15** — 关系数据库（端口5432） - ✅ **MongoDB 6.0** — 文档数据库（端口27017） - ✅ **Neo4j 5.11** — 图数据库（端口7474，7687） - ✅ **Milvus 2.2.16** — 向量数据库（端口19530） - ✅ **Milvus依赖项** — Etcd和MinIO服务（Milvus所需） ### 步骤2：验证数据库正在运行 ```bash docker ps ``` 您应该看到7个正在运行的容器： ``` CONTAINER ID IMAGE 端口 ... postgres:15 5432->5432/tcp ... mongo:6.0 27017->27017/tcp ... neo4j:5.11.0-community 7474->7474/tcp, 7687->7687/tcp ... milvusdb/milvus:v2.2.16 19530->19530/tcp, 9091->9091/tcp ... quay.io/coreos/etcd:v3.5.5 2379->2379/tcp ... minio/minio:RELEASE.2023-03-20T20-16-18Z 9000->9000/tcp ``` ### 步骤3：等待健康检查 Docker服务包括健康检查。等待1-2分钟，所有服务变为健康： ```bash docker-compose ps ``` 查找所有服务的`(healthy)`状态。 ### 步骤4：验证数据库连接性 #### PostgreSQL ```bash docker exec 多数据库查询系统_postgres psql -U postgres -d 多数据库查询系统 -c "SELECT version();" ``` #### MongoDB ```bash docker exec 多数据库查询系统_mongo mongo --eval "db.adminCommand('ping')" ``` #### Neo4j 访问`http://localhost:7474`浏览器（用户名：`neo4j`，密码：`neo4jpassword`） #### Milvus ```bash docker logs milvus-standalone | grep "Milvus start successfully" ``` --- ## 数据库填充 数据库运行后，使用提供的种子脚本填充它们以包含样本数据。 ### 脚本前提条件 ```bash cd 后端 python -m venv .venv # 激活虚拟环境 # Windows： .\.venv\Scripts\Activate.ps1 # Unix/Linux/macOS： source .venv/bin/activate # 安装需求 pip install -r 需求.txt ``` ### 种子脚本 所有种子脚本都在`后端/脚本/`目录： ```bash cd 脚本 ``` #### 1. PostgreSQL - 种子客户 ```bash python seed_postgres_customers.py ``` - 创建`customers`表，包含150个样本客户 - 包括客户ID、姓名、电子邮件和嵌入 - 大约需要5-10秒 #### 2. MongoDB - 种子订单 ```bash python seed_mongo_orders.py ``` - 创建`orders`集合，包含500个样本订单 - 链接订单到客户ID - 包括订单金额和时间戳 - 大约需要5-10秒 #### 3. Neo4j - 种子推荐网络 ```bash python seed_neo4j_referrals.py ``` - 在客户之间创建推荐关系 - 构建客户推荐连接图 - 创建约1000个推荐边 - 大约需要10-15秒 #### 4. Milvus - 种子向量嵌入 ```bash python seed_milvus_vectors.py ``` - 为客户嵌入创建一个向量集合 - 插入150个客户嵌入以进行相似性搜索 - 构建搜索索引 - 大约需要5-10秒 ### 一次运行所有种子脚本 ```bash # 从后端/脚本目录 python seed_postgres_customers.py && \ python seed_mongo_orders.py && \ python seed_neo4j_referrals.py && \ python seed_milvus_vectors.py ``` 或逐一运行以获得更好的错误可见性。 ### 验证数据加载 #### PostgreSQL ```bash docker exec 多数据库查询系统_postgres psql -U postgres -d 多数据库查询系统 -c "SELECT COUNT(*) FROM customers;" ``` 预期输出：`150` #### MongoDB ```bash docker exec 多数据库查询系统_mongo mongo 多数据库查询系统 --eval "db.orders.countDocuments()" ``` 预期输出：`500` #### Neo4j ```bash docker exec 多数据库查询系统_neo4j cypher-shell -u neo4j -p neo4jpassword "MATCH (c:Customer) RETURN COUNT(c);" ``` 预期输出：`150` #### Milvus ```bash python -c " from pymilvus import Collection col = Collection('customer_embeddings') print(f'Milvus records: {col.num_entities}') "` 预期输出：`150` --- ## 运行后端服务 ### 设置后端环境 从`后端/`目录： ```bash # 创建虚拟环境（如果尚未完成） python -m venv .venv # 激活虚拟环境 # Windows： .\.venv\Scripts\Activate.ps1 # Unix/Linux/macOS： source .venv/bin/activate # 安装依赖项 pip install -r 需求.txt ``` ### 选项1：启动所有MCP服务（推荐） #### Windows（PowerShell） ```bash ./运行所有服务器.ps1 ``` 该脚本自动启动5个并行MCP服务，端口8000-8004。 #### Unix/Linux/macOS ```bash bash 运行所有服务器.sh ``` #### 停止所有服务 ```bash # Windows： ./运行所有服务器.ps1 stop # Unix/Linux/macOS： bash 运行所有服务器.sh stop ``` ### 选项2：手动启动服务 在单独的终端启动每个服务： #### 终端1：主FastAPI服务器 ```bash # 从后端/目录激活venv uvicorn 应用.main:应用 --port 8000 --reload ``` - 主API服务器 - 监听`http://localhost:8000` - API文档可在`http://localhost:8000/docs`访问 #### 终端2-5：MCP服务 ```bash # 终端2 uvicorn 应用.mcp_plugins.mcp_sql_sample:应用 --port 8001 --reload # 终端3 uvicorn 应用.mcp_plugins.mcp_nosql_sample:应用 --port 8002 --reload # 终端4 uvicorn 应用.mcp_plugins.mcp_graph_sample:应用 --port 8003 --reload # 终端5 uvicorn 应用.mcp_plugins.mcp_vector_sample:应用 --port 8004 --reload ``` ### 验证后端服务 ```bash # 检查主API curl http://localhost:8000/docs # 测试健康端点（如果可用） curl http://localhost:8000/health` ``` --- ## 运行前端 ### 设置前端环境 从`前端/`目录： ```bash # 安装Node.js依赖项 npm install ``` ### 启动开发服务器 ```bash npm run dev` ``` 应用程序将在`http://localhost:5173`可用 ### 构建生产版本 ```bash npm run build` ``` 输出将在`前端/dist/`中 ### 运行Linting ```bash npm run lint` npm run typecheck` ``` --- ## API测试 ### 单元集成测试 后端包含所有组件的综合测试。 #### 运行所有测试 ```bash cd 后端 # 确保虚拟环境已激活 # 激活：.venv\Scripts\Activate.ps1（Windows） # 或：source .venv/bin/activate（Unix/Linux/macOS） # 使用pytest运行测试 pytest ``` #### 运行特定测试套件 ```bash # 端到端测试 pytest 应用/测试/test_end_to_end.py -v # 错误合约测试 pytest 应用/测试/test_error_contracts.py -v # MCP适配器测试 pytest 应用/测试/test_mcp_adapters.py -v # 向量图工作流测试 pytest 应用/测试/test_vector_graph_workflows.py -v # 连接性诊断 pytest 应用/测试/test_connectivity_diagnostics.py -v ``` #### 运行简单测试脚本 ```bash python test.py` ``` 此脚本测试查询规划、执行和融合管道。 ### 使用cURL的API测试 #### 测试查询端点 ```bash curl -X POST http://localhost:8000/api/v1/query \ -H "Content-Type: application/json" \ -d '{ "query": "显示region A中客户订单 > 1000" }' ``` #### 测试模式搜索 ```bash curl http://localhost:8000/api/v1/schema/search?q=customer ``` #### 测试聊天端点 ```bash curl -X POST http://localhost:8000/api/v1/chat \ -H "Content-Type: application/json" \ -d '{ "message": "哪些客户的订单量最高？" }' ``` ### API文档（交互式Swagger UI） 一旦后端运行，请访问： ``` http://localhost:8000/docs` ``` 提供交互式接口以测试所有API端点，并自动生成文档。 --- ## API端点参考 ### 查询端点 **POST** `/api/v1/query` 跨所有数据库执行自然语言查询。 **请求：** ```json { "query": "显示cust001相似的客户", "include_provenance": true }` ``` **响应：` { "results": { "customer": { ... }, "similar_customers": [ ... ], "orders": [ ... ], "referrals": [ ... ] }, "provenance": [ "客户信息来自sql_customers", "相似客户来自milvus_vector_search", "订单来自nosql_orders", "推荐来自graph_referral_network" ] } ``` ### 模式搜索端点 **GET** `/api/v1/schema/search?q=<查询>` 搜索跨所有数据库的可用字段。 **响应：` { "results": [ { "source": "sql_customers", "fields": ["id", "name", "email"] }, { "source": "nosql_orders", "fields": ["order_id", "customer_id", "amount"] } ] }` ### 聊天端点 **POST** `/api/v1/chat` 多轮对话接口用于查询。 **请求：` { "message": "哪些客户的订单量最高？", "conversation_id": "conv_123" }` ### 来源端点 **GET** `/api/v1/sources` 列出所有连接的数据源及其状态。 **响应：` { "sources": [ { "name": "sql_customers", "type": "sql", "status": "connected", "port": 8001 }, { "name": "nosql_orders", "type": "nosql", "status": "connected", "port": 8002 } ] }` --- ## 故障排除 ### 数据库未启动 ```bash # 检查Docker守护进程是否运行 docker ps # 查看docker-compose日志 docker-compose logs # 重建容器 docker-compose down -v docker-compose up -d ``` ### 数据库连接错误 1. 检查服务是否健康 docker-compose ps # 等待健康检查通过（2-3分钟） # 然后再次尝试填充 ``` ### Python虚拟环境问题 ```bash # 删除并重新创建虚拟环境 rm -rf .venv # (Windows上使用rd /s .venv) python -m venv .venv` # 重新激活并重新安装 # Windows：.venv\Scripts\Activate.ps1 # Unix：source .venv/bin/activate pip install -r requirements.txt ``` ### 前端端口已被占用 ```bash # 在vite.config.ts中更改端口或使用： npm run dev -- --port 5174 ``` ### 后端端口已被占用 ```bash # 杀死端口上的进程 # Windows PowerShell： Stop-Process -Id (Get-NetTCPConnection -LocalPort 8000).OwningProcess -Force # Unix/Linux： lsof -ti :8000 | xargs kill -9 ``` ### 测试失败 ```bash # 确保数据库正在运行且健康 docker-compose ps # 确保所有设置脚本已运行 cd scripts python seed_postgres_customers.py python seed_mongo_orders.py python seed_neo4j_referrals.py python seed_milvus_vectors.py # 使用详细输出运行 pytest -vvs ``` ### 无法连接到Gemini API ```bash # 在.env文件中验证API密钥 cat .env | grep GEMINI_API_KEY # 确保密钥有效且在Google AI Studio中处于活动状态 # 添加到.env： GEMINI_API_KEY=您的实际密钥` # 重启后端服务 ``` --- ## 开发工作流 ### 本地开发设置清单 - [ ] 克隆仓库 - [ ] 创建.env文件，包含`GEMINI_API_KEY` - [ ] 启动Docker数据库：`docker-compose up -d` - [ ] 等待2-3分钟进行健康检查 - [ ] 运行种子脚本来自`后端/脚本/` - [ ] 激活venv并安装Python依赖项 - [ ] 启动后端服务（全部或手动） - [ ] 安装前端依赖项：`npm install` - [ ] 启动前端：`npm run dev` - [ ] 在浏览器中打开`http://localhost:5173` ### 常见开发命令 ```bash # 后端 cd backend .\.venv\Scripts\Activate.ps1 # Windows source .venv/bin/activate # Unix uvicorn 应用.main:应用 --port 8000 --reload # 启动主服务器 pytest -vvs # 运行测试 # 前端 cd frontend npm install # 安装依赖项 npm run dev # 启动开发服务器 npm run build # 构建生产版本 npm run lint # 检查代码风格 # Docker docker-compose up -d # 启动数据库 docker-compose down -v # 停止并删除卷 docker-compose logs -f <服务> # 查看日志 ``` --- ## 附加资源 ### 键文件和文档 - **后端架构：** 参见 [后端/README.md](后端/README.md) - **前端设置：** 参见 [前端/README.md](前端/README.md) - **配置：** 参见 `后端/.env` 和 `后端/核心/config.py` - **API测试：** 参见 `后端/应用/测试/` ### 外部文档 - **FastAPI：** https://fastapi.tiangolo.com/ - **Docker Compose：** https://docs.docker.com/compose/ - **React + Vite：** https://vitejs.dev/ - **谷歌Gemini API：** https://ai.google.dev/ - **PyMilvus：** https://github.com/milvus-io/pymilvus --- ## 贡献 进行更改时： 1. 创建一个功能分支 2. 在单独的终端中进行更改，以避免破坏正在运行的服务 3. 运行测试：`pytest` 4. 运行linting：`npm run lint`（前端）或`flake8`（后端） 5. 提交带有描述性消息的提交 6. 推送并创建一个拉取请求 --- ## 许可 [在此添加您的许可信息] --- ## 支持 对于问题或疑问： 1. 查看 [故障排除](#-故障排除) 部分 2. 查看日志：`docker-compose logs` 或测试输出 3. 检查API文档：`http://localhost:8000/docs` 4. 查看测试文件以获取使用示例 快乐查询！ 🚀