Qwen テスト用 JSONL スキーマと用途

作成日: 2026年 6月 28日

目的

Qwen で Godot コードチャンクを作成し、そのコードチャンクに対して正解 JSONL と不正解 JSONL を付けて はい/いいえ 検証を行う際に参照する JSONL 形式と各 JSONL の用途を整理する。

この文書はサンプルデータを提供する文書ではない。テスト時にどの JSONL がどの役割を持ち、どのフィールドが直接根拠判定に使用されるかを確認するためのスキーマ参照文書である。

共通基準

JSONL は 1 行に JSON オブジェクトを 1 つ書く。

{...}
{...}
{...}

テストではテーブル名を囲むラッパーを設けず、対象テーブルのカラムに対応するフィールドをトップレベルに置く。

良い:
{"chunk_id":"...","content":"...","code_blocks":[...]}

回避:
{"table":"docs_chunks","payload":{"chunk_id":"..."}}

DBで自動生成したり検索インデックスに書き込むフィールドは、テスト JSONL から直接埋める必要はありません。

DB 運用フィールド	テスト JSONL 基準
`id`	除外
`embedding`	除外または null
`search_tsv`	除外
`created_at`	除外

Qwen 直接根拠検証で重要なのは「JSONL のどのフィールドが SOURCE_CODE の実際の文字列/API/パターンと直接一致するか」です。

docs_chunks

用途

docs_chunks は公式ドキュメントの説明、チュートリアル、クラスリファレンス本文をチャンク単位で保存する JSONL です。

コード説明のリクエスト、共通 API の使用方法確認、Godot 3/4 の共通文法説明の確認に使用されます。マイグレーション規則そのものよりも「このコードがどの公式ドキュメント説明と直接関連しているか」を確認する根拠です。

JSONL 形式

{
  "chunk_id": "text, required",
  "doc_version": "text, required",
  "source_url": "text, required",
  "source_file": "text, required",
  "source_sha256": "text, required",
  "doc_type": "text, required",
  "symbol": "text or null",
  "section_path": "array, required",
  "heading": "text or null",
  "content": "text, required",
  "code_blocks": "array, required",
  "language_tags": "array<string>",
  "godot_version_tags": "array<string>",
  "api_symbols": "array<string>",
  "token_count": "integer or null",
  "metadata": "object"
}

直接根拠で見るフィールド

フィールド	直接根拠基準
`content`	SOURCE_CODEにある API、関数名、ノード名、コードパターンを説明する必要がある
`code_blocks`	SOURCE_CODEと同じコード文字列または呼び出しパターンが存在する必要がある
`api_symbols`	SOURCE_CODEにある API/シンボルと直接一致する必要がある
`heading`	補助根拠。heading だけが同じで本文/コード根拠がない場合は弱い
`godot_version_tags`	バージョン参照用。これだけで `예` 判定してはいけない

テストでの役割

ケース	期待
SOURCE_CODE が `get_viewport_rect().size` を使用し、`content` または `code_blocks` にも同じ表現がある	`예`
SOURCE_CODE と同じ広いテーマだけ共有し、実際の文字列/API がない	`아니오`
Godot 3/4 共通文法の説明で、コード文字列が直接合致する	`예`
バージョンタグだけが合致し、コード根拠がない	`아니오`

api_mapping

用途

api_mapping は Godot 3 から Godot 4 へ名前、クラス名、関数名、シンボル名がどのように変わったかを保存する JSONL です。

単純な名前変更、rename、replacement、deprecated/removed API 判定に使用されます。関数の使用方法全体が変わる例は label_prototypes 側に近いです。

JSONL 形式

{
  "mapping_id": "text, required",
  "source_api": "text, required",
  "target_api": "text or null",
  "change_type": "text, required",
  "godot_from": "text, required",
  "godot_to": "text, required",
  "confidence": "text, required",
  "evidence_chunk_ids": "array<string>",
  "match_terms": "array<string>",
  "notes": "text",
  "negative_patterns": "array<string>"
}

直接根拠で見るフィールド

フィールド	直接根拠基準
`source_api`	SOURCE_CODEに実際に出現している必要がある
`target_api`	変換後コードやマイグレーション説明の検証に使用
`match_terms`	SOURCE_CODE内の実際の文字列/APIと直接一致している必要がある
`notes`	補助説明。単独の根拠というよりは source_api/match_terms と合わせて見る
`negative_patterns`	SOURCE_CODEがこのパターンに該当すると、むしろ `いいえ` の根拠になる

テストでの役割

ケース	期待
SOURCE_CODEに `KinematicBody2D` があり JSONL `source_api` も `KinematicBody2D` である	`はい`
SOURCE_CODEに `yield(` があり JSONL `match_terms` に `yield(` がある	`はい`
JSONL が `Camera -> Camera3D` なのに SOURCE_CODE は `KinematicBody2D` である	`いいえ`
Godot 3/4、migration のような広い単語だけが重なる	`いいえ`

label_prototypes

用途

label_prototypes は単なる名前変更ではなく、関数の使用方法、引数構成、呼び出しパターンが全体として変わる例を保存する JSONL です。

api_mapping が「どの名前が何に変わったか」なら、label_prototypes は「コードをどのパターンで書くべきか」に近いです。

JSONL 形式

{
  "prototype_id": "text, required",
  "label": "text, required",
  "task_type": "text, required",
  "input_pattern": "text, required",
  "expected_finding": "text, required",
  "recommended_action": "text, required",
  "evidence_mapping_ids": "array<string>",
  "evidence_chunk_ids": "array<string>",
  "severity": "text",
  "validator_rules": "object"
}

validator_rulesは次のサブフィールドを持つことができます。

{
  "required_when_seen_in_code": "array<string>",
  "before_code": "text",
  "after_code": "text",
  "reject_when_seen_in_code": "array<string>"
}

直接根拠で見るフィールド

フィールド	直接根拠基準
`input_pattern`	SOURCE_CODE の呼び出しパターンと直接合致している必要がある
`expected_finding`	どの問題/パターンを見つけるべきかを説明
`recommended_action`	変換または説明の方向
`validator_rules.required_when_seen_in_code`	SOURCE_CODE 内に実際に存在すれば「はい」の根拠になる
`validator_rules.before_code`	SOURCE_CODE と直接同じ以前のコードパターンであれば強い「はい」の根拠
`validator_rules.reject_when_seen_in_code`	SOURCE_CODE がこのパターンであれば該当プロトタイプは「いいえ」

テストでの役割

ケース	期待
SOURCE_CODE に `yield(get_tree().create_timer(...), "timeout")` があり `before_code` も同じパターンである	`はい`
SOURCE_CODE に `move_and_slide(velocity)` がありプロトタイプがその呼び出し方式の変更を説明している	`はい`
SOURCE_CODE は `yield` だがプロトタイプは `Color8` 変換である	`いいえ`
SOURCE_CODE と同じラベルだけ共有し実際のパターンがない	`いいえ`

3 つの JSONL の境界

JSONL	核心質問	主に合致すべきもの
`docs_chunks`	このコードがどの公式ドキュメント説明/チュートリアルと直接関係があるか	`content`, `code_blocks`, `api_symbols`
`api_mapping`	このコードに含まれる API/シンボルが Godot 3 → 4 で名前や対象が変わったか	`source_api`, `target_api`, `match_terms`
`label_prototypes`	このコードの使用方法/引数/呼び出しパターンが全体的に変わる例に該当するか	`input_pattern`, `validator_rules`, `before_code`

共通文法処理

Godot 3 と Godot 4 で同じ文法であればバージョン差として判断しない。

状況	使用する JSONL	判定基準
`_ready()`, `_process(delta)`, `print()` のように共通で使用されるコード	該当コード/関数 JSONL 1 個 + 全く別の関数 JSONL 1 個	同じコードチャンク基準で直接根拠があれば「はい」、全く別の関数なら「いいえ」
共通文法コードに関係ない migration JSONL を付ける	`api_mapping` または `label_prototypes` 誤答	実際の API/パターンがなければ「いいえ」
Godot 3 固有 API が登場する	Godot 3 専用 JSONL + Godot 4 専用 JSONL	SOURCE_CODE の Godot 3 文字列/パターンと直接合致する JSONL は「はい」
Godot 4 固有 API が登場する	Godot 4 専用 JSONL + Godot 3 専用 JSONL	SOURCE_CODE の Godot 4 文字列/パターンと直接合致する JSONL は「はい」