このページは GitHub の文書 から作っています。

CSE Config Modding Guide 🐸🎛️

23 Parameters to Tune, Break, and Study

Version: Draft 0.2 Target: CSE Course Edition / Frog Companion: HANDBOOK.md Draft 0.4 / REFERENCE.md

0. このGuideの目的

CSEには23個のConfigがあります。

API Referenceは、

「この設定は何をするか」

を説明します。

このModding Guideは、

「いじると何が起こるか」 「どのスイッチをONにすると効き始めるか」 「どこまでいじると壊れるか」 「何を観察すると面白いか」

を扱います。

各Configを、

で見ていきます。

Evidence LabelはHandbookと共通です。

[CODE] 実コード [DOC] README / REFERENCE [EXP-C] Course Editionで確認 [EXP-R] Research Editionで確認 [IDEA] 未検証の実験案

1. 重要：Configには「前提スイッチ」がある

[CODE][EXP-C]

CSEのConfigは、すべてが独立して働くわけではありません。

例えば、

activation_decay

を変更しても、Frogの標準設定では予測が変わりません。

なぜなら、

activation
 ↓
history term
 ↓
candidate score

という経路でしかactivationが予測scoreへ入らないのに、

history_boost = 0

がFrogの既定だからです。

つまり、

部品は動いていても、その出力先のスイッチがOFFなら最終予測には届かない。

これはCSEの構造を理解するうえで重要です。

2. Prerequisite Map

[CODE][EXP-C]

さらにtop_k_edgesには別の仕事があります。

候補確率を上位K個へ絞る機能は、

positive candidateがK個を超えたとき

に初めて違いが表面化します。

つまり同じConfigでも、

top_k_edges
├─ candidate limiting
└─ activation spreading

で発動条件が異なります。

3. Config Map

Prediction
├─ probability_mode
├─ temperature
├─ top_k_edges
├─ history_boost
├─ refractory_steps
└─ max_consecutive_repeats

Context
├─ pair_context_capacity
├─ pair_context_boost
├─ context_trace_decay
└─ context_projection_boost

Learning
├─ learning_rate
├─ max_edge_weight
├─ weight_decay
├─ weight_decay_scope
├─ temporal_learning_window
├─ direct_learning_window
├─ temporal_learning_decay
└─ normalize_direct_scores

Activation
├─ activation_decay
├─ threshold
└─ activation_cap

System
├─ max_nodes
└─ seed

4. 全23Config早見表

5. probability_mode

Default: "softmax"

[CODE][DOC]

Frog(probability_mode="softmax")
Frog(probability_mode="linear")

どちらの場合も、まずcandidate scoreが計算されます。

そして、

positive scoreの上位top_k_edges候補だけ

が確率化されます。

つまり、

scores
 ↓
Top-K candidate selection
 ↓
softmax OR linear normalization

です。

softmax

score / temperature
 ↓
exp()
 ↓
normalize

linear

score
 ↓
normalize

注意

linearにするとTop-Kが無効になるわけではありません。

softmaxでもlinearでもTop-K candidate selectionは先に行われます。

おすすめ実験

同じscores()に対して、

softmax
vs
linear

のprobabilities()を比較。

6. temperature

Default: 0.8

[CODE][EXP-C]

probability_mode="softmax"時のみ有効です。

低くすると

確率分布が尖ります。

高くすると

分布が平坦化します。

[EXP-C]

0.05 → 下 ≈ 1.0
10.0 → 下 ≈ 0.525

Prerequisite

probability_mode = "softmax"

linearではtemperatureは使われません。

おすすめ実験

0.05
0.2
0.8
2
10

を比較。

7. top_k_edges

Default: 3

[CODE]

CSEで最も注意が必要な名前の一つです。

二つの役割があります。

A. Candidate Limiting

positive candidateのうち、上位K個だけを確率化します。

これは、

positive candidates > top_k_edges

のときに初めて結果差が出ます。

B. Activation Spreading

各Nodeから活性を広げるとき、強いK本のEdgeだけを使用します。

Prerequisite

[EXP-C]

Frog既定では、

history_boost = 0

なので、activation propagationを変えても、その差がcandidate scoreへ入りません。

Spreading側の効果を見るなら、

Frog(
    history_boost=0.35,
    top_k_edges=...
)

のようにする必要があります。

何が壊れる？

Kが小さすぎる:

有望な候補や伝播経路を早期に切る。

Kが大きすぎる:

弱い候補やEdgeも残る。

8. history_boost

Frog default: 0.0 Engine default: 0.35

[CODE]

activation historyをcandidate scoreへ足す倍率です。

このConfigはactivation系設定の主電源に近い存在です。

activation
 ↓
× history_boost
 ↓
candidate score

0

Frog既定。

Activationは内部で存在しても、history termとしてscoreへ入りません。

正にすると

最近活性化した記号を押し上げます。

負にすると

[EXP-C]

history_boost=-0.3では、教材実験で候補scoreがすべて消え、

<END> = 1.0

となりました。

つまり負値は、

最近の記号を抑制する

程度では済まず、candidate set全体を消す場合があります。

Research Result

[EXP-R]

H-GEN-2では、

history_boost = 0.35
        ↓
history_boost = 0

へ変更すると、最初の生成逸脱が遅れました。

つまりこの実験では、

History termを外した方が生成崩壊が遅くなった

という結果です。

「Historyを入れると必ず悪い」という一般則ではありません。

9. refractory_steps

Default: 0

[CODE][EXP-C]

最近出た記号を何個前まで禁止するか。

非常に良い教材Configです。

10. max_consecutive_repeats

Default: 2

[CODE]

Refractoryの例外規則です。

Prerequisite

refractory_steps > 0

でなければ意味を持ちません。

これは、

「禁止されているけど、学習済みself-loopなら何回まで許す？」

を決めます。

おすすめ実験

A → A → A → B

を学習して、

refractory_steps = 2
max_consecutive_repeats = 1 / 2 / 3

を比較。

11. pair_context_capacity

Frog default: 2048

[CODE][EXP-C]

直前2Tokenの組を何種類保存するか。

0で無効。

[EXP-C]

No-Context Frogでは教材例が、

下 0.5
右 0.5

になりました。

Capacityが満杯になると、弱いPairから追い出されます。

12. pair_context_boost

Default: 1.0

[CODE]

ここはScaleに注意が必要です。

Pair rowは使用時に、

pair_scores / pair_total

と合計1へ正規化されます。

そのあと、

× pair_context_boost

してcandidate scoreへ加えられます。

一方、Frog既定ではDirect scoreは、

raw edge weight

のままです。

Edge weightは最大10.0まで持てます。

したがって標準状態では、

DirectとPairはそもそも同じScaleではありません。

normalize_direct_scores=True

これをONにするとDirect側も合計1へ正規化され、

Direct : normalized
Pair   : normalized

となります。

このとき両者は比較しやすいScaleになります。

Research connection

[EXP-R]

H-LEAK-1のResearch Editionではnormalize_direct_scores=Trueを使用していました。

そこでは誤候補への最終probability massについて、

direct         : 約87〜91%
backoff mixing : 約9〜13%
pair memory    : 0%

でした。

Pair Memoryは正しいカテゴリだけを指し、漏洩源になりませんでした。

ただしResearch EditionにはCourse Editionに存在しないbackoff mixingがあります。

13. context_trace_decay

Default: 0.0

[CODE]

Traceが1Tokenごとにどれだけ残るか。

Prerequisite

context_projection_boost > 0

でなければ、Traceを変更してもpredictionへ反映されません。

これは非常に重要です。

Traceを作る
 ↓
projectionがOFF
 ↓
scoreへ入らない
 ↓
predictは変わらない

Evidence

[EXP-C]

単純な教材例ではTraceを有効化しても変化なし。

[EXP-R]

Research Editionの追加Trace機構も主に負方向。

両者は同じ機構ではないので結果を混同しません。

14. context_projection_boost

Default: 0.0

[CODE]

TraceをEdge構造へ投影し、candidate scoreへ足す倍率です。

ただし重要な制約があります。

Projectionは、

すでにpositive scoreを持つcandidate

にしか加算されません。

つまり、

score = 0

だった全く新しいcandidateを、Traceだけで突然生み出すことはできません。

概念的には、

existing candidates
       ↓
Traceが順位・scoreを補正

です。

何が壊れる？

Boostを上げても、

Candidate generation能力そのものが増える

わけではありません。

既存候補間のbiasが強まります。

15. learning_rate

Default: 0.1

[CODE]

1回観測するたびにEdgeをどれだけ増やすか。

低い:

ゆっくり学習。

高い:

少数観測で強く学習。

高すぎるとmax_edge_weightへ早く到達します。

16. max_edge_weight

Default: 10.0

[CODE]

Direct / Context / Pair learningの上限。

低いと早く飽和。

高いと頻度差を長く保持できます。

17. weight_decay

Default: 0.9995

ここは重要な修正点です。

[CODE][EXP-C]

weight_decayが減衰させるのは、

direct weights
context weights

です。

Pair Context Memoryにはweight_decayが適用されません。

つまり、

Direct / Context
 ↓
decay

Pair Memory
 ↓
decayしない

です。

[EXP-C]

x → y → zを3系列×3エポック(36学習step)、weight_decay=0.9で学習した実験では、

• Direct weightの合計は、減衰なし(1.0)の3.6に対して0.98まで減衰
• Pair Memoryの合計は2.7(= 0.1 × 27回の更新。減衰なしの値そのもの)

でした。

したがって、

FrogのPair Memoryはweight_decayによる忘却をしない。

正確には、新しいPair学習によって値は更新されますが、weight_decayによる時間減衰を受けません。

17.1 Trap A — 重みが減っても確率が変わらない

例えば、

A:
朝 → 起きる → 歯磨き

B:
夜 → 寝る → 夢

のようにPrefixが競合しない場合。

古いDirect weightが減っても、

朝 → 起きる

の候補が歯磨きしかなければ、

P(歯磨き) = 1.0

のままです。

絶対scoreが下がることと、正規化後確率が下がることは別。

17.2 Trap B — 競合すると確率に見える

[EXP-C]

A = [["朝", "起きる", "歯磨き"] * 4]
B = [["朝", "起きる", "二度寝"] * 4]

のように同一Prefixで競合させると、

となりました。

この競合実験で、古い候補のraw scoreは、

3.26 → 2.29

へ低下しました。

この数値は、

「確率が1.0のままだった非競合ケース」

のものではありません。

17.3 Pair Memoryが忘れないという意味

ここがCSEとして面白いところです。

同一PrefixのPairを学習している場合、

Direct
 └─ weight_decayを受ける

Pair
 └─ decayしない

ので、長期的には両者の相対バランスが変化する可能性があります。

したがってCompetitive Forgettingは、

CSE全体が一様に忘れている

と解釈してはいけません。

より正確には、

Direct / Context系は減衰する一方、Pair Memoryはweight_decayでは忘れない。

です。

これは今後の重要な教材テーマです。

18. weight_decay_scope

Default: "global"

[CODE]

global
active_rows

から選択。

globalは全Direct / Context weight。

active_rowsは現在学習に関係するRowだけ。

なお、

どちらを選んでもPair Memoryはweight_decay対象外

です。

19. temporal_learning_window

Default: 1

[CODE]

何個前まで遡って現在Tokenとの関係を学習するか。

1
→ 直前だけ

2
→ 2個前まで

3
→ 3個前まで

ただし、すべてが同じMatrixへ入るわけではありません。

Frog既定の、

direct_learning_window = 2

では、

distance 1 → direct weight
distance 2 → direct weight
distance 3+ → context weight

です。

重要

frog.edges()が表示するのはDirect Edgeです。

したがって、

A → x → x → B

でAからBはdistance 3。

temporal_learning_window >= 3なら関係自体は学習できますが、

A → B

はcontext weightへ入るためedges("A")には出ません。

おすすめ実験

A B C D E

で、

window = 1 / 2 / 3 / 4

を変える。

観察:

distance 1–2:
edges()

distance 3+:
Trace + Projectionを有効にして予測への影響を見る

20. direct_learning_window

Default: 2

[CODE]

Temporal Learning Window内の関係を、

Direct
or
Context

どちらへ保存するかの境界。

Prerequisite

temporal_learning_window >= 2

でなければ実質的な意味がありません。

例えば、

temporal_learning_window = 1

ならdistance 2以上をそもそも学習しないため、

direct_learning_window = 1
2
3

を変えても差が出ません。

低くすると

遠い関係をContext Matrixへ回します。

高くすると

遠い関係までDirect Matrixへ入れます。

21. temporal_learning_decay

Default: 0.5

[CODE]

距離が遠い関係をどれだけ弱く学習するか。

Prerequisite

temporal_learning_window >= 2

が必要。

Window=1ならdistance 2以上が存在しないため、Decayを変えても結果は変わりません。

おすすめ実験

A B C D

について、

temporal_learning_window = 3

を固定し、

temporal_learning_decay =
0.1
0.5
1.0

を比較。

22. normalize_direct_scores

Default: False

[CODE]

False:

Direct = raw weight

True:

Direct row / positive row sum

とします。

これはPairとの比較で重要。

Pairは元々、

pair row / positive row sum

なので、

normalize_direct_scores=True

にすると、

Direct ≈ normalized scale
Pair   ≈ normalized scale

になります。

[EXP-R]

H-LEAK-1はこの設定でDirectとPairを比較しています。

23. activation_decay

Default: 0.6

[CODE][EXP-C]

1stepごとにActivationをどれだけ残すか。

Prerequisite

history_boost > 0

Frog既定ではhistory_boost=0なので、

activation_decayだけ変えてもPredictionは変わりません。

これは「設定が壊れている」のではなく、

Activation
 ↓
History Score

History Score × 0
 ↓
0

だからです。

おすすめ実験

Frog(
    history_boost=0.35,
    activation_decay=...
)

として、

0.1
0.6
0.9

を比較。

24. threshold

Default: 0.05

[CODE][EXP-C]

どのActivationから先へ伝播を許すか。

Prerequisite

history_boost > 0

Predictionへの変化を見るにはHistory pathwayが必要です。

低い

弱いactivationも広がる。

高い

強いactivationだけ伝播。

Trap

Frog既定でthresholdだけ変えて、

何も変わらない！

となるのは正常です。

25. activation_cap

Default: 0.0

[CODE][EXP-C]

Activationの上限。

0は無制限ではなく、自動安全上限。

Prerequisite

history_boost > 0

Predictionへ影響させるにはHistory経路をONにする必要があります。

小さくすると

強いactivationを早くclip。

高くすると

より大きなactivationを残せる。

26. max_nodes

Frog default: 256

[CODE][DOC]

利用者Tokenは、

256 - 3 special nodes
= 253

まで。

Main matricesは概ね、

N × N

なので、メモリは二乗で増えます。

27. seed

Default: 42

[CODE][DOC]

Frogの通常の、

learn
predict
top
probabilities

は決定論的。

seedを変えても通常結果は変わりません。

Engine内部のsample generation等で乱数を使う場合に意味を持ちます。

28. Config Dependency Graph

今回の実験で、Configを単独のツマミとして見るだけでは不十分なことが分かりました。

activation_decay ─┐
threshold ─────────┼──► activation
activation_cap ────┘        │
                            ▼
                     history_boost
                            │
                            ▼
                     candidate score


context_trace_decay
        │
        ▼
 context_trace
        │
        ▼
context_projection_boost
        │
        ▼
 existing candidates only


temporal_learning_window
        │
        ├──► temporal_learning_decay
        │
        └──► direct_learning_window
                  │
             ┌────┴────┐
             ▼         ▼
          direct     context


refractory_steps
        │
        ▼
 candidate blocking
        │
        └── max_consecutive_repeats
             （例外規則）

Configは、

23個の独立したノブ

ではありません。

むしろ、

依存関係を持つ小さな回路

です。

29. 「何も変わらない」には2種類ある

これは今回かなり重要な発見です。

Type A — 内部では変化したが、出力に見えない

例:

weight_decay

scoreは減っている。

しかし候補が1つなので、

probability = 1.0

のまま。

Type B — そもそもPrediction経路がOFF

例:

activation_decay

だけ変更。

しかし、

history_boost = 0

なのでActivation差がscoreへ届かない。

この場合は、

本当にPredictionへは何も起きていない。

この二つを区別します。

predict()同じ
       │
       ├─ scoreは変わった？
       │      ├─ YES → Type A
       │      └─ NO
       │
       └─ prerequisiteはON？
              ├─ NO → Type B
              └─ YES → 別の理由を調査

これはCSEを解剖する際の重要な診断フローです。

30. Recommended Experiment Pack

01 Temperature Ladder

0.05 → 0.2 → 0.8 → 2 → 10

02 Refractory Ladder

0 → 1 → 2 → 5

03 Pair Context ON/OFF

capacity 2048
vs
0

04 Competitive Forgetting

同じPrefixに別Continuationを学習。

さらに、

Direct
Pair
Probability

を別々に観察。

05 Activation Wake-Up

まず、

history_boost = 0

で、

activation_decay
threshold
activation_cap

を変更。

→ Prediction変化なし。

その後、

history_boost = 0.35

へ変更。

→ Activation系Configが「生きる」かを見る。

これはPrerequisiteの概念を理解する最良の教材候補です。

06 Trace Wake-Up

context_projection_boost = 0

の状態でcontext_trace_decayを変更。

→ Prediction変化なし。

次にProjectionをON。

context_projection_boost > 0

→ TraceがPredictionへ届く。

07 Temporal Wake-Up

temporal_learning_window = 1

で、

temporal_learning_decay
direct_learning_window

を変更。

→ 差なし。

次に、

temporal_learning_window = 3

へ。

→ 距離2・3の学習差を見る。

08 Direct vs Pair Scale

normalize_direct_scores = False

と、

True

を比較。

explain()で、

direct
pair
score
probability

を見る。

31. 実験するときのチェックリスト

Configを変えたら、

□ そのConfigのPrerequisiteはONか？
□ predict()だけで判断していないか？
□ top()で分布を見たか？
□ scores()でraw scoreを見たか？
□ explain()で成分を分解したか？
□ DirectとPairを混同していないか？
□ weight decay対象のMemoryか？
□ Course EditionとResearch Editionを混ぜていないか？

を確認します。

32. Config Difficulty

33. 23 Config Checklist

23 / 23 covered. 🐸✅

Closing

最初は23個のConfigが、

23個のツマミ

に見えます。

でも実際には、

Switch
 ↓
Subsystem
 ↓
Another Config
 ↓
Candidate Score
 ↓
Top-K
 ↓
Probability

という依存構造を持っています。

だから、

設定を変えたのに何も起きない

こと自体がバグとは限りません。

前提となる回路がOFFなのかもしれない。

逆に、

predict()は同じなのに、中では大きく変わっている

こともあります。

CSE Moddingでは、

Outputを見る。 Scoreを見る。 Componentを見る。 そして、回路を見る。

それが🐸の解剖です。

Tune it. Wake it. Break it. Explain it. 🐸🎛️🔬