2026 年 6 月 22 日 回顧
今日は Godot 公式ドキュメント Markdown を直接 RAG に入れるのではなく、まず構造化された JSONL に変換して確認するフローを作った。最初は公式ドキュメント Markdown をどう分割すればいいか感覚がつかめなかったが、変換 UI を作ってファイルごとの結果を目で見たらずっと楽だった。
Markdown → JSONL 変換器
Godot 公式ドキュメント Markdown ファイルをアップロードすると Qwen API を通じて対象テーブルを分類し、結果を docs_chunks、api_mapping、label_prototypes 用の JSONL に分ける方式で整理した。
最初は単に Markdown を読み取ってすぐ DB に入れる形を考えていたが、そうするとどの文書がどのテーブルに入るか確認しにくかった。そこで中間生成物として JSONL を先に作り、画面で変換結果と原文の差分を確認する方式に変えた。
この方式が良い理由は次のとおりです。
- 元の Markdown と変換された JSONL を比較しながら見ることができる。
- 1 文書が
docs_chunks、api_mapping、label_prototypesのどこに入るか確認できる。 - 誤分類された文書や空の結果を DB に入れる前に除外できる。
- 後で変換ルールを変えても JSONL を再生成して比較できる。
変換結果の確認
変換器は保存された JSONL ファイル数とエラー数を画面に表示する。今日確認した画面では docs_chunks 側の結果が先に積み上がり、api_mapping、label_prototypes、エラーファイルはまだ空の状態だった。
この状態は異常というより、序盤の文書がほとんど説明文書で docs_chunks に入るのが自然に見えたからだ。重要なのは結果がすぐ DB に入るのではなく、まず JSONL として保存され人が確認できる点である。
JSONL プレビューとテーブル形式の確認
JSONL 結果を画面で JSON 形式とテーブル形式で確認できるようにした。例えば docs_chunks レコードは chunk_id、doc_version、source_url、source_file、source_sha256、doc_type、section_path、heading、content、code_blocks、api_symbols、token_count、metadata といったフィールドを持つ。
こう見ると単に Markdown ファイルを持っているよりはるかに良い。特に chunk_id と source_sha256 が一緒に見えるので、後でどのチャンクがどの原本から出たか追跡しやすくなった。RAG で最も重要なのは根拠がどこから来たかを失わないことだが、JSONL 中間生成物がその役割を果たせそうだ。
変換ログ
ファイル別の変換ログも確認した。どのファイルが開始され、Qwen がどのテーブルに分類し、何件の有効レコードが出たかを見ることができた。
今日確認した例では about__complying_with_licenses 文書が docs_chunks に分類され、複数のチャンクに変換された。逆に 404 のような文書は対象テーブルがなくスキップされるフローも見られた。このようなログがあれば、後で 1,570 件の文書をすべて処理するときにどこで問題が起きたか追跡できる。
ローカル PostgreSQL 設定
JSONL を作成した後はローカル PostgreSQL に入れられるよう DB も整備した。pgvector/pgvector:pg16 ベースでコンテナを立ち上げ、docs_chunks、api_mapping、label_prototypes、ingest_reports テーブルを作った。
今日特に重要視したのは DB スキーマが JSONL のフィールド名と食い違わないことだ。DB が勝手にフィールドを増やすと JSONL の契約が曖昧になり、後で変換器とインジェクタが異なる基準で動く可能性がある。そこで DB の payload カラムは JSONL スキーマに合わせ、運用用カラムは id、embedding、search_tsv、created_at 程度に最小化した。
ローカル DB を実際に起動し、サンプル JSONL 形式の insert と検索もロールバックテストで確認した。まだ全文書を DB に投入したわけではないが、JSONL → PostgreSQL へ続く道はずっと明確になった。
今日の判断
今日作ったフローは最終的な RAG 判別器そのものではない。しかし今の段階ではかなり重要な前進だ。
以前は公式ドキュメント Markdown をどう扱うべきか曖昧で、すぐにチャンク化や DB 注入に移ると構造が崩れるリスクがあった。今日はその間に JSONL 変換/検証ステップを挟み、人が確認できる中間生成物を作った。
結論として、今後のフローはこのように進めるのが妥当だと思われる。
Godot 公式ドキュメント Markdown
-> JSONL 変換
-> JSONL プレビュー/検証
-> PostgreSQL 注入
-> Retriever 検索 検証
-> Validator/Qwen 応答 整理明日以降、全体 1,570 件の文書を最後まで変換したときに docs_chunks、api_mapping、label_prototypes がどの割合になるかを確認する必要があります。特に api_mapping と label_prototypes は Qwen が勝手に作成してはいけないため、自動生成結果をそのまま信頼せず、承認/検証ステップを別途設ける必要があります。
処理速度の測定
さらに変換速度を計算してみたところ、全体 1,570 件の Markdown をすべて JSONL に変換するのに約 42 時間かかると見込まれます。
現在までの実際の処理時間は約 1 時間 9 分でした。この間に done が 39 件、deferred が 4 件、合計 43 件のファイルが処理されました。平均速度はファイル 1 件あたり約 1.6 分です。
実際の処理時間: 約1時間9分
現在処理されたファイル: done 39件 + deferred 4件 = 43件
平均速度: ファイル1件あたり約1.6分
全体 1,570件変換の予想時間: 約42時間最初は感覚的に1分に1個程度だと思っていましたが、実際のログに基づいて計算するとそれより少し時間がかかります。今日中に1,500個すべての変換を終えるのは難しいかもしれないので、処理速度と失敗/保留ファイル数を継続的に記録しながら進める必要があります。
次の検証計画
明日と明後日は時間が取れない可能性が高く、すぐに続きの作業ができないと思われます。それでも後で再開する作業はある程度整理できました。
まず、収集と変換の途中ですでに生成された JSONL をローカル PostgreSQL に投入しなければなりません。これまで作成した変換器は Markdown を docs_chunks、api_mapping、label_prototypes 用の JSONL に分割することに焦点を当てており、次のステップはこの JSONL を実際の DB に入れた後、検索可能な状態かどうかを確認することです。
その次に、docs/roadmaps/2026-06-21-initial-rag-classifier-architecture.md に記載した workflow の流れを Python スクリプトで小規模に検証する予定です。
source code
-> AST Parser
-> Retriever
-> evidence JSONL / evidence bundle
-> Qwen 3.6 API 呼び出し
-> 応答 確認つまり、任意の Godot ソースコードを Python スクリプトに入れ、AST パーサがシンボルとバージョンシグナルを抽出するか確認する。その結果を Retriever に入れて PostgreSQL から関連する公式ドキュメントのチャンクや API マッピングを取得させ、返された JSONL/evidence バンドルを Qwen 3.6 API に渡したときにどのような応答が返るかを随時確認する予定です。
このプロセスは最終的な自動化ではなく、各段階が実際に連携しているかを確認する小規模なエンドツーエンド検証に近い。特に Qwen が記憶に基づいて回答するのか、あるいは Retriever が渡した根拠に基づいて回答するのかを確認する必要がある。
公開リポジトリと非公開への切り替えに関する考え
最近このリポジトリを一度公開した後、再び非公開に切り替えました。理由は単純だったようです。自分の実力を見せたくなかった。
今の自分の実力はまだまだ不十分だと感じている。しかし同時に、Godot専用のモデルを作成し、Hugging Faceにアップロードし、それを出発点として講義動画、大学、ポートフォリオ、名誉といったさまざまな領域へと拡げたいという考えも抱いた。見る角度によっては、あまりにも夢のような空想に思えるかもしれない。それでも、自分が残した回顧と作業記録が誰かの足掛かりとなり成長できるのであれば、私自身もその過程でより速く成長できるのではないかと考えた。
実はまだ公開したくない気持ちがあります。自分が作ったものが深みがないように見えるのが怖くてもあり、逆にいろいろな知識を浅くでも組み合わせて分かりやすく作り上げた部分が誰かにそのまま盗まれるのではないかと警戒していたようにも思います。結果物がすごい技術だからというより、これまで考え、つなげてきた痕跡が丸ごと露呈することが負担に感じられたようです。
PR や CI/CD パイプラインも設定しましたが、元々考えていた流れは GitHub workflow で PR が上がったら Oracle Cloud に立てたローカル LLM エンドポイントが自動で PR レビューを行う構造でした。Oracle Cloud 側は 24 GB VRAM 環境なので、ほとんどのローカルモデルは動かせそうだと思い、ホスティングされた LLM をコードレビュー自動化に組み込むことを考えていました。ただし Oracle Cloud アカウントを紛失したため、この流れは当面再利用できません。RunPod も PR 検証用に使うには作業のたびに設定をやり直す手間があるので、当面は手動作業と文書化中心で進め、LLM ベースの PR レビュー自動化は後で再度取り組むのが現実的だと思います。
結論はこれだと思われる。実際には誰も見ない可能性が高いにもかかわらず、私は失敗することへの警戒心が非常に強かった。しかしたとえ誰かが私の作業を参考にしたり持ち去ったとしても、それを足掛かりにして自分もさらに優れなければならない。公開するかどうかは依然として慎重に決める必要があるが、恐れのために記録自体を止めてはいけない。