yeuimu
0ed5b9d9ff
- config.ini 全局生效，GUI 跟随配置，CLI --mode 参数可临时覆盖 - 必填项检查与首次配置对话框按模式过滤（仅豆包不要求 DeepSeek 配置，反之亦然） - 模板/示例/README 同步更新，新增 2 个配置测试（共 35 个全部通过）
124 lines
5.1 KiB
Markdown
124 lines
5.1 KiB
Markdown
# 商品图合规检测工具
|
||
|
||
同一份 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
|
||
[run]
|
||
mode = cascade # cascade / doubao（仅豆包）/ deepseek（仅 DeepSeek）
|
||
```
|
||
|
||
运行模式：config.ini `[run] mode` 全局生效（GUI 也跟随）；CLI 的 `--mode` 参数可临时覆盖。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── 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 点）。
|