KPP エネルギー模型とサンプリング
PyTorch モデルと Kaiwu サンプラーの統合を担当します。モデルパラメータ、目的関数、最適化器は PyTorch に保持します。 互換性のあるサンプラーを介して Kaiwu ソルバーまたはタスク既存のサンプリングフローに接続します。通常の機械学習タスクを自動的にエネルギー模型タスクに書き換えないでください。
コンポーネントの選択
最初に、入力、出力、およびモデル化する関係に基づいて構造を選択し、選択したコンポーネントがタスク要件をどのように満たすかを説明します。 ユーザーが構造を指定した場合は、指定された構造に従います。自己選定の場合は、タスクが観測変数間の直接関係、 隠れ因子、階層表現、潜在変数の再構成、コンテキスト生成、または特徴選択のいずれを必要とするかを判断し、対応するコンポーネントを選択します。 モデルサイズはデフォルトの優先順位ではありません。まず能力と効果が一致するかを検証し、要件を満たす解決策間でトレーニングとサンプリングのコストを比較します。
| 問題に必要な能力 | コンポーネント | 選択の根拠 |
|---|---|---|
| 隠れ因子で観測パターンを説明、または可視/隠れ二部構造を学習 | RestrictedBoltzmannMachine | 隠れ表現がタスクに必要な分布学習に関与する；二値入力のみでは RBM 採用を決定できない |
| 二値ノードのペアワイズ相互作用を直接記述、または一部ノードを固定してサンプリング | BoltzmannMachine | ノードとその相互作用が問題変数に対応する；タスク指標を使用して、必要な関係を表現するのに十分かを検証する |
| 多層 RBM で階層的特徴を学習 | UnsupervisedDBN | タスクに層ごとの学習表現が必要、またはユーザーが明示的に RBM スタックを要求している |
| エンコード、再構成、およびサンプリング可能なエネルギー模型潜在事前分布 | QVAE | 再構成と潜在事前分布の両方がタスクに貢献する；通常のオートエンコーダーを QVAE に変更しない |
| コンテキストに関連する離散候補生成とエネルギー誘導 | QDiffusion | proposal が必要なコンテキストを提供し、energy がタスクに関連する候補の誘導を行う |
| 既存の PyTorch モデルの入力から特徴サブセットを選択 | FeatureSelectionWrapper | タスクに入力特徴の選択が必要であり、周期的に更新される 0/1 マスクを使用する |
二値データ、ラベル数、またはサンプルの出現順序だけでは選定を決定できません。 タスクで要求される関連、再構成、補完、予測などの結果で選択を検証します。インポートの成功や出力形状の一致だけではマッチしません。 タスクに高次関係やコンテキストが必要な場合、ペアワイズ統計が基準を満たすだけではモデルが十分であるとは見なせません。 BM と RBM の異なるトレーニング構造については モデルパラダイム を参照し、現在のタスクに関連する部分のみを読んでください。
これらは同じ KPP パッケージの異なるコンポーネントであり、6 つのプラグインを個別にインストールする必要はありません。 特徴選択は内部的に QUBO を解きますが、PyTorch モデルのトレーニングに貢献するため、このスキルに属します。 純粋な立地選定、スケジューリング、Max-Cut など、モデルに依存せずに直接最適解を求めるタスクは、Kaiwu SDK スキルを使用します。 同じタスクに組合せ最適化とエネルギー学習の両方が含まれる場合は、2 つのスキルをそれぞれロードし、それぞれのインタプリタを使用できます。
アプリケーションタスクの最小クローズドループ
- 代表的なデータを使用して、選択した構造のタスク効果を確認し、実際のトレーニングと生成の規模と時間を記録します。これに基づいて本番実行を計画し、総予算にモデル保存、新しいプロセスのロード、生成、レポート確認の時間を確保します。
- タスクで要求される完全なエントリポイントを早期に確立します。各検証後、現時点で最も効果的で再利用可能なモデル、設定、レポートを保存します。後続の実験では新しい出力ディレクトリを使用し、納品ディレクトリには常に実行可能なバージョンを保持します。
- バッチ生成は実際の行数で累積します：追加バッチごとにそのバッチの行数を累積し、要求された数に達した時点で切り取ります。最初に小さなリクエストで数、幅、値を確認します。バッチ数はサンプル数と等しくありません。
- 元の記録の直接コピー、モデルサンプリングによる自然な重複、および人為的選択を分けてチェックします。一般的な組み合わせは独立した生成で重複する可能性があります。重複レコードをフィルタリングしたり強制的に一意にしたりすると分布が変化するため、使用後は割合や関連性などのビジネス指標を再確認します。
- タスクの公開されたビジネス要件に従って検証します。モデルを保存した後、新しいプロセスで納品モデルとリクエスト入力のみを使用して再生成し、同じ実行の品質と時間を報告します。今回の目標に達した場合は納品を完了します。達しなかった場合は現在の成果を保持して正直に説明し、残りの予算で上記の確認が完了できることを前提に継続して試みます。
チェック、自動インストール、検証
- ユーザー指定/プロジェクト既存のインタプリタを再利用し、Python、
kaiwu-torch-plugin、kaiwu、torchのバージョンを確認します。同じ環境でpython -m pip checkを 1 回実行し、次にスキルディレクトリ内の scripts/verify_kpp.py を--imports-onlyモードで実行します。 既に今回のチェック結果がある場合はそれを再利用し、その後タスクに進みます。環境を追加でスキャンしたり、汎用トレーニングを試運転したりしません。 - パッケージがない場合のみ、インストール計画を確認してインストールします。依存関係の競合、オフラインパッケージ、Python バージョン、または wheel サポートに問題がある場合は、 インストール手順 に従って処理し、実際のメタデータに基づいて互換性のある環境を選択します。
- タスクで提供される互換性のあるサンプラーを再利用します。SDK SA/CIM を選択する場合のみ、対応するライセンスを確認します。 SDK ライセンスの欠如を、すべてのローカルサンプラーがトレーニングできない理由と見なさないでください。ライセンスの初期化と非対話型の制限については、インストール手順を参照してください。
- 実際のタスクプログラムで選択したモデルを検証します。タスクプログラムがなく、SDK サンプラーを使用したトレーニングを確認する必要がある場合のみ、検証スクリプトのデフォルトモードを実行します。
KPP_IMPORT_OKはインポートのみを証明します。KPP_TRAIN_OKはスクリプトがカバーする小規模トレーニングのみを証明します。
チェックログ、一時ファイル、検証コピーはタスクディレクトリに残します。クラウド CIM は、タスクで明示的に必要とされ、かつクォータライセンスがすでにある場合にのみ使用します。
Kaiwu CIM を呼び出す場合、task_name は kpp-skill で始める必要があります。これはバックエンド統計のためです。
例：kpp-skill-rbm-train。既存のタスク名にこのプレフィックスがない場合は、前に kpp-skill- を追加します。
トレーニングと生成の契約
BM と RBM の公開インポートパス：
from kaiwu.torch_plugin import BoltzmannMachine, RestrictedBoltzmannMachine
SDK SA を選択する場合、SimulatedAnnealingOptimizer は kaiwu.classical からインポートします。
BM のコンストラクタは BoltzmannMachine(num_nodes, quadratic_coef=None, linear_bias=None, device=None) を使用します。
RBM は RestrictedBoltzmannMachine(num_visible, num_hidden, quadratic_coef=None, linear_bias=None, device=None) を使用します。学習率、重み減衰などの設定は PyTorch のオプティマイザに任せ、
モデルコンストラクタに learning_rate、k、batch_size、またはその他のライブラリのトレーニングパラメータを渡さないでください。
- RBM：
get_hidden(batch, bernoulli=True)とsample(sampler)は可視+隠れの結合状態を返し、 幅はnum_visible + num_hiddenです。正相バッチと負相プールの行数は異なっていてもよく、それぞれ平均を取ります。 同じサンプル数に無理に合わせないでください。objective(positive, negative)はスカラーを返します。 直接positive = model.get_hidden(batch, bernoulli=True)と書き、戻り値をアンパックしたり、可視層を再度連結したりしないでください。get_hiddenはデフォルトでbernoulli=Falseであり、隠れ部分は確率です。これは RBM 正相の期待値としては妥当ですが、 二値の結合サンプルを提供する場合にのみbernoulli=Trueが必要です。確率状態を、すでにサンプリングされた二値サンプルと混同しないでください。 プール容量は実際のサンプラー設定に従います。SDK SA はSimulatedAnnealingOptimizer(size_limit=...)を使用します。set_configをでっち上げたり、sampleに未定義のnum_solutionsパラメータを追加したりしないでください。 - SDK サンプリング：
sampler.solveは末尾に参照スピンを含む ±1 の 2 次元配列を返します。KPP のsampleは内部で参照スピンの正規化、末尾列の削除、0/1 浮動小数点テンソルへの変換を行います。sampleの戻り値に対して、再度列の削除や変換を行わないでください。 ユーザーが固定テスト解を提供する場合、solveを呼び出すたびに解のセット全体をそのまま返します。各解を異なる条件に割り当てたり、 最初の行を繰り返してサンプル数を水増ししたりしないでください。条件付きサンプリングは、固定列と変換後の各解の自由列の両方を確認する必要があり、形状のみをチェックするだけでは不十分です。 - トレーニング順序：各ステップで
optimizer.zero_grad()→ 正相/負相 →objective→backward()→step()。objectiveとbackward()をtorch.no_grad()の中に配置しないでください。sample()は 勾配がないサンプリングテンソルを返します。勾配はobjectiveがエネルギーを再計算することで発生し、sample()がno_grad内にあるかどうかはトレーニングに影響しません。モデル、データ、手動テンソルは同じデバイスに保ちます。 正相/負相の幅、負相の二値性、損失/勾配の有限性、パラメータの実際の更新を確認します。 - BM / DBN：条件付きサンプリングは
condition_sample(sampler, s_visible)を使用します。これは常に最初のs_visible.shape[1]個のノードを固定します。 各行の既知の位置が異なる場合は、行ごとに再配置します：「既知を前方に」配置するようにlinear_biasと対称化後のquadratic_coefを置換し、置換後のパラメータで一時的なBoltzmannMachineを作成してcondition_sampleを呼び出し、その後列を元の順序に逆置換します。 DBN は使用前にcreate_rbm_layer(input_dim)を呼び出し、トレーニング完了後にmark_as_trained()を呼び出してからforward/transformを行います。 - QVAE：encoder/decoder/bm/sampler を注入してコンストラクタに渡すか、4 つの
_create_*ファクトリメソッドをサブクラス化して実装できます。 config にはnum_latent_units / loss_type / dist_beta / kl_beta / weight_decayが含まれます。 ベルヌーイ平均補正はオプションの設定です。使用する場合は、コンストラクタの後にset_dataset_mean、set_train_biasをそれぞれ呼び出します。 後で平均を設定しても、自動的にバイアスが更新されるとは見なさないでください。平均はスカラーまたは次元ごとのテンソルであり、現在のインターフェースに従います。 encoder+decoder と BM には 2 つのオプティマイザを使用します。 BM の更新はbm_loss(q.detach(), weight_decay)を使用します。モデルパラダイム を参照してください。 最終評価では、トレーニング時の入力平均補正と出力バイアスを保持します。qはエンコーダーのロジットであり、(q > 0).float()はハード判定であり、事後平均ではありません。ネイティブ再構成と平均の違いについては、リファレンスドキュメントの QVAE セクションを参照してください。 ランダム再構成、デコードされた真の事後平均のいずれも可能です。 実際の最終ロジットからメトリクスを計算して保存し、使用した方法を説明します。少量のトレーニングの品質をインターフェース合格条件と見なさないでください。 - QDiffusion：proposal は入力 [B,L]、出力 [B,L,V] のロジットです。コンテキスト補完が必要な場合、
自己注意などの構造を使用して、欠落位置が他の位置を読み取れるようにします。位置ごとの embedding + MLP は位置バイアスしか学習できず、
一致率が高くても、コンテキスト補完には不十分です。
EnergyModelサブクラスはscore_conditioned(noisy, candidate, attention_mask)を実装し、[B,1] を出力します。SequenceTokenSpecはkaiwu.torch_plugin.qdiffusionからインポートします。トップレベルではエクスポートされていません。 「語彙サイズ V」のみが指定された場合、出力幅は V のままにします。特殊 id はこの語彙内に収まり、コンテンツトークンと区別される必要があります。 V をコンテンツ語彙と解釈して V+4 に拡張しないでください。コンテンツ id が V をすべて占有している場合、または特殊 id のマッピングが不明な場合、 ソリューションで確認が必要なマッピングをリストアップします。確認前は、拡大された出力幅を採用せず、ユーザーの既存のコンテンツカテゴリを削減しないでください。 proposal をゼロからトレーニングする場合は、最初に独立した補完トレーニングを完了し、 その後 proposal を凍結して energy をトレーニングします。ネイティブのobjectiveは内部で proposal の勾配を遮断するため、proposal の事前トレーニングに使用できません。 トレーニングはgenerator.objective({"targets": batch})を使用し、生成はgenerator.generate(init, max_steps=...)を使用します。freeze_proposal=Trueの場合、energy 側のみが最適化されます。完全な統合条件については モデルパラダイム を参照してください。 - 特徴選択（MAIFS）：
from kaiwu.torch_plugin import FeatureSelectionWrapper, QuadraticLinearSolver。 コンストラクタシグネチャは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)。トレーニングはsel.fit_weights(loader, loss_fn, optimizer, train_epochs)を使用します。loader は(x, y)を生成し、loss_fnはスカラーを返し、optimizer はsel.model.parameters()に作用します。マスクはmask_update_epochsエポックごとに更新されます。Noneの場合は、手動でupdate_mask(loader, loss_fn, hessian_mode="full"|"diagonal", max_samples=1000)を呼び出した場合のみ更新されます。 結果はselected_indices()、num_selected()、get_support()で読み取ります。solver="local_search"はライセンスを必要としません。"sa"、"kaiwu_cim"は Kaiwu SDK を使用するため、ライセンスが必要です。update_maskの所要時間は主に QUBO 解決と数量投影にあり、特徴数が増えると急速に増加します（ローカルマシンで 400 特徴の場合、約 13～15 秒、 導関数計算は 1 秒未満）。hessian_modeとmax_samplesは導関数部分のみに影響するため、実際の特徴数に応じて時間を確保してください。QuadraticLinearSolver().solve(Q, b)は QUBO 項を 1 つの補助スピンを持つ Ising 行列に変換するだけで、解決は行いません。
納品と検収
新しいタスクでは完全なスクリプトを作成して納品し、データ、import、設定、トレーニングループ、結果出力を補完します。既存のコードを変更する場合は、タスクに必要な部分のみを変更します。
ソリューションや環境の記録のみが要求されている場合は、指定されたドキュメントを実際に保存します。複数回の要件追加後に納品を更新し、ファイルが書き込まれたことを確認します。
リファレンスドキュメント内の QVAE/QDiffusion の断片は構造の概要であり、コンテキスト変数を含みますが、そのまま実行可能なスクリプトとして使用することはできません。
API が不明な場合は、現在の kaiwu.torch_plugin.__file__ を特定し、実際のシグネチャとソースコードを確認します。
実際のインタプリタ、依存関係のバージョン、実行結果を報告します。RBM の合格は、他のモデル、GPU、またはクラウド CIM の合格を意味しません。