> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sifi.life/llms.txt
> Use this file to discover all available pages before exploring further.

# 테스트 & 벤치마크

> 이 문서는 **[Genie Space](/blog/guides/genie-space/overview)** 섹션의 일부입니다.

***

## 개요

Genie Space의 품질은 **체계적인 테스트와 반복 개선** 으로 결정됩니다. 벤치마크 기능을 활용하면 Space가 다양한 질문에 얼마나 정확하게 응답하는지 정량적으로 측정하고, 개선 포인트를 식별할 수 있습니다.

### 왜 벤치마크가 필수인가

Genie Space는 LLM 기반 시스템이기 때문에 **비결정적(non-deterministic)** 입니다. 같은 인스트럭션을 수정해도 예상치 못한 부작용이 생길 수 있습니다. 예를 들어, "매출"의 정의를 인스트럭션에 추가했더니 기존에 잘 되던 "고객 수" 관련 질문이 틀리게 되는 경우가 있습니다.

벤치마크는 소프트웨어 개발의 **회귀 테스트(Regression Test)** 와 동일한 역할을 합니다:

| 소프트웨어 개발       | Genie Space                 |
| -------------- | --------------------------- |
| 코드 변경          | 인스트럭션/테이블/SQL Expression 변경 |
| 단위 테스트         | 벤치마크 질문-응답 쌍                |
| 회귀 테스트 실행      | 벤치마크 Run All                |
| 테스트 실패 → 버그 수정 | Incorrect → 원인 분석 → 수정      |
| CI/CD 파이프라인    | 변경 후 자동 벤치마크 실행             |

> **주의**
> **벤치마크 없이 운영하면 생기는 문제**: 인스트럭션을 변경할 때마다 수십 개의 질문을 수동으로 테스트해야 합니다. 실수로 기존에 잘 되던 질문이 깨져도 발견하지 못합니다. 벤치마크는 이 문제를 자동화합니다.

***

## 샘플 질문

샘플 질문은 사용자가 채팅 창을 열었을 때 표시되는 예시 질문입니다. 테스트의 첫 단계이기도 합니다.

**설정 방법:**

1. **Configure > Settings** 에서 **Sample Questions** 섹션으로 이동합니다.
2. Space가 다루는 주제를 대표하는 질문을 추가합니다.
3. 각 질문을 직접 실행하여 결과가 정확한지 검증합니다.

### 좋은 샘플 질문 vs 나쁜 샘플 질문

| 좋은 예시                | 나쁜 예시        | 이유                    |
| -------------------- | ------------ | --------------------- |
| "지난 달 매출 상위 5개 지역은?" | "매출"         | 구체적인 기간, 집계, 정렬 조건 포함 |
| "올해 신규 고객 수 추이를 보여줘" | "고객 데이터 보여줘" | 분석 유형(추이)이 명확         |
| "제품 카테고리별 반품률을 비교해줘" | "반품"         | 비교 기준이 명시됨            |
| "이번 분기 목표 대비 달성률은?"  | "목표"         | 비즈니스 맥락이 포함           |

> **팁**
> 샘플 질문은 **Genie가 Space의 의도를 이해하는 컨텍스트** 로도 활용됩니다. 잘 작성된 샘플 질문은 유사한 패턴의 다른 질문에도 긍정적인 영향을 줍니다. 샘플 질문을 등록한 후 반드시 직접 실행해보고, 결과가 정확한지 검증하세요.

> **주의**
> **샘플 질문의 응답이 틀리면 안 됩니다.** 사용자가 가장 먼저 시도하는 것이 샘플 질문입니다. 첫 번째 질문의 답이 틀리면 Space에 대한 신뢰가 바로 무너집니다. 샘플 질문은 반드시 정확한 응답이 보장된 질문만 등록하세요.

***

## 벤치마크 개요

벤치마크는 검증된 질문-응답 쌍의 집합입니다. Space를 변경한 후 벤치마크를 실행하면 변경이 기존 응답의 정확도에 미치는 영향을 즉시 확인할 수 있습니다.

### 벤치마크 질문 설계 원칙

좋은 벤치마크는 단순히 "질문을 많이 만드는 것"이 아니라, Space의 **다양한 능력을 고르게 평가** 하는 것입니다:

1. **커버리지**: 모든 테이블과 주요 컬럼이 최소 1개 벤치마크에 포함되어야 함
2. **난이도 분포**: 단순 질문(50%), 중간 질문(30%), 복잡한 질문(20%) 비율 유지
3. **비즈니스 용어 포함**: "활성 고객", "순매출" 같은 도메인 용어 사용 질문 반드시 포함
4. **엣지 케이스**: "데이터가 없는 기간", "NULL 값이 있는 컬럼" 관련 질문
5. **다국어**: 한국어/영어로 같은 질문을 각각 만들어 매핑 정확도 확인

### 벤치마크의 구성 요소

| 구성 요소                      | 설명                            |
| -------------------------- | ----------------------------- |
| **질문(Question)**           | 사용자가 입력하는 자연어 질문              |
| **기대 SQL(Expected SQL)**   | 이 질문에 대한 정답 SQL 쿼리            |
| **기대 결과(Expected Result)** | 정답 SQL의 실행 결과 (자동 생성)         |
| **채점 결과(Grade)**           | Correct / Incorrect / Partial |

***

## 벤치마크 생성 방법

> **팁**
> **가장 효과적인 벤치마크 생성 순서**: (1) 먼저 채팅에서 다양한 질문을 테스트 → (2) 정확한 응답을 바로 벤치마크로 추가 → (3) 부정확한 응답은 올바른 SQL을 직접 작성하여 벤치마크 탭에서 추가. 이 순서로 하면 가장 빠르게 충분한 벤치마크를 만들 수 있습니다.

### 방법 1: 채팅에서 직접 추가

1. 채팅에서 질문을 입력하고 응답을 확인합니다.
2. 응답이 **정확한 경우**, 응답 우측의 케밥 메뉴(...)를 클릭합니다.
3. **Add as benchmark** 를 선택합니다.
   * *화면 설명: 질문 텍스트와 생성된 SQL이 벤치마크 항목으로 저장됩니다.*
4. 필요하면 기대 SQL을 수정합니다.

### 방법 2: 벤치마크 탭에서 직접 추가

1. **Configure > Benchmarks** 탭으로 이동합니다.
2. **Add benchmark** 버튼을 클릭합니다.
3. 질문 텍스트를 입력합니다.
4. 기대 SQL을 작성합니다.
5. **Save** 를 클릭합니다.

### 방법 3: 모니터링에서 추가

1. **Monitoring** 탭에서 사용자 질문을 검토합니다.
2. 정확한 응답의 케밥 메뉴에서 **Add as benchmark** 를 선택합니다.
3. 이 방법은 실제 사용자 질문 패턴을 벤치마크에 반영할 수 있어 가장 실용적입니다.

> **참고**
> 벤치마크는 최소 **10-20개의 핵심 질문** 으로 시작하는 것을 권장합니다. 다양한 질문 유형(집계, 필터, 조인, 시계열, 랭킹)을 포함해야 Space의 전반적인 품질을 평가할 수 있습니다.

***

## 채점 기준

벤치마크를 실행하면 각 질문에 대해 다음 3가지 등급으로 채점됩니다:

| 등급            | 의미    | 판단 기준                      |
| ------------- | ----- | -------------------------- |
| **Correct**   | 정확함   | 생성된 SQL의 결과가 기대 결과와 일치     |
| **Incorrect** | 부정확함  | 결과가 완전히 다르거나 오류 발생         |
| **Partial**   | 부분 정확 | 일부 값은 맞지만 정렬, 필터, 집계 등이 다름 |

> **주의**
> 채점은 **결과 데이터 기반** 으로 이루어집니다. SQL 구문이 다르더라도 결과가 같으면 Correct로 판정됩니다. 반대로, SQL이 비슷해 보여도 결과가 다르면 Incorrect입니다.

***

## 테스트 권장 프로세스

### Phase 1: 초기 벤치마크 구성 (10-20개)

> **참고**
> **왜 10-20개인가**: 10개 미만이면 Space의 품질을 충분히 평가할 수 없고, 초기에 20개 이상을 만들려면 시간이 너무 많이 걸립니다. 10-20개로 시작하고, 운영하면서 실제 사용자 질문을 기반으로 30-50개까지 확장하는 것이 현실적입니다.

다양한 질문 유형을 포함한 핵심 벤치마크를 만듭니다:

| 질문 유형       | 예시                             | 권장 개수 |
| ----------- | ------------------------------ | ----- |
| **단순 집계**   | "총 매출은 얼마인가?"                  | 2-3개  |
| **필터링**     | "서울 지역 매출은?"                   | 2-3개  |
| **조인**      | "고객별 주문 금액 합계는?"               | 2-3개  |
| **시계열**     | "월별 매출 추이를 보여줘"                | 2-3개  |
| **랭킹**      | "매출 상위 10개 제품은?"               | 2-3개  |
| **비교**      | "전년 대비 매출 증감률은?"               | 2-3개  |
| **비즈니스 용어** | "활성 고객 수는?" (활성 = 최근 90일 내 구매) | 2-3개  |

### Phase 2: 벤치마크 실행 및 분석

1. **Configure > Benchmarks** 탭에서 **Run all** 버튼을 클릭합니다.
   * *화면 설명: 각 질문의 채점 결과가 Correct/Incorrect/Partial로 표시되며, 전체 정확도 비율이 상단에 나타납니다.*
2. 전체 정확도(Correct 비율)를 확인합니다.
3. **Incorrect** 와 **Partial** 항목을 클릭하여 생성된 SQL과 기대 SQL을 비교합니다.

### Phase 3: 오답 분석 및 개선

Incorrect 항목의 원인을 분석하고, 적절한 위치에서 수정합니다.

***

## 오답 원인별 수정 위치 가이드

| 오답 원인            | 증상                         | 수정 위치                              | 수정 방법                 |
| ---------------- | -------------------------- | ---------------------------------- | --------------------- |
| **잘못된 테이블 선택**   | 엉뚱한 테이블에서 쿼리               | Configure > Data                   | 불필요한 테이블 제거 또는 설명 보강  |
| **컬럼 의미 혼동**     | 비슷한 이름의 컬럼을 잘못 사용          | Configure > Data > 컬럼 설명           | 컬럼별 명확한 설명과 동의어 추가    |
| **비즈니스 용어 미인식**  | "활성 고객"의 정의를 모름            | Configure > Instructions           | 텍스트 인스트럭션으로 용어 정의     |
| **집계 로직 오류**     | SUM 대신 COUNT, 잘못된 GROUP BY | Configure > Data > SQL Expressions | Measure로 정확한 집계 공식 정의 |
| **필터 조건 누락**     | 삭제된 데이터 포함, 기간 필터 누락       | Configure > Data > SQL Expressions | Filter로 기본 조건 정의      |
| **조인 오류**        | 잘못된 키로 조인                  | Configure > Data > Join Relations  | 명시적 조인 관계 정의          |
| **한국어-영어 매핑 실패** | "서울"을 "Seoul"로 매칭 못함       | Configure > Data > Prompt Matching | 프롬프트 매칭 활성화           |

***

## 반복 개선 사이클

효과적인 Space 품질 관리는 아래 사이클을 반복하는 것입니다:

```
1. 벤치마크 실행 (Run all)
   ↓
2. 정확도 확인 (목표: 80% 이상)
   ↓
3. Incorrect 항목의 원인 분석
   ↓
4. 원인에 맞는 위치에서 수정
   (인스트럭션, 컬럼 설명, SQL Expression, 조인 등)
   ↓
5. 벤치마크 재실행 → 개선 확인
   ↓
6. 새로운 질문 유형 벤치마크 추가
   ↓
7. 1번으로 돌아가기
```

### 점수 해석과 개선 전략

벤치마크 정확도에 따라 취해야 할 전략이 다릅니다:

| 정확도 범위     | 상태 | 우선 조치                                                   |
| ---------- | -- | ------------------------------------------------------- |
| **90% 이상** | 우수 | 엣지 케이스와 새로운 질문 유형 추가. 현 상태 유지에 집중                       |
| **80-89%** | 양호 | 사용자 공유 가능. Incorrect 항목 개별 분석 후 인스트럭션/SQL Expression 보강 |
| **60-79%** | 미흡 | 공유하기 이른 단계. 컬럼 설명 부족이나 동의어 누락이 주 원인인 경우가 많음             |
| **60% 미만** | 심각 | 근본적 구조 문제. 테이블 선택이 잘못되었거나, 핵심 메타데이터가 거의 없는 상태           |

> **참고**
> **정확도가 60% 미만이면 인스트럭션 튜닝보다 데이터 구성을 먼저 점검하세요.** 테이블이 너무 많거나, 컬럼 설명이 없거나, 핵심 비즈니스 지표의 SQL Expression이 없는 것이 원인인 경우가 대부분입니다.

### 변경 시 벤치마크 활용 워크플로

Space를 수정할 때 다음 워크플로를 따르면 품질 저하를 방지할 수 있습니다:

1. **변경 전**: 벤치마크 전체 실행 → 현재 점수 기록 (예: 85%)
2. **변경 적용**: 인스트럭션/SQL Expression/컬럼 설명 등 수정
3. **변경 후**: 벤치마크 전체 재실행 → 점수 비교
4. **점수 하락 시**: 새로 Incorrect가 된 항목을 확인하고, 변경을 원복하거나 추가 수정
5. **점수 유지/상승 시**: 변경 확정

> **팁**
> 벤치마크 정확도가 **80% 이상** 이면 사용자에게 공유할 준비가 된 것입니다. 공유 후에도 모니터링 탭의 실제 사용자 질문을 벤치마크에 추가하며 지속적으로 개선하세요.

***

## 오답 분석 심화 — Partial 결과의 의미

Partial은 "완전히 틀린 것은 아니지만, 기대와 다른 결과"를 의미합니다. Partial이 많다면 다음을 점검하세요:

| Partial의 흔한 원인 | 예시                       | 해결 방법                   |
| -------------- | ------------------------ | ----------------------- |
| **정렬 차이**      | 결과 데이터는 맞지만 ORDER BY가 다름 | 예제 쿼리에서 정렬 기준 명시        |
| **집계 수준 차이**   | 일별 vs 월별 집계가 다름          | 인스트럭션에 기본 집계 단위 정의      |
| **필터 범위 차이**   | NULL 포함/제외가 다름           | 컬럼 설명에 NULL 처리 규칙 명시    |
| **컬럼 선택 차이**   | 원하는 컬럼이 빠지거나 추가됨         | 예제 쿼리에서 SELECT 컬럼 패턴 시연 |

> **팁**
> Partial은 "거의 맞지만 미세 조정이 필요한 상태"입니다. 대부분 인스트럭션이나 예제 쿼리 1-2개 추가로 해결됩니다. Incorrect보다 수정이 쉬우므로, Incorrect를 먼저 해결한 후 Partial을 개선하세요.

***

## 벤치마크 관리 베스트 프랙티스

| 항목              | 권장 사항                                     |
| --------------- | ----------------------------------------- |
| **벤치마크 수**      | 초기 10-20개, 운영 중 30-50개로 확장                |
| **질문 다양성**      | 한 유형에 편중되지 않도록 다양한 패턴 포함                  |
| **정기 실행**       | 인스트럭션이나 테이블 구성 변경 후 반드시 실행. 최소 주 1회       |
| **실제 질문 반영**    | 모니터링에서 자주 묻는 질문을 벤치마크로 등록                 |
| **오답 우선 대응**    | Incorrect부터 해결 후 Partial 개선               |
| **기대 SQL 업데이트** | 데이터 스키마 변경 시 기존 벤치마크의 기대 SQL도 업데이트        |
| **벤치마크 분류**     | 태그나 명명 규칙으로 질문 유형별 분류 (집계, 필터, 조인, 시계열 등) |