Smilegate MCP·Select AI 운영 가이드

1. 목적과 공통 문서 경계

이 문서는 Smilegate 게임 데이터 질의에만 적용한다. MCP, VPD, Data Redaction, DDS의 공통 설치·보안 원칙은 main의 공통 운영 가이드를 따른다. 여기서는 게임 식별, DB 실행 계획, Few-shot, 고객 질의 검증처럼 Smilegate에만 필요한 규칙을 정의한다.

2. 기본 질의 흐름

질문
 → oracle.select_ai.game_query_plan
 → DB가 게임·데이터 가능 여부·executionTasks 결정
 → QUERY task만 smilegate_fewshot_nl2sql 호출
 → 승인·검증 예제 검색
 → SHOWSQL 생성 · SELECT/WITH 검증 · read-only 실행
 → generatedSql + items + rowCount를 Portal에 반환

game_query_plan은 항상 첫 호출이다. Portal과 Java는 게임명, prefix, 물리 테이블, 지표 필터를 하드코딩하거나 보정하지 않는다.

3. 운영자가 관리하는 DB 객체

목적	주요 객체/스크립트	운영 원칙
게임 식별	`SG_GAME_CATALOG`, `80_sg_game_mention_extract.sql`, `81_sg_game_query_plan.sql`	별칭·지원 여부·대상 테이블을 DB에서 결정
QA/Few-shot	`SG_QA_VECTOR_EXAMPLE`, `75_sgmp_qa_vector_retrieval.sql`, `140_sgmp_hybrid_fewshot_reranking.sql`	승인·검증 예제만 검색
메타데이터	comment/annotation API, 게임별 View·테이블 정의	Select AI가 객체 역할과 조인을 이해하도록 관리
고객 기준 판정	`129`~`142` SQL 및 QA 이력	값뿐 아니라 SQL 의미를 확인

4. Few-shot 승인과 리타이어

APPROVED 및 VERIFIED 예제만 후보가 된다.
RETIRED 예제는 질문이 같아도 검색하지 않는다.
예제 SQL은 런타임에 직접 실행하지 않는다. SQL 구조·필수 필터·집계 정의를 새 SHOWSQL 생성의 참고 자료로만 사용한다.
실패 원인은 데이터 부재, 게임 식별, 메타데이터, 지표 정의, 예제 부족으로 분류한다.
수정은 Java의 예외 목록이 아니라 DB의 example 상태·설명·SQL template·평가 기준에 반영한다.

5. 고객 질의 검증 순서

게임이 SUPPORTED이며 데이터 대상이 있는지 확인한다.
executionTasks가 대상별로 생성됐는지 확인한다.
generatedSql이 날짜·지표·필터·집계 기준을 보존하는지 확인한다.
items, rowCount, 빈 결과와 SQL 오류를 구분한다.
결과값이 같아도 기준 SQL의 필수 조건이 다르면 QA 실패로 처리한다.
실패 사례를 검토한 뒤 필요한 경우에만 새로운 승인 Few-shot을 등록한다.

6. 자주 보는 장애

증상	확인 순서
게임 미식별	별칭 카탈로그, 거리 임계값, `game_query_plan` 결과
SQL 미실행	`REPORT_UNAVAILABLE` 사유와 data eligibility
Few-shot 미적용	승인/검증/리타이어 상태와 hybrid score
잘못된 집계	고객 기준 SQL, annotation, 예제 설명
읽기 전용 거절	SHOWSQL 원문과 SQL validator 결과

3.2 KiB Raw Blame History