# 商品图合规检测工具

同一份 17 类违规检测提示词，两级级联调用视觉模型，在控制成本的同时从严检测：

```
全部图片 ──▶ 豆包（火山方舟 Ark）初筛 ──┬─ 判为违规 ──▶ 直接定稿（便宜，拦下大头）
                                        └─ 无违规/违规不明/异常 ──▶ DeepSeek 复检
                                                                     └─ 仍判无违规 ──▶ 追加两票复核（3票取多数）
```

## 输出结构

指定输出目录后，自动建立时间戳文件夹，按分类归档图片，Excel 放在一级目录：

```
<输出目录>/检测结果_20260902_151603/
├── 违规检测结果_20260902_151604.xlsx      # 检测明细 + 统计汇总
├── 12. 侵权 - 除人物外的其他侵权/  *.jpg
├── 13. 侵权 - 人物相关（…）/
├── 无违规/  ……
```

## 使用方式

### exe 版（dist/ 目录）

- `商品图合规检测工具.exe`：双击打开图形界面（零配置：选图片文件夹和输出目录即可）。
- `商品图合规检测工具CLI.exe`：命令行版，用法同下方 CLI。
- 首次运行会在 exe 同目录生成 `config.ini` 模板；GUI 会弹窗引导填写
  豆包 API Key / 接入点、DeepSeek API Key / 模型，四项填完保存即可。
- 内置提示词（打包进 exe）；界面上也可另选 txt 覆盖。

### 源码运行（Python ≥3.10）

```bash
uv run violation-detector-gui                 # GUI
uv run violation-detector tests -o output     # CLI
# 或免安装：
PYTHONPATH=src python -m violation_detector.gui
PYTHONPATH=src python -m violation_detector tests -o output
```

### 重新打包

```bash
uv run --with pyinstaller --with aiohttp --with openpyxl \
  pyinstaller --noconfirm --clean --onefile --windowed \
  --name 商品图合规检测工具 --add-data "prompts.txt;." --paths src app_gui.py
uv run --with pyinstaller --with aiohttp --with openpyxl \
  pyinstaller --noconfirm --clean --onefile \
  --name 商品图合规检测工具CLI --add-data "prompts.txt;." --paths src app_cli.py
```

## CLI 用法

```
商品图合规检测工具CLI <图片文件夹> [选项]

  -o, --output DIR     输出目录（默认为图片文件夹）
  --mode               cascade（默认）/ doubao / deepseek
  --no-verify          跳过 DeepSeek 无违规两票复核
  --prompt FILE        自定义提示词（默认内置 prompts.txt）
  --workers-ark/--workers-ds/--max-tokens   调优项（默认即可）
```

## 配置（config.ini，自动生成）

缺失必填项时：GUI 弹窗引导填写；CLI 打印缺哪些项后退出。也可用环境变量
`ARK_API_KEY` / `ARK_MODEL_ID` / `DEEPSEEK_API_KEY` / `DEEPSEEK_MODEL` 覆盖。

```ini
[ark]
api_key = ...
model_id = ep-xxxx
[deepseek]
api_key = sk-...
model = deepseek-v4-flash-vision-exp
max_tokens = 5000
```

## 项目结构

```
├── src/violation_detector/
│   ├── config.py     # 配置（自动生成 ini、缺项检测、冻结环境路径）
│   ├── providers.py  # 豆包/DeepSeek 异步客户端，统一结果结构
│   ├── pipeline.py   # 级联调度、断点缓存(runs/)、两票复核、成本汇总
│   ├── report.py     # 时间戳输出目录、分类归档、Excel 报表
│   ├── cli.py / gui.py
├── app_gui.py / app_cli.py   # 启动器 + PyInstaller 入口
├── prompts.txt       # 内置提示词
├── runs/             # 分阶段缓存（断点续跑；删缓存即全量重跑）
├── dist/             # 打包产物 exe
└── legacy/           # 早期脚本与实验数据
```

## 日志与排错

所有运行过程写入日志文件（exe 同目录 / 源码项目根目录下的 `logs/violation_detector_日期.log`）：

- 文件记录 DEBUG 级全量：运行配置、缓存命中、每次请求的重试与 HTTP 响应体、异常完整堆栈；
- 控制台/GUI 只显示 INFO 级简洁信息，异常时同样附带完整 traceback；
- GUI 右下角「打开日志」按钮直达日志文件；CLI 出错时会在结尾打印日志文件路径。

```bash
# 跑测试（33 个单元测试，无需网络与 API Key）
uv run --with pytest --with aiohttp --with openpyxl --no-project \
  env PYTHONPATH=src pytest tests -q
```

## 检测规则与已知特性

- 分类按提示词 17 类标准输出唯一分类，自动归一化写法差异。
- DeepSeek：temperature=0 + JSON 模式、max_tokens=5000（全量梯度实测零失败最小档）。
- 无违规两票复核：3 票一致才稳；2:1 保留多数但标记“人工复核”；分歧从严取违规类。
- 边界图存在运行间抖动（同为 temp=0 重测全量一致率约 68%），与 max_tokens 无关；
  报表“票型/复核”列已标出分歧图，建议人工终审。
- 级联成本：DeepSeek 只处理豆包放行的少数存疑图（单张约 1-1.6 分钱，
  空闲时段半价；高峰=工作日 9-12、14-18 点）。