본문으로 건너뛰기

Deep Agent Builder Evaluator 구성

Evaluator는 에이전트의 답변을 기준 답변이나 판정 지시에 따라 점수로 바꾸는 평가 기준입니다. 이 페이지에서는 Evaluator의 범위와 판정 유형을 정하고, 생성·수정·삭제 전에 확인할 조건을 설명합니다. Dataset과 Case를 먼저 준비하려면 평가 Dataset 만들기와 평가 Case 설계를 확인합니다.

Evaluator가 결정하는 것​

Evaluator에는 판정 지시문, 유형, 점수 범위가 저장됩니다. 실행에 실제로 사용된 모델은 Evaluator가 아니라 평가 실행의 model 값에 기록됩니다. 따라서 Evaluator를 바꿨다고 해서 이미 끝난 실행의 모델이나 결과가 바뀌지는 않습니다.

Evaluator 유형은 세 가지입니다.

유형용도확인할 값
binary통과·실패처럼 두 상태를 판정설정된 판정 지시문과 결과 점수
score일정한 범위에서 점수를 부여score_min이 score_max보다 작은지
rubric여러 기준으로 답변을 검토판정 지시문에 포함한 기준과 결과

유형의 이름만으로 점수 계산 방식이나 품질 보증 범위를 확정하지 않습니다. 실행 결과를 해석할 때는 Evaluator 설정, Dataset의 Case 구성, 실행 상태를 함께 기록합니다.

범위와 표시 정보 확인하기​

Evaluator는 preset, workspace, user 범위로 구분됩니다. 목록에는 고정된 preset 집합, 같은 Workspace의 Evaluator, 호출자가 만든 user Evaluator가 scope와 name 순으로 표시됩니다. 오래된 preset 행이나 중복 preset UID는 목록 대상이 아닙니다.

목록 응답의 prompt_template은 빈 문자열로 표시되고, 상세 조회에서 실제 prompt_template을 확인할 수 있습니다. 목록에서 이름과 유형만 보고 판정 지시문을 확인했다고 판단하지 마세요.

Preset Evaluator는 다음 키로 제공됩니다.

  • accuracy
  • relevance
  • faithfulness
  • completeness
  • humanizer
  • professional

Preset의 수정·삭제 가능 여부와 실제 UI 표시는 제품 권한과 현재 구현을 기준으로 확인합니다. 이 페이지의 근거는 Evaluator API 계약이며, 특정 화면의 메뉴명이나 성공 메시지를 보장하지 않습니다.

Evaluator를 만들기 전에 결정할 것​

먼저 다음 값을 정합니다.

  1. 이름을 정합니다. user 범위에서는 같은 사용자의 같은 이름이 중복되지 않아야 하고, workspace 범위에서는 같은 Workspace의 같은 이름이 중복되지 않아야 합니다.
  2. 범위를 정합니다. 기본 scope는 user이며, Workspace 공유가 필요할 때만 workspace를 선택합니다.
  3. 판정 유형을 정합니다. binary, score, rubric 중 하나를 선택합니다.
  4. 답변을 어떤 기준으로 판정할지 prompt_template에 씁니다. 실제 고객 정보, 비밀값, 운영 로그는 넣지 않습니다.
  5. score 유형을 사용하면 score_min과 score_max를 정합니다. score_min은 score_max보다 작아야 합니다.
  6. 기존 Evaluator를 바탕으로 만들 때는 source_evaluator_id 또는 허용된 source_prebuilt_key를 확인합니다. source_evaluator_id는 저장·감사 로그에는 남지만 응답에는 나타나지 않습니다.

필수 입력은 name, eval_type, prompt_template입니다. description은 선택값이며 기본값은 빈 문자열입니다. score_min의 기본값은 0, score_max의 기본값은 1입니다.

Evaluator를 생성하거나 수정하기​

Evaluator를 생성·수정할 권한과 평가 실행을 조회할 권한은 같은 의미가 아닙니다. 생성 전에 현재 사용자의 범위와 Workspace 컨텍스트를 확인합니다. Workspace Evaluator의 수정은 생성자이거나 manager, admin, owner, superuser 역할일 때만 허용됩니다.

생성 후에는 다음을 확인합니다.

  1. 응답의 name, scope, eval_type이 입력한 값과 일치하는지 확인합니다.
  2. score 유형이면 score_min < score_max 조건을 다시 확인합니다.
  3. source 값을 사용했다면 응답에 source_evaluator_id가 나타난다고 가정하지 않습니다.
  4. 목록에서 같은 이름의 중복이 생기지 않았는지 확인합니다.
  5. 실행을 시작하기 전에 선택한 Evaluator의 상세에서 prompt_template을 다시 확인합니다.

수정은 name, description, prompt_template, eval_type, score_min, score_max에 대한 부분 수정입니다. 바꾸지 않은 값을 요청에 넣지 않아도 되지만, 빈 요청이 기존 값을 바꾸는 것으로 해석된다고 가정하지 마세요. 수정 후에는 유형과 점수 범위가 함께 유효한지 다시 확인합니다.

Evaluator를 삭제하거나 실행에 사용하기​

Evaluator 삭제는 hard delete입니다. 진행 중 평가 실행이 해당 Evaluator를 참조하면 삭제가 409 CONFLICT로 거부될 수 있습니다. 삭제 전에 다음 순서로 판단합니다.

  1. 삭제 대상의 scope와 name을 다시 확인합니다.
  2. pending 또는 running 상태의 평가 실행이 해당 Evaluator를 참조하는지 확인합니다.
  3. Workspace Evaluator라면 호출자가 생성자 또는 허용된 Workspace 역할인지 확인합니다.
  4. 삭제 후 목록과 상세 조회 결과를 다시 확인합니다.

평가를 실행할 때는 Dataset, Agent, Evaluator의 소유·범위를 따로 확인합니다. Workspace Dataset을 조회할 수 있다는 사실만으로 해당 Dataset을 사용한 실행을 시작할 수 있는 것은 아닙니다. 실행에 사용한 모델과 Evaluator 설정은 실행 시점의 값으로 기록되므로, 결과를 비교할 때는 같은 Dataset과 Case뿐 아니라 Evaluator와 모델도 함께 고정해야 합니다.

현재 활성 Backend 경로에서는 ARQ worker가 실행마다 judge 모델을 해소하고, Case별 Agent 응답 뒤 BinaryEvaluator 또는 ScoreEvaluator를 프로세스 안에서 실행합니다. 별도 evaluations 서비스의 evaluation_judge와 evaluation_panel 계약은 이 활성 Backend 경로가 end-to-end로 연결되어 있다는 뜻이 아닙니다.

오류가 나면 무엇을 확인할까​

  • 400 VALIDATION_ERROR: 입력값, 판정 유형 또는 점수 범위를 확인합니다. Preset 수정·삭제의 구현 오류도 이 코드로 나타날 수 있으므로 문서의 예상 권한 오류만 보고 재시도하지 않습니다.
  • 403 WBAC_DENIED: Workspace Evaluator의 생성자 또는 허용된 역할인지 확인합니다.
  • 404 NOT_FOUND: user 범위 Evaluator가 현재 사용자 소유인지, 식별자가 올바른지 확인합니다. 권한이 없는 user Evaluator는 존재하지 않는 것처럼 처리될 수 있습니다.
  • 409 CONFLICT: 진행 중인 평가 실행이 Evaluator를 참조하는지 확인합니다.

요청의 scope 필드는 구현상 Pydantic enum으로 정형 검증된다고 보장할 수 없습니다. 지원되는 scope와 Workspace 컨텍스트를 먼저 확인하고, 알 수 없는 값은 반복해서 전송하지 않습니다.

완료 판단​

Evaluator 준비가 끝났다고 판단하려면 다음 조건을 모두 확인합니다.

  1. 이름과 scope가 평가 목적에 맞고 중복되지 않습니다.
  2. eval_type이 binary, score, rubric 중 의도한 유형입니다.
  3. score 유형의 점수 범위가 유효합니다.
  4. 상세 조회에서 prompt_template과 수정된 필드를 확인했습니다.
  5. 실행에 사용할 Dataset과 Agent의 권한·소유 범위를 확인했습니다.
  6. pending 또는 running 실행과 삭제·수정 작업을 분리했습니다.
  7. 비교할 실행이라면 모델, Evaluator, Dataset, Case 구성을 함께 기록했습니다.

이 확인이 끝나면 에이전트 평가에서 Evaluator를 선택하고, 평가 실행에서 실행 상태를 확인합니다.

다음 문서​