数据集难度分析技能 是做什么的？
为图像分类数据集生成一个可复现、与模型无关的难度先验估计。 在CLIP嵌入可用时使用，但保持每个原始指标和组件可见。 切勿将最终得分呈现为预测准确率或下游验证的替代品。
何时使用
当用户希望执行以下操作时使用此技能：
- 在训练前审计图像分类数据集；
- 查找损坏、重复、未标记、冲突标签或统计离群值；
- 比较相对Easy/Medium/Hard难度；
- 创建按类别和难度分层的训练/验证/测试清单；
- 生成机器可读和人工可审查的报告。
不要将其用于目标检测、分割、视频分析或微调分类器。
首先检查输入
- 确认数据集目录存在。
- 确定格式：按类别文件夹、CSV或JSON。
- 对于CSV/JSON，确认标签文件以及相关的路径/标签列。
- 如果需要泄漏安全分组，确认可选的
group_id列名。 - 选择数据集目录之外的输出目录。
- 切勿修改或删除原始图像或标签。
- 除非用户明确授权，否则不要下载CLIP权重。
支持的文件夹布局：
dataset/
cat/
image-1.jpg
dog/
image-2.png
CSV和JSON示例及列覆盖详见 references/configuration.md。
运行分析
源代码目录可以直接执行：
python scripts/analyze_dataset.py DATA_ROOT \
--output OUTPUT_DIR \
--config configs/default.yaml
使用标签文件：
python scripts/analyze_dataset.py DATA_ROOT \
--labels labels.csv \
--format csv \
--output OUTPUT_DIR
使用泄漏安全分组：
python scripts/analyze_dataset.py DATA_ROOT \
--labels labels.csv \
--format csv \
--group-column group_id \
--output OUTPUT_DIR
不使用CLIP的离线分析：
python scripts/analyze_dataset.py DATA_ROOT \
--output OUTPUT_DIR \
--no-semantic
CLIP默认仅在本地使用。如果用户明确授权模型下载和网络使用：
python scripts/analyze_dataset.py DATA_ROOT \
--output OUTPUT_DIR \
--semantic-backend clip \
--allow-model-download
运行python scripts/analyze_dataset.py --help查看所有覆盖选项。
按此顺序解读
- 首先读取
summary.json。 - 将
corrupt_image、empty_label和conflicting_label作为数据完整性发现处理。 - 审查重复组和近似重复项。
- 将质量离群值与难度分开审查。
- 比较视觉可及性、描述性视觉复杂度、原始语义组件、权重和贡献值。
- 仅对非异常评分样本解读Easy/Medium/Hard。
- 在使用清单之前检查拆分诊断和警告。
报告驱动结果的组件。例如：“困难因为样本远离其类别质心且在增强下不稳定；其图像质量本身正常。”不要说“模型将失败”或“此样本准确率低”。
如果语义字段为空，则说明CLIP不可用或已禁用。不要推断或编造嵌入。不要将低质量视为语义难度。不要将异常标签合并到Easy/Medium/Hard中。
仅统计异常和低质量但可读的图像默认被视为软异常：保留其异常标志，但在评分和拆分中将其保留为Statistically_Unusual或Quality_Flagged。只有硬完整性异常（如损坏、冲突标签、重复或尺寸过小的数据）默认被排除。不要将每个统计或质量离群值描述为无效数据。
对于真正的验证声明，请检查summary.json["provenance"]、summary.json["dataset"]和summary.json["semantic_runtime"]。在声称可复现之前，检查记录的Git提交、脏状态、命令、配置路径、模型来源、批次、缓存计数、失败、设备。
标签稀有度是一个独立的数据集统计量，权重和贡献均为零。图像熵和频率复杂度是描述性视觉复杂度，并非样本更难的证据。当difficulty_scope=visual_only时，明确警告先验缺乏CLIP语义证据。
读取summary.json["semantic_runtime"]和summary.json["performance"]获取实际设备、批次大小、缓存命中/未命中、失败、阶段时序和CUDA峰值内存。除非这些字段来自实际运行，否则不要报告它们。
阅读：
- references/metrics.md了解公式和限制；
- references/configuration.md了解每个配置部分、输入模式和CLI覆盖；
- references/outputs.md了解工件和列约定。
验证
使用具有所需依赖项的项目环境：
python -c "import cv2, numpy, pandas, sklearn, matplotlib, yaml, torch, transformers"
python -m pytest -v
对于实际运行，确认samples.csv、summary.json、report.html、hard_samples.png、anomaly_samples.png、split_manifest.csv和split_summary.json存在。验证summary.json中不包含NaN或Infinity标记。
安全性和范围
- 所有分析写入都进入显式的输出和缓存目录。
- 输出和缓存路径必须在输入数据集树之外。
- 特征缓存条目以图像内容哈希和模型签名为键。
- 缺失指标保持为null；可用组件被重新加权并报告覆盖率。
- 最终得分是相对先验，而非校准概率。
- 类别平衡和难度分层对于微小分层是近似的；报告拆分警告。