Extraire les embeddings publics Encodon

Objectif

Extraire un vecteur CLS figé par séquence de codons avec la v1 publique d'Encodon. Prendre en charge la validation des entrées, la préparation des commandes, l'extraction et la sélection de checkpoint pour modéliser l'efficacité de la traduction, l'expression ou la stabilité de l'ARNm. L'extraction n'entraîne pas automatiquement un régresseur aval.

Prérequis

• La validation ne nécessite que la stdlib Python 3 ; pas de GPU, de poids ni de clé API.
• L'exécution nécessite le checkout public CodonFM, son environnement requirements.txt, un GPU NVIDIA compatible et les poids de checkpoint locaux. Un JSON de métadonnées n'est pas un checkpoint. Un fichier .safetensors a besoin de son frère config.json ; les checkpoints .ckpt sont aussi pris en charge par le loader public.
• Lancez python -m src.runner à la racine du dépôt CodonFM. Dans un espace de travail isolé, utilisez les artefacts sources fournis ; les chemins sources ci-dessous sont relatifs à ce checkout ou cette archive source, pas à ce répertoire skill.

Entrées

Ordre de priorité de la source d'entrée : arguments explicites du prompt utilisateur, puis fichiers/métadonnées de checkpoint fournis, puis inspectez les defaults publics du runner. Résolvez les conflits de noms de modèles et de métadonnées de checkpoint avant l'exécution. Les métadonnées 80M fournies sont utiles pour préparer une commande 80M ; elles ne limitent pas une recommandation ouverte à cette taille.

Requis pour la validation : un CSV. Requis pour l'extraction : le CSV, le checkpoint, le nom de modèle correspondant et le répertoire de sortie. Optionnel : longueur de contexte et taille de batch. Les questions de sélection de checkpoint peuvent être répondues sans CSV.

Instructions

1. Choisissez le workflow demandé. Pour une question de checkpoint/performance, lisez checkpoint selection et répondez à partir de preuves de benchmark publiques. Pour les plus forts résultats publiés aval, préférez le checkpoint public 1B random-mask quand les ressources le permettent ; 80M est un choix de démonstration ou de ressources limitées. Un petit ensemble étiqueté seul n'établit pas que les features figées 80M sont meilleures. Ne téléchargez pas les poids ni n'inspectez l'arborescence source entière juste pour faire une recommandation.
2. Inspectez la source fournie uniquement si nécessaire. Confirmez runner/config, src/data/codon_bert_dataset.py, src/data/preprocess/codon_sequence.py, src/inference/encodon.py, ou src/utils/pred_writer.py pour le comportement pertinent. Lisez les membres ZIP avec zipfile.ZipFile.namelist() et .read() ; l'inspection source n'a pas besoin d'extraction. Si un checkout est nécessaire, utilisez un nouveau répertoire depuis tempfile.mkdtemp() ou mktemp -d, sans supprimer ni écraser un répertoire existant. Pour les questions de support Decodon, inspectez runner/config et modules model/inference, citez les fichiers inspectés, expliquez l'implémentation publique manquante, et arrêtez-vous là.
3. Validez le CSV avant de lancer l'extraction. Lancez le checker fourni ci-dessous avec la longueur de contexte prévue. Rapportez les verdicts par ligne en utilisant les numéros de ligne CSV aussi bien que les IDs, car les IDs peuvent se répéter. Séparez les lignes exclues, les entrées invalides, les avertissements ID dupliqué et la troncature. Proposez des corrections sans réécrire silencieusement les données fournies. Le checker est une vérification préalable, pas une exécution de modèle ni une preuve de validité biologique du CDS.
4. Livrez la préparation ou l'exécution demandée. Pour la préparation, retournez une commande complète avec les chemins résolus (ou prérequis clairement identifiés), le nombre de lignes test, les résultats de validation et le contrat de sortie ci-dessous. Incluez tous les flags task/dataset/process dans la réponse finale, même s'ils sont déjà affichés dans un appel d'outil. Pour l'extraction, réutilisez/téléchargez le checkpoint choisi si nécessaire, exécutez une fois les ressources prêtes, et vérifiez les arrays sauvegardés. Si les ressources manquent, terminez la préparation et indiquez ce qui manque.

Scripts disponibles

Lancez la vérification préalable avec Python ; CODONFM_SKILL_DIR est le répertoire contenant ce fichier :

python "$CODONFM_SKILL_DIR/scripts/validate_inputs.py" "$CODONFM_DATA_PATH" \
    --context-length 2048

Le checker affiche du JSON. Exit 0 signifie aucun résultat, 1 signifie des résultats de ligne à examiner (incluant exclusions/avertissements), et 2 signifie une erreur fichier/schéma. Ni les avertissements ni les exclusions n'impliquent que le runner public plantera.

Format de sortie

Le checker émet du JSON avec total_rows, test_rows, excluded_rows, context_length, codon_limit, warnings et rows. Chaque ligne enregistre son numéro de ligne de données en base 1 (excluant l'en-tête), ID, split, verdict, problèmes, validité de séquence/valeur et codons retenus/perdus. Une erreur fichier/schéma émet error et csv à la place. Ce sont des résultats de vérification préalable, pas des embeddings générés.

Exemples

Définissez CODONFM_DATA_PATH sur le CSV, CODONFM_CHECKPOINT_PATH sur les poids, CODONFM_MODEL_NAME sur l'architecture correspondante, et CODONFM_RUN_DIR sur un répertoire de sortie neuf. Substituez les chemins réels dans une commande préparée :

python -m src.runner eval \
    --task_type embedding_prediction \
    --process_item codon_sequence \
    --dataset_name CodonBertDataset \
    --exp_name embed_extract \
    --model_name "$CODONFM_MODEL_NAME" \
    --checkpoint_path "$CODONFM_CHECKPOINT_PATH" \
    --data_path "$CODONFM_DATA_PATH" \
    --context_length 2048 \
    --num_nodes 1 \
    --num_gpus 1 \
    --num_workers 0 \
    --val_batch_size 2 \
    --out_dir "$CODONFM_RUN_DIR" \
    --predictions_output_dir "$CODONFM_RUN_DIR/predictions"

Pour une démonstration à faible coût, encodon_80m correspond à nvidia/NV-CodonFM-Encodon-80M-v1, révision 399ca9fe17b57941a7bebc6788033919b417413c, fichier NV-CodonFM-Encodon-80M-v1.safetensors et frère config.json.

Sorties

• Sous --predictions_output_dir, embeddings_merged.npy contient des vecteurs CLS figés de dernière couche, shape (processed_rows, hidden_size).
• ids_merged.npy est aligné par index : la ligne embedding i appartient à l'ID ligne i. Utilisez ces IDs pour joindre au CSV ; ne supposez pas que chaque ligne CSV a été conservée. Les IDs dupliqués rendent cette jointure ambiguë même quand l'extraction réussit.
• Pour l'exemple mono-GPU, vérifiez que les deux arrays ont le nombre de lignes test prévu, que les embeddings sont finis et que la largeur correspond au config checkpoint (1024 pour 80M, 2048 pour 600M/1B). Ne fabriquez pas d'arrays pour une demande de préparation uniquement.

Les références de modèle aval du checkout public sont :

• notebooks/4-EnCodon-Downstream-Task-riboNN.ipynb
• notebooks/5-EnCodon-Downstream-Task-mRFP-expression.ipynb
• notebooks/6-EnCodon-Downstream-Task-mRNA-stability.ipynb

Limitations

• La v1 publique n'a pas d'implémentation de modèle/inference Decodon, de notebooks Decodon, de notebooks/te_predictor.py ou notebooks/mfe_predictor.py.
• À longueur de contexte 2048, conservez les 2046 premiers codons ; toute séquence 3-prime restante est perdue. Augmenter le flag ne valide pas un contexte plus long. Divulguez la troncature délibérée ou une stratégie séparée de chunking/agrégation ; aucune n'équivaut à embedder la séquence complète une seule fois.
• --dryrun construit la configuration runtime, peut créer des répertoires et a besoin de dépendances ML ; il ne lit ni le CSV ni les poids et n'est pas une validation d'entrée.
• Ne prétendez pas qu'un régresseur entraîné sur benchmark se généralise à un nouvel organisme, type cellulaire ou assay sans nouvelles données de validation étiquetées.
• N'invoquez pas cette skill pour une demande générique de prédiction d'expression qui ne mentionne pas CodonFM ou Encodon.

Dépannage