Cortex Agentの評価¶

Cortexコード¶

評価用データセットの作成を:doc:`/user-guide/cortex-code/cortex-code`に支援してもらうには、Cortex Code ``cortex-agent``スキルの``dataset-curation``サブスキルを使用します。Cortex Codeスキルについて詳しくは、:ref:`Cortex Code CLI - Skills<label-extensibility_skills>`を参照してください。

データセットの形式¶

評価用データセットの作成に使用されるテーブルには、クエリを表すVARCHAR型の入力クエリ列と、期待されるエージェントの動作の説明を含むVARIANT型の出力列があります。この単一の出力列は、LLM判定機能によってグラウンドトゥルースとして使用されます。

出力列の値には、``ground_truth_output``という1つのキーがあります。このキーの値は、回答の正確性の評価で使用されます。LLM判定機能はグラウンドトゥルースをプロンプトに含めることで、エージェントの出力を評価します。

JSONデータセットをSnowflakeテーブルに取り込むには、PARSE_JSON SQL関数を使用します。次の例では、評価データセットに使用する新しいテーブル``agent_evaluation_data``を作成し、グラウンドトゥルースが``The temperature was 14 degrees Celsius in San Francisco on August 2nd, 2019.``である入力クエリ``What was the temperature 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コード¶

:doc:`/user-guide/cortex-code/cortex-code`に評価を実行させるには、Cortex Code ``cortex-agent``スキルの``evaluate-cortex-agent``サブスキルを使用します。Cortex Codeスキルについて詳しくは、:ref:`Cortex Code CLI - Skills<label-extensibility_skills>`を参照してください。

Snowsight¶

Cortex Agentの評価を開始するには、次の手順を実行します。

1. Snowsight にサインインします。

2. ナビゲーションメニューで AI & ML » Agents を選択します。

3. 評価を実施するエージェントを選択します。

4. Evaluations タブを選択します。

5. New evaluation run を選択します。

   :ui:`New evaluation run`モーダルが開きます。

6. :ui:`Name`フィールドに、評価の名前を指定します。この名前は、評価されるエージェントに対して一意である必要があります。

7. オプション：:ui:`Description`フィールドに、評価に関するコメントを指定します。

8. Next を選択します。

   これにより、:ui:`Select dataset`モーダルに進みます。

9. エージェントの評価に使用するデータセットを選択します。Existing dataset または Create new dataset を選択できます。

   既存のデータセットを使用するには：

   1. :ui:`Database and schema`リストから、データセットを含むデータベースとスキーマを選択します。

   2. :ui:`Select dataset`リストから、データセットを選択します。

   新しいデータセットを作成するには：

   1. :ui:`Source table - Database and schema`リストから、データセットにインポートするテーブルを含むデータベースとスキーマを選択します。

   2. :ui:`Select source table`リストから、ソーステーブルを選択します。

   3. :ui:`New dataset location - Database and schema`リストから、新しいデータセットを配置するデータベースとスキーマを選択します。

   4. :ui:`Dataset name`フィールドに、データセット名を入力します。この名前は、選択したスキーマ内のスキーマレベルのオブジェクトの中で一意である必要があります。

10. Next を選択します。

    これにより、:ui:`Select metrics`モーダルに進みます。

11. :ui:`Input query`リストから、入力クエリを含むデータセットの列を選択します。

12. 各:ui:`System metrics`について、評価に含めたいメトリックのトグルをアクティブに変更します。評価のグラウンドトゥルースを含むデータセットの列を選択します。

13. （オプション）カスタム評価を行うには、:ui:`Custom metrics`をオンに切り替えます。

    1. カスタム評価構成が保存されているステージを含むデータベースとスキーマを選択します。

    2. カスタム評価構成が保存されているステージを選択します。

    3. カスタム評価用のYAML構成ファイルを選択します。

       注釈

       |sf-web-interface|では、カスタム評価定義のみがYAML構成からロードされます。YAMLファイルの残りの部分は引き続き有効である必要があります。評価YAMLの仕様については、:ref:`label-cortex_agent_evaluation_yaml_spec`を参照してください。

    4. 各カスタムメトリックについて、評価に含める場合はトグルをアクティブに変更します。この評価のグラウンドトゥルースを含むデータセットの列を選択します。

14. :ui:`Create`を選択して評価を作成し、評価プロセスを開始します。

いつでも、:ui:`Cancel`を選択して評価の作成をキャンセルしたり、:ui:`Prev`を選択して前のモーダルに戻ったりすることができます。

SQL¶

SQLを使用して評価を開始または評価に関する情報を取得するには、:doc:`/sql-reference/functions/execute_ai_evaluation`関数を使用します。この関数には次の必須引数があります。

• evaluation_job:'START'または'STATUS'の文字列値。

• run_parameters:キー``run_name``を含み、値が実行の名前であるSQL OBJECT。

• config_file_path: 実行構成のYAMLファイルを指すステージファイルパス。このパスを署名付きURLにすることはできません。評価YAMLの仕様については、:ref:`label-cortex_agent_evaluation_yaml_spec`を参照してください。

評価を開始するには、``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 Observability Runs <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コード¶

Cortex Codeは、``cortex-agent``スキルの2つのサブスキルを提供します。評価を検査し、構成やデータ内の問題を見つけるには、``investigate-cortex-agent-evals``サブスキルを使用します。完了した評価から結果を取得し、エージェントのパフォーマンスを向上させるには、``optimize-cortex-agent``サブスキルを使用します。

Snowsight¶

|sf-web-interface|のエージェントの:ui:`Evaluations`タブには、各評価実行の概要とその集計結果が表示されます。

|sf-web-interface|で評価結果を表示するには：

1. Snowsight にサインインします。

2. ナビゲーションメニューで AI & ML » Agents を選択します。

3. 評価を実施するエージェントを選択します。

4. Evaluations タブを選択します。

SQL¶

生の評価詳細を取得するには、:doc:`/sql-reference/functions/get_ai_evaluation_data-snowflake-local`関数を使用します。この関数には次の必須引数があります。

• database:エージェントを含むデータベース。

• schema:エージェントを含むスキーマ。

• agent_name:エージェントの名前。

• agent_type:文字列定数'CORTEX AGENT'。この値では大文字と小文字が区別されません。

• run_name:取得する評価実行の名前。

この関数は、:ref:`label-cortex_agent_evaluations_results_format`で説明されているイベントデータのテーブルを返します。次の例は、スキーマ``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')
);

単一記録のクエリトレース¶

評価トレースから単一記録にアクセスするには、:doc:`/sql-reference/functions/get_ai_record_trace-snowflake-local`関数を使用します。この関数には次の必須引数があります。

• database:エージェントを含むデータベース。

• schema:エージェントを含むスキーマ。

• agent_name:エージェントの名前。

• agent_type:文字列定数'CORTEX AGENT'。この値では大文字と小文字が区別されません。

• record_id:フィルター対象の記録ID。

この関数は、:ref:`label-cortex_agent_evaluations_results_format`で説明されているイベントデータのテーブルを返します。次の例では、``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'
));

実行のクエリ評価エラーと警告¶

評価実行中に発生した警告やエラーのログにアクセスするには、:doc:`/sql-reference/functions/get_ai_observability_logs-snowflake-local`関数を使用します。この関数には次の必須引数があります。

• database:エージェントを含むデータベース。

• schema:エージェントを含むスキーマ。

• agent_name:エージェントの名前。

• agent_type:文字列定数'CORTEX AGENT'。この値では大文字と小文字が区別されません。

この関数は、:ref:`label-cortex_agent_evaluations_results_format`で説明されているイベントデータのテーブルを返します。次の例では、``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``列に必要な構造については、:ref:`label-agent_evaluation_dataset_format`を参照してください。``dataset``値のキーは次のとおりです。

• dataset_type:文字列定数"CORTEX AGENT"。この値では大文字と小文字が区別されません。

• table_name:データセットのコンテンツに使用するテーブルの完全修飾名。

• dataset_name:作成されるデータセットの名前。

• column_mapping:必須の評価入力列``query_text``および出力列``ground_truth``の、データセットの作成元となるテーブルの列へのマッピング。

生成されたデータセットは、構築元のテーブルと同じデータベースおよびスキーマに格納されます。

次のデータセット定義の例は、``user_question``を入力として使用し、``expected_outcome``でグランドトゥルースを定義して、``evals_db.evals_schema.evaluation_data``テーブルから作成された``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;

ナビゲーションメニューで:ui: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;

:doc:`ワークスペース</user-guide/ui-snowsight/workspaces>`でYAMLを作成した場合は、アクティブなワークスペースからステージにYAMLをコピーできます。次の例では、ファイル``evaluation_config.yaml``をワークスペースからステージ``evals_db.evals_schema.evaluation_config``にコピーします。

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