Ce document explique comment tester QueryData pour Spanner Graph en appelant la méthode QueryData de l'API Conversational Analytics, et comment mettre à jour le fichier d'ensemble de contexte. Vous pouvez tester la capacité de QueryData à générer des requêtes GQL (Graph Query Language) à partir de questions en langage naturel. Si une requête GQL générée n'est pas exacte, vous pouvez mettre à jour le fichier d'ensemble de contexte.
Pour en savoir plus sur les ensembles de contexte pour Spanner Graph, consultez Présentation des ensembles de contexte.
Avant de commencer
- Assurez-vous que votre base de données Spanner est configurée avec le schéma de graphe de propriétés
FinGraphet des exemples de données. Pour savoir comment créer le schémaFinGraphet insérer les exemples de données, consultez Configurer et interroger Spanner Graph. - Assurez-vous qu'un ensemble de contextes a déjà été créé et que le fichier de l'ensemble de contextes a été importé dans la base de données. Pour en savoir plus, consultez Gérer les ensembles de contexte dans Spanner Studio.
- Installez et initialisez la Google Cloud CLI.
Rechercher l'ID de l'ensemble de contextes existant
Pour tester QueryData avec votre ensemble de contextes ou pour connecter une application de données à QueryData, vous avez besoin de l'ID de l'ensemble de contextes.
Dans la console Google Cloud , accédez à la page "Spanner".
Sélectionnez une instance dans la liste, puis une base de données.
Dans le menu de navigation, cliquez sur Spanner Studio.
Dans le volet Explorateur, cliquez sur Afficher les actions à côté de l'ensemble de contexte que vous utilisez.
Cliquez sur Modifier l'ensemble de contextes.
Notez l'ID de l'ensemble de contextes dans ID de l'ensemble de contextes. Le format de l'ID de l'ensemble de contextes est semblable à
projects/my-project/locations/us-central1/contextSets/fingraph-assistant.
Tester QueryData à l'aide d'une requête HTTP POST
Pour tester QueryData pour Spanner Graph, envoyez une requête HTTP POST QueryData incluant le champ graph_ids et l'ID de votre ensemble de contexte :
Créez un fichier nommé
request.jsonavec le contenu suivant :{ "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.", "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "PROJECT_ID", "instance_id": "INSTANCE_ID", "database_id": "DATABASE_ID", "graph_ids": ["FinGraph"] }, "agent_context_reference": { "context_set_id": "CONTEXT_SET_ID" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_explanation": true } }
Remplacez les éléments suivants :
PROJECT_ID: ID de votre projet Google Cloud .INSTANCE_ID: ID de votre instance Spanner.DATABASE_ID: ID de votre base de données Spanner.CONTEXT_SET_ID: ID complet de l'ensemble de contextes que vous avez noté dans Rechercher l'ID de l'ensemble de contextes.
Envoyez la requête :
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/global:queryData" \ -d @request.json
Dans la réponse, vérifiez l'exactitude du champ
generatedQuery(GRAPH FinGraph MATCH ...) et examinez le champqueryResultpour les lignes renvoyées.
Pour tester d'autres questions, modifiez la valeur prompt dans request.json et envoyez à nouveau la requête. Pour voir comment QueryData se comporte sans contexte créé, supprimez l'objet agent_context_reference.
Pour vérifier que QueryData utilise votre ensemble de contexte, posez une question qui en dépend (par exemple, "Qui est le propriétaire du compte rainy day ?") et comparez les réponses avec et sans l'objet agent_context_reference. Sans le contexte défini, QueryData peut filtrer sur 'rainy day' et ne renvoyer aucune ligne. Une fois le contexte défini, il filtre sur 'Rainy Day Fund' et renvoie Dana.
Télécharger et mettre à jour l'ensemble de contexte existant
Si vos réponses de test indiquent que la requête GQL générée pour une question en langage naturel doit être améliorée, téléchargez le fichier d'ensemble de contexte existant. Vous pouvez ensuite examiner et mettre à jour les modèles de requête GQL, les facettes ou les recherches de valeurs, puis importer le fichier d'ensemble de contexte mis à jour dans l'ensemble de contexte.
Pour télécharger et mettre à jour un ensemble de contextes, procédez comme suit :
- Dans le volet Explorateur, cliquez sur Afficher les actions à côté de votre ensemble de contexte.
- Cliquez sur Télécharger le fichier de contexte.
- Suivez les étapes de la section Créer des ensembles de contextes à l'aide de l'agent d'ingénierie contextuelle pour mettre à jour l'ensemble de contextes avec des paires de requêtes supplémentaires en langage naturel vers GQL.
- Dans le volet Explorateur, cliquez sur Afficher les actions à côté de l'ensemble de contexte que vous utilisez.
- Cliquez sur Modifier l'ensemble de contextes.
- Cliquez sur Parcourir dans la section Importer un fichier d'ensemble de contexte, puis sélectionnez le fichier d'ensemble de contexte mis à jour.
- Cliquez sur Enregistrer pour mettre à jour l'ensemble de contextes.
- Cliquez à nouveau sur Test QueryData (Tester QueryData) pour vérifier la requête GQL générée.
Une fois que vous êtes satisfait de la précision de vos réponses, vous pouvez utiliser le point de terminaison QueryData pour connecter votre application à l'ensemble de contextes.
Connecter QueryData à votre application
Définissez l'ID de l'ensemble de contexte et la cible graph_ids dans l'appel de méthode QueryData pour fournir un contexte créé et activer la génération de requêtes GQL pour Spanner Graph. Pour en savoir plus sur l'utilisation de QueryData avec des sources de données de base de données, consultez Définir le contexte de l'agent de données pour les sources de données de base de données. Pour obtenir un exemple qui connecte une application d'agent à QueryData via un outil HTTP personnalisé qui appelle l'API REST QueryData, consultez Intégrer QueryData à une application.
Exemple de requête QueryData avec un contexte créé
L'exemple suivant montre une requête QueryData utilisant la source de données de la base de données spanner_reference pour le graphique de propriétés FinGraph. Vous devez fournir graph_ids dans spanner_reference.database_reference pour que QueryData cible votre graphique de propriétés et génère des requêtes GQL. Le champ agent_context_reference.context_set_id renvoie au contexte pré-rédigé stocké dans la base de données :
{ "parent": "projects/my-project/locations/global", "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.", "context": { "datasource_references": { "spanner_reference": { "database_reference": { "engine": "GOOGLE_SQL", "project_id": "my-project", "instance_id": "my-instance", "database_id": "fin-graph-db", "graph_ids": [ "FinGraph" ] }, "agent_context_reference": { "context_set_id": "projects/my-project/locations/us-central1/contextSets/fingraph-assistant" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Le corps de la requête contient les champs suivants :
parent: facultatif. Projet et emplacement de la requête, au formatprojects/PROJECT_ID/locations/LOCATION. Utilisez le même projet et le même emplacement que dans l'URL de la requête.prompt: question en langage naturel de l'utilisateur final.context: contient des informations sur les sources de données.datasource_references: indique la source de données. Ce champ est un objet, pas une liste.spanner_reference: obligatoire lors de l'interrogation d'une base de données Spanner.database_reference: spécifie les informations liées à votre base de données Spanner et à vos graphiques de propriétés.engine: dialecte de la base de données. Définissez cette option surGOOGLE_SQLpour les bases de données Spanner Graph.project_id: ID du projet de l'instance Spanner.instance_id: ID de l'instance Spanner.database_id: ID de la base de données Spanner.graph_ids: obligatoire pour Spanner Graph. Liste des noms de graphes de propriétés dans la base de données à interroger (par exemple,["FinGraph"]). Fournirgraph_idsindique à QueryData de générer des requêtes GQL sur les graphes de propriétés spécifiés. Si vous omettezgraph_ids, QueryData ne génère que des requêtes SQL relationnelles sur les tables sous-jacentes.
agent_context_reference: liens vers le contexte créé dans la base de données.context_set_id: ID complet de l'ensemble de contextes stocké dans la base de données, par exempleprojects/my-project/locations/us-central1/contextSets/fingraph-assistant.
generation_options: configure le type de sortie à générer.generate_query_result: définissez cette option surtruepour exécuter la requête GQL générée et renvoyer les résultats de la requête.generate_natural_language_answer: facultatif. Si la valeur est définie surtrue, génère une réponse en langage naturel résumant les résultats de la requête.generate_explanation: facultatif. Si la valeur est définie surtrue, génère une explication de la requête GQL.generate_disambiguation_question: facultatif. Si la valeur est définie surtrue, génère des questions de désambiguïsation si la requête en langage naturel est ambiguë.
Exemple de réponse QueryData
L'exemple suivant montre une réponse réussie d'un appel QueryData sur le graphique de propriétés FinGraph. L'API REST renvoie les noms de champs en camelCase, par exemple generatedQuery et queryResult. La génération GQL n'étant pas déterministe, la requête, les noms de colonnes et le texte de la réponse générés peuvent différer d'un appel à l'autre.
{
"generatedQuery": "GRAPH `FinGraph` MATCH (p:`Person` {`name`: 'Dana'})-[:`Owns`]->(src:`Account`)-[t:`Transfers`]->(dst:`Account`) MATCH (p_recipient:`Person`)-[:`Owns`]->(dst) RETURN DISTINCT p_recipient.`name` AS recipient_name, dst.`id` AS recipient_account_id, t.`amount` AS transfer_amount",
"intentExplanation": "To find everyone Dana transferred money to, we identify the person named Dana and locate the accounts they own. We trace the transfer relationships from Dana's accounts to any destination accounts, identifying the specific amounts sent and the IDs of those receiving accounts. Finally, we find the individuals who own those receiving accounts to present their names along with the account details and transfer amounts.",
"queryResult": {
"columns": [
{
"name": "recipient_name",
"type": "STRING"
},
{
"name": "recipient_account_id",
"type": "INT64"
},
{
"name": "transfer_amount",
"type": "FLOAT64"
}
],
"rows": [
{
"values": [
{
"value": "Alex"
},
{
"value": "7"
},
{
"value": "500"
}
]
},
{
"values": [
{
"value": "Lee"
},
{
"value": "16"
},
{
"value": "200"
}
]
}
],
"totalRowCount": "2"
},
"naturalLanguageAnswer": "Based on the transaction records, Dana transferred money to the following recipients:\n\n* **Alex**: Account ID **7**, with a transfer amount of **500**\n* **Lee**: Account ID **16**, with a transfer amount of **200**"
}
Étapes suivantes
- En savoir plus sur les ensembles de contexte
- Découvrez comment créer des ensembles de contextes à l'aide de l'agent d'ingénierie contextuelle.
- Découvrez comment gérer les ensembles de contexte dans Spanner Studio.