Cortex Agent-Evaluierungen¶

Cortex Code¶

Damit Cortex Code Sie bei der Erstellung eines Datensets für Ihre Evaluierung unterstützt, verwenden Sie die untergeordnete dataset-curation-Fähigkeit der Cortex Code cortex-agent-Fähigkeit. Weitere Informationen zu Cortex Code-Fähigkeiten finden Sie unter Cortex Code CLI-Fähigkeiten.

Datenset-Format¶

Die Tabelle, die zum Erstellen eines Datensets für die Auswertung verwendet wird, hat eine Eingabeabfragespalte vom Typ VARCHAR, welche Ihre Abfrage darstellt, sowie eine Ausgabespalte vom Typ VARIANT, die eine Beschreibung des erwarteten Verhaltens des Agenten enthält. Diese einzelne Ausgabespalte wird vom LLM-Beurteiler (Judge) als grundlegende Wahrheit verwendet.

Values in the output column often include the key ground_truth_output. The value of that key is used by the answer correctness system metric. The value is most powerful when its accuracy is not dependent on relative time (i.e. last week versus January 2026), and when the ground truth clearly explains the criteria for success, such as specific criteria for data accuracy. LLM judges compare that ground truth to the full streamed reply the user would see. This includes all spans from LLM planning, tool calls, LLM response generation, or chart generation.

You can store any valid JSON object in this column. Custom metrics can reference the entire JSON through the {{ground_truth}} placeholder in the metric prompt (the serialized content of your ground truth VARIANT). That behavior is not limited to a particular key such as ground_truth_output. For example, you can use an object like {"ground_truth_output":"...","custom_a":"...","custom_b":"..."} and read those fields in a custom LLM judge via {{ground_truth}}. System metrics expect specific JSON shapes (for example, answer correctness relies on ground_truth_output). Choose your JSON structure based on which system and custom metrics you enable.

Um eine JSON-Datenset in eine Snowflake-Tabelle zu übertragen, verwenden Sie die SQL-Funktion PARSE_JSON. Das folgende Beispiel erstellt eine neue Tabelle agent_evaluation_data, die für ein Evaluierungs-Datenset verwendet werden soll, und fügt eine Zeile für die Eingabeabfrage What was the temperature in San Francisco on August 2nd 2019? mit der Ground Truth von``The temperature was 14 degrees Celsius in San Francisco on August 2nd, 2019.`` ein.

CREATE OR REPLACE TABLE agent_evaluation_data (
    input_query VARCHAR,
    ground_truth VARIANT
);

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."
      }
    ');

Daten, die Sie über die Spalte ground_truth angeben, die nicht von einer ausgewählten Kennzahl verwendet wird, werden ignoriert. Wenn Sie einen Evaluierungslauf nur mit referenzlosen Kennzahlen ausführen, können Sie die Ausgabespalte leer lassen.

Wenn Sie Ihre erste Evaluierung durchführen, haben Sie die Möglichkeit, ein neues Datenset aus einer bestehenden Tabelle zu erstellen.

Create a dataset from a Snowflake table (SQL)¶

To create an evaluation dataset with SQL, call SYSTEM$CREATE_EVALUATION_DATASET.

Cortex Code¶

Wenn Sie mit Cortex Code eine Evaluierung ausführen möchten, verwenden Sie die untergeordnete Fähigkeit evaluate-cortex-agent der Cortex Code cortex-agent-Fähigkeit. Weitere Informationen zu Cortex Code-Fähigkeiten finden Sie unter Cortex Code CLI-Fähigkeiten.

Snowsight¶

Beginnen Sie Ihre Evaluierung eines Cortex Agent, indem Sie Folgendes tun:

1. Melden Sie sich bei Snowsight an.

2. Wählen Sie im Navigationsmenü die Option AI & ML » Agents aus.

3. Wählen Sie den Agenten aus, für den Sie eine Evaluierung durchführen möchten.

4. Wählen Sie die Registerkarte Evaluations aus.

5. Wählen Sie New evaluation run aus.

   Das Modalfenster New evaluation run wird geöffnet.

6. Geben Sie im Feld Name einen Namen für Ihre Evaluierung ein. Dieser Name sollte für den zu bewertenden Agenten eindeutig sein.

7. Optional: Geben Sie im Feld Description Kommentare zur Evaluierung ein.

8. Wählen Sie Next aus.

   Dies führt zum Modalfenster Select dataset.

9. Wählen Sie das Datenset aus, das zur Evaluierung Ihres Agenten verwendet wird. Sie können Existing dataset oder Create new dataset auswählen.

   So verwenden Sie ein vorhandenes Datenset:

   1. Wählen Sie in der Liste Database and schema die Datenbank und das Schema aus, die Ihr Datenset enthalten.

   2. Wählen Sie aus der Liste Select dataset Ihr Datenset aus.

   So erstellen Sie ein neues Datenset:

   1. Wählen Sie in der Liste Source table - Database and schema die Datenbank und das Schema aus, die die Tabelle enthalten, die Sie in ein Datenset importieren möchten.

   2. Wählen Sie aus der Liste Select source table Ihre Quelltabelle aus.

   3. Wählen Sie über die Liste New dataset location - Database and schema die Datenbank und das Schema aus, in denen Ihr neues Datenset gespeichert werden soll.

   4. Geben Sie im Feld Dataset name den Namen Ihres Datensets ein. Dieser Name muss unter den Objekten auf Schemaebene in dem von Ihnen ausgewählten Schema eindeutig sein.

10. Wählen Sie Next aus.

    Dies führt zum Modalfenster Select metrics.

11. Wählen Sie in der Liste Input query die Spalte Ihres Datensets aus, die die Eingabeabfragen enthält.

12. Für jede der System metrics setzen Sie den Umschalter für jede Kennzahl, die Sie in Ihre Evaluierung einbeziehen möchten, auf aktiv. Wählen Sie die Spalte Ihres Datensets aus, die die grundlegende Wahrheit (Ground Truth) für Ihre Evaluierung enthält.

13. (Optional) Um eine kundenspezifische Evaluierung durchzuführen, verwenden Sie den Umschalter Custom metrics.

    1. Wählen Sie die Datenbank und das Schema aus, die den Stagingbereich enthalten, in dem Ihre kundenspezifische Evaluierungskonfiguration gespeichert ist.

    2. Wählen Sie den Stagingbereich aus, in dem Ihre kundenspezifische Evaluierungskonfiguration gespeichert ist.

    3. Wählen Sie die YAML-Konfigurationsdatei für Ihre kundenspezifische Evaluierung aus.

       Bemerkung

       In der Snowsight werden nur die kundenspezifischen Evaluierungsdefinitionen aus Ihrer YAML-Konfiguration geladen. Der Rest der YAML-Datei muss trotzdem gültig sein. Informationen zur YAML-Spezifikation der Evaluierung finden Sie unter YAML-Spezifikation der Agentenevaluierung.

    4. Setzen Sie den Umschalter für jede kundenspezifische Kennzahl auf aktiv, wenn Sie diese in Ihre Evaluierung aufnehmen möchten. Wählen Sie die Spalte Ihres Datensets aus, die die grundlegende Wahrheit (Ground Truth) für diese Evaluierung enthält.

14. Wählen Sie Create aus, um die Evaluierung zu erstellen und den Evaluierungsprozess zu starten.

Sie können jederzeit Cancel verwenden, um die Evaluierungserstellung abzubrechen, oder Sie wählen Prev aus, um zum vorherigen Modalfenster zurückzukehren.

SQL¶

Zum Starten oder Abrufen von Informationen zu einer Evaluierung mit SQL verwenden Sie die EXECUTE_AI_EVALUATION-Funktion. Diese Funktion hat die folgenden erforderlichen Argumente:

• evaluation_job: Ein Zeichenfolgenwert mit ‚START‘ oder ‚STATUS‘.

• run_parameters: Ein SQL OBJECT, das den Schlüssel run_name mit einem Wert mit dem Namen Ihrer Evaluierung enthält.

• config_file_path: Ein Stagingbereichs-Dateipfad, der auf Ihre YAML-Datei mit der Ausführungskonfiguration verweist. Dieser Pfad kann keine signierte URL sein. Informationen zur YAML-Spezifikation der Evaluierung finden Sie unter YAML-Spezifikation der Agentenevaluierung.

Verwenden Sie den evaluation_job-Wert ‚START‘, um eine Evaluierung zu starten. Im folgenden Beispiel wird eine Ausführung namens run-1 unter Verwendung der Konfiguration der Agenten-Evaluierung von``@eval_db.eval_schema.metrics/agent_evaluation_config.yaml`` gestartet:

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

Nach dem Start einer Ausführung können Sie den Fortschritt mit dem evaluation_job-Wert ‚STATUS‘ abfragen. Dieser Aufruf gibt eine Tabelle in dem Format zurück, das für AI-Beobachtbarkeitsausführungen verwendet wird. Im folgenden Beispiel wird der Status der mit dem vorherigen Beispiel gestarteten Agentenevaluierung abgefragt:

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

Cortex Code¶

Cortex Code bietet zwei untergeordnete Fähigkeiten der cortex-agent-Fähigkeit. Verwenden Sie die untergeordnete Fähigkeit investigate-cortex-agent-evals, um Evaluierungen zu prüfen und Probleme in Ihrer Konfiguration oder Ihren Daten zu finden. Verwenden Sie die untergeordnete Fähigkeit optimize-cortex-agent, um die Ergebnisse abgeschlossener Evaluierungen zu nutzen und die Leistung Ihres Agenten zu verbessern.

Snowsight¶

Die Registerkarte Evaluations für einen Agenten in der Snowsight gibt Ihnen einen Überblick über jeden Evaluierungslauf und seine zusammenfassenden Ergebnisse.

So zeigen Sie Evaluierungsergebnisse in Snowsight an:

1. Melden Sie sich bei Snowsight an.

2. Wählen Sie im Navigationsmenü die Option AI & ML » Agents aus.

3. Wählen Sie den Agenten aus, für den Sie eine Evaluierung durchführen möchten.

4. Wählen Sie die Registerkarte Evaluations aus.

SQL¶

Um die Rohdetails der Evaluierung abzurufen, verwenden Sie die Funktion GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL). Diese Funktion hat die folgenden erforderlichen Argumente:

• database: Datenbank, die den Agenten enthält.

• schema: Schema, das den Agenten enthält.

• agent_name: Der Name des Agenten.

• agent_type: CORTEX AGENT or EXTERNAL AGENT. This value is case-insensitive.

• run_name: Der Name des abzurufenden Evaluierungslaufs.

Diese Funktion gibt eine Tabelle mit Ereignisdaten zurück, wie in Format der Tabelle mit den Evaluierungsergebnissen beschrieben. Das folgende Beispiel zeigt die vollständigen Evaluierungsdetails für eine Ausführung namens run-1 an, wobei der Agent evaluated_agent heißt, der im Schema eval_db.eval_schema gespeichert ist:

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

Abfrageablaufverfolgungen für einen einzelnen Datensatz¶

Um auf einen einzelnen Datensatz aus einer Evaluierungsablaufverfolgung zuzugreifen, verwenden Sie die Funktion GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL). Diese Funktion hat die folgenden erforderlichen Argumente:

• database: Datenbank, die den Agenten enthält.

• schema: Schema, das den Agenten enthält.

• agent_name: Der Name des Agenten.

• agent_type: CORTEX AGENT or EXTERNAL AGENT. This value is case-insensitive.

• record_id: Datensatz-ID, nach der gefiltert wird.

Diese Funktion gibt eine Tabelle mit Ereignisdaten zurück, wie in Format der Tabelle mit den Evaluierungsergebnissen beschrieben. Das folgende Beispiel zeigt die Ablaufverfolgung für den Datensatz 9346efc3-5dd6-4038-9b1a-72ca3d3b768c, wobei der Agent evaluated_agent heißt und im Schema eval_db.eval_schema gespeichert ist:

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

Abfrageevaluierungsfehler und Warnungen für eine Ausführung¶

Um auf Protokolle für Warnungen und Fehler zuzugreifen, die während eines Evaluierungslaufs aufgetreten sind, verwenden Sie die Funktion GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL). Diese Funktion hat die folgenden erforderlichen Argumente:

• database: Datenbank, die den Agenten enthält.

• schema: Schema, das den Agenten enthält.

• agent_name: Der Name des Agenten.

• agent_type: CORTEX AGENT or EXTERNAL AGENT. This value is case-insensitive.

Diese Funktion gibt eine Tabelle mit Ereignisdaten zurück, wie in Format der Tabelle mit den Evaluierungsergebnissen beschrieben. Im folgenden Beispiel wird auf Fehler und Warnungen für eine Ausführung namens run-1 geprüft, wo der Agent evaluated_agent heißt und im Schema eval_db.eval_schema gespeichert ist:

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';

Datenset-Definition¶

Der dataset-Wert definiert ein neues Datenset aus bestehenden Tabellendaten, die Spalten für die Eingabeabfrage und die Ground Truth zuordnen. Informationen zu der für Ihre Spalte ground_truth erforderliche Struktur finden Sie unter Datenset-Format. Die Schlüssel für den dataset-Wert sind:

• dataset_type: Die Zeichenfolgenkonstante ‚CORTEX AGENT‘. Dieser Wert unterscheidet nicht zwischen Groß- und Kleinschreibung.

• table_name: Der vollqualifizierte Name der Tabelle, die für den Inhalt des Datasets verwendet werden soll.

• dataset_name: Der Name des erstellten Datensets.

• column_mapping: Die Zuordnung der erforderlichen Eingabespalte query_text und der Ausgabespalte ground_truth für die Evaluierung zu Spalten der Tabelle, aus der das Datenset erstellt werden soll.

Das resultierende Dataset wird in derselben Datenbank und demselben Schema gespeichert wie die Tabelle, aus der es erstellt wurde.

Die folgende Beispiel-Datensetdefinition zeigt ein Datenset mit dem Namen evaluation_input, das aus der Tabelle evals_db.evals_schema.evaluation_data unter Verwendung von user_question als Eingabe und expected_outcome zum Definieren der grundlegenden Wahrheit erstellt wurde:

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"

Agentenkonfiguration¶

Der evaluation-Wert legt die Konfiguration für den Agenten fest, mit der eine Evaluierung durchgeführt werden soll. Die Schlüssel für den evaluation-Wert sind:

• agent_params: Ein Wörterbuch, das den Agenten beschreibt, für den die Evaluierung durchgeführt werden soll. Dieser Wert verwendet folgende Schlüssel:

  • agent_name: Der Name des zu bewertenden Agenten.

  • agent_type: Die Zeichenfolgenkonstante ‚CORTEX AGENT‘. Dieser Wert unterscheidet nicht zwischen Groß- und Kleinschreibung.

• (Optional) run_params: Metadaten zur Identifizierung dieses Evaluierungslaufs. Dieser Wert verwendet folgende Schlüssel:

  • (Optional) label: Das Label für diese Evaluierung.

  • (Optional) description: Eine detaillierte Beschreibung der Evaluierung.

• source_metadata: Ein Wörterbuch, welches das für die Evaluierung verwendete Datenset beschreibt. Dieser Wert verwendet folgende Schlüssel:

  • type: The string constant dataset. This value is case-sensitive.

  • dataset_name: Der Name des zu verwendenden Datensets.

Das folgende Beispiel für die Konfiguration eines Agenten führt einen Agenten namens evaluated_agent mit der Bezeichnung Basic evaluation unter Verwendung des Datensets evaluation_input aus:

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

Auswahl der Kennzahlen¶

Der metrics-Wert ist eine Sequenz von zu bewertenden Kennzahlen, einschließlich Ihrer eigenen kundenspezifischen Kennzahldefinitionen. Die akzeptierten Werte für vordefinierte Kennzahlen sind:

• answer_correctness: Measure how closely the expected ground truth answer for a given input query matches the actual response streamed from the agent.

• logical_consistency: Messen der Konsistenz zwischen Agentenanweisungen, Planung und Tool-Aufrufen. Diese Kennzahl ist referenzlos und verwendet kein Datenset.

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?

Vollständige Beispielkonfiguration¶

Die Kombination aller vorherigen Beispielabschnitte ergibt eine vollständige Konfiguration der Agentenevaluierung:

# 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"

metrics:
  # 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?

Hochladen der Konfiguration in einen Stagingbereich¶

Die Konfiguration der Agentenevaluierung muss ein bestimmtes Dateiformat haben, damit Snowflake sie analysieren kann. Der folgende Ausschnitt zeigt die Erstellung der erforderlichen yaml_file_format für das Schema evals_db.evals_schema und erstellt dann den Stagingbereich evaluation_config, um eine Agentenkonfiguration hochzuladen:

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;

Laden Sie Ihre Konfiguration über in einen erstellten Stagingbereich über die Snowsight hoch. Wählen Sie dazu im Navigationsmenü Ingestion » Add Data und dann Load files into a Stage aus. Sie können auch den SQL PUT-Befehl zum Hochladen einer lokalen YAML-Datei verwenden. Das folgende Beispiel zeigt das Kopieren der lokalen Datei /Users/dev/evaluation_config.yaml in den Stagingbereich evals_db.evals_schema.evaluation_config:

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

Wenn Sie Ihre YAML in einem :doc:` Arbeitsbereich </user-guide/ui-snowsight/workspaces>` erstellt haben, können Sie diese aus Ihrem aktiven Arbeitsbereich in einen Stagingbereich kopieren. Im folgenden Beispiel wird die Datei evaluation_config.yaml von Ihrem Arbeitsbereich in den Stagingbereich evals_db.evals_schema.evaluation_config kopiert:

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