> ## 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)** 섹션의 일부입니다. *** ## 인스트럭션이 하는 역할 — System Prompt와 동일 Genie Space의 인스트럭션은 ChatGPT나 Claude에서 사용하는 **System Prompt와 본질적으로 동일** 합니다. LLM이 사용자 질문을 해석하고 SQL을 생성할 때, 인스트럭션은 "배경 지식"과 "행동 규칙"으로 작용합니다. 예를 들어, 인스트럭션에 "'매출'이라고 하면 부가세를 제외한 순매출(net\_revenue)을 의미한다"고 적으면, LLM은 "매출 보여줘"라는 질문에 `SUM(net_revenue)`를 사용합니다. 인스트럭션이 없으면 LLM은 `SUM(gross_revenue)`를 선택할 수도 있고, `SUM(amount)`를 선택할 수도 있습니다. > **주의** > **인스트럭션의 한계를 이해하세요**: 인스트럭션은 LLM이 "참고"하는 것이지, "프로그래밍"하는 것이 아닙니다. "반드시 A 테이블에서만 쿼리해라"라고 써도 LLM이 100% 따르지 않을 수 있습니다. 비즈니스 로직의 정확한 적용이 필요하면 SQL Expression을 사용하세요. *** ## 인스트럭션 우선순위 Genie에 비즈니스 로직을 전달할 때는 다음 우선순위를 따르세요: ``` 1순위: SQL 표현식 (가장 정확 — Genie가 SQL에 직접 삽입) ↓ 2순위: 예제 SQL 쿼리 (복잡한 시나리오 — 정답 패턴 학습) ↓ 3순위: 텍스트 인스트럭션 (최후의 수단 — LLM이 해석 필요) ``` 이 우선순위가 중요한 이유는 **정확도의 보장 수준** 이 다르기 때문입니다. SQL Expression은 그대로 SQL에 삽입되므로 100% 정확합니다. 예제 쿼리는 유사한 질문에 대해 높은 정확도를 보입니다. 텍스트 인스트럭션은 LLM이 해석해야 하므로 가장 불확실합니다. *** ## 예제 SQL 쿼리 추가 예제 SQL 쿼리는 Genie에게 "이런 질문에는 이런 SQL이 정답이다"라는 **Few-shot 학습** 을 제공합니다. 텍스트 인스트럭션이 "규칙"이라면, 예제 쿼리는 "예시 답안"입니다. LLM은 일반적으로 규칙보다 구체적인 예시에서 더 잘 학습합니다. **Configure > SQL Queries** 탭에서 추가합니다. **작성 규칙:** * 제목은 사용자가 실제로 물어볼 법한 **가장 일반적인 표현** 으로 작성. 이 제목이 Genie가 "이 질문과 유사한가?"를 판단하는 기준이 됩니다 * 파라미터화된 쿼리는 **Trusted** 마크가 부여됨. Trusted 마크는 사용자에게 "이 응답은 검증된 패턴입니다"라는 신뢰를 줍니다 * 복잡한 로직은 Unity Catalog에 **커스텀 함수** 로 등록 가능 * SQL은 실제로 실행 가능하고 올바른 결과를 반환하는지 **반드시 사전 검증** **예시:** ```sql theme={null} -- 제목: "이번 분기 매출 상위 10개 제품은?" SELECT product_name, SUM(amount) as total_sales FROM sales.transactions WHERE quarter = QUARTER(CURRENT_DATE()) AND year = YEAR(CURRENT_DATE()) GROUP BY product_name ORDER BY total_sales DESC LIMIT 10 ``` *** ### 예제 SQL 쿼리 작성 전략 예제 SQL 쿼리는 Genie에게 "이런 유형의 질문에는 이런 SQL을 생성해라"라는 패턴을 학습시킵니다. 효과적인 예제 쿼리를 만들려면 다음 전략을 따르세요: | 전략 | 설명 | 예시 | | --------------- | -------------------- | -------------------------- | | **자주 묻는 질문 우선** | 실제로 가장 많이 물어볼 질문부터 | "이번 달 총 매출은?" | | **복잡한 조인 포함** | Genie가 혼동하기 쉬운 조인 패턴 | 3개 테이블 조인이 필요한 질문 | | **비즈니스 용어 사용** | 사용자가 실제로 사용하는 표현 | "활성 고객별 객단가" (활성=90일 내 구매) | | **파라미터화** | 질문에 변수가 포함된 패턴 | "\{\{지역}}의 \{\{기간}} 매출" | > **참고** > 파라미터화된 예제 쿼리(`{{변수}}` 포함)는 **Trusted** 마크가 부여됩니다. Trusted 응답은 사용자에게 "이 답변은 검증된 쿼리를 기반으로 합니다"라는 신뢰를 줍니다. *** ## SQL 함수 등록 복잡한 비즈니스 로직은 Unity Catalog에 커스텀 함수로 등록하고, Genie Space에서 참조합니다. 함수를 사용한 응답은 **Trusted** 로 표시됩니다. ### 왜 SQL 함수인가? 예제 쿼리와 SQL Expression이 "특정 질문에 대한 답"이라면, SQL 함수는 **재사용 가능한 비즈니스 로직 모듈** 입니다. 여러 Space에서 동일한 계산 로직이 필요할 때, 함수로 한 번 정의하면 일관성이 보장됩니다. ```sql theme={null} -- 예: "활성 고객" 판별 함수 CREATE FUNCTION catalog.schema.is_active_customer(last_purchase_date DATE) RETURNS BOOLEAN RETURN last_purchase_date >= DATE_ADD(CURRENT_DATE(), -90) ``` Genie는 이 함수를 인식하고, "활성 고객"이라는 질문이 들어오면 `WHERE catalog.schema.is_active_customer(last_purchase_date)` 형태로 SQL을 생성합니다. *** ## 텍스트 인스트럭션 작성 **Configure > Text Instructions** 탭에서 추가합니다. ### 좋은 인스트럭션 vs 나쁜 인스트럭션 — 5가지 비교 | # | 나쁜 인스트럭션 | 좋은 인스트럭션 | 왜 다른가 | | - | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | 1 | "매출에 대해 질문하면 명확히 해달라고 물어봐" | "사용자가 '매출'을 질문할 때 기간을 명시하지 않으면, 기본적으로 당월(CURRENT\_MONTH) 데이터를 사용하고, 응답에 '기간: 이번 달'이라고 명시해라" | 나쁜 예시는 행동이 모호함. 좋은 예시는 **기본값과 구체적 행동** 을 정의 | | 2 | "데이터를 정확히 보여줘" | "'매출'은 항상 orders 테이블의 net\_revenue 컬럼을 사용하고, gross\_revenue는 사용하지 마라" | 나쁜 예시는 너무 추상적. 좋은 예시는 **구체적인 컬럼을 지정** | | 3 | "한국어로 답해줘" | "모든 응답의 요약(summary)은 한국어로 작성하되, SQL 쿼리의 alias는 영문을 유지해라. 숫자는 천 단위 콤마를 포함하고, 금액 뒤에 '원'을 붙여라" | 나쁜 예시는 범위가 불명확. 좋은 예시는 **언어, 형식, 단위** 를 모두 지정 | | 4 | "고객 등급을 잘 처리해" | "'VIP 고객'은 tier = 'Gold'인 고객을 의미한다. '일반 고객'은 tier IN ('Silver', 'Bronze')이다. '전체 고객'이라고 하면 모든 tier를 포함한다" | 나쁜 예시는 "잘"의 기준이 없음. 좋은 예시는 **비즈니스 용어를 데이터 값에 매핑** | | 5 | "날짜 관련 질문에 주의해" | "'지난 분기'는 DATEADD(QUARTER, -1, CURRENT\_DATE()) 기준이다. '올해'는 YEAR(CURRENT\_DATE()) 기준이다. 날짜를 명시하지 않으면 최근 30일을 기본으로 사용해라" | 나쁜 예시는 지시가 없음. 좋은 예시는 **시간 기준을 SQL 함수로 명확히 정의** | > **참고** > **인스트럭션 작성의 황금률**: "만약 이 인스트럭션을 신입 SQL 개발자에게 주면, 모호함 없이 SQL을 작성할 수 있는가?"를 자문하세요. 그렇다면 좋은 인스트럭션입니다. *** ## 업종별 인스트럭션 템플릿 ### 금융/은행 ``` - '연체'는 due_date < CURRENT_DATE() AND status = 'unpaid'인 건을 의미한다 - '부실채권'은 overdue_days >= 90인 건이다 - 금액은 천 단위 콤마를 포함하고, '원' 또는 '백만원' 단위로 표시해라 - 고객 개인정보(이름, 연락처, 계좌번호)는 절대 결과에 포함하지 마라 - '수익률'은 (수익/투자원금)*100으로 계산하고 소수점 2자리까지 표시해라 ``` ### 제조 ``` - '불량률'은 (불량수량/전체생산수량)*100으로 계산한다 - '가동률'은 (실가동시간/계획가동시간)*100이다 - '리드타임'은 주문일(order_date)부터 출하일(ship_date)까지의 일수다 - 설비코드는 'EQ-'로 시작하는 형식이다. 사용자가 설비명으로 질문하면 equipment_name 컬럼으로 매칭해라 - 날짜를 명시하지 않으면 최근 1개월 데이터를 기본으로 사용해라 ``` ### 유통/이커머스 ``` - '매출'은 환불/취소 건을 제외한 순매출(net_revenue)을 의미한다 - '객단가'는 순매출/유효주문건수로 계산한다 - '재구매율'은 (2회 이상 구매 고객수/전체 구매 고객수)*100이다 - '신규 고객'은 첫 구매일이 조회 기간 내인 고객이다 - 상품 카테고리는 대분류 > 중분류 > 소분류 3단계로 구성된다. 카테고리를 명시하지 않으면 대분류 기준으로 집계해라 ``` *** ### 업종별 인스트럭션 작성 시 핵심 포인트 업종에 관계없이 인스트럭션에 반드시 포함해야 할 세 가지: 1. **핵심 KPI 정의**: "매출", "이익", "고객수" 같은 가장 많이 질문될 지표의 정확한 계산식 2. **날짜/기간 기본값**: "기간을 명시하지 않으면 최근 30일/당월/당분기"와 같은 기본 규칙 3. **데이터 필터 기본값**: "삭제 건 제외", "취소 건 제외" 같은 암묵적 필터 규칙 > **주의** > **과도한 인스트럭션 주의**: 업종 템플릿을 그대로 복사하지 마세요. 해당 Space에 실제로 존재하는 테이블/컬럼에 맞게 수정하고, 실제로 사용자가 물어볼 질문에 관련된 인스트럭션만 추가하세요. *** ## 한국어 인스트럭션 작성 팁 한국어 환경에서 Genie Space를 운영할 때 주의할 점이 있습니다: | 이슈 | 해결 방법 | | -------------------- | ----------------------------------------- | | **컬럼명이 영어, 질문은 한국어** | 동의어에 한국어 표현 등록 + 인스트럭션에 용어 매핑 | | **데이터 값이 영어** | 프롬프트 매칭으로 한국어 → 영어 자동 변환 | | **한국어 날짜 표현** | "지난 달", "이번 분기" 같은 표현을 인스트럭션에서 SQL 함수로 정의 | | **수치 단위** | "억", "만" 단위 사용 시 인스트럭션에 변환 규칙 명시 | | **요약 언어** | "응답 요약은 한국어로, SQL alias는 영문 유지"로 명시 | > **팁** > **실전 팁**: 인스트럭션을 한국어와 영어를 혼합하여 작성해도 됩니다. 비즈니스 규칙은 한국어로, SQL 관련 지시는 영어로 작성하면 LLM이 더 정확하게 이해하는 경우가 많습니다. *** ## 명확화 질문(Clarification) 인스트럭션 명확화 질문은 사용자의 애매한 질문에 대해 Genie가 바로 잘못된 SQL을 생성하는 대신, **필요한 정보를 먼저 물어보도록** 하는 메커니즘입니다. "매출 보여줘"라는 모호한 질문에 대해 무작정 전체 매출을 보여주는 것보다, "어떤 기간의 매출을 원하시나요?"라고 물어보는 것이 사용자 경험과 정확도 모두에서 유리합니다. 4가지 구성 요소로 작성합니다: 1. **트리거 조건**: "사용자가 팀 성과 분석을 요청하면..." 2. **누락 정보**: "...기간, 팀명, KPI를 명시하지 않았을 때..." 3. **필요 행동**: "...반드시 확인 질문을 먼저 해라..." 4. **예시**: "분석할 기간과 팀명, 확인하고 싶은 KPI를 알려주세요." ### 명확화 질문의 좋은 예시 ``` 트리거: 사용자가 "팀 성과 분석"을 요청할 때 누락 조건: 기간, 팀명, KPI를 명시하지 않았을 때 행동: 확인 질문을 먼저 해라 응답 예시: "분석할 기간(예: 이번 분기), 팀명(예: 영업1팀), 확인하고 싶은 KPI(매출, 고객수, 달성률 등)를 알려주세요." ``` > **주의** > 명확화 인스트럭션은 일반 가이드 뒤에 배치하세요. 전체 General Instructions 텍스트 블록은 100개 인스트럭션 제한 중 **1개** 로 계산됩니다. *** ## 요약(Summary) 커스터마이징 "인스트럭션 중 요약 생성 시 반드시 따를 규칙" 섹션을 별도로 추가할 수 있습니다: * 응답 언어 지정 (예: "항상 한국어로 요약해라") * 포맷 요구사항 (불릿 포인트, 인용 포함 등) * 데이터 범위 명시 > **참고** > 텍스트 인스트럭션만 요약에 영향을 미칩니다. SQL 예제와 SQL 표현식은 요약 생성에 반영되지 않습니다. *** ## 인스트럭션 관리 베스트 프랙티스 | 항목 | 권장 사항 | | ----------------- | ---------------------------------------------------------------------------------- | | **총 인스트럭션 수** | General Instructions 텍스트 블록 + SQL 쿼리 + SQL Expression 합쳐서 200개 제한. 핵심에 집중 | | **인스트럭션 간 모순 방지** | "매출은 gross\_revenue를 사용해라"와 "매출 = net\_revenue"가 동시에 있으면 Genie가 혼란. 정기적으로 중복/모순 검토 | | **버전 관리** | 인스트럭션 변경 시 벤치마크를 실행하여 기존 정확도에 영향이 없는지 확인. 변경 이력을 별도로 기록 | | **점진적 추가** | 한 번에 20개 인스트럭션을 추가하지 말고, 2-3개씩 추가하면서 벤치마크로 효과 검증 | | **구체성 원칙** | "잘 해라", "정확하게 해라" 같은 추상적 지시는 효과 없음. 항상 구체적 행동과 예시 포함 | > **주의** > **흔한 실수**: 인스트럭션을 너무 많이 넣으면 오히려 정확도가 떨어질 수 있습니다. LLM의 컨텍스트 윈도우에는 한계가 있으며, 인스트럭션이 많으면 서로 충돌하거나 중요한 지시가 묻힐 수 있습니다. **"적지만 정확한 인스트럭션"** 이 "많지만 모호한 인스트럭션"보다 낫습니다. ### 인스트럭션 효과 검증 방법 인스트럭션을 추가/수정한 후 효과를 검증하는 3단계 프로세스: 1. **즉시 테스트**: 해당 인스트럭션과 관련된 질문 2-3개를 직접 채팅에서 테스트 2. **벤치마크 실행**: Run All로 전체 벤치마크를 실행하여 부작용이 없는지 확인 3. **A/B 비교**: 인스트럭션 추가 전/후의 벤치마크 점수를 비교하여 정량적 효과 확인 > **팁** > 인스트럭션 변경을 하나의 "실험"으로 간주하세요. **"가설 → 변경 → 측정 → 결론"** 사이클을 반복하면 Space의 품질이 체계적으로 향상됩니다.