kpp-coding-skill

Modèles Énergétiques KPP et Échantillonnage

Responsable de l'intégration des modèles PyTorch avec les échantillonneurs Kaiwu. Les paramètres du modèle, la fonction objectif et l'optimiseur restent dans PyTorch ; l'échantillonneur compatible connecte le solveur Kaiwu ou le flux d'échantillonnage existant de la tâche. Ne transformez pas automatiquement une tâche d'apprentissage automatique ordinaire en une tâche de modèle énergétique.

Sélection des Composants

Choisissez d'abord la structure en fonction des entrées, des sorties et de la relation à modéliser, et expliquez comment le composant sélectionné répond aux exigences de la tâche. Lorsque l'utilisateur spécifie la structure, réalisez-la selon ses instructions ; en cas d'auto-sélection, déterminez si la tâche nécessite des relations directes entre les variables observées, des facteurs cachés, une représentation hiérarchique, une reconstruction latente, une génération contextuelle ou une sélection de caractéristiques, puis choisissez le composant correspondant. La taille du modèle n'est pas une priorité par défaut ; vérifiez d'abord si les capacités et les résultats correspondent, puis comparez les coûts d'entraînement et d'échantillonnage entre les solutions satisfaisantes.

Capacité requise	Composant	Justification du choix
Expliquer les motifs observés par des facteurs cachés, ou apprendre une structure bipartite visible/cachée	RestrictedBoltzmannMachine	La représentation cachée participe à l'apprentissage de la distribution nécessaire à la tâche ; une entrée uniquement binaire ne justifie pas à elle seule l'utilisation d'un RBM
Modéliser directement les interactions par paires de nœuds binaires, ou échantillonner après avoir fixé certains nœuds	BoltzmannMachine	Les nœuds et leurs interactions correspondent aux variables du problème ; validez avec des indicateurs de la tâche si cela suffit à exprimer la relation nécessaire
Apprendre des caractéristiques hiérarchiques via plusieurs couches de RBM	UnsupervisedDBN	La tâche nécessite une représentation apprise couche par couche, ou l'utilisateur demande explicitement une pile de RBM
Reconstruction et a priori latent de modèle énergétique échantillonnable	QVAE	La reconstruction et l'a priori latent servent tous deux la tâche ; un auto-encodeur ordinaire ne doit pas être converti en QVAE pour cette raison
Génération de candidats discrets contextuels et guidage par l'énergie	QDiffusion	La proposition fournit le contexte nécessaire, l'énergie guide les candidats en fonction de la tâche
Sélection d'un sous-ensemble de caractéristiques à partir des entrées d'un modèle PyTorch existant	FeatureSelectionWrapper	La tâche nécessite une sélection des caractéristiques d'entrée, en utilisant un masque 0/1 mis à jour périodiquement

Les données binaires, le nombre d'étiquettes ou l'ordre d'apparition des exemples ne peuvent pas déterminer seuls le choix. Validez le choix avec les résultats requis par la tâche : association, reconstruction, complétion ou prédiction ; une simple importation réussie ou une forme de sortie correcte ne signifie pas une adéquation. Lorsque la tâche nécessite des relations d'ordre supérieur ou un contexte, ne considérez pas le modèle comme suffisant sur la seule base de statistiques par paires satisfaisantes. Les différentes structures d'entraînement de BM et RBM sont décrites dans le paradigme du modèle, lisez uniquement la partie pertinente pour la tâche en cours.

Il s'agit de différents composants du même package KPP ; il n'est pas nécessaire d'installer six plugins séparément. Bien que la sélection de caractéristiques résolve en interne un QUBO, elle sert l'entraînement du modèle PyTorch et relève donc de cette compétence ; les tâches pures de localisation, d'ordonnancement, de Max-Cut, etc., qui ne sont pas附 adossées à un modèle et recherchent directement une décision optimale, relèvent de la compétence Kaiwu SDK. Si une même tâche contient à la fois de l'optimisation combinatoire et de l'entraînement énergétique, les deux compétences peuvent être chargées séparément, chacune avec son propre interpréteur.

Boucle Minimale d'une Tâche Applicative

1. Utilisez des données représentatives pour vérifier l'effet de la structure choisie sur la tâche, et enregistrez les échelles et durées réelles d'entraînement et de génération. Planifiez l'exécution formelle en conséquence, en réservant dans le budget total le temps nécessaire pour la sauvegarde du modèle, le chargement dans un nouveau processus, la génération et la vérification du rapport.
2. Établissez dès que possible le pipeline complet d'entrée requis. Après chaque vérification, sauvegardez le modèle, la configuration et le rapport les plus performants et réutilisables ; les expériences suivantes utiliseront un nouveau répertoire de sortie, le répertoire de livraison conservant toujours une version exécutable.
3. La génération par lots accumule le nombre réel de lignes : lorsqu'un lot est ajouté, ajoutez le nombre de lignes de ce lot, puis tronquez lorsque la quantité demandée est atteinte. Utilisez d'abord une petite requête pour vérifier la quantité, la largeur et les valeurs ; le nombre de lots n'est pas égal au nombre d'échantillons.
4. Distinguez la copie directe des enregistrements originaux, la coïncidence naturelle de l'échantillonnage du modèle et le filtrage manuel. Les combinaisons courantes peuvent coïncider dans des générations indépendantes ; le filtrage des enregistrements en double ou l'imposition de l'unicité modifie la distribution ; après utilisation, revérifiez les proportions, les associations et autres indicateurs métier.
5. Validez selon les exigences métier publiques de la tâche ; après avoir sauvegardé le modèle, régénérez dans un nouveau processus en utilisant uniquement le modèle livré et l'entrée de la requête, et rapportez la qualité et le temps de la même exécution. Si l'objectif de cette itération est atteint, terminez la livraison ; sinon, conservez les résultats actuels et expliquez honnêtement, en continuant les tentatives à condition que le budget restant permette les vérifications ci-dessus.

Vérification, Installation Automatique, Validation

1. Réutilisez l'interpréteur spécifié par l'utilisateur ou existant du projet, et vérifiez les versions de Python, kaiwu-torch-plugin, kaiwu, torch. Exécutez une fois python -m pip check dans le même environnement, puis exécutez le mode --imports-only du script scripts/verify_kpp.py situé dans le répertoire de la compétence. Si le résultat de cette vérification existe déjà, réutilisez-le directement, puis passez à la tâche ; ne scannez pas l'environnement ni n'essayez un entraînement général.
2. Ne vérifiez le plan d'installation et n'installez que si un paquet manque ; en cas de conflit de dépendances, de paquet hors ligne, de problème de version Python ou de support wheel, consultez les instructions d'installation et choisissez un environnement compatible en fonction des métadonnées réelles.
3. Réutilisez l'échantillonneur compatible fourni par la tâche. Ne vérifiez la licence correspondante que lors du choix SDK SA/CIM ; n'interprétez pas l'absence de licence SDK comme une impossibilité d'entraînement avec tous les échantillonneurs locaux. L'initialisation de la licence et les restrictions non interactives sont décrites dans les instructions d'installation.
4. Validez le modèle sélectionné avec le programme réel de la tâche ; si aucun programme de tâche n'existe et qu'il est nécessaire de vérifier l'entraînement par échantillonnage SDK, exécutez uniquement le mode par défaut du script de validation. KPP_IMPORT_OK prouve uniquement l'importation ; KPP_TRAIN_OK prouve uniquement l'entraînement à petite échelle couvert par le script.

Conservez les journaux de vérification, les fichiers temporaires et les copies de validation dans le répertoire de la tâche. Le CIM cloud n'est utilisé que si la tâche le nécessite explicitement et qu'une licence de quota est disponible. Lors de l'appel à Kaiwu CIM, le task_name doit commencer par kpp-skill pour faciliter les statistiques backend ; par exemple kpp-skill-rbm-train. Si un nom de tâche existant ne contient pas ce préfixe, ajoutez kpp-skill- devant.

Contrats d'Entraînement et de Génération

Chemin d'importation publique pour BM et RBM :

from kaiwu.torch_plugin import BoltzmannMachine, RestrictedBoltzmannMachine

Lors du choix de SDK SA, SimulatedAnnealingOptimizer s'importe depuis kaiwu.classical. Le constructeur BM utilise BoltzmannMachine(num_nodes, quadratic_coef=None, linear_bias=None, device=None) ; RBM utilise RestrictedBoltzmannMachine(num_visible, num_hidden, quadratic_coef=None, linear_bias=None, device=None). Les réglages tels que le taux d'apprentissage et la décroissance du poids sont confiés à l'optimiseur PyTorch ; ne transmettez pas learning_rate, k, batch_size ou d'autres paramètres d'entraînement de bibliothèque au constructeur du modèle.

• RBM : get_hidden(batch, bernoulli=True) et sample(sampler) renvoient l'état conjoint visible+caché, avec une largeur de num_visible + num_hidden. Le nombre de lignes du lot de phase positive et du pool de phase négative peut être différent ; calculez les moyennes séparément. N'essayez pas de forcer le même nombre d'échantillons. objective(positive, negative) renvoie un scalaire. Écrivez directement positive = model.get_hidden(batch, bernoulli=True), ne dépaquetez pas la valeur de retour et ne concaténez pas la couche visible. get_hidden a par défaut bernoulli=False, la partie cachée étant des probabilités ; cela est légal pour l'espérance de la phase positive RBM, mais bernoulli=True est nécessaire pour livrer des échantillons binaires conjoints. Ne considérez pas les états probabilistes comme des échantillons binaires déjà échantillonnés. La capacité du pool est configurée selon l'échantillonneur réel ; pour SDK SA, utilisez SimulatedAnnealingOptimizer(size_limit=...) ; n'inventez pas de set_config ni n'ajoutez de paramètre num_solutions non défini à sample.
• Échantillonnage SDK : sampler.solve renvoie un tableau 2D ±1 avec des spins de référence en queue. La méthode sample de KPP normalise les spins de référence, supprime la colonne de queue et convertit en tenseur flottant 0/1. Ne supprimez plus de colonne ni ne convertissez la valeur de retour de sample. Lorsque l'utilisateur fournit des solutions de test fixes, solve renvoie l'ensemble des solutions inchangées ; n'attribuez pas chaque solution à des conditions différentes, ni ne répétez la première ligne pour atteindre le nombre d'échantillons. L'échantillonnage conditionnel doit vérifier simultanément les colonnes fixes et les colonnes libres converties de chaque solution, pas seulement la forme.
• Ordre d'entraînement : chaque étape : optimizer.zero_grad() → phase positive/négative → objective → backward() → step() ; objective et backward() ne doivent pas être placés dans torch.no_grad(). sample() renvoie un tenseur d'échantillonnage sans gradient ; le gradient provient du recalcul de l'énergie par objective() ; placer sample() dans no_grad ou non n'affecte pas l'entraînement. Maintenez le modèle, les données et les tenseurs manuels sur le même device. Vérifiez la largeur des phases positive et négative, la binarité de la phase négative, la finitude de la perte/du gradient, et la mise à jour effective des paramètres.
• BM / DBN : l'échantillonnage conditionnel utilise condition_sample(sampler, s_visible), qui fixe toujours les s_visible.shape[1] premiers nœuds, et appelle le solveur une fois par ligne de condition. Lorsque les positions connues diffèrent entre les lignes, réorganisez ligne par ligne : permutez linear_bias et quadratic_coef symétrisé en mettant les connues en premier, créez un BoltzmannMachine temporaire avec les paramètres permutés, appelez condition_sample, puis inversez la permutation des colonnes pour revenir à l'ordre original. Avant d'utiliser un DBN, appelez create_rbm_layer(input_dim), et après l'entraînement, mark_as_trained() avant forward/transform.
• QVAE : peut être construit en injectant encoder/decoder/bm/sampler, ou en sous-classant et en implémentant les quatre fabriques _create_*. La config contient num_latent_units / loss_type / dist_beta / kl_beta / weight_decay. La correction de la moyenne de Bernoulli est un paramètre facultatif ; lors de l'utilisation, appelez set_dataset_mean puis set_train_bias après la construction ; ne supposez pas que la définition ultérieure de la moyenne mettra automatiquement à jour le biais. La moyenne peut être un scalaire ou un tenseur par dimension, selon l'interface actuelle. encoder+decoder et BM utilisent deux optimiseurs ; la mise à jour de BM utilise bm_loss(q.detach(), weight_decay) ; référez-vous au paradigme du modèle. L'évaluation finale conserve la correction de la moyenne d'entrée et le biais de sortie de l'entraînement. q est les logits de l'encodeur, (q > 0).float() est une décision dure, pas la moyenne postérieure. La différence entre la reconstruction native et la moyenne est expliquée dans le paragraphe QVAE du document de référence. La reconstruction aléatoire ou le décodage de la moyenne postérieure réelle sont tous deux acceptables ; calculez et enregistrez les métriques à partir des logits finaux réels, en précisant la méthode utilisée ; ne considérez pas la qualité d'un petit entraînement comme une condition de passage de l'interface.
• QDiffusion : proposition : entrée [B,L], sortie [B,L,V] logits. Pour la complétion de contexte, utilisez des structures comme l'auto-attention pour permettre aux positions manquantes de lire les autres positions ; l'embedding positionnel + MLP ne peut apprendre que des préférences de position, même avec un taux de correspondance élevé, cela ne satisfait pas la complétion contextuelle. EnergyModel sous-classe implémente score_conditioned(noisy, candidate, attention_mask) pour produire [B,1]. SequenceTokenSpec s'importe depuis kaiwu.torch_plugin.qdiffusion, il n'est pas exporté au niveau supérieur. Lorsque seule la "taille du vocabulaire V" est donnée, la largeur de sortie reste V ; les identifiants spéciaux doivent se trouver dans ce vocabulaire et être séparés des tokens de contenu. N'interprétez pas V comme la taille du vocabulaire de contenu et ne l'étendez pas à V+4. Si les identifiants de contenu remplissent V ou si le mappage des identifiants spéciaux n'est pas clair, listez les mappages à confirmer dans la solution ; avant confirmation, n'utilisez pas une largeur de sortie élargie, et ne réduisez pas les catégories de contenu déjà présentes de l'utilisateur. Lorsque la proposition est entraînée à partir de zéro, effectuez d'abord un entraînement de complétion indépendant, puis figez-la et entraînez l'énergie ; la objective native tronque le gradient de la proposition en interne, elle ne peut pas être utilisée pour le pré-entraîner. L'entraînement utilise generator.objective({"targets" : batch}), la génération utilise generator.generate(init, max_steps=...). Avec freeze_proposal=True, seul le côté énergie est optimisé. Les conditions d'intégration complète sont décrites dans le paradigme du modèle.
• Sélection de Caractéristiques (MAIFS) : from kaiwu.torch_plugin import FeatureSelectionWrapper, QuadraticLinearSolver. Signature du constructeur : FeatureSelectionWrapper(model, feature_dim, lambda_reg=0.0, cardinality_k=None, min_selected_features=None, max_selected_features=None, solver="local_search", mask_update_epochs=None, input_feature_axis=-1, solver_kwargs=None). L'entraînement utilise sel.fit_weights(loader, loss_fn, optimizer, train_epochs) : le loader produit (x, y), loss_fn renvoie un scalaire, l'optimizer agit sur sel.model.parameters(). Le masque est rafraîchi tous les mask_update_epochs epochs ; s'il est None, le rafraîchissement n'a lieu que lors de l'appel manuel de update_mask(loader, loss_fn, hessian_mode="full"|"diagonal", max_samples=1000). Les résultats sont lus avec selected_indices(), num_selected(), get_support(). solver="local_search" ne nécessite pas de licence ; "sa", "kaiwu_cim" utilisent Kaiwu SDK et nécessitent une licence. Le temps d'exécution de update_mask est principalement dû à la résolution QUBO et à la projection sur la cardinalité, et croît rapidement avec le nombre de caractéristiques (environ 13–15 secondes pour 400 caractéristiques en local, le calcul des dérivées prenant moins de 1 seconde) ; hessian_mode et max_samples n'affectent que la partie dérivée, prévoyez du temps en fonction du nombre réel de caractéristiques. QuadraticLinearSolver().solve(Q, b) ne fait que convertir le terme QUBO en une matrice Ising avec un spin auxiliaire ; il ne résout pas.

Livraison et Validation

Pour une nouvelle tâche, livrez un script complet avec les données, les importations, la configuration, la boucle d'entraînement et la sortie des résultats ; pour modifier du code existant, ne modifiez que la partie nécessaire à la tâche. Si seul un plan ou un enregistrement d'environnement est demandé, sauvegardez le document spécifié ; après plusieurs itérations de clarification des besoins, mettez à jour la livraison et vérifiez que les fichiers ont bien été écrits. Les extraits QVAE/QDiffusion dans les documents de référence sont des illustrations structurelles contenant des variables contextuelles ; ils ne peuvent pas être utilisés comme scripts exécutables. En cas d'incertitude sur l'API, localisez kaiwu.torch_plugin.__file__ et vérifiez la signature et le code source réels. Rapportez l'interpréteur réel, les versions des dépendances et les résultats d'exécution ; la validation avec RBM ne garantit pas la validation avec d'autres modèles, GPU ou CIM cloud.