Spaces:
Running
Running
Download manual/ARCHITECTURE.html from HanWangTJU/NMM-data-preprocess: direct link, hf CLI and curl.
- Browser
- Download file 21.1 kB
-
https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess/resolve/main/manual/ARCHITECTURE.html
- Command line
-
hf download hf://spaces/HanWangTJU/NMM-data-preprocess/manual/ARCHITECTURE.html
-
curl -L -o ARCHITECTURE.html https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess/resolve/main/manual/ARCHITECTURE.html
21.1 kB
| <html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>代码说明 · NMM-data-preprocess</title><link rel="stylesheet" href="../assets/style.css"><script defer src="../assets/app.js"></script></head><body><header class="topbar"><a class="brand" href="../index.html">NMM<span> / </span>data-preprocess</a><nav><a href="https://huggingface.co/spaces/HanWangTJU/NMM-data-preprocess/tree/main">源代码 ↗</a><a href="../downloads/NMM-data-preprocess-0.3.1.zip" download>下载源码 ↓</a></nav></header><div class="manual-layout"><aside class="sidebar"><a href="../index.html">← 返回首页</a><a class="" href="QUICKSTART.html">逐步教程</a><a class="" href="USAGE.html">完整手册</a><a class="" href="PARAMETERS.html">参数参考</a><a class="" href="DEPLOYMENT.html">部署指南</a><a class="active" href="ARCHITECTURE.html">代码说明</a><h2>本页目录</h2><div class="toc"> | |
| <ul> | |
| <li><a href="#1-当前版本与数据流">1. 当前版本与数据流</a></li> | |
| <li><a href="#2-功能矩阵">2. 功能矩阵</a></li> | |
| <li><a href="#3-源码文件说明">3. 源码文件说明</a></li> | |
| <li><a href="#4-记录格式与状态">4. 记录格式与状态</a></li> | |
| <li><a href="#5-为什么统计后能反复筛选">5. 为什么统计后能反复筛选</a></li> | |
| <li><a href="#6-并行去重和内存">6. 并行、去重和内存</a></li> | |
| <li><a href="#7-当前没有覆盖的训练前审核">7. 当前没有覆盖的训练前审核</a></li> | |
| <li><a href="#8-验证与版本">8. 验证与版本</a></li> | |
| </ul> | |
| </div> | |
| </aside><main class="manual"><h1 id="代码结构功能与实现边界">代码结构、功能与实现边界</h1> | |
| <h2 id="1-当前版本与数据流">1. 当前版本与数据流</h2> | |
| <p>当前清洗库版本 0.3.1,面向图片—文本对。0.3.1 修复透明图片导出时 JSON 数组背景色回读的类型问题。主要流程:</p> | |
| <pre><code class="language-text">图片文件夹 / 图文 JSONL | |
| │ prepare:稳定编号、固定清单与 SHA-256 | |
| ▼ | |
| input.jsonl + input.jsonl.meta.json | |
| │ analyze:rank 分片、本机进程池、规范化、测量 | |
| ▼ | |
| 各 rank 的 SQLite + JSONL | |
| │ merge/filter:重算规则、全局去重、流式统计 | |
| ▼ | |
| kept / rejected / duplicate / error + HTML/JSON 报告 | |
| │ export:源哈希校验、输出规范化 RGB | |
| ▼ | |
| 标准化图片 + exported.jsonl → 训练数据加载器 | |
| </code></pre> | |
| <p><code>run</code> 将单机 prepare、analyze、merge 顺序串联,可选 export。静态 Space 仅展示文档与命令,算法在用户机器运行。</p> | |
| <h2 id="2-功能矩阵">2. 功能矩阵</h2> | |
| <table> | |
| <thead> | |
| <tr> | |
| <th>环节</th> | |
| <th>已实现</th> | |
| <th>输出/限制</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td>批量导入</td> | |
| <td>递归图片目录、同名 txt、图文 JSONL</td> | |
| <td>固定清单,路径和原始 ID 可追溯</td> | |
| </tr> | |
| <tr> | |
| <td>解码检查</td> | |
| <td>坏文件、截断、像素容量、动画/多页</td> | |
| <td>单图失败进入 error,不删除源图</td> | |
| </tr> | |
| <tr> | |
| <td>标准化</td> | |
| <td>EXIF、ICC→sRGB、RGB、透明合成、Unicode/空白</td> | |
| <td>无模型推理,无默认裁剪</td> | |
| </tr> | |
| <tr> | |
| <td>尺寸统计</td> | |
| <td>宽高、短/长边、像素、比例、方向分类</td> | |
| <td>全量直方图,最多 20000 样本估计分位数</td> | |
| </tr> | |
| <tr> | |
| <td>尺寸筛选</td> | |
| <td>短边 >=Np、精确 WxH、其他尺寸阈值</td> | |
| <td>条件取交集,包含边界</td> | |
| </tr> | |
| <tr> | |
| <td>宽高比桶</td> | |
| <td>八桶、多选/全选、严格/宽松、可调容差</td> | |
| <td>固定桶,不做桶均衡采样</td> | |
| </tr> | |
| <tr> | |
| <td>技术质量</td> | |
| <td>模糊、噪声、SNR、块效应代理</td> | |
| <td>最多五个原生像素区域,不是人工质量结论</td> | |
| </tr> | |
| <tr> | |
| <td>文本检查</td> | |
| <td>长度、Unicode、广告等正则</td> | |
| <td>不评估图文语义一致性</td> | |
| </tr> | |
| <tr> | |
| <td>精确去重</td> | |
| <td>原字节、规范化像素</td> | |
| <td>跨全部分片全局处理</td> | |
| </tr> | |
| <tr> | |
| <td>近重复</td> | |
| <td>pHash、dHash、比例、RGB RMSE 联合</td> | |
| <td>启发式,不是 embedding 语义去重</td> | |
| </tr> | |
| <tr> | |
| <td>并行/续跑</td> | |
| <td>本机进程池、多机静态 rank、SQLite 检查点</td> | |
| <td>合并由单协调节点,无自动调度</td> | |
| </tr> | |
| <tr> | |
| <td>导出</td> | |
| <td>独立 RGB PNG/JPEG、缩小长边、清单、续跑校验</td> | |
| <td>原图不改动,固定裁剪由训练端完成</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <p>用户提到的“正则化”在此实现中是数据规范化和规则校验;不包含训练损失正则化、数据增强或张量标准化。</p> | |
| <h2 id="3-源码文件说明">3. 源码文件说明</h2> | |
| <table> | |
| <thead> | |
| <tr> | |
| <th>文件</th> | |
| <th>主要职责</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td><code>image_cleaner/cli.py</code></td> | |
| <td>argparse 子命令、CLI 覆盖、run 串联与返回码</td> | |
| </tr> | |
| <tr> | |
| <td><code>image_cleaner/config.py</code></td> | |
| <td>不可变 Config、JSON 加载、字段与数值校验、配置指纹</td> | |
| </tr> | |
| <tr> | |
| <td><code>image_cleaner/io.py</code></td> | |
| <td>目录导入、JSONL、清单身份、原子写入、锁、SQLite、限流进程池</td> | |
| </tr> | |
| <tr> | |
| <td><code>image_cleaner/images.py</code></td> | |
| <td>EXIF/色彩/透明度/文本规范化、单图分析与筛选原因</td> | |
| </tr> | |
| <tr> | |
| <td><code>image_cleaner/aspect.py</code></td> | |
| <td>精确分数比较、对称偏差、确定性桶分配</td> | |
| </tr> | |
| <tr> | |
| <td><code>image_cleaner/metrics.py</code></td> | |
| <td>原生区域质量测量、pHash/dHash、缩略图与 RMSE</td> | |
| </tr> | |
| <tr> | |
| <td><code>image_cleaner/jobs.py</code></td> | |
| <td>分片分析、全局过滤、落盘去重索引、导出与续跑</td> | |
| </tr> | |
| <tr> | |
| <td><code>image_cleaner/stats.py</code></td> | |
| <td>增量统计、蓄水池分位数、内嵌 SVG HTML 报告</td> | |
| </tr> | |
| <tr> | |
| <td><code>tests/test_pipeline.py</code></td> | |
| <td>导入/清洗/去重/导出/分片/续跑/容量等测试</td> | |
| </tr> | |
| <tr> | |
| <td><code>tests/test_aspect.py</code></td> | |
| <td>容差边界、横竖桶、重叠分配、CLI、缓存重筛选</td> | |
| </tr> | |
| <tr> | |
| <td><code>configs/</code></td> | |
| <td>统计、尺寸、桶、去重、生成数据示例配置</td> | |
| </tr> | |
| <tr> | |
| <td><code>examples/</code></td> | |
| <td>生成合成演示样本</td> | |
| </tr> | |
| <tr> | |
| <td><code>docker/Dockerfile</code></td> | |
| <td>CLI 容器部署,不启动 Web 服务</td> | |
| </tr> | |
| <tr> | |
| <td><code>tools/build_space.py</code></td> | |
| <td>文档转换、静态页面、源码 ZIP、发布文件校验清单</td> | |
| </tr> | |
| <tr> | |
| <td><code>tools/publish_space.py</code></td> | |
| <td>从环境变量读取 Token,检查账号并发布白名单文件</td> | |
| </tr> | |
| <tr> | |
| <td><code>web/</code></td> | |
| <td>Space 首页模板、样式与交互脚本</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <p><code>index.html</code>、<code>manual/*.html</code> 与 <code>downloads/*.zip</code> 是发布构建产物。运行结果在 runs,虚拟环境在 .venv,两者不发布。</p> | |
| <h2 id="4-记录格式与状态">4. 记录格式与状态</h2> | |
| <p>外部 JSONL 每条必须有字符串 path;text 为字符串或 null,metadata 为对象。输入 id 会保存为 source_id,程序生成稳定 <code>sample-000000000000</code> 等 ID 与 seq。其他外部字段放入 metadata,避免覆盖计算指标。</p> | |
| <p>分析记录包含源路径、规范化文本、原始/校正宽高、文件/像素哈希、质量指标、预处理元数据、警告和筛选原因。最终状态:</p> | |
| <table> | |
| <thead> | |
| <tr> | |
| <th>状态</th> | |
| <th>含义</th> | |
| </tr> | |
| </thead> | |
| <tbody> | |
| <tr> | |
| <td>kept</td> | |
| <td>所有规则通过,且没有归并到其他代表</td> | |
| </tr> | |
| <tr> | |
| <td>rejected</td> | |
| <td>至少一个尺寸/桶/质量/文本规则不通过</td> | |
| </tr> | |
| <tr> | |
| <td>duplicate</td> | |
| <td>规则通过,但精确或近重复判定归并到代表</td> | |
| </tr> | |
| <tr> | |
| <td>error</td> | |
| <td>无法成功解码、规范化或测量</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <p>最终满足 <code>input_count=kept+rejected+duplicate+error</code>。同一拒绝记录可以有多个原因,原因计数不可当成样本数相加。</p> | |
| <h2 id="5-为什么统计后能反复筛选">5. 为什么统计后能反复筛选</h2> | |
| <p>analyze 保存成功处理的完整指标,即使当时被阈值拒绝也写入 SQLite。filter 从全部记录重新计算规则,而不是仅读取上一次 kept。因此放宽阈值能恢复以前被拒绝的记录,收紧阈值也无需读源图片。</p> | |
| <p>六项测量设置(reject_animated、max_decode_pixels、metric_patch_size、alpha_background、convert_icc、text_unicode_form)不允许在重筛选中改变。变化会使缓存指标不再对应新处理逻辑,需要重新分析。</p> | |
| <h2 id="6-并行去重和内存">6. 并行、去重和内存</h2> | |
| <p>进程池并发队列约为 workers 的两倍,结果逐条写入 SQLite。rank 使用 <code>seq % world_size</code>,每个 rank 写单独数据库。全局 merge 校验完整分片并按稳定优先级处理候选。</p> | |
| <p>精确去重索引基于哈希,近重复使用 pHash 的 r+1 分段索引召回候选,再复核联合条件。索引和排序主要落磁盘,不将全量图片或全量指标载入内存;没有全数据两两比较。</p> | |
| <p>合并批量处理 500 条候选,SQLite 缓存约 32 MiB,分位数抽样上限 20000。图片解码内存仍随原图像素与 workers 增长。大量相似图片、纯色图或高半径设置会增加复核成本,不能据此承诺百万/亿级吞吐量。</p> | |
| <h2 id="7-当前没有覆盖的训练前审核">7. 当前没有覆盖的训练前审核</h2> | |
| <p>当前不包含 OCR、水印/人脸/隐私识别、NSFW/版权判定、CLIP 语义一致性、美学模型、语义 embedding 去重、训练/验证集防泄漏、WebDataset/Parquet 输入、视频/音频、训练采样配额、动态集群调度。</p> | |
| <p>初筛保留仅代表通过已配置规则;训练前仍应按来源、内容类别和任务需求抽查,确认图文对齐及样本可用性。若后续扩展,应保留现有 source_id、稳定清单和每条决策原因便于追溯。</p> | |
| <h2 id="8-验证与版本">8. 验证与版本</h2> | |
| <p>现有 22 项清洗测试覆盖正好 5% 边界、零容差、桶重叠、源文件删除后的缓存筛选、多进程/双分片一致性、去重、多文本、断点续跑、透明图导出与配置回读、导出校验、分辨率包含边界等。发布时另核验文档参数与代码、ZIP 白名单和页面链接。</p> | |
| <p>恢复分析要求软件版本与配置指纹一致。合并旧分片需要同一批分片身份一致且当前代码能够读取其字段;不要混用不同软件版本、不同清单或不同 world-size 的分片。版本号不代表数据清洗标准或模型效果保证。</p></main></div><footer>NMM-data-preprocess · v0.3.1<span>图片文本数据初筛教程</span></footer></body></html> |