Qwen 테스트용 JSONL 스키마와 용도

작성일: 2026년 6월 28일

목적

Qwen으로 Godot 코드 chunk를 만들고, 그 코드 chunk에 대해 정답 JSONL과 오답 JSONL을 붙여 예/아니오 검증을 할 때 참고할 JSONL 형식과 각 JSONL의 용도를 정리한다.

이 문서는 샘플 데이터를 제공하는 문서가 아니다. 테스트할 때 어떤 JSONL이 어떤 역할을 하고, 어떤 필드가 직접근거 판정에 쓰이는지 확인하기 위한 스키마 참조 문서다.

공통 기준

JSONL은 한 줄에 JSON 객체 하나를 쓴다.

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

테스트에서는 테이블 이름을 감싸는 wrapper를 두지 않고, 대상 테이블의 컬럼에 해당하는 필드를 top-level에 둔다.

좋음:
{"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는 공식문서 설명, 튜토리얼, class reference 본문을 chunk 단위로 저장하는 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`	변환 후 코드나 migration 설명 검증에 사용
`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가 이 패턴이면 해당 prototype은 `아니오`

테스트에서의 역할

케이스	기대
SOURCE_CODE에 `yield(get_tree().create_timer(...), "timeout")`가 있고 `before_code`도 같은 패턴임	`예`
SOURCE_CODE에 `move_and_slide(velocity)`가 있고 prototype이 해당 호출 방식 변경을 설명함	`예`
SOURCE_CODE는 `yield`인데 prototype은 `Color8` 변환임	`아니오`
SOURCE_CODE와 같은 label만 공유하고 실제 패턴이 없음	`아니오`

세 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개	같은 코드 chunk 기준으로 직접근거가 있으면 `예`, 전혀 다른 함수면 `아니오`
공통문법 코드에 관련 없는 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은 `예`