ML Recog

Apprentissage métrique pour la reconnaissance visuelle fine-grained. Apprend des embeddings pour la reconnaissance par correspondance basée sur la récupération (par ex. reconnaissance de produits retail). Utilise des pertes triplet/contrastives.

Définissez model.pretrained_model_path pour un backbone préentraîné.

Pour les actions TAO Deploy TensorRT (gen_trt_engine, TensorRT evaluate, et TensorRT inference), lisez d'abord references/tao-deploy-metric-learning-recognition.md. Les templates de spec de déploiement se trouvent dans le dossier references/ de cette skill avec le préfixe spec_template_deploy_*.yaml.

Schémas Dataclass

Les schémas TAO Core générés sont packagés dans schemas/<action>.schema.json, avec schemas/manifest.json listant les actions disponibles. Chaque schéma généré émet aussi references/spec_template_<action>.yaml à partir du champ default du niveau supérieur du schéma. L'activation AutoML est déclarée au niveau modèle dans references/skill_info.yaml via automl_enabled. L'exécution AutoML nécessite toujours que schemas/train.schema.json et references/spec_template_train.yaml existent et soient parsables. Utilisez le schéma train packagé pour automl_default_parameters, automl_disabled_parameters, les défauts, les bornes min/max, les enums, les poids d'options, les conditions mathématiques, les dépendances et les paramètres populaires. N'attendez pas ~/tao-core à l'exécution ; les mainteneurs régénèrent les schémas/templates avant de packager la skill bank.

Politique d'Action Train

Ce modèle est activé pour AutoML au niveau du modèle. Avant de traiter toute demande au stade train, lisez references/skill_info.yaml et résolvez l'override d'exécution depuis une valeur automl_policy explicite ou la demande de workflow de l'utilisateur. Traitez les phrases comme « turn off AutoML », « disable AutoML », « no HPO » ou « plain training » comme automl_policy: off pour cette exécution uniquement ; sinon, utilisez par défaut auto. Quand automl_policy: auto, automl_enabled: true, et que schemas/train.schema.json et references/spec_template_train.yaml sont packagés, routez l'action train via tao-skill-bank:tao-run-automl par défaut avec le skill_dir de ce modèle. Préservez les overrides de workflow/application pour les datasets, specs, répertoires de sortie, paramètres GPU/platform, checkpoints parents et automl_policy. Utilisez l'entraînement direct du modèle uniquement quand automl_policy: off ou que le schéma/template train packagé manque ; dans le cas du schéma manquant, signalez qu'AutoML est activé mais non exécutable pour ce modèle jusqu'à ce que les schémas soient générés.

Les actions non-train comme evaluate, inference, export et les flux de déploiement restent dans cette skill de modèle. L'override automl_policy par exécution ne change pas les métadonnées du modèle.

Exigences d'Entraînement

• Type de dataset : ml_recog
• Formats : default
• Métrique de monitoring : val Precision at Rank 1

Exigences de Dataset par Action

Overrides Spec Typiques

Les overrides de source de données sont obligatoires pour chaque action — l'agent DOIT construire les chemins de source de données à partir du tableau Exigences de Dataset par Action ci-dessus et les inclure dans spec_overrides.

S3_TRAIN = "s3://bucket/data/train"

train (sources de données obligatoires) :

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "dataset.train_dataset": f"{S3_TRAIN}/metric_learning_recognition/retail-product-checkout-dataset_classification_demo/known_classes/train.tar.gz",
    "dataset.val_dataset": {"reference": f"{S3_TRAIN}/metric_learning_recognition/retail-product-checkout-dataset_classification_demo/known_classes/reference.tar.gz", "query": f"{S3_TRAIN}/metric_learning_recognition/retail-product-checkout-dataset_classification_demo/known_classes/val.tar.gz"},
}

gen_trt_engine (sources de données obligatoires) :

{
    "gen_trt_engine.tensorrt.data_type": "INT8",
    "gen_trt_engine.tensorrt.calibration.cal_image_dir": [f"{S3_TRAIN}/metric_learning_recognition/retail-product-checkout-dataset_classification_demo/known_classes/test.tar.gz"],
}

evaluate (sources de données obligatoires) :

{
    "dataset.val_dataset": {"reference": f"{S3_TRAIN}/metric_learning_recognition/retail-product-checkout-dataset_classification_demo/unknown_classes/reference.tar.gz", "query": f"{S3_TRAIN}/metric_learning_recognition/retail-product-checkout-dataset_classification_demo/unknown_classes/test.tar.gz"},
}

inference (sources de données obligatoires) :

{
    "dataset.val_dataset": {"reference": f"{S3_TRAIN}/metric_learning_recognition/retail-product-checkout-dataset_classification_demo/unknown_classes/reference.tar.gz"},
    "inference.input_path": f"{S3_TRAIN}/metric_learning_recognition/retail-product-checkout-dataset_classification_demo/unknown_classes/test.tar.gz",
}

Dataset d'Évaluation

Obligatoire. L'évaluation nécessite des datasets de référence et de requête pour les métriques de récupération.

Paramètres Importants

• model.backbone : Par défaut resnet_50. Options : resnet_50, resnet_101, fan_small, fan_base, fan_large, fan_tiny, nvdinov2_vit_large_legacy.
• model.feat_dim : Dimension d'embedding. Par défaut 256. Taille du vecteur de caractéristiques de sortie pour la correspondance de similarité.
• train.batch_size : Taille de batch par GPU. Par défaut 4. val_batch_size également 4.
• dataset.num_instance : Instances par identité dans un batch (échantillonnage P/K). Par défaut 4. Contrôle combien d'images de la même classe apparaissent ensemble.
• train.optim.trunk.base_lr : Taux d'apprentissage du trunk (backbone). Par défaut 3.5e-4 (Adam).
• train.optim.embedder.base_lr : Taux d'apprentissage de la tête d'embedding. Par défaut 3.5e-4.
• train.optim.triplet_loss_margin : Marge pour la perte triplet. Par défaut 0.3. smooth_loss=True par défaut.
• train.optim.miner_function_margin : Marge d'extraction difficile. Par défaut 0.1. Contrôle la difficulté d'extraction de paires.
• train.optim.steps : Étapes de décroissance LR. Par défaut [40, 70] avec gamma=0.1.
• dataset.train_dataset : Chemin vers les images d'entraînement organisées en dossiers de classe.
• dataset.val_dataset : Dict avec les clés « reference » et « query » pointant vers des répertoires au format ImageNet pour l'évaluation de récupération.

Multi-GPU / Multi-Node

Méthode de lancement : Lightning-managed (un seul processus python, Lightning crée les workers).

• Stratégie : auto (Lightning choisit la meilleure stratégie automatiquement)
• Pas de config num_nodes ou distributed_strategy explicite — orientation single-node

Matériel

Minimum 1 GPU(s), recommandé 2 GPU(s). 16 Go+ VRAM par GPU. L'apprentissage métrique bénéficie de tailles de batch plus importantes pour un meilleur échantillonnage triplet mais est autrement modéré en mémoire.

Patterns d'Erreur

Décalage référence/requête : Assurez-vous que les datasets de référence et de requête partagent des espaces de noms de classe compatibles pour l'évaluation.

Paramètre Spec / Inférence du Modèle Parent

Les mappages d'inférence spécifiques au modèle appartiennent à ce fichier MD, pas à config.json. Les runners générés doivent lire cette section et appliquer les mappages avec les helpers du SDK avant create_job(). Cela reflète l'ancien flux infer_params.py des microservices.

Mappages d'inférence de TAO Core ml_recog.config.json :

Pour parent_model ou parent_model_folder, passez l'id du job enfant train/export/AutoML en amont comme parent_job_id. Le SDK liste le dossier de résultats parent, filtre les artefacts de checkpoint et retourne le fichier ou dossier de modèle sélectionné. N'ajoutez pas ces mappages à config.json et ne patchezdites pas les scripts runner générés pour deviner les chemins de checkpoint.

Déploiement

• tao-deploy-metric-learning-recognition — Workflow de déploiement MLRecog pour la génération de moteur TensorRT, l'évaluation TensorRT et l'inférence TensorRT utilisant TAO Deploy.