Cortex Analyst REST API

Utilisez cette API pour répondre aux questions sur vos données avec des requêtes en langage naturel.

Envoyer un message

POST /api/v2/cortex/analyst/message

Génère une requête SQL pour la question donnée à l’aide d’un modèle sémantique ou d’une vue sémantique fournie dans la requête. Un ou plusieurs modèles peuvent être spécifiés ; lorsque plusieurs modèles sont spécifiés, Cortex Analyst choisit le plus approprié. Vous pouvez avoir des conversations à plusieurs tours où vous pouvez poser des questions de suivi qui s’appuient sur les requêtes précédentes. Pour plus d’informations, voir Conversation à plusieurs tours en Cortex Analyst.

La requête comprend une question de l’utilisateur ; la réponse comprend la question de l’utilisateur et la réponse de l’analyste. Chaque message d’une réponse peut avoir plusieurs blocs de contenu de types différents. Trois valeurs actuellement prises en charge pour le champ type de l’objet de contenu sont : text, suggestions, et sql.

Les réponses peuvent être envoyées en une seule fois dès le traitement terminé, ou à mesure qu’elles sont générées.

En-têtes de requête

En-tête

Description

Authorization

(Obligatoire) Jeton d’autorisation. Pour plus d’informations, voir Authentification auprès du serveur.

Content-Type

(Obligatoire) application/json

X-Snowflake-Authorization-Token-Type

(Facultatif) Type de jeton d’autorisation. La valeur par défaut est OAuth. Pour plus d’informations, voir Authentification auprès du serveur.

Corps de la requête

Dans le corps de la requête :

  • Définissez le dernier champ messages[].role sur le rôle de l’orateur, qui doit être user.

  • Incluez la question de l’utilisateur dans l’objet content. Dans cet objet :

    • Définissez type sur text.

    • Définissez text sur la question de l’utilisateur.

  • Incluez l’un des éléments suivants :

    • La spécification du modèle sémantique dans YAML.

    • Le chemin vers le fichier YAML qui contient la spécification du modèle sémantique. Ce fichier doit se trouver sur une zone de préparation.

    • Le nom de la vue sémantique.

Le tableau suivant décrit les champs que vous pouvez définir dans le corps de la requête :

Champ

Description

messages[].role

(Obligatoire) Le rôle de l’entité qui crée le message. Actuellement, seulement user est pris en charge.

Type : string:enum

Exemple : user

messages[].content[]

(Obligatoire) L’objet de contenu qui fait partie d’un message.

Type : objet

Exemple :

{
  "type": "text",
  "text":  "Which company had the most revenue?"
}
Copy

messages[].content[].type

(Obligatoire) Le type de contenu. Actuellement, seulement text est pris en charge.

Type : string:enum

Exemple : text

messages[].content[].text

(Obligatoire) La question de l’utilisateur.

Type : chaîne

Exemple : Which company had the most revenue?

semantic_model_file

Chemin vers le fichier YAML du modèle sémantique. Doit être une URL de zone de préparation entièrement qualifiée, y compris la base de données et le schéma.

Pour spécifier plusieurs modèles sémantiques, utilisez le champ semantic_models.

Si vous souhaitez fournir la spécification YAML directement dans la requête, définissez le champ semantic_model sur la spécification YAML pour le modèle sémantique.

Type : chaîne

Exemple : @my_db.my_schema.my_stage/my_semantic_model.yaml

semantic_model

Une chaîne contenant l’intégralité du modèle sémantique YAML.

Pour spécifier plusieurs modèles sémantiques, utilisez plutôt le champ semantic_models.

Si vous souhaitez plutôt pointer vers une spécification YAML dans un fichier, téléchargez le fichier sur une zone de préparation, et donnez au champ semantic_model_file le chemin d’accès au fichier.

Type : chaîne

semantic_models

Un tableau contenant des objets JSON, dont chacun contient un champ semantic_model_file ou semantic_view.

Ces champs ont la même sémantique que les champs de niveau supérieur semantic_model_file et semantic_view :

  • semantic_model_file spécifie un fichier YAML, stocké dans une zone de préparation, qui contient une définition de modèle sémantique. (Vous ne pouvez pas spécifier le YAML pour le modèle sémantique directement dans la requête à l’aide de ce formulaire.)

  • semantic_view spécifie le nom complet d’une vue sémantique. Par exemple :

    {
  /* ... */
  "semantic_models": [
    {"semantic_view": "my_db.my_sch.my_sem_view_1" },
    {"semantic_view": "my_db.my_sch.my_sem_view_2" }
  ]
  /* ... */
}
    Copy

Pour chaque requête, Cortex Analyst choisit dans la liste le modèle ou la vue le plus approprié.

Cette capacité simplifie les interactions de l’utilisateur avec Cortex Analyst. Vous n’avez pas besoin de choisir une source de données à interroger, ni de savoir quel modèle ou quelle vue sémantique utiliser pour chacune d’entre elles. Il vous suffit de spécifier l’ensemble de vos modèles ou de vos vues à chaque requête et de laisser Cortex Analyst déterminer lequel utiliser.

Type : tableau

Astuce

Cortex Analyst n’exige pas que vous spécifiiez plus d’un modèle ou d’une vue. Si vous spécifiez un seul modèle ou une seule vue, la requête est fonctionnellement équivalente à une requête contenant un champ de niveau supérieur semantic_model_file ou semantic_view.

L’avantage d’utiliser semantic_models pour les requêtes portant sur un seul modèle est que vous pouvez utiliser le même code client, quel que soit le nombre de modèles ou de vues.

semantic_view

Nom pleinement qualifié de la vue sémantique. Par exemple :

{
  /* ... */
  "semantic_view": "MY_DB.MY_SCHEMA.SEMANTIC_VIEW"
  /* ... */
}
Copy

Si le nom est sensible à la casse ou contient des caractères qui ne sont pas autorisés dans un identifiant sans guillemets, vous devez le placer entre guillemets doubles échappés par une barre oblique inverse. Par exemple, si le nom de la base de données, le nom du schéma et le nom de la vue comprennent des traits d’union (my-database.my-schema.my-semantic-view) :

{
  /* ... */
  "semantic_view": "\"my-database\".\"my-schema\".\"\"my-semantic-view\"\""
  /* ... */
}
Copy

Pour spécifier plusieurs vues sémantiques, utilisez le champ semantic_models.

Type : chaîne

stream

(Facultatif) Si la valeur est définie sur true, la réponse est transmise au client sous forme de flux à l’aide d’événements envoyés par le serveur au fur et à mesure qu’elle est générée (voir Réponse en flux). Dans le cas contraire, la réponse complète est renvoyée après que Cortex Analyst a entièrement traité la question de l’utilisateur.

Type : booléen

Important

Vous devez spécifier l’un des champs suivants dans le corps de la requête :

  • semantic_model_file

  • semantic_model

  • semantic_models

  • semantic_view

Exemple de spécification d’un modèle sémantique dans un fichier sur une zone de préparation

{
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "which company had the most revenue?"
                }
            ]
        }
    ],
    "semantic_model_file": "@my_db.my_schema.my_stage/my_semantic_model.yaml"
}
Copy

Exemple de spécification d’une vue sémantique

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "which company had the most revenue?"
        }
      ]
    }
  ],
  "semantic_view": "MY_DB.MY_SCH.MY_SEMANTIC_VIEW"
}
Copy

Réponse sans flux

Cette opération peut renvoyer les codes de réponse énumérés ci-dessous. La réponse a toujours la structure suivante. Actuellement, trois types de contenu sont pris en charge pour la réponse, text, suggestion, et sql. Les types de contenu suggestion et sql s’excluent mutuellement, de sorte que si la réponse contient un type de contenu sql, elle ne contiendra pas de type de contenu suggestion, et vice versa. Le type de contenu suggestion n’est inclus dans une réponse que si la question de l’utilisateur était ambiguë et Cortex Analyst ne pouvait pas retourner une instruction SQL pour cette requête.

Lorsque la requête contient un champ semantic_models, la réponse comprend un champ semantic_model_selection qui indique le modèle sémantique choisi pour la requête.

Pour garantir la compatibilité ascendante, assurez-vous que votre implémentation prend en compte le type de contenu et gère les types.

Code

Description

200

L’instruction a été exécutée avec succès.

Le corps de la réponse contient un objet message qui contient les champs suivants :

  • message : Messages de la conversation entre l’utilisateur et l’analyste.

  • message (objet) : Représente un message dans un Chat.

  • message.role (string:enum) : L’entité qui a produit le message. L’un des rôles suivants : user ou analyst.

  • message.content[] (objet) : L’objet de contenu qui fait partie d’un message.

  • message.content[].type (string:enum) : Le type de contenu du message. L’un des rôles suivants : text, suggestion ou sql.

  • message.content[].text (string) : Le texte du contenu. Renvoyé uniquement pour le type de contenu text.

  • message.content[].statement (string) : Une instruction SQL. Renvoyé uniquement pour le type de contenu sql.

  • message.content[].confidence (object) : Contient des informations relatives à la confiance. Renvoyé uniquement pour le type de contenu sql.

  • message.content[].confidence.verified_query_used (object) : Représente la requête vérifiée provenant du dépôt de requêtes vérifiées utilisé dans la génération de la réponse SQL. Si aucune requête vérifiée n’est utilisée, la valeur du champ est null.

  • message.content[].confidence.verified_query_used.name (string) : Le nom de la requête vérifiée utilisée, extrait du dépôt des requêtes vérifiées.

  • message.content[].confidence.verified_query_used.question (string) : La question à laquelle répond la requête vérifiée, extraite du dépôt de requêtes vérifiées.

  • message.content[].confidence.verified_query_used.sql (string) : L’instruction SQL de la requête vérifiée utilisée, extraite du dépôt de requêtes vérifiées.

  • message.content[].confidence.verified_query_used.verified_at (entier) : La représentation numérique de l’horodatage lorsque la requête est vérifiée, extraite du dépôt des requêtes vérifiées.

  • message.content[].confidence.verified_query_used.verified_by (string) : La personne qui a vérifié la requête, extraite du dépôt des requêtes vérifiées.

  • message.content[].suggestions (string) : Si le SQL ne peut pas être généré, une liste pour lesquelles le modèle sémantique peut générer du SQL. Renvoyé uniquement pour le type de contenu suggestion.

  • warnings : Liste des avertissements de l’analyste concernant la requête de l’utilisateur.

  • warnings[].message (string) : Contient une description détaillée d’un avertissement individuel.

  • response_metadata (objet) : Métadonnées contenant les détails de la génération de la réponse.

  • response_metadata.model_names : Liste des modèles utilisés pour générer la réponse.

  • response_metadata.cortex_search_retrieval (objet) : Entités résolues avec Cortex Search.

  • response_metadata.question_category (string) : Comment la question de la requête est catégorisée.

Par défaut, la réponse est renvoyée en une seule fois après que Cortex Analyst a entièrement traité la question de l’utilisateur. Voir Réponse en flux pour le format des réponses en mode flux.

{
    "request_id": "75d343ee-699c-483f-83a1-e314609fb563",
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "We interpreted your question as ..."
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table",
                "confidence": {
                    "verified_query_used": {
                        "name": "My verified query",
                        "question": "What was the total revenue?",
                        "sql": "SELECT * FROM table2",
                        "verified_at": 1714497970,
                        "verified_by": "Jane Doe"
                    }
                }
            }
        ]
    },
    "warnings": [
        {
            "message": "Table table1 has (30) columns, which exceeds the recommended maximum of 10"
        },
        {
            "message": "Table table2 has (40) columns, which exceeds the recommended maximum of 10"
        }
    ],
    "response_metadata": {
        "model_names": [
            "claude-3-5-sonnet"
        ],
        "cortex_search_retrieval": [
            {
                "service": "my_db.my_schema.my_search_service",
                "response_body": {
                    "results": [
                        {
                            "CUST_NAME": "customer1"
                        }
                    ],
                    "request_id": "request1"
                },
                "query": "'customer1'"
            }
        ],
        "question_category": "CLEAR_SQL"
    }
}
Copy

Réponse en flux

Le mode flux permet à votre client de recevoir les réponses au fur et à mesure qu’elles sont générées par Cortex Analyst, plutôt que d’attendre que la réponse soit entièrement générée. Cela améliore la réactivité perçue de votre application, en particulier pour les requêtes de longue durée, car les utilisateurs commencent à voir la sortie beaucoup plus tôt. Les réponses en flux fournissent également des informations de statut qui peuvent vous aider à comprendre où en est Cortex Analyst dans le processus de génération d’une réponse, ainsi que des avertissements qui peuvent vous aider à comprendre ce qui s’est passé lorsque Cortex Analyst ne fonctionne pas comme vous l’espériez.

Pour recevoir une réponse en flux, il convient d’attribuer la valeur true au champ stream dans le corps de la requête. Les réponses en flux utilisent les événements envoyés par le serveur.

Cortex Analyst envoie cinq types d’événements distincts dans une réponse en flux :

  • status : Fournit des mises à jour du statut du processus de génération SQL.

  • message.content.delta : Contient un élément de la réponse. Cet événement est envoyé plusieurs fois.

  • error : Indique que Cortex Analyst a rencontré une erreur et ne peut poursuivre le traitement de la requête. Aucun autre événement message.content.delta ne sera envoyé.

  • warnings : Contient les éventuels avertissements rencontrés lors du traitement. Les avertissements n’interrompent pas le traitement.

  • response_metadata : Envoyé à la fin d’une réponse pour afficher des données sur le traitement de la requête.

  • done : Envoyé pour indiquer que le traitement est terminé et qu’aucun autre événement message.content.delta ne sera envoyé.

Parmi ceux-ci, les événements message.content.delta sont les plus importants à comprendre, car ils contiennent le contenu de la réponse proprement dite. Chaque delta contient des jetons provenant d’un champ de la réponse complète. Chaque événement delta peut contenir entre un seul caractère et la totalité de la réponse, et ils peuvent être de longueurs différentes. Vous recevez ces jetons au fur et à mesure qu’ils sont générés ; c’est à vous de les assembler dans la réponse finale.

Important

Les événements de différentes réponses (même extrêmement similaires) peuvent varier. Il n’y a aucune garantie que les événements seront envoyés dans le même ordre ou avec le même contenu.

Exemple simple

Voici un échantillon de réponse sans flux pour une requête simple :

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "This is how we interpreted your question and this is how the sql is generated"
            },
            {
                "type": "sql",
                "statement": "SELECT * FROM table"
            }
        ]
    }
}
Copy

Voici maintenant une série possible d’événements de flux pour cette réponse (une autre série d’événements est également possible) :

event: status
data: { status: "interpreting_question" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: "This is how we interpreted your question"
}

event: status
data: { status: "generating_sql" }

event: status
data: { status: "validating_sql" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: " and this is how the sql is generated"
}

event: message.content.delta
data: {
  index: 1,
  type: "sql",
  statement_delta: "SELECT * FROM table"
}

event: status
data: { status: "done" }

Utilisez le champ index dans les réponses message.content.delta pour déterminer le champ de la réponse complète dont l’événement fait partie. Par exemple, ici, les deux premiers événements delta utilisent l’index 0, ce qui signifie qu’ils font partie du premier champ (élément 0) du tableau content de la réponse sans flux. De même, l’événement delta qui contient la réponse SQL utilise l’index 1.

Exemple avec suggestions

Cet exemple contient des suggestions de questions pour une question ambiguë. La réponse suivante est une réponse sans flux :

{
    "message": {
        "role": "analyst",
        "content": [
            {
                "type": "text",
                "text": "Your question is ambigous, here are some alternatives:"
            },
            {
                "type": "suggestions",
                "suggestions": [
                    "which company had the most revenue?",
                    "which company placed the most orders?"
                ]
            }
        ]
    }
}
Copy

Voici maintenant une série possible d’événements en flux qui constituent cette réponse :

event: status
data: { status: "interpreting_question" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: "Your question is ambigous,"
}

event: status
data: { status: "generating_suggestions" }

event: message.content.delta
data: {
  index: 0,
  type: "text",
  text_delta: " here are some alternatives:"
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 0,
    suggestion_delta: "which company had",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 0,
    suggestion_delta: " the most revenue?",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 1,
    suggestion_delta: "which company placed",
  }
}

event: message.content.delta
data: {
  index: 1,
  type: "suggestions",
  suggestions_delta: {
    index: 1,
    suggestion_delta: " the most orders?",
  }
}

event: status
data: { status: "done" }

Dans cet exemple, le champ content de la réponse sans flux est un tableau. L’un des éléments de content est le tableau suggestions. La signification des champs index pour les événements delta text et suggestions fait donc référence à l’emplacement des éléments dans ces deux tableaux différents. Vous devrez suivre ces index séparément lors de l’élaboration de la réponse complète.

Note

Actuellement, l’instruction SQL générée est toujours envoyée en un seul événement. Cela pourrait ne pas être le cas à l’avenir. Votre client doit être prêt à recevoir l’instruction SQL en plusieurs événements.

Autres exemples

Vous trouverez un client de flux Streamlit pour Cortex Analyst dans le référentiel de Cortex Analyst GitHub. Cette démonstration doit être exécutée localement ; SiS ne prend pas actuellement en charge le flux.

Consultez le playground Cortex Analyst dans AI/ML Studio (dans Snowsight) pour une démonstration interactive de la réponse en flux.

Schémas d’événements de flux

Voici les schémas OpenAPI/Swagger des événements envoyés par Cortex Analyst dans une réponse en flux.

status
message.content.delta
error
StreamingError:
type: object
properties:
  message:
    type: string
    description: A description of the error
  code:
    type: string
    description: The Snowflake error code categorizing the error
  request_id:
    type: string
    description: Unique request ID
Copy
warnings
Warnings:
type: object
description: Warnings found while processing the request
properties:
  warnings:
    type: array
    items:
      $ref: "#/components/schemas/Warning"
Warning:
type: object
title: The warning object
description: Represents a warning within a chat.
properties:
  message:
    type: string
    description: A human-readable message describing the warning
Copy
response_metadata
ResponseMetadata:
type: object
description: Details about request processing
Copy

Envoyer le feedback

POST /api/v2/cortex/analyst/feedback

Fournit un retour d’information qualitatif à l’utilisateur final. Sur l”Snowsight, le retour d’information est indiqué à l’adresse Semantic Model Admins sous Monitoring.

En-têtes de requête

En-tête

Description

Authorization

(Obligatoire) Jeton d’autorisation. Pour plus d’informations, voir Authentification auprès du serveur.

Content-Type

(Obligatoire) application/json

Corps de la requête

Champ

Description

request_id

(Obligatoire) L’identifiant de la requête que vous avez faite pour envoyer un message. Renvoyé dans le champ request_id de /api/v2/cortex/analyst/message. Pour plus d’informations, voir Réponse sans flux.

Type : chaîne

Exemple : 75d343ee-699c-483f-83a1-e314609fb563

positive

(Obligatoire) Indique si le retour d’information est positif ou négatif. true pour un retour d’information positif ou un « pouce vers le haut », false pour un retour d’information négatif ou un « pouce vers le bas ».

Type : booléen

Exemple :

true

feedback_message

(Facultatif) Le message de retour de l’utilisateur.

Exemple : This is the best answer I've ever seen!

Réponse

Corps de réponse vide avec le code de statut 200.

Exigences en matière de contrôle d’accès

Pour obtenir des informations sur les privilèges requis, voir Exigences en matière de contrôle d’accès.

Pour plus d’informations sur l’authentification à l’API, voir Authentification d”Snowflake REST APIs avec Snowflake.

Langage: Français