From 72b88c43fc76a1c371d1c216ac309e4ea7ea882d Mon Sep 17 00:00:00 2001 From: devmrko Date: Mon, 3 Aug 2026 13:36:23 +0900 Subject: [PATCH] refs #739: add Smilegate MCP operations guide --- docs/runbooks/smilegate-mcp-operations.md | 63 +++++++++++++++++++ docs/smilegate-mcp-current-operation-guide.md | 3 + 2 files changed, 66 insertions(+) create mode 100644 docs/runbooks/smilegate-mcp-operations.md diff --git a/docs/runbooks/smilegate-mcp-operations.md b/docs/runbooks/smilegate-mcp-operations.md new file mode 100644 index 0000000..31d256e --- /dev/null +++ b/docs/runbooks/smilegate-mcp-operations.md @@ -0,0 +1,63 @@ +# Smilegate MCP·Select AI 운영 가이드 + +## 1. 목적과 공통 문서 경계 + +이 문서는 Smilegate 게임 데이터 질의에만 적용한다. MCP, VPD, Data Redaction, DDS의 +공통 설치·보안 원칙은 `main`의 공통 운영 가이드를 따른다. 여기서는 게임 식별, DB +실행 계획, Few-shot, 고객 질의 검증처럼 Smilegate에만 필요한 규칙을 정의한다. + +## 2. 기본 질의 흐름 + +```text +질문 + → 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. 고객 질의 검증 순서 + +1. 게임이 `SUPPORTED`이며 데이터 대상이 있는지 확인한다. +2. `executionTasks`가 대상별로 생성됐는지 확인한다. +3. `generatedSql`이 날짜·지표·필터·집계 기준을 보존하는지 확인한다. +4. `items`, `rowCount`, 빈 결과와 SQL 오류를 구분한다. +5. 결과값이 같아도 기준 SQL의 필수 조건이 다르면 QA 실패로 처리한다. +6. 실패 사례를 검토한 뒤 필요한 경우에만 새로운 승인 Few-shot을 등록한다. + +## 6. 자주 보는 장애 + +| 증상 | 확인 순서 | +| --- | --- | +| 게임 미식별 | 별칭 카탈로그, 거리 임계값, `game_query_plan` 결과 | +| SQL 미실행 | `REPORT_UNAVAILABLE` 사유와 data eligibility | +| Few-shot 미적용 | 승인/검증/리타이어 상태와 hybrid score | +| 잘못된 집계 | 고객 기준 SQL, annotation, 예제 설명 | +| 읽기 전용 거절 | SHOWSQL 원문과 SQL validator 결과 | + +## 7. 관련 자료 + +- [현재 MCP 도구 운영 안내](../smilegate-mcp-current-operation-guide.md) +- [Few-shot NL2SQL MCP 설계](../design/735-sgmp-fewshot-nl2sql-mcp/README.md) diff --git a/docs/smilegate-mcp-current-operation-guide.md b/docs/smilegate-mcp-current-operation-guide.md index d79f132..0dffb72 100644 --- a/docs/smilegate-mcp-current-operation-guide.md +++ b/docs/smilegate-mcp-current-operation-guide.md @@ -1,5 +1,8 @@ # Smilegate Data & AI PoC — 현재 MCP 도구 운영 안내 +> 전체 운영 절차는 [Smilegate MCP·Select AI 운영 가이드](runbooks/smilegate-mcp-operations.md)를, +> 고객사와 무관한 보안·VPD·Data Redaction 기준은 `main`의 공통 운영 문서를 따른다. + ## 1. 현재 기본 실행 경로 모든 게임 데이터 질문은 먼저 `oracle.select_ai.game_query_plan`을 호출한다.