Testa QueryData in Firestore Studio

Questo documento descrive come testare QueryData e aggiornare il file del set di contesti. Puoi testare la capacità di QueryData di generare query MQL (MongoDB-compatible Query Language) da domande in linguaggio naturale. Se una query generata non è accurata, puoi aggiornare il file del set di contesti.

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 set di contesti e che il file del set di contesti sia stato caricato nell'agente QueryData. Per saperne di più, consulta Gestire i set di contesti in Firestore Studio.

Per scaricare, aggiornare e caricare i file del set di contesti, assicurati che l'utente IAM disponga del ruolo Dataplex Catalog Editor (roles/dataplex.catalogEditor) o Dataplex Catalog Admin (roles/dataplex.catalogAdmin) nel progetto. Per saperne di più, consulta Autorizzazioni dei set di contesti.

Testare QueryData

Per testare QueryData:

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

    Vai a Firestore

  2. Seleziona un database a cui hai aggiunto un set di contesti. È supportato solo Firestore con compatibilità MongoDB.

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

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

  5. Fai clic su Testa set di contesti.

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

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

  8. Controlla l'accuratezza della query MQL.

Scaricare e aggiornare un set di contesti

Se non sei soddisfatto della query MQL generata per una domanda in linguaggio naturale, scarica il file del set di contesti esistente. Puoi quindi rivedere e aggiornare il modello di query e ricaricare il file di contesto aggiornato nell'agente.

Per scaricare e aggiornare un set di contesti:

  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 progettazione del contesto per aggiornare il contesto con altre coppie di query.
  4. Nel riquadro Explorer, fai clic su Visualizza azioni accanto al set di contesti 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.

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

Trovare l'ID del set di contesti

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

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

    Vai a Firestore

  2. Seleziona un database a cui hai aggiunto un set di contesti.

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

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

  5. Fai clic su Modifica set di contesti.

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

Connettere QueryData all'applicazione

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

Dopo aver testato il set di contesti, 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 firestore_reference (Firestore con compatibilità MongoDB). Il campo agent_context_reference.context_set_id viene utilizzato per creare un link al contesto pre-creato archiviato nel database.

{
  "parent": "projects/context-set-project/locations/us-central1",
  "prompt": "How many accounts in the Prague region are eligible for loans?",
  "context": {
    "datasource_references": [
      {
        "firestore_reference": {
          "database_reference": {
            "project_id": "context-set-project",
            "region": "us-central1",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/context-set-project/locations/us-central1/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.
      • firestore_reference: 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.
          • project_id: l'ID progetto del database.
          • region: la regione del database.
          • database_id: l'ID del database.
        • agent_context_reference: crea un 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-central1/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 impostato su true, genera una spiegazione della query MQL.
    • 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 da una chiamata QueryData:

{
  "generated_query": "// Count the number of accounts in Prague that are eligible for loans\ndb.loans.aggregate([\n  // 1. Filter loans in the Prague region\n  { \n    $match: { \"district.name\": \"Prague\" } \n  },\n  // 2. Group by account_id to get distinct values, and count them\n  { \n    $group: { \n      _id: null, \n      uniqueAccounts: { $addToSet: \"$account_id\" } \n    } \n  },\n  // 3. Project the size of the unique accounts array\n  { \n    $project: { \n      _id: 0,\n      distinct_account_count: { $size: \"$uniqueAccounts\" } \n    } \n  }\n]);",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to filter the documents in the loans collection to only give me those in the Prague region. Then I need to group the loans by account ID to get distinct values and count them. Finally, I need to project the size of the array of unique accounts.",
  "query_result": {
    "columns": [
      {
        "name": "distinct_account_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