> ## 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.
# AutoGenie — Genie Space 자동 생성 & 최적화
**AutoGenie**는 Genie Space를 **자동으로 생성하고 성능을 최적화**하는 Databricks App입니다. 요구사항 문서(PDF/Markdown)를 업로드하면 AI가 Genie Space 설정을 자동 생성하고, 벤치마크 기반으로 반복 개선합니다.
> **소스 코드**: [GitHub에서 전체 소스 보기](https://github.com/SimyungYang/dbx-gitbook/tree/main/docs-mintlify/assets/autogenie)
AutoGenie의 아키텍처, 워크플로우, 데모 화면을 포함한 소개 슬라이드
***
## 왜 AutoGenie인가?
Genie Space를 수동으로 구성하려면 다음 작업이 필요합니다:
| 수동 작업 | 소요 시간 |
| --------------------- | ----- |
| 비즈니스 요구사항에서 테이블/컬럼 매핑 | 수 시간 |
| 인스트럭션 작성 | 수 시간 |
| 벤치마크 질문 작성 + 정답 SQL | 수 일 |
| 테스트 → 개선 반복 | 수 주 |
AutoGenie는 이 전체 과정을 **AI로 자동화**합니다.
***
## 두 가지 워크플로우
### Lamp — 새 Genie Space 생성
요구사항 문서에서 Genie Space를 자동 생성합니다.
PDF/Markdown 요구사항 문서를 업로드하면, LLM이 메트릭과 비즈니스 로직을 자동 추출합니다.
AI가 테이블 선택, JOIN 관계, 인스트럭션, 컬럼 설명을 포함한 **완전한 Genie Space 설정**을 생성합니다.
생성된 설정의 테이블/컬럼 참조를 Unity Catalog와 대조 검증합니다. 불일치가 있으면 인터랙티브하게 수정합니다.
요구사항에서 벤치마크 SQL 쿼리를 추출하고 검증합니다.
검증된 설정으로 Genie Space를 워크스페이스에 배포합니다.
### Enhancer — 기존 Genie Space 최적화
벤치마크 기반으로 기존 Genie Space의 답변 정확도를 자동 개선합니다.
최적화할 Genie Space, SQL Warehouse를 선택하고 벤치마크 파일을 업로드합니다.
벤치마크 질문을 Genie에 실행하고, 정답 SQL과 비교하여 pass/fail 비율을 측정합니다.
AI가 실패한 질문을 분석하고, 인스트럭션 추가/예시 쿼리 등록/JOIN 수정 등 **구체적인 개선안**을 제안합니다.
승인된 개선안을 Genie Space에 적용합니다.
**Auto-Loop 모드**: Score → Plan → Apply 사이클을 **목표 점수에 도달할 때까지 자동 반복**합니다.
***
## 아키텍처
AutoGenie는 **Databricks App**으로 배포되며, FastAPI 백엔드 + Next.js 프론트엔드로 구성됩니다.
| 계층 | 기술 | 역할 |
| ------------ | --------------------------------------- | ----------------------- |
| **Frontend** | Next.js 14 + TypeScript + Tailwind CSS | Lamp/Enhancer 탭 UI |
| **Backend** | FastAPI + SQLite | API, 세션 관리, Job 실행 |
| **AI** | Databricks Foundation Models | 요구사항 파싱, 설정 생성, 실패 분석 |
| **Platform** | Unity Catalog, Genie API, SQL Warehouse | 테이블 검증, Space 배포, 쿼리 실행 |
### 인증
OBO(On-Behalf-Of) 인증을 사용합니다. 사용자의 Databricks 토큰으로 모든 API를 호출하므로, 사용자의 UC 권한이 자동 적용됩니다.
***
## 배포 방법
### 1. 사전 준비
| 항목 | 요구사항 |
| ---------------- | ----------------------------------- |
| Python | 3.11+ |
| Node.js | 18+ |
| Databricks CLI | 설치 및 인증 완료 |
| SQL Warehouse | Serverless 권장 |
| Foundation Model | `databricks-gpt-5-2` 또는 동등 모델 접근 가능 |
### 2. 빌드 & 배포
```bash theme={null}
# 1. 클론
git clone
cd AutoGenie
# 2. Python 의존성 설치
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# 3. 프론트엔드 빌드
cd frontend
npm install
npm run build
cd ..
# 4. Databricks Apps로 배포
databricks apps deploy . --name autogenie
```
### 3. app.yaml 설정
```yaml theme={null}
command:
- uvicorn
- backend.main:app
- --host
- '0.0.0.0'
- --port
- '8000'
env:
- name: WAREHOUSE_ID
valueFrom: validation-warehouse # SQL Warehouse 리소스 바인딩
- name: FRONTEND_EXPORT_DIR
value: "frontend/out"
```
### 4. DABs 배포 (권장)
```yaml theme={null}
# databricks.yml
bundle:
name: autogenie
sync:
exclude:
- ".venv"
- "frontend/node_modules"
- "frontend/.next"
- "storage"
- "__pycache__"
```
```bash theme={null}
# DABs로 배포
databricks bundle deploy --target prod
```
***
## 벤치마크 파일 형식
Enhancer에 업로드하는 벤치마크 CSV 형식:
```csv theme={null}
question,expected_sql
"이번 달 전체 매출 합계","SELECT SUM(amount) FROM gold.orders WHERE MONTH(order_date) = MONTH(CURRENT_DATE())"
"서울 지역 VIP 고객 수","SELECT COUNT(*) FROM gold.customers WHERE region = '서울' AND grade = 'VIP'"
"전분기 대비 매출 증가율","SELECT (curr.total - prev.total) / prev.total * 100 FROM ..."
```
| 필드 | 설명 |
| -------------- | --------------------------- |
| `question` | 자연어 질문 (사용자가 Genie에 물어볼 질문) |
| `expected_sql` | 정답 SQL (결과 비교 기준) |
> **팁**: [Genie 성능 튜닝 가이드](/blog/guides/genie-space/performance-tuning)의 벤치마크 설계 팁을 참고하세요.
***
## 핵심 API
### Lamp (생성)
```python theme={null}
# 요구사항 파싱
POST /api/lamp/parse
Body: multipart/form-data (PDF/Markdown 파일)
# Genie Space 설정 생성
POST /api/lamp/generate
Body: {"session_id": "...", "options": {...}}
# Unity Catalog 검증
POST /api/lamp/validate
Body: {"session_id": "...", "catalog": "gold"}
# 배포
POST /api/lamp/deploy
Body: {"session_id": "...", "space_name": "my-genie-space"}
```
### Enhancer (최적화)
```python theme={null}
# 벤치마크 점수 측정
POST /api/enhancer/jobs/score
Body: {"session_id": "...", "space_id": "...", "warehouse_id": "..."}
# AI 개선안 생성
POST /api/enhancer/jobs/plan
Body: {"session_id": "...", "iteration_id": "..."}
# 개선안 적용
POST /api/enhancer/jobs/apply
Body: {"session_id": "...", "iteration_id": "...", "approved_fixes": [...]}
# Auto-Loop (자동 반복)
POST /api/enhancer/sessions/{id}/auto-loop
Body: {"target_score": 0.85, "max_iterations": 10}
```
***
## 실전 활용 팁
### 1. 요구사항 문서 작성 팁
Lamp의 파싱 정확도를 높이려면 요구사항 문서를 구조화하세요:
```markdown theme={null}
## 분석 목표
- 고객 세그먼트별 매출 분석
- 신규 고객 유입 트렌드
## 사용할 테이블
- gold.customers (고객 마스터)
- gold.orders (주문 내역)
## 비즈니스 용어
- "우량 고객": 등급이 VIP 또는 우수인 당월 활성 고객
- "이탈 고객": 최근 90일간 거래가 없는 고객
## 예상 질문
1. 이번 달 VIP 고객 수는?
2. 지역별 매출 Top 5는?
```
### 2. Auto-Loop 활용
벤치마크 점수가 **85% 이상**이 될 때까지 자동 반복하도록 설정하면, 사람이 개입하지 않아도 Genie Space가 점진적으로 개선됩니다.
```
Auto-Loop 설정 예시:
- Target Score: 85%
- Max Iterations: 10
- 보통 3-5회 반복으로 70% → 85%+ 달성 가능
```
### 3. Enhancer + 수동 튜닝 조합
Auto-Loop으로 기본 최적화를 한 후, 남은 실패 케이스는 [수동 Genie 튜닝 가이드](/blog/guides/genie-space/performance-tuning)를 참고하여 직접 개선하세요.
***
## 관련 문서
* [Genie Space 생성](/blog/guides/genie-space/create-space) — Space 기본 설정
* [Genie 성능 튜닝](/blog/guides/genie-space/performance-tuning) — 수동 튜닝 5단계
* [Consumer Access](/blog/guides/genie-space/consumer-access) — 비즈니스 사용자 읽기 전용 설정
* [Databricks Apps 배포](/blog/guides/apps/deployment) — Apps 배포 워크플로우
* [Genie Space Best Practices](https://docs.databricks.com/aws/en/genie/best-practices) — 공식 문서