Skip to main content

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에 등록하면 정확도가 크게 향상됩니다.
-- 예시: 월별 매출 합계 표현식
SELECT DATE_TRUNC('month', order_date) AS month,
       SUM(order_amount) AS total_revenue
FROM sales.orders
GROUP BY 1
ORDER BY 1
항목권장사항
Sample Questions실제 비즈니스 질문 패턴을 등록 (최대 100개)
Instructions응답 형식, 단위(원/달러), 날짜 형식 등 명시
모니터링정기적으로 Monitoring 탭 확인 후 Knowledge Store 업데이트

Supervisor Agent 베스트 프랙티스

서브 에이전트 설계

항목권장사항
서브 에이전트 수3~5개 이내 권장 (많을수록 라우팅 복잡도 증가)
Description담당 업무를 최대한 상세하게 작성 (라우팅 정확도에 직결)
권한 설계엔드 유저의 서브 에이전트별 접근 권한을 사전에 설계
테스트다양한 시나리오로 라우팅 정확도를 검증
Long-Running Mode복잡한 태스크는 Long-Running Task Mode 활용

라우팅 로직 최적화

Supervisor는 서브 에이전트의 Description 을 기반으로 라우팅합니다. 다음을 지켜주세요.
  1. 겹치지 않는 역할 정의: 서브 에이전트 간 책임이 겹치면 라우팅이 혼란스러워집니다
  2. 명확한 키워드 포함: Description에 해당 에이전트가 처리할 질문 유형의 키워드를 포함
  3. 폴백 에이전트 설정: 어떤 에이전트에도 해당하지 않는 질문을 처리할 일반 에이전트 배치
주의 서브 에이전트가 7개 이상 이면 라우팅 정확도가 눈에 띄게 떨어집니다. 역할이 비슷한 에이전트는 하나로 통합하세요.

공통 권장사항

평가 루프

  1. 반복적 개선: 배포 후에도 Examples 탭에서 지속적으로 피드백을 수집하고 가이드라인을 업데이트
  2. 체계적 평가: AI Judge + Synthetic Task Generation으로 정기적 품질 측정
  3. SME 리뷰: 도메인 전문가(Subject Matter Expert)에게 공유 링크를 전달하여 정기 리뷰 수행

모니터링

  1. 트레이싱 활성화: Production Monitoring for MLflow를 활성화하여 실행 과정 추적
  2. 응답 지연 모니터링: 엔드포인트 응답 시간이 10초를 초과하면 최적화 필요
  3. 오류율 추적: 실패한 쿼리 비율이 5% 이상이면 즉시 원인 분석

비용 관리

전략설명
Serverless Budget Policy예산 한도를 설정하여 비용 초과 방지
사용량 모니터링Billing 대시보드에서 에이전트별 DBU 소비량 추적
불필요한 엔드포인트 정리테스트용 엔드포인트는 사용 후 삭제
모델 선택간단한 태스크에 대형 모델을 사용하지 않기

권한 및 보안

  1. 권한 최소화: 필요한 사용자에게만 최소한의 권한 부여
  2. Unity Catalog 활용: 데이터 접근 권한을 UC로 일원화
  3. 리전 확인: 현재 us-east-1 또는 us-west-2에서만 사용 가능

Anti-patterns: 흔한 실수 5가지

위험 다음은 Agent Bricks를 사용할 때 자주 발생하는 실수입니다. 반드시 피하세요.
#Anti-pattern문제점해결 방법
1모든 문서를 하나의 KA에 몰아넣기검색 정확도 하락, 무관한 문서가 인용됨도메인별로 KA를 분리하고 Supervisor로 조율
2Genie 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사용자 피드백좋아요/싫어요 비율 추이매주
5AI Judge 점수주요 메트릭(Correctness, Groundedness)이 임계값 이상인지매주
6Knowledge Source 동기화문서 업데이트가 반영되었는지문서 변경 시
7비용일별 DBU 소비량이 예산 내인지매주
8권한사용자 접근 권한이 올바르게 설정되어 있는지매월

운영 단계별 안정화 전략

[배포 직후 (1~2주): 집중 모니터링]
    - 모든 사용자 질문을 Monitoring 탭에서 확인
    - 부정 피드백(싫어요)이 달린 응답을 우선 분석
    - 라우팅 오류, 검색 실패 패턴 파악
    - 긴급 수정이 필요한 Instructions/Description 조정

[안정화 (3~4주): 품질 개선]
    - 프로덕션 로그에서 실패 케이스 수집 → Examples 탭에 추가
    - AI Judge로 정기 평가 시작 (주 1회)
    - 사용 패턴 분석 → 자주 묻는 질문 유형에 대한 최적화
    - Genie의 경우: 비효율적 SQL을 Instructions에 최적화된 예시로 교체

[성숙 운영 (1개월+): 자동화]
    - 평가 자동화 파이프라인 구축
    - 알림 설정 (오류율 급증, 응답 지연 증가 시)
    - 정기 SME 리뷰 프로세스 확립
    - 비용 최적화 (불필요한 엔드포인트 정리, 모델 크기 조정)

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 SearchKA의 문서 검색 시인덱스 크기 + 쿼리 수에 비례
SQL WarehouseGenie의 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 DBUGenie별비효율적 SQL 패턴 감지
Vector Search DBUKA별인덱스 크기 급증 감지
참고 비용 최적화 팁: Agent Bricks의 자동 최적화 기능은 더 효율적인 모델을 자동으로 선택합니다. 즉, 시간이 지남에 따라 동일한 품질을 더 저렴한 모델로 달성할 수 있게 되어 비용이 자연스럽게 감소할 수 있습니다.

모니터링 설정

필수 모니터링 항목

카테고리메트릭수집 방법알림 조건
가용성엔드포인트 상태Serving Endpoint API상태가 Ready가 아닐 때
성능P50/P95/P99 응답 시간MLflow TracingP95 > 10초
오류HTTP 5xx 비율엔드포인트 로그5분간 5% 초과
품질AI Judge Correctness주간 자동 평가전주 대비 5% 이상 하락
사용자부정 피드백 비율Monitoring 탭일 20% 초과
라우팅라우팅 정확도Supervisor Trace 분석80% 미만
비용일별 DBUBilling API예산 80% 초과

알림 설정 방법

Databricks SQL Alert 활용:
-- 에이전트 오류율 모니터링 쿼리 예시
SELECT
    DATE(timestamp) AS date,
    endpoint_name,
    COUNT(*) AS total_requests,
    SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) AS error_count,
    ROUND(SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) * 100.0
          / COUNT(*), 2) AS error_rate_pct
FROM system.serving.endpoint_logs
WHERE endpoint_name = 'customer-support-supervisor'
    AND DATE(timestamp) = CURRENT_DATE
GROUP BY 1, 2
HAVING error_rate_pct > 5.0
외부 모니터링 도구 연동:
도구연동 방법용도
DatadogDatabricks → Datadog Integration메트릭 대시보드 + 알림
PagerDutyDatabricks SQL Alert → Webhook → PagerDuty온콜 알림
SlackDatabricks SQL Alert → Webhook → Slack팀 채널 알림

장애 대응 패턴

일반적인 장애 유형과 대응

장애 유형증상원인대응
엔드포인트 다운모든 요청이 5xxServerless Compute 문제Databricks 상태 페이지 확인 → 지원 티켓
응답 지연 급증P95 > 30초Vector Search 또는 SQL Warehouse 부하엔드포인트 크기 증가, SQL Warehouse 스케일업
품질 급락Correctness 급감Knowledge Source 변경, 모델 업데이트최근 변경 사항 롤백, 평가 재실행
라우팅 오류잘못된 에이전트로 위임Description 변경 또는 새 서브 에이전트 추가Description 수정, Instructions에 라우팅 규칙 명시
권한 에러”접근 불가” 응답UC 권한 변경, 서비스 프린시펄 문제UC 권한 확인, On-Behalf-Of-User 설정 확인
비용 급증일별 DBU 급등비정상 트래픽, 비효율적 SQLBudget Policy로 즉시 제한, 원인 분석

장애 대응 플레이북

[1단계: 감지]
    - 알림 수신 (Slack, PagerDuty 등)
    - 영향 범위 파악: 전체 에이전트? 특정 서브 에이전트?

[2단계: 1차 진단 (5분)]
    - Serving Endpoint 상태 확인
    - 최근 변경 사항 확인 (Instructions, Knowledge Source, 권한)
    - MLflow Trace에서 에러 패턴 확인

[3단계: 임시 조치 (10분)]
    - 원인이 Knowledge Source 변경이면 → Sync 재실행 또는 이전 버전 복원
    - 원인이 권한 변경이면 → UC 권한 복원
    - 원인이 과부하이면 → Budget Policy 조정, 트래픽 제한

[4단계: 근본 원인 분석 (1시간)]
    - 장애 발생 시점의 Trace 상세 분석
    - 유사 패턴의 과거 장애 사례 확인
    - 근본 원인 특정

[5단계: 영구 수정 + 재발 방지]
    - 근본 원인 수정
    - AI Judge로 수정 후 품질 검증
    - 해당 장애 유형에 대한 자동 알림 추가
    - 장애 보고서 작성 (원인, 영향, 대응, 재발 방지)

롤백 전략

변경 유형롤백 방법
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 필수 설정
10SME 피드백 루프 없이 운영에이전트 품질이 사용자 기대와 괴리월 1회 이상 SME 리뷰 프로세스 운영