# multiper

**Repository Path**: xuanwu_s3/multiper

## Basic Information

- **Project Name**: multiper
- **Description**: 多流视觉语言模型推理系统，支持多路视频流实时处理与智能分析。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-06-06
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

> 本文档的使用受[《版权与免责声明》](https://gitee.com/xuanwu_s3/docs/blob/master/版权与免责声明.md)约束，请在使用前仔细阅读。

# MultiStream-VLM

多流视觉语言模型推理系统，支持多路视频流实时处理与智能分析。

## 项目简介

MultiStream-VLM 是一个基于 RK3588 平台的多流视频处理系统，集成了：
- 多路视频流解码与处理
- YOLO 目标检测
- VLM（视觉语言模型）推理
- 实时视频显示输出

## 目录结构

```
multiper/
├── CMakeLists.txt          # 主 CMake 配置
├── build.sh                # 一键编译脚本
├── cmake/                  # CMake 配置文件
│   ├── toolchain.cmake     # 交叉编译工具链配置
│   ├── msvlm.cmake         # MSVLM 模块编译配置
│   ├── vi_yolo_venc.cmake  # VI-YOLO-VENC 模块编译配置
│   ├── hdmi_in_vlm.cmake   # HDMI-IN-VLM 模块编译配置
│   ├── rockit_yolo_detect.cmake # ROCKIT-YOLO-DETECT 模块编译配置
│   ├── ai_hub.cmake        # AI-HUB 模块打包配置（无需编译）
│   ├── anomaly_detection.cmake # ANOMALY-DETECTION 模块打包配置（无需编译）
│   ├── install.cmake       # 安装配置
│   └── package.cmake       # 打包配置
├── sample/                 # 示例模块
│   ├── msvlm/              # MSVLM 模块源码
│   ├── msevent/            # MSEVENT 模块源码
│   ├── vi_yolo_venc/       # VI-YOLO-VENC 模块源码
│   ├── hdmi_in_vlm/        # HDMI-IN-VLM 模块源码
│   ├── rockit_yolo_detect/ # ROCKIT-YOLO-DETECT 模块源码
│   ├── ai_hub/            # AI-HUB 模块源码（纯 Python，无需编译）
│   └── anomaly-detection/ # ANOMALY-DETECTION 模块源码（纯 Python，无需编译）
├── include/                # 公共头文件
├── third/                  # 第三方依赖库
├── _install/               # 安装目录
│   ├── msvlm/              # MSVLM 安装文件
│   ├── msevent/            # MSEVENT 安装文件
│   ├── vi_yolo_venc/       # VI-YOLO-VENC 安装文件
│   ├── hdmi_in_vlm/        # HDMI-IN-VLM 安装文件
│   ├── rockit_yolo_detect/ # ROCKIT-YOLO-DETECT 安装文件
│   ├── ai_hub/            # AI-HUB 安装文件
│   ├── anomaly-detection/ # ANOMALY-DETECTION 安装文件
│   └── overlay/            # 固件和模型文件
├── build/                  # 构建目录
└── output/                 # 打包输出目录
```

## 编译说明

### 环境要求

- CMake >= 3.16
- aarch64-none-linux-gnu 交叉编译工具链
- 目标平台：RK3588 (ARM aarch64)

### 编译命令

使用 `build.sh` 一键编译脚本：

```bash
# 显示帮助信息
./build.sh -h

# 清理构建目录（不编译）
./build.sh -c

# 编译所有模块
./build.sh -a

# 只编译 MSVLM 模块
./build.sh -m

# 只编译 MSEVENT 模块
./build.sh -e

# 只编译 VI-YOLO-VENC 模块
./build.sh --vi_yolo_venc

# 只编译 HDMI-IN-VLM 模块
./build.sh --hdmi_in_vlm

# 只编译 ROCKIT-YOLO-DETECT 模块
./build.sh --rockit_yolo_detect

# 只打包 AI-HUB 模块（纯 Python，无需编译）
./build.sh --ai_hub

# 只打包 ANOMALY-DETECTION 模块（纯 Python，无需编译）
./build.sh --anomaly_detection

# 编译并安装
./build.sh -m -i

# 编译、安装并打包
./build.sh -m -i -p

# 清理后编译、安装、打包
./build.sh -c -m -i -p
```

### 编译选项

| 选项 | 说明 |
|------|------|
| `-h, --help` | 显示帮助信息 |
| `-a, --all` | 编译所有模块（默认） |
| `-m, --msvlm` | 只编译 MSVLM 模块 |
| `-e, --msevent` | 只编译 MSEVENT 模块 |
| `--vi_yolo_venc` | 只编译 VI-YOLO-VENC 模块 |
| `--hdmi_in_vlm` | 只编译 HDMI-IN-VLM 模块 |
| `--rockit_yolo_detect` | 只编译 ROCKIT-YOLO-DETECT 模块 |
| `--ai_hub` | 只打包 AI-HUB 模块（纯 Python，无需编译） |
| `--anomaly_detection` | 只打包 ANOMALY-DETECTION 模块（纯 Python，无需编译） |
| `-c, --clean` | 清理 build 和 output 目录 |
| `-i, --install` | 编译后执行安装 |
| `-p, --package` | 编译后创建打包 |

## 安装目录结构

编译安装后的目录结构：

```
_install/
├── msvlm/
│   ├── bin/                    # 可执行文件
│   │   └── msvlm
│   ├── lib/                    # 共享库
│   ├── config/                 # 配置文件
│   │   ├── default.json
│   │   └── vlm_system_prompt.txt
│   ├── scripts/                # 运行脚本
│   │   ├── start.sh            # 启动服务（含 HDMI kiosk UI）
│   │   └── stop.sh             # 停止服务
│   ├── models/                 # 检测模型文件
│   │   └── yolov8/             # YOLOv8n 检测模型
│   ├── web/                    # Web 界面资源（HTTP/WebSocket）
│   └── install.sh              # 将 models 部署到 /userdata/models
├── vi_yolo_venc/
│   ├── bin/                    # 可执行文件
│   │   └── vi_yolo_venc
│   ├── lib/                    # 共享库
│   ├── models/                 # 模型文件
│   │   └── yolov8/             # YOLOv8n 检测模型
│   ├── run.sh                  # 启动脚本
│   └── install.sh              # 将模型部署到 /userdata/models
├── hdmi_in_vlm/
│   ├── bin/                    # 可执行文件
│   │   └── hdmi_in_vlm
│   ├── lib/                    # 共享库
│   ├── font/                   # OSD 渲染字体文件
│   ├── models/                 # 模型文件
│   │   └── yolov5s/            # YOLOv5s 检测模型
│   ├── run.sh                  # 启动脚本
│   └── install.sh              # 将字体和模型部署到 /userdata
├── rockit_yolo_detect/
│   ├── bin/                    # 可执行文件
│   │   ├── rockit_yolo_detect       # 主程序
│   │   └── rockit_yolo_detect_debug # 码流增删调试工具
│   ├── lib/                    # 共享库
│   ├── resource/               # 背景图与模型
│   │   ├── background-image.png
│   │   └── model/              # YOLOv5s 检测模型
│   ├── run.sh                  # 启动脚本
│   └── install.sh              # 将资源部署到 /usr/share/resource
├── ai_hub/                     # AI-HUB（纯 Python，无需编译）
│   ├── app.py                  # Flask 应用入口（端口 5000）
│   ├── backend/                # 后端蓝图（llm/multimodal/cnn/embedding/audio 等）
│   ├── static/                 # 前端静态资源
│   ├── templates/              # 页面模板
│   ├── system/                 # 部署到板端系统目录的二进制/库/模型数据
│   ├── run.sh                  # 服务启停脚本（start/stop）
│   └── install.sh              # 安装 Python 依赖并部署资源
└── anomaly-detection/          # ANOMALY-DETECTION（纯 Python，无需编译）
    ├── app.py                  # Flask 应用入口（端口 5000）
    ├── patchcore_train.py      # PatchCore 数据集标注/建库
    ├── patchcore_test.py       # PatchCore 数据集检测
    ├── patchcore-inspection/   # PatchCore 算法库（pip install -e 安装）
    ├── model/                  # DINOv3 特征提取模型（onnx/rknn/weight）
    ├── static/                 # 前端静态资源
    ├── templates/              # 页面模板
    ├── system/                 # 部署到板端系统目录的桌面图标等
    ├── run.sh                  # 服务启停脚本（start/stop）
    └── install.sh              # 安装 Python 依赖并部署资源
```

## 输出目录

打包后的输出文件位于 `output/` 目录：

```
output/
├── msvlm/                  # MSVLM 完整包
├── msvlm.tar.gz            # MSVLM 打包文件
├── msevent/                # MSEVENT 完整包
├── msevent.tar.gz          # MSEVENT 打包文件
├── vi_yolo_venc/           # VI-YOLO-VENC 完整包
├── vi_yolo_venc.tar.gz     # VI-YOLO-VENC 打包文件
├── hdmi_in_vlm/            # HDMI-IN-VLM 完整包
├── hdmi_in_vlm.tar.gz      # HDMI-IN-VLM 打包文件
├── rockit_yolo_detect/     # ROCKIT-YOLO-DETECT 完整包
├── rockit_yolo_detect.tar.gz # ROCKIT-YOLO-DETECT 打包文件
├── ai_hub/                 # AI-HUB 完整包
├── ai_hub.tar.gz           # AI-HUB 打包文件
├── anomaly-detection/      # ANOMALY-DETECTION 完整包
└── anomaly-detection.tar.gz # ANOMALY-DETECTION 打包文件
```

## 模块说明

### MSVLM 模块

多流视觉语言模型处理模块，主要功能：
- 多路视频流解码（支持本地文件、RTSP）
- YOLO 目标检测推理
- VLM 视觉语言模型推理
- NPU 多核负载均衡调度
- 实时视频显示输出（VO/HDMI）
- Web 监控界面（HTTP/WebSocket）+ HDMI kiosk 浏览器 UI 叠加

### VI-YOLO-VENC 模块

摄像头采集 + YOLO 检测 + 编码推流模块，主要功能：
- 通过 VI 采集摄像头视频（默认 1920x1080）
- YOLOv8n 目标检测，叠加检测框与类别名标签（NV12 直绘）
- 仅保留 person/car/bus/cat/dog 五类检测结果，其余类别过滤
- H.264/H.265 编码
- RTSP 直播推流
- 可选将编码码流保存到本地文件

### HDMI-IN-VLM 模块

HDMI 输入采集 + VLM 推理模块，主要功能：
- 通过 RK628-CSI 桥接采集 HDMI-IN 视频（1920x1080）
- YOLO 目标检测并叠加检测框
- FastVLM 视觉语言模型推理（场景描述）
- FreeType OSD 将 VLM 结果渲染到视频帧
- H.264/H.265 编码 + RTSP 直播推流
- VO 视频显示输出

### MSEVENT 模块

事件检测模块（预留）。

### ROCKIT-YOLO-DETECT 模块

多路视频文件解码 + YOLO 检测 + VO 显示模块，主要功能：
- 通过 rkdemuxer 解析 MP4 文件、Rockit VDEC 硬解码
- YOLOv5s 目标检测（支持 RKNN3 与 RKNN2 两种推理后端）
- Cairo 绘制检测框，经 VO RGN overlay 叠加显示
- 多路码流网格布局，无码流时显示背景图
- 通过 `rockit_yolo_detect_debug` 在运行时动态增删码流

可执行文件：
- `rockit_yolo_detect`：主程序，启动后显示背景图，等待码流接入
- `rockit_yolo_detect_debug`：调试工具，动态创建/删除码流

```shell
# 板端：先部署资源（背景图 + 模型）到 /usr/share/resource
./install.sh
# 运行主程序
./run.sh
# 另开终端：创建一路码流，无限循环播放
./bin/rockit_yolo_detect_debug path add /userdata/input.mp4 -1
# 删除第一路码流
./bin/rockit_yolo_detect_debug path remove 0
```

### AI-HUB 模块

端侧 AI 能力体验中心（纯 Python Web 应用，无需编译），主要功能：
- 基于 Flask 的 Web UI，集中体验多种端侧 AI 能力（默认端口 5000）
- LLM 大语言模型对话
- Multimodal 多模态（VLM）图文理解
- CNN 视觉推理（分类 ResNet/MobileNet、检测 YOLO）
- Embedding 文本/图像向量化
- Audio 语音识别（Whisper ASR）
- 在线模型管理与系统设置
- 一键部署脚本（install.sh 安装依赖并部署二进制/模型，run.sh 守护进程启停）

### ANOMALY-DETECTION 模块

工业缺陷检测示例（纯 Python Web 应用，无需编译），主要功能：
- 基于 Flask 的 Web UI 工业检测演示（默认端口 5000）
- 采用 PatchCore 异常检测算法 + DINOv3 特征提取（RKNN3 NPU 推理）
- 支持对 MVTec-AD 等数据集先标注建库、再进行缺陷检测
- 多线程并发检测、自动/单步运行、异常暂停、热力图叠加
- 提供桌面图标一键启动，支持局域网浏览器访问

## 依赖库

项目依赖以下第三方库：
- RKNPU2：RK3588 NPU 运行时库
- RKNN3-API：RKNN3 推理接口
- RKNN3-VLM：VLM 推理核心库
- Rockit：Rockchip 多媒体框架
- FFmpeg：音视频编解码库
- DRM：Direct Rendering Manager
- Tokenizer：文本分词库
- nlohmann/json：JSON 解析库

## 配置说明

系统配置文件位于 `_install/msvlm/config/default.json`，主要配置项：

- `pipeline.num_streams`：视频流数量
- `sources`：视频源配置
- `detector`：检测器配置
- `vlm`：VLM 配置
- `display`：显示输出配置

## 运行说明

### MSVLM

将编译好的 msvlm.tar.gz 文件部署到 RK3588 设备后，先解压进入目录：

```bash
tar -xvf msvlm.tar.gz
cd msvlm
```

**启动服务前，请先完成以下准备工作：**

1. 执行 `./install.sh` 将 YOLO 检测模型部署到 `/userdata/models/yolov8`：

   ```bash
   ./install.sh
   ```

2. 手动部署 VLM 模型到 `/userdata/models/`（具体路径见 config/default.json）。以 Qwen3-VL-2B 为例，`/userdata/models/Qwen3-VL-2B/` 目录下需包含以下文件，文件名必须与下方完全一致，否则程序无法加载，需手动重命名：

   ```
   Qwen3-VL-2B-llm.embed.bin
   Qwen3-VL-2B-llm.rknn
   Qwen3-VL-2B-llm.tokenizer.gguf
   Qwen3-VL-2B-llm.weight
   Qwen3-VL-2B-vision.rknn
   Qwen3-VL-2B-vision.weight
   ```

   > 特别注意 `Qwen3-VL-2B-llm.tokenizer.gguf` 和 `Qwen3-VL-2B-llm.embed.bin` 两个文件的命名。

3. 将测试视频 `1.ts`、`2.ts`、`3.ts`、`4.ts` 放到 `config/default.json` 中 `sources` 配置的路径下（默认配置为 `/userdata` 目录）。测试片源只支持 ts 流、H.264 / H.265 裸码流。

   视频源也支持 RTSP 网络流，把 `sources` 中对应条目的 `type` 改为 `rtsp`、`path` 填 RTSP 地址即可，四路可以文件与 RTSP 混用：

   ```json
   "0": {
       "id": 1,
       "name": "stream_0",
       "type": "rtsp",
       "path": "rtsp://192.168.1.100:554/live/stream0",
       "stream_id": 0,
       "enabled": true
   }
   ```

   > 必须同时改 `type`。只把 `path` 填成 RTSP 地址而 `type` 仍为 `video_file`，虽然也能出图，但会出现持续花屏、延迟累积、断流后该路不再恢复等问题。

完成上述准备后，启动/停止服务：

```bash
./scripts/start.sh           # 启动服务（默认在 HDMI 上拉起 kiosk 浏览器叠加显示监控 UI）
./scripts/stop.sh            # 停止服务
```

支持的命令行参数（传递给 msvlm 可执行文件；start.sh 默认透传 `--no-kiosk`）：

| 参数 | 说明 |
|------|------|
| `--no-kiosk` | 不在 HDMI 上拉起 kiosk 浏览器（仅保留视频输出 + Web 服务） |
| `--no-web` | 关闭 Web 服务器（HTTP/WebSocket） |
| `--no-vlm` | 关闭 VLM 推理 |
| `--port <端口>` | Web 服务端口（默认：8080） |
| `-c, --config <文件>` | 配置文件路径（默认：config/default.json） |

Web 访问地址：`http://<设备IP>:8080`

### VI-YOLO-VENC

将编译好的 vi_yolo_venc.tar.gz 文件部署到 RK3588 设备后：

```bash
tar -xvf vi_yolo_venc.tar.gz
cd vi_yolo_venc
./install.sh          # 将 models/yolov8 模型复制到 /userdata/models
./run.sh              # 启动 vi_yolo_venc（默认 -I 0 -w 1920 -h 1080 -e h264）
```

> 注意：程序读取 `/userdata/models/yolov8/config.json`，模型文件已随包提供，首次运行前执行 `./install.sh` 部署即可。

支持的命令行参数：

| 参数 | 说明 |
|------|------|
| `-w, --width` | VI 视频宽度（默认：1920） |
| `-h, --heght` | VI 视频高度（默认：1080） |
| `-I, --chnid` | 摄像头通道 ID（默认：0） |
| `-c, --frame_cnt` | 输出帧数（默认：-1，表示不限制） |
| `-e, --encode` | 编码类型：h264、h265（默认：h264；mjpeg 参数保留但当前 RTSP 流程不支持） |
| `-o` | 码流输出文件路径（默认：NULL，不保存） |

RTSP 推流地址：`rtsp://<设备IP>:554/live/0`

### HDMI-IN-VLM

将编译好的 hdmi_in_vlm.tar.gz 文件部署到 RK3588 设备后，先解压进入目录：

```bash
tar -xvf hdmi_in_vlm.tar.gz
cd hdmi_in_vlm
```

**启动前，请先完成以下准备工作：**

1. 执行 `./install.sh` 将字体与 YOLO 检测模型复制到 `/userdata`：

   ```bash
   ./install.sh
   ```

2. 手动将 FastVLM 模型部署到 `/userdata/models/FastVLM/`，目录下需包含以下文件，文件名必须与下方完全一致，否则程序无法加载，需手动重命名：

   ```
   vision_FastVLM_1.6B.rknn
   vision_FastVLM_1.6B.weight
   llm_FastVLM_1.6B.rknn
   llm_FastVLM_1.6B.weight
   FastVLM_1.6B.tokenizer.gguf
   FastVLM_1.6B.embed.bin
   ```

完成上述准备后，启动程序：

```bash
./run.sh              # 启动 hdmi_in_vlm
```

运行过程中按 `Ctrl+C` 可停止程序。

支持的命令行参数：

| 参数 | 说明 |
|------|------|
| `-w <宽度>` | 视频宽度（默认：1920） |
| `-h <高度>` | 视频高度（默认：1080） |
| `-e <h264\|h265>` | 编码器类型（默认：h264） |
| `-p <提示词>` | 自定义 VLM 提示词 |
| `-y <0\|1>` | YOLO 后端：0=rknn2，1=rknn3（默认：rknn2） |

RTSP 推流地址：`rtsp://<设备IP>:554/live/0`

### ROCKIT-YOLO-DETECT

将编译好的 rockit_yolo_detect.tar.gz 文件部署到 RK3588 设备后：

```bash
tar -xvf rockit_yolo_detect.tar.gz
cd rockit_yolo_detect
./install.sh          # 将 resource/（背景图 + 模型）复制到 /usr/share/resource
./run.sh              # 启动主程序（为 VO GPU 合成器配置 X 环境）
# 另开终端，动态增删码流：
./bin/rockit_yolo_detect_debug path add /userdata/input.mp4 -1   # -1 = 无限循环，1 = 播放一次
./bin/rockit_yolo_detect_debug path remove 0                     # 删除第一路码流
```

### AI-HUB

将编译好的 ai_hub.tar.gz 文件部署到 RK3588 设备后：

```bash
tar -xvf ai_hub.tar.gz -C /userdata    # 解压到 /userdata/ai_hub
cd /userdata/ai_hub
./install.sh          # 安装 Python 依赖，并将 system/ 下的二进制、库、模型数据部署到系统目录
./run.sh start        # 启动服务（守护进程，默认自动打开浏览器）
./run.sh stop         # 停止服务
```

> 注意：install.sh 需联网安装 Python 依赖（flask、openai、pillow、numpy 等）；
> VLM 与各类模型需预先部署到 `/userdata/models/`。

Web 访问地址：`http://<设备IP>:5000`

### ANOMALY-DETECTION

将打包好的 anomaly-detection.tar.gz 部署到 RK3588/RK182X 设备后：

```bash
tar -xvf anomaly-detection.tar.gz -C /userdata   # 解压到 /userdata/anomaly-detection
cd /userdata/anomaly-detection
./install.sh          # 安装 Python 依赖（flask、patchcore-inspection）并部署桌面图标
./run.sh start        # 启动服务（守护进程，初始化完成后自动打开浏览器）
./run.sh stop         # 停止服务
```

> 注意：运行前需保证 rknn3 服务已正常启动，并按 SDK 安装 rknn3-toolkit-lite；
> 数据集（如 MVTec-AD）需自行下载并推送到 `/userdata/datasets/`。
> 也可点击桌面图标「工业检测」启动。使用时先在页面选择数据集并「标注」，
> 完成后进入「数据集测试」页面选择数据集开始检测。

Web 访问地址：`http://<设备IP>:5000`

## 许可证

Apache License 2.0

## 贡献指南

欢迎提交 Issue 和 Pull Request。

## 联系方式

www.ebaina.com