refs #739: document DB-owned task and few-shot policy

2026-07-30 16:41:28 +09:00
parent 7bf8199343
commit 022ae7f9d2
16 changed files with 737 additions and 4 deletions
--- a/docs/design/735-sgmp-fewshot-nl2sql-mcp/README.md
+++ b/docs/design/735-sgmp-fewshot-nl2sql-mcp/README.md
@@ -1,11 +1,13 @@
-# SGMP Few-shot NL2SQL MCP (#735)
+# Redmine #735 · SGMP Few-shot NL2SQL MCP

 > 상태: Approved
 > 구현: `McpSseService`, `SelectAiService`, `McpProperties`

 ## 목적

-기존 Select AI Text2SQL 경로와 분리된 검증용 MCP tool을 제공한다. 질문과 유사한 검토 완료 예제를 벡터 검색하고, 그 SQL 패턴을 prompt에 참고자료로 넣은 뒤 `SHOWSQL`로 생성한 SQL을 읽기 전용으로 실행한다.
+기존 Select AI Text2SQL 경로와 분리된 MCP tool을 제공한다. 질문과 의미가 유사한 검토
+완료 예제를 DB에서 검색하고, 승인 SQL 구조를 참고자료로 넣은 뒤 `SHOWSQL`로 생성한 SQL을
+읽기 전용으로 실행한다.

 ## MCP 계약

@@ -13,11 +15,26 @@
 - **입력**: `prompt` (최대 4,000자)
 - **출력**: 벡터 Few-shot 예제(질문, SQL, 모델, cosine distance), 생성 SQL, 실행 상태, 행 수, 최대 100건 결과

-Few-shot SQL은 실행하지 않는다. 현재 메타데이터·alias 정책을 우선하고, Select AI가 새로 생성한 SQL만 read-only 검증 후 실행한다.
+Few-shot SQL은 실행하지 않는다. 현재 메타데이터·alias 정책을 우선하고, Select AI가 새로
+생성한 SQL만 read-only 검증 후 실행한다.
+
+## DB 검색·승인 기준
+
+- `sg_qa_vector_example`의 `reference_status='APPROVED'`,
+  `inspection_status='VERIFIED'`, SQL 존재 예제만 후보가 된다.
+- `RETIRED`는 동일 질문이라도 후보에서 제외된다. 리타이어 여부는 DB 컬럼으로 저장하며
+  Java가 별도 목록으로 판단하지 않는다.
+- 벡터 cosine distance가 `QA_VECTOR_MAX_COSINE_DISTANCE` 이하여야 한다.
+- 후보 순위는 벡터 유사도와 질문 문자열 유사도를 DB에서 결합한다. 정책값
+  `QA_VECTOR_LEXICAL_WEIGHT=0.35`, `QA_VECTOR_HYBRID_SCORE_MARGIN=0.05`는
+  유사한 후속 질문에는 참고 범위를 남기되, 핵심 요청어가 다른 예제가 최상위가 되는 문제를
+  줄인다.
+- 고객 기준 예제는 개별 승인 상태로 관리한다. 같은 문장만 허용하는 방식으로 제한하지 않으며,
+  승인된 SQL 구조가 새 질문의 참고 근거가 될 수 있다.

 ## 안전 규칙

-1. 벡터 검색 실패는 `UNAVAILABLE` 상태로 남기고 기존 정책 prompt로 폴백한다.
+1. 검색 후보가 없으면 `NO_MATCH`로 기록하고 일반 Select AI 생성은 계속한다.
 2. 생성 결과는 단일 `SELECT` 또는 `WITH`만 허용한다.
 3. DDL, DML, PL/SQL, 시스템 객체, 잠금 구문, 다중 문장은 차단한다.
 4. JDBC read-only 트랜잭션과 30초 query timeout, 최대 100행 제한을 적용한다.
--- a/docs/design/741-db-owned-execution-task-contract/README.md
+++ b/docs/design/741-db-owned-execution-task-contract/README.md
@@ -0,0 +1,41 @@
+# Redmine #739 · DB 소유 게임별 실행 작업 계약
+
+## 목표
+
+복수 게임 질문에서 Portal과 `smilegate_fewshot_nl2sql`은 게임명을 재해석하거나 원 질문을
+수정하지 않는다. ADB의 `sg_game_query_plan`이 DB 카탈로그·OCI Chat 결과를 바탕으로 실행
+가능한 작업을 만들고, 호출자는 그 작업을 그대로 실행한다.
+
+## 계약
+
+`executionTasks`의 `QUERY` 작업은 다음 값을 모두 가진다.
+
+- `action`: `QUERY`
+- `workerTool`: 호출할 worker 도구명
+- `workerArguments.prompt`: 원 질문의 지표·날짜·필터·결과 모양을 보존한 해당 target 전용 질의
+- `workerArguments.scopeGameKey`: DB가 확정한 game key
+- `workerArguments.queryPlan`: 해당 target 하나만 담긴 `SINGLE` plan
+- `fewShotArguments.question`: 보조 진단 도구가 필요할 때만 사용할 같은 target 전용 질의
+
+`REPORT_UNAVAILABLE` 작업은 worker 인자를 갖지 않으며 최종 응답 항목으로만 사용한다.
+
+## 책임 분리
+
+| 구성요소 | 책임 |
+| --- | --- |
+| `sg_game_query_plan` | 게임 식별, 데이터 가능 여부, target별 자연어 작업 생성, 단일 target plan 생성 |
+| Portal 오케스트레이터 | 작업 순회, worker 호출, 결과 합성, task 완료 판정 |
+| `fewshot_preflight` | reasoning에서 필요할 때만 후보 적합성을 확인하는 보조 진단 도구 |
+| `smilegate_fewshot_nl2sql` | 전달된 단일 작업으로 DB Few-shot 검색·승인 판정 후 SQL 생성 및 읽기 전용 실행 |
+
+## 안전 규칙
+
+- planner가 생성한 target 전용 작업 질의에는 다른 계획 target의 실제 mention이 포함되면 실패 처리한다. 호출자가 문자열을 제거하거나 보정하지 않는다.
+- worker는 `queryPlan`이 단일 target인지 검증만 하며, 전체 plan에서 target을 추출하거나 원 질문을 재작성하지 않는다.
+- worker의 Few-shot 검색은 DB가 발급한 `workerArguments.prompt`로 수행한다. preflight 결과는 선택적으로만 전달할 수 있으며 worker 실행의 조건이 아니다.
+- Java는 지표별 SQL 조건, 결과 모양, Few-shot 활성화/리타이어, 후보 유사도에 관여하지 않는다.
+  이 정책은 DB 메타데이터와 `sg_qa_vector_search`에서 관리한다.
+
+## 검증
+
+STD-11에서 Bubblyz는 `REPORT_UNAVAILABLE`, 카제나는 `QUERY` 한 건이 되어야 한다. 카제나 worker에 전달되는 prompt·plan·생성 SQL 어디에도 Bubblyz가 없어야 하며, 결과는 2026-07-15 매출 227681이어야 한다.
--- a/docs/smilegate-mcp-current-operation-guide.md
+++ b/docs/smilegate-mcp-current-operation-guide.md
@@ -0,0 +1,118 @@
+# Smilegate Data & AI PoC — 현재 MCP 도구 운영 안내
+
+## 1. 현재 기본 실행 경로
+
+모든 게임 데이터 질문은 먼저 `oracle.select_ai.game_query_plan`을 호출한다.
+
+```text
+일반 데이터 분석 질문
+game_query_plan → smilegate_fewshot_nl2sql
+
+게임별·일반 분석 질문
+game_query_plan → executionTasks → smilegate_fewshot_nl2sql
+```
+
+`game_query_plan`은 게임 카탈로그, 별칭, 벡터 검색 결과를 사용하여 질의 범위를 `NONE`,
+`SINGLE`, `MULTI`, `ALL` 중 하나로 판정하고 `executionTasks`를 발급한다. 다음 worker에는
+원 질문을 보존한 DB 작업 인자와 `GAME QUERY REFERENCE`를 전달한다. Portal은 이를 보정하지
+않고 task 종료 상태를 합산한다.
+
+## 2. 기본 실행 MCP 도구
+
+### `oracle.select_ai.game_query_plan`
+
+- 모든 게임 데이터 질의의 필수 첫 단계다.
+- OCI GenAI Chat으로 질문에서 게임명 후보를 식별하고 게임 카탈로그 벡터 검색 결과를 검증한다.
+- `targetType`, `supportedGames`, `dataEligibleTargets`, 미매칭 대상을 반환한다.
+- 게임명·prefix·물리 테이블을 Java나 포털 코드에서 하드코딩하지 않는다.
+
+### `oracle.select_ai.smilegate_fewshot_nl2sql`
+
+- AU 외 일반 분석 질의의 주 실행 도구다.
+- 현재 질문으로 QA 벡터 저장소에서 승인·검증된 유사 Few-shot 예제를 찾는다.
+- 선택된 Few-shot 예제의 질문·승인 SQL·논리 객체 역할을 현재 질문 및 `queryPlan`과 함께 Select AI 프롬프트에 추가한다.
+- ADB `DBMS_CLOUD_AI.GENERATE(..., 'showsql')`로 SQL을 생성한다.
+- 생성 SQL을 읽기 전용으로 검증한 후 실행한다.
+- Few-shot 근거, 생성 SQL, 실행 결과, 행 수를 반환한다.
+- 예제 승인·리타이어·유사도 기준은 DB가 관리한다. Java/Portal은 지표 조건이나
+  검색 결과를 보정하지 않는다.
+
+### `oracle.select_ai.game_daily_au_lookup`
+
+- 고정 정의 AU를 별도로 점검할 때 쓰는 전용 도구다. 고객 질의의 기본 실행 경로는
+  `executionTasks`가 지정한 worker이며, 일반적으로 `smilegate_fewshot_nl2sql`이다.
+- 입력은 `queryPlan`과 선택적인 `baseDate(YYYY-MM-DD)`다.
+- `queryPlan`의 게임 키를 `SG_GAME_CATALOG`에서 다시 검증하고 `USER_MASTER_OBJECT_NAME`을 동적으로 선택한다.
+- 선택된 사용자 마스터 객체에 대해 아래 정의로 AU를 집계한다.
+
+```sql
+SELECT COUNT(DISTINCT GUID) AS AU_COUNT
+FROM <catalog_user_master_object>
+WHERE BASE_DT = :baseDate
+  AND AU_FLAG = 1
+  AND EXPT_USER_YN = 'N'
+```
+
+- 게임명·별칭·prefix·물리 테이블명을 입력값이나 코드에서 직접 사용하지 않는다.
+- `SINGLE`, `MULTI`, `ALL` 계획의 각 대상에 대해 결과를 반환한다.
+
+## 3. 등록돼 있으나 기본 경로에서 직접 실행하지 않는 도구
+
+### `oracle.select_ai.qa_vector_search`
+
+- 유사 질문과 승인 SQL 예제를 직접 확인하는 관리자·점검용 도구다.
+- 일반 질의에서는 `smilegate_fewshot_nl2sql`이 내부적으로 Few-shot 검색을 수행하므로 별도 호출하지 않는다.
+
+### `oracle.select_ai.qa_vector_store`
+
+- 검토 완료한 질문·읽기 전용 SQL·검토 메모를 Few-shot 벡터 지식으로 저장하는 관리자 도구다.
+- 사용자 질의 실행 중에는 호출하지 않는다.
+
+### `oracle.select_ai.game_catalog_resolve`
+
+- 게임명 후보의 벡터 검색 결과를 독립적으로 점검하는 진단 도구다.
+- 정상 흐름에서는 `game_query_plan` 내부의 게임 식별 과정이 이 역할을 수행한다.
+
+### `oracle.select_ai.game_scope_resolve`
+
+- 과거 게임 범위와 별칭 매칭을 점검하기 위한 보조 도구다.
+- 현재 기본 판정 기준은 `game_query_plan`이므로 정상 경로에는 넣지 않는다.
+
+### `oracle.select_ai.smilegate_game_text2sql`
+
+- Few-shot을 붙이지 않은 기본 Select AI 결과를 비교·점검하는 보조 Text2SQL 도구다.
+- 고객용 기본 분석 경로는 `smilegate_fewshot_nl2sql`이다.
+
+### `oracle.select_ai.smilegate_game_showprompt`
+
+- SQL 생성에 전달된 최종 Select AI 프롬프트를 확인하는 진단 도구다.
+- 테이블 comment, 컬럼 annotation, 제약조건, 게임 범위 계획, Few-shot 근거가 프롬프트에 반영됐는지 점검한다.
+- SQL을 실행하지 않는다.
+
+### `oracle.select_ai.fewshot_preflight`
+
+- Few-shot 후보의 적합성을 별도로 확인할 때 사용하는 점검 도구다.
+- 현재 `smilegate.cloud-handson.com` 포털의 기본 질문 allowlist와 기본 실행 경로에는 직접 넣지 않는다.
+
+## 4. 실제 검증 결과
+
+| 항목 | 확인 결과 |
+|---|---|
+| 질문 | 카제나의 2026-07-15 AU |
+| 게임 범위 | `SINGLE / SUPPORTED` |
+| 게임 키 | `STOVE_CHAOSZERO` |
+| 카탈로그 선택 객체 | `CZN_COMN_USER_MST` |
+| AU 실행 상태 | `GAME_AU_LOOKUP / READY` |
+| 기준일 | `2026-07-15` |
+| 반환 AU | `0` |
+
+이 검증에서 테이블명은 코드에 고정하지 않았으며, 게임 계획 결과와 `SG_GAME_CATALOG` 메타데이터를 통해 선택됐다.
+
+## 5. 운영 원칙
+
+1. 게임 범위 판단과 실행 작업 생성은 항상 `game_query_plan`이 담당한다.
+2. Portal은 DB task를 실행·합성하며, 질문·SQL·결과를 보정하지 않는다.
+3. 분석성 질의는 승인·검증된 Few-shot 기반 Select AI로 처리한다.
+4. `RETIRED` 예제는 검색하지 않으며, 승인/리타이어는 DB에 저장한다.
+5. 정답지 SQL을 런타임에 실행하지 않는다. Select AI가 새로 만든 읽기 전용 SQL만 실행한다.
+6. 문제 발생 시 SHOWPROMPT, 생성 SQL, 실행 결과, 판정 이력을 근거로 metadata·Few-shot을 보완한다.