Questa pagina è stata tradotta dall'API Cloud Translation.

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

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

Questa pagina descrive come fornire il contesto creato per le origini dati del database utilizzando il metodo QueryData. Per le origini dati del database come AlloyDB, GoogleSQL per Spanner, Cloud SQL e Cloud SQL per PostgreSQL, fornisci il contesto creato definendolo e memorizzandolo prima nel database e poi facendo riferimento ad esso nella chiamata QueryData.

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

Prima di iniziare

Esiste un agente dati con il contesto dell'agente caricato per un database. Per saperne di più, consulta Agenti per i dati per AlloyDB, Agenti per i dati per GoogleSQL per Spanner, Agenti per i dati per Cloud SQL e Agenti per i dati per Cloud SQL per PostgreSQL.
Abilita l'API Cloud SQL Data per la tua istanza nel seguente modo:
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
Sostituisci INSTANCE_ID con l'ID della tua 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 privilegi di database a un singolo utente IAM o account di servizio in Cloud SQL e Concedere privilegi di 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 contestuali nel campo QueryDataRequest.context.datasourceReferences. Per le origini database, devi utilizzare una delle seguenti opzioni:

alloydb per AlloyDB per PostgreSQL,
spanner_reference per GoogleSQL per Spanner
cloud_sql_reference per Cloud SQL e Cloud SQL per PostgreSQL

All'interno di questi riferimenti, specifica 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 mediante alloydb. Il campo agent_context_reference.context_set_id viene utilizzato per collegarsi al contesto predefinito memorizzato nel database.

AlloyDB

{
  "parent": "projects/cloud-db-nl2sql/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": "cloud-db-nl2sql",
            "region": "us-central1",
            "cluster_id": "sqlgen-magic",
            "instance_id": "sqlgen-magic-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/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/cloud-db-nl2sql/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": "cloud-db-nl2sql"
            "region": "us-central1"
            "instance_id": "evalbench"
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/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 e Cloud SQL per PostgreSQL

{
  "parent": "projects/cloud-db-nl2sql/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": "cloud-db-nl2sql",
            "region": "us-central1",
            "instance_id": "sqlgen-magic-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/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 durante l'esecuzione di query sul database. Questo campo cambia in base al database su cui esegui la query.
    - database_reference: specifica le informazioni relative all'istanza del database.
      - engine:
      - 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: Link al contesto creato nel database.
      - context_set_id: l'ID contesto agente archiviato nel database. Per saperne di più su come trovare l'ID del set di contesto, consulta Trovare l'ID contesto dell'agente in AlloyDB, Trovare l'ID contesto dell'agente in GoogleSQL per Spanner, Trovare l'ID contesto dell'agente in Cloud SQL e Trovare l'ID contesto dell'agente in Cloud SQL per PostgreSQL.
generationOptions: configura il tipo di output da generare.
- generate_query_result: impostalo 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 il valore è impostato su true, viene generata una spiegazione della query SQL.
- generate_disambiguation_question: (Facoltativo) Se impostato su true, genera domande di disambiguazione se la query è ambigua.

Risposta `QueryData` di esempio

Ecco un esempio di risposta corretta 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.