各結果の背後にある証拠をたどる。

キャンペーン、構成、実行を区別する

キャンペーンは問いを担います。たとえば、ベースラインと適応版を比較するといったものです。構成は技術的な選択を記述します。実行（run）はその構成を実際に試みたものであり、シード、開始、終了、ステータスを持ちます。したがって、同一の試行が2回あれば、2回目が中断された試行を置き換えるものであっても、2つの識別子を持ちます。

同じアーティファクトを複数のデータセットで、あるいは新しいメトリクスで評価する場合は、評価識別子を追加しましょう。これにより、新しいモデルと、既存モデルの新しい評価を混同することを避けられます。再開した試行は、それを先行する試行とロードしたチェックポイントに結び付けます。

MLflowもまた、実行・パラメータ・メトリクス・アーティファクトを軸にトラッキングを整理します。この区別は、単純なファイルフォルダにおいても役立ちます。いつものツールで適用できます。始めるにあたって特定のトラッキングプラットフォームは必要ありません。

技術的な出典: MLflow — 実行、パラメータ、メトリクス、アーティファクト

実際に実行されたマニフェストを書く

デフォルト値や起動引数を適用した後の、解決済みのパラメータを保存しましょう。元の構成ファイルは、デフォルトのバッチや実行時に変更されたオプションを省略しているかもしれません。実際に用いられたものを、コードのコピーまたは不変のリビジョン、および未保存の変更の状態とともに記録します。

マニフェストは、モデルとトークナイザのバージョン、ソフトウェア環境、実際に使用したGPU、精度、データ、シード、メトリクスの定義も結び付けます。インストールの手引きになるのではなく、その試行を記述するものです。単位を明記しましょう。秒、バイト、トークン、ポイント、または測定に応じて0から1の割合などです。

開始時点ではステータスは実行中であり、終了時には、確認した内容に応じて完了・失敗・中断のいずれかになります。忘れられたバージョンを、現在インストールされているバージョンで後から埋めないようにしましょう。不明な情報は不明と記し、それに依存する結論を限定します。

フォルダ名を超えてデータを識別する

donnees/final のようなパスは、安定したバージョンを指しません。ファイルやサンプルのインベントリ、分割、変換手順を保存しましょう。ラベルを修正したり行をフィルタリングしたりする場合は、新しいバージョンを作成し、前のバージョンとの関係を保ちます。古いスコアは、引き続きその古いデータを指し続けるべきです。

Hugging Face Datasets は、データセットの状態とその変換にフィンガープリントを関連付けてキャッシュを管理します。この仕組みは有用ですが、データの由来と前処理もあわせて保存する必要があります。特にハッシュ化できない変換はランダムなフィンガープリントにつながることがあります。キャッシュの識別子だけでは、出所の記録を置き換えることはできません。

確定したアーティファクトには、サイズとファイルのフィンガープリントを加えましょう。コピーの前後で計算したSHA-256ダイジェストを使えば、バイト列が保存した基準と一致することを確認できます。ただし、それはラベルの品質や利用権、分割間のリークの有無を証明するものではありません。

技術的な出典: Hugging Face Datasets — フィンガープリントと変換 · Python 3.14 — hashlib によるファイルフィンガープリント

メトリクス、予測、アーティファクトを結び付ける

メトリクスの1行は、run、評価対象のアーティファクト、評価データセット、メトリクスのバージョンとその適用範囲を特定できるべきです。値が中間チェックポイント、最終モデル、サブグループのいずれに関するものかを明記してください。採用した点がどのファイルに対応するのか分からなくなれば、曲線だけでは不十分です。

予測は、入力ID、ステータス、評価に必要な情報とともに保存してください。期待される参照は、バージョン管理された別ファイルに置いても構いません。構造化出力の場合は、生の結果、パース済みの結果、判定を区別してください。パースの修正が元の出力を上書きしてはいけません。

MLflowを使うと、メトリクスをモデルやデータに紐付けられます。ファイルで運用する場合も、明示的な識別子によって同じ原則を適用してください。アーティファクトの一覧を読みやすく保ちましょう。重みまたはアダプタ、生成パラメータ、出力、評価レポート、意思決定メモです。スクリーンショットがこれらのファイルの代わりになると考えないでください。

技術的な出典: MLflow — メトリクス、モデル、データセットを紐付ける

例：6つの実行と、不足を隠す重複1つ

2つの構成と3つのシードによる分類の例を考えます。これで6つのrunが予定されます。各runは同じ300個の評価IDを予測する必要があります。つまり完全なフォルダには、6 × 300 = 1,800組の一意な (run_id, input_id) が必要です。この計算は期待される棚卸しを表すものであり、実際に実行された実験ではありません。

あるファイルに300行あるものの、ID doc-042 が2回現れ、doc-117 が欠けているとします。行の合計は正しく見えますが、一意なIDは299個しかありません。このrunは、異常が説明され修正されるまでカバレッジ検査に失敗します。

各実行をその後、コーパス全体と長文テキストのサブグループで評価すると、ある指標について12行の指標値が得られます。それでも実行は6つであり、独立した学習12回ではありません。この区別を保つには、評価キーにスコープを含める必要があります。

読みやすい意思決定で記録を締めくくる

runを完了と宣言する前に、ファイルの存在と開けるかどうか、IDの一致、再計算可能なメトリクス、各エラーのステータスを確認してください。技術的には完了した試行でも、品質不足により却下されたままのことがあります。この2つの状態は分けて保ってください。

意思決定メモには、問い、比較したバリアント、事前に宣言した基準、採用した結果、除外の理由をまとめます。「最新のモデル」ではなく、run_id とアーティファクトのパスを記載してください。限界も加えます。反復回数が少ない、サブグループが不十分、バージョンが見つからない、比較が不可能になった、などです。

後からの修正は痕跡を残す必要があります。新しい評価、新しいレポート、変更理由です。以前の結論は、特定された履歴バージョンとして保ち、現在の意思決定として現れないようにしてください。最後に、エクスポートしたコピーが移動先フォルダから開けることを確認します。

不要な収集と再現の約束を避ける

証拠に必要なフィールドを収集し、すべての環境変数やターミナル履歴を集めてはいけません。設定やURLにトークンが含まれることがあります。秘密情報を除いた共有可能なバージョンを用意し、非公開にすべきデータは許可された場所に保ってください。技術的な試行IDに人名を含める必要はありません。

完全なフォルダは、実験をやり直して理解できる可能性を高めます。ただし、プラットフォームやバージョン間で数値が一致することを保証するものではありません。PyTorchはこの再現性の限界を文書化しています。プロトコルをたどれること、アーティファクトを再読み込みできること、数値を正確に再現できることを区別してください。

IteraGPUのノートブックは、目標、パラメータ、意思決定を有用な参照とともに保管できます。runを起動したり、ファイルやテレメトリを自動収集したりはしません。思考の索引として使い、アーティファクトのフォルダは自分のバックアップに保管してください。

技術的な出典: PyTorch 2.14 — 環境間の再現性の限界

実用的な質問