# Video Summary - 视频分析与总结系统

基于 Python Flask 和阿里云 DashScope API 的视频内容分析与总结系统。

![系统界面](image.png)

## 功能特性

- 📹 **视频上传**: 支持多种视频格式上传（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
- 实现现代化前端界面