swaggylei/dataset-difficulty-skill

데이터셋 난이도 스킬

이미지 분류 데이터셋에 대해 재현 가능하고 모델에 독립적인 난이도 사전 정보를 생성합니다. 가능한 경우 CLIP 임베딩을 사용하지만 모든 원시 지표와 구성 요소는 투명하게 유지합니다. 최종 점수를 예측 정확도로 제시하거나 다운스트림 검증을 대체하는 용도로 절대 사용하지 마십시오.

사용 시기

사용자가 다음을 원할 때 이 스킬을 사용하십시오:

• 학습 전 이미지 분류 데이터셋 감사
• 손상, 중복, 레이블 없음, 레이블 충돌 또는 통계적 이상치 탐지
• 상대적 Easy/Medium/Hard 난이도 비교
• 클래스 및 난이도별 계층화된 Train/Val/Test 매니페스트 생성
• 기계 판독 가능 및 사람 검토 가능 보고서 생성

객체 탐지, 세그멘테이션, 비디오 분석 또는 분류기 미세 조정에는 사용하지 마십시오.

먼저 입력 확인

1. 데이터셋 디렉토리가 존재하는지 확인합니다.
2. 형식을 결정합니다: folder-per-class, CSV 또는 JSON.
3. CSV/JSON의 경우 레이블 파일과 관련 경로/레이블 열을 확인합니다.
4. 누출 방지 그룹화가 필요한 경우 선택적 group_id 열 이름을 확인합니다.
5. 데이터셋 트리 외부에 출력 디렉토리를 선택합니다.
6. 원본 이미지나 레이블을 절대 수정하거나 삭제하지 마십시오.
7. 사용자가 명시적으로 승인하지 않는 한 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를 실행하십시오.

다음 순서로 해석

1. 먼저 summary.json을 읽습니다.
2. corrupt_image, empty_label, conflicting_label을 데이터 무결성 발견 사항으로 처리합니다.
3. 중복 그룹 및 근사 중복을 검토합니다.
4. 품질 이상치를 난이도와 별도로 검토합니다.
5. 시각적 접근성, 설명적 시각적 복잡성, 원시 의미 구성 요소, 가중치 및 기여 값을 비교합니다.
6. 이상치가 아닌 점수가 매겨진 샘플에서만 Easy/Medium/Hard를 해석합니다.
7. 매니페스트를 사용하기 전에 분할 진단 및 경고를 확인합니다.

결과를 유발한 구성 요소를 보고합니다. 예: "샘플이 클래스 중심에서 멀고 증강 시 불안정하기 때문에 Hard입니다. 이미지 품질 자체는 정상입니다." "모델이 실패할 것입니다" 또는 "이 샘플의 정확도가 낮습니다"라고 말하지 마십시오.

의미 필드가 null이면 CLIP을 사용할 수 없거나 비활성화되었음을 명시하십시오. 임베딩을 추론하거나 생성하지 마십시오. 낮은 품질을 의미적 난이도로 처리하지 마십시오. 이상치 레이블을 Easy/Medium/Hard에 병합하지 마십시오.

통계적 이상치 및 저품질이지만 읽을 수 있는 이미지는 기본적으로 소프트(soft)합니다: 이상치 플래그를 유지하되 Statistically_Unusual 또는 Quality_Flagged로 점수 계산 및 분할에 유지합니다. 손상, 레이블 충돌, 중복 또는 너무 작은 데이터와 같은 하드 무결성 이상치만 기본적으로 제외됩니다. 모든 통계적 또는 품질 이상치를 유효하지 않은 데이터로 설명하지 마십시오.

실제 검증 주장의 경우 summary.json["provenance"], summary.json["dataset"], summary.json["semantic_runtime"]을 검사하십시오. 재현 가능성을 주장하기 전에 기록된 Git 커밋, 더티 상태, 명령, 구성 경로, 모델 소스, 배치, 캐시 수, 실패 횟수 및 장치를 확인하십시오.

레이블 희소성은 가중치와 기여도가 0인 독립적인 데이터셋 통계량입니다. 이미지 엔트로피 및 주파수 복잡성은 설명적 시각적 복잡성일 뿐 샘플이 더 어렵다는 증거가 아닙니다. difficulty_scope=visual_only인 경우 사전 정보에 CLIP 의미 증거가 부족함을 명시적으로 경고하십시오.

실제 장치, 배치 크기, 캐시 적중/실패, 실패, 단계 타이밍 및 CUDA 최대 메모리에 대해서는 summary.json["semantic_runtime"] 및 summary.json["performance"]를 읽으십시오. 실제 실행에서 얻지 않은 경우 해당 필드를 보고하지 마십시오.

참고:

• 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로 유지됩니다. 사용 가능한 구성 요소는 재가중되며 적용 범위가 보고됩니다.
• 최종 점수는 상대적 사전 정보이며 보정된 확률이 아닙니다.
• 클래스 균형 및 난이도 계층화는 매우 작은 계층의 경우 근사치입니다. 분할 경고를 보고하십시오.