Knowledge Assistant 베스트 프랙티스
문서 준비
| 항목 | 권장사항 |
|---|---|
| 문서 크기 | 50MB 이하로 분할, 큰 문서는 섹션별로 나누기 |
| 문서 형식 | 구조화된 마크다운(md) 또는 잘 포맷된 PDF 권장 |
| 이미지/표 | PDF 내 이미지나 복잡한 표는 텍스트로 보충 설명 추가 |
| 파일명 | 내용을 유추할 수 있는 명확한 파일명 사용 (예: 2024-Q3-매출보고서.pdf) |
청크 사이즈와 검색 품질
Vector Search Index가 문서를 청크 단위로 분할합니다. 기본 설정으로 시작하되, 다음을 참고하세요.- 짧은 FAQ 문서: 작은 청크 사이즈가 유리 (개별 질문-답변 쌍이 잘 분리됨)
- 긴 기술 문서: 큰 청크 사이즈가 유리 (문맥이 유지됨)
- 오버랩(overlap): 청크 간 겹침을 두면 문맥 손실을 줄일 수 있음
인스트럭션 작성
| 항목 | 권장사항 |
|---|---|
| Content Description | 문서의 도메인, 용도, 대상 사용자를 구체적으로 명시 |
| Instructions | 응답 언어, 톤, 인용 규칙 등을 명확히 지정 |
| Knowledge Source 수 | 관련성 높은 소스만 선별 (최대 10개이지만 적을수록 정확) |
| 동기화 | 문서 업데이트 후 반드시 Sync 실행 |
참고 인스트럭션 예시: “반드시 한국어로 응답하세요. 답변에는 출처 문서명과 페이지를 인용하세요. 문서에 없는 내용은 ‘해당 정보를 찾을 수 없습니다’라고 답하세요.”
Genie Spaces 베스트 프랙티스
테이블 설계
| 항목 | 권장사항 |
|---|---|
| 테이블/컬럼 설명 | 비즈니스 용어와 동의어를 풍부하게 등록 |
| JOIN 관계 | 자주 사용되는 조인을 미리 정의 |
| 테이블 수 | 30개 이하, 핵심 테이블만 포함 |
| 컬럼 타입 | DATE, TIMESTAMP 등 정확한 타입 사용 (문자열 날짜 지양) |
| 네이밍 | order_amount_krw처럼 단위를 컬럼명에 포함 |
SQL 표현식 활용
재사용 가능한 SQL 표현식을 Knowledge Store에 등록하면 정확도가 크게 향상됩니다.| 항목 | 권장사항 |
|---|---|
| Sample Questions | 실제 비즈니스 질문 패턴을 등록 (최대 100개) |
| Instructions | 응답 형식, 단위(원/달러), 날짜 형식 등 명시 |
| 모니터링 | 정기적으로 Monitoring 탭 확인 후 Knowledge Store 업데이트 |
Supervisor Agent 베스트 프랙티스
서브 에이전트 설계
| 항목 | 권장사항 |
|---|---|
| 서브 에이전트 수 | 3~5개 이내 권장 (많을수록 라우팅 복잡도 증가) |
| Description | 담당 업무를 최대한 상세하게 작성 (라우팅 정확도에 직결) |
| 권한 설계 | 엔드 유저의 서브 에이전트별 접근 권한을 사전에 설계 |
| 테스트 | 다양한 시나리오로 라우팅 정확도를 검증 |
| Long-Running Mode | 복잡한 태스크는 Long-Running Task Mode 활용 |
라우팅 로직 최적화
Supervisor는 서브 에이전트의 Description 을 기반으로 라우팅합니다. 다음을 지켜주세요.- 겹치지 않는 역할 정의: 서브 에이전트 간 책임이 겹치면 라우팅이 혼란스러워집니다
- 명확한 키워드 포함: Description에 해당 에이전트가 처리할 질문 유형의 키워드를 포함
- 폴백 에이전트 설정: 어떤 에이전트에도 해당하지 않는 질문을 처리할 일반 에이전트 배치
주의 서브 에이전트가 7개 이상 이면 라우팅 정확도가 눈에 띄게 떨어집니다. 역할이 비슷한 에이전트는 하나로 통합하세요.
공통 권장사항
평가 루프
- 반복적 개선: 배포 후에도 Examples 탭에서 지속적으로 피드백을 수집하고 가이드라인을 업데이트
- 체계적 평가: AI Judge + Synthetic Task Generation으로 정기적 품질 측정
- SME 리뷰: 도메인 전문가(Subject Matter Expert)에게 공유 링크를 전달하여 정기 리뷰 수행
모니터링
- 트레이싱 활성화: Production Monitoring for MLflow를 활성화하여 실행 과정 추적
- 응답 지연 모니터링: 엔드포인트 응답 시간이 10초를 초과하면 최적화 필요
- 오류율 추적: 실패한 쿼리 비율이 5% 이상이면 즉시 원인 분석
비용 관리
| 전략 | 설명 |
|---|---|
| Serverless Budget Policy | 예산 한도를 설정하여 비용 초과 방지 |
| 사용량 모니터링 | Billing 대시보드에서 에이전트별 DBU 소비량 추적 |
| 불필요한 엔드포인트 정리 | 테스트용 엔드포인트는 사용 후 삭제 |
| 모델 선택 | 간단한 태스크에 대형 모델을 사용하지 않기 |
권한 및 보안
- 권한 최소화: 필요한 사용자에게만 최소한의 권한 부여
- Unity Catalog 활용: 데이터 접근 권한을 UC로 일원화
- 리전 확인: 현재
us-east-1또는us-west-2에서만 사용 가능
Anti-patterns: 흔한 실수 5가지
위험 다음은 Agent Bricks를 사용할 때 자주 발생하는 실수입니다. 반드시 피하세요.
| # | Anti-pattern | 문제점 | 해결 방법 |
|---|---|---|---|
| 1 | 모든 문서를 하나의 KA에 몰아넣기 | 검색 정확도 하락, 무관한 문서가 인용됨 | 도메인별로 KA를 분리하고 Supervisor로 조율 |
| 2 | Genie Space에 30개 이상 테이블 등록 | SQL 생성 정확도 급감 | 비즈니스 주제별로 Space를 나누고 핵심 테이블만 포함 |
| 3 | 서브 에이전트 Description을 한 줄로 작성 | 라우팅 정확도 저하 | 담당 업무, 처리 가능한 질문 유형, 사용 데이터를 상세히 기술 |
| 4 | 평가 없이 프로덕션 배포 | 품질 문제가 사용자에게 그대로 노출 | AI Judge + Synthetic Task로 최소 50개 이상 테스트 후 배포 |
| 5 | 인스트럭션 없이 기본 설정만 사용 | 응답이 일관성 없고 형식이 제각각 | 언어, 톤, 인용 규칙, 거부 조건 등을 인스트럭션에 명시 |
프로덕션 운영 노하우
안정적인 프로덕션 운영을 위한 체크리스트
Agent Bricks를 프로덕션에 배포한 후 안정적으로 운영하기 위해 아래 항목을 점검하세요.| # | 항목 | 확인 내용 | 주기 |
|---|---|---|---|
| 1 | 엔드포인트 상태 | Model Serving 엔드포인트가 Ready 상태인지 | 매일 |
| 2 | 응답 지연 | P95 응답 시간이 10초 이내인지 | 매일 |
| 3 | 오류율 | 실패 쿼리 비율이 5% 미만인지 | 매일 |
| 4 | 사용자 피드백 | 좋아요/싫어요 비율 추이 | 매주 |
| 5 | AI Judge 점수 | 주요 메트릭(Correctness, Groundedness)이 임계값 이상인지 | 매주 |
| 6 | Knowledge Source 동기화 | 문서 업데이트가 반영되었는지 | 문서 변경 시 |
| 7 | 비용 | 일별 DBU 소비량이 예산 내인지 | 매주 |
| 8 | 권한 | 사용자 접근 권한이 올바르게 설정되어 있는지 | 매월 |
운영 단계별 안정화 전략
Knowledge Source 업데이트 전략
프로덕션 환경에서 문서나 데이터가 변경될 때의 대응 전략입니다.| 변경 유형 | 영향 | 대응 |
|---|---|---|
| 문서 내용 수정 | 기존 답변이 구버전 정보를 참조할 수 있음 | Sync 실행 후 관련 질문으로 재테스트 |
| 새 문서 추가 | 새 문서 관련 질문에 답변 가능해짐 | Sync 후 새 문서 관련 테스트 케이스 추가 |
| 문서 삭제 | 해당 문서 관련 질문에 답변 불가 | Sync 후 “정보 없음” 응답이 올바르게 나오는지 확인 |
| 테이블 스키마 변경(Genie) | SQL 생성이 실패할 수 있음 | Knowledge Store의 컬럼 설명 즉시 업데이트 |
| 데이터 값 변경(Genie) | 자동 반영 (SQL이 실시간 실행) | 추가 조치 불필요 |
비용 최적화
Agent Bricks의 비용은 크게 Foundation Model 호출 비용, Serverless Compute 비용, Vector Search 비용 으로 나뉩니다.비용 구조 이해
| 비용 항목 | 발생 조건 | 규모 |
|---|---|---|
| Foundation Model (LLM) | 에이전트가 응답을 생성할 때마다 | 토큰 수에 비례 — 가장 큰 비용 요소 |
| Serverless Compute | 에이전트 엔드포인트 실행 | 항상 켜져 있으므로 기본 비용 발생 |
| Vector Search | KA의 문서 검색 시 | 인덱스 크기 + 쿼리 수에 비례 |
| SQL Warehouse | Genie의 SQL 실행 시 | 쿼리 복잡도 + Warehouse 크기에 비례 |
| 자동 최적화 | 백그라운드 모델 테스트/파인 튜닝 | 자동 실행되므로 비용 예측이 어려울 수 있음 |
비용 절감 전략
| 전략 | 예상 절감 효과 | 구현 방법 |
|---|---|---|
| 불필요한 엔드포인트 정리 | 20~30% | 테스트용 에이전트 삭제, 미사용 엔드포인트 비활성화 |
| Knowledge Source 최적화 | 10~15% | 중복 문서 제거, 불필요한 소스 연결 해제 → 검색 토큰 절감 |
| Instructions 최적화 | 5~10% | “간결하게 응답하세요” 지시 → 출력 토큰 절감 |
| Serverless Budget Policy | 비용 초과 방지 | 일별/월별 예산 한도 설정 |
| Genie SQL Warehouse 최적화 | 15~25% | Auto Stop 설정, 적정 크기 선택, Serverless 사용 |
| 사용 패턴 분석 | 간접 효과 | 비업무 시간에는 트래픽이 없으므로 리소스 자동 축소 활용 |
비용 모니터링 대시보드 설정
다음 메트릭을 추적하는 대시보드를 구축하세요.| 메트릭 | 집계 단위 | 임계값 |
|---|---|---|
| 일별 DBU 소비량 | 에이전트별 | 예산의 80% 초과 시 알림 |
| 쿼리당 평균 토큰 수 | 에이전트별 | 급격한 증가 시 알림 (Instructions 또는 Knowledge Source 변경 영향) |
| 일별 쿼리 수 | 에이전트별 | 급격한 증가 시 알림 (비정상 트래픽 감지) |
| SQL Warehouse DBU | Genie별 | 비효율적 SQL 패턴 감지 |
| Vector Search DBU | KA별 | 인덱스 크기 급증 감지 |
참고 비용 최적화 팁: Agent Bricks의 자동 최적화 기능은 더 효율적인 모델을 자동으로 선택합니다. 즉, 시간이 지남에 따라 동일한 품질을 더 저렴한 모델로 달성할 수 있게 되어 비용이 자연스럽게 감소할 수 있습니다.
모니터링 설정
필수 모니터링 항목
| 카테고리 | 메트릭 | 수집 방법 | 알림 조건 |
|---|---|---|---|
| 가용성 | 엔드포인트 상태 | Serving Endpoint API | 상태가 Ready가 아닐 때 |
| 성능 | P50/P95/P99 응답 시간 | MLflow Tracing | P95 > 10초 |
| 오류 | HTTP 5xx 비율 | 엔드포인트 로그 | 5분간 5% 초과 |
| 품질 | AI Judge Correctness | 주간 자동 평가 | 전주 대비 5% 이상 하락 |
| 사용자 | 부정 피드백 비율 | Monitoring 탭 | 일 20% 초과 |
| 라우팅 | 라우팅 정확도 | Supervisor Trace 분석 | 80% 미만 |
| 비용 | 일별 DBU | Billing API | 예산 80% 초과 |
알림 설정 방법
Databricks SQL Alert 활용:| 도구 | 연동 방법 | 용도 |
|---|---|---|
| Datadog | Databricks → Datadog Integration | 메트릭 대시보드 + 알림 |
| PagerDuty | Databricks SQL Alert → Webhook → PagerDuty | 온콜 알림 |
| Slack | Databricks SQL Alert → Webhook → Slack | 팀 채널 알림 |
장애 대응 패턴
일반적인 장애 유형과 대응
| 장애 유형 | 증상 | 원인 | 대응 |
|---|---|---|---|
| 엔드포인트 다운 | 모든 요청이 5xx | Serverless Compute 문제 | Databricks 상태 페이지 확인 → 지원 티켓 |
| 응답 지연 급증 | P95 > 30초 | Vector Search 또는 SQL Warehouse 부하 | 엔드포인트 크기 증가, SQL Warehouse 스케일업 |
| 품질 급락 | Correctness 급감 | Knowledge Source 변경, 모델 업데이트 | 최근 변경 사항 롤백, 평가 재실행 |
| 라우팅 오류 | 잘못된 에이전트로 위임 | Description 변경 또는 새 서브 에이전트 추가 | Description 수정, Instructions에 라우팅 규칙 명시 |
| 권한 에러 | ”접근 불가” 응답 | UC 권한 변경, 서비스 프린시펄 문제 | UC 권한 확인, On-Behalf-Of-User 설정 확인 |
| 비용 급증 | 일별 DBU 급등 | 비정상 트래픽, 비효율적 SQL | Budget Policy로 즉시 제한, 원인 분석 |
장애 대응 플레이북
롤백 전략
| 변경 유형 | 롤백 방법 |
|---|---|
| Instructions 변경 | 이전 Instructions 텍스트를 다시 입력 (별도 버전 관리 권장) |
| Knowledge Source 변경 | UC Volume에서 이전 버전 파일 복원 → Sync 재실행 |
| 서브 에이전트 추가/삭제 | Supervisor 설정에서 서브 에이전트 복원/제거 |
| 권한 변경 | UC GRANT/REVOKE로 원래 권한 복원 |
주의 버전 관리의 중요성: Agent Bricks는 현재 Instructions, Description 등의 텍스트 설정에 대한 내장 버전 관리를 제공하지 않습니다. 중요한 설정 변경 전에 반드시 현재 설정을 별도로 백업(텍스트 파일, Confluence 등)해두세요. SDK를 통해 설정을 조회하고 저장하는 스크립트를 만들어 두면 롤백이 훨씬 수월합니다.
추가 Anti-patterns: 운영 단계의 실수
위험 배포 이후 운영 단계에서 자주 발생하는 추가 실수입니다.
| # | Anti-pattern | 문제점 | 해결 방법 |
|---|---|---|---|
| 6 | 배포 후 모니터링을 설정하지 않음 | 품질 저하, 장애를 사용자 보고로만 감지 | 배포 전 모니터링 알림 먼저 설정 |
| 7 | 문서 업데이트 후 Sync를 잊음 | 에이전트가 구버전 정보로 답변 | 문서 업데이트 프로세스에 Sync를 필수 단계로 포함 |
| 8 | 모든 사용자에게 Can Manage 권한 부여 | 설정이 의도치 않게 변경될 위험 | 관리자만 Can Manage, 일반 사용자는 Can Query |
| 9 | 비용 한도 없이 운영 | 예상치 못한 비용 폭증 | Serverless Budget Policy 필수 설정 |
| 10 | SME 피드백 루프 없이 운영 | 에이전트 품질이 사용자 기대와 괴리 | 월 1회 이상 SME 리뷰 프로세스 운영 |