README.md

# VideoAgent — 视频理解分析(基于 AX650N)

基于 AX650N 芯片平台，构建多模态 VideoAgent，面向视频理解与检索，支持长视频智能分析与自然语言问答。

<p align="center">
  <img src="https://img.shields.io/badge/platform-AX650N-blue" alt="Platform">
  <img src="https://img.shields.io/badge/python-3.10+-green" alt="Python">
  
</p>

---

## 核心功能

- **芯片平台部署** — 基于 AX650N 芯片部署全部模型，端到端运行完整流程
- **视频智能索引** — 自动分段、特征提取、多模态信息融合（ASR + VLM）
- **向量检索** — 高效相似度检索与结果融合，支持跨模态查询
- **自然语言问答** — 用自然语言提问，基于视频内容生成回答

---

## 模型配置

基于 AX650N 芯片平台运行前，请下载以下模型并参照相关文档完成部署：

| 模型类型 | 模型名称 | 说明 |
|---------|---------|------|
| **ASR** | [SenseVoiceSmall-axmodel](https://huggingface.co/M5Stack/SenseVoiceSmall-axmodel) | 多语言语音理解模型 |
| **VLM** | [Qwen3-VL-2B-Instruct-GPTQ-Int4](https://huggingface.co/AXERA-TECH/Qwen3-VL-2B-Instruct-GPTQ-Int4) | 多模态视觉语言模型 |
| **LLM** | [Qwen3-1.7B](https://huggingface.co/AXERA-TECH/Qwen3-1.7B) | 大语言模型 |
| **Embedding** | [Qwen3-VL-Embedding-2B-AX650](https://huggingface.co/AXERA-TECH/Qwen3-VL-Embedding-2B-AX650-C128_P1280_CTX1407) | 多模态嵌入模型 |

---

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置环境变量

Embedding、VLM、LLM、ASR、Tokenizer 均通过环境变量配置。其中 Embedding、VLM、LLM 兼容 OpenAI API 格式。

```bash
cp .env.example .env
# 编辑 .env 文件，填入实际模型路径和 API 地址
```

`.env` 配置示例：

```ini
# LLM API（OpenAI API 格式）
LLM_MODEL_PATH = "/data/huangjie/.cache/modelscope/hub/models/Qwen/Qwen3-VL-Embedding-2B"
LLM_API_BASE_URL = "http://0.0.0.0:8012/v1/"
LLM_API_KEY = "xxx"
LLM_MODEL_NAME = "AXERA-TECH/Qwen3-1.7B"
LLM_API_PORT = 8012

# ASR API
SHERPA_MODEL_DIR = "/root/huangjie/AXERA-TECH/SenseVoice"
SHERPA_ASR_URL = "http://0.0.0.0:8013"
SHERPA_ASR_API_PORT = 8013
SHERPA_MODEL_FILE = "/root/huangjie/AXERA-TECH/SenseVoice/ax650/model-10-seconds.axmodel"

# Tokenizer API
Tokenizer_MODEL_PATH = "/root/huangjie/project/VideoAgent_api507/VideoAgent/_llm/tokenizer_model/Qwen/Qwen3-1.7B"
Tokenizer_API_BASE_URL = "http://0.0.0.0:8014"
Tokenizer_API_PORT = 8014
```

### 3. 启动模型服务

基于 AX650N 芯片启动各模型服务：

```bash
# Embedding 服务 — 端口 8010
axllm serve /root/huangjie/AXERA-TECH/models--AXERA-TECH--Qwen3-VL-Embedding-2B-AX650-C128_P1280_CTX1407 --port 8010

# VLM 服务 — 端口 8011
axllm serve /root/huangjie/AXERA-TECH/Qwen3-VL-2B-Instruct-GPTQ-Int4 --port 8011

# LLM 服务 — 端口 8012
axllm serve /root/huangjie/AXERA-TECH/models--AXERA-TECH--Qwen3-1.7B --port 8012

# ASR 服务 — 端口 8013
python VideoAgent/_server/sherpa_asr_server.py

# Tokenizer 服务 — 端口 8014
python VideoAgent/_server/tokenizer_server.py
```

### 4. 使用方式

#### Web UI（推荐）

```bash
python webui.py
```

浏览器访问 **http://localhost:7869**

| 索引界面 | 检索界面 |
|---------|---------|
| ![索引界面](image-5.png) | ![检索界面](image-4.png) |

#### Python SDK

```python
from VideoAgent import VideoRAG, QueryParam

# 初始化 RAG 系统
rag = VideoRAG(working_dir="./working_dir")

# 索引视频文件
rag.insert_video(video_path_list=["video1.mp4", "video2.mp4"])

# 查询视频内容
result = rag.query(query="视频中什么时候出现张飞？", param=QueryParam())
print(result)
```

---

## 工作流程

### 视频索引流程

![索引流程](image-2.png)
### 查询流程


![查询流程](image-3.png)


---

## 项目结构

```
VideoAgent-AX650N/
├── VideoAgent/                 # 核心包
│   ├── _llm/                   # 模型定义层
│   ├── _server/                # 服务层（FastAPI）
│   ├── _storage/               # 存储层
│   ├── _videoutil/             # 视频处理工具
│   └── vidrag_pipeline.py      # 核心管道
├── working_dir/                # 运行时数据目录
├── webui.py                    # Gradio Web 入口
├── videorag_longervideos.py    # 测试脚本
└── README.md                   # 项目文档
```

---

## 参考项目

- 香港大学数据科学实验室（HKUDS）— [VideoRAG](https://github.com/HKUDS/VideoRAG)：超长视频跨模态检索增强生成框架