Habilidad de extracción e incrustación de DEFT

Eres el operador del flujo de trabajo «incrustar y extraer» de DEFT para el AOI de VCN. Tu tarea consiste en tomar un archivo Parquet de imágenes objetivo débiles (el resultado del análisis de brechas o del enrutamiento) y un conjunto de fuentes, para luego generar un archivo Parquet deduplicado de imágenes fuente extraídas que se parezcan a los objetivos, listas para incorporarlas a la siguiente ronda de entrenamiento.

El flujo de trabajo es fijo y determinista: incrustar los objetivos, incrustar el conjunto de fuentes y, a continuación, extraer los vecinos más cercanos. El archivo Parquet de salida de cada paso es la entrada del siguiente. No hay búsqueda iterativa, ni pasada de agrupamiento en clústeres, ni selección con intervención humana: la profundidad proviene de elegir el codificador adecuado y el «topn» correcto, no de una investigación en varias fases.

Toda la skill es una sencilla envoltura en torno a tres invocaciones directas de «docker run» 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 -e [sobrescrituras de Hydra...] — pasa image_embeddings -e … para la incrustación y tmm nearest_neighbors -e … para la minería. El indicador -e apunta a un archivo YAML que proporciona valores por defecto para el esquema de la subtarea; todo lo que viene después es una sustitución simple de Hydra (clave=valor) que anula selectivamente campos de la especificación en cada ejecución. (No hay ninguna palabra clave «dataset» dentro del contenedor; se trata del prefijo «pillar» del lanzador TAO y aquí se omite). Descarga la imagen una vez si no está almacenada en caché: docker pull "$DS_IMAGE" (tras resolver $DS_IMAGE según la configuración).

Las claves del esquema pueden cambiar de nombre entre versiones de data-services (la skill RCA pasó de «inference_csv» a «inference_results_dir», y de «output_dir» a «results_dir»). En caso de duda, comprueba el esquema real una vez por imagen: docker run --rm "$DS_IMAGE" embedding image_embeddings --cfg=job y ... tmm nearest_neighbors --cfg=job.

Entradas

1. Parquet de destino: el resultado del análisis de brechas, normalmente mining_gaps.parquet de tao-route-visual-changenet-samples (o gaps.parquet de tao-analyze-gaps-visual-changenet si se ha omitido el enrutamiento). Columna obligatoria: filepath. Si también está presente la columna label, se puede aplicar un filtrado basado en etiquetas durante la extracción; de lo contrario, la tarea de extracción ignora el filtro sin mostrar ningún mensaje.
2. Conjunto de origen: un archivo Parquet con imágenes candidatas para la extracción, que incluya una columna «filepath ». Si el usuario solo dispone de un archivo CSV, debe convertirlo a un archivo Parquet con las mismas columnas antes del paso 2. Para el filtrado basado en etiquetas, el conjunto también debe incluir una columna «label ».
3. Archivo de especificaciones de incrustación: un archivo YAML que contiene model, model_path, batch_size y (solo cuando model_path es un archivo .pth/.ckpt de TAO) model_config_path. Se reutiliza en los pasos 1 y 2;input_parquet/output_parquet se proporcionan en cada ejecución como anulaciones de Hydra. La misma especificación DEBE regir ambos pasos de incrustación: las incrustaciones de diferentes codificadores no son comparables, y los codificadores no coincidentes son la causa más común de los informes que indican que «las imágenes extraídas parecen no estar relacionadas».
4. Archivo de especificaciones de extracción: un archivo YAML que contiene topn, knn_metric, filter_by_label y (rara vez se modifican)source_embed_column_name/target_embed_column_name.source_parquet/target_parquet/output_parquet son valores de Hydra que se sobrescriben en tiempo de ejecución. Las incrustaciones de SigLIP y CLIP deben utilizar knn_metric: cosine. Cuando filter_by_label es true, pero alguno de los archivos Parquet de incrustación carece de una columna de etiqueta, el contenedor registra una advertencia y continúa sin filtrar.

Configuración

Resuelve la URI concreta de ` tao_toolkit.data_services` a partir de `versions.yaml ` una sola vez al inicio de la ejecución; a continuación, comprueba que Docker, el kit de herramientas de contenedores de NVIDIA y una GPU estén presentes antes de realizar cualquier otra acción. Se requiere una GPU tanto para la pasada de avance del codificador como para la búsqueda k-NN de cuML/cuDF; ambos pasos fallan sin CUDA.

# Resolver tao_toolkit.data_services → URI concreta nvcr.io/... desde el archivo 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"

Todas las rutas del host que el contenedor lea o escriba deben montarse mediante bind. El enfoque más predecible consiste en montar la raíz del espacio de trabajo con rutas idénticas dentro y fuera del contenedor, y luego reutilizar un alias $DOCKER para las tres invocaciones:

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

No pases --user $(id -u):$(id -g): provoca un error KeyError de getpwuid() durante la importación de transformers antes de que comience ningún trabajo. El contenedor se ejecuta como root; chown devuelve posteriormente el UID del host.

Crea los dos archivos de especificaciones una vez por iteración, colocándolos en $WORKSPACE para que el argumento -e se resuelva a ambos lados del montaje; los valores específicos de cada ejecución se mantienen fuera de la especificación y se pasan como modificaciones de Hydra. Si el conjunto de datos de origen es un CSV, conviértelo a Parquet desde el principio (conservando la ruta del archivo y la etiqueta, si la hay). El archivo embedding_spec.yaml predeterminado utiliza model: SigLIP, model_path: google/siglip-base-patch16-224, batch_size: 64; el archivo mining_spec.yaml predeterminado utiliza topn: 5, knn_metric: cosine, filter_by_label: «false» (entre comillas, ya que el esquema lo lee como una cadena).

Consulta references/setup.md para ver las notas completas sobre el entorno, el manejo de TAO_SKILL_BANK_PATH, la justificación del montaje de rutas, la solución alternativa para el cambio de propietario con getpwuid, el fragmento de código de CSV a Parquet y los bloques de creación de archivos de especificaciones tal cual.

Método

Tres comandos, en orden. El archivo Parquet generado por cada comando sirve de entrada para el siguiente. Ejecútalos como comandos Bash sin formato; el alias $DOCKER de la configuración se encarga del contenedor, la GPU y los montajes. Cada ejecución sigue el mismo formato: -e para los valores predeterminados integrados, seguido de unas cuantas modificaciones de Hydra para las rutas específicas de la ejecución.

Paso 1: incrustar las imágenes de destino

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

Lee la salida del análisis de brechas y del enrutamiento y escribe un archivo Parquet con la ruta del archivo, la incrustación y cualquier columna de metadatos adicional (por ejemplo, label, siamese_score, weakness) que se haya transferido tal cual desde la entrada. Imprime el esquema de salida (pd.read_parquet(...).columns) en la salida estándar (stdout) para que el gancho de comprobación del script pueda confirmar que la columna de incrustación existe.

Si necesitas anular model / model_path / batch_size para una ejecución sin editar la especificación, añádelos como anulaciones de Hydra (p. ej., model_path=...).

Paso 2 — Incrustar el conjunto de datos de origen

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

El comando tiene la misma estructura que en el paso 1, pero aplicado al conjunto de datos de origen. Utiliza el mismo archivo embedding_spec.yaml que en el paso 1 y no modifiques aquí los parámetros model, model_path ni batch_size de forma diferente; unas configuraciones del codificador que no coincidan entre ambos pasos producen incrustaciones no comparables.

Paso 3: Identificar los vecinos más cercanos

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

Para cada incrustación de destino, busca las topn incrustaciones de origen más cercanas según la métrica elegida, elimina los duplicados entre los destinos y escribe un archivo Parquet de una sola columna (ruta de archivo) con las rutas de origen únicas extraídas. El contenedor también genera un archivo mining_summary.txt junto al archivo Parquet de salida con: recuento de consultas, recuento de vecinos, duplicados eliminados y (cuando el filtrado por etiqueta está activado) recuentos de pares conservados frente a descartados. Se puede ajustar topn, knn_metric o filter_by_label mediante una sobrescritura de Hydra en línea durante el barrido (p. ej., topn=10); no es necesario reescribir la especificación.

Cuando filter_by_label=true pero a uno de los archivos Parquet de incrustación le falta la columna de etiqueta, el contenedor registra una advertencia y continúa sin filtrar. Si el resultado extraído parece mayor de lo esperado o contiene pares entre etiquetas, revisa el registro de Docker en busca de esa advertencia antes de dar por hecho que la tarea se ha ejecutado correctamente.

Consulta references/reference-invocation.md para ver la receta completa mínima, lista para copiar y editar (resuelve $DS_IMAGE, escribe ambas especificaciones, ejecuta los tres pasos, cambia el propietario de los resultados e imprime el recuento de filas), que se ejecuta como un único bloque de Bash en serie.

Resultados e informe

Guarda todo en una carpeta con marca de tiempo dentro del directorio del experimento o la iteració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 directamente, pero mantén la misma estructura interna. El hook de empaquetado añade automáticamente «mining_config/» y «claude_session.jsonl » cuando se escribe «Mining_Report.md ».

El archivo Parquet extraído es el artefacto que consume el entrenamiento posterior. Los dos archivos Parquet de incrustación son intermedios, pero vale la pena conservarlos: son reutilizables en múltiples ejecuciones de extracción con el mismo conjunto de datos de origen, y son el único lugar donde buscar cuando un informe «que parece no estar relacionado» requiere una depuración a nivel del codificador.

Consulta references/outputs-and-reporting.md para ver la estructura completa del directorio de salida y la plantilla literal de Mining_Report.md (Veredicto, Entradas, Coherencia del codificador, Ejecución de minería, Desglose por etiqueta, Validez de la salida, Acciones recomendadas; mantén una extensión de entre 600 y 1200 palabras).

Errores habituales

El error más frecuente es la falta de coincidencia entre los codificadores de los dos pasos de incrustación —la causa más habitual de resultados erróneos en la extracción de datos—; ambos pasos deben utilizar el mismo archivo embedding_spec.yaml. Otras trampas recurrentes: pasar --user (el error KeyError «getpwuid» ), saltarse un paso de incrustación, la ausencia de una columna de etiquetas que hace que filter_by_label=true no tenga ningún efecto, archivos de especificaciones fuera de $WORKSPACE, sentinelas ??? sin resolver, puntos de control de TAO sin model_config_path, conjuntos de datos de origen en CSV introducidos directamente, discrepancias en las rutas del host o del contenedor, ausencia de GPU, una etiqueta de imagen no descargada o :latest, y topn × N_targets ≫ tamaño del conjunto de datos de origen (esperado: informa del recuento real extraído).

Consulta references/troubleshooting.md para ver la lista completa de problemas con los errores exactos, las causas y las soluciones.

Orden de ejecución

1. Resuelve DS_IMAGE a partir de versions.yaml (images.tao_toolkit.data_services) y, 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 alguno falla.
2. Ejecuta «date +%Y-%m-%d_%H%M%S » para obtener la marca de tiempo; crea « » y «/mining_results//».
3. Escribe los archivos `embedding_spec.yaml ` y `mining_spec.yaml` en el directorio con la marca de tiempo, indicando la opción de codificador y los parámetros de minería. Guárdalos en `$WORKSPACE ` para que la ruta `-e ` se resuelva dentro del contenedor.
4. Si el conjunto de datos de origen es un CSV, conviértelo primero a Parquet (conserva la ruta del archivo y la etiqueta).
5. Ejecuta el paso 1 (incrustar destinos) mediante `docker run … embedding image_embeddings -e embedding_spec.yaml input_parquet=… output_parquet=…`. Imprime el número de filas y columnas del archivo Parquet de salida en la salida estándar (stdout).
6. Ejecuta el paso 2 (incrustar el conjunto de datos de origen) con el mismo archivo ` embedding_spec.yaml ` que en el paso 1. Imprime el número de filas y columnas del archivo Parquet de salida.
7. Ejecuta el paso 3 (minar vecinos más cercanos) mediante `docker run … tmm nearest_neighbors -e mining_spec.yaml source_parquet=… target_parquet=… output_parquet=…`. Comprueba que el archivo `mining_summary.txt` se haya escrito junto al archivo ` mined.parquet`.
8. Calcula el desglose por etiqueta (Sección 5) uniendo el archivo Parquet de incrustaciones de destino con la salida extraída en la ruta de archivo, siempre que ambos contengan una etiqueta.
9. Escribe Mining_Report.md en último lugar: al hacerlo se activa el gancho de empaquetado, que copia los registros de sesión y la configuración de la habilidad.