TAO Generate Image Embeddings

Utilisez cette skill pour exécuter l'embedding d'images TAO Data Services. La skill consomme un parquet de chemins d'accès aux images et écrit un parquet avec une colonne embedding. Les skills de mining en aval (tao-mine-od-images, tao-mine-nearest-neighbors) consomment sa sortie.

Le point d'entrée du conteneur est :

embedding image_embeddings -e /absolute/path/to/image_embeddings.yaml

Inputs

L'utilisateur peut fournir soit une spec existante, soit les champs nécessaires pour en générer une.

Champs de spec requis :

Champs optionnels courants :

Le parquet d'entrée doit contenir une colonne filepath. Toute colonne supplémentaire est transmise verbatim à la sortie, de sorte que les métadonnées telles que label subsistent dans le parquet d'embedding.

Le template par défaut est assets/default_image_embeddings.yaml.

Encoder Consistency

Quand les embeddings alimentent une étape de mining, chaque parquet comparé à un autre doit être produit avec le même model et model_path. La dimensionalité de l'embedding suit l'encodeur — 768 pour la valeur par défaut SigLIP, 512 pour CLIP ViT-B/32 — et rien dans le parquet de sortie n'enregistre quel encodeur l'a écrit. Les embeddings provenant d'encodeurs différents ne sont pas comparables, et les encodeurs incompatibles sont la cause la plus courante de résultats de mining qui semblent sans rapport avec les cibles. Réutilisez une spec unique pour chaque parquet dans une exécution de mining et ne surcharger que input_parquet / output_parquet.

Quick Start

Exécutez depuis la racine du repo tao-skill-bank.

Écrivez la spec à côté du parquet de sortie. L'exécution ne la conserve pas, de sorte que les embeddings n'ont sinon aucun enregistrement de l'encodeur qui les a produits. C'est particulièrement important ici : chaque parquet comparé à un autre lors d'une étape de mining doit provenir du même model et model_path, et les encodeurs incompatibles sont la cause habituelle de résultats de mining qui semblent sans rapport avec ses cibles.

OUT_DIR=/absolute/path/for/this/run              # where output_parquet is written
SPEC="$OUT_DIR/image_embeddings.yaml"            # spec lives beside its output
RUN_ROOT=/absolute/path/that/contains/parquets/images/and/results
GPU_COUNT=1

python3 skills/data/tao-generate-image-embeddings/scripts/verify_image_embeddings_spec.py \
  --spec "$SPEC"

DS_IMAGE=nvcr.io/nvidia/tao/tao-toolkit:7.2.0-data-services  # versions-key: images.tao_toolkit.data_services

docker run --rm --gpus "$GPU_COUNT" --shm-size=8g --network=host \
  -v "$RUN_ROOT:$RUN_ROOT" \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -w "$RUN_ROOT" \
  "$DS_IMAGE" \
  embedding image_embeddings -e "$SPEC"

Ne passez pas --user $(id -u):$(id -g) au conteneur TAO data-services ; l'image importe transformers au démarrage, ce qui appelle getpass.getuser() et échoue quand l'UID n'est pas présent dans /etc/passwd.

Pour embedder plusieurs parquets avec un seul encodeur, réutilisez la même spec et surcharger les deux chemins par exécution :

docker run --rm --gpus "$GPU_COUNT" --shm-size=8g --network=host \
  -v "$RUN_ROOT:$RUN_ROOT" -w "$RUN_ROOT" "$DS_IMAGE" \
  embedding image_embeddings -e "$SPEC" \
  input_parquet=/abs/path/other_input.parquet \
  output_parquet=/abs/path/other_output.parquet

Generate A Spec

Si l'utilisateur fournit des chemins de parquet et un encodeur au lieu d'une spec prête, copiez le template et remplissez les null. Chaque valeur de tuning qu'il porte déjà est celle que cette étape veut — changez-en une uniquement délibérément.

cp skills/data/tao-generate-image-embeddings/assets/default_image_embeddings.yaml "$SPEC"

Remplissez input_parquet, output_parquet et — si vous n'utilisez pas l'encodeur par défaut — model et model_path, tous en tant que chemins absolus, puis validez :

python3 skills/data/tao-generate-image-embeddings/scripts/verify_image_embeddings_spec.py --spec "$SPEC"

input_parquet: /absolute/path/filepaths.parquet
output_parquet: /absolute/path/results/embeddings.parquet
model: SigLIP
model_path: google/siglip-base-patch16-224
model_config_path: ""          # required only when model_path is a TAO .pth/.ckpt
batch_size: 64

Le template est le seul endroit où une valeur par défaut vit, donc rien ne peut le contredire. verify rapporte l'encodeur, puisque les embeddings ne sont comparables qu'à d'autres produits par le même model et model_path.

Conservez la spec, le parquet d'entrée, les fichiers image et le répertoire de sortie sous RUN_ROOT pour que les mêmes chemins se résolvent à l'intérieur du conteneur.

Preflight

1. Vérifiez Docker et l'accès GPU :

docker info > /dev/null
nvidia-smi -L

2. Résolvez et tirez l'image data-services si nécessaire :

DS_IMAGE=nvcr.io/nvidia/tao/tao-toolkit:7.2.0-data-services  # versions-key: images.tao_toolkit.data_services
docker image inspect "$DS_IMAGE" > /dev/null || docker pull "$DS_IMAGE"

3. Validez la spec :

python3 skills/data/tao-generate-image-embeddings/scripts/verify_image_embeddings_spec.py \
  --spec "$SPEC"

4. Confirmez que RUN_ROOT contient la spec, le parquet d'entrée, les fichiers image vers lesquels sa colonne filepath pointe, et le répertoire de sortie. Montez RUN_ROOT au même chemin absolu à l'intérieur de Docker.

Outputs

Le parquet de sortie contient filepath, une colonne embedding de vecteurs de type list, et chaque colonne supplémentaire transmise depuis l'entrée. Imprimez son nombre de lignes et sa liste de colonnes après l'exécution pour que l'appelant puisse confirmer que la colonne embedding existe.

Troubleshooting

The subtask image_embeddings requires -e/--experiment_spec_file : relancez avec embedding image_embeddings -e "$SPEC".

Parquet d'entrée ou images non trouvés à l'intérieur de Docker : les valeurs filepath sont lues verbatim. Utilisez un montage RUN_ROOT où les chemins hôte et conteneur sont identiques, et confirmez que les images elles-mêmes sont sous ce montage — pas seulement le parquet.

Erreur de chargement de modèle avec un model_path .pth / .ckpt : les checkpoints TAO ont besoin que model_config_path soit défini sur la spec d'entraînement pour que l'architecture puisse être reconstruite. Les ids HuggingFace et les répertoires de snapshot n'en ont pas besoin.

CUDA manque de mémoire : diminuez batch_size (essayez 32 ou 16).

Les résultats minés semblent sans rapport en aval : les parquets comparés pendant le mining ont été embarqués avec des encodeurs différents. Réembedez-les avec une spec partagée — voir ## Encoder Consistency.

Aucun GPU disponible : l'embedding nécessite au moins un GPU CUDA. Vérifiez nvidia-smi -L, le flag Docker --gpus et l'installation du nvidia container toolkit.