🧠 研究助理GraphRAG系统
一个全面的、人工智能驱动的研究助手，将图形数据库技术与检索增强生成（GraphRAG）相结合，提供智能文档处理、高级实体提取和知识图构建。具有MCP（模型上下文协议）集成功能，可增强文档上传和处理能力。
✨ 特性
核心能力
- 📤 多格式文档上传：支持CSV、PDF、TXT、JSON和Markdown文件
- 🎯 高级实体提取：基于规则+LLM的实体检测，具有置信度评分
- 🕸️ 自动化知识图谱：Neo4j支持关系推理的图构造
- 🧠 MCP集成：模型上下文协议支持增强的AI交互
- 💬 智能聊天系统：带有实体参考和引用的情境感知回复
- 📊 实时处理：文档处理任务的实时进度跟踪
- 🔍 基于图形的搜索：高效检索相互关联的信息
- ⚡ 高性能：针对批处理和大型文档收集进行了优化
支持的实体类型
- 人：研究人员、作者、高管
- 组织：公司、大学、研究机构
- 技术：工具、框架、算法、软件系统
- 概念：理论、方法、科学范式
- 位置地理实体、研究设施
🏗️ 建筑
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ File Upload │───▶│ Entity Extract │───▶│ Graph Construct │
│ & Validation │ │ & Processing │ │ & Storage │
│ │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MCP Server │───▶│ Reasoning │───▶│ Query │
│ Integration │ │ Engine │ │ Response │
│ │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘技术栈
- 后端：Python 3.9+、FastAPI、Uvicorn
- 前端：Next.js 16、React 19、TypeScript、顺风CSS
- 数据库：Neo4j（图形数据库），Redis（缓存）
- AI/ML：Olama（LLM），Granite4模型，自定义实体提取
- 基础设施：Docker，Docker Compose
- 协议：MCP（模型上下文协议）
🚀 快速开始
先决条件
在运行系统之前，请确保已安装以下内容：
- Python 3.9+ 使用pip
- Node.js 16+ 使用npm
- Docker&Docker编写 （适用于Neo4j和Redis）
- 奥拉玛 （用于本地LLM支持）
安装
- 克隆存储库
git clone https://github.com/yourusername/research-assistant-graphrag.git
cd research-assistant-graphrag- 运行自动安装脚本
./setup.sh此脚本将：
- 创建Python虚拟环境 - 安装所有Python和Node.js依赖项 - 启动Docker服务（Neo4j、Redis） - 下载所需的Olama型号 - 创建必要的目录和索引
- 启动应用程序
./start.sh这将开始：
- Neo4j数据库（图形数据库） - Redis（缓存） - Ollama服务（LLM） - FastAPI后端服务器（端口8000） - Next.js前端（端口3000）
- 访问应用程序
- 前端: http://localhost:3000 - API 文档: http://localhost:8000/docs - Neo4j浏览器: http://localhost:7474（作者：neo4j/研究2025） - 健康检查: http://localhost:8000/api/health
📤 文档上传与处理
文件上载API
上传文件 （职位 /api/upload/files):
curl -X POST "http://localhost:8000/api/upload/files" \
-F "files=@document.pdf" \
-F "files=@research_paper.txt"处理上传的文件 （职位 /api/upload/process):
curl -X POST "http://localhost:8000/api/upload/process" \
-H "Content-Type: application/json" \
-d '{
"session_id": "your-session-id",
"entity_types": ["Person", "Organization", "Technology", "Concept"],
"confidence_threshold": 0.6,
"max_chunk_size": 1000,
"overlap_size": 200
}'检查处理进度 （得到 /api/upload/progress/{task_id}):
curl http://localhost:8000/api/upload/progress/your-task-id支持的文件格式
- PDF：研究论文、技术文件
- 文本：纯文本文件
- JSON：结构化数据
- CSV：表格数据
- 标记语言：文档文件
限制:
- 每次上传最多20个文件
- 单个文件大小限制：50MB
- 总上传大小限制：200MB
💬 聊天与查询系统
基本聊天
curl -X POST "http://localhost:8000/api/chat" \
-H "Content-Type: application/json" \
-d '{
"message": "What are the key findings about transformers in the uploaded papers?",
"context": "research_papers"
}'高级查询功能
- 实体感知响应：返回具有置信度得分的相关实体
- 引文追踪：参考源文件和章节
- 主题层次结构：按相关概念组织回应
- 共现分析：显示相互关联的想法
🔧 配置
环境变量
创建一个 .env 根目录中的文件：
# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=research2025
# Ollama Configuration
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=granite4:micro-h
# Redis Configuration
REDIS_URL=redis://localhost:6379
# Application Settings
UPLOAD_BATCH_SIZE=10
MAX_FILE_SIZE=50000000
CONTEXT_WINDOW_SIZE=8000
CONFIDENCE_THRESHOLD=0.6
# MCP Settings
MCP_SERVER_PORT=3001
MCP_MAX_CONTEXT_TOKENS=16000Neo4j设置
该系统使用Neo4j进行图形存储。默认凭据：
- 用户名：neo4j
- 密码：研究2025
- 螺栓端口: 7687
- 浏览器端口: 7474
Olama模型
所需Olama型号：
granite4:micro-h（主要推理模型）mxbai-embed-large:latest（嵌入相似性模型）
🧪 开发与测试
运行测试
# Backend tests
python -m pytest
# Frontend tests
cd frontend && npm test发展模式
# Start backend in development mode
python main.py --reload
# Start frontend in development mode
cd frontend && npm run dev数据库管理
# Create indexes
python create_indexes.py
# Create thread relationships
python create_thread_relationships.py
# Debug database
python debug_db.py📊 监测和健康检查
API终点
- 健康检查:
GET /api/health
{
"status": "healthy",
"timestamp": "2025-11-18T12:00:00.000Z",
"services": {
"neo4j": "connected",
"ollama": "ready",
"redis": "connected"
}
}- 系统状态:
GET /api/status
{
"total_documents": 1250,
"total_entities": 3420,
"total_topics": 450,
"uptime_seconds": 3600
}日志
- Neo4j日志：
neo4j-logs/ - 应用程序日志：检查正在运行的服务的控制台输出
- Docker日志：
docker-compose logs
🚢 部署
开发部署
为当地发展提供所有服务：
# Use the simple setup and start scripts
./setup.sh # One-time setup
./start.sh # Start all servicesDocker开发部署
# Start services using Docker Compose
docker-compose up --build
# Start in background
docker-compose up -d生产Docker部署
对于具有适当编排的生产部署：
- 生产设置
# Copy production environment variables
cp .env.example .env
# Edit .env with your production values
# Start production services
docker-compose -f docker-compose.prod.yml up --build -d
# To include Ollama and Nginx
docker-compose -f docker-compose.prod.yml --profile with-ollama --profile with-nginx up -d- 生产配置
# Required environment variables for production
NEO4J_URI=bolt://your-neo4j-host:7687
NEO4J_USERNAME=production_user
NEO4J_PASSWORD=secure_password_123
REDIS_URL=redis://your-redis-cluster:6379
DEBUG=false
SECRET_KEY=your-production-secret-key-min-32-chars
LOG_LEVEL=INFO
HOST=0.0.0.0
FRONTEND_URL=https://yourdomain.com
ALLOWED_ORIGINS=https://yourdomain.com生产服务配置
Neo4j企业设置
# docker-compose.prod.yml (relevant section)
neo4j:
image: neo4j:5.20-enterprise
environment:
- NEO4J_AUTH=${NEO4J_USERNAME}/${NEO4J_PASSWORD}
- NEO4J_PLUGINS=["apoc", "graph-data-science"]
- NEO4J_dbms_memory_heap_initial__size=512m
- NEO4J_dbms_memory_heap_max__size=4G
- NEO4J_dbms_memory_pagecache_size=2G缩放注意事项
- Neo4j：使用带集群的Neo4j Enterprise实现高可用性
- 瑞迪斯：使用Redis集群进行横向扩展和持久化
- 应用：使用负载均衡器和多个实例进行部署
- 奥拉玛：使用专用GPU实例以获得更好的LLM性能
使用Nginx的反向代理
生产设置包括可选的Nginx反向代理，具有：
- 速率限制：防止API滥用
- 负载平衡：跨实例分发请求
- SSL终止：处理HTTPS证书
- 安全标头：添加与安全相关的HTTP标头
- 静态文件服务：优化资产交付
监测和健康检查
# Check service health
curl http://localhost/api/health
# View service logs
docker-compose -f docker-compose.prod.yml logs -f
# Monitor resource usage
docker stats🤝 贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
开发设置
# Install development dependencies
pip install -r requirements-dev.txt
cd frontend && npm install
# Run linting
python -m flake8
cd frontend && npm run lint
# Run tests
python -m pytest
cd frontend && npm test📚 API 参考
上传端点
POST /api/upload/files-上传多个文件POST /api/upload/process-开始文档处理GET /api/upload/progress/{task_id}-获取处理状态DELETE /api/upload/progress/{task_id}-取消处理
聊天端点
POST /api/chat-发送聊天信息GET /api/search-搜索文档和实体POST /api/graph-rag/query-高级基于图的查询
系统端点
GET /api/health-健康检查GET /api/status-系统统计GET /api/evaluation-results-性能指标
MCP端点
GET /mcp/documents/{id}-通过MCP访问文档GET /mcp/entities/{id}-访问实体信息POST /mcp/tools/search-用于图形搜索的MCP工具
🐛 故障排除
常见问题
- Neo4j连接失败
- 确保Docker服务正在运行： docker-compose ps - 查看Neo4j日志： docker-compose logs neo4j - 验证中的凭据 .env 文件
- Ollama无法进入
- 启动Ollama： ollama serve - 拉动所需型号： ollama pull granite4:micro-h - 检查Ollama状态： ollama list
- 端口冲突
- 前端默认为端口3000，后端默认为8000 - 检查使用端口的内容： lsof -i :3000 - 必要时修改配置中的端口
- 内存问题
- 增加Docker内存限制 - 优化配置中的块大小 - 考虑Ollama的GPU加速
数据库重置
# Stop all services
docker-compose down
# Remove database volumes
docker volume rm research-assistant-graphrag_neo4j-data research-assistant-graphrag_redis-data
# Rebuild and restart
docker-compose up --build📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
📞 支持
如需支持，请：
🗺️ 路线图
- \[\]多语言文档支持
- \[\]高级图形可视化
- \[\]与外部API（ArXiv、PubMed）集成
- \[\]提取实体的机器学习模型训练
- \[\]实时协作功能
- \[\]移动应用伴侣