Testare QueryData utilizzando Cloud SQL Studio

Questo documento descrive come testare QueryData e aggiornare il file 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 contesti, consulta la Panoramica dei set di contesti.

Prima di iniziare

Assicurati che sia già stato creato un insieme di contesti e che il file dell'insieme di contesti sia stato caricato nell'agente QueryData. Per saperne di più, consulta Gestire i set di contesto in Cloud SQL Studio.

Testare QueryData

Per testare un QueryData:

  1. Nella console Google Cloud , vai alla pagina Cloud SQL.

    Vai a Cloud SQL

  2. Seleziona un'istanza dall'elenco.

  3. Nel menu di navigazione, fai clic su Cloud SQL Studio.

  4. Accedi a Studio utilizzando l'autenticazione Identity and Access Management.

  5. Nel riquadro Explorer, fai clic su Visualizza azioni accanto al set di contesto che stai utilizzando.

  6. Fai clic su Set di contesti di test.

  7. Nell'editor di query, fai clic su Genera SQL per aprire il riquadro Aiutami a programmare.

  8. Inserisci una domanda in linguaggio naturale nell'editor per generare una query SQL e fai clic su Genera.

  9. Esamina l'accuratezza della query SQL.

Scaricare e aggiornare 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 ricaricare il file di contesto aggiornato nell'agente.

Per scaricare e aggiornare un insieme di contesti, segui questi passaggi:

  1. Nel riquadro Explorer, fai clic su Visualizza azioni.
  2. Fai clic su Scarica file di contesto.
  3. Segui i passaggi descritti in Creare set di contesti utilizzando l'agente di ingegneria del contesto per aggiornare il contesto con coppie di query aggiuntive.
  4. Nel riquadro Explorer, fai clic su Visualizza azioni accanto al set di contesto che stai utilizzando.
  5. Fai clic su Modifica insieme di contesti.
  6. Fai clic su Sfoglia nella sezione Carica file del set di contesto e seleziona il file del set di contesto aggiornato.
  7. Fai clic su Salva per aggiornare il set di contesto.

Una volta soddisfatto dell'accuratezza delle risposte, puoi utilizzare l'endpoint QueryData per connettere l'applicazione al set di contesto.

Trovare l'ID set di contesti

Per connettere un'applicazione di dati all'agente QueryData, devi disporre dell'ID del set di contesti.

  1. Nella console Google Cloud , vai alla pagina Cloud SQL.

    Vai a Cloud SQL

  2. Seleziona un'istanza dall'elenco.

  3. Nel menu di navigazione, fai clic su Cloud SQL Studio.

  4. Accedi a Studio utilizzando l'autenticazione Identity and Access Management.

  5. Nel riquadro Explorer, fai clic su Visualizza azioni accanto al set di contesto che stai utilizzando.

  6. Fai clic su Modifica insieme di contesti.

  7. Prendi nota dell'ID contesto in ID set di contesti. Il formato dell'ID set di contesti è simile a projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates.

Connettere QueryData all'applicazione

Imposta l'ID del set di contesto nella chiamata al metodo QueryData per fornire il contesto creato per le origini dati del database come AlloyDB, Spanner, Cloud SQL e Cloud SQL per PostgreSQL. Per saperne di più, consulta Definire il contesto dell'agente dati per le origini dati del database.

Dopo aver testato il set di contesto, puoi fare riferimento all'origine dati del database nella chiamata QueryData.

Esempio di richiesta QueryData con contesto creato

L'esempio seguente mostra una richiesta QueryData che utilizza l'origine dati del database cloud_sql_reference. Il campo agent_context_reference.context_set_id viene utilizzato per collegarsi al contesto predefinito memorizzato nel database.

{
  "parent": "projects/context-set-project/locations/us-central1",
  "prompt": "How many accounts in the Prague region are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "cloud_sql_reference": {
          "database_reference": {
            "engine": "MYSQL"
            "project_id": "context-set-project",
            "region": "us-central1",
            "instance_id": "context-set-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/context-set-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.
      • cloud_sql_reference: 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: il motore del database. Imposta MYSQL per le istanze Cloud SQL.
          • project_id: l'ID progetto dell'istanza del database.
          • region: la regione dell'istanza Cloud SQL.
          • instance_id: l'ID istanza dell'istanza Cloud SQL.
          • database_id: l'ID del database.
        • agent_context_reference: Link al contesto creato nel database.
          • context_set_id: L'ID completo del set di contesti del contesto archiviato nel database. Ad esempio, projects/context-set-project/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates.
  • 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.

Esempio di risposta 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."
}

Passaggi successivi