왜 kpubdata-builder인가¶
문제¶
한국의 data.go.kr에는 수천 개의 가치 있는 공공데이터셋이 있다. 하지만 전 세계 연구자와 개발자에게는 사실상 보이지 않는 것과 같다:
- API 사용을 위해 한국어 기반 정부 서비스 키 등록이 필요하다.
- 응답은 한국어 필드명을 가진 XML이다.
- 영어 문서가 없다.
- 표준 형식이 없다 — Parquet도, HuggingFace도, Kaggle도 없다.
우리가 하는 일¶
kpubdata-builder는 한국 공공 API의 원시 데이터를 게시 가능한 HuggingFace 데이터셋으로 바꾸는 파이프라인이다.
[data.go.kr API] → [kpubdata SDK] → [builder pipeline] → [HuggingFace Dataset]
목표: 한국 공공데이터를 전 세계 누구나 load_dataset() 한 줄로 쓸 수 있게 만든다.
(전 세계 누구나 load_dataset() 한 번으로 한국 공공데이터에 접근할 수 있게 한다.)
설계 결정¶
한국어 텍스트 값 유지¶
동 이름과 건물 이름은 한국어 그대로 유지한다. 로마자 표기는 정보 손실이 크고 일관되지 않다
(효성주얼리시티 → hyoseong Jewelry City? 아니다). 프로그래밍 방식 접근에는 영어 컬럼명만으로 충분하다.
도메인 맥락은 데이터셋 카드에서 설명한다.
하나의 설정 = 하나의 데이터셋¶
YAML 설정 하나가 게시될 내용을 완전히 정의한다: 소스, 컬럼 매핑, 타입, 필터, 출력. 선언되지 않은 컬럼도 없고, 예상 밖의 결과도 없다. 이 설정이 단일 진실 공급원이다.
검증 게이트¶
출력 스키마가 설정에서 벗어나면 게시가 실패한다. 구체적으로는 다음과 같다: - 출력에 선언되지 않은 컬럼이 있으면 → 실패 - 선언된 컬럼이 출력에 없으면 → 실패 - 100% null 컬럼이면 → 경고
피처 엔지니어링 없음¶
우리는 파생 분석 테이블이 아니라 정리된 원시 정부 데이터를 게시한다. 위도/경도, 지하철 거리, 금리 등은 사용자가 직접 추가한다 — Kaggle과 같은 방식이다. 데이터셋의 역할은 ML 준비 상태가 아니라 원본 충실성과 접근성이다.
편의성보다 원본 충실성¶
- 원본 값 보존(번역 없음, 데이터 로마자화 없음)
- null 처리: null 토큰은 표준화하지만 결측치 대체는 하지 않음
- 필터링: 명백히 잘못된 레코드만 제거(예: price = 0)
네이밍 규칙¶
HuggingFace 데이터셋은 kpubdata/{scope}-{subject}-{type} 규칙을 따른다.
예시:
- kpubdata/seoul-apartment-trades — 서울 아파트 매매 실거래
- kpubdata/korea-air-quality-hourly — 전국 시간별 대기질
- kpubdata/busan-bus-ridership — 부산 버스 승객 수
품질 기준¶
hf-publishing-standards.md의 기준:
- 최소 10,000개 레코드(권장 50,000개 이상)
- 시계열: 최소 36개월 범위
- 타입 선언 및 강제 적용
- 영어 설명 + 한국어 맥락을 담은 데이터셋 카드
- 법적 출처표시(공공누리 → CC 매핑)
- 로컬 dry-run을 포함한 사전 게시 체크리스트
다른 프로젝트와의 관계¶
| 프로젝트 | 역할 |
|---|---|
| kpubdata | Python SDK — API 인증, 페이지네이션, 응답 파싱 담당 |
| kpubdata-builder | 빌드 파이프라인 — 수집, 변환, 검증, 게시 담당 |
| kpubdata-studio | 시각적 워크벤치 UI(향후) — 탐색, 미리보기, 내보내기 담당 |
| HuggingFace kpubdata org | 게시된 데이터셋 — 사용자가 최종적으로 소비하는 결과물 |