qwen2.5-1.5b-wordle-grpo-merged

用多輪 GRPO 把 Qwen/Qwen2.5-1.5B-Instruct 訓練成會玩 Wordle 的 agent： 模型每回合輸出 <guess>word</guess>，環境把 G/Y/X 回饋插成 user turn，最多 6 回合。 這是「訓練 agent 而非 prompt agent」的示範專案——所有決策能力都寫進權重， 而不是寫進越疊越長的 prompt。

• 訓練框架：TRL 1.8 GRPOTrainer + 自訂多輪 rollout_func（單張 A100、vLLM colocate、LoRA）
• 環境/獎勵/評測程式碼：GitHub agentic-rl-wordle（含完整 PLAN 與四階段 gate 記錄）
• 姊妹 repo：本 repo 為合併後全量權重（LoRA 已 merge 進 base model，可直接載入、不需要 PEFT）；qwen2.5-1.5b-wordle-grpo 為 LoRA adapter 版本

方法

1. 環境：經典兩趟重複字母規則（先標 G 扣計數，再左→右標 Y）；非法猜測消耗回合。 答案 2,315 / 合法猜測 12,972（cfreshman 公開清單，fetch-at-setup）。
2. 協定：system prompt 說明規則與 G/Y/X 記號；歷史每輪 You guessed "crane" -> feedback: G Y X X Y + 已知線索摘要；模型輸出經三態 robust parser（tag → 全文最後 5 字母詞 → 放棄）。
3. GRPO：一組 = 同一隱藏答案的 8 條軌跡（組內比較 advantage）；episode 級獎勵； assistant-only loss 以「只有生成 token 進 completion_ids」結構性達成。
4. 訓練詞/評測詞嚴格隔離：answers 以 seed=42 切 1,852 train / 463 eval， 評測固定取 eval 前 200 詞，全程不進訓練。

獎勵

項目	值
獲勝	+10 + (6−回合數)
新綠位 / 新存在字母（首次發現）	+0.2 / +0.1（shaping 總上界 1.5 << 勝利 10）
非法詞或格式錯誤	−2 / 回合
違反已知限制	−1 / 回合
重複同一猜測	−2 / 次

量級論證與防 hacking 分析見 repo 的 docs/rewards.md（附單元測試）。

評測結果（200 個 held-out 詞、greedy、Wilson 95% CI；2026-07-11 真實執行）

agent	勝率 [95% CI]	勝局均猜	非法輸出率	tag 遵循率	違限率(重用X/破壞G)
random（12,972 均勻）	0.0% [0.0, 1.9]	—	0.0%	100%	87.4% / 57.8%
heuristic（頻率+過濾；有答案表存取）	99.5% [97.2, 99.9]	3.56	0.0%	100%	0.0% / 0.0%
qwen2.5-1.5b-instruct（未訓練）	0.0% [0.0, 1.9]	—	100.0%	0.0%	—
qwen2.5-1.5b + GRPO LoRA（本模型）	2.0% [0.8, 5.0]	5.25	0.3%	99.7%	57.5% / 46.2%

判讀（照本專案自己立的紅線誠實陳述）：

• 格式與合法性：塌陷式學會。未訓練的 base 在此協定下 100% 回合非法（連一手合法棋 都下不出來）；訓練後 99.7% 回合輸出格式正確的合法 5 字母單字。這是壓倒性顯著的差異， 也是本次訓練最確定的成果。
• 勝率：方向正確、未達統計顯著。0/200 → 4/200（0.0% → 2.0%），但 Fisher 精確檢定 單尾 p≈0.06、兩者 Wilson CI 有重疊——以 n=200 不足以宣稱「勝率顯著超過 baseline」。 依紅線，本 model card 不做此宣稱。
• 無 reward hacking：重複猜測率 0.0%，訓練期 samples/ 人工抽查亦無刷分模式。

代表性對局（訓練後模型，eval 確定性選取，含失敗案例）

answer: shiny — WIN in 5 turn(s)

• turn 1: guess=cloud [tag_ok] -> XXXXX
• turn 2: guess=train [tag_ok] -> XXXYY
• turn 3: guess=spike [tag_ok] -> GXGXX
• turn 4: guess=snake [tag_ok] -> GYXXX ⚠ breaks_green, reuses_absent_letter
• turn 5: guess=shiny [tag_ok] -> GGGGG

answer: shame — WIN in 6 turn(s)

• turn 1: guess=cloud [tag_ok] -> XXXXX
• turn 2: guess=train [tag_ok] -> XXGXX
• turn 3: guess=brave [tag_ok] -> XXGXG ⚠ reuses_absent_letter
• turn 4: guess=spare [tag_ok] -> GXGXG ⚠ reuses_absent_letter
• turn 5: guess=smash [tag_ok] -> GYGXY ⚠ breaks_green
• turn 6: guess=shame [tag_ok] -> GGGGG

answer: large — LOSS in 6 turn(s)

• turn 1: guess=cloud [tag_ok] -> XYXXX
• turn 2: guess=train [tag_ok] -> XYYXX
• turn 3: guess=brave [tag_ok] -> XYYXG
• turn 4: guess=pearl [tag_ok] -> XYYYY ⚠ breaks_green
• turn 5: guess=glory [tag_ok] -> YYXYX ⚠ breaks_green, reuses_absent_letter
• turn 6: guess=smear [tag_ok] -> XXYYY ⚠ breaks_green

answer: pedal — LOSS in 6 turn(s)

• turn 1: guess=cloud [tag_ok] -> XYXXY
• turn 2: guess=flank [tag_ok] -> XYYXX
• turn 3: guess=blame [tag_ok] -> XYYXY
• turn 4: guess=glade [tag_ok] -> XYYYY
• turn 5: guess=train [tag_ok] -> XXYXX ⚠ reuses_absent_letter
• turn 6: guess=plead [tag_ok] -> GYYGY

answer: frown — LOSS in 6 turn(s)

• turn 1: guess=cloud [tag_ok] -> XXGXX
• turn 2: guess=stone [tag_ok] -> XXGYX
• turn 3: guess=brain [tag_ok] -> XGXXG ⚠ breaks_green
• turn 4: guess=green [tag_ok] -> XGXXG ⚠ breaks_green, reuses_absent_letter
• turn 5: guess=crane [tag_ok] -> XGXYX ⚠ breaks_green, reuses_absent_letter
• turn 6: guess=flank [tag_ok] -> GXXYX ⚠ breaks_green, reuses_absent_letter

限制與誠實聲明

• 1.5B 模型的 Wordle 絕對勝率不高是預期內的（HF 官方以 Qwen3-1.7B 跑同任務的結論 是「有進步但無法穩定獲勝」）。本專案的成功判準是：勝率顯著超過未訓練 baseline （信賴區間佐證）+ 格式錯誤率塌陷 + 違限率下降，不是「打贏 heuristic solver」。
• heuristic baseline 看得到完整答案分布，是參照上界而非公平對手。
• 勝率項未達統計顯著（0/200 → 4/200，Fisher 單尾 p≈0.06）：三項判準中，格式錯誤率 塌陷（100%→0.3%）與訓練期 reward 曲線持續上升（-9.4 → -3.2，3000 步）確定成立， 勝率項方向正確但差距不足以在 n=200 下過檢定。如實記錄，不宣稱勝率顯著。
• 策略弱點（訓練期與評測一致觀察到）：模型收斂到固定開局腳本（cloud → train →…）， 且經常不沿用已確認的綠位（破壞綠位率 46.2%）、重用已排除字母（57.5%）——它學會了 「下合法的棋」，但只部分學會「利用回饋收斂」。可能原因依序：(a) shaped 獎勵中 「非法 −2/回合」是最大的梯度訊號，先被吃掉後策略梯度變稀疏；(b) 1.5B 容量對 多步約束推理吃緊；(c) 3000 步（4.8 萬局）對策略層次的學習仍偏短。
• 可能的後續槓桿（v1 未做）：binary 獎勵 A/B（HF 官方發現對 Wordle 更穩）、 提高違限懲罰或對「利用新資訊」加大 shaping、SFT 暖身、更大 base 模型。

重現

git clone <repo> && cd agentic-rl-wordle
python scripts/fetch_words.py && pip install -e . && pytest   # 環境全綠
python baselines/run_baseline.py --agent random               # 階段 1
# 訓練：上傳 wordle_rl_bundle.zip 到 Drive，跑 wordle_grpo_colab_train.ipynb（SMOKE→FULL）
python play.py --answer crane --adapter <path>                # 即時觀看