# 公安执法视觉理解检索系统

**Repository Path**: gdzWork/public-security-vision-retrieval-system

## Basic Information

- **Project Name**: 公安执法视觉理解检索系统
- **Description**: 面向公安执法的的视觉理解与检索系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-08-21
- **Last Updated**: 2026-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 公安执法视频智能分析与语义检索系统

本项目是一个面向公安执法视频管理场景的原型系统，围绕视频入库、结构化理解、自然语言检索、隐私脱敏和已入库视频管理构建完整流程。

项目技术路线与论文保持一致：**最终在线系统采用微调后的千问/Qwen-VL 多模态模型作为视频理解核心**，将视频关键帧转换为结构化字段；检索阶段使用结构化文本、DashScope 文本向量、关键词匹配、模糊匹配和标签权重完成混合排序。**CLIP 微调仅作为离线对比实验基线**，不接入 Web 主流程、视频入库接口或在线检索链路。

## 开源说明

由于执法视频、标注样本、训练集划分、运行索引和模型权重涉及数据安全、隐私保护或文件体积问题，本仓库不包含以下内容：

- 原始视频数据集、关键帧数据、人工标注数据
- `outputs/` 下的运行索引、上传文件、搜索日志和登录数据库
- EgoBlur `.jit` 权重、YOLO `.pt` 权重等大模型文件

## 核心功能

- 视频入库：上传视频或指定本地视频路径，调用千问多模态模型生成结构化归档结果。
- 结构化理解：输出物体、场景、人物角色、视频简介和业务标签等字段。
- 混合检索：融合 DashScope `text-embedding-v3`、关键词命中、模糊匹配、字段权重和长尾词增强。
- 隐私脱敏：基于 EgoBlur 或 OpenCV 回退逻辑处理人脸和车牌。
- 权限管理：提供管理员和普通用户两类权限，支持视频管理、搜索和脱敏操作。

## 技术路线

```text
视频输入
  |
  |-- 关键帧抽取
  v
微调千问/Qwen-VL 多模态模型
  |
  |-- objects
  |-- scene
  |-- persons
  |-- description
  |-- tags
  v
结构化索引写入 manifest.jsonl
  |
  |-- DashScope text-embedding-v3 生成文本向量
  |-- semantic_vectors.npz / semantic_meta.json 保存语义向量
  v
混合检索排序
  |
  |-- 语义相似度
  |-- 关键词命中
  |-- 模糊匹配
  |-- 字段权重
  |-- 标签匹配
  v
Web 结果展示与隐私脱敏
```

CLIP 路线只用于离线实验：

```text
视频关键帧 + 文本描述
  |
  v
CLIP 图文对比学习微调
  |
  v
生成视频向量和查询文本向量
  |
  v
与千问工作流使用相同测试集、相同 Top-K 指标进行对比
```

## 目录结构

```text
api/                  FastAPI 服务、鉴权、接口入口
configs/              项目配置模板，建议保留与当前主流程一致的配置
models/               模型封装和备用分析模块
pipelines/            视频入库、索引写入和混合检索流程
privacy/              人脸、车牌脱敏和 EgoBlur 适配
retrieval/            DashScope 语义向量存储及检索辅助组件
tools/                千问分析、批量入库、导入和必要数据处理脚本
utils/                视频读取和设备选择工具
web/                  前端页面、样式和脚本
finetune/             论文微调复现实验代码
docs/                 建议仅保留 QUICKSTART_DATASET.md 和 TECHNICAL.md
build_index.py        根据 manifest 重建语义向量索引
```

## 环境要求

- Python 3.10+
- Windows PowerShell 或兼容终端
- DashScope API Key，用于千问多模态调用和文本向量生成
- 可选 CUDA GPU，用于本地训练或加速隐私脱敏

设置 API Key：

```powershell
$env:DASHSCOPE_API_KEY="your_dashscope_api_key"
# 或
$env:QIANWEN_API_KEY="your_dashscope_api_key"
```

## 安装

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

如果需要运行论文微调实验，再安装训练专用依赖：

```powershell
pip install -r finetune\requirements-finetune.txt
```


启动后访问：

- Web 页面：`http://127.0.0.1:8000/`

默认本地管理员账号：

```text
用户名：admin
密码：admin123
```

正式部署前请通过环境变量修改默认账号密码：

```powershell
$env:LAW_VIDEO_ADMIN_USER="your_admin_user"
$env:LAW_VIDEO_ADMIN_PASSWORD="your_strong_password"
```

## 视频入库

通过 Web 页面登录后进入“视频入库”即可上传视频。

也可以使用本地路径入库接口：

```powershell
curl.exe -X POST "http://127.0.0.1:8000/index/from-path" `
  -F "video_path=D:\your_video_dir\demo.mp4" `
  -F "index_dir=outputs\index"
```

批量入库：

```powershell
python tools\qianwen_bulk_index.py `
  --source dir `
  --videos-dir D:\your_video_dir `
  --index-dir outputs\index `
  --max-videos 10
```

入库后主要生成：

```text
outputs/index/manifest.jsonl
outputs/index/semantic_vectors.npz
outputs/index/semantic_meta.json
web/static/previews/
```

这些文件属于运行产物，默认不建议提交到开源仓库。

## API 摘要

| 方法 | 路径 | 权限 | 说明 |
| --- | --- | --- | --- |
| `GET` | `/` | 公开 | Web 首页或登录页 |
| `POST` | `/auth/login` | 公开 | 登录 |
| `POST` | `/auth/logout` | 登录用户 | 退出登录 |
| `GET` | `/auth/me` | 登录用户 | 当前用户 |
| `GET` | `/health` | 公开 | 健康检查 |
| `POST` | `/index` | 管理员 | 上传单个视频入库 |
| `POST` | `/index/stream` | 管理员 | 流式上传入库 |
| `POST` | `/index/batch` | 管理员 | 上传多个视频入库 |
| `POST` | `/index/from-path` | 管理员 | 指定本地路径入库 |
| `POST` | `/search` | 登录用户 | 视频检索 |
| `GET` | `/search/hot` | 登录用户 | 搜索热度 |
| `POST` | `/privacy/redact` | 登录用户 | 图片或视频脱敏 |
| `GET` | `/index/list` | 登录用户 | 已入库视频列表 |
| `DELETE` | `/index/video/{video_id}` | 管理员 | 删除单条入库记录 |
| `POST` | `/index/videos/delete` | 管理员 | 批量删除入库记录 |
| `POST` | `/index/clear` | 管理员 | 清空索引目录 |

## 重要注意事项

- 本项目仅用于学习、科研和原型验证。
- 使用真实执法视频前，应完成数据授权、脱敏、审计和安全管理。

## 许可证
> ⚠️ 额外约束：**严禁将本项目（含修改后的衍生作品）用于各类学科竞赛、科创比赛、项目申报、评优评奖等参赛场景**。
> 本项目仅允许个人非商业学习、研究与参考。