docs: rewrite README to reflect current architecture and features
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -1,291 +1,121 @@
|
|||||||
# 国土空间规划课程智能体 - Docker单容器版本
|
# 国土空间规划课程智能体
|
||||||
|
|
||||||
一个基于大模型的智能问答系统，专门为国土空间规划课程设计。本版本将所有服务整合到单个Docker容器中，简化部署和管理。
|
基于大模型和 RAG 的国土空间规划课程智能问答系统，支持多模态文档理解、知识图谱、AI 绘图和论坛交流。
|
||||||
|
|
||||||
## 🎯 项目特色
|
## 功能概览
|
||||||
|
|
||||||
- **单容器架构**: 前端和后端服务整合在一个容器中，使用supervisor管理进程
|
| 模块 | 说明 |
|
||||||
- **AI驱动**: 集成硅基流动大模型和LangGraph工作流
|
|------|------|
|
||||||
- **RAG增强**: 基于Chroma向量数据库的智能检索
|
| **智能问答** | RAG 检索增强生成，支持流式输出、多模型切换、思考过程展示 |
|
||||||
- **响应式设计**: 完美适配手机、平板、桌面设备
|
| **多模态 RAG** | PDF 图片自动提取 + VLM 描述生成，问答结果中直接展示图片 |
|
||||||
- **现代化技术栈**: Next.js 15 + React 19 + FastAPI + Python 3.12
|
| **知识库管理** | 上传 PDF/DOCX/TXT/MD 文档，自动分块、向量化入库 |
|
||||||
|
| **课程内容** | 知识图谱可视化，教材章节结构浏览 |
|
||||||
|
| **AI 绘图** | 文生图（Stable Diffusion）、图生图，SiliconFlow API 驱动 |
|
||||||
|
| **论坛** | 分类讨论区，支持发帖、回复 |
|
||||||
|
| **用户系统** | JWT 认证，管理员/普通用户角色分离 |
|
||||||
|
|
||||||
## 🏗️ 技术架构
|
## 技术架构
|
||||||
|
|
||||||
### 单容器架构
|
|
||||||
|
|
||||||
```
|
```
|
||||||
┌─────────────────────────────────────┐
|
用户浏览器
|
||||||
│ Docker Container │
|
│
|
||||||
│ ┌─────────────┐ ┌──────────────┐ │
|
▼
|
||||||
│ │ Backend │ │ Frontend │ │
|
Next.js 15 (:8001) ←── Turbopack 构建
|
||||||
│ │ FastAPI │ │ Next.js │ │
|
│ /api/* → 反向代理
|
||||||
│ │ :8000 │ │ :8001 │ │
|
│ /images/* → 反向代理
|
||||||
│ └─────────────┘ └──────────────┘ │
|
▼
|
||||||
│ │ │ │
|
FastAPI (:8000)
|
||||||
│ └──────┬─────────┘ │
|
├── LangGraph 工作流 (analyze → retrieve → generate)
|
||||||
│ Supervisor │
|
├── RAG 管线
|
||||||
└─────────────────────────────────────┘
|
│ ├── text2vec-base-chinese (嵌入)
|
||||||
│
|
│ ├── ChromaDB (向量存储)
|
||||||
▼
|
│ ├── pymupdf (PDF 图片提取)
|
||||||
┌──────────────────┐
|
│ └── Qwen3-VL-8B (图片描述生成)
|
||||||
│ PostgreSQL │
|
├── LLM 路由
|
||||||
│ Database │
|
│ ├── SiliconFlow (Qwen/DeepSeek 系列)
|
||||||
└──────────────────┘
|
│ └── DeepSeek 官方 API
|
||||||
|
└── SQLAlchemy ORM
|
||||||
|
├── SQLite (本地开发)
|
||||||
|
└── PostgreSQL (Docker 部署)
|
||||||
```
|
```
|
||||||
|
|
||||||
### 技术栈
|
## 技术栈
|
||||||
|
|
||||||
**后端**:
|
**后端**: Python 3.12 / FastAPI / LangChain / LangGraph / ChromaDB / SQLAlchemy / pymupdf
|
||||||
- FastAPI + Uvicorn
|
|
||||||
- LangChain + LangGraph
|
|
||||||
- 硅基流动API (Qwen3-30B)
|
|
||||||
- Chroma向量数据库
|
|
||||||
- PostgreSQL
|
|
||||||
|
|
||||||
**前端**:
|
**前端**: Next.js 15 / React 19 / TypeScript / TailwindCSS / shadcn/ui / Zustand
|
||||||
- Next.js 15 (App Router)
|
|
||||||
- React 19
|
|
||||||
- TypeScript
|
|
||||||
- TailwindCSS + shadcn/ui
|
|
||||||
|
|
||||||
## 📁 项目结构
|
**部署**: Docker + Supervisor (单容器) / PostgreSQL
|
||||||
|
|
||||||
```
|
## 快速开始
|
||||||
course_Agent/
|
|
||||||
├── backend/ # Python后端代码
|
|
||||||
│ ├── src/ # 源代码
|
|
||||||
│ ├── main.py # 应用入口
|
|
||||||
│ ├── pyproject.toml # 依赖配置
|
|
||||||
│ └── migrations/ # 数据库迁移
|
|
||||||
├── web/ # Next.js前端代码
|
|
||||||
│ ├── src/ # 源代码
|
|
||||||
│ ├── public/ # 静态资源
|
|
||||||
│ └── package.json # 依赖配置
|
|
||||||
├── docker/ # Docker相关文件
|
|
||||||
│ ├── supervisord.conf # Supervisor配置
|
|
||||||
│ └── start.sh # 启动脚本
|
|
||||||
├── data/ # 数据目录（挂载卷）
|
|
||||||
├── vector_store/ # 向量数据库（挂载卷）
|
|
||||||
├── uploads/ # 上传文件（挂载卷）
|
|
||||||
├── logs/ # 日志文件（挂载卷）
|
|
||||||
├── generated_images/ # 生成的图像（挂载卷）
|
|
||||||
├── Dockerfile # Docker构建文件
|
|
||||||
├── docker-compose.yml # Docker Compose配置
|
|
||||||
└── README.md # 本文件
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🚀 快速开始
|
|
||||||
|
|
||||||
### 前置要求
|
|
||||||
|
|
||||||
- Docker 20.10+
|
|
||||||
- Docker Compose 2.0+
|
|
||||||
|
|
||||||
### 1. 克隆项目
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd course_Agent
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 配置环境变量
|
|
||||||
|
|
||||||
复制环境变量模板：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cp env.example .env
|
|
||||||
```
|
|
||||||
|
|
||||||
编辑 `.env` 文件，配置必要的参数（API密钥、数据库密码等）。
|
|
||||||
|
|
||||||
### 3. 启动服务
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 构建并启动所有服务
|
|
||||||
docker-compose up -d
|
|
||||||
|
|
||||||
# 查看日志
|
|
||||||
docker-compose logs -f
|
|
||||||
|
|
||||||
# 查看服务状态
|
|
||||||
docker-compose ps
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. 访问应用
|
|
||||||
|
|
||||||
- **前端应用**: http://localhost:8001
|
|
||||||
- **后端API**: http://localhost:8000
|
|
||||||
- **API文档**: http://localhost:8000/docs
|
|
||||||
|
|
||||||
### 5. 停止服务
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker-compose down
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔧 服务管理
|
|
||||||
|
|
||||||
### 查看日志
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 查看所有服务日志
|
|
||||||
docker-compose logs -f
|
|
||||||
|
|
||||||
# 查看特定服务日志
|
|
||||||
docker-compose logs -f app
|
|
||||||
docker-compose logs -f db
|
|
||||||
```
|
|
||||||
|
|
||||||
### 重启服务
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 重启所有服务
|
|
||||||
docker-compose restart
|
|
||||||
|
|
||||||
# 重启特定服务
|
|
||||||
docker-compose restart app
|
|
||||||
```
|
|
||||||
|
|
||||||
### 进入容器
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 进入应用容器
|
|
||||||
docker-compose exec app bash
|
|
||||||
|
|
||||||
# 在容器内查看进程状态
|
|
||||||
supervisorctl status
|
|
||||||
```
|
|
||||||
|
|
||||||
### 数据库操作
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 进入数据库容器
|
|
||||||
docker-compose exec db psql -U user -d course_agent_db
|
|
||||||
|
|
||||||
# 备份数据库
|
|
||||||
docker-compose exec db pg_dump -U user course_agent_db > backup.sql
|
|
||||||
|
|
||||||
# 恢复数据库
|
|
||||||
docker-compose exec -T db psql -U user course_agent_db < backup.sql
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📊 数据持久化
|
|
||||||
|
|
||||||
以下目录通过Docker volumes挂载，数据会持久化到宿主机：
|
|
||||||
|
|
||||||
- `./data` → `/app/data` - 知识库数据
|
|
||||||
- `./vector_store` → `/app/vector_store` - 向量数据库
|
|
||||||
- `./uploads` → `/app/uploads` - 用户上传文件
|
|
||||||
- `./logs` → `/app/logs` - 日志文件
|
|
||||||
- `./generated_images` → `/app/generated_images` - 生成的图像
|
|
||||||
|
|
||||||
## 🔍 故障排除
|
|
||||||
|
|
||||||
### 服务无法启动
|
|
||||||
|
|
||||||
1. 检查端口是否被占用：
|
|
||||||
```bash
|
|
||||||
netstat -ano | findstr :8000
|
|
||||||
netstat -ano | findstr :8001
|
|
||||||
```
|
|
||||||
|
|
||||||
2. 查看容器日志：
|
|
||||||
```bash
|
|
||||||
docker-compose logs app
|
|
||||||
```
|
|
||||||
|
|
||||||
3. 检查环境变量配置：
|
|
||||||
```bash
|
|
||||||
docker-compose exec app env | grep DATABASE_URL
|
|
||||||
```
|
|
||||||
|
|
||||||
### 数据库连接失败
|
|
||||||
|
|
||||||
1. 确保数据库服务已启动：
|
|
||||||
```bash
|
|
||||||
docker-compose ps db
|
|
||||||
```
|
|
||||||
|
|
||||||
2. 检查数据库连接字符串：
|
|
||||||
```bash
|
|
||||||
docker-compose exec app env | grep DATABASE_URL
|
|
||||||
```
|
|
||||||
|
|
||||||
### 前端无法访问后端
|
|
||||||
|
|
||||||
1. 检查后端服务是否运行：
|
|
||||||
```bash
|
|
||||||
curl http://localhost:8000/health
|
|
||||||
```
|
|
||||||
|
|
||||||
2. 检查CORS配置：
|
|
||||||
```bash
|
|
||||||
docker-compose exec app env | grep ALLOWED_ORIGINS
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🛠️ 开发指南
|
|
||||||
|
|
||||||
### 本地开发
|
### 本地开发
|
||||||
|
|
||||||
如果需要本地开发（不使用Docker）：
|
**后端** (终端 1):
|
||||||
|
|
||||||
1. **启动后端**:
|
|
||||||
```bash
|
```bash
|
||||||
cd backend
|
cd backend
|
||||||
uv sync
|
uv sync
|
||||||
uv run main.py
|
uv run main.py # http://localhost:8000
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **启动前端** (新终端):
|
**前端** (终端 2):
|
||||||
```bash
|
```bash
|
||||||
cd web
|
cd web
|
||||||
pnpm install
|
pnpm install
|
||||||
pnpm dev
|
pnpm dev # http://localhost:8001
|
||||||
```
|
```
|
||||||
|
|
||||||
### 修改代码后重建镜像
|
### Docker 部署
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 重新构建镜像
|
cp env.example .env # 编辑 .env，配置 SILICONFLOW_API_KEY 等
|
||||||
docker-compose build app
|
docker-compose up -d # http://localhost:8001
|
||||||
|
|
||||||
# 重启服务
|
|
||||||
docker-compose up -d app
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 📝 环境变量说明
|
## 项目结构
|
||||||
|
|
||||||
主要环境变量（完整列表见 `env.example`）：
|
```
|
||||||
|
course_agent_od/
|
||||||
|
├── backend/
|
||||||
|
│ ├── main.py # 应用入口
|
||||||
|
│ ├── pyproject.toml # 依赖 (uv)
|
||||||
|
│ └── src/
|
||||||
|
│ ├── api/ # FastAPI 路由
|
||||||
|
│ ├── core/ # 配置、数据库、安全
|
||||||
|
│ ├── rag/ # RAG 管线
|
||||||
|
│ │ ├── chains.py # RAGChain
|
||||||
|
│ │ ├── retrievers.py # KnowledgeBaseRetriever
|
||||||
|
│ │ ├── document_loaders.py # PDFImageExtractor
|
||||||
|
│ │ ├── vector_store.py # ChromaDB 封装
|
||||||
|
│ │ └── prompts.py # 提示词模板
|
||||||
|
│ ├── llm/ # LLM 客户端 + VLM
|
||||||
|
│ ├── graph/ # LangGraph 工作流
|
||||||
|
│ ├── models/ # SQLAlchemy ORM
|
||||||
|
│ └── services/ # 业务逻辑
|
||||||
|
├── web/
|
||||||
|
│ ├── next.config.js # 反向代理配置
|
||||||
|
│ └── src/
|
||||||
|
│ ├── app/(main)/ # 页面路由
|
||||||
|
│ ├── components/chat/ # 聊天组件
|
||||||
|
│ ├── store/ # Zustand 状态管理
|
||||||
|
│ └── lib/api.ts # API 客户端
|
||||||
|
├── data/ # 运行时数据 (.gitignore)
|
||||||
|
├── docker/ # Docker + Supervisor 配置
|
||||||
|
├── Dockerfile
|
||||||
|
└── docker-compose.yml
|
||||||
|
```
|
||||||
|
|
||||||
- `DATABASE_URL`: 数据库连接字符串
|
## 环境变量
|
||||||
- `SILICONFLOW_API_KEY`: 硅基流动API密钥
|
|
||||||
- `SECRET_KEY`: JWT密钥
|
|
||||||
- `VECTOR_STORE_PATH`: 向量数据库路径
|
|
||||||
- `KNOWLEDGE_BASE_DIR`: 知识库目录
|
|
||||||
|
|
||||||
## 🔐 安全建议
|
关键变量见 `env.example`：
|
||||||
|
|
||||||
1. **生产环境**:
|
| 变量 | 说明 |
|
||||||
- 修改所有默认密码和密钥
|
|------|------|
|
||||||
- 使用强密码
|
| `SILICONFLOW_API_KEY` | SiliconFlow LLM/VLM API 密钥 (必需) |
|
||||||
- 配置HTTPS（通过Nginx反向代理）
|
| `DATABASE_URL` | SQLite 或 PostgreSQL 连接串 |
|
||||||
- 限制数据库访问
|
| `SECRET_KEY` | JWT 签名密钥 |
|
||||||
|
| `POSTGRES_PASSWORD` | PostgreSQL 密码 (Docker) |
|
||||||
|
|
||||||
2. **数据备份**:
|
## 许可证
|
||||||
- 定期备份PostgreSQL数据库
|
|
||||||
- 备份向量数据库和知识库文件
|
|
||||||
|
|
||||||
## 📄 许可证
|
|
||||||
|
|
||||||
MIT License
|
MIT License
|
||||||
|
|
||||||
## 📞 技术支持
|
|
||||||
|
|
||||||
如有问题或建议，请联系开发团队。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**版本**: v1.0.0 (单容器版本)
|
|
||||||
**最后更新**: 2025年1月
|
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user