資料集難度分析技能 是做什麼的？
為影像分類資料集產生一個可重現、與模型無關的難度先驗。 在可用時使用 CLIP 嵌入，但保持每個原始指標和元件的可見性。 切勿將最終分數呈現為預測準確度或作為下游驗證的替代品。
使用時機
當使用者想要以下操作時，請使用此技能：
- 在訓練前稽核影像分類資料集；
- 找出損壞、重複、未標記、衝突標籤或統計離群值；
- 比較相對的簡單/中等/困難難度；
- 建立按類別和難度分層的訓練/驗證/測試清單；
- 取得機器可讀與人工可審查的報告。
請勿將其用於物體檢測、分割、影片分析或微調分類器。
先檢查輸入
- 確認資料集目錄存在。
- 確定格式：按類別的資料夾、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視為資料完整性發現。 - 檢查重複組與近似重複。
- 分別檢視品質離群值與難度。
- 比較視覺可及性、描述性視覺複雜度、原始語意元件、權重和貢獻值。
- 僅對非異常的已評分樣本解讀簡單/中等/困難。
- 在使用清單前，檢查切分診斷與警告。
報告驅動結果的元件。例如：「困難因為該樣本遠離其類別中心且在增強下不穩定；其影像品質本身正常。」請勿說「模型將會失敗」或「此樣本準確度低。」
如果語意欄位為空，請說明 CLIP 不可用或已停用。請勿推斷或憑空創造嵌入。請勿將品質不佳視為語意難度。請勿將異常標籤合併到簡單/中等/困難中。
純統計異常與低品質但可讀的影像預設為軟性：保留其異常標誌，但將其保留在評分和切分中，並標記為 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 標記。
安全性與範圍
- 所有分析寫入操作僅會進入明確指定的輸出和快取目錄。
- 輸出和快取路徑必須位於輸入資料集目錄樹之外。
- 特徵快取條目以影像內容雜湊和模型簽章為鍵。
- 缺失的指標保留為空；可用的元件會重新加權並報告覆蓋率。
- 最終分數是相對先驗，而非校準後的機率。
- 對於極小的分層，類別平衡和難度分層是近似值；請報告切分警告。