Godot 公式ドキュメント RAG 分類器スキーマとアーキテクチャ

作成日: 2026 年 6 月 21 日

目的

Godot 公式ドキュメント全体収集版を JSONL -> PostgreSQL -> Retriever -> Validator -> Qwen 3.6 フローで接続するための基準アーキテクチャを整理する。この文書は学習データを作成するための実装文書ではなく、outputs/godot_docs_full/pages にすでに集められた公式ドキュメント Markdown をどのような形で構造化し、検索可能な根拠 DB にするかを定義する設計基準である。

Godot 初期 RAG 分類器アーキテクチャ

現在の入力データ

公式ドキュメント収集結果はリポジトリの outputs/godot_docs_full 以下にある。

パス	役割
`outputs/godot_docs_full/pages/`	Godot 公式ドキュメントページ別 Markdown 原本
`outputs/godot_docs_full/manifest.json`	原本 URL、ローカルファイルパス、収集状態、バイトサイズ
`outputs/godot_docs_full/summary.json`	全体収集カウントと検証サマリ
`outputs/godot_docs_full/urls.txt`	実際に収集した URL の一覧
`outputs/godot_docs_full/searchindex_urls.txt`	Sphinx 検索インデックスから復元した対象 URL の一覧
`outputs/godot_docs_full/failed.json`	収集失敗一覧
`outputs/godot_docs_full/missing_from_searchindex.txt`	検索インデックス基準の欠落一覧

現在の基準線:

項目	値
Search index target pages	1568
Collected pages	1570
Page files	1570
Failed fetches	0
Missing from search index	0

全体パイプライン

crawler が Godot 公式ドキュメントをインターネットから収集する。
収集結果をページ単位の Markdown として保存する。
Markdown を正規化しメタデータを付与して JSONL レコードに変換する。
JSONL を PostgreSQL に投入する。
PostgreSQL は文書チャンク、API マッピング、ラベルプロトタイプを分離して保存する。
ユーザーが Godot ソースコード解析を要求すると、AST Parser がプロジェクトコードを構造化する。
Retriever がユーザー質問と AST 解析結果を基に PostgreSQL から根拠を検索する。
Validator が質問、AST 結果、検索根拠をまとめて Qwen 3.6 に渡す。
Qwen 3.6 は最終判定者ではなく、検証された根拠を使用して回答を整理する。
Validator が回答の根拠/形式/禁止パターンを確認した後、ユーザーに返す。

Markdown から JSONL への変換

pages/*.md は人が読みやすいページ原本であり、RAG には大きすぎる単位である。したがって変換スクリプトはページをセクション/API メンバー/例示単位に分割し、原本 URL と文書種別を共に保持しなければならない。

共通正規化規則

ステップ	処理
ファイルロード	`manifest.json` の `file`、`url`、`status`、`bytes` を基準に Markdown を読む。
本文整理	繰り返しヘッダー、Sphinx UI テキスト、壊れたアンカー文字、過剰な空白を除去する。
文書タイプ分類	URL とパスを基準に `class_reference`、`tutorial`、`migration`、`engine_details`、`about`、`other` に分ける。
セクション分割	見出し階層と Godot class reference パターンを基準にチャンク候補を作成する。
コードブロック保持	GDScript、C#、shader、CLI 例示は本文から除去せず `code_blocks` に別途保持する。
provenance 付与	すべてのレコードに原本 URL、ファイルパス、原本ハッシュ、変換スクリプトバージョンを残す。

JSONL 出力物

ファイル	目的	対象テーブル
`work/godot_rag/jsonl/docs_chunks.jsonl`	公式ドキュメント説明/チュートリアル/リファレンス検索用チャンク	`docs_chunks`
`work/godot_rag/jsonl/api_mapping.jsonl`	Godot 3 → 4 API 変更、リネーム、非推奨、置換規則	`api_mapping`
`work/godot_rag/jsonl/label_prototypes.jsonl`	分類/変換/拒否/修正例プロトタイプ	`label_prototypes`
`work/godot_rag/jsonl/ingest_report.jsonl`	変換中の警告、スキップ、品質チェックログ	DB 投入前検証用

`docs_chunks.jsonl` スキーマ

{
  "chunk_id": "godot-stable:classes/class_node.html#description:0001",
  "doc_version": "stable",
  "source_url": "https://docs.godotengine.org/en/stable/classes/class_node.html",
  "source_file": "outputs/godot_docs_full/pages/classes__class_node__....md",
  "source_sha256": "...",
  "doc_type": "class_reference",
  "symbol": "Node",
  "section_path": ["Node", "Description"],
  "heading": "Description",
  "content": "Nodes are Godot's building blocks...",
  "code_blocks": [],
  "language_tags": ["gdscript"],
  "godot_version_tags": ["4.x", "stable"],
  "api_symbols": ["Node", "_ready", "_process", "queue_free"],
  "token_count": 420,
  "metadata": {
    "status": "copied_old",
    "bytes": 12345
  }
}

必須フィールド:

フィールド	説明
`chunk_id`	再実行しても変わらない決定的な ID
`doc_version`	`stable`、`4.6` などのドキュメントバージョン
`source_url`	公式ドキュメントの元 URL
`source_file`	リポジトリ内の Markdown パス
`source_sha256`	元 Markdown のハッシュ
`doc_type`	ドキュメントの種類
`symbol`	クラス／API ドキュメントの場合の代表シンボル
`section_path`	見出し階層
`content`	検索および埋め込み対象の本文
`code_blocks`	本文から抽出したコードブロックの配列
`api_symbols`	本文で検出された Godot API シンボル

`api_mapping.jsonl` スキーマ

{
  "mapping_id": "godot3-to-4:kinematicbody2d-to-characterbody2d",
  "source_api": "KinematicBody2D",
  "target_api": "CharacterBody2D",
  "change_type": "rename_or_replacement",
  "godot_from": "3.x",
  "godot_to": "4.x",
  "confidence": "verified_from_docs",
  "evidence_chunk_ids": [
    "godot-stable:tutorials/migrating/upgrading_to_godot_4.html#..."
  ],
  "match_terms": ["KinematicBody2D", "CharacterBody2D"],
  "notes": "Godot 4 character movement node replacement candidate.",
  "negative_patterns": ["do not suggest KinematicBody2D for Godot 4 projects"]
}

原則:

項目	基準
`confidence`	公式文書の根拠があれば `verified_from_docs`、規則候補は `candidate` とする。
自動抽出	migration 文書と class reference から候補を作成できる。
承認基準	学習/ラベリングに使用する規則は、人がレビューした項目のみ `approved` 状態に昇格させる。
exact index	`source_api`, `target_api`, `match_terms` は正確な検索対象である。

`label_prototypes.jsonl` スキーマ

{
  "prototype_id": "label:godot3-api-in-godot4:kinematicbody2d",
  "label": "godot3_api_in_godot4",
  "task_type": "version_classification",
  "input_pattern": "extends KinematicBody2D",
  "expected_finding": "Godot 3 style physics body API detected.",
  "recommended_action": "Use CharacterBody2D or CharacterBody3D depending on project dimension.",
  "evidence_mapping_ids": [
    "godot3-to-4:kinematicbody2d-to-characterbody2d"
  ],
  "evidence_chunk_ids": [],
  "severity": "high",
  "validator_rules": {
    "requires_ast_symbol": "KinematicBody2D",
    "forbidden_answer_terms": ["KinematicBody2D is recommended in Godot 4"]
  }
}

ラベル候補:

ラベル	意味
`godot4_valid_api`	Godot 4 基準で有効な API 使用
`godot3_api_in_godot4`	Godot 4 プロジェクトに Godot 3 API が混在
`deprecated_or_removed_api`	削除/廃止 API 使用
`migration_required`	Godot 3 → 4 変換が必要
`ambiguous_version_signal`	バージョン判定根拠が不足または衝突
`non_godot_noise`	Python/WEB/Unity など Godot と無関係なデータ
`unsafe_or_obfuscated_code`	難読化、制御文字、悪意疑いコード

PostgreSQL スキーマ草案

PostgreSQL は pgvector を使用することを前提とする。キーワード検索は tsvector または trigram インデックスを併用する。

`docs_chunks`

カラム	型	説明
`id`	`bigserial primary key`	内部 ID
`chunk_id`	`text unique not null`	JSONL の決定的 ID
`doc_version`	`text not null`	文書バージョン
`source_url`	`text not null`	公式ドキュメント URL
`source_file`	`text not null`	Markdown ファイルパス
`source_sha256`	`text not null`	元データハッシュ
`doc_type`	`text not null`	文書種別
`symbol`	`text`	代表 API/クラスシンボル
`section_path`	`jsonb not null`	見出し階層
`heading`	`text`	現在のチャンク見出し
`content`	`text not null`	検索対象本文
`code_blocks`	`jsonb not null default '[]'`	コードブロック
`api_symbols`	`text[] not null default '{}'`	抽出シンボル
`metadata`	`jsonb not null default '{}'`	その他メタデータ
`embedding`	`vector`	埋め込みベクトル
`search_tsv`	`tsvector`	キーワード検索
`created_at`	`timestamptz default now()`	挿入時刻

インデックス:

インデックス	目的
`unique(chunk_id)`	重複挿入防止
`ivfflat/hnsw(embedding)`	意味ベース検索
`gin(search_tsv)`	キーワード検索
`gin(api_symbols)`	API シンボルフィルタ
`btree(doc_type, symbol)`	class/API 文書フィルタ

`api_mapping`

カラム	型	説明
`id`	`bigserial primary key`	内部 ID
`mapping_id`	`text unique not null`	決定的 ID
`source_api`	`text not null`	旧/問題 API
`target_api`	`text`	推奨 API
`change_type`	`text not null`	rename, removed, behavior_change など
`godot_from`	`text`	出発バージョン
`godot_to`	`text`	目標バージョン
`confidence`	`text not null`	根拠レベル
`status`	`text not null default 'candidate'`	candidate, approved, rejected
`evidence_chunk_ids`	`text[] not null default '{}'`	公式文書根拠チャンク
`match_terms`	`text[] not null default '{}'`	検索キーワード
`notes`	`text`	説明
`negative_patterns`	`jsonb not null default '[]'`	禁止パターン

インデックス:

インデックス	目的
`unique(mapping_id)`	重複防止
`btree(source_api)`	正確検索
`btree(target_api)`	逆方向検索
`gin(match_terms)`	キーワード検索
`btree(status, confidence)`	承認ルールフィルタ

`label_prototypes`

カラム	型	説明
`id`	`bigserial primary key`	内部 ID
`prototype_id`	`text unique not null`	決定的 ID
`label`	`text not null`	分類ラベル
`task_type`	`text not null`	classification, migration_fix, patch_generation など
`input_pattern`	`text not null`	検出パターン
`expected_finding`	`text not null`	期待判定
`recommended_action`	`text`	推奨アクション
`evidence_mapping_ids`	`text[] not null default '{}'`	API マッピング根拠
`evidence_chunk_ids`	`text[] not null default '{}'`	文書チャンク根拠
`severity`	`text not null`	low, medium, high
`validator_rules`	`jsonb not null default '{}'`	検証ルール
`embedding`	`vector`	類似事例検索
`search_tsv`	`tsvector`	キーワード検索

インデックス:

インデックス	目的
`unique(prototype_id)`	重複防止
`btree(label, task_type)`	ラベル別参照
`ivfflat/hnsw(embedding)`	類似ラベル検索
`gin(search_tsv)`	キーワード検索

AST Parser 入力/出力

AST Parser はユーザーソースコードを LLM に直接渡す前に検索可能な構造に変換する。初期対象は .gd, .tscn, project.godot である。

入力

入力	説明
ユーザー質問	例: "このプロジェクトが Godot 4 基準で安全か確認してほしい"
ソースコードファイル	`.gd`, `.tscn`, `.tres`, `project.godot`
プロジェクト構造	ファイルパス、シーン接続、リソースパス

出力スキーマ

{
  "project_id": "local-analysis-...",
  "godot_project": {
    "config_version": 5,
    "features": ["4.4", "Forward Plus"]
  },
  "files": [
    {
      "path": "scripts/player.gd",
      "language": "gdscript",
      "extends": "CharacterBody2D",
      "class_name": "Player",
      "symbols": ["CharacterBody2D", "Input", "move_and_slide"],
      "annotations": ["@onready"],
      "version_signals": ["godot4_annotation_syntax"],
      "diagnostics": []
    }
  ],
  "version_evidence": {
    "godot4": ["config_version=5", "@onready"],
    "godot3": []
  }
}

初期抽出フィールド:

フィールド	目的
`extends`	Node/API バージョン判定
`class_name`	プロジェクト内部シンボルマッピング
`annotations`	`@onready`, `@export` など Godot 4 シグナル
`legacy_keywords`	`onready var`, `export var`, `KinematicBody` など Godot 3 シグナル
`method_calls`	ドキュメント検索と API マッピング参照
`scene_dependencies`	シーン/スクリプト接続検証
`resource_paths`	欠落リソースとアセット接続検証

Retriever 動作

Retriever は LLM より先に根拠を選択する層です。

ユーザー質問から意図と対象タスクを抽出する。
AST Parser 結果から API シンボル、バージョンシグナル、ファイルパスを取得する。
api_mapping で exact lookup をまず実行する。
docs_chunks で API シンボルフィルタ + キーワード検索 + ベクトル検索を同時に実行する。
label_prototypes で類似ラベルと検証ルールを取得する。
検索結果を根拠バンドルとして整列する。

根拠バンドル:

{
  "query_id": "analysis-...",
  "task_type": "version_classification",
  "ast_summary": {},
  "doc_evidence": [],
  "api_mapping_evidence": [],
  "label_evidence": [],
  "retrieval_scores": {
    "exact_api_hits": 2,
    "keyword_hits": 8,
    "vector_hits": 12
  }
}

ValidatorとQwen 3.6の役割分離

Qwen 3.6は検索された根拠を読み、回答を整理するモデルです。最終ラベル、根拠採択、禁止パターン検証はValidatorが担当します。

構成要素	責任
Retriever	関連公式ドキュメント/API マッピング/ラベル根拠検索
Validator	根拠の欠落、禁止パターン、出力 JSON 形式の検証
Qwen 3.6	ユーザーに読まれる説明、修正方向、コード提案の整理

Validatorが確認する項目:

項目	基準
根拠 ID の存在	回答に使用した文書/マッピング/ラベル ID が実際の検索結果に存在すること。
Godot 4 基準	Godot 4 プロジェクトで Godot 3 API を推奨しないこと。
不確実性の表示	根拠が不足している場合、確定判定を禁止し `ambiguous_version_signal` とすること。
コード提案の検証	提案コードが検出されたプロジェクトの 2D/3D と衝突しないこと。
JSON 形式	内部パイプラインの出力はパース可能な JSON であること。

注入順序

outputs/godot_docs_full/summary.json と failed.json を確認する。
manifest.json と pages/*.md をロードする。
Markdown 正規化レポートを作成する。
docs_chunks.jsonl を生成する。
migration/class 文書から api_mapping.jsonl の候補を生成する。
承認された規則と代表事例で label_prototypes.jsonl を生成する。
JSONL スキーマ検証を通過したレコードだけを PostgreSQL に upsert する。
埋め込みを生成し vector index を更新する。
キーワード index と exact index を更新する。
サンプル質問で Retriever の結果を検証する。

品質検証チェックリスト

段階	合格基準
収集検証	`failed_count = 0`, `missing_from_searchindex = 0`
Markdown 正規化	空チャンクなし、元の URL を保持
JSONL 検証	すべての行が JSON パース可能、必須フィールドが存在
重複検証	`chunk_id`, `mapping_id`, `prototype_id` の重複なし
根拠検証	`api_mapping.evidence_chunk_ids` が実際の `docs_chunks` に存在
検索検証	代表 API 質問で exact hit と docs hit が共に返される
応答検証	Qwen の応答が根拠のない断定や Godot 3 API の推奨をしないこと

実装優先順位

pages/*.md 構造分析レポート作成
docs_chunks.jsonl 変換スクリプト作成
JSONL スキーマ検証スクリプト作成
PostgreSQL DDL 作成
docs_chunks 注入と検索検証
api_mapping 候補生成と手動承認フロー作成
label_prototypes 初期ラベルセット作成
AST パーサー最小フィールド抽出
Retriever 根拠バンドル出力
Validator + Qwen 3.6 応答整理ループ接続

核心原則

公式ドキュメントの元 Markdown は変更せずに保存する。
JSONL は再生成可能な中間成果物とする。
DB には元パス、元 URL、ハッシュ、変換スクリプトバージョンを必ず残す。
LLM がラベルを創作できないようにする。
Godot 3/4 の判定は AST シグナル、API マッピング、公式ドキュメント根拠を組み合わせて行う。
不確実な候補は学習データとしてすぐに使用せず candidate 状態に置く。
Qwen 3.6 は回答整理者であり、判定基準は Retriever と Validator が持つ。

次の作業

次の段階は outputs/godot_docs_full/pages の Markdown 構造をサンプル分析することです。特に class reference、migration、tutorial 文書がそれぞれ異なる構造を持つため、単一のチャンク規則で押し付けず、文書タイプ別のチャンク戦略をまず確定する必要があります。

Godot 公式ドキュメント RAG 分類器 スキーマとアーキテクチャ

目的

現在の入力データ

全体パイプライン

Markdown から JSONL への変換

共通正規化規則

JSONL 出力物

docs_chunks.jsonl スキーマ

api_mapping.jsonl スキーマ

label_prototypes.jsonl スキーマ

PostgreSQL スキーマ草案

docs_chunks

api_mapping

label_prototypes

AST Parser 入力/出力

入力

出力 スキーマ

Retriever 動作

ValidatorとQwen 3.6の役割分離

注入順序

品質検証チェックリスト

実装優先順位

核心原則

次の作業

Godot 公式ドキュメント RAG 分類器スキーマとアーキテクチャ

`docs_chunks.jsonl` スキーマ

`api_mapping.jsonl` スキーマ

`label_prototypes.jsonl` スキーマ

`docs_chunks`

`api_mapping`

`label_prototypes`

出力スキーマ