평가 결과 및 실패 클러스터 분석

시작하기 전에

평가 결과를 보고 분석하려면 다음이 있어야 합니다.

  • 에이전트 평가 또는 오프라인 평가 실행에 설명된 대로 평가를 하나 이상 실행합니다.
  • 오프라인 평가를 실행하는 경우 평가 출력을 위해 Cloud Storage 버킷을 구성했습니다.
  • (선택사항) SDK를 사용하여 결과를 가져오는 경우 환경이 인증되었는지 확인합니다.

평가를 실행한 후 Agent Platform은 실패의 근본 원인을 파악하는 데 도움이 되는 진단 도구를 제공합니다. 대시보드의 집계 추세, 실패 클러스터의 시맨틱 그룹, 개별 트레이스의 세분화된 로직 경로의 세 가지 수준에서 결과를 분석할 수 있습니다.

온라인 모니터의 평가 대시보드

활성 온라인 모니터가 있는 에이전트의 경우 대시보드에서 집계된 성능 추세를 볼 수 있습니다.

  1. 콘솔에서 Agent Platform > 에이전트 페이지로 이동합니다. Google Cloud
  2. 왼쪽 탐색 메뉴에서 배포 를 선택합니다.

  3. 에이전트를 선택합니다.

    배포로 이동

  4. 대시보드 탭을 클릭하고 평가 하위 섹션을 선택합니다.

  • 성능 추세: 다양한 에이전트 버전 또는 기간에 걸쳐 작업 성공 또는 도구 사용 품질 과 같은 측정항목의 점수가 어떻게 변하는지 시각화합니다.
  • 제로 상태: 활성 온라인 모니터 가 없는 에이전트의 경우 이 뷰는 적용 범위 격차를 식별하고 평가를 시작하기 위한 클릭 유도 문구를 제공합니다.

SDK로 평가 결과 보기

Agent Platform SDK 를 사용하여 평가 결과에 프로그래매틱 방식으로 액세스할 수 있습니다. SDK는 집계 요약 측정항목과 케이스별 세부 결과를 모두 표시하는 Colab 및 Jupyter 노트북 환경을 위한 기본 제공 대화형 시각화를 제공합니다.

평가를 실행한 후 결과 객체에서 .show()를 호출하여 노트북에서 직접 대화형 보고서를 렌더링합니다.

from vertexai import evals, types

# Run an evaluation
result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.FINAL_RESPONSE_QUALITY,
        types.RubricMetric.TOOL_USE_QUALITY,
        types.RubricMetric.HALLUCINATION,
        types.RubricMetric.SAFETY,
    ],
)

# Visualize aggregate and per-case results in your notebook
result.show()

시각화에는 다음이 포함됩니다.

  • 요약 측정항목: 각 측정항목의 평균 점수와 통과율을 비롯한 모든 평가 케이스의 집계 점수입니다.
  • 케이스별 결과: 세부 결과를 검사하기 위해 펼칠 수 있는 개별 평가 케이스 점수입니다.

다음 예시에서는 result.show()의 요약 측정항목을 보여줍니다.

각 측정항목의 평균 점수와 표준 편차를 보여주는 평가 요약 보고서

개별 평가 케이스를 펼쳐 측정항목별 점수, 기준표 확인 결과, 근거를 확인할 수 있습니다.

측정항목 점수와 개별 기준표 통과 또는 실패 확인 결과가 설명과 함께 표시되는 케이스별 평가 결과

평가 결과 해석

미리 정의된 측정항목은 측정항목 유형에 따라 두 가지 형식으로 결과를 반환합니다.

  • 적응형 기준표 측정항목 은 에이전트의 구성과 사용자의 프롬프트를 기반으로 기준표를 자동으로 생성합니다. 각 기준표는 판사 LLM의 추론을 설명하는 자연어 근거와 함께 개별 통과 또는 실패 확인 결과를 받습니다. 전반적인 점수는 통과 확인 결과를 받은 기준표의 비율인 통과율을 나타냅니다.
  • 정적 기준표 측정항목 은 고정된 평가 기준을 사용합니다. 예를 들어 할루시네이션은 대답을 원자적 클레임으로 분할하고 각 클레임을 도구 사용 증거와 비교하여 확인합니다. PII, 증오심 표현, 위험한 콘텐츠, 기타 정책 위반에 대한 안전 점검입니다. 이러한 측정항목은 단일 숫자 점수 (0~1)를 반환합니다.

실패 식별 및 분류

평가 결과를 검토한 후 다음 단계는 시스템 실패 패턴을 식별하고 에이전트를 개선하기 위해 분류하는 것입니다. Agent Platform 은 기준표 기반 측정항목의 통과 또는 실패 신호를 분석하고, 실패를 미리 정의된 손실 패턴으로 분류하고, 시맨틱 클러스터로 그룹화하는 자동 손실 분석을 제공합니다. 이를 통해 에이전트가 실패했다는 사실뿐만 아니라 이유와 방법을 이해할 수 있습니다.

콘솔에서 실패 클러스터에 액세스

  1. Agent Platform > 에이전트 > 평가 페이지로 이동합니다.
  2. 평가 탭을 선택합니다.
  3. 완료된 평가 실행의 이름을 클릭하여 보고서를 엽니다.
  4. 평가에서 클러스터를 감지한 경우 보고서의 실패 클러스터 섹션에 표시됩니다.

SDK로 실패 클러스터 생성

generate_loss_clusters 메서드를 사용하여 프로그래매틱 방식으로 실패 클러스터를 생성할 수도 있습니다.

# Generate failure clusters from evaluation results
loss_clusters = client.evals.generate_loss_clusters(
    eval_result=result,
)

# Visualize the loss pattern analysis in your notebook
loss_clusters.show()

다음 예시에서는 loss_clusters.show()의 손실 패턴 분석을 보여줍니다.

예시 시나리오와 근거가 포함된 카테고리별로 그룹화된 실패 클러스터를 보여주는 손실 패턴 분석 보고서

손실 패턴 분류

자동 손실 분석은 각 실패를 하나 이상의 미리 정의된 손실 패턴으로 분류합니다. 이러한 패턴은 구체적이고 실행 가능하도록 설계되어 있으며 개선할 수 있는 에이전트의 특정 영역에 직접 매핑됩니다.

두 가지 미리 정의된 분류가 있으며 각 분류는 특정 측정항목에 맞춰져 있습니다.

에이전트 작업 성공 분류

이 분류는 에이전트 멀티턴 작업 성공 측정항목(multi_turn_task_success_v1)과 함께 사용됩니다. 할루시네이션, 안내 준수성, 도구 호출, 도구 출력 처리, 도구 품질 전반의 높은 수준의 에이전트 동작 실패를 다룹니다.

카테고리 손실 패턴 설명
할루시네이션 작업 할루시네이션 에이전트가 필요한 도구 호출을 실행하지 않고 작업을 완료했다고 주장합니다.
누락된 정보 할루시네이션 에이전트가 사용자 쿼리 또는 도구 출력에 없는 세부정보 (예: 값, 사실, 날짜)를 만들어냅니다.
도구 또는 기능 할루시네이션 에이전트가 보유하지 않은 도구 또는 기능을 보유하고 있다고 주장합니다.
안내 준수성 제약조건 위반 에이전트가 작업을 수행하지만 명시적인 사용자 제약조건 (예: 형식 규칙 또는 부정적 제약조건)을 위반합니다.
무의미한 작업 (언더펀팅) 에이전트가 사용 가능한 도구로 작업을 수행할 수 없다고 말하는 대신 관련 없는 작업을 수행합니다.
실행 미완료 에이전트가 작업을 부분적으로 완료하지만 너무 일찍 중지하거나 명시적으로 요청된 단계에 대해 불필요한 권한을 요청합니다.
오버펀팅 에이전트가 실제로 보유하고 있는 도구 또는 기능 이 부족하다고 주장하며 작업을 거부합니다.
도구 호출 잘못된 도구 선택 에이전트가 사용 가능한 옵션 중에서 잘못된 도구를 선택합니다.
의미상 잘못된 도구 매개변수 도구 호출은 구문적으로 유효하지만 매개변수 값에 논리적 또는 의미적 오류가 포함되어 있습니다.
구문적으로 잘못된 도구 호출 도구 호출에 구문 오류, 필수 매개변수 누락 또는 잘못된 인수 값이 있습니다.
도구 출력 처리 잘못된 도구 출력 처리 에이전트가 유효한 도구 출력을 수신하지만 정보를 부정확하게 추출, 처리 또는 해석합니다.
도구 품질 도구 출력 부족 도구가 성공적으로 실행되지만 에이전트가 진행하는 데 필요한 데이터가 부족하거나 누락되어 반환됩니다.
도구 실패 도구가 인증 실패, 시간 초과 또는 내부 오류와 같은 인프라 문제로 인해 실패합니다.

도구 사용 품질 분류

이 분류는 에이전트 멀티턴 도구 사용 품질 측정항목(multi_turn_tool_use_quality_v1)과 함께 사용됩니다. 특히 도구 호출 정확성과 도구 응답 처리에 중점을 둡니다.

카테고리 손실 패턴 설명
할루시네이션 매개변수 값 할루시네이션 에이전트가 사용자가 제공하지 않았거나 컨텍스트에서 파생될 수 없는 매개변수의 특정 값을 만들어냅니다.
도구 할루시네이션 에이전트가 정의된 도구 모음에 없는 함수를 호출하려고 시도합니다.
도구 호출 매개변수 설정 실패 에이전트가 사용자 제약조건을 충족하는 데 필요한 매개변수를 생략하여 의도하지 않은 값으로 기본 설정합니다.
잘못된 매개변수 데이터 유형 에이전트가 매개변수에 잘못된 데이터 유형의 값을 제공합니다 (예: 정수가 필요한 경우 문자열).
잘못된 매개변수 매핑 에이전트가 잘못된 매개변수에 값을 할당합니다 (예: 시작 날짜와 종료 날짜를 바꾸는 경우).
잘못된 매개변수 값 에이전트가 논리적으로 또는 사실적으로 잘못된 파라미터 값을 제공하거나 필요한 데이터 변환을 적용하지 못합니다.
잘못된 도구 선택 에이전트가 사용 가능한 도구 모음에서 잘못된 함수를 선택합니다.
잘못된 도구 호출 구문 에이전트가 파싱 또는 실행을 방지하는 구문 오류가 있는 함수 호출을 생성합니다.
존재하지 않는 매개변수 에이전트가 도구의 서명에 정의되지 않은 매개변수 인수를 포함합니다.
필수 도구 호출 생략 에이전트가 직접 대답하거나 복합 요청의 일부를 건너뛰거나 필수 단계를 건너뛰어 필요한 함수를 실행하지 못합니다.
언더펀팅 에이전트가 자연어로 대답해야 할 때 (예: 설명을 요청하거나 범위 외 요청을 거부하는 경우) 도구 호출을 강제합니다.
도구 응답 관련성 없는 도구 응답 도구가 성공적으로 실행되지만 사용자의 특정 쿼리와 관련이 없는 데이터를 반환합니다.
도구 오류 도구가 외부 문제 (예: API 서비스 중단 또는 잘못된 권한)로 인해 명시적 오류 또는 실패 상태를 반환합니다.

다음 워크플로를 사용하여 평가 실패를 체계적으로 분류합니다.

  1. 요약 측정항목으로 시작 하여 평가 데이터 세트에서 점수가 가장 낮은 측정항목을 식별합니다.
  2. 케이스별 결과로 드릴다운 하여 실패한 특정 평가 케이스를 찾습니다.
  3. 실패 클러스터 생성 하여 실패 전반의 시스템 손실 패턴을 식별합니다.
  4. 트레이스로 드릴다운 하여 실패가 발생한 정확한 턴 또는 도구 호출을 찾습니다. 콘솔에서 Agent Platform > 에이전트 > 배포 로 이동하여 에이전트를 선택하고 트레이스 탭을 엽니다. 트레이스를 선택하여 전체 대화 기록과 모델 입력, 도구 호출, 응답의 정확한 시퀀스를 확인합니다.
  5. 근본 원인 식별 - 손실 패턴 카테고리를 사용하여 문제가 프롬프트 문제인지, 도구 구성 문제인지, 데이터 문제인지 확인합니다.
  6. 에이전트의 시스템 안내, 도구 정의 또는 퓨샷 예시에 타겟 수정사항 적용 합니다.
  7. 평가를 다시 실행 하고 점수를 비교하여 개선사항을 확인합니다.