Habilidade de mineração e incorporação do DEFT

Você é o operador do fluxo de trabalho DEFT de “incorporação e mineração” para a AOI do VCN. Sua função é pegar um arquivo Parquet de imagens-alvo fracas (a saída da análise de lacunas ou do roteamento) e um conjunto de imagens de origem, para então produzir um arquivo Parquet desduplicado de imagens de origem extraídas que se pareçam com as imagens-alvo — prontas para serem utilizadas na próxima rodada de treinamento.

O fluxo de trabalho é fixo e determinístico: incorpore os alvos, incorpore o conjunto de imagens de origem e, em seguida, extraia os vizinhos mais próximos. O arquivo Parquet de saída de cada etapa serve como entrada para a próxima etapa. Não há busca iterativa, nem etapa de agrupamento, nem seleção com intervenção humana — a profundidade vem da escolha do codificador certo e do topn certo, não de uma investigação em várias fases.

A habilidade como um todo é um invólucro simples em torno de três chamadas diretas de `docker run` contra a imagem `tao_toolkit.data_services ` declarada no ` versions.yaml ` (resolvida em tempo de execução — consulte Configuração). O ponto de entrada do contêiner aceita ` -e [substituições do Hydra...] ` — passando `image_embeddings -e …` para embedding e ` tmm nearest_neighbors -e …` para mineração. O sinalizador -e aponta para um arquivo YAML que fornece valores padrão para o esquema da subtarefa; tudo o que vem depois é uma substituição direta do Hydra (chave=valor) que substitui seletivamente campos da especificação a cada execução. (Não há a palavra-chave “dataset” dentro do contêiner — esse é o prefixo “pillar” do lançador TAO e foi omitido aqui.) Baixe a imagem uma vez se ela não estiver em cache: docker pull "$DS_IMAGE" (após resolver $DS_IMAGE conforme a configuração).

As chaves do esquema podem ser renomeadas entre versões do data-services (a skill RCA mudou de `inference_csv` para ` inference_results_dir` e de `output_dir` para `results_dir`). Em caso de dúvida, analise o esquema real uma vez por imagem: docker run --rm "$DS_IMAGE" embedding image_embeddings --cfg=job e ... tmm nearest_neighbors --cfg=job.

Entradas

1. Parquet de destino — a saída da análise de lacunas, normalmente mining_gaps.parquet do tao-route-visual-changenet-samples (ou gaps.parquet do tao-analyze-gaps-visual-changenet, caso o roteamento tenha sido ignorado). Coluna obrigatória: filepath. Se a coluna label também estiver presente, a filtragem com reconhecimento de rótulos durante a mineração estará disponível; caso contrário, a tarefa de mineração ignorará silenciosamente o filtro.
2. Conjunto de origem — um arquivo Parquet com imagens candidatas a serem exploradas, contendo uma coluna filepath. Se o usuário tiver apenas um CSV, converta-o para um Parquet com as mesmas colunas antes da Etapa 2. Para a filtragem com reconhecimento de rótulos, o conjunto também deve conter uma coluna label.
3. Arquivo de especificação de incorporação — um YAML contendo model, model_path, batch_size e (somente quando model_path for um TAO .pth/.ckpt) model_config_path. Reutilizado nas Etapas 1 e 2;input_parquet/output_parquet são fornecidos a cada execução como substituições do Hydra. A mesma especificação DEVE orientar ambas as etapas de embedding — embeddings de codificadores diferentes não são comparáveis, e codificadores incompatíveis são a causa mais comum de relatos do tipo “as imagens extraídas parecem não ter relação”.
4. Arquivo de especificações de mineração — um YAML contendo topn, knn_metric, filter_by_label e (raramente alterados)source_embed_column_name/target_embed_column_name.source_parquet/target_parquet/output_parquet são substituições do Hydra em tempo de execução. As incorporações SigLIP e CLIP devem usar knn_metric: cosine. Quando filter_by_label: true, mas algum dos arquivos Parquet de incorporação não possui uma coluna de rótulo, o contêiner registra um aviso e prossegue sem filtrar.

Configuração

Resolva a URI específica de `tao_toolkit.data_services ` no arquivo ` versions.yaml ` uma única vez no início da execução; em seguida, verifique se o Docker, o kit de ferramentas de contêineres da NVIDIA e uma GPU estão disponíveis antes de prosseguir. É necessária uma GPU tanto para a passagem direta do codificador quanto para a pesquisa k-NN do cuML/cuDF; ambas as etapas falham sem o CUDA.

# 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"

Todos os caminhos do host que o contêiner lê ou grava devem ser montados por bind. A abordagem mais previsível monta a raiz do espaço de trabalho com caminhos idênticos dentro e fora do contêiner e, em seguida, reutiliza um alias $DOCKER para as três invocações:

WORKSPACE=
DOCKER="docker run --gpus all --rm --ipc=host -v $WORKSPACE:$WORKSPACE -w $WORKSPACE $DS_IMAGE"

Não passe --user $(id -u):$(id -g) — isso aciona um KeyError de getpwuid() durante a importação dos transformadores antes mesmo de qualquer trabalho começar. O contêiner é executado como root; o comando chown reverte para o UID do host posteriormente.

Crie os dois arquivos de especificação uma vez por iteração, colocando-os na pasta $WORKSPACE para que o argumento -e seja resolvido em ambos os lados da montagem; os valores específicos de cada execução ficam fora da especificação e são passados como substituições do Hydra. Se o conjunto de dados de origem for um CSV, converta-o para o formato Parquet antecipadamente (preservando o caminho do arquivo e o rótulo, se houver). O arquivo embedding_spec.yaml padrão usa model: SigLIP, model_path: google/siglip-base-patch16-224, batch_size: 64; o arquivo mining_spec.yaml padrão usa topn: 5, knn_metric: cosine, filter_by_label: "false" (entre aspas — o esquema o interpreta como uma string).

Consulte references/setup.md para obter as notas completas sobre o ambiente, o tratamento de TAO_SKILL_BANK_PATH, a justificativa para o mapeamento de caminhos, a solução alternativa para chown no getpwuid, o trecho de código para conversão de CSV para Parquet e os blocos de criação de arquivos de especificação na íntegra.

Método

Três comandos, nessa ordem. O arquivo Parquet de saída de cada comando serve como entrada para o próximo comando. Execute-os como Bash simples; o alias $DOCKER da configuração cuida do contêiner, da GPU e das montagens. Cada invocação segue o mesmo formato: -e para os padrões integrados, seguido de algumas substituições do Hydra para os caminhos específicos da execução.

Etapa 1 — Incorporar as imagens de destino

$DOCKER embedding image_embeddings \
    -e  \
    input_parquet= \
    output_parquet=

Lê a saída da análise de lacunas/roteamento e grava um arquivo Parquet com o caminho do arquivo, a incorporação e quaisquer colunas de metadados extras (por exemplo, label, siamese_score, weakness) transportadas literalmente da entrada. Imprima o esquema de saída (pd.read_parquet(...).columns) no stdout para que o gancho de verificação de script possa confirmar se a coluna de embedding existe.

Se for necessário sobrescrever model / model_path / batch_size para uma execução sem editar a especificação, acrescente-os como sobrescritas do Hydra (por exemplo, model_path=...).

Etapa 2 — Incorporar o conjunto de dados de origem

$DOCKER embedding image_embeddings \
    -e  \
    input_parquet= \
    output_parquet=

O formato do comando é o mesmo da Etapa 1, aplicado ao conjunto de dados de origem. Use o mesmo arquivo embedding_spec.yaml da Etapa 1 e não altere as configurações de model / model_path / batch_size de forma diferente aqui — configurações de codificador incompatíveis entre as duas etapas geram embeddings não comparáveis.

Etapa 3 — Identificação dos vizinhos mais próximos

$DOCKER tmm nearest_neighbors \
    -e  \
    source_parquet= \
    target_parquet= \
    output_parquet=

Para cada embedding de destino, localiza os topn embeddings de origem mais próximos de acordo com a métrica escolhida, elimina duplicatas entre os destinos e grava um arquivo Parquet de coluna única (caminho do arquivo) contendo os caminhos de origem únicos extraídos. O contêiner também gera um arquivo mining_summary.txt ao lado do arquivo Parquet de saída com: contagem de consultas, contagem de vizinhos, duplicatas removidas e (quando a filtragem por rótulo está ativada) contagem de pares mantidos versus descartados. Ajuste `topn`, `knn_metric` ou `filter_by_label` por meio da substituição inline do Hydra durante a varredura (por exemplo, `topn=10`) — não é necessário reescrever a especificação.

Quando filter_by_label=true, mas um dos arquivos Parquet de incorporação não contém a coluna de rótulo, o contêiner registra um aviso e prossegue sem filtrar. Se a saída extraída parecer maior do que o esperado ou contiver pares entre rótulos, verifique o log do Docker em busca desse aviso antes de presumir que a tarefa foi executada corretamente.

Consulte references/reference-invocation.md para obter a receita completa mínima do tipo “copiar e editar” (resolve $DS_IMAGE, escreve ambas as especificações, executa todas as três etapas, altera a propriedade dos arquivos de saída e imprime as contagens de linhas) para ser executada como um único bloco Bash transmitido.

Saídas e relatório

Grave tudo em uma pasta com carimbo de data e hora no diretório da experiência / iteração. Obtenha o carimbo de data e 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 diretamente, mas mantenha o mesmo layout interno. O gancho de empacotamento adiciona automaticamente mining_config/ e claude_session.jsonl quando o Mining_Report.md é gravado.

O arquivo Parquet extraído é o artefato consumido pelo treinamento a jusante. Os dois arquivos Parquet de embedding são intermediários, mas vale a pena mantê-los — eles são reutilizáveis em várias execuções de mineração com o mesmo conjunto de dados de origem e são o único lugar a ser consultado quando um relatório que “parece não estar relacionado” precisa de depuração no nível do codificador.

Consulte references/outputs-and-reporting.md para ver o layout completo do diretório de saída e o modelo literal do Mining_Report.md (Veredicto, Entradas, Consistência do Codificador, Execução da Mineração, Discriminação por Rótulo, Validade da Saída, Ações Recomendadas; mantenha-o entre 600 e 1.200 palavras).

Armadilhas comuns

A falha mais frequente é a incompatibilidade entre os codificadores nas duas etapas de incorporação — a causa mais comum de resultados de mineração inválidos; ambas as etapas devem utilizar o mesmo arquivo embedding_spec.yaml. Outras armadilhas recorrentes: passar --user (o erro KeyError getpwuid ), pular uma etapa de incorporação, uma coluna de rótulo ausente que silencia a ação do filter_by_label=true, arquivos de especificação fora do $WORKSPACE, sentinelas ??? não resolvidas , pontos de verificação do TAO sem model_config_path, conjuntos de dados de origem em CSV alimentados diretamente, incompatibilidades entre caminhos do host/contêiner, ausência de GPU, uma tag de imagem não baixada ou :latest e topn × N_targets ≫ tamanho da fonte (esperado — relate a contagem real extraída).

Consulte references/troubleshooting.md para obter a lista completa de armadilhas com os erros exatos, causas e soluções.

Ordem de execução

1. Resolva DS_IMAGE a partir do arquivo versions.yaml (images.tao_toolkit.data_services) e, em seguida, execute docker info, nvidia-smi e docker image inspect "$DS_IMAGE" (baixando se estiver faltando) uma vez para confirmar o ambiente. Aborte 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 ` /mining_results/` e `/`.
3. Grave os arquivos `embedding_spec.yaml ` e `mining_spec.yaml` no diretório com o carimbo de data/hora, preenchendo a escolha do codificador e os parâmetros de mineração. Mantenha-os em `$WORKSPACE ` para que o caminho `-e` seja resolvido dentro do contêiner.
4. Se o conjunto de dados de origem for um CSV, converta-o primeiro para Parquet (preservando o caminho do arquivo e o rótulo).
5. Execute a Etapa 1 (incorporar destinos) por meio de `docker run … embedding image_embeddings -e embedding_spec.yaml input_parquet=… output_parquet=…`. Imprima a contagem de linhas e colunas do arquivo Parquet de saída no stdout.
6. Execute a Etapa 2 (incorporar o conjunto de dados de origem) com o mesmo arquivo embedding_spec.yaml da Etapa 1. Imprima o número de linhas e colunas do Parquet de saída.
7. Execute a Etapa 3 (mineração de vizinhos mais próximos) por meio de `docker run … tmm nearest_neighbors -e mining_spec.yaml source_parquet=… target_parquet=… output_parquet=…`. Confirme se o arquivo ` mining_summary.txt` foi gravado ao lado do `mined.parquet`.
8. Calcule a divisão por rótulo (Seção 5) unindo o arquivo Parquet de embeddings de destino com a saída extraída no caminho do arquivo, caso ambos contenham rótulos.
9. Grave o Mining_Report.md por último — gravá-lo aciona o gancho de empacotamento, que copia os logs da sessão e a configuração da skill junto com ele.