2026-06-17 Godot LLM/RAG 판별기 구축 회고

한 줄 요약

오늘은 Godot 특화 코딩 모델의 방향을 단순 Q&A 모델에서 repo-level SWE Agent로 다시 잡고, 그 앞단에 필요한 공식문서 기반 RAG 판별기와 데이터 생성 파이프라인의 첫 실체를 만들었다.

오늘 하루의 큰 흐름

처음에는 “Godot 공식문서로 RAG 챗봇을 만들자” 정도의 목표였다. 하지만 이야기와 작업이 진행되면서 목표가 더 분명해졌다.

Godot 공식문서 수집
-> 공식문서 기반 RAG 판별기
-> GitHub Godot 프로젝트 라벨링
-> SFT/DPO 데이터 생성
-> Qwen 기반 Godot 4 코딩 모델
-> repo-level SWE Agent

즉 오늘의 핵심은 챗봇 하나를 만드는 것이 아니라, 나중에 Godot 프로젝트를 실제로 읽고 고치는 모델을 만들기 위한 데이터 판별/생성 기반을 세우는 것이었다.

1. 단순 Q&A 모델로는 부족하다는 판단

오늘 가장 먼저 정리한 것은 모델 목표의 성격이었다.

기존에는 Godot 4 질문/답변 데이터셋을 만들고, 모델이 Godot 4 코드 답변을 잘하도록 학습시키는 방향을 생각했다. 하지만 “맵을 만들어줘” 같은 요청을 생각해보면, 이건 단순 Q&A 문제가 아니었다.

실제 요청 흐름은 다음에 가깝다.

사용자 요청 이해
-> 레포지토리 구조 탐색
-> 관련 scene/script/resource 찾기
-> 에셋 경로와 기존 코드 스타일 확인
-> Godot 4 문법/API 판단
-> 코드 수정
-> 실행/테스트/검증
-> patch 생성

이 흐름은 답변 하나를 생성하는 문제가 아니라 software engineering agent 문제다. 그래서 오늘 모델 방향을 SWE-agent trajectory training 관점으로 다시 잡았다.

오늘 기록한 핵심 키워드:

Long-context repository-level software engineering agent training
SWE-agent trajectory training
Godot repo-level patch generation
long-context trajectory dataset

참고 사례도 같이 정리했다.

SWE-agent trajectories
SWE-smith
SWE-Gym
CoderForge-Preview
ACC
RepoBench / CrossCodeEval / RepoCoder
aiXcoder CoLT
godot-dodo
wallstoneai/godot-gdscript-dataset

오늘의 결론은 작은 instruction Q&A만으로는 부족하다는 것이었다. 최종적으로 필요한 것은 Godot 프로젝트 단위의 탐색, 판단, 수정, 검증 trajectory다.

2. Godot LLM 전체 로드맵 정리

그 다음에는 전체 개발 로드맵을 다시 잡았다.

큰 흐름은 다음과 같이 정리했다.

데이터
-> 1차 RAG 챗봇
-> SFT
-> DPO
-> SWE Agent

단계를 더 자세히 나누면 다음과 같다.

Stage 0. 준비 단계
Stage 1. 데이터 수집 및 구조화
Stage 2. 1차 RAG 챗봇 개발
Stage 3. 데이터 라벨링 및 데이터셋 생성
Stage 4. 모델 학습
Stage 5. SWE Agent 개발
Stage 6. 지속적 개선

이 로드맵에서 가장 중요한 판단은 1차 RAG 챗봇을 단순 질의응답 도구로 보지 않는다는 점이다. 먼저 Godot 공식문서 전문가 역할을 하는 RAG 판별기를 만들고, 그 판별기를 통해 GitHub 데이터를 라벨링/가공한 뒤 SFT/DPO와 SWE Agent로 확장하는 구조가 필요하다고 봤다.

특히 Stage 5의 SWE Agent는 단순 코드 생성기가 아니라 다음 능력을 가져야 한다.

프로젝트 분석
필요 파일 탐색
코드 수정
Godot CLI 또는 실행 결과 검증
실패 원인 분석
patch 생성

3. RAG 판별기 기반 데이터 생성 구조 설계

오늘 또 하나 중요했던 판단은 “LLM에게 최종 라벨 결정을 맡기지 않는다”는 것이었다.

처음에는 RAG 챗봇이 GitHub 코드나 문서를 보고 Godot 3/4 여부를 판별해줄 수 있다고 생각하기 쉬웠다. 하지만 라벨링은 학습 데이터 품질에 직접 영향을 주기 때문에, LLM의 즉흥 판단에 맡기면 위험하다.

그래서 구조를 다음처럼 잡았다.

LLM은 생성 보조
라벨은 시스템이 결정
최종 JSONL은 Python pipeline이 조립/검증

시스템이 담당해야 하는 것:

심볼 추출
API 매핑 DB 조회
공식문서 벡터 검색
키워드 검색
라벨 프로토타입 검색
라벨 스코어링
confidence 계산
최종 JSONL 조립
검증

LLM이 담당해도 되는 것:

수정 코드 초안 생성
설명 생성
SFT 질문/답변 생성
DPO 나쁜 답변 생성
patch 초안 생성
검증/문제점 설명 보조

생성 대상 데이터셋도 8가지로 정리했다.

version_classification
api_mapping
migration_fix
instruction_sft
dpo_preference
repo_explorer
patch_generation
metadata_verification

이 정리는 오늘 만든 RAG 후처리 코드의 설계 기준이 되었다. 특히 api_mapping, symbol_catalog, keyword_index, search_text를 분리한 이유도 여기서 나온다.

4. RAG 판별기에서 Qwen 3.6 모델로 가는 MVP 흐름

Godot RAG 판별기와 Qwen 3.6 코딩모델 사이의 MVP 흐름도 별도로 정리했다.

정리한 흐름:

godot_docs_full.zip 원본 문서 준비
-> chunk_docs.py 기반 1차 청킹
-> Godot 전용 후처리
-> 로컬 검색 인프라 구축
-> GitHub 데이터 수집 및 구조화
-> RAG 판별기 실행
-> 학습 데이터셋 생성
-> Qwen 3.6 SFT/DPO

여기서 로컬 검색 인프라는 하나의 벡터DB만 의미하지 않는다.

필요한 구성:

Vector DB
Keyword Index
Reranker
API Mapping DB
Label Prototype DB

또한 GitHub 데이터는 단순 코드 조각이 아니라 repo 단위 구조로 들어와야 한다.

필요한 입력:

.gd
.tscn
.tres
project.godot
README
repo tree
metadata

1차 SFT 목표도 다시 정리했다.

Godot 4 우선 사고
GDScript 기본 출력
Godot 3 API 거부
Godot 3 -> 4 변환 근거 설명

이후 DPO에서는 좋은 답변과 나쁜 답변 기준을 더 명확히 잡아야 한다.

나쁜 답변: Godot 3 API가 섞인 답변
좋은 답변: Godot 4 순수 코드와 근거가 있는 답변

5. v1 공식문서 청킹

설계 정리 이후 실제 공식문서 데이터를 RAG에 넣을 수 있는 형태로 만들었다.

처음 만든 산출물은 다음 파일이다.

work/godot_rag/chunks/docs_chunks.jsonl

공식문서 Markdown 1,570개를 heading과 길이 기준으로 나누어 9,741개 청크를 만들었다.

결과:

Input pages: 1,570
Output chunks: 9,741
Max chunk chars: 2,800
Overlap chars: 350

v1에서 좋았던 점:

공식문서 전체를 JSONL 청크로 만들었다.
JSONL 파싱은 안정적이었다.
class_reference, tutorial, migration 같은 기본 문서 타입이 분류되었다.

v1의 문제:

Sphinx 잔여 문구가 많이 남았다.
너무 짧은 노이즈 청크가 있었다.
heading, section, method/property 구조가 충분히 살아 있지 않았다.
class reference가 API 단위로 정밀하게 분리되지 않았다.

v1은 “공식문서 수집과 기본 청킹 성공” 단계였다. 검색 MVP의 출발점은 되었지만, 라벨 판별기용으로는 부족했다.

6. v2 후처리

다음으로 postprocess_chunks.py를 만들고 v2 청크를 생성했다.

파일:

work/godot_rag/postprocess_chunks.py
work/godot_rag/chunks/docs_chunks_v2.jsonl

v2에서 처리한 것:

404 청크 제거
짧은 노이즈 청크 제거
Sphinx 잔여 문구 제거
symbols 추출
class_name 추출
section/member_type/member_name 보강
migration 관련 청크 표시

결과:

Input chunks: 9,741
Output chunks: 8,778
Dropped 404 chunks: 3
Dropped short/noise chunks: 960
Migration-related chunks: 695

v2는 공식문서 기반 RAG 검색 MVP로는 사용할 수 있는 상태가 되었다. 하지만 최종 라벨 판별기로 보기에는 아직 부족했다. 특히 move_and_slide, velocity, @export, await 같은 문법/API 변화가 독립적인 판별 기준으로 분리된 상태는 아니었다.

7. 잘못된 v3 방향과 되돌림

처음 생각한 v3는 일부 핵심 API를 하드코딩해서 api_focus 청크를 만드는 방식이었다.

예시:

KinematicBody2D
CharacterBody2D
move_and_slide
@export
await

이 방식은 빠르게 검색 성능을 높이는 것처럼 보일 수 있다. 하지만 실제로는 위험했다.

문제:

사람이 고른 API에 검색기가 과적합될 수 있다.
목록 밖 API가 약해진다.
일부 대표 API가 전체 Godot API를 대표하는 것처럼 보일 수 있다.
누락된 API가 나중에 라벨링 사고로 이어질 수 있다.

그래서 기존 v3는 되돌렸다. 이 판단은 중요했다. 단기적으로는 손해처럼 보이지만, 최종 판별기 품질을 생각하면 하드코딩 focus 청크는 잘못된 방향이었다.

8. catalog 기반 v3 재설계

되돌린 뒤에는 방향을 바꿨다.

새 원칙:

v2 청크를 하나도 잃지 않는다.
새 focus 청크를 임의로 만들지 않는다.
공식문서 전체에서 symbol/catalog/index/mapping을 자동 추출한다.
검색 보강 정보는 metadata로 붙인다.

추가한 코드:

work/godot_rag/build_symbol_catalog.py
work/godot_rag/build_keyword_index.py
work/godot_rag/build_api_mapping.py
work/godot_rag/make_chunks_v3.py
work/godot_rag/validate_rag_artifacts.py
work/godot_rag/retrieval_smoke_test.py

생성한 산출물:

work/godot_rag/catalog/symbol_catalog.jsonl
work/godot_rag/catalog/keyword_index.json
work/godot_rag/catalog/api_mapping.jsonl
work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl
work/godot_rag/validation/validation_report.json
work/godot_rag/validation/retrieval_smoke_test.json

전체 docs_chunks_v3.jsonl은 약 189MB라 GitHub 단일 파일 제한에 걸릴 수 있었다. 그래서 저장소에는 줄 단위로 보존되는 분할 파일을 올리고, 필요하면 로컬에서 다시 합치도록 했다.

cat work/godot_rag/chunks/docs_chunks_v3.part-*.jsonl \
  > work/godot_rag/chunks/docs_chunks_v3.jsonl

9. v3 정합성 검증

v3에서 가장 중요하게 본 것은 누락 방지였다. v2 청크가 하나라도 빠지면 나중에 공식문서 근거가 사라질 수 있기 때문이다.

그래서 validate_rag_artifacts.py를 만들었다.

검증 기준:

v2 chunk_id set == v3 chunk_id set
no missing or extra v3 chunks
catalog/index/mapping references point to existing chunks
search_text is present
no old hardcoded api_focus fields remain

검증 결과:

status: pass
v2 chunks: 8,778
v3 chunks: 8,778
v2 unique chunk_id: 8,778
v3 unique chunk_id: 8,778
symbol catalog entries: 134,922
keyword index keys: 192,257
api mapping records: 144
v3 chunks with api mappings: 1,900
v3 migration-related chunks: 2,392

또한 임베딩 전 단계에서 lexical/keyword 기반 smoke test도 수행했다.

대표 질의:

KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4

결과는 5개 모두 통과했다.

10. 오늘 발견한 가장 큰 위험

오늘 가장 중요한 인사이트는 “많이 뽑는 것”과 “믿고 라벨에 쓰는 것”이 다르다는 점이었다.

공식문서 전체에서 넓게 뽑으면 recall은 좋아진다. 하지만 그 결과를 모두 같은 신뢰도로 취급하면 keyword index가 오염된다.

예를 들어 다음은 실제 API나 문법 요소일 가능성이 높다.

CharacterBody2D
move_and_slide
FileAccess
@export
await

반면 다음은 문서 일반 단어이거나 표 컬럼일 가능성이 높다.

Returns
See
Tip
MIT
Software
Type

실제로 smoke test를 확인하는 과정에서 Type -> EditorSceneFormatImporterFBX2GLTF처럼 일반 표 컬럼이 API mapping 후보로 잡힐 수 있는 문제를 발견했다. 이 문제는 Type을 mapping 후보에서 제외하도록 보정했다.

여기서 얻은 결론은 명확하다.

넓게 추출하는 것은 필요하다.
하지만 넓게 추출한 모든 것을 trusted fact로 쓰면 안 된다.

11. v3.1 신뢰도 분리 구조로 개편

위 위험을 확인한 뒤, v3를 그대로 최종 라벨 판별기에 쓰면 안 된다고 판단했다. 그래서 v3.1에서는 catalog를 하나로 뭉쳐 쓰지 않고, 신뢰도와 용도별로 분리했다.

v3.1에서 새로 잡은 구조:

trusted_api_symbols
syntax_symbols
migration_mappings
mentioned_symbols
candidate_terms
rejected_terms
retrieval_keys
search_text

각 필드의 의미도 명확히 나눴다.

trusted_api_symbols:
class reference 구조에서 직접 확인된 class/method/property/signal/constant

syntax_symbols:
GDScript 문법 문서와 migration 문서에서 확인된 문법 요소

migration_mappings:
old -> new 관계가 근거 chunk와 함께 연결된 Godot 3 -> 4 변경 매핑

mentioned_symbols:
tutorial/body에서 언급되었지만 이미 trusted/syntax catalog에 있는 심볼

candidate_terms:
검색 recall 보조용 후보 단어

rejected_terms:
Returns, See, Tip, MIT, Software 같은 라벨 근거로 쓰면 안 되는 일반 단어

추가한 코드:

work/godot_rag/build_v31_artifacts.py
work/godot_rag/validate_v31_artifacts.py

생성한 v3.1 산출물:

work/godot_rag/chunks/docs_chunks_v3_1.jsonl
work/godot_rag/chunks/docs_chunks_v3_1.summary.json
work/godot_rag/catalog_v3_1/trusted_api_catalog.jsonl
work/godot_rag/catalog_v3_1/syntax_catalog.jsonl
work/godot_rag/catalog_v3_1/api_mapping.jsonl
work/godot_rag/catalog_v3_1/mention_index.json
work/godot_rag/catalog_v3_1/keyword_index.json
work/godot_rag/catalog_v3_1/v3_1.summary.json
work/godot_rag/validation_v3_1/validation_report.json
work/godot_rag/validation_v3_1/retrieval_smoke_test.json

v3.1 결과:

Source v2 chunks: 8,778
Output v3.1 chunks: 8,778
Trusted API catalog entries: 26,318
Syntax catalog entries: 68
API mapping records: 144
Mention index keys: 10,292
Keyword keys: 71,543
Validation status: pass
Retrieval smoke tests: 5 / 5 passed

중요하게 고친 부분도 있었다.

처음 v3.1 생성 과정에서는 class_name을 v2 메타데이터에서 그대로 믿으면 Tutorials, All, String 같은 잘못된 값이 trusted catalog로 올라갈 수 있었다. 그래서 source URL과 class reference 경로를 기준으로 canonical class name을 다시 만들었다. 이 수정 후 Characterbody2d 같은 casing 문제도 CharacterBody2D로 바로잡혔다.

또 하나 중요한 검증은 move_and_slide였다. 넓은 추출 방식에서는 ProjectSettings.move_and_slide 같은 거짓 trusted 항목이 생길 위험이 있었다. v3.1에서는 class reference의 구조화된 section에서 확인된 멤버만 trusted로 승격하도록 제한했고, 최종적으로 move_and_slide trusted 항목은 다음처럼 실제 Godot class에만 남았다.

CharacterBody2D.move_and_slide
CharacterBody3D.move_and_slide

즉 오늘 v3.1에서 한 일은 단순히 필드를 늘린 것이 아니라, “검색에는 넓게 쓰되 라벨 결정에는 좁고 믿을 수 있는 근거만 쓰는 구조”로 바꾼 것이다.

12. v3.1 정합성 검증

v3.1에서는 누락이 특히 위험했다. v2의 8,778개 청크 중 하나라도 빠지면 공식문서 근거가 사라질 수 있기 때문이다.

검증 기준:

v2 chunk_id set == v3.1 chunk_id set
v3.1 unique chunk_id count == 8,778
doc_type 분포 유지
legacy 혼합 필드 제거
trusted/syntax/migration catalog 참조 무결성 확인
search_text 존재 확인

검증 결과:

status: pass
errors: 0
warnings: 0
v2 chunks: 8,778
v3.1 chunks: 8,778

검색 smoke test도 다시 돌렸다.

KinematicBody2D Godot 4 replacement
CharacterBody2D move_and_slide velocity
yield await Godot 4
export var @export Godot 4
onready var @onready Godot 4

결과는 5개 모두 통과했다. 이 단계의 의미는 “최종 라벨러가 완성됐다”가 아니라, v3.1 구조가 최소한 MVP vector/keyword index로 넘어갈 수 있을 정도로 무결하다는 뜻이다.

13. GitHub 반영과 기록 정리

오늘은 코드와 데이터 산출물을 만든 것뿐 아니라 GitHub 반영도 정리했다.

처리한 일:

remote 설정
대용량 v3 파일 분할
작업 브랜치 push
원격 main과 로컬 히스토리 병합
main push
문서 디렉토리 정리

docs_chunks_v3.jsonl은 약 189MB라 그대로 올리면 GitHub 단일 파일 제한에 걸릴 수 있었다. 그래서 docs_chunks_v3.part-000.jsonl, docs_chunks_v3.part-001.jsonl, docs_chunks_v3.part-002.jsonl로 나눴다.

또한 처음에는 회고가 루트 retrospectives/에 생겼지만, 기존 저장소 구조와 맞지 않았다. 그래서 문서 구조를 다음처럼 정리했다.

docs/research-notes/   설계 메모
docs/roadmaps/         전체 로드맵
docs/retrospectives/   날짜별 회고
work/godot_rag/        RAG 코드와 산출물
outputs/godot_docs_full/ 공식문서 크롤링 결과

추가로 docs/README.md를 만들어 문서 디렉토리 역할도 정리했다.

14. Git author/email 정리

오늘 README에 기록한 것처럼 GitHub 잔디 반영 문제도 정리했다.

확인한 문제:

main 히스토리의 author/committer 이메일이 섞여 있음
로컬 호스트 이메일
naver 이메일
GitHub noreply 이메일

처리한 방향:

전역 Git 설정을 yyeongjin <appsky1888@gmail.com>으로 변경
main 히스토리 author/committer 통일
원격 반영
재작성 전 백업 브랜치 보관

백업 브랜치:

backup/before-author-email-rewrite-2026-06-17

이 작업은 RAG 자체와 직접 연결되지는 않지만, 오늘의 중요한 정리 작업 중 하나였다. 이후 기록과 커밋이 GitHub 프로필에 제대로 반영되도록 기반을 맞춘 작업이었다.

15. 오늘 만든/정리한 문서

오늘 생성하거나 정리한 주요 문서:

docs/research-notes/2026-06-17-swe-agent-trajectory-keywords.md
docs/research-notes/2026-06-17-godot-rag-labeler-data-generation.md
docs/research-notes/2026-06-17-godot-rag-to-qwen-coding-model-flow.md
docs/roadmaps/2026-06-17-godot-llm-roadmap.md
docs/retrospectives/2026-06-17-godot-rag-judge.md
docs/README.md

README에도 6월 17일 개발 일지와 RAG 데이터 준비 섹션을 추가했다.

16. 현재 결론

오늘 기준 상태를 이렇게 정리할 수 있다.

방향성:
Godot Q&A 모델이 아니라 Godot SWE Agent로 가야 한다.

데이터:
공식문서 RAG는 학습 데이터 생성을 위한 판별기 역할을 해야 한다.

라벨:
LLM이 아니라 Python pipeline이 결정해야 한다.

RAG:
v2는 안전한 기본 청크셋이다.
v3는 넓게 추출한 중간 catalog 산출물이다.
v3.1은 신뢰도 분리까지 적용한 현재 권장 RAG 산출물이다.

위험:
추출한 symbol을 모두 같은 신뢰도로 쓰면 안 된다.

오늘 작업은 단순히 파일 몇 개를 만든 것이 아니라, 잘못 가기 쉬운 방향을 몇 번 꺾은 날이었다. 특히 하드코딩 API focus 청크를 되돌린 판단, broad v3의 노이즈 위험을 발견한 판단, 그리고 v3.1에서 trusted/syntax/migration/mention/candidate/rejected를 분리한 판단이 중요했다.

17. 다음 작업

다음 작업은 바로 GitHub 코드 라벨링이 아니다.

먼저 해야 할 일:

docs_chunks_v3_1.jsonl의 search_text 기반 embedding 생성
vector search + keyword search를 결합한 hybrid retrieval 테스트
trusted_api_symbols, syntax_symbols, migration_mappings 기반 라벨 결정 Python pipeline 설계
GitHub repo 구조화 데이터 입력 포맷 정의
.gd, .tscn, .tres, project.godot, README를 함께 보는 repo-level 판별 흐름 설계
RAG 판별기 결과를 8종 JSONL 데이터셋 생성 파이프라인과 연결
원격 LLM endpoint가 준비되면 수정 코드/설명/SFT/DPO 후보 생성 보조로 연결
이후 Qwen 기반 SFT/DPO와 SWE Agent trajectory 학습으로 확장

오늘의 최종 교훈은 이것이다.

문서를 많이 모으는 것보다,
모은 지식을 어떤 신뢰도로 사용할지 분리하는 것이 더 중요하다.