Questo documento descrive come testare QueryData e aggiornare il file del set di contesto. Puoi testare la capacità di QueryData di generare query SQL da domande in linguaggio naturale. Se una query generata non è accurata, puoi aggiornare il file del set di contesto.
Per scoprire di più sui set di contesto, consulta la panoramica dei set di contesto.Prima di iniziare
Assicurati di aver creato un set di contesti in Knowledge Catalog e di aver caricato il file del set di contesti nel set di contesti. Per saperne di più, consulta Gestisci i set di contesto in AlloyDB Studio.
Per scaricare, aggiornare e caricare i file dei set di contesto, assicurati che l'utente IAM disponga del ruolo Dataplex Catalog Editor (roles/dataplex.catalogEditor) o Dataplex Catalog Admin (roles/dataplex.catalogAdmin) nel progetto. Per saperne di più, consulta Autorizzazioni per i set di contesti.
Testa QueryData
Per testare un QueryData, segui questi passaggi:
Nella console Google Cloud , vai alla pagina AlloyDB.
Seleziona un cluster dall'elenco.
Nel menu di navigazione, fai clic su AlloyDB Studio.
Accedi a Studio utilizzando l'autenticazione Identity and Access Management.
Nel riquadro Explorer, fai clic su Visualizza azioni accanto al set di contesto che stai utilizzando.
Fai clic su Set di contesti di test.
Nell'editor di query, fai clic su Genera SQL utilizzando QueryData con: CONTEXT_SET_NAME per aprire il riquadro di generazione delle query.
Inserisci una domanda in linguaggio naturale nel riquadro di generazione delle query per generare una query SQL e fai clic su Genera.
Esamina la query SQL per verificarne l'accuratezza. Fai clic su Inserisci per aggiungere la query all'editor.
Scarica e aggiorna un set di contesti
Se non sei soddisfatto della query SQL generata per una domanda in linguaggio naturale, scarica il file del set di contesto esistente. Puoi quindi rivedere e aggiornare il modello di query e caricare il file del set di contesto aggiornato nel set di contesto in Knowledge Catalog.
Per scaricare e aggiornare un set di contesti, segui questi passaggi:
- Nel riquadro Explorer, fai clic su Visualizza azioni accanto al set di contesto che stai utilizzando.
- Fai clic su Scarica file di contesto.
- Segui i passaggi descritti in Crea set di contesti utilizzando l'agente di progettazione del contesto per aggiornare il contesto con altre coppie di query.
- Nel riquadro Explorer, fai clic su Visualizza azioni accanto al set di contesto che stai utilizzando.
- Fai clic su Modifica set di contesti.
- Fai clic su Sfoglia nella sezione Carica file di contesto e seleziona il file del set di contesti aggiornato.
- Fai clic su Salva per aggiornare il set di contesti.
Quando l'accuratezza delle risposte ti soddisfa, puoi passare l'ID del set di contesto all'endpoint QueryData stateless nelle richieste della tua applicazione.
Trova l'ID set di contesti
Per fare riferimento al set di contesti creato e archiviato in Knowledge Catalog quando chiami l'endpoint QueryData stateless dalla tua applicazione, devi avere l'ID del set di contesti.
Nella console Google Cloud , vai alla pagina AlloyDB.
Seleziona un cluster dall'elenco.
Nel menu di navigazione, fai clic su AlloyDB Studio.
Accedi a Studio utilizzando l'autenticazione di Identity and Access Management.
Nel riquadro Explorer, fai clic su Visualizza azioni accanto al set di contesto che stai utilizzando.
Fai clic su Modifica set di contesti.
Prendi nota del nome della risorsa del set di contesti in ID set di contesti. L'endpoint
QueryDatasupporta entrambi i seguenti formati di nome risorsa del set di contesti in Knowledge Catalog:- Formato a 6 segmenti:
projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, ad esempioprojects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates - Formato a 8 segmenti:
projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION(ad esempio,@v1)
- Formato a 6 segmenti:
Connetti QueryData alla tua applicazione
Imposta l'ID del set di contesto nella chiamata al metodo QueryData per fornire il contesto creato da Knowledge Catalog per le origini dati del database come AlloyDB, Spanner, Cloud SQL per MySQL, Cloud SQL per PostgreSQL, Firestore e Bigtable. Per saperne di più, consulta Definisci il contesto dell'agente per i dati per le origini dati del database.
Dopo aver testato il set di contesto, puoi fare riferimento all'origine dati del database e al set di contesto nella chiamata QueryData stateless.
Esempio di richiesta QueryData con contesto creato
L'esempio seguente invia una richiesta QueryData stateless utilizzando l'origine dati del database alloydb. Il campo agent_context_reference.context_set_id collega la richiesta al set di contesto pre-creato archiviato in Knowledge Catalog, non nel tuo database:
curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "x-goog-user-project: PROJECT_ID" \ -H "Content-Type: application/json" \ https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION:queryData \ -d '{ "prompt": "How many accounts in the Prague region are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": { "alloydb": { "database_reference": { "project_id": "PROJECT_ID", "region": "LOCATION", "cluster_id": "CLUSTER_ID", "instance_id": "INSTANCE_ID", "database_id": "DATABASE_ID" }, "agent_context_reference": { "context_set_id": "projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }'
Sostituisci quanto segue:
PROJECT_ID: l'ID del progetto Google Cloud utilizzato per la richiesta.LOCATION: la regione per la richiesta, ad esempious-central1.CLUSTER_ID: l'ID cluster del cluster AlloyDB.INSTANCE_ID: l'ID istanza dell'istanza AlloyDB.DATABASE_ID: l'ID del database.CONTEXT_SET_ID: l'ID del set di contesti.
Il corpo della richiesta contiene i seguenti campi:
prompt: la domanda in linguaggio naturale dell'utente finale.context: contiene informazioni sulle origini dati.datasource_references: specifica il tipo di origine dati.alloydb: obbligatorio quando si esegue una query sul database.database_reference: : specifica le informazioni relative all'istanza del database.cluster_id: l'ID cluster dell'istanza di database.project_id: l'ID progetto dell'istanza di database.region: la regione dell'istanza AlloyDB.instance_id: l'ID istanza dell'istanza AlloyDB.database_id: l'ID del database.
agent_context_reference: collega la richiestaQueryDatastateless al set di contesto creato da te archiviato in Knowledge Catalog, non nel tuo database.context_set_id: il nome completo della risorsa del set di contesto archiviato in Knowledge Catalog. Puoi specificare il formato a 6 segmenti,projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, o il formato a 8 segmenti,projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION(ad esempio,@v1).
generation_options: configura il tipo di output da generare.generate_query_result: impostato su true per generare e restituire i risultati della query.generate_natural_language_answer: (Facoltativo) Se impostato su true, genera una risposta in linguaggio naturale.generate_explanation: (Facoltativo) Se impostato su true, genera una spiegazione della query SQL.generate_disambiguation_question: (Facoltativo) Se impostato su true, genera domande di disambiguazione se la query è ambigua.
Esempio di risposta QueryData
Ecco un esempio di risposta corretta da una chiamata QueryData:
{
"generatedQuery": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
"intentExplanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
"queryResult": {
"columns": [
{
"name": "count"
}
],
"rows": [
{
"values": [
{
"value": "2"
}
]
}
],
"totalRowCount": "1"
},
"naturalLanguageAnswer": "There are 2 accounts in Prague that are eligible for loans.",
"tokenUsage": {
"inputTokenCount": 312,
"outputTokenCount": 148
}
}
Passaggi successivi
- Scopri di più sui set di contesti.
- Scopri come creare set di contesti utilizzando l'agente di progettazione del contesto.
- Scopri come gestire i set di contesto in AlloyDB Studio.