296 lines
6.3 KiB
Markdown
296 lines
6.3 KiB
Markdown
# Video Summary - 视频分析与总结系统
|
||
|
||
基于 Python Flask 和阿里云 DashScope API 的视频内容分析与总结系统。
|
||
|
||
|
||
|
||
## 功能特性
|
||
|
||
- 📹 **视频上传**: 支持多种视频格式上传（mp4, avi, mov, mkv, wmv, flv, webm）
|
||
- 🔍 **视频分析**: 使用阿里云 DashScope 多模态 API 分析视频内容
|
||
- 📝 **自动总结**: 自动生成视频内容摘要
|
||
- 🔄 **视频对比**: 支持多个视频之间的内容对比分析
|
||
- 🎨 **现代化前端**: 简洁美观的静态前端界面
|
||
|
||
## 技术栈
|
||
|
||
- **后端**: Python Flask
|
||
- **数据库**: MongoDB
|
||
- **AI 服务**: 阿里云 DashScope (qwen3-vl-plus)
|
||
- **前端**: HTML/CSS/JavaScript (静态页面)
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
videoSummary/
|
||
├── app/
|
||
│ ├── __init__.py # Flask 应用初始化
|
||
│ ├── config.py # 配置管理
|
||
│ ├── routes/ # API 路由
|
||
│ │ └── video_routes.py
|
||
│ ├── services/ # 业务逻辑服务
|
||
│ │ ├── video_service.py
|
||
│ │ ├── dashscope_service.py
|
||
│ │ └── analysis_service.py
|
||
│ ├── models/ # 数据模型
|
||
│ │ ├── video.py
|
||
│ │ ├── analysis.py
|
||
│ │ └── comparison.py
|
||
│ └── utils/ # 工具函数
|
||
│ ├── logger.py
|
||
│ ├── validators.py
|
||
│ └── file_utils.py
|
||
├── static/ # 静态前端文件
|
||
│ ├── index.html
|
||
│ ├── style.css
|
||
│ └── app.js
|
||
├── uploads/ # 视频文件存储目录
|
||
├── config.yaml # 配置文件
|
||
├── requirements.txt # Python 依赖
|
||
├── app.py # 应用入口
|
||
├── API.md # API 文档
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 环境要求
|
||
|
||
- Python 3.8+
|
||
- MongoDB 4.0+
|
||
- 阿里云 DashScope API Key
|
||
|
||
### 2. 安装依赖
|
||
|
||
#### 方式一：使用启动脚本（推荐）
|
||
|
||
**Linux/Mac:**
|
||
```bash
|
||
./start.sh
|
||
```
|
||
|
||
**Windows:**
|
||
```cmd
|
||
start.bat
|
||
```
|
||
|
||
启动脚本会自动：
|
||
- 创建虚拟环境（如果不存在）
|
||
- 激活虚拟环境
|
||
- 安装/更新依赖
|
||
- 启动应用
|
||
|
||
#### 方式二：手动安装
|
||
|
||
```bash
|
||
# 创建虚拟环境
|
||
python3 -m venv venv
|
||
|
||
# 激活虚拟环境
|
||
source venv/bin/activate # Linux/Mac
|
||
# 或
|
||
venv\Scripts\activate # Windows
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. 配置
|
||
|
||
#### 主要配置方式：config.yaml（推荐）
|
||
|
||
编辑 `config.yaml` 文件，设置所有配置项：
|
||
|
||
```yaml
|
||
# DashScope API Configuration
|
||
dashscope:
|
||
api_key: "your-dashscope-api-key" # 必需：设置你的 DashScope API Key
|
||
|
||
# MongoDB Configuration
|
||
mongodb:
|
||
uri: "mongodb://localhost:27017"
|
||
database: "videoSummary"
|
||
|
||
# Server Configuration
|
||
server:
|
||
host: "0.0.0.0"
|
||
port: 8080
|
||
mode: "debug"
|
||
```
|
||
|
||
**所有配置都在 `config.yaml` 中管理，这是主要的配置方式。**
|
||
|
||
**注意**:
|
||
- 所有配置均在 `config.yaml` 文件中设置
|
||
- 请确保配置文件中的值正确
|
||
|
||
### 4. 配置 DashScope API Key
|
||
|
||
在 `config.yaml` 文件中设置你的 DashScope API Key：
|
||
|
||
```yaml
|
||
dashscope:
|
||
api_key: "your-dashscope-api-key-here"
|
||
```
|
||
|
||
**重要**: 必须设置 `dashscope.api_key` 才能使用视频分析功能。
|
||
|
||
# 5. 启动 MongoDB
|
||
|
||
确保 MongoDB 服务正在运行：
|
||
|
||
```bash
|
||
# Linux/Mac
|
||
mongod
|
||
|
||
# Windows
|
||
# 启动 MongoDB 服务
|
||
```
|
||
|
||
### 6. 运行应用
|
||
|
||
#### 使用启动脚本（推荐）
|
||
|
||
**Linux/Mac:**
|
||
```bash
|
||
./start.sh
|
||
```
|
||
|
||
**Windows:**
|
||
```cmd
|
||
start.bat
|
||
```
|
||
|
||
#### 手动运行
|
||
|
||
确保已激活虚拟环境，然后运行：
|
||
|
||
```bash
|
||
# 激活虚拟环境
|
||
source venv/bin/activate # Linux/Mac
|
||
# 或
|
||
venv\Scripts\activate # Windows
|
||
|
||
# 运行应用
|
||
python app.py
|
||
```
|
||
|
||
应用将在 `http://localhost:8080` 启动。
|
||
|
||
### 6. 访问前端
|
||
|
||
在浏览器中打开 `http://localhost:8080/static/index.html`
|
||
|
||
## API 使用
|
||
|
||
详细的 API 文档请参考 [API.md](API.md)
|
||
|
||
### 快速示例
|
||
|
||
#### 上传视频
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/videos/upload \
|
||
-F "file=@video.mp4"
|
||
```
|
||
|
||
#### 分析视频
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/videos/{video_id}/analyze
|
||
```
|
||
|
||
#### 生成总结
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/videos/{video_id}/summarize
|
||
```
|
||
|
||
#### 对比视频
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/videos/compare \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"video_ids": ["id1", "id2"]}'
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### config.yaml
|
||
|
||
主要配置项：
|
||
|
||
- **server**: 服务器配置（host, port, mode）
|
||
- **mongodb**: MongoDB 连接配置
|
||
- **dashscope**: DashScope API 配置（api_key, model, fps）
|
||
- **upload**: 上传配置（max_size, allowed_extensions）
|
||
- **log**: 日志配置（level, format, output）
|
||
|
||
### 配置说明
|
||
|
||
所有配置项均在 `config.yaml` 文件中设置。详细配置说明请参考 `CONFIG.md` 文档。
|
||
|
||
## 开发
|
||
|
||
### 项目结构说明
|
||
|
||
- **app/**: Flask 应用代码
|
||
- `routes/`: API 路由定义
|
||
- `services/`: 业务逻辑层
|
||
- `models/`: 数据模型
|
||
- `utils/`: 工具函数
|
||
- **static/**: 前端静态文件
|
||
- **uploads/**: 视频文件存储
|
||
|
||
### 代码规范
|
||
|
||
- 所有代码注释和文档使用英文
|
||
- 遵循 PEP 8 Python 代码规范
|
||
- API 设计遵循 RESTful 原则
|
||
|
||
## 部署
|
||
|
||
### 使用 Gunicorn（生产环境）
|
||
|
||
```bash
|
||
pip install gunicorn
|
||
gunicorn -w 4 -b 0.0.0.0:8080 app:app
|
||
```
|
||
|
||
### Docker 部署
|
||
|
||
```dockerfile
|
||
FROM python:3.9-slim
|
||
|
||
WORKDIR /app
|
||
COPY requirements.txt .
|
||
RUN pip install -r requirements.txt
|
||
|
||
COPY . .
|
||
|
||
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8080", "app:app"]
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **API Key 安全**: 不要将包含 API Key 的 `config.yaml` 提交到代码仓库。建议：
|
||
- 在本地 `config.yaml` 中设置 API Key
|
||
- 在 `config.yaml` 中设置 `dashscope.api_key`
|
||
- 将 `config.yaml` 添加到 `.gitignore`（如果包含敏感信息）
|
||
2. **文件存储**: 视频文件存储在本地 `uploads/` 目录，生产环境建议使用对象存储
|
||
3. **性能优化**: 视频分析可能需要较长时间，建议实现异步任务队列
|
||
4. **存储空间**: 定期清理旧视频文件，避免磁盘空间不足
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.0
|
||
- 初始版本发布
|
||
- 实现视频上传、分析、总结和对比功能
|
||
- 提供完整的 RESTful API
|
||
- 实现现代化前端界面
|
||
|