2026-06-17 Godot LLM/RAG 判別器構築振り返り

一行要約

今日は Godot 特化コーディングモデルの方向性を単純な Q&A モデルからリポジトリレベルの SWE エージェントへ再設定し、その前段に必要な公式ドキュメントベースの RAG 判別器とデータ生成パイプラインの最初の実体を作成した。

今日の大まかな流れ

最初は「Godot 公式ドキュメントで RAG チャットボットを作ろう」という程度の目標だった。しかし、話と作業が進むにつれて目標がより明確になった。

Godot 公式ドキュメントの収集  
-> 公式ドキュメントベースのRAG判別器  
-> GitHub Godot プロジェクトのラベリング  
-> SFT/DPO データの生成  
-> Qwen ベースの Godot 4 コーディングモデル  
-> リポジトリレベルの SWE エージェント

つまり、今日の核心はチャットボットを一つ作ることではなく、後にGodotプロジェクトを実際に読み取り修正するモデルを作るためのデータ判別/生成基盤を構築することだった。

1. 単純なQ&Aモデルでは不十分という判断

今日最初に整理したのは、モデル目標の性格でした。

既存では Godot 4 の質問/回答データセットを作成し、モデルが Godot 4 のコード回答をうまく行えるように学習させる方向を考えていました。しかし「マップを作ってほしい」などのリクエストを考えてみると、これは単純な Q&A の問題ではありませんでした。

実際のリクエストの流れは次に近いです。

ユーザーリクエストの理解
-> リポジトリ構造の探索
-> 関連するシーン/スクリプト/リソースの検索
-> アセットパスと既存コードスタイルの確認
-> Godot 4 文法/API の判断
-> コード修正
-> 実行/テスト/検証
-> パッチ作成

この流れは単一の回答を生成する問題ではなく、software engineering agent の問題です。したがって、今日はモデルの方向性を SWE-agent trajectory training の観点で再設定しました。

本日記録した主要キーワード:

Long-context repository-level software engineering agent training
SWE-agent trajectory training
Godot repo-level patch generation
long-context trajectory dataset

参考事例も一緒に整理しました。

SWE-agent trajectories
SWE-smith
SWE-Gym
CoderForge-Preview
ACC
RepoBench / CrossCodeEval / RepoCoder
aiXcoder CoLT
godot-dodo
wallstoneai/godot-gdscript-dataset

今日の結論は、小さな instruction Q&A だけでは不十分だということだった。最終的に必要なのは、Godot プロジェクト単位の探索、判断、修正、検証の trajectory である。

2. Godot LLM 全体ロードマップ整理

その次に、全体開発ロードマップを再度組み立てました。

大まかな流れは以下のように整理しました。

データ
-> 第1段階 RAG チャットボット
-> SFT
-> DPO
-> SWE エージェント

ステップをさらに詳しく分けると、次のようになります。

Stage 0. 準備段階  
Stage 1. データ収集および構造化  
Stage 2. 第1段階 RAG チャットボット開発  
Stage 3. データラベリングおよびデータセット作成  
Stage 4. モデル学習  
Stage 5. SWE エージェント開発  
Stage 6. 継続的改善

このロードマップで最も重要な判断は、1次 RAG チャットボットを単なる質問応答ツールと見なさない点です。まず Godot 公式ドキュメントの専門家役割を担う RAG 判別器を作成し、その判別器を通じて GitHub データをラベリング／加工した後、SFT/DPO と SWE エージェントへ拡張する構造が必要だと考えました。

特に Stage 5 の SWE エージェントは、単なるコード生成器ではなく、次の能力を備えている必要があります。

プロジェクト分析  
必要なファイルの探索  
コード修正  
Godot CLI または実行結果の検証  
失敗原因の分析  
パッチ生成

3. RAG 判別器ベースデータ生成構造設計

今日もう一つ重要だった判断は「LLMに最終ラベル決定を任せない」ことだった。

最初はRAGチャットボットがGitHubのコードやドキュメントを見てGodot 3/4かどうかを判別できると思い込みやすかった。だがラベリングは学習データの品質に直接影響するため、LLMの即興判断に任せるのは危険だ。

そこで構造を次のように組んだ。

LLMは生成補助  
ラベルはシステムが決定  
最終JSONLはPythonパイプラインが組み立て/検証

システムが担当すべきこと:

シンボル抽出  
APIマッピングDB照会  
公式文書ベクトル検索  
キーワード検索  
ラベルプロトタイプ検索  
ラベルスコアリング  
confidence計算  
最終JSONL組み立て  
検証

LLMが担当してもよいこと：

修正コード草案作成  
説明生成  
SFT 質問/回答 生成  
DPO 悪い回答 生成  
パッチ草案作成  
検証/問題点 説明 補助

生成対象データセットも8種類に整理した。

version_classification
api_mapping
migration_fix
instruction_sft
dpo_preference
repo_explorer
patch_generation
metadata_verification

この定理は、今日作成したRAG後処理コードの設計基準となった。特に api_mapping、symbol_catalog、keyword_index、search_text を分離した理由もここから出てくる。

4. RAG 判別器から Qwen 3.6 モデルへの MVP フロー

Godot RAG 判別器と Qwen 3.6 コーディングモデル間の MVP フローを別途整理した。

整理したフロー:

godot_docs_full.zip 原本ドキュメントの準備
-> chunk_docs.py ベースの第1段階チャンク化
-> Godot 専用の後処理
-> ローカル検索インフラの構築
-> GitHub データの収集と構造化
-> RAG 判別器の実行
-> 学習データセットの作成
-> Qwen 3.6 SFT/DPO

ここでローカル検索インフラは、単一のベクトルDBだけを意味するわけではありません。

必要な構成:

Vector DB
Keyword Index
Reranker
API Mapping DB
Label Prototype DB

さらに、GitHub データは単なるコードスニペットではなく、リポジトリ単位の構造で提供される必要があります。

必要な入力:

.gd
.tscn
.tres
project.godot
README
repo tree
metadata

第1回 SFT の目標も再整理した。

Godot 4 の優先事項  
GDScript 基本出力  
Godot 3 API 拒否  
Godot 3 → 4 変換根拠の説明

その後、DPOでは良い回答と悪い回答の基準をより明確に設定する必要がある。

悪い回答：Godot 3 APIが混ざった回答  
良い回答：Godot 4 純粋なコードと根拠のある回答

5. v1 公式ドキュメントチャンク化

設計を整理した後、実際の公式ドキュメントデータを RAG に投入できる形にした。

最初に作成した成果物は次のファイルである。

work/godot_rag/chunks/docs_chunks.jsonl

公式ドキュメントのMarkdown 1,570個を見出しと長さの基準で分割し、9,741個のチャンクを作成しました。

結果:

Input pages: 1,570
Output chunks: 9,741
Max chunk chars: 2,800
Overlap chars: 350

v1で良かった点:

公式ドキュメント全体を JSONL チャンクにした。
JSONL のパースは安定していた。
class_reference、tutorial、migration のような基本ドキュメントタイプが分類された。

v1の問題:

Sphinx の残り文字列が多く残っていた。
短すぎるノイズチャンクがあった。
heading、section、method/property の構造が十分に残っていなかった。
class reference が API 単位で細かく分割されていなかった。

v1は「公式ドキュメントの収集と基本チャンク化の成功」段階だった。検索 MVP の出発点にはなったが、ラベル判別器としては不十分だった。

6. v2 後処理

次に postprocess_chunks.py を作成し、v2 チャンクを生成した。

ファイル:

work/godot_rag/postprocess_chunks.py
work/godot_rag/chunks/docs_chunks_v2.jsonl

v2で処理したもの:

404 チャンクの削除  
短いノイズチャンクの削除  
Sphinx の残り文字列の削除  
シンボルの抽出  
クラス名の抽出  
セクション/メンバータイプ/メンバー名 の強化  
マイグレーション関連チャンクの表示

結果:

Input chunks: 9,741
Output chunks: 8,778
Dropped 404 chunks: 3
Dropped short/noise chunks: 960
Migration-related chunks: 695

v2は公式ドキュメントベースのRAG検索MVPとして使用できる状態になった。しかし、最終ラベル判別器として見るにはまだ不足していた。特に move_and_slide、velocity、@export、await といった構文/API の変化が独立した判別基準として分離された状態ではなかった。

7. 誤った v3 の方向と巻き戻し

最初に考えた v3 は、一部のコア API をハードコーディングして api_focus チャンクを作成する方式だった。

例:

KinematicBody2D
CharacterBody2D
move_and_slide
@export
await

この方式は検索性能を迅速に向上させるように見えるかもしれません。しかし実際には危険でした。

問題:

人が選んだ API に検索エンジンが過学習する可能性がある。
リスト外の API が弱くなる。
一部の代表 API が全体の Godot API を代表しているように見える可能性がある。
欠落した API が後にラベリングミスにつながる可能性がある。

そこで既存の v3 を元に戻しました。この判断は重要でした。短期的には損失のように見えますが、最終的な判別器の品質を考えるとハードコーディングされた focus チャンクは誤った方向でした。

8. catalog 基盤の v3 再設計

元に戻した後、方向を変えました。

新原則:

v2 のチャンクを一つも失わない。  
新しい focus チャンクを任意に作成しない。  
公式文書全体から symbol/catalog/index/mapping を自動抽出する。  
検索強化情報は metadata として付加する。

追加したコード:

work/godot_rag/build_symbol_catalog.py
work/godot_rag/build_keyword_index.py
work/godot_rag/build_api_mapping.py
work/godot_rag/make_chunks_v3.py
work/godot_rag/validate_rag_artifacts.py
work/godot_rag/retrieval_smoke_test.py

生成した成果物:

work/godot_rag/catalog/symbol_catalog.jsonl
work/godot_rag/catalog/keyword_index.json
work/godot_rag/catalog/api_mapping.jsonl
work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl
work/godot_rag/validation/validation_report.json
work/godot_rag/validation/retrieval_smoke_test.json

全体の docs_chunks_v3.jsonl は約 189 MB で、GitHub の単一ファイル制限に引っかかる可能性がありました。そのため、リポジトリには行単位で保存される分割ファイルをアップロードし、必要に応じてローカルで再度結合するようにしました。

cat work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl \
  > work/godot_rag/chunks/docs_chunks_v3.jsonl

9. v3 整合性検証

v3で最も重要視したのは欠落防止です。v2 のチャンクが一つでも抜けると、後で公式文書の根拠が失われる可能性があるためです。

そこで validate_rag_artifacts.py を作成しました。

検証基準:

v2 chunk_id set == v3 chunk_id set
no missing or extra v3 chunks
catalog/index/mapping references point to existing chunks
search_text is present
no old hardcoded api_focus fields remain

検証結果：

status: pass
v2 chunks: 8,778
v3 chunks: 8,778
v2 unique chunk_id: 8,778
v3 unique chunk_id: 8,778
symbol catalog entries: 134,922
keyword index keys: 192,257
api mapping records: 144
v3 chunks with api mappings: 1,900
v3 migration-related chunks: 2,392

また、埋め込み前の段階で lexical/keyword ベースのスモークテストも実施した。

代表的なクエリ:

KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4

結果はすべて5件合格した。

10. 今日見つけた最大のリスク

今日の最も重要なインサイトは「多く抽出すること」と「信頼してラベルに書くこと」が異なるという点だった。

公式ドキュメント全体で広く抽出すればリコールは向上する。しかしその結果をすべて同じ信頼度で扱うとキーワードインデックスが汚染される。

例えば次は実際の API や構文要素である可能性が高い。

CharacterBody2D
move_and_slide
FileAccess
@export
await

一方、次は文書の一般的な単語であるか、表の列である可能性が高いです。

Returns
See
Tip
MIT
Software
Type

実際に smoke test を確認する過程で Type -> EditorSceneFormatImporterFBX2GLTF のように一般表のカラムが API マッピング候補として拾われる問題を発見した。この問題は Type をマッピング候補から除外するように修正した。

ここで得られた結論は明確である。

広く抽出することは必要です。  
しかし、広く抽出したすべてを信頼できる事実として使用してはいけません。

11. v3.1 信頼度分離構造への改編

上記のリスクを確認した後、v3をそのまま最終ラベル判別器に使用してはならないと判断した。そこで v3.1 では catalog を一つにまとめて使用せず、信頼度と用途別に分離した。

v3.1 で新たに設定した構造:

trusted_api_symbols
syntax_symbols
migration_mappings
mentioned_symbols
candidate_terms
rejected_terms
retrieval_keys
search_text

各フィールドの意味も明確に分けました。

trusted_api_symbols:
class reference 構造で直接確認された class/method/property/signal/constant

syntax_symbols:
GDScript 文法ドキュメントと migration ドキュメントで確認された文法要素

migration_mappings:
old -> new 関係が根拠チャンクと共に結び付けられた Godot 3 -> 4 変更マッピング

mentioned_symbols:
tutorial/bodyで言及されたがすでに trusted/syntax カタログにあるシンボル

candidate_terms:
検索 recall 補助用候補語

rejected_terms:
Returns, See, Tip, MIT, Software のようなラベル根拠で使用してはいけない一般語

追加したコード:

work/godot_rag/build_v31_artifacts.py
work/godot_rag/validate_v31_artifacts.py

生成した v3.1 成果物:

work/godot_rag/chunks/docs_chunks_v3_1.jsonl
work/godot_rag/chunks/docs_chunks_v3_1.summary.json
work/godot_rag/catalog_v3_1/trusted_api_catalog.jsonl
work/godot_rag/catalog_v3_1/syntax_catalog.jsonl
work/godot_rag/catalog_v3_1/api_mapping.jsonl
work/godot_rag/catalog_v3_1/mention_index.json
work/godot_rag/catalog_v3_1/keyword_index.json
work/godot_rag/catalog_v3_1/v3_1.summary.json
work/godot_rag/validation_v3_1/validation_report.json
work/godot_rag/validation_v3_1/retrieval_smoke_test.json

v3.1 の結果:

Source v2 chunks: 8,778
Output v3.1 chunks: 8,778
Trusted API catalog entries: 26,318
Syntax catalog entries: 68
API mapping records: 144
Mention index keys: 10,292
Keyword keys: 71,543
Validation status: pass
Retrieval smoke tests: 5 / 5 passed

重要な修正点もありました。

最初の v3.1 生成過程では、class_name を v2 メタデータからそのまま信頼すると、Tutorials、All、String のような誤った値が trusted catalog に上がってしまう可能性がありました。そこで、source URL と class reference のパスを基準に canonical class name を再作成しました。この修正後、Characterbody2d のようなケース問題も CharacterBody2D に直されました。

もう一つ重要な検証は move_and_slide でした。広範な抽出方式では ProjectSettings.move_and_slide のような偽の trusted 項目が生まれる危険がありました。v3.1 では class reference の構造化されたセクションで確認されたメンバーだけを trusted に昇格させるよう制限し、最終的に move_and_slide の trusted 項目は以下のように実際の Godot クラスにのみ残されました。

CharacterBody2D.move_and_slide
CharacterBody3D.move_and_slide

つまり、今日 v3.1 で行ったことは単にフィールドを増やしただけでなく、「検索には広く使用し、ラベルの決定には狭く信頼できる根拠だけを使用する構造」に変更したということです。

12. v3.1 整合性検証

v3.1では欠落が特に危険でした。v2の 8,778 個のチャンクのうち 1 つでも抜けると、公式文書の根拠が失われる可能性があるためです。

検証基準：

v2 chunk_id set == v3.1 chunk_id set  
v3.1 unique chunk_id count == 8,778  
doc_type 分布 維持  
legacy 混合 フィールド 削除  
trusted/syntax/migration カタログ 参照 整合性 確認  
search_text 存在 確認

検証結果：

status: pass
errors: 0
warnings: 0
v2 chunks: 8,778
v3.1 chunks: 8,778

検索スモークテストも再度実行しました。

KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4

結果はすべて5件が通過した。この段階の意味は「最終ラベラーが完成した」ことではなく、v3.1構造が最低限MVPベクトル/キーワードインデックスに移行できるほど整合性があるということです。

13. GitHub 反映と記録整理

今日はコードとデータの成果物を作成しただけでなく、GitHub への反映も整理しました。

処理した作業:

リモート設定  
大容量 v3 ファイル分割  
作業ブランチ push  
リモート main とローカル履歴のマージ  
main push  
ドキュメントディレクトリの整理

docs_chunks_v3.jsonlは約189MBで、そのままアップロードするとGitHubの単一ファイル制限に引っかかる可能性がありました。そこで docs_chunks_v3.part-000.jsonl、docs_chunks_v3.part-001.jsonl、docs_chunks_v3.part-002.jsonlに分割しました。

また、当初は回顧がルート retrospectives/ に作成されましたが、既存のリポジトリ構造と合わなかったため、ドキュメント構造を以下のように整理しました。

docs/research-notes/   設計メモ
docs/roadmaps/         全体ロードマップ
docs/retrospectives/   日付別回顧
work/godot_rag/        RAGコードと成果物
outputs/godot_docs_full/ 公式文書クロール結果

追加で docs/README.md を作成し、ドキュメントディレクトリの役割も整理した。

14. Git の author/email の整理

本日の README に記録したとおり、GitHub の貢献グラフの反映問題も整理した。

確認した問題：

main ヒストリーの author/committer メールが混在しています  
ローカルホストのメール  
naver のメール  
GitHub noreply のメール

処理した方向:

全体の Git 設定を yyeongjin <appsky1888@gmail.com> に変更  
main の履歴 author/committer を統一  
リモートに反映  
再作成前にバックアップブランチを保管

バックアップブランチ:

backup/before-author-email-rewrite-2026-06-17

この作業はRAG自体と直接つながっているわけではありませんが、今日の重要な整理作業の一つでした。その後、記録とコミットがGitHubプロフィールに正しく反映されるように基盤を整える作業でした。

15. 今日作成/整理した文書

今日作成または整理した主な文書:

docs/research-notes/2026-06-17-swe-agent-trajectory-keywords.md
docs/research-notes/2026-06-17-godot-rag-labeler-data-generation.md
docs/research-notes/2026-06-17-godot-rag-to-qwen-coding-model-flow.md
docs/roadmaps/2026-06-17-godot-llm-roadmap.md
docs/retrospectives/2026-06-17-godot-rag-judge.md
docs/README.md

READMEにも6月17日の開発日誌とRAGデータ準備セクションを追加しました。

16. 現在の結論

本日基準の状態をこのように整理できます。

方向性:
Godot Q&A モデルではなく Godot SWE エージェントにすべきです。

データ:
公式ドキュメント RAG は学習データ生成のための判別器として機能すべきです。

ラベル:
LLM ではなく Python パイプラインが決定すべきです。

RAG:
v2 は安全な基本チャンクセットです。
v3 は広く抽出した中間カタログの成果物です。
v3.1 は信頼度の分離まで適用した、現在推奨される RAG の成果物です。

リスク:
抽出したシンボルをすべて同じ信頼度で使用してはいけません。

今日の作業は単にいくつかのファイルを作っただけでなく、間違いやすい方向に何度も曲がった日でした。特にハードコーディング API フォーカスチャンクを元に戻した判断、broad v3 のノイズリスクを発見した判断、そして v3.1 で trusted/syntax/migration/mention/candidate/rejected を分離した判断が重要でした。

17. 次の作業

次の作業はすぐに GitHub コードラベリングではありません。

まずやるべきこと:

docs_chunks_v3_1.jsonl の search_text に基づく埋め込み生成
ベクトル検索 + キーワード検索を組み合わせたハイブリッドリトリーバルテスト
trusted_api_symbols、syntax_symbols、migration_mappings に基づくラベル決定 Python パイプライン設計
GitHub リポジトリ構造化データ入力フォーマット定義
.gd、.tscn、.tres、project.godot、README を一緒に見るリポジトリレベル判別フロー設計
RAG 判別器結果を 8 種類の JSONL データセット生成パイプラインと接続
リモート LLM エンドポイントが準備できたら修正コード/説明/SFT/DPO 候補生成支援に接続
その後 Qwen ベースの SFT/DPO と SWE エージェントの軌跡学習へ拡張

今日の最終的な教訓はこれです。

文書をたくさん集めることよりも、集めた知識をどの信頼度で使用するかを分けることの方が重要です。

2026-06-17 Godot LLM/RAG 判別器構築 振り返り