swaggylei/dataset-difficulty-skill

Skill de Dificuldade de Conjunto de Dados

Produza uma prioridade de dificuldade reprodutível e independente de modelo para um conjunto de dados de classificação de imagens. Use embeddings CLIP quando disponíveis, mas mantenha cada métrica bruta e componente visível. Nunca apresente a pontuação final como uma precisão prevista ou como substituto para validação downstream.

Quando Usar

Use este Skill quando o usuário quiser:

• auditar um conjunto de dados de classificação de imagens antes do treinamento;
• encontrar amostras corrompidas, duplicadas, sem rótulo, com rótulo conflitante ou outliers estatísticos;
• comparar dificuldade relativa Fácil/Médio/Difícil;
• criar manifestos de Treino/Val/Treino estratificados por classe e dificuldade;
• obter relatórios legíveis por máquina e revisáveis por humanos.

Não use para detecção de objetos, segmentação, análise de vídeo ou ajuste fino de um classificador.

Verifique as Entradas Primeiro

1. Confirme que o diretório do conjunto de dados existe.
2. Determine o formato: pasta-por-classe, CSV ou JSON.
3. Para CSV/JSON, confirme o arquivo de rótulos e as colunas relevantes de caminho/rótulo.
4. Se for necessário agrupamento seguro contra vazamento, confirme o nome da coluna opcional group_id.
5. Selecione um diretório de saída fora da árvore de dados.
6. Nunca modifique ou exclua imagens ou rótulos originais.
7. Não baixe pesos CLIP a menos que o usuário autorize explicitamente.

Layout de pasta suportado:

dataset/
  gato/
    imagem-1.jpg
  cachorro/
    imagem-2.png

Exemplos de CSV e JSON e substituições de colunas estão em referencias/configuracao.md.

Execute a Análise

A árvore de origem é diretamente executável:

python scripts/analyze_dataset.py DATA_ROOT \
  --output DIRETORIO_SAIDA \
  --config configs/default.yaml

Com um arquivo de rótulos:

python scripts/analyze_dataset.py DATA_ROOT \
  --labels rotulos.csv \
  --format csv \
  --output DIRETORIO_SAIDA

Com grupos seguros contra vazamento:

python scripts/analyze_dataset.py DATA_ROOT \
  --labels rotulos.csv \
  --format csv \
  --group-column group_id \
  --output DIRETORIO_SAIDA

Análise offline sem CLIP:

python scripts/analyze_dataset.py DATA_ROOT \
  --output DIRETORIO_SAIDA \
  --no-semantic

CLIP é apenas local por padrão. Se o usuário autorizar explicitamente o download do modelo e o uso de rede:

python scripts/analyze_dataset.py DATA_ROOT \
  --output DIRETORIO_SAIDA \
  --semantic-backend clip \
  --allow-model-download

Execute python scripts/analyze_dataset.py --help para todas as substituições.

Interprete Nesta Ordem

1. Leia summary.json primeiro.
2. Trate corrupt_image, empty_label e conflicting_label como achados de integridade de dados.
3. Revise grupos duplicados e quase duplicados.
4. Revise outliers de qualidade separadamente da dificuldade.
5. Compare acessibilidade visual, complexidade visual descritiva, componentes semânticos brutos, pesos e valores de contribuição.
6. Interprete Fácil/Médio/Difícil apenas entre amostras pontuadas não anômalas.
7. Verifique diagnósticos e avisos de divisão antes de usar o manifesto.

Relate os componentes que geram um resultado. Por exemplo: "Difícil porque a amostra está longe do seu centróide de classe e instável sob aumento de dados; sua qualidade de imagem em si é normal." Não diga "o modelo falhará" ou "esta amostra tem baixa precisão."

Se os campos semânticos forem nulos, informe que o CLIP estava indisponível ou desabilitado. Não infira ou invente embeddings. Não trate baixa qualidade como dificuldade semântica. Não mescle rótulos de anomalia em Fácil/Médio/Difícil.

Anomalias apenas estatísticas e imagens de baixa qualidade, mas legíveis, são suaves por padrão: preserve sua flag de anomalia, mas as mantenha na pontuação e divisão como Estatisticamente_Incomum ou Sinalizado_por_Qualidade. Apenas anomalias de integridade fortes, como dados corrompidos, com rótulo conflitante, duplicados ou subdimensionados, permanecem excluídos por padrão. Não descreva todo outlier estatístico ou de qualidade como dados inválidos.

Para reivindicações de validação reais, inspecione summary.json["provenance"], summary.json["dataset"] e summary.json["semantic_runtime"]. Verifique o commit Git registrado, estado sujo, comando, caminho de configuração, fonte do modelo, lote, contagens de cache, falhas e dispositivo antes de reivindicar reprodutibilidade.

Raridade de rótulo é uma estatística independente do conjunto de dados com peso zero e contribuição zero. Entropia de imagem e complexidade de frequência são complexidade visual descritiva, não evidência de que uma amostra é mais difícil. Quando difficulty_scope=visual_only, avise explicitamente que a prioridade carece de evidência semântica CLIP.

Leia summary.json["semantic_runtime"] e summary.json["performance"] para obter dispositivo real, tamanho do lote, acertos/falhas de cache, falhas, tempos de estágio e memória máxima CUDA. Não relate esses campos, a menos que venham de uma execução real.

Leia:

• referencias/metricas.md para fórmulas e limites;
• referencias/configuracao.md para cada seção de configuração, esquema de entrada e substituição de CLI;
• referencias/saidas.md para contratos de artefatos e colunas.

Verifique

Use o ambiente do projeto que possui as dependências necessárias:

python -c "import cv2, numpy, pandas, sklearn, matplotlib, yaml, torch, transformers"
python -m pytest -v

Para uma execução real, confirme que samples.csv, summary.json, report.html, hard_samples.png, anomaly_samples.png, split_manifest.csv e split_summary.json existem. Verifique se summary.json não contém tokens NaN ou Infinity.

Segurança e Escopo

• Todas as escritas da análise vão para os diretórios explícitos de saída e cache.
• Os caminhos de saída e cache devem estar fora da árvore do conjunto de dados de entrada.
• As entradas de cache de características são indexadas pelo hash de conteúdo da imagem e pela assinatura do modelo.
• Métricas ausentes permanecem nulas; os componentes disponíveis são reponderados e a cobertura é relatada.
• A pontuação final é uma prioridade relativa, não uma probabilidade calibrada.
• O equilíbrio de classe e a estratificação por dificuldade são aproximados para estratos pequenos; relate avisos de divisão.