176 lines
5.1 KiB
Markdown
176 lines
5.1 KiB
Markdown
# 技术设计文档
|
||
|
||
## 上下文
|
||
项目需要实现视频内容分析和总结功能，使用阿里云 DashScope 多模态 API 进行视频解析。系统需要支持视频上传、内容解析、自动总结以及多视频对比功能。
|
||
|
||
## 目标 / 非目标
|
||
|
||
### 目标
|
||
- 提供 RESTful API 用于视频文件上传和管理
|
||
- 集成阿里云 DashScope API 进行视频内容解析
|
||
- 自动生成视频内容总结
|
||
- 支持多个视频之间的内容对比
|
||
- 使用 MongoDB 持久化存储视频元数据和分析结果
|
||
- 提供简洁的静态前端页面进行交互
|
||
|
||
### 非目标
|
||
- 视频流式处理（当前仅支持文件上传）
|
||
- 实时视频分析（异步处理）
|
||
- 视频编辑功能
|
||
- 用户认证和权限管理（当前版本）
|
||
|
||
## 决策
|
||
|
||
### 1. 后端框架：Python Flask
|
||
**决策**：使用 Python Flask 构建 RESTful API 后端
|
||
|
||
**原因**：
|
||
- Python 对 AI/ML 生态支持良好，DashScope SDK 为 Python 原生
|
||
- Flask 轻量级，适合快速开发 RESTful API
|
||
- 易于集成第三方服务
|
||
|
||
**考虑的替代方案**：
|
||
- FastAPI：性能更好，但 Flask 更简单直接
|
||
- Django：功能完整但过于重量级
|
||
|
||
### 2. 数据库：MongoDB
|
||
**决策**：使用 MongoDB 存储视频元数据和分析结果
|
||
|
||
**原因**：
|
||
- 文档数据库适合存储非结构化的分析结果
|
||
- 灵活的 schema 便于扩展
|
||
- 项目已有 MongoDB 配置
|
||
|
||
**考虑的替代方案**：
|
||
- PostgreSQL：关系型数据库，但分析结果结构可能变化
|
||
- SQLite：轻量但不适合生产环境
|
||
|
||
### 3. 视频解析服务：阿里云 DashScope
|
||
**决策**：使用 DashScope MultiModalConversation API（qwen3-vl-plus 模型）
|
||
|
||
**原因**：
|
||
- 官方提供的多模态视频理解能力
|
||
- 支持视频抽帧分析（fps 参数）
|
||
- API 调用简单，集成方便
|
||
|
||
**配置要点**：
|
||
- fps 参数控制抽帧频率（默认 2，即每 0.5 秒一帧）
|
||
- API Key 通过环境变量或配置文件管理
|
||
- 需要处理 API 调用失败和重试
|
||
|
||
### 4. 文件存储：本地文件系统
|
||
**决策**：使用本地 uploads/ 目录存储视频文件
|
||
|
||
**原因**：
|
||
- 简单直接，无需额外服务
|
||
- 适合中小规模部署
|
||
|
||
**考虑的替代方案**：
|
||
- 对象存储（OSS/S3）：适合大规模部署，但增加复杂度
|
||
- 数据库存储：不适合大文件
|
||
|
||
### 5. 前端：静态页面
|
||
**决策**：使用纯 HTML/CSS/JavaScript 静态页面
|
||
|
||
**原因**：
|
||
- 简单直接，无需构建工具
|
||
- 易于部署和维护
|
||
- 满足当前功能需求
|
||
|
||
**考虑的替代方案**：
|
||
- React/Vue 框架：功能强大但增加复杂度
|
||
- 服务端渲染：当前不需要 SEO
|
||
|
||
## 架构设计
|
||
|
||
### 后端架构
|
||
```
|
||
app/
|
||
├── __init__.py # Flask 应用初始化
|
||
├── config.py # 配置管理
|
||
├── routes/
|
||
│ └── video_routes.py # 视频相关路由
|
||
├── services/
|
||
│ ├── video_service.py # 视频处理服务
|
||
│ ├── dashscope_service.py # DashScope API 封装
|
||
│ └── analysis_service.py # 分析业务逻辑
|
||
├── models/
|
||
│ ├── video.py # 视频模型
|
||
│ ├── analysis.py # 分析结果模型
|
||
│ └── comparison.py # 对比结果模型
|
||
└── utils/
|
||
├── file_utils.py # 文件处理工具
|
||
└── validators.py # 验证工具
|
||
```
|
||
|
||
### API 端点设计
|
||
```
|
||
POST /api/videos/upload # 上传视频
|
||
GET /api/videos # 获取视频列表
|
||
GET /api/videos/{video_id} # 获取视频详情
|
||
POST /api/videos/{video_id}/analyze # 解析视频内容
|
||
POST /api/videos/{video_id}/summarize # 生成视频总结
|
||
GET /api/videos/{video_id}/summary # 获取视频总结
|
||
POST /api/videos/compare # 对比多个视频
|
||
GET /api/videos/compare/{comparison_id} # 获取对比结果
|
||
```
|
||
|
||
### 数据模型设计
|
||
|
||
**Video 文档**：
|
||
```python
|
||
{
|
||
"_id": ObjectId,
|
||
"filename": str,
|
||
"file_path": str,
|
||
"upload_time": datetime,
|
||
"file_size": int,
|
||
"status": str, # "uploaded", "analyzing", "analyzed", "failed"
|
||
"mime_type": str
|
||
}
|
||
```
|
||
|
||
**AnalysisResult 文档**：
|
||
```python
|
||
{
|
||
"_id": ObjectId,
|
||
"video_id": ObjectId,
|
||
"analysis_type": str, # "content", "summary"
|
||
"content": str,
|
||
"fps": int,
|
||
"created_at": datetime
|
||
}
|
||
```
|
||
|
||
**Comparison 文档**：
|
||
```python
|
||
{
|
||
"_id": ObjectId,
|
||
"video_ids": [ObjectId],
|
||
"comparison_result": str,
|
||
"created_at": datetime
|
||
}
|
||
```
|
||
|
||
## 风险 / 权衡
|
||
|
||
### 风险
|
||
1. **API 调用失败** → 实现重试机制和错误处理
|
||
2. **大文件上传超时** → 设置合理的文件大小限制和超时时间
|
||
3. **视频解析耗时** → 异步处理，返回任务 ID，客户端轮询状态
|
||
4. **存储空间增长** → 定期清理或归档旧文件
|
||
|
||
### 权衡
|
||
- **同步 vs 异步处理**：当前采用同步处理，简单但可能阻塞。后续可改为异步任务队列
|
||
- **本地存储 vs 对象存储**：当前使用本地存储，简单但扩展性有限
|
||
|
||
## 迁移计划
|
||
- 无需迁移（新功能）
|
||
|
||
## 开放问题
|
||
- [ ] 是否需要实现视频文件清理策略（自动删除旧文件）？
|
||
- [ ] 是否需要支持批量视频上传？
|
||
- [ ] 视频解析的 fps 参数是否需要可配置？
|
||
- [ ] 是否需要实现解析结果缓存机制？
|
||
|