# LLaVA-Video-Insight

**Repository Path**: yixuanhuangtech/LLaVA-Video-Insight

## Basic Information

- **Project Name**: LLaVA-Video-Insight
- **Description**: fastapi包装llava-hf/LLaVA-NeXT-Video-7B-hf 

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-18
- **Last Updated**: 2025-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLaVA-Video Insight
基于 LLaVA-NeXT-Video 的智能视频内容分析 API
# 视频分析 API
- 🔒 **单例模型管理** - 确保模型只加载一次，节省内存
- 🛡️ **并发安全** - 支持多个请求同时初始化，但只执行一次
- ⚡ **启动预加载** - 应用启动时自动加载模型，首次请求无延迟
- 🔧 灵活的配置选项于 LLaVA-NeXT-Video 模型的视频内容分析 API，使用 FastAPI 构建。

## 功能特性

- 🎥 支持多种视频格式（MP4, AVI, MOV, MKV, WMV, FLV）
- 🤖 基于 LLaVA-NeXT-Video-7B 模型的智能视频内容分析
-### 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `PROJECT_NAME` | 项目名称 | "视频分析 API" |
| `ENVIRONMENT` | 运行环境 | "development" |
| `HOST` | 监听地址 | "0.0.0.0" |
| `PORT` | 监听端口 | 8000 |
| `CUDA_AVAILABLE` | GPU 是否可用 | "false" |
| `MODEL_ID` | 模型ID | "llava-hf/LLaVA-NeXT-Video-7B-hf" |
| `MAX_FRAMES` | 最大采样帧数 | 8 |
| `MAX_NEW_TOKENS` | 最大生成token数 | 1000 |
| `MAX_FILE_SIZE` | 最大文件大小 | 104857600 (100MB) |
| `PRELOAD_MODEL_ON_STARTUP` | 启动时预加载模型 | "true" |
| `STARTUP_TIMEOUT` | 启动超时时间(秒) | 300 |持高并发
- 📊 自动视频帧采样和处理
- � 支持 URL 视频和本地文件
- ⏱️ 基于时间间隔的精确帧采样
- 🔒 **单例模型管理** - 确保模型只加载一次，节省内存
- 🛡️ **并发安全** - 支持多个请求同时初始化，但只执行一次
- �🔧 灵活的配置选项
- 📝 完整的 API 文档（Swagger UI）
- 🐳 Docker 容器化部署
- 💾 分析结果缓存和管理

## 项目结构

```
video_anaylize/
├── app/
│   ├── api/
│   │   └── routes/
│   │       └── video.py          # 视频分析 API 路由
│   ├── core/
│   │   └── config.py             # 应用配置
│   ├── models/
│   │   └── video.py              # 数据模型
│   └── services/
│       └── video_analysis.py     # 视频分析服务
├── uploads/                      # 上传文件目录
├── temp/                        # 临时文件目录
├── main.py                      # 原始分析脚本
├── main_fastapi.py             # FastAPI 应用入口
├── requirements.txt            # Python 依赖
├── Dockerfile                  # Docker 构建文件
├── docker-compose.yml         # Docker Compose 配置
├── .env.example              # 环境变量示例
└── README.md                 # 项目说明
```

## 快速开始

### 1. 环境要求

- Python 3.8+
- CUDA 11.8+ (可选，用于 GPU 加速)
- FFmpeg (用于视频处理)

### 2. 安装依赖

```bash
# 克隆项目
cd video_anaylize

# 创建虚拟环境
python -m venv venv

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

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

### 3. 配置环境

```bash
# 复制环境变量配置文件
copy .env.example .env

# 编辑 .env 文件，设置必要的配置
# 特别是 CUDA_AVAILABLE 参数
```

### 4. 启动服务

```bash
# 开发模式
uvicorn main_fastapi:app --reload --host 0.0.0.0 --port 8000

# 生产模式
uvicorn main_fastapi:app --host 0.0.0.0 --port 8000
```

### 5. 使用 Docker 部署

```bash
# 构建镜像
docker build -t video-analysis-api .

# 运行容器
docker run -p 8000:8000 video-analysis-api

# 或使用 docker-compose
docker-compose up -d
```

## API 使用

### 访问 API 文档

启动服务后，访问以下地址查看完整的 API 文档：

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

### 主要 API 端点

#### 1. 预测视频内容（新增）

```bash
POST /predictions
```

**全新的预测接口**，支持URL和本地文件，基于时间间隔采样：

**请求示例：**
```json
{
    "video": "https://www.shutterstock.com/shutterstock/videos/1104246027/preview/stock-footage-woman-friends-and-jumping-in-sea-holding-hands-for-fun-holiday-weekend-adventure-or-vacation-in.mp4",
    "prompt": "Describe this video and the people in it in detail",
    "num_frames": 10,
    "max_new_tokens": 500
}
```

**参数说明：**
- `video`: 视频URL或本地文件路径
- `prompt`: 分析提示词（必填）
- `num_frames`: 帧间隔秒数（10=每10秒一帧，0.1=每秒10帧）
- `max_new_tokens`: 最大生成token数

**响应示例：**
```json
{
    "output": "The video shows two women jumping into the sea...",
    "processing_time": 15.23,
    "frames_processed": 5,
    "video_duration": 30.5,
    "frame_interval": 10.0
}
```

#### 2. 上传视频

```bash
POST /api/v1/video/upload
```

上传视频文件并获取文件ID。

#### 3. 分析视频

```bash
POST /api/v1/video/analyze
```

分析视频内容，支持自定义提示词。

#### 4. 获取分析结果

```bash
GET /api/v1/video/analysis/{analysis_id}
```

根据分析ID获取结果。

#### 6. 获取分析历史

```bash
GET /api/v1/video/analyses
```

获取所有分析结果的分页列表。

#### 7. 模型管理接口

```bash
# 获取模型详细状态
GET /api/v1/video/model/status

# 初始化模型（如果未加载）
POST /api/v1/video/model/initialize

# 强制重新初始化模型
POST /api/v1/video/model/reinitialize

# 获取模型基本信息
GET /api/v1/video/model/info
```

### 使用示例

#### 使用新的预测API

```python
import requests

# 预测视频内容（支持URL和本地文件）
response = requests.post(
    'http://localhost:8000/predictions',
    json={
        'video': 'https://example.com/video.mp4',  # 或本地路径
        'prompt': 'Describe this video and the people in it in detail',
        'num_frames': 10,  # 每10秒采样一帧
        'max_new_tokens': 500
    }
)
result = response.json()
print(f"分析结果: {result['output']}")
print(f"处理时间: {result['processing_time']:.2f}秒")
print(f"处理帧数: {result['frames_processed']}")
```

#### 使用传统上传+分析API

```python
import requests

# 1. 上传视频
with open('test_video.mp4', 'rb') as f:
    response = requests.post(
        'http://localhost:8000/api/v1/video/upload',
        files={'file': f}
    )
    file_id = response.json()['file_id']

# 2. 分析视频
response = requests.post(
    'http://localhost:8000/api/v1/video/analyze',
    json={
        'file_id': file_id,
        'prompt': '详细描述视频中的内容',
        'max_frames': 8,
        'max_tokens': 1000
    }
)
analysis = response.json()
print(f"分析结果: {analysis['result']}")
```

#### 测试新API

你可以运行提供的测试脚本：

```bash
# 测试预测功能
python test_predictions.py

# 测试启动预加载功能
python test_startup.py

# 测试模型单例机制
python test_singleton.py

# 验证项目设置
python test_setup.py
```

## 启动方式

### 方式1: 使用启动脚本（推荐）

```bash
# Windows
start.bat

# Linux/Mac
./start.sh
```

启动脚本会：
- 自动检查环境配置
- 创建必要目录 
- 显示启动进度
- 预加载模型（可配置）

### 方式2: 直接启动

```bash
# 开发模式（自动重载）
python main_fastapi.py

# 或使用 uvicorn
uvicorn main_fastapi:app --reload

# 生产模式
uvicorn main_fastapi:app --host 0.0.0.0 --port 8000
```

### 方式3: 使用自定义启动器

```bash
python startup.py
```

提供详细的启动信息和环境检查。

### 模型单例机制

本项目实现了**智能的模型单例管理**：

- ✅ **单次加载**: 无论多少个请求同时到达，模型只会被加载一次
- ✅ **并发安全**: 使用异步锁确保并发初始化的安全性
- ✅ **启动预加载**: 应用启动时自动加载模型，避免首次请求延迟
- ✅ **状态检查**: 提供详细的模型状态检查和诊断
- ✅ **自动恢复**: 支持强制重新初始化以处理模型损坏情况
- ✅ **内存优化**: 避免重复加载造成的内存浪费

**工作原理:**
1. **启动预加载**: 应用启动时自动在后台加载模型
2. **首次请求**: 如果预加载成功，首次请求立即响应
3. **并发保护**: 如果多个请求同时初始化，只执行一次加载
4. **状态监控**: 提供多个接口监控模型状态和诊断问题

**配置选项:**
```bash
# .env 文件
PRELOAD_MODEL_ON_STARTUP=true  # 启用启动预加载
STARTUP_TIMEOUT=300           # 预加载超时时间（秒）
```

**性能优势:**
- **首次请求**: 毫秒级响应（无需等待模型加载）
- **内存效率**: 避免重复加载节省几GB内存
- **用户体验**: 无感知的模型初始化过程

## 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `PROJECT_NAME` | 项目名称 | "视频分析 API" |
| `ENVIRONMENT` | 运行环境 | "development" |
| `HOST` | 监听地址 | "0.0.0.0" |
| `PORT` | 监听端口 | 8000 |
| `CUDA_AVAILABLE` | GPU 是否可用 | "false" |
| `MODEL_ID` | 模型ID | "llava-hf/LLaVA-NeXT-Video-7B-hf" |
| `MAX_FRAMES` | 最大采样帧数 | 8 |
| `MAX_NEW_TOKENS` | 最大生成token数 | 1000 |
| `MAX_FILE_SIZE` | 最大文件大小 | 104857600 (100MB) |

### 支持的视频格式

- MP4 (.mp4)
- AVI (.avi) 
- MOV (.mov)
- MKV (.mkv)
- WMV (.wmv)
- FLV (.flv)

## 性能优化

### GPU 加速

如果您有可用的 NVIDIA GPU：

1. 安装 CUDA 和 cuDNN
2. 安装 GPU 版本的 PyTorch：
   ```bash
   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
   ```
3. 设置环境变量：
   ```
   CUDA_AVAILABLE=true
   ```

### 内存优化

- 调整 `MAX_FRAMES` 参数减少内存使用
- 设置 `LOW_CPU_MEM_USAGE=true` 启用低内存模式
- 限制 `MAX_FILE_SIZE` 避免处理过大的视频文件

## 故障排除

### 常见问题

1. **模型下载慢**
   - 使用国内镜像源或手动下载模型到本地
   - 设置 `HF_ENDPOINT` 环境变量

2. **内存不足**
   - 减少 `MAX_FRAMES` 参数
   - 启用 `LOW_CPU_MEM_USAGE` 模式
   - 使用更小的模型

3. **GPU 不可用**
   - 检查 CUDA 安装
   - 验证 PyTorch CUDA 支持
   - 确认 GPU 驱动程序

### 日志查看

```bash
# 查看应用日志
tail -f logs/app.log

# Docker 容器日志
docker-compose logs -f
```

## 开发指南

### 项目架构

- **FastAPI**: Web 框架
- **Pydantic**: 数据验证和序列化
- **Transformers**: 模型加载和推理
- **PyAV**: 视频处理
- **Uvicorn**: ASGI 服务器

### 添加新功能

1. 在 `app/models/` 中定义数据模型
2. 在 `app/services/` 中实现业务逻辑
3. 在 `app/api/routes/` 中创建 API 端点
4. 更新配置和文档

### 测试

```bash
# 运行测试
pytest tests/

# 代码格式化
black app/ tests/

# 类型检查
mypy app/
```

## 部署

### Docker 部署

```bash
# 构建和运行
docker-compose up -d

# 扩容
docker-compose up -d --scale video-analysis-api=3
```

### 生产环境建议

- 使用反向代理（Nginx）
- 配置 HTTPS
- 设置日志轮转
- 监控和告警
- 负载均衡

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

如有问题，请通过 GitHub Issues 联系我们。