# PPT Text Extractor

**Repository Path**: fbb_cn/ppt-text-extractor

## Basic Information

- **Project Name**: PPT Text Extractor
- **Description**: 通过Vibe Coding实现的一个简单的ppt文本提取器，包括后端服务与前端站点，可以将ppt/pptx文件中的文本和部分图片中的文本按页提取出来。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-03-16
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PPT转Markdown智能体应用

一个完整的AI智能体应用，实现用户上传PPT → 智能体提取全部文本（含图片文字） → 生成规整Markdown文件的全流程自动化。

## 项目概述

本项目基于 **agno-agent-builder** 框架构建智能体核心，提供用户友好的Web界面，支持PPT/PPTX文件上传、AI智能体处理、实时进度跟踪和结果下载功能。

### 核心特性

- **智能文本提取**: 自动提取PPT中的所有文本内容
- **OCR图像识别**: 识别图片中的文字（支持Tesseract/PaddleOCR）
- **内容结构化**: 智能分析内容层级和结构关系
- **Markdown生成**: 生成规整的Markdown格式文档
- **实时进度跟踪**: 可视化处理进度和状态
- **Web界面**: 现代化Vue 3前端界面
- **RESTful API**: 完整的后端API服务

## 系统架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Vue 3前端     │ ←→ │ FastAPI后端     │ ←→ │ 处理引擎        │
│   - 文件上传    │    │ - API网关       │    │                 │
│   - 进度展示    │    │ - 任务管理      │    ├─────────────────┤
│   - 结果下载    │    │ - 文件存储      │    │ 规则引擎（默认） │
└─────────────────┘    └─────────────────┘    │ - PPT解析       │
                 ↑                            │ - OCR处理       │
                 │                            │ - 内容组织      │
                 └────────────────────────────┤ - Markdown生成  │
                                              ├─────────────────┤
                                              │ 智能体（可选）   │
                                              │ - AI增强处理    │
                                              └─────────────────┘
```

**双引擎架构：**
1. **规则引擎（默认）**：基于规则处理，不依赖AI模型，功能完整
2. **智能体（可选）**：基于AI模型处理，需配置API密钥

## 技术栈

### 前端
- **Vue 3** - 渐进式JavaScript框架
- **Element Plus** - UI组件库
- **Vite** - 下一代前端构建工具
- **Axios** - HTTP客户端
- **Vue Router** - 路由管理

### 后端
- **FastAPI** - 现代Python Web框架
- **SQLAlchemy** - Python SQL工具包
- **Uvicorn** - ASGI服务器
- **Python-pptx** - PPT文件处理库

### 处理引擎
#### 规则引擎（默认）
- **Python-pptx** - PPT文件解析库
- **Tesseract OCR** - 开源OCR引擎，图片文字识别
- **自定义规则系统** - 内容提取和结构化逻辑

#### 智能体（可选）
- **agno-agent-builder** - AI智能体开发框架
- **多模型支持** - DeepSeek、MiniMax等
- **PaddleOCR** - 可选OCR引擎（中文优化）

### 数据库
- **SQLite** - 轻量级数据库（开发环境）
- **PostgreSQL** - 可选生产数据库

## 快速开始

### 环境要求

- Python 3.8+
- Node.js 16+
- Tesseract OCR (安装指南见下文)

### 1. 克隆项目

```bash
git clone <repository-url>
cd demo03
```

### 2. 安装Tesseract OCR

#### Windows
1. 下载安装Tesseract: https://github.com/UB-Mannheim/tesseract/wiki
2. 默认安装路径：`C:\Program Files\Tesseract-OCR\`
3. 安装时选择"Add to PATH"或将安装目录添加到系统PATH

#### Linux (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install tesseract-ocr tesseract-ocr-chi-sim
```

#### macOS
```bash
brew install tesseract tesseract-lang
```

### 3. 安装后端依赖

```bash
# 进入后端目录
cd backend

# 创建虚拟环境（推荐）
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 返回项目根目录
cd ..
```

### 4. 安装前端依赖

```bash
# 进入前端目录
cd frontend

# 安装Node.js依赖
npm install

# 返回项目根目录
cd ..
```

### 5. 配置环境变量

```bash
# 进入后端目录
cd backend

# 复制环境配置示例文件
copy .env.local.example .env

# 编辑 .env 文件，配置必要的参数
# 详细配置说明见下文"配置说明"章节
```

**重要说明：**
- 本项目默认使用**规则引擎**处理PPT，**无需配置API密钥**即可正常运行
- 如需使用AI智能体增强功能（可选），需要配置相应的API密钥
- 数据库文件会在首次启动后端时自动创建（`ppt_converter.db`）

### 6. 启动后端服务

```bash
# 进入后端目录
cd backend

# 确保虚拟环境已激活
# Windows: venv\Scripts\activate
# Linux/macOS: source venv/bin/activate

# 启动FastAPI服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

**后端启动后访问：**
- 应用主页：http://localhost:8000
- API文档：http://localhost:8000/docs
- 健康检查：http://localhost:8000/health

### 7. 启动前端服务（新终端）

```bash
# 进入前端目录
cd frontend

# 启动Vite开发服务器
npm run dev
```

**前端启动后访问：** http://localhost:5173

### 8. 测试验证

启动服务后，访问以下地址验证系统是否正常运行：

1. **后端健康检查**：http://localhost:8000/api/system/health
2. **前端界面**：http://localhost:5173
3. **API文档**：http://localhost:8000/docs

**详细操作指南请参考：** [LOCAL_RUN_GUIDE.md](LOCAL_RUN_GUIDE.md)

## 项目结构

```
demo03/
├── frontend/                 # Vue前端应用
│   ├── src/
│   │   ├── components/      # Vue组件
│   │   ├── views/          # 页面视图
│   │   ├── services/       # API服务
│   │   └── router/         # 路由配置
│   ├── public/             # 静态资源
│   └── package.json        # 依赖配置
├── backend/                 # FastAPI后端服务
│   ├── app/
│   │   ├── api/            # API端点
│   │   ├── core/           # 核心配置
│   │   ├── models/         # 数据模型
│   │   ├── services/       # 业务服务
│   │   └── utils/          # 工具函数
│   ├── uploads/            # 上传文件存储
│   ├── results/            # 生成结果存储
│   └── requirements.txt    # Python依赖
└── agent/                   # 处理引擎模块
    ├── skills/             # 技能函数（规则引擎和智能体共用）
    ├── core/               # 核心引擎
    │   └── rule_engine.py  # 规则引擎（默认处理引擎）
    ├── workflows/          # 工作流定义
    ├── agents/             # 智能体定义（可选）
    └── config/             # 配置管理
```

## API文档

后端启动后，访问以下地址查看API文档：

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

主要API端点：

- `POST /upload` - 上传PPT文件
- `GET /tasks/{task_id}` - 获取任务状态
- `GET /results/{task_id}/download` - 下载转换结果
- `GET /system/health` - 系统健康检查

## 配置说明

### 环境配置（重要）

首次运行前，需要配置环境变量文件：

```bash
# 1. 复制配置示例文件
cp backend/.env.local.example backend/.env
```

**无需API密钥即可运行：**
- 默认使用**规则引擎**处理PPT，功能完整
- 只需安装Tesseract OCR（见安装步骤）
- 无需配置任何AI模型API密钥

**可选：配置AI智能体（需要API密钥）：**
如需使用AI增强处理，需要配置以下API密钥：

```env
# AI模型配置（可选）
MODEL_PROVIDER=minimax  # 或 deepseek
MODEL_NAME=abab5.5-chat  # 或 deepseek-chat
MINIMAX_API_KEY=your_api_key_here
# 或
DEEPSEEK_API_KEY=your_api_key_here
```

### 后端配置 (backend/.env)

```env
# 应用配置
APP_NAME=PPT转Markdown应用
DEBUG=true
HOST=0.0.0.0
PORT=8000

# 文件配置
UPLOAD_DIR=./uploads
RESULT_DIR=./results
MAX_FILE_SIZE=52428800  # 50MB
ALLOWED_EXTENSIONS=.ppt,.pptx

# 数据库配置（SQLite会自动创建）
DATABASE_URL=sqlite:///./ppt_converter.db
# 注意：数据库文件会在首次启动后端时自动创建

# 规则引擎配置（默认）
OCR_LANGUAGE=chi_sim+eng  # OCR语言：中文+英文
INCLUDE_TOC=true          # 是否生成目录

# 智能体配置（可选，如使用智能体需配置API密钥）
# AGENT_CONFIG=default
# MODEL_PROVIDER=deepseek  # 或 minimax
# MODEL_NAME=deepseek-chat  # 或 abab5.5-chat
# DEEPSEEK_API_KEY=your_api_key_here
# MINIMAX_API_KEY=your_api_key_here
```

### 前端配置 (frontend/vite.config.js)

```javascript
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8000',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, '')
    }
  }
}
```

## 使用指南

### 1. 上传PPT文件

1. 打开Web界面 (http://localhost:5173)
2. 点击上传区域或拖拽PPT文件
3. 选择PPT或PPTX文件（最大50MB）
4. 点击"开始上传并处理"

### 2. 查看处理进度

- 实时显示处理进度百分比
- 查看当前处理步骤（PPT解析、OCR处理等）
- 显示预计剩余时间
- 支持取消处理任务

### 3. 下载结果

处理完成后可以：
- 下载Markdown文件
- 预览Markdown内容
- 查看统计信息（幻灯片数、字数等）
- 下载JSON格式的元数据

## 开发指南

### 添加新的处理技能

1. 在 `agent/skills/` 目录创建新的Python文件
2. 使用 `@tool` 装饰器定义技能函数
3. 在 `agent/core/rule_engine.py` 中集成新技能（规则引擎）
4. 或在工作流 `agent/workflows/ppt_processing.py` 中集成（智能体）
5. 测试技能功能

### 扩展API功能

1. 在 `backend/app/api/` 目录创建新的API模块
2. 定义路由和处理函数
3. 在 `backend/app/main.py` 中注册路由
4. 更新API文档

### 自定义前端样式

1. 修改 `frontend/src/App.vue` 中的全局样式
2. 使用Element Plus的主题定制功能
3. 添加新的Vue组件到 `frontend/src/components/`

## 故障排除

### 常见问题

1. **OCR不可用**
   - 检查Tesseract是否安装：`tesseract --version`
   - 确认安装路径正确（Windows：`C:\Program Files\Tesseract-OCR\tesseract.exe`）
   - 访问健康检查确认OCR状态：http://localhost:8000/api/system/health

2. **OCR识别率低**
   - 确保安装正确语言包
   - 调整OCR参数（对比度、分辨率）
   - 考虑使用PaddleOCR替代

2. **文件上传失败**
   - 检查文件大小限制
   - 验证文件格式
   - 检查网络连接

4. **处理引擎超时**
   - 调整任务超时设置
   - 优化PPT文件（减少图片数量）
   - 增加系统资源
   - 检查规则引擎状态：访问 http://localhost:8000/api/system/health

5. **数据库连接错误**
   - 检查数据库URL配置
   - 确保数据库文件可写
   - 重启后端服务

### 日志查看

- 后端日志: `backend/logs/app.log`
- 规则引擎日志: 后端日志中查看
- 前端控制台: 浏览器开发者工具
- 系统状态: 访问 http://localhost:8000/api/system/health 查看详细状态

## 性能优化

### 对于大文件
- 启用分块上传
- 增加超时时间
- 优化内存使用

### 提高OCR准确率
- 预处理图片（调整对比度、去噪）
- 使用更高精度的OCR引擎
- 添加后处理校正

### 并发处理
- 配置Celery任务队列
- 使用Redis作为消息代理
- 部署多个工作进程

## 部署指南

### Docker部署

```bash
# 构建并启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f
```

### 生产环境建议

1. 使用PostgreSQL代替SQLite
2. 配置Nginx反向代理
3. 启用HTTPS
4. 设置定期备份
5. 监控系统资源

## 贡献指南

欢迎提交Issue和Pull Request！

1. Fork项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建Pull Request

## 许可证

MIT License

## 联系方式

如有问题或建议，请通过以下方式联系：

- 提交GitHub Issue
- 发送电子邮件

## 更新日志

### v0.1.0 (2024-03-10)
- 初始版本发布
- 实现基本PPT转Markdown功能
- 提供Web界面
- 集成agno智能体框架