dezoe/pcb-defect-multi-modal-dataset

印制电路板焊接及装联缺陷多模态数据集

面向 PCB 焊接与装联缺陷识别、资料辅助根因分析和维修建议生成的中文多模态研究数据集。数据集将光学、扫描声学显微（SAM）和 X 射线等缺陷图像与来源标签、中文任务文本，以及可用的检测测量和试验工况关联，支持视觉语言模型的数据准备、指令微调实验和检索增强问答。

版本 v3 包含 5,000 条图像／缺陷区域样本、15,000 条任务指令，覆盖焊点连接质量、焊料分布与形态、焊接层结构及元件装联位置等方面的 14 类目标缺陷：

另收录 6 条立碑图例，描述两端器件一端明显竖起的现象，作为附加类别计入上述 5,000 条样本。各类别的样本数量见下文“数据概览”。

快速上手 · 使用手册 · 数据说明 · 离线浏览器 · 许可范围

数据集能做什么

围绕“看见缺陷、结合资料解释、给出排查与维修建议”组织了三类任务，每类各有 5,000 条记录。

维修建议任务是文字任务，images=[]。根因任务组织候选原因与验证步骤，维修任务组织处理建议与复查项目；标注证据等级见数据卡。

有哪些特点

数据集的创新性体现在多种检测模态、实测证据与中文工程任务的联合组织：将“缺陷表现、检测数值、试验背景、原因排查、维修建议”通过样本关联起来，为工业视觉语言模型提供可追溯、可组合的学习与分析材料。

1. 五种检测模态，覆盖表面外观与内部结构。 汇集光学、扫描声学显微（SAM）、X 射线、扫描电子显微（SEM）和金相截面五类图像，将不同检测方式获得的缺陷信息纳入统一分类与任务格式。模型可在同一数据体系中学习焊点外观、内部空洞、焊接层裂纹和微观界面等多种表现，支持按检测模态开展识别、描述和分析研究。

2. 图像与量化测量关联，让工程分析有具体依据。 3,913 条 LED／金属基 PCB 样本关联原始测量表，包括 3,313 张裂纹 SAM 图像和 600 张空洞 X 射线图像。图像可联查相应的裂纹指标或空洞比例，以及焊料、热冲击工况、器件编号和原始 CSV 行。这种组织方式支持将已知测量与工况显式加入输入，研究模型如何结合视觉信息和量化证据生成缺陷描述、解释候选机制并提出验证方法。

3. 同器件关联与多图对照，支持缺陷演化分析。 LED 数据对应 1,444 个可追溯物理器件，保留同器件不同检测阶段的关联及可用的初始 SAM 基线。全库 3,314 条样本带有附加证据图，可将主图、初始对照和案例证据按任务顺序共同输入模型，用于对照描述、退化分析和多图证据整合。器件标识与图像路径使这些关联可以直接查询和复核。

4. 三类关联任务，贯通识别、原因排查与维修建议。 围绕同一批样本组织缺陷描述、资料辅助根因分析、维修建议生成三类任务，共 15,000 条指令。任务通过统一样本标识关联，将缺陷类别与描述、候选原因与验证步骤、处理建议与复检项目组织为相互衔接的学习目标，支持多任务指令微调，以及对识别、证据整合和工程建议生成能力的分别评估。

5. 中文工程语义与原始证据关联，兼顾知识问答和区域分析。 统一 14 类目标缺陷的中文术语，保留来源标签、类别映射、资料引用及适用的区域几何信息。其中 SolDef_AI 的 485 条区域样本来自 311 张父图，可追溯原始多边形与裁剪位置。研究者可据此组织中文工业问答、检索增强生成和区域描述任务，并沿来源记录核查标签与解释依据。

6. 可组合的输入设计与可复现的数据准备。 配套工具支持纯图像类别识别、图像结合已知资料的描述，以及保留附加证据的多图根因任务，并可按任务、划分、模态、类别和尺寸导出子集。导出结果记录选择条件、样本 ID 和文件哈希；像素去重、来源与器件分组、质量字段及技术校验共同支持数据复核，便于比较不同数据配置，并复现实验所用的样本与输入。

数据概览

14 类目标缺陷的标签数量如下。各列按标签出现次数统计，多标签样本分别计入对应类别。

主清单聚焦缺陷样本。完整来源统计、模态说明和类别定义见数据说明。

快速上手

Hugging Face 在线预览与读取

Hugging Face 仓库的 default 配置使用 hf_data/ 中的 Parquet 文件，包含全部 5,000 条主样本，并保留训练 4,804 条、验证 21 条、测试 175 条的原始划分。 image 列内嵌主图原始字节，网页预览和 Python 读取均无需先解压完整数据包。 常用列包括中文标签、描述、检测模态、来源、许可状态，以及带证据限制的根因假设和维修建议。

python3 -m pip install -r requirements-hf.txt

from datasets import load_dataset

dataset = load_dataset("dezoe/pcb-defect-multi-modal-dataset")
sample = dataset["train"][0]
print(sample["labels_zh"], sample["caption_zh"])
image = sample["image"]  # PIL 图像

sample_json 列保存完整原始样本 JSON；其中的测量、区域几何、质量和附加证据记录均保留。 附加证据图片、父图、源测量表和 15,000 条任务指令仍从下述完整数据包获取， 其中的相对路径以解压后的根目录为基准。Parquet 导出沿用原始许可和再分发状态。

维护者可从完整项目目录重新生成这些文件：

python3 scripts/export_huggingface.py

该命令校验样本划分、分组和主图哈希，生成 Parquet 分片与校验清单； 如果 hf_data/ 已存在，请用 --out 指定新目录以保留旧版。 发布预览数据时，同时上传 hf_data/ 和本 README 中的划分配置。

1. 准备数据与环境

已有完整项目目录时，直接在项目根目录操作。若使用压缩包，取得含许可声明的 v3 数据包和对应 manifest，按使用手册中的方法校验后，在压缩包所在目录解压：

mkdir -p pcb_dataset_v3
tar -xzf pcb_solder_multimodal_v3_with_notices.tar.gz -C pcb_dataset_v3
cd pcb_dataset_v3

使用 Python 3.10+。以下命令从包含 data/、scripts/ 和 README.md 的根目录执行：

python3 -m venv .venv
.venv/bin/python -m pip install 'Pillow>=10' 'jsonschema>=4.18'

浏览图片时，直接用浏览器打开 reports/gallery.html，即可按类别、来源和划分筛选，并查看描述、原因假设及维修建议。保留完整目录结构，浏览器需要读取相对路径下的图片。

2. 读取一条样本

使用 .venv/bin/python 或对应虚拟环境的 notebook 运行：

import json
from pathlib import Path
from PIL import Image

root = Path('.')  # 数据集根目录
with (root / 'data/annotations/samples.jsonl').open(encoding='utf-8') as f:
    sample = json.loads(next(f))

with Image.open(root / sample['image']) as image:
    print('图像尺寸：', image.size)

print('缺陷标签：', sample['labels_zh'])
print('检测模态：', sample['source']['modality'])
print('中文描述：', sample['caption_zh'])
print('测量记录：', sample.get('measurements'))
print('可能原因：', sample['root_cause']['possible_causes_zh'])

JSONL 每行是一条 JSON 记录。所有图像路径都相对于数据集根目录；测量字段中的 null 表示该项未记录，与数值零分别处理。

3. 导出训练数据

配套导出脚本只依赖 Python 标准库。下面导出普通光学图像、短边至少 64 像素的训练样本，并使用来源标签作为识别目标：

.venv/bin/python examples/prepare_training_data.py \
  --root . \
  --task image_to_description \
  --split train \
  --modality optical \
  --min-side 64 \
  --description-mode label_only \
  --out work/optical_train.jsonl

v3 会得到 592 条记录，以及同目录的 optical_train.jsonl.manifest.json。label_only 用于类别识别，不将外部测量值写成仅凭图像推断的答案。

如果输入确实包含检测资料，可导出 “SAM 图像＋已知工况／测量 → 描述”任务：

.venv/bin/python examples/prepare_training_data.py \
  --root . \
  --task image_to_description \
  --split train \
  --modality scanning_acoustic_microscopy \
  --description-mode with_context \
  --out work/sam_context_train.jsonl

该示例输出 3,313 条记录，输入显式包含当前阶段的已知资料。任务评估关注模型结合图像和已知测量生成描述的能力。

另外两类任务可直接按任务名导出：

.venv/bin/python examples/prepare_training_data.py \
  --root . --task multimodal_to_root_cause --split train \
  --min-side 64 --out work/root_cause_train.jsonl

.venv/bin/python examples/prepare_training_data.py \
  --root . --task defect_to_repair --split train \
  --out work/repair_train.jsonl

导出文件保留 sample_id、messages 和有序的 images 列表。图像任务的 <image> 占位符与 images 一一对应；根因任务可能包含多图，维修任务使用纯文本输入。导出 JSONL 引用原数据目录中的图片，读取时使用数据集根目录。

脚本负责数据准备，模型训练需要接入所选框架的数据加载器，并按其多模态输入格式适配。重复运行示例时请更换输出路径，脚本不会覆盖已有导出文件。更多筛选、多图处理和评估示例见使用手册。

4. 校验成品数据

.venv/bin/python scripts/validate_dataset.py

正常结果应包含 passed: true、valid_samples: 5000 和 instruction_rows: 15000。校验覆盖文件完整性、去重、关联和分组等技术条件。

常用文件

data/images/                         成品图片
data/annotations/samples.jsonl        样本、标签、来源与证据主清单
data/annotations/train.jsonl          训练样本主清单
data/annotations/validation.jsonl     验证样本主清单
data/annotations/test.jsonl           测试样本主清单
data/annotations/instructions.jsonl   三类任务的完整指令
data/annotations/<任务名>.jsonl        按任务组织的指令
data/parents/                        SolDef 父图
data/led_evidence/                   LED 检测原图与初始对照
data/source_annotations/             原始区域标注与测量表
data/knowledge/                      缺陷分类与中文排查知识
reports/gallery.html                 离线图片浏览器
examples/prepare_training_data.py    训练子集导出工具

任务通过 sample_id 关联主清单中的 id。train.jsonl 等划分文件存放样本记录；三类任务文件各自包含全部划分，使用时需按 split 筛选，配套导出脚本会完成这一步。

任务选择与评估

• —任务目标：中文文本按来源标签、资料和测量信息整理。根因任务评估候选机制与验证步骤，维修任务评估建议与复查方案；逐样本证据和复核状态见数据卡。
• —类别与评测覆盖：数据呈长尾分布，裂纹占主样本约 66.3%。验证集包含 21 条元件偏移样本，测试集覆盖 4 类；指标按实际类别报告，面向其他类别的评估需配置对应测试数据。
• —检测标注与尺寸：检测／分割实验使用具有 geometry 的子集。231 条主图短边小于 64 像素，可按任务需要筛选。
• —输入与答案分离：不要将整个样本 JSON 直接作为模型输入，它可能含标签、目标描述和后续阶段的测量值。研究时序预测时，尤其要排除未来阶段的信息。
• —工程应用：选图阈值服务于数据筛选；产品验收和返修决策需结合适用标准、工艺条件与功能检测。

证据等级、来源映射和分组方法的完整说明见数据卡。

许可与来源

项目原创代码采用 MIT；项目拥有相应权利的原创文档和独立撰写文本采用 CC BY-NC-SA 4.0。第三方图像、标注、测量和文献仍适用原来源条款，具体范围见 LICENSE 和第三方声明。

进一步阅读