> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 자동 평가
> 에이전트 응답을 심판 LLM이 비동기로 채점 — 검색 품질·충실도·응답 품질 평가, 켜기·결과·통계·내보내기
관리자 › 평가 › 자동 평가
에이전트에서 자동 평가를 활성화하면, 응답 후 비동기로 **심판 LLM**이 품질을 평가하고 결과를 기록합니다.
자동 평가는 라이선스 기능입니다. `evaluation` 피처가 활성화된 라이선스가 필요합니다.
***
## 평가 유형
| 유형 | 설명 |
| ----------------------------- | -------------------------- |
| **검색 품질 (Retrieval Quality)** | 검색된 문서가 질문과 관련성이 있는지 평가 |
| **충실도 (Faithfulness)** | 검색 내용에 기반한 답변인지 평가 (환각 감지) |
| **응답 품질 (Response Quality)** | 전반적인 유용성과 정확성 평가 |
**검색 품질**과 **충실도**는 해당 응답에 검색된 컨텍스트가 있을 때만 평가됩니다. 지식 기반을 거치지 않은 대화에서는 두 유형이 건너뛰어지고 **응답 품질**만 기록됩니다. 사용자가 대화 중 직접 올린 파일은 에이전트의 검색 결과가 아니므로 **검색 품질** 대상에서는 제외되고, **충실도** 평가에는 포함됩니다.
***
## 평가 프로세스
```mermaid theme={null}
flowchart LR
A[에이전트 응답] --> B{활성화 · 심사 모델 · 평가 유형 설정 완료?}
B -->|Yes| C[샘플링]
B -->|No| D[종료]
C --> E[유형별 컨텍스트 조건 확인]
E --> F[심판 LLM에 전달]
F --> G[점수 + 근거 생성]
G --> H[결과 저장]
H --> I[대시보드 반영]
```
***
## 자동 평가 켜기 (에이전트에서 활성화)
자동 평가는 에이전트 단위로 켭니다. 다만 **활성화 토글만으로는 평가가 실행되지 않습니다** — **심사 모델**과 **평가 유형(1개 이상)** 을 함께 지정해야 합니다. 셋 중 하나라도 비어 있으면 에이전트는 그대로 저장되지만 평가 결과가 쌓이지 않습니다(설정 화면에 '심사 모델을 선택해주세요' · '평가 유형을 하나 이상 선택해주세요' 안내가 표시됩니다). 세 가지가 갖춰진 뒤에야 응답마다 샘플링 비율에 따라 평가 여부가 결정됩니다.
**워크스페이스 > 에이전트**에서 대상 에이전트의 편집 화면을 엽니다.
에이전트 설정의 **자동 평가** 섹션에서 활성화합니다.
| 설정 | 설명 |
| ---------- | ---------------------------------------------- |
| **활성화** | 자동 평가 사용 여부 |
| **샘플링 비율** | 평가할 응답 비율 (1%\~100%, 기본 10%) |
| **심사 모델** | 평가에 사용할 LLM 모델. 목록에는 프리셋 모델과 아레나 모델이 나타나지 않습니다 |
| **평가 유형** | 활성화할 평가 유형 선택 |
**샘플링 비율 권장:**
| 상황 | 권장 | 이유 |
| ------- | :------: | ------------ |
| 신규 에이전트 | 50\~100% | 초기 품질 빠르게 파악 |
| 안정화 후 | 5\~10% | 비용 절감 + 모니터링 |
| 핵심 업무 | 20\~30% | 품질 보증 |
심사 모델 호출에도 토큰이 사용됩니다. 이 토큰은 [모니터링 › 사용량](/ko/monitoring/usage)에서 평가 유형별 작업 유형(`auto_eval:...`)으로 집계되며, 해당 응답의 추적 상세에도 평가 실행 기록이 함께 남습니다.
에이전트를 저장하면, 이후 해당 에이전트의 응답에 대해 자동 평가가 실행됩니다.
심사 모델은 평가 대상 모델보다 동등하거나 더 높은 수준의 모델을 사용하세요. 예를 들어 GPT-4o 응답을 GPT-4o-mini로 평가하면 정확도가 낮을 수 있습니다.
***
## 평가 결과
화면 하단 표에 평가 건별 결과가 쌓입니다. 행을 클릭하면 아래로 펼쳐져 **평가 근거**와 평가에 사용된 입력을 확인할 수 있고(우측 화살표는 펼침 상태 표시입니다), 휴지통 아이콘으로 개별 결과를 삭제합니다. 삭제 시 확인 창이 한 번 표시됩니다.
결과 표의 컬럼은 **모델 · 유형 · 점수 · 상태 · 생성일** 입니다. 행을 펼치면 아래 항목이 표시되며, 각 항목은 값이 있을 때만 나타납니다.
| 항목 | 설명 |
| ------------ | --------------------------------------------------------------- |
| **평가 대상 모델** | 응답을 생성한 모델 |
| **심사 모델** | 평가에 사용된 LLM |
| **점수** | 0.0\~1.0 값으로 기록되며 화면에는 백분율로 표시(80% 이상 초록 · 50% 이상 노랑 · 그 미만 빨강) |
| **생성일** | 평가가 생성된 시각 |
| **오류** | 실패한 평가의 오류 내용 |
| **평가 근거** | 점수에 대한 심사 모델의 설명 |
| **사용자 질문** | 평가 대상이 된 질문 |
| **어시스턴트 응답** | 평가 대상이 된 응답 |
| **검색된 컨텍스트** | 평가에 사용된 검색 컨텍스트. 개수와 함께 표시 |
| **추가 정보** | 평가와 함께 기록된 부가 정보 |
| **평가 사용자** | 평가 대상 대화의 사용자(이름 · 이메일) |
대화·메시지 식별자는 화면에 표시되지 않고 내보내기 파일에만 포함됩니다.
***
## 점수 추이 차트
기간 내 평균 점수 변화를 라인 차트로 보여줍니다. 범례에는 데이터가 있는 평가 유형(검색 품질·충실도·응답 품질)이 표시되고, 유형이 **둘 이상일 때만** 전체 **평균** 기준선(회색 파선)이 함께 그려집니다. 차트에는 **완료** 상태이면서 점수가 있는 평가만 반영되며, 평가가 없는 구간은 선이 끊겨 표시됩니다.
* 차트 우측 상단 토글로 집계 단위를 바꿉니다.
| 집계 단위 | 설명 |
| ------------------ | ---------------------- |
| **시간 / 일 / 주 / 월** | 해당 단위로 평균 점수 집계 |
| **자동** | 선택한 기간에 맞춰 집계 단위 자동 결정 |
모델·유형별로 좁혀 보려면 상단 필터(모델/유형)를 사용합니다.
선택한 기간에 완료된 평가가 아주 많으면(약 1,000건 이상) 차트는 그 기간의 **앞쪽(오래된) 구간**만 그리고 최근 구간이 빠질 수 있습니다. 최근 추이를 정확히 보려면 기간을 좁히거나 모델·유형 필터로 범위를 줄이세요. 상단 **평균 점수** 카드의 값은 이 제한과 무관하게 기간 전체를 집계하며, 카드 아래 스파크라인은 차트와 같은 범위를 따릅니다.
***
## 모델별
차트 아래 **모델별** 영역에 모델(에이전트)별 **평가 수**와 **평균 점수**가 표로 정리됩니다. 평가 수가 많은 순으로 정렬되고, 평균 점수는 막대와 백분율로 함께 표시됩니다(점수가 없으면 `-`). 모델이 많으면 영역 안에서 스크롤됩니다. 어느 모델의 점수가 낮은지 비교할 때 사용합니다.
이 표의 평가 수와 평균 점수는 **완료된 평가만** 집계하므로 상단 **합계** 카드보다 작을 수 있습니다.
***
## 필터 옵션
화면 상단의 필터로 기간·모델·유형·상태를 좁힙니다. 기간을 제외한 세 필터는 **체크박스 다중 선택**이며 기본값은 전체 선택입니다. 일부만 선택하면 옆에 **필터 초기화** 버튼이 나타나고, **새로고침** 버튼으로 다시 조회할 수 있습니다.
| 필터 | 옵션 |
| ------ | ------------------------------------------- |
| **기간** | 최근 1일 · 최근 7일 · 최근 30일 · 전체 · 사용자 정의 |
| **모델** | 전체(기본), 또는 모델·에이전트 여러 개 선택 — 아레나 모델은 목록에 없음 |
| **유형** | 검색 품질 · 충실도 · 응답 품질 (여러 개 선택 가능) |
| **상태** | 대기 중 · 완료 · 실패 (여러 개 선택 가능) |
**상태** 필터는 아래 결과 표에만 적용됩니다. 상단 요약 카드·점수 추이 차트·모델별 표는 기간·모델·유형만 반영하므로 상태를 좁혀도 값이 바뀌지 않습니다.
***
## 자동 평가 통계
결과 화면 상단에 요약 카드가 표시됩니다.
| 카드 | 설명 |
| --------- | ---------------------------------------------------------------------------------------------------------- |
| **평균 점수** | 전체 평균 점수(%). 직전 기간 대비 증감률과 추이 스파크라인이 함께 표시됩니다. 기간을 **전체**로 선택하면 비교 기준이 없어 증감률은 표시되지 않으며, 평균은 완료된 평가만 집계합니다 |
| **합계** | 총 자동 평가 수 |
| **완료** | 성공적으로 완료된 평가 수 |
| **대기 중** | 아직 처리되지 않은 평가 수 |
| **실패** | 평가에 실패한 수 |
***
## 내보내기
결과 화면 우측 상단에는 내보내기 버튼이 두 개 있습니다 — 다운로드 아이콘(**JSON으로 내보내기**)과 **CSV** 버튼입니다. 각각 `auto-evaluations-<날짜>-<시각>.json`, `.csv` 파일로 저장됩니다. CSV 에는 평가 ID, 대화·메시지 식별자, 사용자, 평가 대상 모델, 심사 모델, 평가 유형, 점수, 상태, 평가 근거, 오류 메시지, 생성 시각, 완료 시각이 열로 들어갑니다. JSON 은 검색된 컨텍스트와 추가 정보까지 포함한 전체 항목을 그대로 내보냅니다. 두 형식 모두 화면에 적용한 필터와 무관하게 **전체 결과**를 대상으로 합니다.
***
## 활용 사례
1. 점수 추이 차트에서 일간/주간 점수 추이를 확인합니다
2. 특정 모델의 점수가 하락하면 해당 기간의 트레이스를 확인합니다
3. 낮은 점수의 개별 평가 행을 클릭하여 **평가 근거**를 확인합니다
4. 프롬프트, 지식 기반, 도구 설정을 조정합니다
***
## 문제 해결
자동 평가가 failed 상태인 경우:
* **에러 메시지 확인**: 결과 테이블에서 해당 항목의 에러 내용 확인
* **일반적인 원인**: 심사 모델의 API 오류, 타임아웃, 토큰 한도 초과
* **재실행**: 현재 자동 재실행은 지원되지 않습니다. 에이전트 설정에서 자동 평가를 재활성화하면 이후 응답부터 다시 평가됩니다.
***
## 관련 페이지
수동 피드백·아레나·리더보드 등 평가 전체 개요
낮은 평가 점수의 원인을 트레이스에서 추적
자동 평가를 에이전트에 설정