# 智课灵匠_PPT Agent **Repository Path**: gz_djy/ai-agent ## Basic Information - **Project Name**: 智课灵匠_PPT Agent - **Description**: 智教AI 助手是一个面向教育领域的智能课件生成系统,基于 RAG(检索增强生成)技术构建,提供智能问答和多种格式课件的自动生成功能。 核心功能: 📚 智能问答:基于知识库的语义检索和AI回答 🎨 课件生成:一键生成PPT、Word、PDF格式的课件 📹 多模态处理:支持文档和视频的上传、处理与向量化 🤖 意图识别:7种意图自动识别,智能澄清模糊需求 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 2 - **Created**: 2026-05-29 - **Last Updated**: 2026-05-29 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 智教AI助手 ![输入图片说明](photo/3.png) 一个面向教育领域的智能课件生成系统,基于 RAG(检索增强生成)技术,支持多模态内容理解、智能决策流和课件自动生成功能。 - **智能意图识别**:基于向量相似度的混合策略,自动识别用户需求 - **多模态内容理解**:支持文档、图片、视频等多种格式的内容分析 - **智能课件生成**:自动生成 PPT、Word、PDF 和 HTML5 互动游戏 - **知识库管理**:基于 FAISS 的向量检索系统 - **用户系统**:完整的用户认证和历史记录管理 ## 项目架构 本项目采用前后端分离架构,包含三个核心模块: ``` ai-agent/ ├── frontend/ # 前端 - Vue3 用户界面 ├── rag_server/ # RAG 服务 - Python FastAPI └── springblocks/ # 后端服务 - Java Spring Boot ``` ### 架构层次 | 层次 | 模块 | 技术栈 | 职责 | |------|------|--------|------| | 前端层 | frontend/ | Vue 3 + Vite + Element Plus | 用户界面、交互逻辑、文件上传/下载 | | 服务层 | rag_server/ | Python + FastAPI + FAISS | RAG 处理、意图识别、课件生成 | | 后端层 | springblocks/ | Java + Spring Boot + MySQL | 用户认证、数据管理、后台管理 | | 外部服务 | DeepSeek API | - | AI 模型推理 | ### 核心数据流 ``` 用户 → 前端 → RAG服务 → 知识库(FAISS) ↓ DeepSeek API ↓ 生成回答/课件 ↓ 前端 ← 结果展示/下载 ← RAG服务 ↓ Java后端 ← 保存历史记录 ``` ## 核心功能 ### 1. 智能意图识别(基于向量相似度) - **多意图识别**:自动识别聊天、生成PPT/Word/游戏、搜索、上传文档等8种意图 - **混合判断策略**: - 直接关键词匹配(ppt/word/游戏等明确词汇) - 向量相似度匹配(Sentence-BERT 计算与示例的相似度) - AI 分类器兜底(DeepSeek API 辅助判断) - **智能澄清**:当需求不明确时,AI主动询问以澄清意图 - **参数提取**:自动提取页数、主题、风格等参数 - **模板智能选择**:根据主题关键词自动选择PPT/Word模板 ### 2. 智能决策流 - **知识库优先**:有相关资料时,必须基于资料回答或生成 - **无资料降级**:知识库未检索到相关内容时,自动调用 DeepSeek 通用能力回答 - **模糊指令追问**:用户指令不清晰时,AI 主动反问确认主题 - **语义相似度过滤**:基于余弦相似度阈值(默认 0.6)判断检索结果相关性 ### 3. 多模态课件生成 - **PPT生成**(.pptx):支持5种模板(cartoon/tech/simple/chinese/gov),动态版式探测 - **Word文档**(.docx):支持5种模板(formal/academic/business/technical/simple) - **HTML5游戏**(.html):互动问答游戏,支持即时反馈和得分统计 - **PDF生成**:带 CSS 模板样式的PDF文档 - **文件管理**:30分钟自动清理过期文件 ### 4. 智能问答(RAG) - 基于 FAISS 向量检索 - 支持文档/视频多模态内容 - DeepSeek API + Qwen 多模态模型生成回答 - 意图分析和教学大纲生成 ### 5. 视频处理 - 视频上传和异步处理 - 语音转文字(OpenAI Whisper) - 视频内容向量化入库 ### 6. 用户系统 - JWT 身份认证(Access Token + Refresh Token) - 用户管理、历史记录、收藏功能 - 管理员后台(用户管理、知识库管理、问答审核) ## 技术栈 | 模块 | 技术 | |-----|------| | 前端 | Vue 3 + Vite + Element Plus + Pinia | | RAG 服务 | Python 3.10+ + FastAPI + FAISS | | 后端服务 | Java 17 + Spring Boot 3.x + MySQL 8.0 | | AI 模型 | DeepSeek API + Qwen 多模态 | | 向量数据库 | FAISS (IndexFlatIP) | | Embedding | Sentence-BERT (all-MiniLM-L6-v2) | | 语音识别 | OpenAI Whisper | | 文档生成 | python-pptx + python-docx + Playwright | | 游戏生成 | HTML5 + CSS3 + JavaScript | ## 快速开始 ### 1. 环境准备 确保已安装: - Node.js 16+ - Python 3.10+ - Java 17+ - MySQL 8.0+ - FFmpeg(视频处理必需) ### 2. 配置 API 密钥 创建 `rag_server/.env` 文件: ```bash DEEPSEEK_API_KEY=your_deepseek_api_key DEEPSEEK_BASE_URL=https://api.deepseek.com/v1 # 可选:Qwen 多模态模型(用于图片理解) QWEN_API_KEY=your_qwen_api_key QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 ``` ### 3. 启动 RAG 服务 (Python 后端) ```bash cd rag_server pip install -r requirements.txt # 方式1:直接运行 python main.py # 方式2:使用 uvicorn(推荐) uvicorn main:app --host 0.0.0.0 --port 8000 --reload ``` 服务将在 `http://localhost:8000` 运行 ### 4. 启动 Java 后端服务 ```bash cd springblocks # 使用 Maven Wrapper ./mvnw spring-boot:run # 或直接使用 Maven mvn clean install mvn spring-boot:run ``` 服务将在 `http://localhost:8080` 运行 **注意**: 如果遇到依赖问题,已在 `pom.xml` 中配置阿里云镜像和 Spring 里程碑仓库。 ### 5. 启动前端 ```bash cd frontend npm install npm run dev ``` 访问 `http://localhost:5173` ## API 接口 ### RAG 服务接口 (Python) | 接口 | 方法 | 说明 | |-----|------|------| | `/api/v1/chat` | POST | 智能问答/课件生成(核心接口) | | `/api/v1/upload` | POST | 文档上传(PDF/Word/TXT/PPT) | | `/api/v1/download/{file_id}` | GET | 文件下载 | | `/api/v1/voice/transcribe` | POST | 语音转文字 | | `/api/v1/video/submit` | POST | 视频提交处理 | | `/api/v1/video/status/{task_id}` | GET | 查询视频处理状态 | ### Java 后端接口 | 接口 | 方法 | 说明 | |-----|------|------| | `/api/auth/**` | - | 用户认证(登录/注册/刷新Token) | | `/api/user/**` | - | 用户管理 | | `/api/history/**` | - | 历史记录 | | `/api/admin/**` | - | 管理员功能 | | `/rag/**` | - | RAG服务代理(转发到Python后端) | ### /chat 接口响应模式 根据智能决策流,接口会返回四种模式: #### 1. 意图澄清模式(clarification) 当意图识别置信度低或需要确认时返回: ```json { "success": true, "mode": "clarification", "message": "您好!我可以帮您制作PPT演示文稿或Word文档...", "intent": {"type": "clarification", "topic": "..."}, "confidence": 0.38, "parameters": { "page_count": 10, "topic": "...", "style": "tech" } } ``` #### 2. 追问模式(ask) 用户指令模糊时返回: ```json { "success": true, "mode": "ask", "message": "请问您想做什么主题的PPT?", "reasoning": "用户未指定具体主题" } ``` #### 3. 纯文本回答模式(chat) 问答意图或无知识库时返回: ```json { "success": true, "mode": "chat", "message": "资料库中未找到相关内容,根据通用知识回答:...", "sources": [], "note": "基于通用知识回答" } ``` #### 4. 课件生成模式(generate) 生成意图且有知识库时返回: ```json { "success": true, "mode": "generate", "message": "课件生成成功,请点击下载", "intent": {"type": "generate", "topic": "...", "format": "ppt"}, "outline": {...}, "sources": [...], "download_info": { "file_id": "abc123...", "filename": "课件_主题名称.pptx", "file_type": "ppt", "download_url": "/api/v1/download/abc123...", "expires_in": 1800, "expires_at": "2026-04-01T12:00:00" } } ``` ### 请求示例 **生成PPT课件:** ```bash curl -X POST http://localhost:8000/api/v1/chat \ -H "Content-Type: application/json" \ -d '{ "question": "请生成水稻种植技术PPT,10页", "output_format": "ppt" }' ``` **生成Word文档:** ```bash curl -X POST http://localhost:8000/api/v1/chat \ -H "Content-Type: application/json" \ -d '{ "question": "请生成一份关于人工智能的学术报告", "output_format": "word" }' ``` **生成HTML5游戏:** ```bash curl -X POST http://localhost:8000/api/v1/chat \ -H "Content-Type: application/json" \ -d '{ "question": "生成一个小学数学问答游戏", "output_format": "game" }' ``` **上传文档:** ```bash curl -X POST http://localhost:8000/api/v1/upload \ -F "file=@document.pdf" ``` ## 项目结构 ### RAG 服务 (rag_server/) ``` rag_server/ ├── api/ │ └── routes.py # API 路由定义 ├── config/ │ ├── settings.py # 应用配置(Pydantic Settings) │ └── loader.py # 配置加载器 ├── modules/ │ ├── intent/ # 意图识别模块 │ │ ├── __init__.py │ │ └── vector_recognizer.py # 混合意图识别器(向量+AI) │ ├── pipeline/ │ │ └── rag_pipeline.py # RAG 流程编排 │ ├── generation/ │ │ ├── deepseek_generator.py # DeepSeek API 生成器 │ │ ├── prompts/ # 提示词管理 │ │ │ ├── all_prompts.py │ │ │ ├── game_prompts.py │ │ │ └── word_prompts.py │ │ └── base.py │ ├── knowledge/ │ │ └── faiss_knowledge.py # FAISS 知识库实现 │ ├── embedding/ │ │ ├── sentence_transformer.py # Sentence-BERT 嵌入 │ │ └── base.py │ ├── vectorstore/ │ │ └── faiss_store.py # FAISS 向量存储 │ ├── ingestion/ │ │ ├── document_loader.py # 文档加载 │ │ ├── text_chunker.py # 文本切分 │ │ └── multimodal_extractor.py # 多模态提取(OCR/语音) │ ├── builders/ │ │ ├── ppt_builder.py # PPT 构建器 │ │ └── game_builder.py # HTML5 游戏构建器 │ └── video/ │ └── whisper_processor.py # Whisper 语音处理 ├── services/ │ ├── builders.py # PPT/Word/PDF 构建器服务 │ ├── video_service.py # 视频处理服务 │ └── knowledge_service.py # 知识库服务 ├── templates/ # PPT 模板文件 │ ├── cartoon.pptx # 卡通模板(幼儿教育) │ ├── simple.pptx # 简约模板 │ ├── tech.pptx # 科技感模板 │ ├── chinese.pptx # 中国风模板 │ ├── gov.pptx # 党政模板 │ └── word_templates/ # Word 模板目录 │ ├── formal.docx │ ├── academic.docx │ ├── business.docx │ ├── technical.docx │ └── simple.docx ├── downloads/ # 生成的课件文件 ├── data/ │ ├── uploads/ # 上传的文档 │ ├── faiss/ # FAISS 索引文件 │ └── tasks/ # 视频处理任务 ├── main.py # FastAPI 应用入口 └── requirements.txt # Python 依赖 ``` ### 前端 (frontend/) ``` frontend/ ├── src/ │ ├── api/ # API 接口封装 │ │ ├── pptAgentApi.js │ │ ├── file.js │ │ └── ... │ ├── components/ # Vue 组件 │ │ ├── chat/ # 聊天组件 │ │ │ ├── ChatBubble.vue │ │ │ ├── InputArea.vue │ │ │ └── game/ # 游戏组件 │ │ └── common/ # 通用组件 │ ├── views/ # 页面视图 │ │ ├── chat.vue # 主聊天页面 │ │ ├── AdminDashboard.vue │ │ └── ... │ ├── router/ # Vue Router 配置 │ ├── stores/ # Pinia 状态管理 │ └── utils/ # 工具函数 ├── package.json └── vite.config.js ``` ### 后端 (springblocks/) ``` springblocks/ ├── src/main/java/com/tiqs/springblocks/ │ ├── controller/ # REST API 控制器 │ │ ├── UserController.java │ │ ├── RagProxyController.java # RAG 服务代理 │ │ └── Admin*.java # 管理员控制器 │ ├── service/ # 业务逻辑层 │ ├── entity/ # 实体类 │ ├── security/ # JWT 认证 │ │ ├── JwtTokenProvider.java │ │ └── JwtAuthenticationFilter.java │ ├── config/ # 配置类 │ └── aspect/ # AOP 日志 └── pom.xml ``` ## 关键类与函数 ### 意图识别模块 | 类/函数名 | 说明 | 文件位置 | |-----------|------|----------| | `HybridIntentRecognizer` | 混合意图识别器 | `modules/intent/vector_recognizer.py` | | `HybridIntentRecognizer.recognize()` | 识别用户意图 | `modules/intent/vector_recognizer.py` | | `VectorIntentMatcher` | 向量相似度匹配器 | `modules/intent/vector_recognizer.py` | | `AIIntentClassifier` | AI 意图分类器 | `modules/intent/vector_recognizer.py` | | `HybridIntentRecognizer.select_template()` | 智能选择PPT模板 | `modules/intent/vector_recognizer.py` | ### RAG 流程模块 | 类/函数名 | 说明 | 文件位置 | |-----------|------|----------| | `RAGPipeline` | RAG 流程编排 | `modules/pipeline/rag_pipeline.py` | | `RAGPipeline.process()` | 处理用户请求 | `modules/pipeline/rag_pipeline.py` | | `RAGPipeline.retrieve()` | 检索相关内容 | `modules/pipeline/rag_pipeline.py` | ### 构建器模块 | 类/函数名 | 说明 | 文件位置 | |-----------|------|----------| | `PPTBuilder` | PPT 文档构建器 | `services/builders.py` | | `PPTBuilder.build()` | 构建 PPT 文件 | `services/builders.py` | | `DocxBuilder` | Word 文档构建器 | `services/builders.py` | | `GameBuilder` | HTML5 游戏构建器 | `modules/builders/game_builder.py` | ### 用户认证模块 | 类/函数名 | 说明 | 文件位置 | |-----------|------|----------| | `JwtTokenProvider` | JWT 令牌提供者 | `springblocks/security/JwtTokenProvider.java` | | `JwtTokenProvider.generateAccessToken()` | 生成访问令牌 | `springblocks/security/JwtTokenProvider.java` | | `JwtTokenProvider.validateToken()` | 验证令牌 | `springblocks/security/JwtTokenProvider.java` | ### 前端核心组件 | 组件名 | 说明 | 文件位置 | |--------|------|----------| | `chat.vue` | 主聊天界面 | `frontend/src/views/chat.vue` | | `ChatBubble.vue` | 聊天消息气泡 | `frontend/src/components/chat/ChatBubble.vue` | | `InputArea.vue` | 输入区域 | `frontend/src/components/chat/InputArea.vue` | | `CoursewarePreview.vue` | 课件预览 | `frontend/src/components/chat/CoursewarePreview.vue` | ## 配置说明 ### RAG 服务配置 (config/settings.py) ```python # DeepSeek API 配置 DEEPSEEK_API_KEY=your_api_key DEEPSEEK_BASE_URL=https://api.deepseek.com/v1 DEEPSEEK_MODEL=deepseek-v4-flash # Qwen 多模态配置(可选) QWEN_API_KEY=your_qwen_api_key QWEN_MODEL=qwen3.6-plus # 路径配置 UPLOAD_DIR=data/uploads FAISS_DIR=data/faiss DOWNLOADS_DIR=downloads # 处理配置 CHUNK_SIZE=500 # 文本切分大小 CHUNK_OVERLAP=50 # 切分重叠 SIMILARITY_THRESHOLD=0.6 # 相似度阈值 # 服务配置 HOST=0.0.0.0 PORT=8000 ``` ### 环境变量 (.env) ```bash # 必需 DEEPSEEK_API_KEY=your_deepseek_api_key # 可选 DEEPSEEK_BASE_URL=https://api.deepseek.com/v1 QWEN_API_KEY=your_qwen_api_key ``` ### 配置文件 - **RAG 服务配置**:`rag_server/config/settings.py` - **前端配置**:`frontend/.env` - **Java 后端配置**:`springblocks/src/main/resources/application.properties` ## 意图识别模块详解 ### 架构设计 ``` 用户输入 ↓ [直接关键词匹配] → 包含 "ppt"/"word"/"游戏"? → 直接返回对应意图 ↓ [向量相似度匹配] → Sentence-BERT 编码 → 计算与示例的相似度 ↓ [关键词增强] → 融合关键词匹配分数 → 综合评分 ↓ [决策判断] ├─ 置信度 >= 0.65 → 直接返回结果 ├─ 置信度 >= 0.35 → 结合 AI 分类器确认 └─ 置信度 < 0.35 → 调用 AI 分类器判断 ↓ [结果输出] → 意图类型 + 置信度 + 提取参数 ``` ### 支持的意图类型 | 意图类型 | 说明 | 触发关键词/示例 | |---------|------|----------------| | `CHAT` | 普通聊天 | "你好"、"谢谢"、"什么是..." | | `GENERATE_PPT` | 生成PPT | "ppt"、"幻灯片"、"演示文稿"、"课件" | | `GENERATE_WORD` | 生成Word | "word"、"doc"、"文档"、"报告"、"教案" | | `GENERATE_GAME` | 生成游戏 | "游戏"、"game"、"互动"、"答题"、"竞赛" | | `UPLOAD_DOCUMENT` | 上传文档 | "上传"、"导入"、"添加文件" | | `SEARCH` | 搜索知识库 | "搜索"、"查找"、"查询"、"检索" | | `CLARIFICATION` | 需要澄清 | 置信度低时触发 | ### 识别策略 1. **直接关键词匹配**:当用户输入包含明确的类型指示词时,直接返回对应意图 2. **向量相似度匹配**:使用 Sentence-BERT 模型计算用户输入与意图示例的相似度 3. **AI 分类器兜底**:当本地匹配置信度较低时,调用 DeepSeek API 进行判断 ### 置信度阈值 | 阈值 | 值 | 说明 | |-----|---|------| | 高置信度 | 0.65 | 直接返回结果,无需 AI 确认 | | 低置信度 | 0.35 | 需要调用 AI 分类器确认 | | 澄清阈值 | 0.25 | 低于此值触发澄清询问 | ## 课件生成详解 ### PPT 生成 - **智能模板选择**:根据主题自动选择合适的模板(cartoon/tech/simple/chinese/gov) - **动态版式探测**:自动识别模板中的所有版式并智能分配 - **智能版式推断**:根据内容特征选择合适的版式 - **字体统一**:所有文字自动设置为黑体 ### Word 生成 - **智能模板选择**:根据内容自动选择合适的模板(formal/academic/business/technical/simple) - **数据格式兼容**:支持多种内容格式 - **专业排版**:自动设置标题、段落、列表等格式 ### HTML5 游戏生成 - **互动问答游戏**:基于内容自动生成选择题 - **即时反馈**:答题后立即显示正确/错误 - **得分统计**:显示总分和正确率 - **响应式设计**:支持电脑、平板、手机 ![输入图片说明](photo/2.png) ## 模板系统 ### PPT 模板 | 模板 | 文件名 | 适用场景 | 关键词 | |-----|--------|---------|--------| | cartoon | cartoon.pptx | 幼儿教育 | 幼儿园、小学、儿童、卡通 | | tech | tech.pptx | 科技主题 | AI、人工智能、大数据、编程 | | simple | simple.pptx | 简约通用 | 默认模板 | | chinese | chinese.pptx | 中国风 | 国学、传统文化、诗词 | | gov | gov.pptx | 党政报告 | 党建、党课、政府、政策 | ### Word 模板 | 模板 | 文件名 | 适用场景 | 关键词 | |-----|--------|---------|--------| | formal | formal.docx | 正式报告 | 正式、报告、公文、官方 | | academic | academic.docx | 学术论文 | 学术、论文、研究、教案 | | business | business.docx | 商业文档 | 商业、企业、市场、战略 | | technical | technical.docx | 技术文档 | 技术、开发、编程、代码 | | simple | simple.docx | 简约通用 | 默认模板 | ## 智能决策流 ### 决策流程 1. **阶段1: 检索**:FAISS 检索相关内容 2. **相似度过滤**:基于余弦相似度阈值(默认 0.6)判断检索结果相关性 3. **阶段2: 决策**:分析用户指令是否模糊 4. **阶段3: 执行**: - 无知识库:降级到通用回答(chat 模式) - 问答意图:基于知识库回答(chat 模式) - 生成意图:基于知识库生成课件(generate 模式) ### 响应模式 | 模式 | 说明 | 应用场景 | |------|------|----------| | `clarification` | 意图澄清 | 意图识别置信度低或需要确认 | | `ask` | 追问模式 | 用户指令模糊时 | | `chat` | 纯文本回答 | 问答意图或无知识库时 | | `generate` | 课件生成 | 生成意图且有知识库时 | ## 目录结构 | 目录 | 用途 | |------|------| | `data/uploads/` | 上传的文档和视频 | | `data/faiss/` | FAISS 索引文件 | | `downloads/` | 生成的课件文件(30分钟过期) | | `templates/` | PPT 和 Word 模板 | ![输入图片说明](photo/1.png) ## 常见问题排查 ### 1. Python 依赖安装失败 ```bash # 使用国内镜像 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple ``` ### 2. Maven 依赖下载失败 - 已在 `pom.xml` 中配置阿里云镜像 - 尝试删除 `~/.m2/repository` 后重新构建 - 使用 `mvn clean install -U` 强制更新 ### 3. 端口被占用 ```bash # 查找占用 8000 端口的进程 netstat -ano | findstr :8000 # 结束进程 taskkill /PID /F ``` ### 4. FAISS 索引加载失败 - 检查 `data/faiss/` 目录是否存在 - 重新上传文档建立索引 - 检查 embedding 模型是否正确加载 ### 5. FFmpeg 未找到 - 确保 FFmpeg 已安装并添加到 PATH - 或在代码中指定 FFmpeg 路径 ### 6. JWT 测试编译失败 **问题**:`找不到符号: 方法 generateToken(java.lang.String)` **解决**:测试代码已更新,使用 `generateAccessToken()` 替代 `generateToken()` ## 注意事项 - **API 密钥**:请妥善保管 DeepSeek API 密钥,不要提交到代码仓库 - **文件存储**:上传的文档和视频存储在 `rag_server/data/` 目录 - **向量索引**:FAISS 索引文件在 `rag_server/data/faiss/`,删除后需重新上传文档 - **临时文件**:生成的课件文件 30 分钟后自动清理 - **FFmpeg**:视频处理需要 FFmpeg,请确保已安装并配置路径 ## 开发计划 - [x] RAG 智能问答 - [x] PPT/Word/PDF 课件生成 - [x] 视频处理和语音转写 - [x] 用户系统和历史记录 - [x] 意图识别模块(基于向量相似度、7种意图类型) - [x] 混合意图识别策略(本地向量+AI分类器) - [x] 智能决策流(知识库优先、无资料降级、模糊指令追问) - [x] 意图路由机制(chat/generate 分类) - [x] 语义相似度阈值过滤 - [x] PPT 构建器 v2(动态版式探测、智能版式推断) - [x] PPT 智能模板选择(5种模板自动匹配) - [x] Word 智能模板选择(5种模板自动匹配) - [x] HTML5 游戏生成 - [x] 黑体字体统一 - [ ] 多轮对话优化 - [ ] 知识库管理后台增强 - [ ] 图片/图表自动插入 - [ ] 动画效果支持 - [ ] 实时协作编辑 ## 许可证 MIT License