# 零训练图片分类引擎：一体化容器

**Repository Path**: low-code-dev-lab/argus-detect

## Basic Information

- **Project Name**: 零训练图片分类引擎：一体化容器
- **Description**: 零训练图片分类引擎：一体化容器
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Argus Detect

Argus Detect 是一个基于 AnomalyDINO / DINOv2 patch 特征的 CPU 离线少样本图片异常检测服务。应用以“检测场景”为边界：每个场景维护正常参考样本和异常校准样本，校准后对上传图片输出 `normal` 或 `abnormal`，并返回异常分数、当前阈值和分数与阈值的差值。

## 构建与启动

首次构建前准备固定版本的离线模型资产：

```powershell
.\scripts\prepare_vendor.ps1
docker build --tag argus-detect:latest .
docker run --detach `
  --name argus-detect `
  --restart unless-stopped `
  --publish 8000:8000 `
  --mount type=volume,source=argus-data,target=/argus `
  argus-detect:latest
```

macOS / Linux：

```bash
chmod +x scripts/prepare_vendor.sh
./scripts/prepare_vendor.sh
docker build --tag argus-detect:latest .
docker run --detach \
  --name argus-detect \
  --restart unless-stopped \
  --publish 8000:8000 \
  --mount type=volume,source=argus-data,target=/argus \
  argus-detect:latest
```

容器运行时不访问网络。模型、数据库、样本、特征、检测结果和日志统一保存在 `argus-data` named volume 中：

- `/bank/<场景>/normal_reference`：正常参考图片和特征。
- `/bank/<场景>/anomaly_calibration`：异常校准图片和预处理产物。
- `/sample/<场景>/normal`、`/sample/<场景>/abnormal`：检测完成后的图片。
- `/tmp/raw`、`/tmp/processed`：检测过程中的临时文件。
- `/database`：SQLite 数据库及 WAL 文件。
- `/models`：离线模型、权重和缓存。

打开 `http://localhost:8000` 可使用管理控制台。默认管理员密码为 `admin`，可在“系统设置”中修改。

## 二元检测流程

1. 创建一个检测场景，固定拍摄对象、视角、距离和预处理策略。
2. 上传至少 2 张无裂痕的图片，角色为 `normal_reference`，用于构建正常 memory bank。
3. 上传至少 1 张有裂痕的图片，角色为 `anomaly_calibration`，只用于阈值校准，不会进入正常 memory bank。
4. 调用 `/api/calibrations/add`，指定目标正常误报率，轮询 `/api/calibrations/list` 直到任务完成。
5. 调用 `/api/detect` 上传待测图片。服务根据 `anomaly_score > threshold` 生成二元判定，并保存图片和检测记录。

建议正常参考样本覆盖允许的光照、干湿、灰尘、表面纹理和正常接缝变化；异常校准样本覆盖实际裂痕的形态、位置和尺寸。样本或预处理配置变化后，当前校准会变为 `stale`。手动重建样本特征时，系统会复用最近一次校准输入的目标误报率自动重新校准；没有历史校准记录时仍需手动校准。

## API 示例

所有公开接口均为 `POST /api/*`，请求和响应使用 `application/json`，图片通过 `image` 字段传入原始 Base64、Data URL 或 URL 编码后的 Base64。

创建场景：

```bash
curl -X POST http://localhost:8000/api/scenes/add \
  -H 'Content-Type: application/json' \
  -d '{"name":"水泥基座正面"}'
```

上传正常参考样本：

```json
{
  "scene_id": "场景 UUID",
  "role": "normal_reference",
  "image": "<Base64 或 Data URL>",
  "filename": "normal-01.jpg"
}
```

上传异常校准样本时将 `role` 改为 `anomaly_calibration`。阈值校准请求如下：

```bash
curl -X POST http://localhost:8000/api/calibrations/add \
  -H 'Content-Type: application/json' \
  -d '{"scene_id":"场景 UUID","target_false_positive_rate":0.01}'
```

校准任务完成后执行检测：

```json
{
  "scene_id": "场景 UUID",
  "image": "<Base64 或 Data URL>",
  "filename": "query.jpg"
}
```

检测响应包含以下关键字段：

```json
{
  "detection_id": "检测 UUID",
  "scene_id": "场景 UUID",
  "scene_name": "水泥基座正面",
  "verdict": "abnormal",
  "anomaly_score": 0.1834,
  "threshold": 0.142,
  "margin": 0.0414,
  "calibration_id": "校准 UUID",
  "duration_ms": 428.2,
  "timings_ms": {}
}
```

其中 `margin = anomaly_score - threshold`：正数表示超出阈值，负数表示低于阈值。场景列表、校准结果和单次检测响应都会显示当前阈值。

完整接口、数据模型、错误码和验收标准见 [doc/spec.md](doc/spec.md)。

## 本地开发

后端测试使用轻量 FakeBackend，不会下载或加载大模型：

```bash
cd backend
python -m venv .venv
. .venv/bin/activate
pip install -r requirements-dev.txt
pytest
```

启动前端开发服务器：

```bash
cd frontend
npm install
npm run dev
```

## 容器集成与压测

公开 API 集成测试会创建临时场景，验证 OpenAPI 路由、JSON 请求约束、两类样本、样本内容与预处理变体、校准任务、阈值和检测响应，并在结束时清理场景：

```bash
python tests/integration_test.py --base-url http://127.0.0.1:8000
```

在运行中的容器内执行：

```bash
docker exec argus-detect python /opt/argus/tests/integration_test.py
docker exec argus-detect python /opt/argus/tests/load_test.py
```

压测默认在一个场景内准备 10 张正常参考样本和 5 张异常校准样本，完成阈值校准后并发调用二元检测接口，报告判定成功率、异常召回率、吞吐量以及 p50/p95/p99 延迟。

## 许可证

Argus Detect 项目代码采用 [MIT License](LICENSE)。镜像内置的 DINOv2 模型源码和权重遵循其各自的 Apache-2.0 许可；完整版本、来源和校验信息可在控制台“开源许可证”页面查看。