# Nexus-Vision-Service

**Repository Path**: beituo/nexus-vision-service

## Basic Information

- **Project Name**: Nexus-Vision-Service
- **Description**: 基于YOLO + RapidOCR 的人脸识别、物料核对、质检OCR，为NexusERP等系统提供视觉服务
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 12
- **Created**: 2026-10-30
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# nexus-vision-service

统一视觉服务：**YOLO 目标检测 + RapidOCR 文字识别 + 人脸识别（1:1/1:N）+ 人脸底库 + API key 鉴权 + 轻量管理页**。

为 nexus-erp / nexus-school 提供视觉 AI 能力（操作台人脸验证、学生人脸签到、物料核对、质检 OCR），通过 HTTP REST 被 Java 后端调用。

> 本服务融合了 CompreFace 的设计理念（subject 底库 / API key 鉴权 / 1:1/1:N 语义 / 管理界面），
> 用现代 Python 生态实现（InsightFace ONNX + Ultralytics + RapidOCR），单容器部署。

## 特性

- 🔍 **通用目标检测**：YOLOv11n（COCO 80 类），`/api/detect/material`
- 🎯 **多场景检测模型**：物料/缺陷场景模型（`models/scenarios/`）管理页在线切换，请求级 `scenario` 参数覆盖
- 📝 **文字识别**：RapidOCR（PaddleOCR 模型 ONNX 版），`/api/detect/product` 内嵌
- 👤 **人脸识别**：SCRFD 检测 + ArcFace 512 维特征（InsightFace），1:1 verify / 1:N recognize
- 🎬 **视频流人脸识别**：视频文件 / RTSP 拉流，抽帧 + 轨迹聚合 + 静默活体
- 📚 **人脸底库**：MySQL 存储（subject = 工号/学号，重复注册特征取均值）
- 🔑 **API key 鉴权**：CompreFace 同款 `x-api-key` 机制，带内存缓存
- 🖥 **轻量管理页**：`/admin`（底库管理 / 检测调试 / API keys / 系统设置，纯静态无构建链）
- ⚡ **GPU 加速**：torch CUDA + onnxruntime CUDAExecutionProvider，管理页 CPU/GPU 在线切换
- 🐳 **单容器部署**：模型构建期预烘焙，首启即就绪，支持 `--gpus` 与 CPU 镜像两种形态

## 目录结构

```
nexus-vision-service/
├── app/
│   ├── main.py              # FastAPI 入口 + lifespan（启动预载引擎）
│   ├── core/                # config（环境变量）/ db（MySQL 连接池）/ runtime（GPU/场景偏好）/ scenario（默认场景）
│   ├── routers/             # health / material / product / faces / video / api-keys / system
│   ├── models/              # yolo_detector（多场景）/ ocr_engine / face_engine / liveness_engine / scenario_registry
│   ├── services/            # face_recognizer / face_repository / api_key_service / video_analyzer / settings_service
│   └── web/                 # /admin 管理页（人脸底库 / 检测调试 / API keys / 系统设置）
├── models/                  # 模型文件（yolo11n.pt + insightface/buffalo_l + scenarios/，权重不入库）
├── script/                  # install / download_models / prepare_datasets / download_gc10 / convert_deeppcb / convert_rpc / train_scenario
├── docs/                    # API / 部署 / 操作手册 / 安全加固 / 设计文档 / 排障 / 截图
├── tests/                   # pytest（单元 / MySQL 集成测试）
├── requirements.txt / Dockerfile / docker-compose.yml
└── .env.example             # 配置模板
```

## 快速启动

```bash
# 1. 准备 MySQL（建库建表 + 初始 API key）
mysql -u root -p < script/init-vision.sql

# 2. 执行安全字段增量迁移（不轮换 Key、不删除照片/Embedding）
python script/migrate_security.py

# 3. 配置（MySQL 连接信息）
cp .env.example .env

# 4. 构建并启动（仓库自带 docker-compose.yml，Docker Compose v2.20+）
docker compose up -d --build

# 5. 验证
curl http://localhost:5001/health
curl http://localhost:5001/health/ready
```

管理页：`http://localhost:5001/admin/`（API key：`dev-key-admin`）

> ⚠️ 安全提示：`dev-key-*` 是本地开发 key，**生产环境必须**通过 `POST /api/v1/api-keys`
> 生成新 key 并禁用 dev key（服务启动时检测到 dev key 会打 WARNING）。
> `/api/v1/api-keys` 管理端点仅管理员 key（`owner=admin-page`）可调用。

## 场景模型训练（可选）

服务内置 `general`（COCO 80 类通用模型），若需检测工厂物料/成品缺陷等自定义类别，
可训练场景模型放入 `models/scenarios/<scenario_key>/`（`weights.pt` + `classes.yaml` +
`metrics.yaml`，目录规范见 [script/scenarios/README.md](script/scenarios/README.md)），
管理页在线切换，无需重启。

**当前已训练场景**：

| 场景 key | 数据集 | 类别 | mAP50 | 说明 |
|---|---|---|---|---|
| `defect_metal` | GC10-DET | 金属表面缺陷 10 类（中文） | 0.739 | 划痕/斑块/异物等 |
| `defect_pcb` | DeepPCB | PCB 缺陷 6 类（中文） | **0.976** | 开路/短路/鼠咬/毛刺/残铜/针孔 |
| `material_retail` | RPC | 零售商品 200 类（中文 SKU 名） | 0.087* | 单品识别置信度 0.96+；结算密集场景存在域差待改进* |

\* material_retail 的验证集为俯拍密集结算场景，与单品训练图存在视角域差；按"单件物料对准摄像头核对"
的用法（物料核对的真实场景）识别效果良好。

五步流程：

```bash
# 1. 下载并转换公开数据集（按目标场景选择脚本）
python script/download_gc10.py                                      # GC10-DET 金属缺陷(自动下载)
python script/convert_deeppcb.py                                    # DeepPCB(先 clone 到 datasets/)
python script/convert_rpc.py                                        # RPC 零售商品(先从 Kaggle 下载)
# 2. 训练（GPU 机器/容器内执行）
python script/train_scenario.py --data datasets/defect_pcb/dataset.yaml --key defect_pcb --device 0 --batch 8
# 3. 产物自动写入 models/scenarios/defect_pcb/（weights.pt + classes.yaml + metrics.yaml）
# 4. 管理页 system.html 刷新即可看到并切换（无需重启服务）
```

更多数据集（NEU-DET 等）见 `python script/prepare_datasets.py --list`。

相关 `.env` 配置项：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `SCENARIO_MODELS_DIR` | `models/scenarios` | 场景模型目录 |
| `DEFAULT_MATERIAL_SCENARIO` | `general` | 物料接口默认检测场景（未知场景名推理时回落 `general`；场景存在但缺权重则 503） |
| `DEFAULT_PRODUCT_SCENARIO` | `general` | 成品接口默认检测场景（同上） |

### 训练数据来源与许可声明

本项目的演示场景模型使用了以下**公开学术数据集**训练，在此感谢数据集作者：

| 数据集 | 来源 | 用途 | 许可 |
|---|---|---|---|
| [GC10-DET](https://github.com/lvxiaoming2019/GC10-DET-Metallic-Surface-Defect-Datasets) | 东北大学等 / HF 镜像(`lzhzj/gc10-det`，Roboflow 导出) | 金属表面缺陷检测 | CC BY 4.0 |
| [DeepPCB](https://github.com/tangsanli5201/DeepPCB) | GitHub (Tang et al.) | PCB 缺陷检测 | 仅限研究用途 |
| [RPC](https://rpc-dataset.github.io/) | 阿里云天池 / Kaggle(`diyer22`) | 零售商品识别 | CC BY-NC-SA 4.0 |
| NEU-DET | 东北大学（郝晓静等） | 钢材表面缺陷检测 | 学术用途（备选，未用于已发布模型） |
| YOLOv11n 底模 | [Ultralytics](https://github.com/ultralytics/ultralytics)（AGPL-3.0） | 微调基座 | AGPL-3.0 |

上述数据集均为学术/非商用许可，**本项目仅将其用于技术学习与演示验证，不作商业用途**；
正式商用前必须以自有采拍数据重训替换。若数据集作者认为本项目的使用方式不妥，
请提交 issue 联系删除，我们会立即移除相关模型与文档内容。

> 📦 Docker 部署注意：镜像构建时未包含 `models/scenarios/`，容器内使用场景模型需将
> `models/scenarios/` 目录挂载进容器（compose volumes 已预置
> `./models/scenarios:/app/models/scenarios`），或 `docker cp` 拷入后无需重启即可生效。

## 一键安装包（发行版）

无需 Docker、无需手动建环境，从 **Gitee Releases** 下载源码包解压后一条命令安装（模型自动下载约 188MB）：

**📥 下载地址**：[Gitee Releases](https://gitee.com/NexusERP/nexus-vision-service/releases)（选择最新版本 `v2.2.0`，下载对应平台 zip）

| 平台 | 附件名 | 安装命令 |
|------|--------|---------|
| Windows | `nexus-vision-service-2.2.0-win.zip` | 解压后双击 `install_win.bat` |
| Linux | `nexus-vision-service-2.2.0-linux.zip` | `unzip ... && bash install_linux.sh` |

**Linux 命令行下载示例**：

```bash
wget https://gitee.com/NexusERP/nexus-vision-service/releases/download/v2.2.0/nexus-vision-service-2.2.0-linux.zip
unzip nexus-vision-service-2.2.0-linux.zip && cd nexus-vision-service-2.2.0-linux
bash install_linux.sh
```

**前置条件**（两个平台一致）：
1. **Python 3.10+**（Windows 建议装 `py` 启动器；3.10 首选，3.11/3.12 可用但 insightface 需自行装 wheel）
2. **MySQL 5.7.8+** 已安装并运行（脚本需 root 权限建库，会交互式询问连接信息；无 mysql 客户端则跳过建库，需手动执行 `script/init-vision.sql`）

**安装流程**（脚本自动完成 6 步）：
1. 检测 Python → 2. 创建 `.venv` 并安装依赖（首次约 1.5GB，5-15 分钟）→
   3. 检查/下载模型（约 188MB，多源回退+断点续传，已下载自动跳过）→
   4. 交互式生成 `.env`（MySQL 连接信息，回车用默认值）→
   5. 导入 `init-vision.sql` 建库建表+初始 key → 6. 启动服务

**安装完成后**：
- 服务运行于 `http://localhost:5001`（Windows 前台运行 Ctrl+C 停止；Linux 后台运行，日志 `.venv/uvicorn.log`）
- 管理页 `http://localhost:5001/admin/`，默认 API key：`dev-key-admin`
- 再次运行脚本会自动跳过已完成的步骤（幂等）

**重新安装/升级**：删除 `.env` 重跑脚本可重新配置；模型已下载会跳过。脚本位于 `script/`：`install_win.bat` / `install_linux.sh` / `download_models.py` / `init_env.py`。

> 📦 发行版 zip 仅含源码（~1.2MB），不含模型与依赖——模型与 Python 依赖均在安装时自动获取。

## 测试

自动化测试使用 Python 3.10 和 Node.js 22；只安装轻量依赖，不需要模型文件、GPU、
Torch、Ultralytics、ONNX Runtime 或 InsightFace，也不会自动下载模型。

```bash
python -m pip install -r requirements-dev.txt
python script/test.py                 # Node 管理页 Key 测试，然后运行 Python 单元测试
python script/test.py --integration   # 上述检查通过后，再运行独立 MySQL 集成测试
```

默认入口不需要 Docker。`--integration` 需要可用的 Docker Engine 和 Compose v2，
使用 `compose.test.yml` 启动 `mysql:8.0`。每次运行生成唯一的 Compose 项目名、
`vision_test_` 前缀数据库名和随机密码；MySQL 仅发布到 `127.0.0.1` 的随机端口，
数据目录使用 tmpfs。入口等待健康检查成功后查询实际端口，再向测试子进程注入全部五个
`VISION_TEST_MYSQL_HOST`、`VISION_TEST_MYSQL_PORT`、`VISION_TEST_MYSQL_USER`、
`VISION_TEST_MYSQL_PASSWORD`、`VISION_TEST_MYSQL_DB`。
密码仅通过子进程环境传递，不写入文件或命令参数；子进程输出中的密码会被脱敏。
无论启动、测试失败或中断，入口都会在 `finally` 中对本次唯一项目执行
`docker compose down --volumes`；启动或清理失败均以非零状态退出。

也可以直接运行 pytest（不包含 Node 测试，也不会自动创建数据库）：

```bash
python -m pytest tests/                 # 仅选择单元测试
python -m pytest tests/ --integration   # 仅选择 integration 标记的集成测试
```

测试通过 `VISION_ENV_FILE=''` 禁用项目 `.env` 加载；这与生产默认读取 `.env` 的行为分开。
脚本显式设置该开关，同时移除继承的 `MYSQL_*`、`VISION_TEST_MYSQL_*`、`COMPOSE_*`
和 `PYTEST_ADDOPTS`，防止复用业务连接或改变测试选择。
直接运行集成测试时，必须显式提供上述全部五个 `VISION_TEST_MYSQL_*` 变量，
数据库名必须以 `vision_test_` 开头且是安全 SQL 标识符（字母、数字、下划线）；
缺失或不安全的配置会直接失败，不会回退到生产 `.env` 或 `MYSQL_*`。
集成 fixture 只从建库脚本提取表结构，不导入示例人脸或其他生物识别数据。

图片推理使用每个服务 worker 独立的有界线程池；可配置
`INFERENCE_WORKERS=2`（运行数）、`INFERENCE_MAX_QUEUE=4`（排队数）、
`INFERENCE_QUEUE_TIMEOUT=2`（最大排队等待秒数）。满额返回 429，排队超时返回 503；
请求取消后仍在运行或等待出队的任务继续占用容量，避免输入闭包无界积压。

`.github/workflows/tests.yml` 提供 GitHub Actions 配置，适合将仓库镜像到 GitHub 后使用：
Ubuntu 上准备 Python 3.10、Node.js 22 和 Docker，调用同一 `python script/test.py --integration`。
同一可移植脚本也可由 Gitee 或 Jenkins 的执行节点直接调用。
此处提供的是 CI 配置，尚未执行或验证任何远程 CI。

## API 概览

| 端点 | 功能 |
|------|------|
| `GET /health`、`/health/ready` | 存活 / 就绪探针（免 key） |
| `POST /api/detect/material` | 物料/通用目标检测（YOLO） |
| `POST /api/detect/product` | 成品检测 + OCR |
| `POST /api/v1/faces/recognize` | 1:N 人脸识别 |
| `POST /api/v1/faces/verify` | 1:1 人脸验证 |
| `POST /api/v1/faces/detect` | 仅人脸检测 |
| `POST /api/v1/video/analyze` | 视频流人脸识别（文件/RTSP） |
| `POST /api/v1/faces` | 注册人脸 |
| `GET/PUT/DELETE /api/v1/faces[/{subject}]` | 底库管理 |
| `GET/POST /api/v1/api-keys`、`POST /api/v1/api-keys/{id}/revoke` | API key 管理（列表脱敏） |
| `GET/POST /api/v1/system/device` | GPU/CPU 设备状态与运行时切换（管理员） |
| `GET/POST /api/v1/system/detect-scenario` | 检测场景状态与在线切换（管理员） |

完整 API 参考见 [docs/api.md](docs/api.md)。安全升级说明见 [docs/安全加固与升级说明.md](docs/安全加固与升级说明.md)。

## 模型

| 模型 | 文件 | 用途 | 来源 |
|------|------|------|------|
| YOLOv11n | `yolo11n.pt`（5.4MB） | 通用目标检测 | ModelScope |
| SCRFD | `det_10g.onnx`（16.9MB） | 人脸检测 | HF 镜像 |
| ArcFace | `w600k_r50.onnx`（174MB） | 人脸特征 512 维 | HF 镜像 |
| RapidOCR | wheel 内置（~15MB） | 中英文 OCR | rapidocr-onnxruntime |

> 工厂物料/成品缺陷多不在 COCO 80 类内，本服务支持**多场景检测模型**（`models/scenarios/`）：
> 管理页在线切换默认场景（`POST /api/v1/system/detect-scenario`，无需重启），检测接口也可用
> `scenario` 参数按请求覆盖。可用 `script/prepare_datasets.py` + `script/train_scenario.py`
> 从公开数据集（RPC / NEU-DET / GC10 / DeepPCB）训练演示场景模型（仅演示用，禁商用，见下节）。

## 本地开发（Windows，Python 3.10）

```bash
python -m venv .venv && .venv\Scripts\activate
pip install -r requirements.txt
# insightface 无官方 Windows wheel，需预编译版（详见 docs/troubleshooting.md）
pip install --no-deps https://hf-mirror.com/MonsterMMORPG/SECourses_Premium_Flash_Attention/resolve/main/insightface-0.7.3-cp310-cp310-win_amd64.whl
pip uninstall -y opencv-python
pip install --no-deps numpy==1.26.4 opencv-python-headless==4.10.0.84
cp .env.example .env   # 改 MYSQL_*
uvicorn app.main:app --reload --port 5001
# 或一键启动: powershell -ExecutionPolicy Bypass -File script\start.ps1
```

## 与 nexus 项目对接

nexus-erp / nexus-school 通过 `ruoyi-common-cv` 公共模块调用本服务（V5 阶段）：
- 人脸 → `http://<host>:5001/api/v1/faces/*`
- 物料/成品/OCR → `http://<host>:5001/api/detect/*`
- `subject` 约定：nexus-erp 用工号（`EMP-1001`），nexus-school 用学号（`STU-2024001`）

## 文档

- [操作手册](docs/操作手册.md) — 管理员与日常操作指引
- [GPU 部署与场景训练操作手册](docs/GPU部署与场景训练操作手册.md) — Docker GPU 部署 / 场景模型训练与切换 / 验证与排障
- [设计文档](docs/设计文档.md) — 架构决策、数据库、完成情况
- [场景模型切换开发计划](docs/场景模型切换开发计划.md) — 多场景切换功能的设计与逐任务实施记录
- [API 文档](docs/api.md) — 端点 / 参数 / 响应
- [部署文档](docs/deploy.md) — Docker / 生产 / 回滚
- [排障手册](docs/troubleshooting.md) — 本地开发踩坑记录

## 界面截图

### 人脸底库（管理页）

![人脸底库](docs/screenshots/人脸底库.png)

### 检测调试（物料/成品/人脸/视频四合一）

![检测调试](docs/screenshots/检测调试.png)

### 视频流人脸识别

![视频人脸识别](docs/screenshots/视频人脸识别.png)

### API Keys 管理

![API Keys 管理](docs/screenshots/Key管理.png)

### 场景模型识别效果

金属表面缺陷（`defect_metal` 场景，生长斑/斑块等 10 类）：

![金属缺陷检测](docs/screenshots/defect_metal.png)

PCB 电路板缺陷（`defect_pcb` 场景，9 处缺陷全检出：短路/开路/毛刺/鼠咬/针孔/残铜）：

![PCB缺陷检测](docs/screenshots/defect_pcb.png)

零售商品核对（`material_retail` 场景，200 类中文 SKU 名 + OCR 标签识别）：

![零售商品识别](docs/screenshots/material_retail.png)

## License

本项目基于 [MIT 协议](LICENSE) 开源。