ドキュメント

自分の意思決定で Laya をファインチューニングする

typed-decisions ベンチマークでは、ベースのチェックポイントはゼロショットで偶然と同水準です(0.318 のランダムベースラインに対して 0.36 と 0.35)。一方、ファインチューニング後のチェックポイントは同じ 2,000 件の意思決定で 0.766 に達し、TypeSafe Jev の公表値 0.727 と教師の自己一致の上限 0.735 を上回ります。価値の大半はファインチューニングにあり、公開されているファインチューニングノートブックが Kaggle の無料 2xT4 GPU でループ全体を実行します。データセットを構築し、RLCD で学習し、キャリブレーション用の temperature を当てはめ、評価し、結果を Hub にプッシュします。このページはそのノートブックを辿り、データを自分のものに差し替えたときも要になる部分を指します。

同じループはパッケージに入っています。laya-train はラベル付きの判断を並べた CSV または JSONL から、1 つのデバイスでワンコマンドでそれを実行し、laya.train.finetune は Python から同じことをします。どちらも下で、ノートブックより先に説明します。

もう 1 つの実例 —— 有料 API なしで 16 GB の GPU 1 台に載せるブラウザエージェントの意思決定ヘッド —— はブラウザエージェントの意思決定ヘッドとしての Laya のファインチューニングにあります。

laya-train でのファインチューニング

laya-train(laya train でも可)は学習アイテムを組み立て、ファインチューニングし、学習前に 取り分けたスライスでキャリブレーション用の temperature を当てはめ、laya.load が開ける チェックポイントを保存します。1 つのデバイス —— CUDA、MPS、CPU —— で動きます。

CSV から

1 行が 1 つの意思決定で、テキストをある列に、正しいラベルを別の列に置きます:

laya-train --data tickets.csv --text-column body --label-column department \
           --base english --out ./tickets-checkpoint

ラベル列は、その重複を除いた値(最初に現れた順)に対する choice 質問になり、id は --question-id(既定 label)、instructions は --instructions が与えるものになります。 質問はチェックポイントの隣に questions.json として保存されるので、推論時にファインチューニング 済みモデルへ同じ質問を投げてください:

import json, laya

agent = laya.load("./tickets-checkpoint")
questions = json.load(open("./tickets-checkpoint/questions.json"))
print(agent.predict("We were billed twice for March.", questions)["answers"])

Excel からバイトオーダーマーク付きで保存されたファイルも通常どおり読まれます。テキストか ラベルが空の行はスキップされ、数え上げられます。

JSONL から

各行が 1 ケースで、1 つのケースは任意の型の複数の質問を投げられます。ラベルの形は 2 つ読まれ、 1 つのファイルで混在できます:

{"state": "We were billed twice for March.",
 "questions": {"department": {"type": "choice", "instructions": "Which team should handle this?",
                              "criteria": {"billing": "invoices, refunds", "technical": "bugs, outages"}},
               "urgent": {"type": "noul", "instructions": "Does this need an answer today?"}},
 "expected": {"department": "billing", "urgent": true}}
  • expected は質問ごとに 1 つの答えを持ち、laya-evals が読む形式なので、同じファイルで チェックポイントを学習し評価もできます:choice のラベル、noul には true/false、score には レベル(1.5 のような小数のレベルはその重みをレベル 1 と 2 に分けます)。--label-smoothing 0.1 は各答えの重みの 1 割を他の選択肢へ移します。
  • gold は質問ごとの教師の確率を持ち、ノートブックのスキーマです: {"department": {"probabilities": {"billing": 0.9, "technical": 0.1}}}。noul の確率は "false"/"true" をキーにし、score の確率はレベルインデックスを文字列にしたものを キーにします。

長い実行の前にデータを確認する

laya-train --data tickets.csv --text-column body --label-column department --dry-run

--dry-run は、--base のトークナイザーと config で学習アイテムを組み立て、重みの読み込みも 学習もせずに、読んだ行数、生成したアイテム数、スキップした質問とその理由、設定された既定値が 使う optimizer 更新の予算を出力します(optimizer 更新で実行規模を測るを参照):

理由 質問がスキップされたのは
empty_text、empty_label 行にテキストがなかった、または質問に答えがなかった
invalid_question、invalid_target 質問またはその答えが読めなかった
options_collapsed head 予算が 2 つの選択肢を同じトークンにしてしまった(#538)
options_beyond_max_len 質問の選択肢が max_len に収まらない

optimizer 更新で実行規模を測る

--epochs、--micro-batch、--grad-accum は実行がどれだけ学習するかを決めますが、重要な数は それが行う optimizer 更新の回数です。1 エポックは ceil(items / micro_batch) 個のマイクロバッチに 分割され、grad_accum 個のマイクロバッチごとに 1 回更新が走り、各エポックの最後の端数の窓に さらに 1 回加わります。それは含む数が少なくても 1 回ステップします:

updates = epochs * ceil(ceil(train_items / micro_batch) / grad_accum)

--dry-run と実行の開始はいずれもこの予算を、キャリブレーション後の学習件数から、実効バッチと ともに出力します:

optimizer budget: 1100 train item(s), effective batch up to 64 (micro_batch 8 x grad_accum 8), 72 optimizer updates over 4 epoch(s)

既定(4 エポック、実効バッチ 64)はノートブックのものです。typed-decisions の 6,000 件の 意思決定では、既定の 400 アイテムのキャリブレーションスライスが 5,600 学習アイテムを残すので、 既定の実行は 352 回の更新を使います —— スライスを取り分けない場合のみ 376 です。この数は 大きさの異なる実行を比べるための基準で、足切りではありません。同じ設定で 1,100 の学習 アイテムなら 72 更新(1,100 が分割前の件数で 10% のスライスが 110 を取り分けるなら 64)で、 #963 はそこで崩壊した head を測っており、 8 エポックでもタスク自体では失敗しました。したがって小さなデータセットは、同程度の更新回数に 届くにはより多くのエポックを必要とします。

実行が書き出すもの

--out は laya.load が読むレイアウト(model.safetensors、encoder/、tokenizer/、 rl_agent_config.json)に加えて、questions.json と、エポックごとに書き直される checkpoint_latest/ を得ます。クラッシュの代償は最大でも 1 エポックです。

config は実行が使った max_len と head_max_len、training.laya_train の下の学習設定、 training.laya_train_calibration の下のキャリブレーションレポートを記録します。キャリブレーション レポートには、質問の型ごとに、temperature が何件のキャリブレーションアイテムに載っているか、 その accuracy と平均信頼度、そして何を疑うべきかが入ります。同じ問題は実行中に警告として 出力されます:

laya.train: choice calibration: not fitted: 2 calibration items, fewer than 10, so the temperature stays 1.0

このような警告は、そのチェックポイントの信頼度が較正されていないことを意味します。より多くの データでの実行がそれらを当てはめるまで、min_confidence でゲートしないでください。

偶然のままの実行を診断する

ファインチューニングがクラスの事前確率を超えて上がらないとき、accuracy だけではタスクが 難しいのか予算が間違っているのかを言えません。ラベル符号化のポジティブコントロールがその 2 つを 分けます。答えを綴るタグ(たとえば label=<department>; )をすべての学習テキストとテスト テキストの先頭に付け、そのコピーでファインチューニングします。モデルはそのタグから答えを 読めるので、同じ予算に自明に学習可能なシグナルが用意されます。

  • ポジティブコントロールが学習できない → タスクではなく、予算、最適化、実行設定を疑って ください。
  • ポジティブコントロールが 1.00 に達するのに実際のタスクが事前確率のまま → 証拠は、更新が 少なすぎるのではなくタスクか表現の難しさを指します。 #963 は 8 エポックで両方を測りました。 ポジティブコントロールは 1.00 に達したのに、実際のタスクは依然として崩壊しました。

通ったポジティブコントロールが示すのは、その実行がわざと易しくしたシグナルを当てはめられる ことだけです。実際のタスクが学習可能であることや、チェックポイントが汎化することの証明では ありません。

ln K のプラトー付近での離陸もシード依存なので、1 回の実行はどちらの証拠にもなりません。 #963 は、同一のデータと設定で、15 回のうち 9 回がプラトーを離れ、6 回は 32 エポック内で離れませんでした。タスクが学習不可能、または予算が 十分だと結論づける前に、異なるシードで実行を繰り返し、min_confidence でゲートする前に実行が 出力する崩壊警告を読んでください。

オプション

フラグ 既定 何を変えるか
--base convaiinnovations/laya 開始するチェックポイント:ディレクトリ、組み込み名(english、multilingual、typed-decisions)、または Hub リポジトリ id
--loss rlcd rlcd はノートブックの目的関数。soft-ce はソフトクロスエントロピーだけで学習する(#741)
--shuffle-options オフ エポックごとにランダムな選択肢順で choice 質問を再エンコードし、答えも合わせて移す
--label-smoothing 0.0 単一の答えから移す重み
--freeze-encoder オフ 意思決定ヘッドだけを学習する。小さな GPU や CPU に載るが、完全なファインチューニングよりはるかに得るものが少ない
--epochs、--micro-batch、--grad-accum 4, 8, 8 ノートブックの 4 エポックと実効バッチ 64
--encoder-lr、--head-lr 2.5e-5, 1e-4 学習率
--max-len、--head-max-len ベースチェックポイントのもの トークン予算。ノートブックは 1024 と 256 を使う
--device、--seed auto、0

混合精度は CUDA で有効です。fp16 が fp32 より遅い GPU(たとえば GTX 16xx カード)では、 Python から TrainConfig で amp=False を設定してください。

オプションの価値

#887 から、1 実行あたり T4 1 台で、ノートブック の設定で convaiinnovations/laya を完全にファインチューニングしたもの。

typed-decisions について(6,000 件の学習意思決定、2,000 件のテスト意思決定すべて、1 シード):

実行 accuracy ECE 選択肢を逆にすると変わる choice の答え
ベースチェックポイント 0.362 0.174 0.357
--loss rlcd(既定) 0.7715 0.150 0.065
--loss soft-ce 0.790 0.157 0.078
--loss soft-ce --shuffle-options 0.7875 0.159 0.062

MASSIVE の英語意図について、質問あたり 20 選択肢で(11,514 学習行、2,974 テストケースすべて、 それぞれ 3 つのシャッフル順でも解答。--loss soft-ce、行ごとに 2 シード):

実行 accuracy 選択肢を並べ替えると変わる答え
ベースチェックポイント 0.730 0.187
--shuffle-options なし 0.936 0.026
--shuffle-options あり 0.941 0.019

4 選択肢では、ファインチューニングだけで答えは並べ替えに対して安定し、シャッフルは測定できる ものを何も変えません。20 選択肢では accuracy を 0.55 ポイント上げ、変わる答えを約 4 分の 1 削り、どちらも 2 シードにわたって有意で、学習時間は約 14% 増えます。質問が多くの選択肢を持つ ときに使ってください。

Python からのファインチューニング

laya.train.finetune は laya-train が呼ぶものです:

import laya
from laya.train import TrainConfig, finetune

report = finetune("train.jsonl", "english", "./my-checkpoint",
                  TrainConfig(loss="soft-ce", shuffle_options=("choice",)))
print(report["train_items"], report["skipped"], report["calibration"])

agent = laya.load("./my-checkpoint")

TrainConfig() は上の表の既定に加えて、コマンドが公開しない設定を持ちます:amp と gradient_checkpointing(CUDA では既定でオン)、キャリブレーションスライス(calib_max=400 アイテムまたは calib_frac=0.1 の小さいほう)、そして option_layout。返されるレポートは train_items、calibration_items、skipped、epoch_loss、当てはめた temperature と temperature_by_options、そして calibration レポートを持ちます。自分のデータパイプラインには、 train_model と calibration_records が finetune の組み立て元の 2 つの半分です。 API リファレンスがそれらすべてを列挙しています。

ノートブックの手順

# ステップ 起きること
1 環境 2 台の T4 GPU が見えていて割り当てられていることを確認します
2 インストール laya、transformers、datasets と学習用の依存関係
3 前処理 1,200 件の学習ケース(6,000 件の型付き意思決定)がソフトターゲット付きのトークン化済みアイテムになり、両方の DDP ランク用にディスクへ書き出されます
4 学習 torchrun --nproc_per_node=2 の下で train_ddp.py を 4 エポック
5 キャリブレーション 型ごとに 1 つの temperature を、学習前に取り分けたスライスで当てはめます(学習スクリプト内、最終エポックの後)
6 評価 公式の test スプリットをファインチューニング済みチェックポイントで解答(400 ケース、2,000 件の意思決定)。ケースごとのレイテンシ付き
7 指標 accuracy、soft accuracy、Brier、ECE、score MAE、within-one-level、KL/TV、レイテンシのパーセンタイル。Jev と教師の上限に対する直接対決の表
8 公開 (任意)実行自身の数値から作ったモデルカード。フォルダを Hub へアップロード
9 レポート 指標表とワークフローごとの accuracy を含む benchmark_report.json

Kaggle の設定:Accelerator は GPU T4 x2、Internet は On。出力は /kaggle/working/laya_finetuned_typed_decisions に置かれます。

学習レシピ

RLCD はベンチマークの正解分布で学習し、ハードラベルでは学習しません。各アイテムは教師が各選択肢に割り当てた確率を持ち、損失の両方の半分がそのターゲットを読みます。

  • サンプリングしたノイズ付きロジット射影に対する方策勾配の項(GRPO 風:アイテムあたり 4 サンプル、探索ノイズを 0.4 → 0.1 にアニーリング)。適切なスコアリングルール(球面 0.75、順位確率 1.0)で報酬付けします。
  • 同じ分布に対する全重みのソフトクロスエントロピーの項。

16 GB のカード向けにノートブックが設定するつまみ:

エポック 4
実効バッチ 64 系列(マイクロバッチあたり 8、GPU 2 台、蓄積 4 ステップ)
学習率 encoder 2.5e-5、head 1e-4 —— AdamW、コサインスケジュール
メモリ fp16 autocast、encoder と head の勾配チェックポインティング、勾配ノルムのクリップ 1.0
系列予算 max_len 1024、head_max_len 256、max_tokens_per_batch 4096

2xT4 での実行時間は、デモなら分単位、実データなら時間単位です。デモの 6,000 件の意思決定で約 4〜6 分、約 30k 問で 4 エポックならおよそ 4〜5 時間です。

自分のデータに向けるには、2 つの load_dataset 呼び出しを差し替え、行のスキーマを保ってください。各ケースは state・questions・gold(質問ごとの教師確率)を持ち、前処理器がそれらをアイテムに変えます。質問の型は choice・score・noul です。state に対してこれらで表現できるものは何でも対象になります。

キャリブレーションは実行の一部

これはループをコピーするときに最も落とされやすいステップで、誰かが信頼度でゲートした瞬間に要になります。

ノートブックはランクに分割する前に学習データからキャリブレーション用のスライスを取り分けます(最大 400 アイテム、または 10%、固定シード、すべてのランクで同一)。実行がすでに学習したアイテムに temperature を当てはめると、キャリブレーションではなく当てはまりを測ってしまいます。モデルはそれらに対してほぼ確信を持ってほぼ正しいので、最適化器は柔らかくする対象がなく、縮退したスケールを返します。

最終エポックの後、ランク 0 が質問の型ごとに 1 つの temperature(choice、score、noul)を、log-temperature に対する LBFGS で当てはめ、[0.1, 10] にクランプします(10 アイテム未満のスライスでは 1.0、当てはめが例外を投げたら 1.2)。値は temperature として rl_agent_config.json に入り、ノートブックは同じ書き込みで継承した temperature_by_options を削除します。それらの古いバケット値は推論時に優先され、新しい当てはめを黙って覆い隠すからです。

Temperature スケーリングは argmax、つまり accuracy を変えません。動くのは信頼度です。出荷時のチェックポイントは過信なので、しきい値に頼る前に当てはめ、改善を主張する前に未見データで結果を評価してください。config 永続化の回帰はダウンロードも学習もなしで走ります。

python tests/test_calibration_persistence.py

信頼する前に評価する

評価は公式の test スプリット全体のパスです。Agent Trace Observability、Customer Service、Invoice Processing、Security Incidents にわたる 400 ケース、2,000 件の意思決定です。accuracy、soft accuracy、Brier、ECE(laya.common.ece_score 経由)、score MAE、within-one-level、レイテンシのパーセンタイルを計算し、参照行が固定された直接対決の表を作ります。

モデル 種別 accuracy ECE
TypeSafe Jev 1.13.0 汎用 0.727 0.144
ModernBERT-base (149M) 専用 0.646 0.179
Teacher Self-Agreement 上限 0.735 —
Laya(公開チェックポイント) ファインチューニング済み 0.766 —

自分の実行の Laya 行も同じ方法で計算されます。ノートブックは実行自身の数値から表を組み直します。真似する価値のある習慣が 2 つあります。気にするスライス(言語、ワークフロー)を未見データの中に保つこと、そしてキャリブレーションを accuracy の隣に報告することです。学習シグナルはラベルだけでなく分布だからです。数値が出たら、リポジトリの Discussions への投稿が共有の場です。ベンチマークと既知の制約はリポジトリ直下の BENCHMARKS.md にあります。

Hub へのプッシュ

公開セルはループの最後の一マイルで、意図的に退屈に作られています。

  1. 書き込み権限のある HF_TOKEN を Kaggle に置きます(Add-ons → Secrets)。欠けていれば、セルは正確な手順とともに例外を投げます。
  2. 宛先リポジトリを設定します。出荷時のセルはプロジェクト自身の名前空間の名前を既定にしているので、実行前に変えてください。
  3. 実行します。この実行の比較表から数値を取ったモデルカードを書き、model.safetensors、encoder/、tokenizer/、rl_agent_config.json、カード、ベンチマークレポートをアップロードします。

結果は他のチェックポイントと同じように読み込めます。ファインチューニング専用の API はありません。

import laya

agent = laya.load("your-org/your-checkpoint")   # the repo you just pushed
result = agent.predict(state, questions)

ローリングする checkpoint_latest/ はエポックごとに上書きされるので、Kaggle のタイムアウトや OOM の代償は実行全体ではなく 1 エポックで済みます。

注意すべきこと

  • ループはターゲット次第です。 RLCD は自分の質問に対して教師の分布を模倣します。学習の前に(または並行して)教師の信頼度を集め、その品質を上限として扱ってください。
  • キャリブレーション用スライスは意図的に小さいです。 最大 400 アイテムまたは 10% —— 型ごとの 3 つのスカラーには足りますが、検証には足りません。自分用の評価データは別に取り分けてください。
  • ラベルは 3 つのプリミティブに合う必要があります。 意思決定が choice でも尺度でも yes/no の確率でもないなら、まずそのどれかに整形してください。鋭い角は 2 つすでに文書化されています。選択肢が多いと信頼度の選択が劣化し(#394)、強制選択の否定は state よりも質問に従うことがあります(#377)。
  • 重みだけでなく config も出荷してください。 削除した temperature_by_options は、コピーした config に残るとキャリブレーションを黙って外してしまう部分です。