Definisci il contesto dell'agente dati per le origini dati del database

Questa pagina descrive come fornire il contesto creato per gli agenti dati che utilizzano origini dati di database utilizzando il QueryData metodo.

Il contesto creato è una guida che i proprietari degli agenti dati possono fornire per definire il comportamento di un agente dati e perfezionare le risposte dell'API. Un contesto creato efficace fornisce agli agenti dati dell'API Analisi conversazionale un contesto utile per rispondere alle domande sulle origini dati.

Per le origini dati di database come AlloyDB, GoogleSQL per Spanner, Cloud SQL per MySQL e Cloud SQL per PostgreSQL, fornisci il contesto creato definendolo e memorizzandolo nel database, quindi facendo riferimento ad esso nella chiamata QueryData.

Fornire un contesto di elevata accuratezza consente all'API di generare query e risposte SQL più accurate e pertinenti.

Prima di iniziare

Avrai bisogno di un agente dati con il relativo contesto dell'agente caricato per il database su cui vuoi eseguire query. Per ulteriori informazioni, consulta Agenti dati per AlloyDB, Agenti dati per GoogleSQL per Spanner, Agenti dati per Cloud SQL e Agenti dati per Cloud SQL per PostgreSQL.
Abilita l'API Cloud SQL Data per l'istanza nel seguente modo:
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
Sostituisci INSTANCE_ID con l'ID dell'istanza Cloud SQL o Cloud SQL per PostgreSQL.

Devi anche concedere i privilegi del database a un utente IAM o a un account di servizio. Per ulteriori informazioni, consulta Concedere i privilegi del database a un singolo utente IAM o account di servizio in Cloud SQL e Concedere i privilegi del database a un singolo utente IAM o account di servizio in Cloud SQL per PostgreSQL.

Fornire il contesto con `QueryData`

Quando chiami il metodo QueryData, fornisci l'origine dati e le informazioni sul contesto nel campo QueryDataRequest.context.datasourceReferences. Per le origini dati di database, devi utilizzare una delle seguenti opzioni:

alloydb per AlloyDB per PostgreSQL
spanner_reference per GoogleSQL per Spanner
cloud_sql_reference per 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 creato, 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 collegarsi al contesto creato in precedenza e memorizzato 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
 }
}

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 GOOGLE_SQL. Per le istanze Cloud SQL per MySQL, imposta MYSQL. Per le istanze Cloud SQL per PostgreSQL, imposta POSTGRESQL.
      - project_id: l'ID progetto dell'istanza del database.
      - region: la regione dell'istanza del database.
      - cluster_id: l'ID cluster dell'istanza del database.
      - instance_id: l'ID istanza del database.
      - database_id: l'ID del database.
    - agent_context_reference: rimanda al contesto creato nel database.
      - context_set_id: l'ID del contesto dell'agente memorizzato nel database. Per ulteriori informazioni su come trovare l'ID del set di contesto, consulta Trovare l'ID del contesto dell'agente in AlloyDB, Trovare l'ID del contesto dell'agente in GoogleSQL per Spanner, Trovare l'ID del contesto dell'agente in Cloud SQL e Trovare l'ID del contesto dell'agente in Cloud SQL per PostgreSQL.
generationOptions: configura il tipo di output da generare.
- generate_query_result: imposta 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`

Di seguito è riportato un esempio di risposta riuscita a 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."
}

Definisci il contesto dell'agente dati per le origini dati del database Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.