Testare QueryData

Questo documento descrive come testare QueryData per Spanner Graph chiamando il metodo QueryData dell'API Analisi conversazionale e come aggiornare il file del set di contesto. Puoi testare la capacità di QueryData di generare query Graph Query Language (GQL) da domande in linguaggio naturale. Se una query GQL generata non è accurata, puoi aggiornare il file del set di contesto.

Per scoprire di più sui set di contesto per Spanner Graph, consulta la panoramica dei set di contesto.

Prima di iniziare

Trova l'ID del set di contesti esistente

Per testare QueryData con il tuo set di contesti o per connettere un'applicazione di dati a QueryData, devi avere l'ID del set di contesti.

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

    Vai a Spanner

  2. Seleziona un'istanza dall'elenco, quindi seleziona un database.

  3. Nel menu di navigazione, fai clic su Spanner Studio.

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

  5. Fai clic su Modifica set di contesti.

  6. Prendi nota dell'ID del set di contesti in ID set di contesti. Il formato dell'ID del set di contesti è simile a projects/my-project/locations/us-central1/contextSets/fingraph-assistant.

Testa QueryData utilizzando HTTP POST

Per testare QueryData per Spanner Graph, invia una richiesta POST HTTP QueryData che includa il campo graph_ids e l'ID del set di contesto:

  1. Crea un file denominato request.json con i seguenti contenuti:

    {
      "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": "PROJECT_ID",
              "instance_id": "INSTANCE_ID",
              "database_id": "DATABASE_ID",
              "graph_ids": ["FinGraph"]
            },
            "agent_context_reference": {
              "context_set_id": "CONTEXT_SET_ID"
            }
          }
        }
      },
      "generation_options": {
        "generate_query_result": true,
        "generate_natural_language_answer": true,
        "generate_explanation": true
      }
    }

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto Google Cloud .
    • INSTANCE_ID: l'ID istanza Spanner.
    • DATABASE_ID: l'ID del tuo database Spanner.
    • CONTEXT_SET_ID: l'ID set di contesti completo che hai annotato in Trova l'ID set di contesti.
  2. Invia la richiesta:

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "x-goog-user-project: PROJECT_ID" \
      "https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/global:queryData" \
      -d @request.json
    
  3. Nella risposta, controlla l'accuratezza del campo generatedQuery (GRAPH FinGraph MATCH ...) e controlla il campo queryResult per le righe restituite.

Per testare altre domande, modifica il valore prompt in request.json e invia nuovamente la richiesta. Per vedere come si comporta QueryData senza contesto creato, rimuovi l'oggetto agent_context_reference.

Per verificare che QueryData utilizzi il tuo set di contesto, fai una domanda che dipende da questo (ad esempio "Chi è il proprietario dell'account per i giorni di pioggia?") e confronta le risposte con e senza l'oggetto agent_context_reference. Senza il contesto impostato, QueryData potrebbe filtrare in base a 'rainy day' e non restituire righe. Una volta impostato il contesto, filtra in base a 'Rainy Day Fund' e restituisce Dana.

Scarica e aggiorna il set di contesti esistente

Se le risposte del test mostrano che la query GQL generata per una domanda in linguaggio naturale deve essere migliorata, scarica il file del set di contesto esistente. Puoi quindi esaminare e aggiornare i modelli di query GQL, i facet o le ricerche di valori e caricare il file del set di contesti aggiornato nel set di contesti.

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

  1. Nel riquadro Explorer, fai clic su Visualizza azioni accanto al set di contesto.
  2. Fai clic su Scarica file di contesto.
  3. Segui i passaggi descritti in Crea set di contesti utilizzando l'agente di progettazione del contesto per aggiornare il set di contesti con altre coppie di query da linguaggio naturale a GQL.
  4. Nel riquadro Explorer, fai clic su Visualizza azioni accanto al set di contesto che stai utilizzando.
  5. Fai clic su Modifica set di contesti.
  6. Fai clic su Sfoglia nella sezione Carica file del set di contesti e seleziona il file del set di contesti aggiornato.
  7. Fai clic su Salva per aggiornare il set di contesti.
  8. Testa QueryData di nuovo per verificare la query GQL generata.

Quando l'accuratezza delle risposte ti soddisfa, puoi utilizzare l'endpoint QueryData per connettere la tua applicazione al set di contesto.

Connetti QueryData alla tua applicazione

Imposta l'ID del set di contesto e il target graph_ids nella chiamata al metodo QueryData per fornire il contesto creato e abilitare la generazione di query GQL per Spanner Graph. Per ulteriori informazioni sull'utilizzo di QueryData con le origini dati del database, consulta Definisci il contesto dell'agente per i dati per le origini dati del database. Per un esempio di connessione di un'applicazione agente a QueryData tramite uno strumento HTTP personalizzato che chiama l'API REST di QueryData, consulta Integra QueryData con un'applicazione.

Esempio di richiesta QueryData con contesto creato

L'esempio seguente mostra una richiesta QueryData che utilizza l'origine dati del database spanner_reference per il grafico delle proprietà FinGraph. Devi fornire graph_ids all'interno di spanner_reference.database_reference in modo che QueryData abbia come target il grafico delle proprietà e generi query GQL. Il campo agent_context_reference.context_set_id rimanda al contesto pre-creato archiviato nel database:

{
  "parent": "projects/my-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": "my-project",
          "instance_id": "my-instance",
          "database_id": "fin-graph-db",
          "graph_ids": [
            "FinGraph"
          ]
        },
        "agent_context_reference": {
          "context_set_id": "projects/my-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
  }
}

Il corpo della richiesta contiene i seguenti campi:

  • parent: (Facoltativo) Il progetto e la località della richiesta, nel formato projects/PROJECT_ID/locations/LOCATION. Utilizza lo stesso progetto e la stessa località dell'URL della richiesta.
  • prompt: la domanda in linguaggio naturale dell'utente finale.
  • context: contiene informazioni sulle origini dati.
    • datasource_references: specifica l'origine dati. Questo campo è un oggetto, non un elenco.
      • spanner_reference: obbligatorio quando si esegue una query su un database Spanner.
        • database_reference: specifica le informazioni relative al database Spanner e ai grafi delle proprietà.
          • engine: il dialetto del database. Impostato su GOOGLE_SQL per i database Spanner Graph.
          • project_id: l'ID progetto dell'istanza Spanner.
          • instance_id: l'ID istanza Spanner.
          • database_id: l'ID del database Spanner.
          • graph_ids: obbligatorio per Spanner Graph. Un elenco di nomi di grafici delle proprietà nel database su cui eseguire query (ad esempio, ["FinGraph"]). Se fornisci graph_ids, QueryData genera query GQL sui grafici delle proprietà specificati. Se ometti graph_ids, QueryData genera solo query SQL relazionali sulle tabelle sottostanti.
        • agent_context_reference: link al contesto creato nel database.
          • context_set_id: l'ID del set di contesto completo del contesto archiviato nel database, ad esempio projects/my-project/locations/us-central1/contextSets/fingraph-assistant.
  • generation_options: configura il tipo di output da generare.
    • generate_query_result: imposta su true per eseguire la query GQL generata e restituire i risultati della query.
    • generate_natural_language_answer: (Facoltativo) Se impostato su true, genera una risposta in linguaggio naturale che riassume i risultati della query.
    • generate_explanation: (Facoltativo) Se impostato su true, genera una spiegazione della query GQL.
    • generate_disambiguation_question: (Facoltativo) Se impostato su true, genera domande di disambiguazione se il prompt in linguaggio naturale è ambiguo.

Esempio di risposta QueryData

L'esempio seguente mostra una risposta corretta da una chiamata QueryData sul grafico delle proprietà FinGraph. L'API REST restituisce i nomi dei campi in camelCase, ad esempio generatedQuery e queryResult. Poiché la generazione di GQL non è deterministica, la query generata, i nomi delle colonne e il testo della risposta possono variare tra le chiamate.

{
  "generatedQuery": "GRAPH `FinGraph` MATCH (p:`Person` {`name`: 'Dana'})-[:`Owns`]->(src:`Account`)-[t:`Transfers`]->(dst:`Account`) MATCH (p_recipient:`Person`)-[:`Owns`]->(dst) RETURN DISTINCT p_recipient.`name` AS recipient_name, dst.`id` AS recipient_account_id, t.`amount` AS transfer_amount",
  "intentExplanation": "To find everyone Dana transferred money to, we identify the person named Dana and locate the accounts they own. We trace the transfer relationships from Dana's accounts to any destination accounts, identifying the specific amounts sent and the IDs of those receiving accounts. Finally, we find the individuals who own those receiving accounts to present their names along with the account details and transfer amounts.",
  "queryResult": {
    "columns": [
      {
        "name": "recipient_name",
        "type": "STRING"
      },
      {
        "name": "recipient_account_id",
        "type": "INT64"
      },
      {
        "name": "transfer_amount",
        "type": "FLOAT64"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "Alex"
          },
          {
            "value": "7"
          },
          {
            "value": "500"
          }
        ]
      },
      {
        "values": [
          {
            "value": "Lee"
          },
          {
            "value": "16"
          },
          {
            "value": "200"
          }
        ]
      }
    ],
    "totalRowCount": "2"
  },
  "naturalLanguageAnswer": "Based on the transaction records, Dana transferred money to the following recipients:\n\n*   **Alex**: Account ID **7**, with a transfer amount of **500**\n*   **Lee**: Account ID **16**, with a transfer amount of **200**"
}

Passaggi successivi