GET_AI_EVALUATION_DATA

GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL)

GET_AI_EVALUATION_DATA는 Cortex Agent 또는 External Agent 애플리케이션(External Agent 명령 참고)의 실행(run)에 대한 평가 데이터를 가져오는 표(table) 함수예요. 평가 실행 동안 기록된 모든 추적(trace)을 조회하려면 이 함수를 호출해요. Cortex Agent 평가에 대한 자세한 내용은 Cortex Agent evaluations를, AI Observability 애플리케이션은 AI_OBSERVABILITY_EVENTS 테이블을 참고해요.

출처: Snowflake SQL Reference

본문

카테고리: Table 함수 (Cortex Agents)

구문 (Syntax)

SNOWFLAKE.LOCAL.GET_AI_EVALUATION_DATA( <database> , <schema> , <agent_name> , <agent_type>, <run_name> )

인자 (Arguments)

<database> — 에이전트가 들어 있는 데이터베이스 이름이에요.

<schema> — 에이전트가 들어 있는 스키마 이름이에요.

<agent_name> — 레코드를 가져올 에이전트의 이름이에요.

<agent_type> — 에이전트 타입 문자열이에요. Cortex Agent에는 CORTEX AGENT, External Agent 객체에는 EXTERNAL AGENT를 사용해요. 이 값은 대소문자를 구분하지 않아요.

<run_name> — 전체 평가 데이터를 가져올 실행의 이름이에요.

반환값 (Returns)

지정한 평가에 대한 정보를 담은 테이블을 반환하며, 열은 다음과 같아요. (평가 결과 테이블 형식)

열	데이터 타입	설명
RECORD_ID	VARCHAR	이 평가 레코드에 대해 Snowflake가 할당한 고유 식별자.
INPUT_ID	VARCHAR	이 평가 입력에 대해 Snowflake가 할당한 고유 식별자.
REQUEST_ID	VARCHAR	이 요청에 대해 Snowflake가 할당한 고유 식별자.
TIMESTAMP	TIMESTAMP_TZ	요청이 이루어진 시각(UTC).
DURATION_MS	INT	에이전트가 응답을 반환하는 데 걸린 시간(밀리초).
INPUT	VARCHAR	이 평가 레코드의 입력으로 사용된 쿼리 문자열.
OUTPUT	VARCHAR	이 평가 레코드에 대해 Cortex Agent가 반환한 응답.
ERROR	VARCHAR	요청 중 발생한 오류에 대한 정보.
GROUND_TRUTH	VARCHAR	이 레코드의 Cortex Agent 출력을 평가하는 데 사용된 정답(ground truth) 정보. 데이터셋의 ground truth 열에 있는 JSON을 문자열로 직렬화한 값을 담아요. 커스텀 메트릭의 {{ground_truth}}가 이 값과 어떻게 관련되는지는 항목 아래의 주석을 참고해요.
METRIC_NAME	VARCHAR	이 레코드에 대해 평가된 메트릭 이름.
EVAL_AGG_SCORE	NUMBER	이 레코드에 할당된 평가 점수.
METRIC_TYPE	VARCHAR	평가되는 메트릭 타입. 내장 메트릭이면 system, 커스텀 메트릭이면 custom.
METRIC_STATUS	VARIANT	이 레코드에 대한 에이전트의 HTTP 응답 정보를 담은 맵으로, 다음 키를 가져요: status(응답의 HTTP 상태 코드), message(상태 응답으로 보낸 HTTP 메시지).
METRIC_CALLS	ARRAY	계산된 메트릭 대한 정보를 담은 VARIANT 값 배열. 각 배열 항목은 메트릭의 기준, 메트릭 점수 설명, 메타데이터를 담아요. 각 항목의 키는 다음과 같아요: criteria(LLM judge가 응답 정확도를 평가하는 데 사용한 기준), explanation(점수가 할당된 이유에 대한 설명), full_metadata(LLM judge가 이 메트릭을 처리한 방식에 대한 메타데이터·정보를 담은 VARIANT. 이 맵의 키는 completion_tokens, normalized_score, original_score, prompt_tokens, total_tokens를 포함해요).
TOTAL_INPUT_TOKENS	INT	입력 쿼리를 처리하는 데 사용된 총 토큰 수.
TOTAL_OUTPUT_TOKENS	INT	Cortex Agent가 생성한 총 출력 토큰 수.
LLM_CALL_COUNT	INT	에이전트 또는 평가 judge가 어떤 LLM을 호출한 총 횟수.

접근 제어 요구 사항 (Access control requirements)

이 작업을 실행하는 데 사용되는 역할은 최소한 다음 권한을 가져야 해요:

권한	객체	주석
CORTEX_USER	데이터베이스 역할
USAGE	Cortex Agent 또는 External Agent	agent_name으로 식별되는 객체에 필요. EXTERNAL AGENT의 경우 External Agent에 대한 USAGE만 있으면 이 함수를 호출하기에 충분해요(MONITOR는 적용되지 않아요).
MONITOR	Cortex Agent	agent_type이 CORTEX AGENT일 때 agent_name으로 식별되는 Cortex Agent에 필요. agent_type이 EXTERNAL AGENT이면 적용되지 않아요.

스키마의 객체를 조작하려면 상위 데이터베이스에 대한 권한이 하나 이상, 상위 스키마에 대한 권한이 하나 이상 있어야 해요.

지정된 권한 집합으로 커스텀 역할을 만드는 방법은 커스텀 역할 만들기를 참고해요.

보호 가능한 객체(securable objects)에 대한 SQL 작업 시 역할과 권한 부여에 관한 일반 정보는 접근 제어 개요를 참고해요.

agent_type이 EXTERNAL AGENT일 때는 이 함수를 호출하는 데 그 객체에 대한 USAGE만 필요해요. External Agent의 OWNERSHIP은 ALTER EXTERNAL AGENT 또는 DROP EXTERNAL AGENT로 객체를 수정·제거할 때 필요해요.

Cortex Agent 평가에 필요한 전체 접근 제어 권한은 Cortex Agent evaluations: access control requirements를, External Agent 객체는 AI_OBSERVABILITY_EVENTS 테이블을 참고해요.

예시 (Examples)

다음 예시는 스키마 eval_db.eval_schema에 저장된 evaluated_agent라는 에이전트에 대해, run-1이라는 실행의 전체 평가 세부 정보를 보여줘요:

SELECT * FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_EVALUATION_DATA(
  'eval_db',
  'eval_schema',
  'evaluated_agent',
  'CORTEX AGENT',
  'run-1')
);

GET_AI_EVALUATION_DATA