Kategorien:: Tabellenfunktionen (Cortex Agents)

GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL)¶

Abrufen eines einzelnen Ablaufverfolgungsdatensatzes aus einem Evaluierungslauf für einen Cortex Agenten oder für eine externe Agentenanwendung, die Ablaufverfolgungen in AI_OBSERVABILITY_EVENTS speichert (siehe:doc:/sql-reference/commands-external-agent).

Rufen Sie diese Funktion auf, wenn Sie einen einzelnen Datensatz aus einer vollständigen Evaluierung untersuchen möchten. Weitere Informationen dazu finden Sie unter Cortex Agent-Evaluierungen und Observability-Daten.

Siehe auch:: EXECUTE_AI_EVALUATION , GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL) , GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL) , GET_AI_OBSERVABILITY_EVENTS (SNOWFLAKE.LOCAL)

Syntax¶

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

Argumente¶

database: Name der Datenbank, die den Agenten enthält.
schema: Name des Schemas, das den Agenten enthält.
agent_name: Name des Agenten, für den ein Datensatz abgerufen werden soll.
agent_type: Die Zeichenfolge für den Agententyp. Verwenden Sie CORTEX AGENT für einen Cortex Agent oder EXTERNAL AGENT für ein External Agent-Objekt. Dieser Wert unterscheidet nicht zwischen Groß- und Kleinschreibung.
record_id: Der Bezeichner des abzurufenden Datensatzes.

Rückgabewerte¶

Eine Tabelle mit Informationen für die angeforderte Ablaufverfolgung mit den folgenden Spalten:


Spalte	Datentyp	Beschreibung
RECORD_ID	VARCHAR	Der von Snowflake zugewiesene eindeutige Bezeichner für diesen Bewertungsdatensatz.
INPUT_ID	VARCHAR	Der von Snowflake zugewiesene eindeutige Bezeichner für diese Bewertungseingabe.
REQUEST_ID	VARCHAR	Der von Snowflake zugewiesene eindeutige Bezeichner für diese Anforderung.
TIMESTAMP	TIMESTAMP_TZ	Die Uhrzeit (in UTC), zu der die Anforderung gestellt wurde.
DURATION_MS	INT	Die Zeit in Millisekunden, die der Agent benötigte, um eine Antwort zurückzugeben.
INPUT	VARCHAR	Die Abfragezeichenfolge, die als Eingabe für diesen Bewertungsdatensatz verwendet wurde.
OUTPUT	VARCHAR	Die vom Cortex Agent für diesen Bewertungsdatensatz zurückgegebene Antwort.
ERROR	VARCHAR	Informationen über Fehler, die während der Anforderung aufgetreten sind.
GROUND_TRUTH	VARCHAR	Die Ground Truth-Informationen, die zur Bewertung der Cortex Agent-Ausgabe dieses Datensatzes verwendet wurden. Diese Spalte enthält die JSON-Werte aus der Ground-Truth-Spalte Ihres Datensatzes, serialisiert als Zeichenfolge. Wie sich `{{ground_truth}}` in benutzerdefinierten Metriken auf diesen Wert bezieht, sehen Sie unter Format der Tabelle mit den Evaluierungsergebnissen.
METRIC_NAME	VARCHAR	Der Name der für diesen Datensatz bewerteten Kennzahl.
EVAL_AGG_SCORE	NUMBER	Die für diesen Datensatz zugewiesene Bewertungskennzahl.
METRIC_TYPE	VARCHAR	Der Typ der zu bewertenden Kennzahl. Für integrierte Kennzahlen ist der Wert `system`. Für kundenspezifische Kennzahlen ist der Wert `custom`.
METRIC_STATUS	VARIANT	Eine Zuordnung mit Informationen über die HTTP-Antwort des Agenten für diesen Datensatz mit den folgenden Schlüsseln: `status`: Der HTTP-Statuscode der Antwort. `message`: Die HTTP-Meldung, die in der Statusantwort gesendet wird.
METRIC_CALLS	ARRAY	Ein Array von VARIANT-Werten, die Informationen über die berechnete Kennzahl enthalten. Jeder Array-Eintrag enthält die Kriterien der Kennzahl, eine Erklärung der Kennzahl-Bewertung und Metadaten. Die Schlüssel der einzelnen Einträge sind: `criteria`: Die von einem LLM-Beurteilenden verwendeten Kriterien, um die Korrektheit der Antwort zu bewerten. `explanation`: Eine Erklärung, warum die Punktzahl vergeben wurde. `full_metadata`: Ein VARIANT-Wert, der Metadaten und Informationen über die Verarbeitung dieser Kennzahl durch den LLM-Beurteilenden enthält. Die Schlüssel dieser Zuordnung umfassen: `completion_tokens`: Die Anzahl der vom LLM generierten Ausgabe-Token für diesen Aufruf der Kennzahlbewertung. `normalized_score`: Die ursprüngliche Bewertungskennzahl, der auf den Bereich [0,0, 1,0] normalisiert und auf zwei Dezimalstellen gerundet wurde. `original_score`: Die ursprüngliche Punktzahl, die durch diese Bewertung der Kennzahl für den Datensatz zugewiesen wurde. `prompt_tokens`: Die Anzahl der Token, die von der Eingabeaufforderung aufgenommen und dem LLM-Beurteilenden bereitgestellt wurden. `total_tokens`: Die Gesamtzahl der vom LLM-Beurteilenden verwendeten Token für diese Berechnung.
TOTAL_INPUT_TOKENS	INT	Die Gesamtzahl der Token, die zur Verarbeitung der Eingabeabfrage verwendet wurden.
TOTAL_OUTPUT_TOKENS	INT	Die Gesamtzahl der vom Cortex Agent erzeugten Ausgabe-Token.
LLM_CALL_COUNT	INT	Zählt, wie oft LLM aufgerufen wurde, entweder vom Agenten oder einem Beurteilenden für die Bewertung.

Anforderungen an die Zugriffssteuerung¶

Eine Rolle, die zur Ausführung dieser Operation verwendet wird, muss mindestens die folgenden Berechtigungen haben:


Berechtigung	Objekt	Anmerkungen
CORTEX_USER	Datenbankrolle
USAGE	Cortex Agent oder External Agent	Erforderlich für das Objekt, das von `agent_name` identifiziert wird. Für `EXTERNAL AGENT` auf dem External Agent ist USAGE ausreichend, um diese Funktion aufzurufen (MONITOR wird hier nicht angewendet).
MONITOR	Cortex Agent	Erforderlich auf dem Cortex Agent, der durch `agent_name` identifiziert wird, wenn `agent_type` den Wert `CORTEX AGENT` hat. Gilt nicht, wenn:samp:`{agent_type}` `EXTERNAL AGENT` ist.

Für das Ausführen von Operationen für ein Objekt in einem Schema ist mindestens eine Berechtigung für die übergeordnete Datenbank und mindestens eine Berechtigung für das übergeordnete Schema erforderlich.

Eine Anleitung zum Erstellen einer kundenspezifischen Rolle mit einer bestimmten Gruppe von Berechtigungen finden Sie unter Erstellen von kundenspezifischen Rollen.

Allgemeine Informationen zu Rollen und Berechtigungen zur Durchführung von SQL-Aktionen auf sicherungsfähigen Objekten finden Sie unter Übersicht zur Zugriffssteuerung.

Wenn agent_type ist EXTERNAL AGENT wird nur USAGE in diesem Objekt benötigt, um die Funktion aufzurufen. OWNERSHIP auf dem External Agent ist erforderlich, um das Objekt zu ändern oder mit ALTER EXTERNAL AGENT oder DROP EXTERNAL AGENT zu entfernen.

Die vollständigen Berechtigungen für die Zugangssteuerung, die für Cortex Agent-Evaluierungen erforderlich sind, finden Sie unter Cortex Agent-Evaluierungen – Anforderungen für Zugangssteuerung. Informationen zu External Agent-Objekten finden Sie unter Observability-Daten.

Beispiele¶

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