> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 평가 센터

> 테스트 데이터셋과 자동화된 LLM 등급 평가로 에이전트를 정량적으로 벤치마크합니다.

평가 센터를 통해 프로덕션 배포 **전에** 에이전트 품질을 검증할 수 있습니다. 테스트 케이스 데이터셋을 생성하고, 게시된 모든 에이전트에 대해 실행한 후, 케이스별 통과/실패 판정, 지연 시간 및 토큰 사용량이 포함된 정량적 보고서를 받습니다.

<Info>
  엔터프라이즈 조달 검토를 위해 설계됨 — 모든 결과는 감사 가능하고, 재현 가능하며, 지속적으로 저장됩니다.
</Info>

## 작동 방식

각 평가 실행은 모든 테스트 케이스에 대해 **3단계 파이프라인**을 실행합니다:

<Steps>
  <Step title="에이전트 실행">
    실제 ReActAgent가 테스트 케이스 프롬프트를 실행합니다. 채팅과 동일한 엔진: 동일한 모델, 동일한 도구, 동일한 지침. 모킹 없음, 지름길 없음.

    생성: **답변**, **지연시간**, **토큰 사용량**.
  </Step>

  <Step title="LLM 채점">
    별도의 "채점자" LLM(빠른 모델)이 예상 동작 및 어설션에 대해 답변을 판단합니다.

    입력: 프롬프트 + 예상 동작 + 어설션 + 답변. 출력: `{ verdict: "pass"|"fail", reasoning: "..." }`.
  </Step>

  <Step title="저장 및 집계">
    각 케이스 결과는 데이터베이스에 저장됩니다. 모든 케이스가 완료된 후: **통과율**, **평균 지연시간**, **총 토큰**이 계산되어 실행에 첨부됩니다.
  </Step>
</Steps>

### 주요 설계 결정

| 결정                           | 이유                                              |
| ---------------------------- | ----------------------------------------------- |
| **실제 ReActAgent** (모의 객체 아님) | 도구 호출 및 다단계 추론을 포함한 실제 에이전트 동작 테스트              |
| **별도의 채점 LLM** (빠른 모델)       | 저렴하고 빠름; 에이전트 LLM은 실행 중에 이미 토큰 소비               |
| **`asyncio.Semaphore(5)`**   | 동시성을 5로 제한하여 LLM 제공자에 대한 속도 제한 오류 방지            |
| **각 사례는 독립적**                | 사례 간 대화 기록 없음; 각각 새로운 에이전트 인스턴스 획득              |
| **백그라운드 실행**                 | 실행이 비동기 작업으로 시작됨 — API가 즉시 반환되고, 프론트엔드는 3초마다 폴링 |

## 워크플로우

### 1. 데이터셋 생성

**Eval Center → Datasets** 탭으로 이동하여 **New Dataset**을 클릭합니다.

데이터셋은 테스트 케이스의 명명된 컬렉션입니다. 설명적인 이름(예: "Customer Support — Tier 1 Questions")과 선택적 설명을 입력합니다.

### 2. 테스트 케이스 추가

데이터셋을 클릭하여 테스트 케이스를 추가합니다. 각 케이스는 세 가지 필드를 가집니다:

| 필드        | 필수  | 설명                                            |
| --------- | --- | --------------------------------------------- |
| **프롬프트**  | 예   | 에이전트에게 전송되는 정확한 질문 또는 지시사항                    |
| **예상 동작** | 예   | 올바른 답변이 어떤 모습인지에 대한 자연어 설명                    |
| **어설션**   | 아니오 | 특정 확인 목록 (예: "답변에서 환불 정책 언급", "응답이 200단어 미만") |

<Tip>
  **좋은 테스트 케이스 작성하기:**

  * **프롬프트**: 구체적으로 작성하세요. "엔터프라이즈 플랜의 환불 정책은 무엇인가요?"가 "환불에 대해 알려주세요."보다 낫습니다.
  * **예상 동작**: 정확한 표현이 아닌 *결과*를 설명하세요. "30일 환불 기간을 설명하고 연간 플랜의 예외사항을 언급합니다."
  * **어설션**: 엄격한 요구사항에 사용하세요. 채점자가 각 어설션을 명시적으로 검증합니다.
</Tip>

### 3. 평가 시작

**Eval Runs** 탭으로 이동하여 **New Evaluation**을 클릭합니다. 다음을 선택합니다:

1. **Agent** — 소유한 모든 에이전트
2. **Dataset** — 최소 하나 이상의 테스트 케이스가 있는 모든 데이터셋

**Start Evaluation**을 클릭합니다. 결과 페이지로 리디렉션됩니다.

### 4. 결과 읽기

결과 페이지에는 다음이 표시됩니다:

* **헤더**: 에이전트 이름, 데이터셋 이름, 상태 배지, 통과율, 평균 지연시간, 총 토큰
* **진행률 표시줄**: 케이스가 완료되면서 채워짐 (녹색 = 통과 비율)
* **결과 테이블**: 테스트 케이스당 한 행:
  * 프롬프트 (잘림 — 클릭하여 확장)
  * 판정: **Pass** (녹색), **Fail** (빨강), 또는 **Error** (주황)
  * 에이전트의 답변 (잘림 — 클릭하여 확장)
  * 평가자의 추론 (통과 또는 실패 이유)
  * 지연시간 (ms) 및 토큰 수

<Warning>
  실행이 진행 중일 때 (`pending` 또는 `running` 상태), 페이지는 3초마다 자동으로 새로고침됩니다. 실시간으로 결과가 나타나는 것을 보고 싶다면 페이지에서 벗어나지 마세요.
</Warning>

## 테스트되는 항목

### 포함됨

* **기본 제공 도구**: calculator, web\_search, web\_fetch, python\_exec, file\_ops 등
* **에이전트 지침**: 에이전트의 `extra_instructions` 필드가 전달됨
* **에이전트의 구성된 모델**: 에이전트에 사용자 정의 모델 구성이 있는 경우 해당 모델이 사용됨

### 포함되지 않음 (의도적)

* **커넥터**: 외부 HTTP 커넥터는 실시간 타사 서비스가 필요하므로 불안정한 테스트를 피하기 위해 평가에서 제외됨
* **MCP 서버**: 같은 이유 — 외부 프로세스 종속성
* **대화 기록**: 각 케이스는 이전 컨텍스트 없이 격리된 상태에서 실행됨
* **지식 베이스**: KB 검색 도구는 평가 모드에서 로드되지 않음

<Info>
  이는 평가 결과가 에이전트의 **추론 및 도구 사용 능력**을 반영하며, 외부 서비스와의 통합을 반영하지 않음을 의미합니다. 커넥터 테스트 기능을 통해 커넥터를 별도로 테스트하세요.
</Info>

## 채점자

채점자는 LLM(시스템의 "빠른" 모델)으로, 네 가지 정보를 받아 구조화된 JSON 판정을 반환합니다:

**시스템 프롬프트:**

> 당신은 공정한 AI 평가자입니다. 당신의 역할은 AI 에이전트의 답변이 주어진 프롬프트에 대한 예상 동작을 충족하는지 판단하는 것입니다.
>
> 엄격하지만 공정하게 평가하세요. "통과"는 답변이 예상 동작에 따라 프롬프트를 진정으로 다루어야 합니다. "실패"는 답변이 잘못되었거나, 불완전하거나, 주제를 벗어났거나, 핵심 요구사항을 놓쳤다는 의미입니다.

**사용자 메시지 포함:**

1. 원본 프롬프트
2. 예상 동작
3. 어설션 목록(또는 "지정되지 않음")
4. 에이전트의 실제 답변

**출력 스키마:**

```json theme={null}
{
  "verdict": "pass" | "fail",
  "reasoning": "답변이 통과하거나 실패하는 이유에 대한 설명..."
}
```

채점자는 스키마를 강제하기 위해 함수 호출과 함께 `structured_llm_call`을 사용합니다. 채점자 자체가 실패하면(네트워크 오류, 잘못된 응답), 사건은 `error`로 표시됩니다.

## 모범 사례

### 데이터셋 설계

* **작게 시작하기**: 에이전트의 핵심 사용 사례를 다루는 5–10개의 사례
* **엣지 케이스 포함**: 최소 2–3개의 적대적 또는 범위 외 프롬프트 포함
* **예상 동작을 구체적으로 명시**: 모호한 기대사항은 일관성 없는 채점으로 이어짐
* **하드 요구사항에 어설션 사용**: "가격을 반드시 언급해야 함"이 채점자가 이를 포착하기를 바라는 것보다 더 신뢰할 수 있음

### 결과 해석

* **80% 이상의 통과율**은 잘 구성된 에이전트의 좋은 기준입니다
* **낮은 통과율과 높은 지연시간**은 에이전트가 다단계 추론에 어려움을 겪고 있음을 시사합니다
* **오류 상태**는 에이전트 또는 채점자가 충돌했음을 의미합니다 — 서버 로그에서 세부 정보를 확인하세요
* **채점자 불일치**: 채점자가 잘못되었다고 생각하면 그 추론을 읽어보세요. 예상 동작 설명을 수정해야 할 수도 있습니다

### 재평가 시기

* 에이전트 지시사항을 변경한 후
* 에이전트의 LLM 모델을 전환한 후
* 도구 카테고리를 추가하거나 제거한 후
* 프로덕션 배포 전 (CI/CD 통합은 향후 릴리스에서 제공 예정)