Skip to content

QUICKSTART.md

Latest commit

 

History

History
266 lines (209 loc) · 5.78 KB

QUICKSTART.md

File metadata and controls

266 lines (209 loc) · 5.78 KB

GraphChat 快速开始

🚀 项目简介

GraphChat 是一个创新的网状思维图谱AI助手，打破传统线性对话模式，通过图谱结构组织知识，让AI交互更符合人类思维习惯。

✨ 核心特性

  • 网状思维界面：用节点和连线替代传统聊天框，支持多分支、跨主题的思维展开
  • 注意力追踪：记录用户的交互轨迹，让AI理解思维重点和偏好
  • 智能推荐：基于注意力数据提供个性化内容推荐和思维拓展
  • 管理后台：提供用户行为分析、图谱复盘、系统监控等运营工具
  • 实时协作：WebSocket支持的实时图谱更新和多用户同步

📋 前置要求

  • Docker >= 20.10
  • Docker Compose >= 1.29
  • Node.js >= 18 (开发前端)
  • Python 3.12 (开发后端)

🏗️ 架构概览

GraphChat/
├── backend/          # FastAPI 后端
│   ├── app/
│   │   ├── api/      # API路由
│   │   ├── models/   # 数据库模型
│   │   ├── schemas/  # Pydantic模型
│   │   ├── services/ # 业务逻辑
│   │   └── core/     # 核心工具
│   └── alembic/      # 数据库迁移
├── frontend/         # React 前端
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── services/
│   │   └── stores/
│   └── public/
├── docker-compose.yml
└── scripts/
    ├── dev.sh        # 开发环境启动
    └── prod.sh       # 生产环境启动

🛠️ 快速启动

方式一：使用启动脚本（推荐）

  1. 开发环境
# 启动完整开发环境（数据库 + 后端 + 前端）
./scripts/dev.sh
  1. 生产环境
# 启动生产环境（Docker部署）
./scripts/prod.sh

方式二：手动启动

  1. 启动数据库和缓存
docker-compose up -d postgres redis
  1. 配置后端
cd backend
cp .env.example .env
# 编辑 .env 文件，填入 OpenAI API Key
uv add -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload
  1. 启动前端
cd frontend
npm install
npm run dev

📍 服务地址

服务 地址 说明
前端应用 http://localhost:3000 React应用
后端API http://localhost:8000 FastAPI服务器
API文档 http://localhost:8000/api/v1/docs Swagger文档
PostgreSQL localhost:5432 数据库
Redis localhost:6379 缓存

🔧 开发指南

后端开发

  1. 安装依赖
cd backend
uv add <package-name>
  1. 数据库迁移
# 创建迁移
alembic revision --autogenerate -m "描述"

# 应用迁移
alembic upgrade head

# 回滚
alembic downgrade -1
  1. 运行测试
pytest app/tests/

前端开发

  1. 安装依赖
cd frontend
npm install
  1. 代码规范
# ESLint 检查
npm run lint

# 自动修复
npm run lint:fix

# Prettier 格式化
npm run format
  1. 构建生产版本
npm run build

📦 技术栈

后端

  • FastAPI - 现代Python Web框架
  • SQLAlchemy - ORM
  • Alembic - 数据库迁移
  • PostgreSQL - 主数据库
  • Redis - 缓存
  • OpenAI - AI接口
  • JWT - 认证

前端

  • React 18 - UI框架
  • TypeScript - 类型安全
  • Vite - 构建工具
  • Tailwind CSS - 样式框架
  • D3.js - 图谱可视化核心
  • Cytoscape.js - 高级图谱渲染（管理后台）
  • Zustand - 状态管理
  • React Router - 路由管理
  • React Hot Toast - 消息提示
  • Lucide React - 图标库

📝 环境变量

后端 (.env)

DEBUG=true
POSTGRES_SERVER=localhost
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=graphchat
POSTGRES_PORT=5432

SECRET_KEY=your-secret-key

OPENAI_API_KEY=your-openai-api-key
OPENAI_MODEL=gpt-3.5-turbo

前端 (.env)

VITE_API_URL=http://localhost:8000/api/v1

🐛 常见问题

Q: 数据库连接失败

# 确保 PostgreSQL 正在运行
docker-compose up -d postgres

# 检查连接
psql -h localhost -U postgres -d graphchat

Q: 前端无法连接后端

# 检查 CORS 设置
# 确保后端 ALLOWED_HOSTS 包含前端地址

# 检查代理配置
# Vite 配置中的 proxy 设置

Q: OpenAI 调用失败

# 检查 API Key 是否正确
# 确认网络连接
# 检查配额是否充足

📚 相关资源

🤝 贡献指南

  1. Fork 项目
  2. 创建功能分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送分支 (git push origin feature/AmazingFeature)
  5. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

🎯 路线图

✅ 已完成 (v0.1 + v0.2)

  • 基础用户系统（注册/登录）
  • D3.js图谱可视化实现
  • WebSocket实时通信
  • 注意力追踪系统
  • 管理后台（用户管理/图谱复盘）
  • AI对话集成

🚧 v0.3 规划（图谱智能化）

  • 图谱语义聚类与自动主题命名
  • 注意力驱动的AI主动学习机制
  • 图谱关系预测和智能推荐
  • 图谱回放（思维路径动态可视化）

🔮 未来版本

  • 多人协作模式（团队图谱共享）
  • 多模态节点支持（图片/文件/链接）
  • 移动端适配优化
  • 插件系统扩展
  • 导出/导入功能增强

项目状态: 🚀 v0.2 已完成 - 管理后台与注意力追踪系统

联系方式: 请通过 GitHub Issues 提交问题和建议