AI 敘事轉譯平台 (AI Narrative Translation Platform)

一個基於 AI 的智慧教育平台，將複雜知識轉譯為易於理解的敘事、類比和知識圖譜。

🚀 功能特色

AI 智慧助教 - 24/7 智能問答，個性化學習指導
知識圖譜 - 視覺化知識結構，建立概念關聯
簡報生成 - AI 自動生成專業簡報
測驗系統 - 智能題目生成，即時評分反饋
課程管理 - 多人即時編輯，共享知識，自動分組
抽籤系統 - 動畫抽籤功能，支持批量抽取和逐個顯示
AI 管理 - 智能配置管理，性能監控
多語言支援 - 中英文雙語切換
實時統計 - 平台數據統計和監控
Toast 通知 - 全站統一的柔和通知系統

🏗️ 技術架構

後端 (Backend)

框架: FastAPI (Python)
數據庫: PostgreSQL
圖數據庫: Neo4j
容器化: Docker

前端 (Frontend)

框架: Next.js 14 (React)
語言: TypeScript
樣式: Tailwind CSS
動畫: Framer Motion
國際化: 自定義 i18n 系統
容器化: Docker

📁 項目結構

reverse_room/
├── app/                          # 後端 FastAPI 應用
│   ├── __init__.py
│   ├── main.py                   # 主應用入口
│   ├── database.py               # 數據庫配置
│   ├── schemas.py                # Pydantic 模型
│   ├── routers/                  # API 路由
│   │   ├── __init__.py
│   │   ├── sessions.py           # 課程管理
│   │   ├── translations.py       # 知識轉譯
│   │   ├── users.py              # 用戶管理
│   │   ├── tutor.py              # AI 助教
│   │   ├── knowledge_graph.py    # 知識圖譜
│   │   ├── presentations.py      # 簡報生成
│   │   ├── quizzes.py            # 測驗系統
│   │   └── ai_management.py      # AI 管理
│   └── services/                 # 業務邏輯服務
│       ├── __init__.py
│       ├── ai_service.py         # AI 服務
│       ├── agent_manager.py      # 代理管理
│       └── educational_tools.py  # 教育工具
├── frontend/                     # 前端 Next.js 應用
│   ├── src/
│   │   ├── app/                  # App Router 頁面
│   │   │   ├── page.tsx          # 首頁
│   │   │   ├── tutor/            # AI 助教
│   │   │   ├── knowledge-graph/  # 知識圖譜
│   │   │   ├── presentations/    # 簡報生成
│   │   │   ├── quizzes/          # 測驗系統
│   │   │   ├── sessions/         # 課程管理
│   │   │   └── ai-management/    # AI 管理
│   │   ├── components/           # React 組件
│   │   │   ├── ui/               # UI 組件
│   │   │   ├── layout/           # 布局組件
│   │   │   └── LanguageSwitcher.tsx # 語言切換器
│   │   ├── lib/                  # 工具庫
│   │   │   ├── i18n.ts           # 國際化配置
│   │   │   ├── api.ts            # API 客戶端
│   │   │   └── utils.ts          # 工具函數
│   │   └── types/                # TypeScript 類型定義
│   ├── Dockerfile                # 前端 Docker 配置
│   ├── package.json              # 前端依賴
│   └── next.config.js            # Next.js 配置
│   ├── test/                  # 測試腳本
│   ├── test_ai_integration.py    # AI 整合測試
│   ├── test_knowledge_graph.py   # 知識圖譜測試
│   ├── test_neo4j_integration.py # Neo4j 整合測試
│   └── test_upload_functionality.py # 上傳功能測試
├── storage/exports/                      # 導出文件
│   ├── presentations/            # 簡報導出
│   └── quizzes/                  # 測驗導出
├── ssl/                          # SSL 證書 (HTTPS)
├── docker-compose.yml            # Docker Compose 配置
├── docker-compose.dev.yml        # 開發環境配置
├── Dockerfile                    # 後端 Docker 配置
├── requirements.txt              # Python 依賴
├── start.sh                      # 生產環境啟動腳本
├── start-dev.sh                  # 開發環境啟動腳本
└── README.md                     # 項目文檔

🚀 快速開始

系統要求

Docker 20.10+
Docker Compose 2.0+
至少 4GB RAM
至少 10GB 磁盤空間

1. 克隆項目

git clone <repository-url>
cd reverse_room

2. 設置環境變數

# 複製環境變數模板
cp docker/.env.example docker/.env

# 編輯 .env 文件，設置您的 API 金鑰
nano docker/.env

重要：請設置以下 API 金鑰：

GEMINI_API_KEY: Google Gemini API 金鑰
OPENAI_API_KEY: OpenAI API 金鑰（可選）
SERP_API_KEY: SerpAPI 金鑰（可選）

3. 啟動服務

生產環境

# 給啟動腳本執行權限
chmod +x start.sh

# 啟動服務
./start.sh

開發環境

# 給開發啟動腳本執行權限
chmod +x start-dev.sh

# 啟動開發環境
./start-dev.sh

4. 訪問應用

前端應用: http://localhost:3005 (生產) 或 http://localhost:3005 (開發)
後端 API: http://localhost:8005
API 文檔: http://localhost:8005/docs

5. 默認帳號

用戶名: admin
密碼: admin123

⚠️ 重要：請立即修改默認密碼！

🎯 核心功能詳解

🔄 ID 統一說明

session_id = course_id：系統已將課程 ID 統一，session_id 即為 course_id
6位隨機代碼：課程使用 6 位英數字混合的隨機代碼作為唯一識別符
API 端點統一：所有相關 API 端點都使用 session_id 參數
數據庫設計：Session 表的主鍵 id 字段即為課程代碼

📚 課程管理系統

課程創建與管理：支持課程創建、編輯、刪除和狀態管理
課程代碼系統：6位隨機代碼作為 session_id，方便學生加入
課程密碼保護：可選的課程密碼，增強安全性
參與者管理：查看和管理課程參與者
ID 統一：session_id 即為 course_id，使用統一的課程識別碼

🎲 智能分組系統

自動分組：支持按人數或按分組數自動分配
重新分配保護：防止意外重新分配已分組的學生
分組管理：查看分組結果和學生分配情況
文件共享：分組內部和公共文件管理

🎯 抽籤系統

動畫抽籤效果：使用 Framer Motion 實現流暢動畫
批量抽取模式：一次性抽取多個參與者
逐個顯示模式：逐個顯示抽籤結果，增加懸念
結果管理：保存抽籤結果，支持重新抽籤

🧠 AI 智慧助教

24/7 智能問答：基於課程內容的智能回答
個性化學習指導：根據學生水平提供建議
多模型支援：支援 Gemini、OpenAI、Ollama 等模型
上下文理解：理解課程上下文，提供相關回答

🗺️ 知識圖譜系統

PDF 文檔處理：自動提取 PDF 內容並生成總結
智能節點生成：自動識別關鍵概念和知識點
關係建立：建立概念間的關聯關係
視覺化展示：直觀的知識圖譜界面

📊 實時統計系統

平台數據統計：活躍用戶、課程數量、知識節點、測驗題目
動態更新：實時從後端獲取最新數據
視覺化展示：美觀的卡片式統計展示

🔔 Toast 通知系統

全站統一通知：柔和的 Toast 通知樣式
多類型支援：成功、錯誤、警告、信息等類型
自動消失：可配置的自動消失時間
手動關閉：支持手動關閉通知

🔧 開發指南

環境配置

必要的環境變數

# 數據庫配置
DATABASE_URL=postgresql://postgres:postgres123@postgres:5432/ai_education

# Neo4j 配置
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# AI 模型配置
THINK_MODEL_TYPE=gemini
THINK_MODEL_NAME=gemini-flash-2.0
TARGET_MODEL_TYPE=gemini
TARGET_MODEL_NAME=gemini-flash-2.0
TOOL_MODEL_TYPE=gemini
TOOL_MODEL_NAME=gemini-flash-2.0

# API 金鑰
GEMINI_API_KEY=your_gemini_api_key
OPENAI_API_KEY=your_openai_api_key
SERP_API_KEY=your_serp_api_key

# 功能配置
SUPPORT_IMAGE=false
ENABLE_WEB_SEARCH=true
ENABLE_CACHING=true
MAX_CONTENT_LENGTH=2000
MAX_RESPONSE_TOKENS=1024

# 間隔配置
THINK_INTERVAL=6
TARGET_INTERVAL=60
TOOL_INTERVAL=15

API 端點

AI 助教功能

1. 基本問答

POST /api/v1/tutor/ask
Content-Type: application/json

{
  "document_id": 1,
  "query": "什麼是機器學習？"
}

2. AI Agent 查詢

POST /api/v1/tutor/agent/query
Content-Type: application/json

{
  "session_id": "ABC123",
  "query": "請解釋深度學習的概念",
  "context": "機器學習課程"
}

3. 生成學習路徑

POST /api/v1/tutor/agent/learning-path
Content-Type: application/json

{
  "session_id": "ABC123",
  "topic": "機器學習基礎"
}

課程管理

1. 創建課程

POST /api/v1/sessions
Content-Type: application/json

{
  "title": "機器學習入門",
  "description": "學習機器學習基礎概念",
  "password": "optional_password"
}

2. 加入課程

POST /api/v1/sessions/join
Content-Type: application/json

{
  "course_code": "ABC123",
  "password": "optional_password"
}

3. 自動分組

POST /api/v1/sessions/{session_id}/auto-assign
Content-Type: application/json

{
  "mode": "by_count",  // "by_count" 或 "by_groups"
  "value": 3,          // 每組人數或分組數
  "allow_reassign": false
}

知識圖譜

1. 創建課程知識圖譜

POST /api/v1/sessions/{session_id}/knowledge-graph/create

2. 獲取知識圖譜

GET /api/v1/sessions/{session_id}/knowledge-graph

3. 更新知識圖譜

PUT /api/v1/sessions/{session_id}/knowledge-graph/update

測試

運行測試腳本：

# 進入測試目錄
cd test

# 運行 AI 整合測試
python test_ai_integration.py

# 運行知識圖譜測試
python test_knowledge_graph.py

# 運行 Neo4j 整合測試
python test_neo4j_integration.py

# 運行上傳功能測試
python test_upload_functionality.py

🐳 Docker 部署

服務架構

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Nginx     │    │  Frontend   │    │   Backend   │
│   (80/443)  │    │   (3005)    │    │   (8005)    │
└─────────────┘    └─────────────┘    └─────────────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
         ┌─────────┐  ┌─────────┐  ┌─────────┐
         │PostgreSQL│  │  Neo4j  │  │  Files  │
         │  (5432)  │  │  (7687) │  │ (volumes)│
         └─────────┘  └─────────┘  └─────────┘

服務說明

服務	端口	描述
nginx	80/443	反向代理，負載均衡
frontend	3005	Next.js 前端應用
backend	8005	FastAPI 後端服務
postgres	5432	PostgreSQL 數據庫
neo4j	7687	Neo4j 圖數據庫

常用命令

# 查看服務狀態
docker-compose ps

# 查看日誌
docker-compose logs -f [service_name]

# 重啟服務
docker-compose restart [service_name]

# 停止所有服務
docker-compose down

# 停止並清理
docker-compose down -v

# 開發環境
docker-compose -f docker-compose.dev.yml ps
docker-compose -f docker-compose.dev.yml logs -f
docker-compose -f docker-compose.dev.yml down

數據持久化

數據存儲在以下位置：

PostgreSQL: postgres_data volume (Docker 環境)
Neo4j: neo4j_data volume
文件: ./exports 目錄
日誌: ./logs 目錄

注意: 項目使用 Docker PostgreSQL 作為主要數據庫，已清理 SQLite 文件

📁 資料夾說明

storage/exports/

用途: 存放系統導出的文件
presentations/: 存放 AI 生成的簡報文件
quizzes/: 存放生成的測驗文件
功能: 提供文件下載和分享功能

ssl/

用途: 存放 SSL 證書文件
功能: 支援 HTTPS 安全連接
配置: 在 nginx.conf 中配置 SSL 證書路徑

🔍 故障排除

常見問題

端口衝突

# 檢查端口使用
netstat -tulpn | grep :8005

# 修改 docker-compose.yml 中的端口映射

權限問題

# 修復目錄權限
sudo chown -R $USER:$USER exports logs uploads

內存不足

# 增加 Docker 內存限制
# 在 Docker Desktop 設置中調整

API 金鑰錯誤

# 檢查環境變數
docker-compose exec backend env | grep API_KEY

# 重新設置環境變數
docker-compose down
# 編輯 .env 文件
docker-compose up -d

日誌查看

# 查看所有服務日誌
docker-compose logs -f

# 查看特定服務日誌
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f postgres

# 查看錯誤日誌
docker-compose logs --tail=100 | grep ERROR

性能監控

# 查看容器資源使用
docker stats

# 查看系統資源
docker system df

# 清理未使用的資源
docker system prune -a

🔒 安全建議

修改默認密碼：立即修改 admin 用戶的默認密碼
使用 HTTPS：在生產環境中配置 SSL 證書
定期備份：定期備份數據庫和重要文件
監控日誌：定期檢查系統日誌
更新依賴：定期更新依賴包和安全補丁

📞 支援

如有問題，請檢查：

日誌文件中的錯誤信息
環境變數配置是否正確
API 金鑰是否有效
網絡連接是否正常

📄 授權

本項目採用 MIT 授權條款。

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
backend		backend
docker		docker
frontend		frontend
.DS_Store		.DS_Store
.gitignore		.gitignore
README.md		README.md
start-dev.sh		start-dev.sh
start.sh		start.sh

Folders and files

Latest commit

History

Repository files navigation

AI 敘事轉譯平台 (AI Narrative Translation Platform)

🚀 功能特色

🏗️ 技術架構

後端 (Backend)

前端 (Frontend)

📁 項目結構

🚀 快速開始

系統要求

1. 克隆項目

2. 設置環境變數

3. 啟動服務

生產環境

開發環境

4. 訪問應用

5. 默認帳號

🎯 核心功能詳解

🔄 ID 統一說明

📚 課程管理系統

🎲 智能分組系統

🎯 抽籤系統

🧠 AI 智慧助教

🗺️ 知識圖譜系統

📊 實時統計系統

🔔 Toast 通知系統

🔧 開發指南

環境配置

必要的環境變數

API 端點

AI 助教功能

1. 基本問答

2. AI Agent 查詢

3. 生成學習路徑

課程管理

1. 創建課程

2. 加入課程

3. 自動分組

知識圖譜

1. 創建課程知識圖譜

2. 獲取知識圖譜

3. 更新知識圖譜

測試

🐳 Docker 部署

服務架構

服務說明

常用命令

數據持久化

📁 資料夾說明

storage/exports/

ssl/

🔍 故障排除

常見問題

日誌查看

性能監控

🔒 安全建議

📞 支援

📄 授權

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages