图片—文本数据清洗：完整操作与指标手册

1. 工具范围和运行环境

本工具处理本地图片与可选文本，完成导入、规范化测量、分布统计、分辨率/质量筛选、去重和独立导出。源文件不修改、不删除。保留/拒绝/重复/错误的判断通过输出清单表达。

Python 3.10+；Windows 与 Linux；基础处理不需要 GPU。先下载仓库，以下以安装目录为例：

D:\projects\multimodal_training

Windows 首次安装需要建立 .venv，完成后进入项目目录使用：

cd D:\projects\multimodal_training
.\.venv\Scripts\python.exe -m image_cleaner --help

新机器首次安装：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

Linux 对应安装与命令前缀：

python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m image_cleaner --help

下文 Windows 命令均在项目根目录运行。Linux 将前缀改为 .venv/bin/python 并使用相应路径即可。每次筛选使用新的输出目录。

2. 输入方式

2.1 文件夹：适合直接批量导入

D:\datasets\images\
  animals\001.jpg
  animals\001.txt
  charts\002.png
  charts\002.txt

递归发现 .jpg/.jpeg/.png/.webp/.bmp/.tif/.tiff/.gif/.avif。图片有同名 UTF-8 .txt 时加 --sidecar-text，否则只导入图片。默认不跟随目录符号链接；扩展名发现列表与实际可解码格式不同，具体解码能力取决于 Pillow。

2.2 JSONL：适合图文配对与多机迁移

每行至少一个字符串 path，可以附带 text、id、metadata：

{"id":"original-001","path":"animals/001.jpg","text":"一只猫坐在窗边。","metadata":{"source":"dataset-a"}}
{"id":"original-002","path":"charts/002.png","text":"一个展示月份销量的柱状图。"}

相对路径以 --root 为基准；省略时以输入 JSONL 所在目录为基准。原始 ID 保存为 source_id，其他额外字段归入 metadata。同一图片允许多条不同文本记录。跨节点推荐相对路径；绝对路径不受 --root 重映射。

.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\pairs.jsonl" --root "D:\datasets\images" --output runs/pairs_statistics --config configs/statistics_only.json --workers 8

格式错误的输入 JSONL、非字符串文本或无法读取的 sidecar 会使导入报错；单张图片缺失或损坏在分析阶段记录为错误。工具不直接下载 URL 或读取压缩包内的图片。

3. 推荐流程：先统计，再筛选，再导出

3.1 全量分布统计

.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\images" --output runs/statistics --config configs/statistics_only.json --workers 8 --sidecar-text

只处理图片且没有文本时移除 --sidecar-text。统计配置关闭尺寸/质量/文本可选阈值和去重，成功处理的静态图片全部保留；损坏、超过容量限制、动画/多页等仍作为错误记录。

查看报告：

Start-Process -FilePath "runs/statistics/curated/report.html"

report.json 适合程序读取，report.html 包含无外部依赖的分布图。先检查分辨率、宽高比、噪声与清晰度分布，再确定规则。

3.2 保留 256p 及以上的图片

.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_256p --resolution 256p

256p 的定义是 min(width, height) >= 256，表示短边大于或等于 256 像素，256 本身保留。它不表示缩放图片，与 min_short_edge=256 的尺寸边界相同。

其他选择：

# 仅保留 256×256。
.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_square --resolution 256x256

# 仅保留宽 384、高 256。
.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_landscape --resolution 384x256

# 改为短边大于或等于 512。
.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/only_512p --resolution 512p

# 关闭分辨率条件。
.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/all_resolutions --resolution any

尺寸以 EXIF 方向校正后的宽高为准：编码为 256×384、EXIF 要求旋转 90° 的图片会以 384×256 判断。色彩转换不改变尺寸；导出缩放发生在筛选之后。

filter 等价于 merge，始终从分析分片里的全部记录重新判定，不能把它的 --shards 指向上一轮 curated 目录。即使第一轮某图片被阈值或去重排除，分析结果仍在分片中，可以再次参与筛选。原图不会被重新解码；物理导出仍需要原图存在。

3.3 分辨率与其他筛选一起执行

使用配置文件可同时加入宽高比、质量、文本条件或去重：

.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/256p_deduplicated --config configs/audit.json --resolution 256p

上例额外开启去重；符合尺寸的重复记录仍会进入 duplicate.jsonl。如果只希望剔除短边小于 256 的图片，沿用统计配置或指定 --config configs/above_256p.json，其去重关闭。

配置优先级：未传 --config 时继承分析时的完整配置；传了 --config 时从该 JSON 和代码默认值构造新配置，不是对原配置做部分补丁；--resolution 最后覆盖分辨率字段。所有启用规则取交集。若同时设置 min_short_edge=512 与 resolution=256p，最终仍要求短边至少 512；如需允许所有大于或等于 256 的尺寸，先关闭更严格的其他尺寸规则。

阈值修改和精确分辨率筛选可以复用分析结果。reject_animated/max_decode_pixels/metric_patch_size/alpha_background/convert_icc/text_unicode_form 属于测量与预处理设置，改变这些设置需要重新分析。

3.4 导出标准化图片与文本

.\.venv\Scripts\python.exe -m image_cleaner export --curated runs/only_256p --output runs/export_256p --workers 8

只导出 kept.jsonl 中的记录，默认 PNG、RGB、保留已匹配尺寸，不做裁剪或放大。文件放在 images 子目录，exported.jsonl 的 path 为导出目录下的相对路径。导出会校验源文件 SHA-256；源文件在分析后发生变化会记录失败。

export_max_edge 如被启用，可能改变筛选后图片尺寸；需要导出文件仍满足筛选条件时保持 export_max_edge=null。例如 1024×512 符合 256p 及以上，但若导出最长边限制为 384，则会缩成 384×192，输出不再满足短边至少 256 的条件。

3.5 一键流程

已经明确目标时可以直接执行：

.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\images" --output runs/direct_256p --config configs/above_256p.json --workers 8 --export

也可以在 run 或 analyze 上直接传 --resolution；推荐第一次先完成全量统计。

3.6 宽高比桶筛选

比例始终为 EXIF 方向校正后的 宽:高。八个固定桶为 1:1,2:3,3:2,3:4,4:3,9:16,16:9,21:9。竖图与横图分别选择，例如选择 2:3 不会自动选择 3:2。

# 在项目根目录执行。先运行 3.1 的统计任务，再用缓存分片筛选。
# 严格多选：实际尺寸必须与任意一个选中桶完全同比分配。
.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_strict --aspect-buckets "1:1,2:3,3:2" --aspect-mode strict

# 宽松全选：5% 偏差，也可以省略 tolerance 参数使用默认值。
.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_loose --aspect-buckets all --aspect-mode loose --aspect-tolerance 0.05

# 更严格的 3% 容差，同时保留短边 >=256 的图片。
.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_3percent_256 --resolution 256p --aspect-buckets "3:4,4:3,9:16,16:9" --aspect-mode loose --aspect-tolerance 0.03

# 覆盖已有配置、关闭桶条件。其他筛选条件继续生效。
.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_disabled --aspect-buckets none

# 从文件夹直接运行，支持多进程。
.\.venv\Scripts\python.exe -m image_cleaner run --input "D:\datasets\images" --output runs/aspect_run --workers 8 --aspect-buckets all --aspect-mode loose

# 使用示例配置。示例关闭去重以便单独观察桶筛选效果。
.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/statistics/shards --output runs/aspect_config --config configs/aspect_loose.json

每次重筛选使用一个新的输出目录。filter 读取全部分析记录，包括此前被规则拒绝的图片；因此既能收紧也能放宽条件，不需要再次解码。解码失败的记录仍归入错误。

三个参数均支持 analyze、filter/merge、run。显式命令行参数优先于配置；未传参数保留配置值。没有传 --config 的 filter 继承分析分片配置；传入配置文件则按该文件及 Config 默认值构建整套筛选规则。

设实际比例 r=width/height，目标桶比例 b。严格模式使用整数交叉相乘：例如 2:3 要求 width×3 == height×2。宽松模式要求 δ=max(r/b,b/r)-1 <= aspect_tolerance，包含边界。实现使用精确分数比较。例如选 1:1、偏差 5% 时，1050×1000 和 1000×1050 均通过，1051×1000 不通过。此对称定义下允许区间为 [b/1.05, b×1.05]，并非普通的 [b×0.95,b×1.05]。

任意一个选中桶匹配即可通过。如果匹配多个桶，则只分配给偏差最小的桶；同偏差按上述固定八桶顺序选取，因此每张图片只计数一次。重复选择会合并。all 仍会过滤超出所有桶范围的图片。桶条件与分辨率、min_aspect_ratio/max_aspect_ratio、质量、文本条件取交集；不会裁剪或缩放图片。

配置文件新增字段示例：

{
  "aspect_buckets": ["1:1", "2:3", "3:2"],
  "aspect_mode": "loose",
  "aspect_tolerance": 0.05
}

aspect_buckets 也接受 "all"、"none" 或 null。多机仍使用第 6 节的同一 manifest 和 rank/world-size 流程；所有节点分析配置一致，收集全部分片后统一执行上面的 filter 命令，桶筛选无需各节点读取源图片。

4. 各环节指标和判定规则

4.1 导入、解码和容量检查

4.2 标准化

标准化属于数据规范化，未实现模型训练的 dropout/weight decay，也不会执行默认去噪或锐化。16 位/浮点图片最终转为 8 位 RGB，本工具主要面向常规网页图像。

4.3 分布统计、分辨率和宽高比

分辨率筛选不匹配时，原因是 resolution_mismatch。min_short_edge=256 与 resolution=256p 均包含 256，因此 255 不合格，256 和 257 合格。resolution_filter.mode=short_edge_gte 与 comparison=">=" 在报告中记录这一判定；WxH 仍为精确宽高匹配。

每个分布提供有效数量、缺失数量、最小值、最大值、均值、总体标准差、p1/p5/p25/p50/p75/p95/p99，以及固定桶直方图。桶为左闭右开，最后覆盖到无穷大；直方图是全量精确计数。分位数最多使用固定种子 20,000 条蓄水池样本；更大规模时 quantiles_approximate=true。

before 覆盖成功处理的全部记录，after 覆盖最终保留记录；不代表按独立图片去重后的来源统计。分辨率匹配数另外直接按每条记录统计，避免粗直方图桶无法区分 255/256/257 的问题。

4.4 图片技术质量

默认在四角和中心最多五个原生像素区域测量，区域大小最多 metric_patch_size=256，相同区域去重，各指标取有效区域的中位数。不会先缩图再测量；可能漏掉未采样区域的局部缺陷。

这些是代理指标：拉普拉斯方差可能因噪声升高，纹理会影响噪声估计，规则图案也会产生块效应分数。信噪比的“信号”采用局部亮度标准差，不是真实 SNR，也不是 PSNR。

噪声或对比度接近零时，SNR 返回 null 并写入 snr_proxy_undefined；极小图片部分指标为 null。缺失值不会触发对应质量阈值。报告的 missing 表示未得到指标值，不表示质量合格。

所有质量阈值默认 null（关闭）；先按照片/截图/图表/插画等类型抽查，再设置阈值。修改 metric_patch_size 会改变指标分布，必须重新分析并重新校准。

4.5 文本筛选

例如配置 "forbidden_text_patterns": ["(?i)buy\\s+now", "点击购买"] 可匹配部分广告文本。这是启发式文本规则，不能判断图片与文本是否语义对应。

4.6 去重

质量规则通过后再进行全局去重，以避免不合格图片挤掉合格代表。

pHash 使用相对 AC 系数容差抑制极小系数，与普通 pHash 数值不完全相同。所有近重复复核是启发式，不能代替语义 embedding 去重。

默认 duplicate_scope=image_text：规范化文本也相同才归并，保留同图不同描述/问答；没有文本时按图片归并。image 会忽略文本差异。代表优先级为像素数降序、噪声升序、清晰度降序、清单序号升序，不是人工审美排序。

duplicate.jsonl 给出 duplicate_of/duplicate_kind/duplicate_metrics。近重复记录目前保存 pHash 距离和 RGB RMSE，dHash 与比例条件用于判断但未单独写入距离字段。每个重复直接匹配一个保留代表，不通过无限传递链扩大分组。

4.7 阶段评测指标

令 N 为输入条数、D 为处理成功条数、M 为指定分辨率匹配条数、E 为全部规则通过条数、U 为重复条数、K 为最终保留条数：

分母为零时比率为 null。比率是 0–1 的数值；乘 100 得百分比。每次完整输出满足 N=K+rejected_count+U+error_count。关闭去重时 U=0。

这些指标衡量清洗流程和数据组成，不是模型性能或人工标注准确率。若要评估误删/漏删，按图片类型和规则分层抽取人工审核样本，统计“被拒绝但实际可用”的比例和“保留但实际不合格”的比例。后续训练收益需要固定训练预算、随机种子与验证集做对照实验。

4.8 宽高比桶筛选评测指标

打开输出目录的 report.html 查看新增宽高比桶部分；report.json 提供机器可读指标，kept.jsonl、rejected.jsonl 等提供逐条结果。

上述逐条字段针对成功解码记录；错误记录可能没有尺寸与桶字段。counts_before 总和等于独立桶匹配数（条件启用时），counts_after 总和等于最终保留数。选中但没有图片的桶也输出 0；关闭条件时桶计数字典为空。质量评测可同时检查桶通过率、各桶覆盖量、最终保留率，并人工抽查 rejected 中临界偏差图片；各桶不执行均衡采样或配额。

5. 配置文件和参数

项目已有：

以下为可自定义的完整字段表，数值是默认值，不是推荐质量阈值：

{
  "resolution": null,
  "min_short_edge": null,
  "max_long_edge": null,
  "min_pixels": null,
  "max_pixels": null,
  "min_aspect_ratio": null,
  "aspect_buckets": null,
  "aspect_mode": "strict",
  "aspect_tolerance": 0.05,
  "max_aspect_ratio": null,
  "min_blur_score": null,
  "max_noise_sigma": null,
  "min_snr_proxy_db": null,
  "max_blockiness": null,
  "min_text_chars": null,
  "max_text_chars": null,
  "forbidden_text_patterns": [],
  "reject_animated": true,
  "max_decode_pixels": 100000000,
  "metric_patch_size": 256,
  "alpha_background": [255, 255, 255],
  "convert_icc": true,
  "text_unicode_form": "NFC",
  "deduplicate": true,
  "near_deduplicate": true,
  "duplicate_scope": "image_text",
  "phash_distance": 4,
  "dhash_distance": 4,
  "near_rgb_rmse": 8.0,
  "near_aspect_log_tolerance": 0.03,
  "export_max_edge": null,
  "export_format": "png",
  "export_jpeg_quality": 95
}

export_format 可选 png/jpeg；JPEG export_jpeg_quality 为 1–100，采用无色度子采样，仍是有损输出。图片规范化不会自动统一为方形，固定裁剪和张量归一化由训练数据加载器执行。

resolution 支持 256p（短边>=256）、256x256（精确宽高）等正整数格式；大小写与首尾空白会规范化，256×256 也接受。any/none/null 关闭分辨率条件。无后缀的 256、0p、负数、逗号多个值都非法；多目标请分别筛选到不同输出目录。

各子命令参数：

workers 默认 min(8,CPU数量)。配置未知字段、非法类型、范围错误会报错；各子命令的 --help 可查看在线说明。

6. 多机分片流程

先创建全局固定清单：

.\.venv\Scripts\python.exe -m image_cleaner prepare --input "D:\datasets\images" --manifest runs/distributed/input.jsonl --sidecar-text

将 input.jsonl、input.jsonl.meta.json、相同代码和配置分发到节点。每台机器都必须能访问对应原图，可以使用不同本地根目录。

分别在两台机器执行：

# 节点 0
.\.venv\Scripts\python.exe -m image_cleaner analyze --manifest runs/distributed/input.jsonl --root "D:\node0\images" --output runs/distributed/shards --config configs/statistics_only.json --workers 8 --world-size 2 --rank 0

# 节点 1
.\.venv\Scripts\python.exe -m image_cleaner analyze --manifest runs/distributed/input.jsonl --root "E:\node1\images" --output runs/distributed/shards --config configs/statistics_only.json --workers 8 --world-size 2 --rank 1

每条清单按 seq % world_size 分配。每个节点本地写不同 rank 的 SQLite，任务退出后收集全部 shard-*.sqlite 到协调节点同一目录；不用让不同机器写同一个 SQLite。

协调节点先汇总统计，然后按分辨率条件筛选：

.\.venv\Scripts\python.exe -m image_cleaner merge --shards runs/distributed/shards --output runs/distributed/statistics
.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/distributed/shards --output runs/distributed/only_256p --resolution 256p

若希望跨分片去重，在第二条命令增加 --config configs/audit.json。合并会验证全部 rank 完整、清单/配置/软件版本一致、序号不重复。筛选结果与使用同一清单的单机处理一致，去重代表顺序不依赖 worker 完成顺序。

这是静态分片处理，没有自动节点调度或故障迁移。分析并行，最终筛选和全局去重由一个协调节点完成；数据和索引落磁盘，没有百万级运行性能保证。大图处理的解码内存与图片尺寸有关，可降低 workers 或最大解码像素限制。

7. 输出、断点续跑和复核

统计 run 输出清单、分片数据库，以及 curated 报告；filter/merge 的报告直接在其 --output 目录内，不会再额外套一层 curated。

分析续跑：

.\.venv\Scripts\python.exe -m image_cleaner analyze --manifest runs/distributed/input.jsonl --root "D:\node0\images" --output runs/distributed/shards --config configs/statistics_only.json --workers 8 --world-size 2 --rank 0 --resume

导出续跑：

.\.venv\Scripts\python.exe -m image_cleaner export --curated runs/only_256p --output runs/export_256p --workers 8 --resume

run --resume 要求相同输入、配置、分辨率等身份设置；修改规则应使用 filter 输出到新目录。分析每 100 条提交一次；已提交项跳过。清单固定后保持原始文件不变。残留锁文件只能在确认任务退出后移除。

合并/筛选暂不支持中途续跑，失败时用新输出目录重跑，不必重新分析。导出失败会记录清单并返回退出码 1；参数/文件操作等任务错误返回 2；分析阶段的个别图片错误不使整批命令失败，需检查 error_count。

复核建议：检查总数守恒、目标尺寸匹配率、各原因抽样、清洗前后图片类别/宽高比分布变化，以及近重复误合并。为每轮保存独立目录及配置；后续训练/验证划分应让同图及其变体落在同一侧，本工具未自动划分数据集。

8. 验证与功能边界

在全新示例目录运行以下命令，可复现分辨率筛选，不依赖外部数据。示例是六张合成图片和一条损坏图片；256p 及以上预期保留五张（256×256、384×256、256×384、257×384、512×512）、尺寸拒绝一张、错误一张。重复执行请复用已生成输入并为任务更换新的输出目录。旧版筛选报告不会自动改写；重新 filter 到新目录，旧分析分片仍可复用。

.\.venv\Scripts\python.exe examples/make_resolution_demo.py
.\.venv\Scripts\python.exe -m image_cleaner run --input runs/resolution_demo_input --output runs/resolution_demo_statistics --config configs/statistics_only.json --workers 2 --sidecar-text
.\.venv\Scripts\python.exe -m image_cleaner filter --shards runs/resolution_demo_statistics/shards --output runs/resolution_demo_256p --resolution 256p
.\.venv\Scripts\python.exe -m image_cleaner export --curated runs/resolution_demo_256p --output runs/resolution_demo_export --workers 2

单元与集成测试：

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

测试包括包含边界的短边下限、精确宽高、255/256/257 边界、EXIF 后方向、配置覆盖、禁用尺寸条件、规则交集、无原图重复筛选，以及既有多进程/跨分片去重与导出测试。

未包含 CLIP 图文语义对齐、VLM 事实核验、审美模型、OCR、水印分类器、语义 embedding 去重或训练模型性能评测。当前技术质量指标无法判断图片里的描述是否事实正确。