# vlm

**Repository Path**: techwolf/vlm

## Basic Information

- **Project Name**: vlm
- **Description**: 智能视频检测系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-19
- **Last Updated**: 2025-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于Qwen2.5-VL的智能视频分析系统

基于阿里云Qwen2.5-VL多模态大模型的智能视频目标检测和查找系统。

## 🖼️ 界面预览

### 主界面 - 马卡龙浅紫色主题
![主界面](screenshots/main-interface.png)

*美观的马卡龙浅紫色主题界面，支持拖拽上传和中文交互*

### 分析结果展示
![分析结果](screenshots/analysis-results.png)

*实时展示分析结果，包含置信度评分和详细描述*

### 多模型服务支持
![模型配置](screenshots/model-config.png)

*支持本地vLLM、Ollama、云端API等多种推理服务*

> 📸 **截图说明**: 界面截图正在准备中，请参考 `take_screenshots.md` 文件了解如何添加截图。

## 功能特点

- 🎥 支持多种视频格式上传 (MP4、AVI、MOV、MKV等)
- 🔍 自然语言描述目标检测
- 🚀 实时视频分析和结果展示
- 📊 详细的置信度评分
- 🎯 精确的时间定位
- 🎨 美观的马卡龙浅紫色主题界面
- 🌐 全中文交互界面
- 🔧 多种模型服务支持 (vLLM、Ollama、云端API)
- 📱 响应式设计，支持多设备访问
- 🐳 Docker容器化部署

## 技术栈

- **AI模型**: Qwen2.5-VL-7B-Instruct (多模态大语言模型)
- **推理引擎**: vLLM / Ollama / 云端API
- **后端框架**: FastAPI (异步高性能)
- **前端技术**: HTML5 + CSS3 + JavaScript (马卡龙主题)
- **视频处理**: OpenCV (帧提取和预处理)
- **容器化**: Docker + Docker Compose
- **模型客户端**: 支持多种推理服务
- **配置管理**: 环境变量和配置文件

## 快速开始

### 环境要求

- Python 3.11+
- NVIDIA GPU (推荐RTX A6000或更高)
- CUDA 11.8+
- Docker & Docker Compose
- 至少16GB GPU内存

### 安装步骤

#### 方法一：一键启动（推荐）

```bash
# 克隆项目
git clone <repository-url>
cd vlm

# 一键启动（自动安装依赖和启动服务）
./start.sh
```

#### 方法二：手动安装

1. **克隆项目**
```bash
git clone <repository-url>
cd vlm
```

2. **创建虚拟环境**
```bash
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows
```

3. **安装依赖**
```bash
pip install -r requirements.txt
```

4. **启动模型服务**
```bash
# 使用vLLM启动Qwen2.5-VL模型
vllm serve Qwen/Qwen2.5-VL-7B-Instruct --limit-mm-per-prompt image=4 --port 8001
```

5. **启动应用**
```bash
# 开发模式
python main.py

# 或使用uvicorn
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

6. **访问应用**
打开浏览器访问: http://localhost:8000

### Docker部署

#### 一键Docker启动
```bash
./start-docker.sh
```

#### 手动Docker部署
```bash
# 构建并启动所有服务
docker-compose up --build

# 后台运行
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

## 使用方法

### 基本使用流程

1. **上传视频**: 拖拽或点击上传视频文件
2. **描述目标**: 输入要查找的目标描述，如"穿红色衣服的人"
3. **开始分析**: 点击"Start Analysis"按钮
4. **查看结果**: 实时查看分析结果和关键帧

### 目标描述示例

- `"person wearing red shirt"` - 穿红色衣服的人
- `"car"` - 汽车
- `"dog"` - 狗
- `"person with backpack"` - 背背包的人
- `"bicycle"` - 自行车
- `"green object"` - 绿色物体

### 测试系统

1. **创建测试视频**
```bash
python create_test_video.py
```

2. **运行API测试**
```bash
python test_api.py
```

3. **测试模型推理**
```bash
python test_model.py
```

## 🔧 多模型服务支持

系统支持多种AI推理服务，可根据需求选择合适的部署方式：

### 支持的模型服务

| 服务类型 | 描述 | 优势 | 适用场景 |
|---------|------|------|---------|
| **vLLM** | 本地高性能推理 | 速度快、延迟低 | 有GPU资源的本地部署 |
| **Ollama** | 本地轻量化推理 | 部署简单、资源占用少 | 个人开发、小规模应用 |
| **OpenAI API** | OpenAI官方API | 稳定可靠、无需本地资源 | 生产环境、快速原型 |
| **Azure OpenAI** | 微软Azure平台 | 企业级、合规性好 | 企业应用、数据安全要求高 |
| **阿里云通义千问** | 阿里云API服务 | 中文优化、国内访问快 | 国内应用、中文场景 |

### 配置方法

通过环境变量选择模型服务：

```bash
# 使用本地vLLM (默认)
export MODEL_CLIENT_TYPE=vllm
export MODEL_BASE_URL=http://localhost:8001/v1

# 使用Ollama
export MODEL_CLIENT_TYPE=ollama
export MODEL_BASE_URL=http://localhost:11434
export MODEL_NAME=qwen2-vl

# 使用OpenAI API
export MODEL_CLIENT_TYPE=openai
export MODEL_API_KEY=sk-your-api-key-here

# 使用阿里云通义千问
export MODEL_CLIENT_TYPE=alibaba
export MODEL_API_KEY=sk-your-alibaba-key-here
```

详细配置请参考 `.env.example` 文件。

## API文档

### 主要端点

- `GET /` - 主页面
- `POST /analyze` - 视频分析接口
  - `video`: 视频文件 (multipart/form-data)
  - `object_str`: 目标描述字符串

### 响应格式

```json
{
    "status": "success",
    "frame": {
        "second": 5,
        "is_match": true,
        "description": "A person wearing a red shirt...",
        "confidence": 8,
        "frame_path": "/frames/video_id/frame_5.jpg"
    }
}
```

## 项目结构

```
vlm/
├── main.py                 # FastAPI主应用
├── test_model.py          # 模型测试脚本
├── requirements.txt       # Python依赖
├── Dockerfile            # Docker配置
├── docker-compose.yml    # Docker Compose配置
├── nginx.conf           # Nginx配置
├── templates/           # 前端模板
│   └── index.html      # 主页面
├── uploads/            # 上传的视频文件
├── frames/             # 提取的视频帧
└── README.md           # 项目说明
```

## 开发指南

### 测试模型推理

```bash
# 测试模型是否正常工作
python test_model.py
```

### 自定义配置

修改 `main.py` 中的配置:

```python
# 模型服务地址
client = OpenAI(
    base_url="http://localhost:8001/v1",
    api_key="test"
)

# 目录配置
UPLOAD_DIR = Path("uploads")
FRAMES_DIR = Path("frames")
```

## 性能优化

- 使用GPU加速推理
- 批量处理视频帧
- 图像预处理和增强
- 异步处理提升并发性能

## 故障排除

### 常见问题

1. **模型加载失败**
   - 检查GPU内存是否足够
   - 确认CUDA版本兼容性

2. **视频处理错误**
   - 检查视频格式是否支持
   - 确认OpenCV安装正确

3. **连接超时**
   - 增加nginx超时配置
   - 检查模型服务状态