Cortex Agent 평가¶

Cortex Code¶

/user-guide/cortex-code/cortex-code`가 평가를 위한 데이터 세트 생성을 지원하도록 하려면 Cortex Code ``cortex-agent``의 ``dataset-curation` 하위 스킬을 사용합니다. Cortex Code 스킬에 대한 자세한 내용은 :ref:`Cortex Code CLI - 스킬 <label-extensibility_skills>`을 참조하세요.

데이터 세트 형식¶

평가를 위한 데이터 세트를 생성하는 데 사용되는 테이블에는 쿼리를 나타내는 VARCHAR 유형의 쿼리 열 및 예상되는 에이전트 동작에 대한 설명이 포함된 VARIANT 유형의 출력 열이 있습니다. 이 단일 출력 열은 LLM 판단에서 기준값으로 사용됩니다.

출력 열의 값에는 하나의 ground_truth_output 키가 있습니다. 이 키의 값은 답변의 정확성 평가에 사용됩니다. LLM 판단은 기준값을 통해 프롬프트에 포함하여 에이전트의 출력을 평가합니다.

JSON 데이터 세트를 Snowflake 테이블에 가져오려면 PARSE_JSON SQL 함수를 사용합니다. 다음 예제에서는 평가 데이터 세트에 사용할 새 테이블 ``agent_evaluation_data``를 생성하고 입력 쿼리 ``What was the temperature in San Francisco on August 2nd 2019?``에 대한 기준값 ``The temperature was 14 degrees Celsius in San Francisco on August 2nd, 2019.``가 포함된 행을 삽입합니다.

CREATE OR REPLACE TABLE agent_evaluation_data (
    input_query VARCHAR
);

INSERT INTO agent_evaluation_data
  SELECT
    'What was the temperature in San Francisco on August 2nd 2019?',
    PARSE_JSON('
      {
        "ground_truth_output": "The temperature was 14 degrees Celsius in San Francisco on August 2nd, 2019.",
      }
    ');

선택한 메트릭에서 사용하지 않는 ground_truth 열에 제공한 데이터는 무시됩니다. 참조 없는 메트릭만 사용하여 평가 실행을 수행하는 경우 출력 열을 비워 둘 수 있습니다.

첫 번째 평가를 실행할 때 기존 테이블에서 새 데이터 세트를 생성할 수 있는 옵션이 제공됩니다.

Cortex Code¶

/user-guide/cortex-code/cortex-code`가 평가를 실행하도록 하려면 Cortex Code ``cortex-agent` 스킬의 evaluate-cortex-agent 하위 스킬을 사용합니다. Cortex Code 스킬에 대한 자세한 내용은 :ref:`Cortex Code CLI - 스킬 <label-extensibility_skills>`을 참조하세요.

Snowsight¶

다음을 수행하여 Cortex Agent 평가를 시작합니다.

1. Snowsight 에 로그인합니다.

2. 탐색 메뉴에서 AI & ML » Agents 를 선택합니다.

3. 평가를 수행할 에이전트를 선택합니다.

4. Evaluations 탭을 선택합니다.

5. New evaluation run 을 선택합니다.

   New evaluation run 모달이 열립니다.

6. Name 필드에 평가의 이름을 입력합니다. 이 이름은 평가 중인 에이전트에 대해 고유해야 합니다.

7. 선택 사항: 개인 키가 암호화된 경우 암호 구문을 설정하려면 개인 키 암호 구문에 대한 환경 변수를 설정합니다. Description 필드에 평가에 대한 설명을 입력합니다.

8. Next 을 선택합니다.

   이 작업은 Select dataset 모달로 진행됩니다.

9. 에이전트를 평가하는 데 사용되는 데이터 세트를 선택합니다. Existing dataset 또는 Create new dataset 중에서 선택할 수 있습니다.

   기존 데이터 세트를 사용하려면 다음을 수행합니다.

   1. Database and schema 목록에서 데이터 세트가 포함된 데이터베이스와 스키마를 선택합니다.

   2. Select dataset 목록에서 데이터 세트를 선택합니다.

   새 데이터 세트를 생성하려면 다음을 수행합니다.

   1. Source table - Database and schema 목록에서 데이터 세트로 가져올 테이블이 포함된 데이터베이스와 스키마를 선택합니다.

   2. Select source table 목록에서 소스 테이블을 선택합니다.

   3. New dataset location - Database and schema 목록에서 새 데이터 세트를 배치할 데이터베이스와 스키마를 선택합니다.

   4. Dataset name 필드에 데이터 세트 이름을 입력합니다. 이 이름은 선택한 스키마의 스키마 수준 오브젝트 간에 고유해야 합니다.

10. Next 을 선택합니다.

    이 작업은 Select metrics 모달로 진행됩니다.

11. Input query 목록에서 입력 쿼리가 포함된 데이터 세트의 열을 선택합니다.

12. 각 :ui:`System metrics`에 대해 평가에 포함하려는 모든 메트릭의 토글을 활성으로 변경합니다. 평가를 위한 기준값이 포함된 데이터 세트의 열을 선택합니다.

13. (선택 사항) 사용자 지정 평가를 수행하려면 :ui:`Custom metrics`로 전환합니다.

    1. 사용자 지정 평가 구성이 저장된 스테이지가 포함된 데이터베이스와 스키마를 선택합니다.

    2. 사용자 지정 평가 구성이 저장된 스테이지를 선택합니다.

    3. 사용자 지정 평가를 위한 YAML 구성 파일을 선택합니다.

       참고

       Snowsight 에서는 사용자 지정 평가 정의만 YAML 구성에서 로드됩니다. 나머지 YAML 파일은 계속 유효해야 합니다. YAML 사양 평가의 경우 에이전트 평가 YAML 사양 섹션을 참조하세요.

    4. 각 사용자 지정 메트릭의 경우 평가에 포함하려면 토글을 활성으로 변경합니다. 이 평가에 대한 기준값이 포함된 데이터 세트의 열을 선택합니다.

14. :ui:`Create`를 선택하여 평가를 생성하고 평가 프로세스를 시작합니다.

언제든지 :ui:`Cancel`을 선택하여 평가 생성을 취소하거나 :ui:`Prev`를 선택하여 이전 모달로 돌아갈 수 있습니다.

SQL¶

SQL을 사용하여 평가에 대한 정보를 시작하거나 검색하려면 EXECUTE_AI_EVALUATION 함수를 사용합니다. 이 함수에는 다음과 같은 필수 인자가 있습니다.

• evaluation_job: ‘START’ 또는 ‘STATUS’의 문자열 값입니다.

• run_parameters: 실행 이름 값이 있는 run_name 키가 포함된 SQL :ref:`OBJECT <label-data_type_object>`입니다.

• config_file_path: 실행 구성 YAML 파일을 가리키는 스테이지 파일 경로입니다. 이 경로는 서명된 URL일 수 없습니다. YAML 사양 평가의 경우 에이전트 평가 YAML 사양 섹션을 참조하세요.

evaluation_job 값 ‘START’를 사용하여 평가를 시작합니다. 다음 예제에서는 ``@eval_db.eval_schema.metrics/agent_evaluation_config.yaml``의 에이전트 평가 구성을 사용하여 ``run-1``이라는 실행을 시작합니다.

CALL EXECUTE_AI_EVALUATION(
  'START',
  OBJECT_CONSTRUCT('run_name', 'run-1'),
  '@eval_db.eval_schema.metrics/agent_evaluation_config.yaml'
);

실행이 시작된 후 evaluation_job 값 ‘STATUS’를 사용하여 해당 진행 상황을 쿼리할 수 있습니다. 이 호출은 :ref:`AI 가시성 실행 <label-ai_observability_runs>`에 사용되는 형식의 테이블을 반환합니다. 다음 예제에서는 이전 예제에서 시작된 에이전트 평가의 상태를 쿼리합니다.

CALL EXECUTE_AI_EVALUATION(
  'STATUS',
  OBJECT_CONSTRUCT('run_name', 'run-1'),
  '@eval_db.eval_schema.metrics/agent_evaluation_config.yaml'
);

Cortex Code¶

Cortex Code는 cortex-agent 스킬의 두 가지 하위 스킬을 제공합니다. investigate-cortex-agent-evals 하위 스킬을 사용하여 평가를 검사하고 구성 또는 데이터의 문제를 찾습니다. optimize-cortex-agent 하위 스킬을 사용하여 완료된 평가에서 결과를 가져오고 에이전트의 성능을 개선합니다.

Snowsight¶

Snowsight 의 에이전트에 대한 Evaluations 탭에서는 모든 평가 실행과 해당 요약 결과에 대한 개요를 제공합니다.

Snowsight 에서 평가 결과를 확인하려면 다음을 수행합니다.

1. Snowsight 에 로그인합니다.

2. 탐색 메뉴에서 AI & ML » Agents 를 선택합니다.

3. 평가를 수행할 에이전트를 선택합니다.

4. Evaluations 탭을 선택합니다.

SQL¶

원시 평가 세부 정보를 검색하려면 GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL) 함수를 사용합니다. 이 함수에는 다음과 같은 필수 인자가 있습니다.

• database: 에이전트가 포함된 데이터베이스입니다.

• schema: 에이전트가 포함된 스키마입니다.

• agent_name: 에이전트의 이름입니다.

• agent_type: 문자열 상수 ‘CORTEX AGENT’입니다. 이 값은 대/소문자를 구분하지 않습니다.

• run_name: 검색할 평가 실행의 이름입니다.

이 함수는 평가 결과 테이블 형식 에 설명된 이벤트 데이터의 테이블을 반환합니다. 다음 예제에서는 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_RECORD_TRACE (SNOWFLAKE.LOCAL) 함수를 사용합니다. 이 함수에는 다음과 같은 필수 인자가 있습니다.

• database: 에이전트가 포함된 데이터베이스입니다.

• schema: 에이전트가 포함된 스키마입니다.

• agent_name: 에이전트의 이름입니다.

• agent_type: 문자열 상수 ‘CORTEX AGENT’입니다. 이 값은 대/소문자를 구분하지 않습니다.

• record_id: 필터링할 레코드 ID입니다.

이 함수는 평가 결과 테이블 형식 에 설명된 이벤트 데이터의 테이블을 반환합니다. 다음 예제에서는 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'
));

실행에 대한 쿼리 평가 오류 및 경고¶

평가 실행 중에 발생한 경고 및 오류에 대한 로그에 액세스하려면 GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL) 함수를 사용합니다. 이 함수에는 다음과 같은 필수 인자가 있습니다.

• database: 에이전트가 포함된 데이터베이스입니다.

• schema: 에이전트가 포함된 스키마입니다.

• agent_name: 에이전트의 이름입니다.

• agent_type: 문자열 상수 ‘CORTEX AGENT’입니다. 이 값은 대/소문자를 구분하지 않습니다.

이 함수는 평가 결과 테이블 형식 에 설명된 이벤트 데이터의 테이블을 반환합니다. 다음 예제에서는 eval_db.eval_schema 스키마에 저장된 evaluated_agent``라는 에이전트의 ``run-1 실행에 대한 오류와 경고를 확인합니다.

SELECT * FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_OBSERVABILITY_LOGS(
  'eval_db',
  'eval_schema',
  'evaluated_agent',
  'CORTEX AGENT')
)
  WHERE TRUE
  AND (record:"severity_text"='ERROR' or record:"severity_text"='WARN')
  AND record_attributes:"snow.ai.observability.run.name"='run-1';

데이터 세트 정의¶

dataset 값은 기존 테이블 데이터에서 새 데이터 세트를 정의하며, 입력 쿼리 및 기준값에 대한 열을 매핑합니다. ground_truth 열에 필요한 구조의 경우 데이터 세트 형식 섹션을 참조하세요. dataset 값의 키는 다음과 같습니다.

• dataset_type: 문자열 상수 “CORTEX AGENT”입니다. 이 값은 대/소문자를 구분하지 않습니다.

• table_name: 데이터 세트의 내용에 사용할 테이블의 정규화된 이름입니다.

• dataset_name: 생성된 데이터 세트의 이름입니다.

• column_mapping: 데이터 세트를 생성할 테이블의 열에 필요한 평가 입력 열 query_text 및 출력 열 ``ground_truth``의 매핑입니다.

결과 데이터 세트는 생성된 테이블과 동일한 데이터베이스 및 스키마에 저장됩니다.

다음의 데이터 세트 정의 예제에서는 evals_db.evals_schema.evaluation_data 테이블에서 ``user_question``을 입력으로 사용하고 ``expected_outcome``을 기준값으로 정의하여 생성된 ``evaluation_input``이라는 데이터 세트를 보여줍니다.

dataset:
 dataset_type: "CORTEX AGENT"
 table_name: "evals_db.evals_schema.evaluation_data"
 dataset_name: "evaluation_input"
 column_mapping:
   query_text: "user_question"
   ground_truth: "expected_outcome"

에이전트 구성¶

evaluation 값은 평가를 수행할 에이전트의 구성을 설정합니다. evaluation 값의 키는 다음과 같습니다.

• agent_params: 평가를 수행할 에이전트를 설명하는 사전입니다. 이 값은 다음 키를 사용합니다.

  • agent_name: 평가할 에이전트의 이름입니다.

  • agent_type: 문자열 상수 “CORTEX AGENT”입니다. 이 값은 대/소문자를 구분하지 않습니다.

• (선택 사항) run_params: 이 평가 실행을 식별하기 위한 메타데이터입니다. 이 값은 다음 키를 사용합니다.

  • (선택 사항) label: 이 평가의 레이블입니다.

  • (선택 사항) description: 평가에 대한 자세한 설명입니다.

• source_metadata: 평가에 사용되는 데이터 세트를 설명하는 사전입니다. 이 값은 다음 키를 사용합니다.

  • type: 문자열 상수 “DATASET”입니다. 이 값은 대/소문자를 구분하지 않습니다.

  • dataset_name: 사용할 데이터 세트의 이름입니다.

다음의 에이전트 구성 예제에서는 evaluation_input 데이터 세트를 사용하여 Basic evaluation 레이블이 지정된 ``evaluated_agent``라는 에이전트를 실행합니다.

evaluation:
 agent_params:
   agent_name: "evaluated_agent"
   agent_type: "CORTEX AGENT"
  run_params:
   label: "Basic evaluation"
  source_metadata:
   type: "DATASET"
   dataset_name: "evaluation_input"

메트릭 선택¶

metrics 값은 자체 사용자 지정 메트릭 정의를 포함하여 평가할 메트릭의 시퀀스입니다. 미리 정의된 메트릭에 허용되는 값은 다음과 같습니다.

• answer_correctness: 기준값 출력에 대한 에이전트의 응답 정확성을 측정합니다.

• logical_consistency: 에이전트 지침, 계획 및 도구 호출 전반에 걸쳐 일관성을 측정합니다. 이 메트릭은 참조 없는 메트릭이며, 데이터 세트를 사용하지 않습니다.

metrics:
  # Built-in metrics
  - "answer_correctness"
  - "logical_consistency"
  # Custom metric with prompt
  - name: "relevance"
    score_ranges:
      min_score: [1, 3]
      median_score: [4, 6]
      max_score: [7, 10]
    prompt: |
      Evaluate the relevance of the agent's response to the user's query.
      Rate from 1-10 where:
      1 = Completely irrelevant
      4 = Somewhat irrelevant
      6 = Neutral
      8 = Mostly relevant
      10 = Highly relevant and on-topic

      You can compare the {{output}} with the {{ground_truth}} to help you understand if the contents are relevant or not

      Consider:
      - Does the response address the user's question?
      - Is the information provided appropriate to the context?
      - Are there any tangential or off-topic elements?

전체 예제 구성¶

이전의 모든 예제 섹션을 결합하면 전체 에이전트 평가 구성이 제공됩니다.

# Optional: Create dataset before running evaluation
dataset:
  dataset_type: "CORTEX AGENT"
  table_name: "EVALS_DB.EVALS_SCHEMA.EVALUATION_DATA"
  dataset_name: "EVALUATION_INPUT"
  column_mapping:
    query_text: "user_question"
    ground_truth: "expected_outcome"

# Evaluation task configuration
evaluation:
 agent_params:
   agent_name: "evaluated_agent"
   agent_type: "CORTEX AGENT"
  run_params:
   label: "Basic evaluation"
  source_metadata:
   type: "DATASET"
   dataset_name: "EVALUATION_INPUT"

  # Built-in metrics (simple strings)
  - "answer_correctness"
  - "logical_consistency"

  # Custom metric definition
  - name: "relevance"
    score_ranges:
      min_score: [1, 3]
      median_score: [4, 6]
      max_score: [7, 10]
    prompt: |
      Evaluate the relevance of the agent's response to the user's query.
      Rate from 1-10 where:
      1 = Completely irrelevant
      4 = Somewhat irrelevant
      6 = Neutral
      8 = Mostly relevant
      10 = Highly relevant and on-topic

      You can compare the {{output}} with the {{ground_truth}} to help you understand if the contents are relevant or not

      Consider:
      - Does the response address the user's question?
      - Is the information provided appropriate to the context?
      - Are there any tangential or off-topic elements?

스테이지에 구성 업로드¶

에이전트 평가 구성에는 Snowflake가 구문 분석할 수 있는 특정 파일 형식이 있어야 합니다. 다음 스니펫은 evals_db.evals_schema 스키마에 필요한 yaml_file_format``을 생성한 후 ``evaluation_config 스테이지를 생성하여 에이전트 구성을 업로드하는 방법을 보여줍니다.

CREATE OR REPLACE FILE FORMAT evals_db.evals_schema.yaml_file_format
  TYPE = 'CSV'
  FIELD_DELIMITER = NONE
  RECORD_DELIMITER = '\n'
  SKIP_HEADER = 0
  FIELD_OPTIONALLY_ENCLOSED_BY = NONE
  ESCAPE_UNENCLOSED_FIELD = NONE;

CREATE OR REPLACE STAGE evals_db.evals_schema.evaluation_config
  FILE_FORMAT = evals_db.evals_schema.yaml_file_format;

탐색 메뉴로 이동하여 Ingestion » Add Data`를 선택하고 :ui:`Load files into a Stage`를 선택해 |sf-web-interface| 를 통해 생성된 스테이지에 구성을 업로드합니다. SQL :doc:/sql-reference/sql/put` 명령을 사용하여 로컬 YAML 파일에 업로드할 수도 있습니다. 다음 예제에서는 로컬 파일 /Users/dev/evaluation_config.yaml``을 ``evals_db.evals_schema.evaluation_config 스테이지에 복사하는 방법을 보여줍니다.

PUT file:///Users/dev/evaluation_config.yaml @evals_db.evals_schema.evaluation_config
  AUTO_COMPRESS='false'
  OVERWRITE=TRUE;

작업 공간 </user-guide/ui-snowsight/workspaces>`에서 YAML 을 생성하는 경우, 활성 작업 공간에서 스테이지로 복사할 수 있습니다. 다음 예제에서는 작업 공간에서 ``evals_db.evals_schema.evaluation_config` 스테이지로 evaluation_config.yaml 파일을 복사합니다.

COPY FILES INTO @evals_db.evals_schema.evaluation_config
  FROM 'snow://workspace/USER$.PUBLIC.DEFAULT$/versions/live'
  FILES=('custom_metric_config.yaml');