카테고리:: :doc:`/sql-reference/functions-table`(Cortex Agents)

GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL)¶

Cortex Agent 평가 실행에서 단일 추적 레코드를 검색합니다.

전체 Cortex Agent 평가에서 단일 레코드를 검사하려면 이 함수를 호출합니다. 자세한 내용은 Cortex Agent 평가 섹션을 참조하십시오.

참고 항목:: EXECUTE_AI_EVALUATION , GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL) , GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL)

구문¶

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

인자¶

database: 에이전트가 포함된 데이터베이스의 이름입니다.
schema: 에이전트가 포함된 스키마의 이름입니다.
agent_name: 레코드를 검색할 에이전트의 이름입니다.
agent_type: 문자열 상수 ``CORTEX AGENT``입니다. 이 값은 대/소문자를 구분하지 않습니다.
record_id: 검색할 레코드 식별자입니다.

반환¶

다음 열이 있는 요청된 추적에 대한 정보가 포함된 테이블입니다.


열	데이터 타입	설명
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 출력을 평가하는 데 사용되는 기준값 정보입니다.
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에 의해 생성된 출력 토큰의 수입니다. `guard_tokens`: 이 메트릭 평가 호출을 위해 Cortex Guard에서 사용한 토큰 수입니다. `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이 호출된 횟수를 계산합니다.

액세스 제어 요구 사항¶

이 작업을 실행하는 데 사용되는 역할 에는 최소한 다음 권한 이 있어야 합니다.


권한	오브젝트	참고
CORTEX_USER	데이터베이스 역할
USAGE	Cortex Agent
MONITOR	Cortex Agent

스키마의 오브젝트에 대한 작업을 수행하려면 상위 데이터베이스에 대한 하나 이상의 권한과 상위 스키마에 대한 하나 이상의 권한이 필요합니다.

지정된 권한 세트로 사용자 지정 역할을 만드는 방법에 대한 지침은 사용자 지정 역할 만들기 섹션을 참조하십시오.

보안 오브젝트 에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여에 대한 일반적인 정보는 액세스 제어의 개요 섹션을 참조하십시오.

Cortex Agent 평가에 필요한 전체 액세스 제어 권한은 :ref:`Cortex Agent 평가 – 액세스 제어 요구 사항 <label-agent_evaluation_access_control>`을 참조하세요.

예¶

다음 예제에서는 eval_db.eval_schema 스키마에 저장된 ``evaluated_agent``라는 에이전트의 레코드 ``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'
));