# batch_image_verify

**Repository Path**: luopub/batch_image_verify

## Basic Information

- **Project Name**: batch_image_verify
- **Description**: 对比检查原始图像和处理后的图像中产品形态是否发生改变
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-15
- **Last Updated**: 2026-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 批量图片核验工具

把「AI 生成使用场景图」批量对照「实物图」检查产品是否被画错（颜色/形状/部件/文字/logo/伪影）。
检查清单源自 gooseworks-ai/goose-skills 的 `verify-product-image` skill。

核验方式：脚本会把「基准实物图 + AI 场景图」拼成一张并排对比图，再发给视觉模型逐项核对——
多图直传在部分本地模型上不可靠（实测 qwen3-vl 双图输入会漏看），拼图是稳定方案。

## 快速开始

目录结构建议：

```
batch/
├── reference/
│   └── product.png          # 实物图（基准）
└── candidates/
    ├── scene-001.png        # AI 场景图
    ├── scene-002.png
    └── ...
```

基准图支持**分号分隔的多个路径**（每个可以是图片文件或文件夹，文件夹自动取第一张图），
例如 `--reference "图1.png;图2.png"` 或 `--reference "实物图1文件夹;实物图2.png"`。
交互输入时直接回车（留空）会跳到下一项。

多张实物图时：**每张候选图都要经过每一张实物图的筛查**，最终结论为——**任意一张实物图通过即 pass**，
没有 pass 但有 needs-human 则 needs-human，全部实物图都判 fail 才 fail；通过/失败图片统一归档到
**同一个输出文件夹**的 passed / failed / needs-human 中，报告里会标注每个基准各自的结论。

交互输入实物图时：**每个文件地址占一行，回车换行继续输入下一个，输入完按一次空回车结束**，
自动进入下一步。候选图和输出仍填文件夹地址。

候选图同样支持**分号分隔的多个图片文件地址**，例如
`--candidates "场景1.jpg;场景2.jpg;场景3.png"`；也可以继续用文件夹或通配符。

运行（默认本地 Ollama 视觉模型，无需 API key）：

```bash
python batch_verify.py --reference batch/reference/product.png \
    --candidates batch/candidates/ --output results/
```

也可指定多个目录/通配符：

```bash
python batch_verify.py --reference ref.png --candidates "scenes/*.png" "more/*.jpg" --output results/
```

## 模型选择

本机 Ollama 已装：`qwen2.5vl:3b`、`qwen3-vl:2b/4b/8b`。

- 质量优先：`--model qwen3-vl:8b`（默认）
- 速度优先：`--model qwen2.5vl:3b`

双击 `run-batch.bat` 时可以直接选模型：输入 `1` 用本地 8B（准确），输入 `2` 用本地 3B（快），
输入 `3` 用智谱云端 GLM-4.6V（最准，需要 API key，运行时会提示输入；若系统环境变量
`OPENAI_API_KEY` 已设置则直接使用）。直接回车默认 8B。
命令行方式则用 `--model` 指定，例如 `--model qwen2.5vl:3b`。

使用云端模型（OpenAI 兼容接口）：

```bash
set OPENAI_API_KEY=sk-...
set OPENAI_BASE_URL=https://api.openai.com/v1
python batch_verify.py --reference ref.png --candidates scenes/ --output results/ \
    --provider openai --model gpt-4o
```

## 输出

- `results/<图名>.verification.json` — 每张图的完整核验结果
- `results/report.csv` — 汇总表（Excel 可直接打开）
- `results/report.md` — 汇总报告
- `results/verification.md` — 仿照 verify-product-image 的记录文件
- `results/passed/`、`results/failed/`、`results/needs-human/` — 按结论自动归档的图片副本（原图不动；默认开启，加 `--no-sort` 关闭）

归档时，**fail / needs-human 的副本文件名会追加错误原因**（例如
`Cozy Café Lifestyle_形状数量材质不符.jpg`），方便直接看出问题；通过的图片保持原名。

## 判定规则补充

- 场景图中允许出现其他物品、人物、背景，但**必须包含筛查产品**；产品完全缺失或小到无法辨认判 fail。
- **支持多个产品实例**：场景图中若出现多个筛查产品（多个挂件、多件套、多个包），会逐个识别并全部核对，任何一个实例与实物不符即 fail。
- **多实例颜色/款式可不同**：若画面中出现多个同款产品但颜色/款式不同（如同一产品的多色组合），只要至少一个实例与基准一致、其余实例属于同一产品类型（仅颜色/装饰不同），判 pass。
- **存在即通过**：只要画面中出现至少一个与实物基准一致的筛查产品实例即判 pass，即使有其他颜色/款式实例或其他物品/产品混入也不影响；只有画面中完全没有该产品才判 fail。
- 允许只展示产品的**局部特写/细节图**（材质、缝线、五金、图案等），只要该局部属于筛查产品且与实物对应细节一致。
- **允许额外部件**（额外装饰、配饰、场景物品），也**允许特写/局部图缺失部分部件**；部件数量与实物不一致不作为判错依据（实物图是多件套/多色合集、场景图只展示其中一件时同样正常）。
- **细节/特写图放宽判定**：花朵、五金、材质等局部特写只要颜色/材质/造型明显属于筛查产品即判 pass，不做逐件严格比对；物理专项复查对特写图豁免。
- 文件名含 `close-up` / `detail` / `特写` / `细节` / `局部` / `放大` 的图片会自动走**细节图鉴定流程**（只判断局部是否属于该产品，不检查部件数量、挂环、物理）。
- 文件名不含关键词的图会自动**检测是否为细节图**（画面主体是否为产品局部的特写），检测为细节图同样走鉴定流程；可用 `--no-auto-detail` 关闭自动检测。
- 增加**物理合理性检查**：产品悬浮在空中、无支撑漂浮、穿模、明显违背重力或无法挂住 → fail。
- 默认开启**物理合理性专项复查**：主检查判 pass 的图会先定位产品区域、裁剪放大，再用专门提示词以高分辨率局部图复查物理连接（防止模型把悬浮脑补成“有连接”），查出问题即覆盖为 fail；可用 `--no-physics-audit` 关闭。
- 不再输出逐图 `.verification.json` 文件（报告保留 report.csv / report.md / verification.md）。

## 判定规则

- `pass`：产品与实物一致（光线/背景/角度不同不算错）
- `fail`：部件数量不符、文字乱码、logo 错误，或严重形状/颜色/伪影问题
- `needs-human`：轻微出入或模型拿不准，需要人工复核

## 说明

- 基准图每轮一张；不同产品请分开运行。
- 单张超时默认 240 秒，可在 `--timeout` 调整。
- 视觉模型本身可能误判，高价值图建议抽检或换模型复核。