docs: rewrite README to reflect current architecture and features

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-29 21:20:57 +08:00
parent b8253b86a0
commit 1a3730c33c
1 changed files with 85 additions and 255 deletions
@@ -1,291 +1,121 @@
-# 国土空间规划课程智能体 - Docker单容器版本
+# 国土空间规划课程智能体

-一个基于大模型的智能问答系统，专门为国土空间规划课程设计。本版本将所有服务整合到单个Docker容器中，简化部署和管理。
+基于大模型和 RAG 的国土空间规划课程智能问答系统，支持多模态文档理解、知识图谱、AI 绘图和论坛交流。

-## 🎯 项目特色
+## 功能概览

- **单容器架构**: 前端和后端服务整合在一个容器中，使用supervisor管理进程
- **AI驱动**: 集成硅基流动大模型和LangGraph工作流
- **RAG增强**: 基于Chroma向量数据库的智能检索
- **响应式设计**: 完美适配手机、平板、桌面设备
- **现代化技术栈**: Next.js 15 + React 19 + FastAPI + Python 3.12
+| 模块 | 说明 |
+|------|------|
+| **智能问答** | RAG 检索增强生成，支持流式输出、多模型切换、思考过程展示 |
+| **多模态 RAG** | PDF 图片自动提取 + VLM 描述生成，问答结果中直接展示图片 |
+| **知识库管理** | 上传 PDF/DOCX/TXT/MD 文档，自动分块、向量化入库 |
+| **课程内容** | 知识图谱可视化，教材章节结构浏览 |
+| **AI 绘图** | 文生图（Stable Diffusion）、图生图，SiliconFlow API 驱动 |
+| **论坛** | 分类讨论区，支持发帖、回复 |
+| **用户系统** | JWT 认证，管理员/普通用户角色分离 |

-## 🏗️ 技术架构
-
-### 单容器架构
+## 技术架构

 ```
-┌─────────────────────────────────────┐
-│         Docker Container            │
-│  ┌─────────────┐  ┌──────────────┐ │
-│  │  Backend    │  │   Frontend   │ │
-│  │  FastAPI    │  │   Next.js    │ │
-│  │  :8000      │  │   :8001      │ │
-│  └─────────────┘  └──────────────┘ │
-│         │                │           │
-│         └──────┬─────────┘           │
-│              Supervisor              │
-└─────────────────────────────────────┘
-              │
-              ▼
-    ┌──────────────────┐
-    │   PostgreSQL     │
-    │   Database       │
-    └──────────────────┘
+用户浏览器
+    │
+    ▼
+Next.js 15 (:8001)  ←── Turbopack 构建
+    │ /api/* → 反向代理
+    │ /images/* → 反向代理
+    ▼
+FastAPI (:8000)
+    ├── LangGraph 工作流 (analyze → retrieve → generate)
+    ├── RAG 管线
+    │   ├── text2vec-base-chinese (嵌入)
+    │   ├── ChromaDB (向量存储)
+    │   ├── pymupdf (PDF 图片提取)
+    │   └── Qwen3-VL-8B (图片描述生成)
+    ├── LLM 路由
+    │   ├── SiliconFlow (Qwen/DeepSeek 系列)
+    │   └── DeepSeek 官方 API
+    └── SQLAlchemy ORM
+        ├── SQLite (本地开发)
+        └── PostgreSQL (Docker 部署)
 ```

-### 技术栈
+## 技术栈

-**后端**:
- FastAPI + Uvicorn
- LangChain + LangGraph
- 硅基流动API (Qwen3-30B)
- Chroma向量数据库
- PostgreSQL
+**后端**: Python 3.12 / FastAPI / LangChain / LangGraph / ChromaDB / SQLAlchemy / pymupdf

-**前端**:
- Next.js 15 (App Router)
- React 19
- TypeScript
- TailwindCSS + shadcn/ui
+**前端**: Next.js 15 / React 19 / TypeScript / TailwindCSS / shadcn/ui / Zustand

-## 📁 项目结构
+**部署**: 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
 cd backend
 uv sync
-uv run main.py
+uv run main.py          # http://localhost:8000
 ```

-2. **启动前端** (新终端):
+**前端** (终端 2):
 ```bash
 cd web
 pnpm install
-pnpm dev
+pnpm dev                # http://localhost:8001
 ```

-### 修改代码后重建镜像
+### Docker 部署

 ```bash
-# 重新构建镜像
-docker-compose build app
-
-# 重启服务
-docker-compose up -d app
+cp env.example .env     # 编辑 .env，配置 SILICONFLOW_API_KEY 等
+docker-compose up -d     # http://localhost:8001
 ```

-## 📝 环境变量说明
+## 项目结构

-主要环境变量（完整列表见 `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. **生产环境**:
-   - 修改所有默认密码和密钥
-   - 使用强密码
-   - 配置HTTPS（通过Nginx反向代理）
-   - 限制数据库访问
+| 变量 | 说明 |
+|------|------|
+| `SILICONFLOW_API_KEY` | SiliconFlow LLM/VLM API 密钥 (必需) |
+| `DATABASE_URL` | SQLite 或 PostgreSQL 连接串 |
+| `SECRET_KEY` | JWT 签名密钥 |
+| `POSTGRES_PASSWORD` | PostgreSQL 密码 (Docker) |

-2. **数据备份**:
-   - 定期备份PostgreSQL数据库
-   - 备份向量数据库和知识库文件
-
-## 📄 许可证
+## 许可证

 MIT License
-
-## 📞 技术支持
-
-如有问题或建议，请联系开发团队。
-
---
-
-**版本**: v1.0.0 (单容器版本)  
-**最后更新**: 2025年1月
-
-