# 国土空间规划课程智能体

基于大模型和 RAG 的国土空间规划课程智能问答系统，支持多模态文档理解、知识图谱、AI 绘图和论坛交流。

## 功能概览

| 模块 | 说明 |
|------|------|
| **智能问答** | RAG 检索增强生成，支持流式输出、多模型切换、思考过程展示 |
| **多模态 RAG** | PDF 图片自动提取 + VLM 描述生成，问答结果中直接展示图片 |
| **知识库管理** | 上传 PDF/DOCX/TXT/MD 文档，自动分块、向量化入库 |
| **课程内容** | 知识图谱可视化，教材章节结构浏览 |
| **AI 绘图** | 文生图（Stable Diffusion）、图生图，SiliconFlow API 驱动 |
| **论坛** | 分类讨论区，支持发帖、回复 |
| **用户系统** | JWT 认证，管理员/普通用户角色分离 |

## 技术架构

```
用户浏览器
    │
    ▼
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 部署)
```

## 技术栈

**后端**: Python 3.12 / FastAPI / LangChain / LangGraph / ChromaDB / SQLAlchemy / pymupdf

**前端**: Next.js 15 / React 19 / TypeScript / TailwindCSS / shadcn/ui / Zustand

**部署**: Docker + Supervisor (单容器) / PostgreSQL

## 快速开始

### 本地开发

**后端** (终端 1):
```bash
cd backend
uv sync
uv run main.py          # http://localhost:8000
```

**前端** (终端 2):
```bash
cd web
pnpm install
pnpm dev                # http://localhost:8001
```

### Docker 部署

```bash
cp env.example .env     # 编辑 .env，配置 SILICONFLOW_API_KEY 等
docker-compose up -d     # http://localhost:8001
```

## 项目结构

```
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
```

## 环境变量

关键变量见 `env.example`：

| 变量 | 说明 |
|------|------|
| `SILICONFLOW_API_KEY` | SiliconFlow LLM/VLM API 密钥 (必需) |
| `DATABASE_URL` | SQLite 或 PostgreSQL 连接串 |
| `SECRET_KEY` | JWT 签名密钥 |
| `POSTGRES_PASSWORD` | PostgreSQL 密码 (Docker) |

## 许可证

MIT License