GET_AI_RECORD_TRACE

GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL)

Cortex Agent 또는 AI_OBSERVABILITY_EVENTS에 트레이스를 저장하는 External Agent 애플리케이션(External Agent commands 참고)의 평가 실행에서 단일 트레이스 레코드를 가져와요.

완전한 평가에서 단일 레코드를 검사하려면 이 함수를 호출해요. 자세한 내용은 Cortex Agent evaluations 문서와 AI_OBSERVABILITY_EVENTS 테이블 문서를 참고하세요.

출처: Snowflake SQL Reference - GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL)

본문

구문

SNOWFLAKE.LOCAL.GET_AI_RECORD_TRACE( <database> , <schema> , <agent_name> , <agent_type> , <record_id> )

인자

database

  • 에이전트를 포함한 데이터베이스 이름이에요.

schema

  • 에이전트를 포함한 스키마 이름이에요.

agent_name

  • 레코드를 가져올 에이전트의 이름이에요.

agent_type

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

record_id

  • 가져올 레코드 식별자예요.

반환 값

요청한 트레이스에 대한 정보를 담은 테이블을 다음 열과 함께 반환해요.

Column Data type Description
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}}가 이 값과 어떤 관계인지는 Evaluation results table format 아래의 참고를 볼 것.
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 판정자가 응답 정확도를 평가하는 데 사용한 기준. explanation: 점수가 할당된 이유에 대한 설명. full_metadata: 이 메트릭이 LLM 판정자에 의해 처리된 것에 대한 메타데이터와 정보를 담은 VARIANT 값. 이 맵의 키는 다음과 같음: completion_tokens: 이 메트릭 평가 호출 동안 LLM이 생성한 출력 토큰 수. normalized_score: 원래 평가 점수를 [0.0, 1.0] 범위로 정규화한 값(소수점 둘째 자리에서 반올림). original_score: 레코드에 대해 이 메트릭 평가가 할당한 원래 점수. prompt_tokens: LLM 판정자에게 제공된 프롬프트가 차지한 토큰 수. total_tokens: LLM 판정자가 이 계산에 사용한 총 토큰 수.
TOTAL_INPUT_TOKENS INT 입력 쿼리를 처리하는 데 사용된 총 토큰 수.
TOTAL_OUTPUT_TOKENS INT Cortex Agent가 생성한 출력 토큰 수.
LLM_CALL_COUNT INT 에이전트 또는 평가 판정자가 LLM을 호출한 횟수.

접근 제어 요구 사항

이 작업을 실행하는 역할은 최소한 다음 권한을 가져야 해요.

Privilege Object Notes
CORTEX_USER Database role
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일 때는 적용되지 않음.

스키마 안의 객체를 작동하려면 상위 데이터베이스에 대한 권한이 하나 이상, 상위 스키마에 대한 권한이 하나 이상 필요해요.

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

보호 가능 객체에 대해 SQL 작업을 수행하기 위한 역할·권한 부여에 대한 일반 정보는 접근 제어 개요 문서를 참고하세요.

agent_type이 EXTERNAL AGENT일 때는 이 함수를 호출하는 데 해당 객체에 대한 USAGE만 필요해요. ALTER EXTERNAL AGENT 또는 DROP EXTERNAL AGENT로 객체를 수정하거나 제거하려면 External Agent에 대한 OWNERSHIP이 필요해요.

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

예시

다음 예시는 evaluated_agent라는 이름의 에이전트를 eval_db.eval_schema 스키마에 저장하고, record 9346efc3-5dd6-4038-9b1a-72ca3d3b768c에 대한 트레이스를 보여줘요.

SELECT * FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_RECORD_TRACE(
  'eval_db',
  'eval_schema',
  'evaluated_agent',
  'CORTEX AGENT',
  '9346efc3-5dd6-4038-9b1a-72ca3d3b768c'
));

더 알아보기