Análise de lacunas do TAO VCN Classify

Você é analista dos resultados de inferência do NVIDIA TAO VCN Classify (Visual Component Net). Sua função é identificar as amostras mais fracas por rótulo de referência, medindo a distância assinada do limiar de decisão na direção errada, para depois destacá-las para aumento ou reclassificação em etapas posteriores.

Esta habilidade é intencionalmente leve. O cabeçalho de classificação do VCN é um limite binário de pontuação única (PASS vs NO_PASS por siamese_score), portanto, a análise é computacional, não investigativa. Todo o cálculo ocorre por meio de uma única invocação direta do Docker contra a imagem `tao_toolkit.data_services ` declarada no arquivo ` versions.yaml ` (resolvida em tempo de execução — consulte Configuração). O ponto de entrada do contêiner aceita ` [substituições do Hydra...]`; passamos ` gap_analysis vcn_aoi key=value …`. Cada substituição é um simples par chave=valor do Hydra que substitui seletivamente o esquema GapAnalysisConfig do script (os padrões estão embutidos no contêiner; verifique com docker run ... gap_analysis vcn_aoi --cfg=job). (Não há a palavra-chave dataset dentro do contêiner — esse é o prefixo “pillar” do lançador TAO e é omitido aqui.) Você não precisa de análise delegada, auditorias de imagem em múltiplas fases ou agrupamento por tipo de componente — o VCN não expõe essas dimensões. Visualize apenas um pequeno conjunto de amostras fracas representativas para qualificar as lacunas após o retorno do contêiner.

A interface da CLI pode variar entre as compilações de contêineres de serviços de dados. Se uma invocação de `gap_analysis vcn_aoi ` falhar na análise de argumentos, examine o esquema real uma vez por imagem com ` docker run --rm "$DS_IMAGE" gap_analysis vcn_aoi --cfg=job e reconcilie quaisquer chaves renomeadas (por exemplo, inference_csv vs. inference_results_dir, output_dir vs. results_dir) antes de tentar novamente. O nome do arquivo Parquet de saída é kpi_gaps.parquet.

Entradas

1. Diretório de resultados do experimento — contém o arquivo inference/inference.csv da inferência do TAO VCN Classify. Colunas obrigatórias: input_path, object_name, label, siamese_score. Passe o diretório (por exemplo, inference/latest/), e não o arquivo CSV — o contêiner lê o arquivo inference_results_dir/inference.csv.
2. Diretório de código/configuração de treinamento — contém o arquivo YAML de treinamento do VCN. O contêiner lê dataset.classify.input_map (lista de condições de iluminação) e dataset.classify.image_ext a partir dele para expandir cada amostra fraca em uma linha por condição de iluminação.
3. Diretório do conjunto de dados — a raiz da imagem é anexada ao caminho relativo input_path de cada linha (kpi_media_path).
4. Substituições de esquema — min_recall, top_k_per_label e, opcionalmente, um limite fixo são passados como substituições do Hydra (padrões: min_recall=1,0, top_k_per_label=50, threshold=-1,0, o que significa varredura). top_k_per_label deve ser um número inteiro positivo — omitir esse parâmetro coloca o contêiner no modo “filtro abaixo do limiar”, o que, com min_recall=1,0, retorna apenas classificações errôneas do tipo PASS e zero linhas do tipo NO_PASS. Consulte Armadilhas comuns.

Configuração

A varredura de limiar, a classificação de vulnerabilidades e a expansão por iluminação são executadas dentro da imagem tao_toolkit.data_services declarada no arquivo versions.yaml. Resolva a URI específica uma vez no início da execução; em seguida, confirme se o Docker, o kit de ferramentas de contêineres da NVIDIA e uma GPU estão presentes e certifique-se de que a imagem esteja armazenada em cache:

# Resolver tao_toolkit.data_services → URI concreta nvcr.io/... a partir do arquivo versions.yaml
DS_IMAGE=$(python3 -c "import yaml,os; print(yaml.safe_load(open(os.environ['TAO_SKILL_BANK_PATH']+'/versions.yaml'))['images']['tao_toolkit']['data_services'])")
echo "DS_IMAGE=$DS_IMAGE"

docker info > /dev/null && echo "OK: docker"
nvidia-smi > /dev/null && echo "OK: GPU"
docker image inspect "$DS_IMAGE" > /dev/null \
  || docker pull "$DS_IMAGE"

TAO_SKILL_BANK_PATH geralmente é exportado pelo banco de habilidades instalado. Se não estiver definido, aponte-o para a raiz do repositório do banco de habilidades antes da resolução. É necessária uma GPU; interromper o processo logo no início em um host sem GPU evita um erro confuso mais tarde.

Três regras de configuração são fundamentais e fáceis de errar:

• Montagem de caminho — todos os caminhos do host que o contêiner lê ou grava (inference.csv, YAML de treinamento, raiz da imagem do conjunto de dados, diretório de saída) devem ser montados por bind, o que é mais simples com -v $WORKSPACE:$WORKSPACE -w $WORKSPACE, para que os caminhos absolutos sejam resolvidos de forma idêntica em ambos os lados.
• Não passe --user $(id -u):$(id -g) — isso aciona o erro KeyError: 'getpwuid(): uid not found: ' durante a importação dos transformadores pelo contêiner; em vez disso, o chown retorna o UID do host posteriormente.
• -e é obrigatório, não opcional — as imagens atuais exigem isso e encerram com ValueError: A subtarefa vcn_aoi requer o seguinte argumento: -e/--experiment_spec_file antes de analisar as substituições da CLI.

Consulte references/container-setup.md para obter o padrão completo de montagem de caminhos, a justificativa para--user/chown e o comando chown do Alpine, orientações sobre o uso de múltiplos --v e detalhes sobre a exigência de -e .

Método

Toda a tarefa consiste em uma única invocação do `docker run`, seguida por uma breve verificação visual pontual. O contêiner executa as etapas 1 a 4 internamente (varredura de limiares, pontuação de vulnerabilidades, seleção dos K principais, expansão por iluminação). Você realiza a etapa 5 (verificação visual pontual) diretamente com a ferramenta Read.

Etapas 1 a 4 — Execute o contêiner

$DOCKER gap_analysis vcn_aoi \
    inference_results_dir=/inference// \
    train_config=/train.yaml \
    kpi_media_path= \
    results_dir= \
    top_k_per_label=50

Sempre passe o parâmetro top_k_per_label. Esse é o argumento que muda o contêiner do filtro padrão “amostras abaixo do limite” para o ranking adequado top-K-per-label . Com min_recall=1.0, o limiar é, por definição, igual ou inferior a todas as pontuações NO_PASS; portanto, o filtro “abaixo do limiar” retorna APENAS linhas PASS classificadas incorretamente e zero linhas NO_PASS — o que é inútil como fila de aumento. Com top_k_per_label definido como um número inteiro positivo (seja na especificação ou como uma substituição do Hydra), o contêiner calcula a fraqueza assinada em relação ao limiar para cada linha e apresenta as K mais fracas por rótulo de verdade fundamental, que é a saída classificada por rótulo consumida pelas etapas posteriores.

Lê o arquivo inference.csv, varre todos os valores únicos de siamese_score mais um valor logo abaixo do mínimo, mantém os candidatos com recall da classe NO_PASS ≥ min_recall (com tolerância de 1e-12 ) e, em seguida, seleciona o limiar com o melhor F1 (desempate: precisão e, em seguida, valor do limiar). Para cada linha, calcula a fraqueza assinada a partir desse limiar (positiva = classificação incorreta, negativa = correta, magnitude = margem). Classifica por fraqueza em ordem decrescente e seleciona os top_k_per_label principais por rótulo de referência; em seguida, expande cada linha fraca em uma linha por condição de iluminação usando dataset.classify.input_map e dataset.classify.image_ext do YAML de treinamento.

Se nenhum limiar candidato atender à meta de recall, o contêiner sai com valor diferente de zero e grava o arquivo unreachable_kpi.txt no diretório results_dir, explicando qual recall o modelo pode realmente atingir. Nesse caso, interrompa a análise após a chamada do Docker, redija um relatório de uma seção explicando que o modelo é fundamentalmente incapaz de atingir o KPI em qualquer ponto de operação e recomende retreinamento ou reetiquetamento — pule a verificação visual aleatória.

O contêiner grava no diretório results_dir:

Imprima o resumo da saída padrão do contêiner (limite escolhido, contagem de linhas mantidas, detalhamento por rótulo) na sua própria saída padrão para que o gancho de verificação do script possa verificar a saída gerada pela execução.

Etapa 5 — Verificação visual pontual (pequena, fixa)

Pule esta etapa se o arquivo unreachable_kpi.txt existir. Caso contrário, use a ferramenta Read para visualizar as 5 amostras PASS mais fracas e as 5 amostras NO_PASS mais fracas do arquivo kpi_gaps.parquet (deduplicadas para uma linha por amostra, usando o caminho de arquivo FIRST-lighting), classifique cada uma como exatamente uma das seguintes categorias: rotulagem incorreta / caso limite / qualidade dos dados / sistemática e copie cada imagem visualizada (redimensionada para 128×128 se o PIL estiver disponível; caso contrário, basta copiar) para /rca_images/. Essa é a única inspeção de imagens necessária — não visualize dezenas de imagens, não execute agrupamento por modo de falha nem audite imagens de referência (o VCN não possui imagens de referência).

Consulte references/visual-spot-check.md para obter a ordem exata de seleção de amostras, a regra de deduplicação por iluminação, a definição completa de cada categoria de veredicto e os detalhes da cópia de imagens.

Chamada da referência

Cole e edite o espaço de trabalho, os quatro caminhos e os dois parâmetros numéricos; isso executa o processo de ponta a ponta. Capture a saída padrão (stdout) para que o gancho de verificação de script veja as contagens de linhas.

WORKSPACE=           # montado de forma idêntica dentro do contêiner
EXP_DIR=     # contém inference/inference.csv e train.yaml; deve estar dentro de $WORKSPACE
DATASET_ROOT=         # raiz das imagens para as entradas do caminho de entrada do arquivo inference.csv; deve estar dentro de $WORKSPACE
MIN_RECALL=1.0                       # padrão de zero erros; reduza se o KPI for menos rigoroso
TOP_K=50                             # orçamento de aumento por rótulo
OUT="$EXP_DIR/rca_results/$(date +%Y-%m-%d_%H%M%S)"
SPEC="$OUT/vcn_aoi_spec.yaml"
IMG=$(python3 -c "import yaml,os; print(yaml.safe_load(open(os.environ['TAO_SKILL_BANK_PATH']+'/versions.yaml'))['images']['tao_toolkit']['data_services'])")

mkdir -p "$OUT"

# Grave a especificação da análise de lacunas para esta execução
cat > "$SPEC" <<EOF
min_recall: $MIN_RECALL
top_k_per_label: $TOP_K
EOF

docker run --gpus all --rm --ipc=host \
    -v "$WORKSPACE:$WORKSPACE" -w "$WORKSPACE" \
    "$IMG" gap_analysis vcn_aoi \
    -e "$SPEC" \
    inference_results_dir="$EXP_DIR/inference/latest/" \
    train_config="$EXP_DIR/train.yaml" \
    kpi_media_path="$DATASET_ROOT" \
    results_dir="$OUT"

# O contêiner grava como root com a opção --user desativada; reatribua a propriedade ao UID do host, se necessário.
docker run --rm -v "$WORKSPACE:/w" alpine chown -R "$(id -u):$(id -g)" "/w/$(realpath --relative-to="$WORKSPACE" "$OUT")"

# Saída de verificação para que o hook de verificação de script veja valores reais
python3 - "$OUT" << 'PYEOF'
import json, os, sys
out = sys.argv[1]
unreachable = os.path.join(out, "unreachable_kpi.txt")
if os.path.isfile(unreachable):
    print("KPI INACESSÍVEL — consulte", unreachable)
    sys.exit(0)
with open(os.path.join(out, "threshold.txt")) as f:
    print("limite:", f.read().strip())
with open(os.path.join(out, "metrics.json")) as f:
    m = json.load(f)
print(f"precision={m['precision']:.4f} recall={m['recall']:.4f} f1={m['f1']:.4f}")
import pandas as pd
df = pd.read_parquet(os.path.join(out, "kpi_gaps.parquet"))
print(f"kpi_gaps.parquet: rows={len(df)}, cols={list(df.columns)}")
print(df['label'].value_counts())
PYEOF

Saídas

Grave tudo em uma pasta com data e hora no diretório de resultados do experimento. As saídas do contêiner vão diretamente para lá; a verificação visual grava em rca_images/; qualquer gancho de empacotamento em tempo de execução pode adicionar artefatos de captura de sessão/configuração após o arquivo RCA_Report.md ser gravado.

/rca_results/AAAA-MM-DD_HHMMSS/
├── RCA_Report.md              # Relatório completo de análise de lacunas (você o escreve)
├── kpi_gaps.parquet           # Contêiner: os K mais fracos por rótulo, expandidos por iluminação
├── threshold.txt              # Contêiner: limiar de decisão escolhido (único número real)
├── metrics.json               # Contêiner: matriz de confusão + estatísticas de distribuição por rótulo
├── weak_samples_breakdown.txt # Contêiner: contagem por rótulo / amostras mal classificadas / contagens marginais
├── unreachable_kpi.txt        # Contêiner: SOMENTE quando nenhum limiar atinge o min_recall
├── rca_images/                # Você: miniaturas das 10 amostras fracas visualizadas
├── rca_config/                # Copiado automaticamente pelo hook
└── session log/artifacts      # Opcional, captura de pacotes dependente do tempo de execução

No início da execução, obtenha o carimbo de data/hora real executando ` date +%Y-%m-%d_%H%M%S ` no Bash. NÃO codifique manualmente nem adivinhe. Se o usuário especificar um caminho de saída personalizado, use-o, mas mantenha a mesma estrutura interna.

Armadilhas comuns

O modo de falha de maior consequência é esquecer o `top_k_per_label` quando` min_recall=1.0`: nessa taxa de recall, o limiar escolhido fica igual ou abaixo de todas as pontuações NO_PASS; portanto, sem top_k_per_label, o contêiner recorre a um filtro de “amostras abaixo do limiar” que retorna APENAS linhas PASS classificadas incorretamente e zero linhas NO_PASS, interrompendo a fila de aumento. Sempre inclua um top_k_per_label positivo explícito (padrão 50) na especificação ou como uma substituição do Hydra.

Consulte references/pitfalls.md para obter a lista de verificação completa, que abrange: esquecimento do `top_k_per_label`; passar o parâmetro `--user`; chamar apenas com substituições do Hydra (sem `-e `); arquivo de especificação fora do `$WORKSPACE`; arquivo de especificação com sentinelas `???` não resolvidas; imagem não baixada / tag incorreta; incompatibilidade de caminho de montagem; arquivo unreachable_kpi.txt gravado; arquivo inference.csv sem as colunas obrigatórias; YAML de treinamento sem dataset.classify.input_map ou image_ext; kpi_media_path não correspondendo aos prefixos de input_path; e nenhuma GPU detectada de dentro do contêiner.

Estrutura do Relatório

Escreva o arquivo RCA_Report.md como uma análise computacional concisa (1.000–1.800 palavras) das lacunas — a profundidade vem de números precisos e de uma lista clara de ações, não de narrativa. O modelo completo do relatório (7 seções: Veredicto, Seleção de Limiares, Distribuição de Pontos Fracos, Amostras Mais Fracas Top-K, Verificação Visual Pontual, Discriminação por Rótulo, Ações Recomendadas — com a matriz de confusão e os layouts das tabelas) está em references/output-template.md. Quando o arquivo unreachable_kpi.txt existir, substitua as seções 3 a 6 por uma única seção curta citando o conteúdo desse arquivo e resuma a seção 7 a uma única recomendação: retreinar ou reclassificar.

Ordem de execução

1. Resolva DS_IMAGE a partir do arquivo versions.yaml (images.tao_toolkit.data_services); em seguida, execute docker info, nvidia-smi e docker image inspect "$DS_IMAGE" (baixando a imagem caso esteja ausente) uma vez para confirmar o ambiente. Aborta com uma mensagem clara se houver alguma falha.
2. Execute ` date +%Y-%m-%d_%H%M%S ` para obter o carimbo de data/hora; crie ` /rca_results/` e `/`.
3. Grave o arquivo `vcn_aoi_spec.yaml` no diretório com o carimbo de data/hora, preenchendo os campos ` min_recall ` e `top_k_per_label`. Mantenha-o no diretório `$WORKSPACE` para que o caminho `-e ` seja resolvido dentro do contêiner.
4. Execute docker run … "$DS_IMAGE" gap_analysis vcn_aoi -e vcn_aoi_spec.yaml inference_results_dir=… train_config=… kpi_media_path=… output_dir=…. O contêiner grava os arquivos kpi_gaps.parquet, threshold.txt, metrics.json e weak_samples_breakdown.txt no diretório results_dir. Imprima o limiar escolhido e as contagens de linhas mantidas na saída padrão (stdout) para que o gancho de verificação do script possa conferir a saída gerada pela execução.
5. Se o arquivo unreachable_kpi.txt existir, pule a Etapa 6 e gere o relatório resumido. Caso contrário, continue.
6. Selecione 10 amostras fracas (as 5 mais fracas com PASS + as 5 mais fracas com NO_PASS) do arquivo kpi_gaps.parquet, visualize cada imagem de teste com o comando Read, classifique-as e copie cada uma para a pasta rca_images/.
7. Grave o RCA_Report.md por último — gravá-lo aciona o gancho de empacotamento, que copia os logs da sessão e a configuração da habilidade junto com ele.