From 1a3730c33cdfc2100014e0a62a00d4e1466069bd Mon Sep 17 00:00:00 2001 From: xiaopeng <1509442308@qq.com> Date: Fri, 29 May 2026 21:20:57 +0800 Subject: [PATCH] docs: rewrite README to reflect current architecture and features Co-Authored-By: Claude Opus 4.7 --- README.md | 340 ++++++++++++++---------------------------------------- 1 file changed, 85 insertions(+), 255 deletions(-) diff --git a/README.md b/README.md index 92f59de..358b0bf 100644 --- a/README.md +++ b/README.md @@ -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月 - -