Questa pagina descrive come fornire un contesto creato per gli agenti per i dati che utilizzano origini dati del database.
Il contesto creato è una guida che i Data Agent Owner possono fornire per modellare il comportamento di un agente per i dati e perfezionare le risposte dell'API. Un contesto creato in modo efficace fornisce agli agenti per i dati dell'API Analisi conversazionale un contesto utile per rispondere alle domande sulle origini dati.
Per le origini dati del database come AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL, fornisci il contesto creato definendolo e archiviandolo prima nel database, quindi facendovi riferimento nel riferimento all'origine dati. Gli esempi in questa pagina utilizzano il metodo QueryData.
Fornire un contesto di alta precisione consente all'API di generare query SQL e risposte più accurate e pertinenti.
Prima di iniziare
- Avrai bisogno di un agente per i dati con il relativo contesto caricato per il database su cui vuoi eseguire query. Per saperne di più, consulta la documentazione dell'agente per i dati per AlloyDB, Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL. Per Spanner Graph, consulta Gestisci i set di contesto in Spanner Studio.
- Per creare, caricare e gestire i set di contesto per le origini dati del database, abilita l'API Knowledge Catalog e concedi il ruolo Dataplex Catalog Editor (
roles/dataplex.catalogEditor) o Dataplex Catalog Admin (roles/dataplex.catalogAdmin) all'utente IAM o al account di servizio a livello di progetto. Per saperne di più, consulta Autorizzazioni per i set di contesti. Attiva l'API di dati Cloud SQL per la tua istanza come segue:
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_APISostituisci
INSTANCE_IDcon l'ID della tua istanza Cloud SQL per MySQL o Cloud SQL per PostgreSQL.Devi anche concedere i privilegi del database a un utente o un account di servizio IAM. Per saperne di più, consulta Concedi i privilegi del database a un singolo utente o account di servizio IAM in Cloud SQL per MySQL e Concedi i privilegi del database a un singolo utente o account di servizio IAM in Cloud SQL per PostgreSQL.
Fornire contesto con QueryData
Quando chiami il metodo QueryData, fornisci l'origine dati e le informazioni di contesto nel campo QueryDataRequest.context.datasourceReferences. Per le origini dati del database, devi utilizzare uno dei seguenti elementi:
alloydbper AlloyDB per PostgreSQLspanner_referenceper GoogleSQL per Spannercloud_sql_referenceper Cloud SQL per MySQL e Cloud SQL per PostgreSQL
All'interno di questi riferimenti, specifichi il database e le tabelle utilizzando il campo databaseReference. Per includere il contesto dell'autore, devi anche fornire un agentContextReference che rimandi a un context_set_id.
Esempio di richiesta QueryData con contesto creato
L'esempio seguente mostra una richiesta QueryData che utilizza alloydb. Il campo agent_context_reference.context_set_id viene utilizzato per collegare il contesto pre-creato archiviato nel database.
AlloyDB
{ "parent": "projects/data-agents-project/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "alloydb": { "database_reference": { "project_id": "data-agents-project", "region": "us-central1", "cluster_id": "sqlgen-magic", "instance_id": "data-agents-primary", "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
GoogleSQL per Spanner
{ "parent": "projects/data-agents-project/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "spanner_reference" { "database_reference" { "engine": "GOOGLE_SQL" "project_id": "data-agents-project" "instance_id": "evalbench" "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Spanner Graph
{ "parent": "projects/data-agents-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": "data-agents-project", "instance_id": "data-agents-instance", "database_id": "fin-graph-db", "graph_ids": [ "FinGraph" ] }, "agent_context_reference": { "context_set_id": "projects/data-agents-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 } }
Cloud SQL per MySQL
{ "parent": "projects/data-agents-project/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "cloud_sql_reference": { "database_reference": { "engine": "MYSQL" "project_id": "data-agents-project", "region": "us-central1", "instance_id": "data-agents-primary", "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
Cloud SQL per PostgreSQL
{ "parent": "projects/data-agents-project/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "cloud_sql_reference": { "database_reference": { "engine": "POSTGRES" "project_id": "data-agents-project", "region": "us-central1", "instance_id": "data-agents-primary", "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
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. Questo campo cambia in base al database su cui stai eseguendo la query.database_reference: : specifica le informazioni relative all'istanza del database.engine: il motore del database o il dialetto SQL. Facoltativo per AlloyDB. Per i database Spanner, imposta suGOOGLE_SQL. Per le istanze Cloud SQL per MySQL, imposta suMYSQL. Per le istanze Cloud SQL per PostgreSQL, imposta suPOSTGRESQL.project_id: l'ID progetto dell'istanza di database.region: la regione dell'istanza di database.cluster_id: l'ID cluster dell'istanza di database.instance_id: l'ID istanza del database.database_id: l'ID del database.graph_ids: obbligatorio per Spanner Graph. Un elenco di nomi di grafi di proprietà nel database Spanner su cui eseguire query (ad esempio["FinGraph"]). Se omettigraph_ids, QueryData genera query GoogleSQL sulle tabelle sottostanti anziché query GQL.
agent_context_reference: link al contesto creato nel database.context_set_id: l'ID contesto dell'agente archiviato nel database. Per saperne di più su come trovare l'ID del set di contesto, consulta la documentazione di AlloyDB, Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL. Per Spanner Graph, consulta Trova l'ID del set di contesto.
generationOptions: 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.
Risposta di esempio QueryData
Ecco un esempio di risposta corretta da una chiamata QueryData:
{
"generated_query": "-- 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",
"intent_explanation": "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.",
"query_result": {
"columns": [
{
"name": "count"
}
],
"rows": [
{
"values": [
{
"value": "2"
}
]
}
],
"total_row_count": 1
},
"natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}