Habilidad de análisis de deficiencias de TAO VCN Classify

Eres analista de los resultados de inferencia de NVIDIA TAO VCN Classify (Visual Component Net). Tu trabajo consiste en identificar las muestras más débiles por cada etiqueta de referencia midiendo la distancia con signo desde el umbral de decisión en la dirección errónea, para luego seleccionarlas con vistas a su aumento o reetiquetado posterior.

Esta habilidad está diseñada para ser ligera. El módulo de clasificación de VCN es un límite binario de puntuación única (PASS frente a NO_PASS según siamese_score), por lo que el análisis es computacional, no investigativo. Todo el cálculo se lleva a cabo mediante una única invocación directa de Docker contra la imagen «tao_toolkit.data_services» declarada en «versions.yaml» (resuelta en tiempo de ejecución; véase «Configuración»). El punto de entrada del contenedor toma [anulaciones de Hydra...]; pasamos gap_analysis vcn_aoi clave=valor …. Cada anulación es una simple pareja clave=valor de Hydra que anula selectivamente el esquema GapAnalysisConfig del script (los valores por defecto están integrados en el contenedor; compruébalo con ` docker run ... gap_analysis vcn_aoi --cfg=job`). (No hay ninguna palabra clave «dataset» dentro del contenedor; ese es el prefijo «pillar» del lanzador TAO y aquí se omite). No necesitas análisis delegados, auditorías de imágenes en varias fases ni agrupaciones por tipo de componente: VCN no expone esas dimensiones. Examina solo un pequeño conjunto de muestras débiles representativas para calificar las brechas una vez que el contenedor haya devuelto el resultado.

La interfaz de la CLI puede variar entre las diferentes compilaciones de contenedores de servicios de datos. Si una invocación de `gap_analysis vcn_aoi ` falla al analizar los argumentos, examina el esquema real una vez por imagen con ` docker run --rm "$DS_IMAGE" gap_analysis vcn_aoi --cfg=job y concilia cualquier clave renombrada (p. ej., «inference_csv» frente a «inference_results_dir», «output_dir» frente a «results_dir») antes de volver a intentarlo. El nombre del archivo Parquet de salida es «kpi_gaps.parquet».

Entradas

1. Directorio de resultados del experimento: contiene el archivo `inference/inference.csv ` procedente de la inferencia de TAO VCN Classify. Columnas obligatorias: `input_path`, `object_name`, `label`, `siamese_score`. Pasa el directorio (p. ej., «inference/latest/»), no el archivo CSV: el contenedor lee «inference_results_dir/inference.csv».
2. Directorio de código/configuración de entrenamiento: contiene el archivo YAML de entrenamiento de VCN. El contenedor lee de él dataset.classify.input_map (lista de condiciones de iluminación) y dataset.classify.image_ext para expandir cada muestra débil en una fila por cada condición de iluminación.
3. Directorio del conjunto de datos: la ruta raíz de la imagen se antepone a la ruta relativa input_path de cada fila (kpi_media_path).
4. Modificaciones del esquema: min_recall, top_k_per_label y, opcionalmente, un umbral fijo se pasan como modificaciones de Hydra (valores por defecto: min_recall=1,0; top_k_per_label=50; threshold=-1,0, lo que significa un barrido). top_k_per_label debe ser un entero positivo; si se omite, el contenedor pasa al modo de «filtro por debajo del umbral», lo que con min_recall=1,0 devuelve solo clasificaciones erróneas de tipo PASS y cero filas de tipo NO_PASS. Véase «Errores comunes».

Configuración

El barrido de umbrales, la clasificación de debilidades y la expansión por iluminación se ejecutan dentro de la imagen tao_toolkit.data_services declarada en versions.yaml. Resuelve el URI concreto una vez al inicio de la ejecución; a continuación, confirma que Docker, el kit de herramientas de contenedores de NVIDIA y una GPU estén presentes, y asegúrate de que la imagen esté almacenada en caché:

# Resolver tao_toolkit.data_services → URI concreta nvcr.io/... de 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 suele ser exportada por el banco de habilidades instalado. Si no está configurada, dirígela a la raíz del repositorio del banco de habilidades antes de continuar. Se requiere una GPU; interrumpir el proceso en una fase temprana en un host sin GPU evita un error confuso más adelante.

Hay tres reglas de configuración fundamentales en las que es fácil equivocarse:

• Montaje de rutas: todas las rutas del host que el contenedor lee o escribe (inference.csv, el archivo YAML de entrenamiento, la raíz de la imagen del conjunto de datos, el directorio de salida) deben montarse mediante bind; la forma más sencilla es con -v $WORKSPACE:$WORKSPACE -w $WORKSPACE, de modo que las rutas absolutas se resuelvan de forma idéntica en ambos lados.
• No pases --user $(id -u):$(id -g): provoca un KeyError: «getpwuid(): uid not found: » durante la importación de transformers por parte del contenedor; en su lugar, chown devuelve el UID del host posteriormente.
• -e es obligatorio, no opcional: las imágenes actuales lo exigen estrictamente y se cierran con un ValueError: La subtarea vcn_aoi requiere el siguiente argumento: -e/--experiment_spec_file antes de analizar las modificaciones de la CLI.

Consulte references/container-setup.md para conocer el patrón completo de montaje de rutas, la justificación de--user/chown y el comando chown de Alpine, la guía sobre el uso de múltiples --v y los detalles del requisito -e .

Método

Toda la habilidad consiste en una única invocación de `docker run` seguida de una pequeña comprobación visual puntual. El contenedor realiza los pasos 1 a 4 de forma interna (barrido de umbrales, puntuación de vulnerabilidades, selección de los K principales, expansión por iluminación). Tú te encargas del paso 5 (comprobación visual puntual) directamente con la herramienta Read.

Pasos 1 a 4: ejecutar el contenedor

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

Siempre hay que pasar el parámetro top_k_per_label. Este es el argumento que cambia el contenedor del filtro predeterminado «muestras por debajo del umbral» a una clasificación adecuada de top-K-por-etiqueta . Con min_recall=1,0, el umbral se sitúa, por definición, en o por debajo de cada puntuación NO_PASS, por lo que el filtro «por debajo del umbral» devuelve ÚNICAMENTE filas PASS clasificadas erróneamente y cero filas NO_PASS, lo que lo hace inútil como cola de aumento. Con top_k_per_label establecido en un entero positivo (ya sea en la especificación o como una sobrescritura de Hydra), el contenedor calcula la debilidad con signo respecto al umbral para cada fila y muestra las K más débiles por etiqueta de verdad fundamental, que es la salida clasificada por etiqueta que consumen los pasos posteriores.

Lee el archivo inference.csv, recorre todos los valores únicos de siamese_score más uno justo por debajo del mínimo, conserva los candidatos con una recuperación de la clase NO_PASS ≥ min_recall (con una tolerancia de 1e-12 ) y, a continuación, selecciona el umbral con el mejor F1 (en caso de empate: precisión y, a continuación, valor del umbral). Para cada fila, calcula la debilidad con signo a partir de ese umbral (positiva = clasificación errónea, negativa = correcta, magnitud = margen). Ordena por debilidad en orden descendente y toma los primeros top_k_per_label por cada etiqueta de referencia; a continuación, expande cada fila débil en una fila por cada condición de iluminación utilizando dataset.classify.input_map y dataset.classify.image_ext del archivo YAML de entrenamiento.

Si ningún umbral candidato cumple el objetivo de recuperación, el contenedor sale con un valor distinto de cero y escribe el archivo unreachable_kpi.txt en results_dir, explicando qué nivel de recuperación puede alcanzar realmente el modelo. En ese caso, detén el análisis tras la llamada a Docker, redacta un informe de una sola sección en el que se explique que el modelo es fundamentalmente incapaz de alcanzar el KPI en ningún punto de funcionamiento, y recomienda volver a entrenar o reetiquetar — omite la comprobación visual aleatoria.

El contenedor escribe en results_dir:

Imprime el resumen de la salida estándar del contenedor (umbral elegido, recuento de filas conservadas, desglose por etiqueta) en tu propia salida estándar para que el hook de comprobación de scripts pueda verificar la salida generada por la ejecución.

Paso 5 — Comprobación visual aleatoria (pequeña, fija)

Omite este paso si existe el archivo unreachable_kpi.txt. De lo contrario, utiliza la herramienta «Read» para ver las 5 muestras «PASS» más débiles y las 5 muestras «NO_PASS» más débiles de kpi_gaps.parquet (deduplicadas a una fila por muestra, utilizando la ruta de archivo «FIRST-lighting»), clasifica cada una de ellas exactamente en una de las siguientes categorías: «etiquetada incorrectamente », «caso límite », «calidad de los datos » o «sistemática», y copia cada imagen visualizada (redimensionada a 128×128 si hay PIL disponible; de lo contrario, simplemente cópiala) en /rca_images/. Esta es la única inspección de imágenes necesaria: no revises docenas de imágenes, no realices agrupaciones por modos de fallo ni audites imágenes de referencia (VCN no tiene imágenes de referencia).

Consulte references/visual-spot-check.md para conocer el orden exacto de selección de muestras, la regla de deduplicación por iluminación, la definición completa de cada categoría de veredicto y los detalles sobre la copia de imágenes.

Invocación de referencia

Pega y edita el espacio de trabajo, las cuatro rutas y los dos parámetros numéricos; esto se ejecuta de principio a fin. Captura la salida estándar (stdout) para que el gancho de comprobación del script detecte el recuento de filas.

WORKSPACE=           # montado de forma idéntica dentro del contenedor
EXP_DIR=     # contiene inference/inference.csv y train.yaml; debe estar dentro de $WORKSPACE
DATASET_ROOT=         # raíz de imágenes para las entradas de input_path en inference.csv; debe estar dentro de $WORKSPACE
MIN_RECALL=1.0                       # valor predeterminado de «cero omisiones»; reducirlo si se relajan los KPI
TOP_K=50                             # presupuesto de aumento por etiqueta
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"

# Escribir la especificación del análisis de brechas para esta ejecución
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"

# El contenedor escribe como root con la opción --user desactivada; si es necesario, se cambia el propietario (chown) al UID del host.
docker run --rm -v "$WORKSPACE:/w" alpine chown -R "$(id -u):$(id -g)" "/w/$(realpath --relative-to="$WORKSPACE" "$OUT")"

# Impresión de comprobación para que el gancho de script-check vea números reales
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 INACCESIBLE — ver", unreachable)
    sys.exit(0)
with open(os.path.join(out, "threshold.txt")) as f:
    print("umbral:", f.read().strip())
with open(os.path.join(out, "metrics.json")) as f:
    m = json.load(f)
print(f"precisión={m['precisión']:.4f} recuperación={m['recuperación']:.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: filas={len(df)}, columnas={list(df.columns)}")
print(df['label'].value_counts())
PYEOF

Resultados

Guarda todo en una carpeta con marca de tiempo dentro del directorio de resultados del experimento. Los resultados del contenedor se guardan directamente allí; la comprobación visual aleatoria se guarda en rca_images/; cualquier gancho de empaquetado en tiempo de ejecución puede añadir artefactos de captura de sesión/configuración después de que se haya escrito RCA_Report.md.

/rca_results/AAAA-MM-DD_HHMMSS/
├── RCA_Report.md              # Informe completo de análisis de brechas (lo redactas tú)
├── kpi_gaps.parquet           # Contenedor: las K más débiles por etiqueta, desglosadas por iluminación
├── threshold.txt              # Contenedor: umbral de decisión elegido (único número flotante)
├── metrics.json               # Contenedor: matriz de confusión + estadísticas de distribución por etiqueta
├── weak_samples_breakdown.txt # Contenedor: recuento por etiqueta / muestras mal clasificadas / recuentos marginales
├── unreachable_kpi.txt        # Contenedor: SOLO cuando ningún umbral cumple con min_recall
├── rca_images/                # Tú: miniaturas de las 10 muestras débiles visualizadas
├── rca_config/                # Copiado automáticamente por el hook
└── session log/artifacts      # Opcional, captura del empaquetado dependiente del tiempo de ejecución

Al inicio de la ejecución, obtén la marca de tiempo real ejecutando «date +%Y-%m-%d_%H%M%S» en Bash. NO la introduzcas de forma fija ni la adivines. Si el usuario especifica una ruta de salida personalizada, utilízala en su lugar, pero mantén la misma estructura interna.

Errores habituales

El modo de fallo más grave es olvidarse de «top_k_per_label» cuando «min_recall=1,0»: a ese nivel de recuperación, el umbral elegido se sitúa en o por debajo de cada puntuación NO_PASS, por lo que, sin top_k_per_label, el contenedor recurre a un filtro de «muestras por debajo del umbral» que devuelve ÚNICAMENTE filas PASS mal clasificadas y cero filas NO_PASS, lo que interrumpe la cola de aumento. Incluye siempre un top_k_per_label positivo explícito (por defecto 50) en la especificación o como una configuración de Hydra.

Consulta references/pitfalls.md para ver la lista de comprobación completa, que incluye: olvidarse de top_k_per_label; pasar --user; llamar al programa solo con modificaciones de Hydra (sin -e ); archivo de especificaciones fuera de $WORKSPACE; archivo de especificaciones con centinelas ??? sin resolver; imagen no descargada / etiqueta incorrecta; descoincidencia en el montaje de rutas; archivo unreachable_kpi.txt escrito; falta de columnas obligatorias en inference.csv; falta de dataset.classify.input_map o image_ext en el YAML de entrenamiento; kpi_media_path que no coincide con los prefijos de input_path; y no se detecta ninguna GPU desde el interior del contenedor.

Estructura del informe

Redacta el archivo RCA_Report.md como un análisis conciso (entre 1000 y 1800 palabras) de las deficiencias computacionales: la profundidad se consigue con cifras precisas y una lista clara de acciones, no con la narrativa. La plantilla completa del informe (7 secciones: Veredicto, Selección de umbrales, Distribución de debilidades, Muestras más débiles Top-K, Comprobación visual aleatoria, Desglose por etiqueta, Acciones recomendadas —con la matriz de confusión y los diseños de las tablas—) se encuentra en references/output-template.md. Si existe el archivo unreachable_kpi.txt, sustituye las secciones 3 a 6 por una única sección breve en la que se cite el contenido de dicho archivo y reduce la sección 7 a una sola recomendación: volver a entrenar o reetiquetar.

Orden de ejecución

1. Resuelve DS_IMAGE a partir de versions.yaml (images.tao_toolkit.data_services); a continuación, ejecuta docker info, nvidia-smi y docker image inspect "$DS_IMAGE" (descargándola si falta) una vez para confirmar el entorno. Aborta la operación con un mensaje claro si falla alguno de los pasos.
2. Ejecuta «date +%Y-%m-%d_%H%M%S » para obtener la marca de tiempo; crea «/rca_results//».
3. Escribe vcn_aoi_spec.yaml en el directorio con la marca de tiempo, rellenando los campos min_recall y top_k_per_label. Guárdalo en $WORKSPACE para que la ruta -e se resuelva dentro del contenedor.
4. Ejecuta ` docker run … "$DS_IMAGE" gap_analysis vcn_aoi -e vcn_aoi_spec.yaml inference_results_dir=… train_config=… kpi_media_path=… output_dir=…`. El contenedor escribe kpi_gaps.parquet, threshold.txt, metrics.json y weak_samples_breakdown.txt en results_dir. Imprime el umbral elegido y el recuento de filas conservadas en la salida estándar (stdout) para que el hook script-check pueda verificar la salida generada por la ejecución.
5. Si existe el archivo unreachable_kpi.txt, omite el paso 6 y genera el informe resumido. De lo contrario, continúa.
6. Selecciona 10 muestras débiles (las 5 más débiles que han pasado la prueba y las 5 más débiles que no la han pasado) de kpi_gaps.parquet, visualiza cada imagen de prueba con Read, clasifícalas y cópialas en rca_images/.
7. Escribe RCA_Report.md en último lugar: al hacerlo se activa el hook de empaquetado, que copia los registros de sesión y la configuración de la habilidad junto con el archivo.