Godot RAG 분류기 로컬 PostgreSQL 세팅

작성일: 2026 년 6 월 22 일

목적

Godot 공식문서 RAG 분류기를 위해 로컬 PostgreSQL 데이터베이스를 세팅한다. 기준 흐름은 다음과 같다.

JSONL -> PostgreSQL -> Retriever -> Validator -> Qwen 3.6

현재 단계의 목표는 학습 데이터 생성이 아니라, 공식문서 기반 근거 DB를 로컬에서 재현 가능하게 만드는 것이다. 테이블의 payload 컬럼은 JSONL 스키마와 같은 이름으로 유지하고, DB 운영용 파생 컬럼은 id, embedding, search_tsv, created_at처럼 검색/저장에 필요한 최소 컬럼만 둔다.

기준 설계 문서:

docs/roadmaps/2026-06-21-initial-rag-classifier-architecture.md

로컬 DB 구성

Docker Compose 파일:

infra/postgres/docker-compose.yml

사용 이미지:

pgvector/pgvector:pg16

접속 정보:

항목	값
database	`godot_rag`
user	`godot_rag`
password	`godot_rag_local`
host	`localhost`
port	`5432`

로컬 개발용 기본 URL:

postgresql://godot_rag:godot_rag_local@localhost:5432/godot_rag

생성되는 확장

extension	목적
`vector`	문서 청크와 라벨 프로토타입 임베딩 저장
`pg_trgm`	API 이름, heading, symbol의 fuzzy/부분 검색 보조

주의:

embedding 컬럼은 현재 차원을 고정하지 않은 vector 타입이다.
pgvector의 HNSW/IVFFlat 인덱스는 고정 차원이 필요하므로,
실제 vector index는 embedding 모델 차원이 확정된 뒤 별도 migration으로 만든다.

템플릿:

infra/postgres/init/004_vector_index_templates.sql

생성되는 스키마

DB 스키마 이름:

godot_rag

테이블:

테이블	역할
`godot_rag.docs_chunks`	공식문서 설명, 튜토리얼, class reference 청크
`godot_rag.api_mapping`	Godot 3 -> 4 API 변경, rename, replacement, deprecation 규칙
`godot_rag.label_prototypes`	분류/변환/거부/수정 예시 프로토타입
`godot_rag.ingest_reports`	JSONL 변환/주입 과정의 경고, 스킵, 검증 로그

테이블 설계

`docs_chunks`

공식문서 청크를 저장한다. 모든 row는 원본 URL, 원본 파일 경로, 원본 Markdown 해시를 보존해야 한다.

주요 컬럼:

컬럼	설명
`chunk_id`	재실행해도 바뀌지 않는 결정적 ID
`doc_version`	`stable`, `4.6` 등 문서 버전
`source_url`	Godot 공식문서 원본 URL
`source_file`	저장소 안 Markdown 경로
`source_sha256`	원본 Markdown 해시
`doc_type`	`class_reference`, `tutorial`, `migration` 등 문서 유형
`symbol`	class/API 문서 대표 심볼
`section_path`	제목 계층 JSON
`content`	검색과 임베딩 대상 본문
`code_blocks`	본문에서 추출한 코드 블록 배열
`api_symbols`	본문에서 감지한 Godot API 심볼
`embedding`	pgvector 임베딩
`search_tsv`	키워드 검색용 tsvector

`api_mapping`

Godot 3/4 변경 규칙을 저장한다.

중요 원칙:

공식문서 근거가 있으면 confidence = 'verified_from_docs'로 둔다.
아직 검토하지 않은 자동 추출 규칙은 confidence = 'candidate'로 둔다.
학습/라벨링에 직접 쓰는 규칙은 사람이 검토한 뒤 confidence = 'approved' 또는 별도 승인 JSONL을 통해 관리한다.

`label_prototypes`

분류기 출력의 라벨 기준과 대표 패턴을 저장한다.

초기 라벨 후보:

라벨	의미
`godot4_valid_api`	Godot 4 기준으로 유효한 API 사용
`godot3_api_in_godot4`	Godot 4 프로젝트에 Godot 3 API가 섞임
`deprecated_or_removed_api`	제거/폐기 API 사용
`migration_required`	Godot 3 -> 4 변환 필요
`ambiguous_version_signal`	버전 판단 근거가 부족하거나 충돌
`non_godot_noise`	Python/웹/Unity 등 Godot과 무관한 데이터
`unsafe_or_obfuscated_code`	난독화, 제어문자, 악성 의심 코드

실행 방법

DB 시작:

docker-compose -f infra/postgres/docker-compose.yml up -d

현재 로컬 환경에서는 docker compose 플러그인이 아니라 docker-compose 명령을 사용한다.

헬스체크:

docker inspect --format='{{json .State.Health.Status}}' godot-rag-postgres

컨테이너 내부에서 접속:

docker exec -it godot-rag-postgres psql -U godot_rag -d godot_rag

테이블 확인:

docker exec godot-rag-postgres \
  psql -U godot_rag -d godot_rag \
  -c "\\dt godot_rag.*"

확장 확인:

docker exec godot-rag-postgres \
  psql -U godot_rag -d godot_rag \
  -c "select extname from pg_extension where extname in ('vector', 'pg_trgm') order by extname;"

초기화

DB를 완전히 새로 만들 때만 사용한다. 로컬 볼륨이 삭제되므로 주의한다.

docker-compose -f infra/postgres/docker-compose.yml down -v
docker-compose -f infra/postgres/docker-compose.yml up -d

JSONL 주입 예정 경로

아직 주입 스크립트는 만들지 않았다. 다음 JSONL 산출물을 만들고 검증한 뒤 upsert 스크립트를 붙인다.

파일	대상 테이블
`work/godot_rag/jsonl/docs_chunks.jsonl`	`godot_rag.docs_chunks`
`work/godot_rag/jsonl/api_mapping.jsonl`	`godot_rag.api_mapping`
`work/godot_rag/jsonl/label_prototypes.jsonl`	`godot_rag.label_prototypes`
`work/godot_rag/jsonl/ingest_report.jsonl`	`godot_rag.ingest_reports`

다음 작업

outputs/godot_docs_full/pages 구조 분석 리포트를 만든다.
문서 타입별 청킹 기준을 확정한다.
docs_chunks.jsonl 스키마 검증 스크립트를 작성한다.
JSONL upsert 스크립트를 작성한다.
샘플 질문으로 Retriever 검색 품질을 검증한다.