2026년 6월 21일 일요일

2026-06-21 회고

Godot 공식문서 JSONL 변환 흐름을 다시 질문함

Qwen에게 2026-06-21-initial-rag-classifier-architecture.md의 스키마 내용을 붙여 넣고, Markdown 문서를 JSONL로 변환하는 파이썬 코드 방향을 질문했다.

처음 질문의 핵심은 단순 변환 스크립트였다.

Markdown을 입력하면 JSONL로 변환하는 Python 코드가 필요함
실행 명령어까지 함께 제공되면 좋겠음
JSONL 내용은 Qwen API를 호출해서 생성하고 싶음
JSONL로 저장될 때 스키마가 깨지지 않아야 하므로 검사 로직이 필요함
정규표현식 또는 스키마 검증으로 JSONL 형식을 확인하고 싶음
API 호출 시 어떤 테이블에 매핑해야 하는지도 모델이 판단하면 좋겠음
필요하다면 docs_chunks, api_mapping, label_prototypes 전체 스키마를 생성해야 함

CLI 스크립트에서 웹 기반 도구로 생각이 확장됨

이후 단순 CLI 변환기만으로는 흐름을 보기 어렵다고 판단했다. 그래서 웹으로 호출되는 구조도 함께 고민했다.

웹 화면에서 API key를 입력할 수 있으면 좋겠음
Markdown 파일 업로드 또는 폴더 업로드를 지원하면 좋겠음
변환 전후 diff나 변경 내용을 웹에서 눈으로 확인할 수 있으면 좋겠음
단순히 결과 파일만 생성하는 것보다, 변환 과정과 판별 결과를 사람이 검토할 수 있어야 함

이 질문을 하면서 JSONL 변환기는 단순 배치 스크립트가 아니라, 사람이 검토하고 승인하는 데이터 가공 도구에 가까워져야 한다고 느꼈다.

한 파일이 여러 테이블로 갈 수 있다는 문제를 다시 확인함

가장 중요한 추가 질문은 한 Markdown 파일이 하나의 테이블에만 매핑되지 않을 수 있다는 점이었다.

예를 들어 migration 문서 하나는 다음 세 종류의 JSONL을 동시에 만들 수 있다.

공식 설명 청크는 docs_chunks.jsonl
API 변경 규칙은 api_mapping.jsonl
변환/분류 예시는 label_prototypes.jsonl

따라서 변환기는 파일 하나를 입력받아 단일 JSONL만 만드는 구조가 아니라, Qwen을 호출해 어떤 테이블 레코드가 필요한지 먼저 판별하고, 복수 응답이 나오면 한 파일에서 두 개 이상의 JSONL 레코드를 생성할 수 있어야 한다.

오늘 새로 잡은 설계 방향

Markdown to JSONL 변환은 분류 -> 생성 -> 검증 -> 저장 단계로 나눈다.
Qwen은 본문을 읽고 필요한 대상 테이블을 판단하는 역할을 맡을 수 있다.
다만 Qwen 응답을 그대로 신뢰하지 않고, 로컬 스키마 검증기가 최종 저장 여부를 결정해야 한다.
정규표현식은 최소한의 형식 검사용으로 쓰고, 실제 필드 검증은 JSON Schema 또는 Pydantic 같은 구조적 검증이 더 적합하다.
한 Markdown 파일에서 여러 JSONL 산출물이 나올 수 있음을 기본 전제로 둔다.
웹 UI는 단순 편의 기능이 아니라, 자동 생성된 레코드를 사람이 확인하고 승인하는 검수 계층이 될 수 있다.

다음 작업 메모

docs_chunks, api_mapping, label_prototypes별 JSON Schema 초안을 작성한다.
Markdown 파일 하나를 입력받아 Qwen에게 대상 테이블 후보를 판별하게 하는 프롬프트를 설계한다.
Qwen 응답이 여러 테이블 레코드를 포함할 때 파일별로 분리 저장하는 규칙을 만든다.
JSONL 한 줄 단위 검증 스크립트를 먼저 CLI로 만든다.
그 다음 웹 UI에서 업로드, 변환, diff, 검증 결과, 승인/반려 흐름을 볼 수 있게 확장한다.

남겨둘 질문

테이블 매핑 판별까지 Qwen에게 맡기되, 어떤 경우에 사람이 반드시 승인해야 하는가?
api_mapping 후보는 자동 생성 후 바로 DB에 넣을지, candidate 상태로만 저장할지?
웹 UI에서 diff는 원본 Markdown 대비 JSONL diff로 볼지, 이전 JSONL 버전 대비 diff로 볼지?
폴더 업로드 시 실패한 파일과 부분 성공 파일을 어떻게 재시도할지?