Godot RAG 分類器ローカル PostgreSQL 設定

作成日: 2026 年 6 月 22 日

目的

Godot 公式ドキュメント RAG 分類器のためにローカル PostgreSQL データベースを設定する。標準的な流れは以下の通りです。

JSONL -> PostgreSQL -> Retriever -> Validator -> Qwen 3.6

現在の段階の目標は学習データを生成することではなく、公式ドキュメントに基づく根拠データベースをローカルで再現可能にすることです。テーブルの payload カラムは JSONL スキーマと同じ名前で維持し、データベース運用用の派生カラムは id、embedding、search_tsv、created_at のように検索/保存に必要な最小限のカラムだけにします。

基準設計文書：

docs/roadmaps/2026-06-21-initial-rag-classifier-architecture.md

ローカル DB 構成

Docker Compose ファイル:

infra/postgres/docker-compose.yml

使用画像:

pgvector/pgvector:pg16

接続情報:

項目	値
database	`godot_rag`
user	`godot_rag`
password	`godot_rag_local`
host	`localhost`
port	`5432`

ローカル開発用のデフォルト URL:

postgresql://godot_rag:godot_rag_local@localhost:5432/godot_rag

生成される拡張

extension	目的
`vector`	文書チャンクとラベルプロトタイプ埋め込みを保存
`pg_trgm`	API名、heading、symbolのあいまい/部分検索を支援

注意:

embedding カラムは現在次元が固定されていないベクトル型です。  
pgvector の HNSW/IVFFlat インデックスは固定次元が必要なため、  
実際のベクトルインデックスは embedding モデルの次元が確定した後、別途マイグレーションで作成します。

テンプレート:

infra/postgres/init/004_vector_index_templates.sql

生成されるスキーマ

DB スキーマ名:

godot_rag

テーブル:

テーブル	役割
`godot_rag.docs_chunks`	公式文書説明、チュートリアル、class reference のチャンク
`godot_rag.api_mapping`	Godot 3 → 4 API 変更、rename、replacement、deprecation の規則
`godot_rag.label_prototypes`	分類/変換/拒否/修正の例プロトタイプ
`godot_rag.ingest_reports`	JSONL 変換/注入過程の警告、スキップ、検証ログ

テーブル設計

`docs_chunks`

公式文書チャンクを保存する。すべての row は元の URL、元のファイルパス、元の Markdown ハッシュを保持しなければならない。

主なカラム:

カラム	説明
`chunk_id`	再実行しても変わらない決定的 ID
`doc_version`	`stable`、`4.6` など文書バージョン
`source_url`	Godot 公式文書元 URL
`source_file`	リポジトリ内 Markdown パス
`source_sha256`	元の Markdown ハッシュ
`doc_type`	`class_reference`、`tutorial`、`migration` など文書タイプ
`symbol`	class/API 文書代表シンボル
`section_path`	見出し階層 JSON
`content`	検索と埋め込み対象本文
`code_blocks`	本文から抽出したコードブロック配列
`api_symbols`	本文で検出した Godot API シンボル
`embedding`	pgvector 埋め込み
`search_tsv`	キーワード検索用 tsvector

`api_mapping`

Godot 3/4 変更規則を保存する。

重要な原則:

公式文書の根拠があれば confidence = 'verified_from_docs' とする。
まだレビューしていない自動抽出規則は confidence = 'candidate' とする。
学習/ラベリングに直接使用する規則は人がレビューした後 confidence = 'approved' または別途承認 JSONL で管理する。

`label_prototypes`

分類器出力のラベル基準と代表パターンを保存する。

初期ラベル候補:

ラベル	意味
`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`	難読化、制御文字、悪意疑いコード

実行方法

DB 起動:

docker-compose -f infra/postgres/docker-compose.yml up -d

現在のローカル環境では docker compose プラグインではなく docker-compose コマンドを使用します。

ヘルスチェック:

docker inspect --format='{{json .State.Health.Status}}' godot-rag-postgres

コンテナ内部から接続:

docker exec -it godot-rag-postgres psql -U godot_rag -d godot_rag

テーブル確認：

docker exec godot-rag-postgres \
  psql -U godot_rag -d godot_rag \
  -c "\\dt godot_rag.*"

拡張の確認:

docker exec godot-rag-postgres \
  psql -U godot_rag -d godot_rag \
  -c "select extname from pg_extension where extname in ('vector', 'pg_trgm') order by extname;"

初期化

DBを完全に新しく作成するときだけ使用します。ローカルボリュームが削除されるので注意してください。

docker-compose -f infra/postgres/docker-compose.yml down -v
docker-compose -f infra/postgres/docker-compose.yml up -d

JSONL 注入予定パス

まだ注入スクリプトは作成していない。次の JSONL 出力物を作成し検証した後、upsert スクリプトを付ける。

ファイル	対象テーブル
`work/godot_rag/jsonl/docs_chunks.jsonl`	`godot_rag.docs_chunks`
`work/godot_rag/jsonl/api_mapping.jsonl`	`godot_rag.api_mapping`
`work/godot_rag/jsonl/label_prototypes.jsonl`	`godot_rag.label_prototypes`
`work/godot_rag/jsonl/ingest_report.jsonl`	`godot_rag.ingest_reports`

次の作業

outputs/godot_docs_full/pages 構造分析レポートを作成する。
文書タイプ別のチャンク基準を確定する。
docs_chunks.jsonl スキーマ検証スクリプトを作成する。
JSONL upsert スクリプトを作成する。
サンプル質問で Retriever 検索品質を検証する。

Godot RAG 分類器 ローカル PostgreSQL 設定

目的