Prueba de QueryData

En este documento, se describe cómo probar QueryData y actualizar el archivo de conjunto de contexto. Puedes probar la capacidad de QueryData para generar consultas en SQL a partir de preguntas en lenguaje natural. Si una consulta generada no es precisa, puedes actualizar el archivo de conjunto de contexto.

Para obtener más información sobre los conjuntos de contexto, consulta Descripción general de los conjuntos de contexto.

Antes de comenzar

Asegúrate de haber creado un conjunto de contextos en Knowledge Catalog y de haber subido el archivo del conjunto de contextos al conjunto de contextos. Para obtener más información, consulta Administra conjuntos de contexto en AlloyDB Studio.

Para descargar, actualizar y subir archivos de conjuntos de contexto, asegúrate de que el usuario de IAM tenga el rol de editor de Dataplex Catalog (roles/dataplex.catalogEditor) o de administrador de Dataplex Catalog (roles/dataplex.catalogAdmin) en el proyecto. Para obtener más información, consulta El contexto establece permisos.

Prueba QueryData

Para probar un QueryData, sigue estos pasos:

  1. En la consola de Google Cloud , ve a la página de AlloyDB.

    Ir a AlloyDB

  2. Selecciona un clúster de la lista.

  3. En el menú de navegación, haz clic en AlloyDB Studio.

  4. Accede a Studio con la autenticación de Identity and Access Management.

  5. En el panel Explorador, haz clic en Ver acciones junto al conjunto de contexto que estás usando.

  6. Haz clic en Probar conjunto de contextos.

  7. En el editor de consultas, haz clic en Generar SQL con QueryData con: CONTEXT_SET_NAME para abrir el panel de generación de consultas.

  8. Ingresa una pregunta en lenguaje natural en el panel de generación de consultas para generar una consulta en SQL y haz clic en Generar.

  9. Revisa la consulta en SQL para verificar su exactitud. Haz clic en Insertar para agregar la consulta al editor.

Descargar y actualizar un conjunto de contextos

Si no estás conforme con la consulta en SQL generada para una pregunta en lenguaje natural, descarga el archivo de conjunto de contexto existente. Luego, puedes revisar y actualizar la plantilla de consulta, y subir el archivo de conjunto de contexto actualizado al conjunto de contexto en Knowledge Catalog.

Para descargar y actualizar un conjunto de contextos, sigue estos pasos:

  1. En el panel Explorador, haz clic en Ver acciones junto al conjunto de contexto que estás usando.
  2. Haz clic en Descargar archivo de contexto.
  3. Sigue los pasos que se indican en Crea conjuntos de información contextual con el agente de ingeniería de contexto para actualizar el contexto con pares de consultas adicionales.
  4. En el panel Explorador, haz clic en Ver acciones junto al conjunto de contexto que estás usando.
  5. Haz clic en Editar conjunto de contextos.
  6. Haz clic en Explorar en la sección Subir archivo de contexto y selecciona el archivo de conjunto de contexto actualizado.
  7. Haz clic en Guardar para actualizar el conjunto de contextos.

Una vez que estés conforme con la exactitud de tus respuestas, puedes pasar el ID del conjunto de contexto al extremo QueryData sin estado en las solicitudes de tu aplicación.

Cómo encontrar el ID del conjunto de información contextual

Para hacer referencia al conjunto de información contextual que creaste y que se almacena en Knowledge Catalog cuando llamas al extremo QueryData sin estado desde tu aplicación, necesitas el ID del conjunto de información contextual.

  1. En la consola de Google Cloud , ve a la página de AlloyDB.

    Ir a AlloyDB

  2. Selecciona un clúster de la lista.

  3. En el menú de navegación, haz clic en AlloyDB Studio.

  4. Accede a Studio con la autenticación de Identity and Access Management.

  5. En el panel Explorador, haz clic en Ver acciones junto al conjunto de contexto que estás usando.

  6. Haz clic en Editar conjunto de contextos.

  7. Toma nota del nombre del recurso del conjunto de información contextual en ID del conjunto de información contextual. El extremo QueryData admite los siguientes formatos de nombre de recurso de conjunto de contexto en Knowledge Catalog:

    • Formato de 6 segmentos: projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, como projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates
    • Formato de 8 segmentos: projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (por ejemplo, @v1)

Conecta QueryData a tu aplicación

Establece el ID del conjunto de contexto en la llamada de método QueryData para proporcionar el contexto creado desde Knowledge Catalog para las fuentes de datos de la base de datos, como AlloyDB, Spanner, Cloud SQL para MySQL, Cloud SQL para PostgreSQL, Firestore y Bigtable. Para obtener más información, consulta Define el contexto del agente de datos para las fuentes de datos de la base de datos.

Después de probar el conjunto de contexto, puedes hacer referencia a la fuente de datos de la base de datos y al conjunto de contexto en tu llamada sin estado a QueryData.

Ejemplo de solicitud QueryData con contexto creado

En el siguiente ejemplo, se envía una solicitud QueryData sin estado con la fuente de datos de la base de datos alloydb. El campo agent_context_reference.context_set_id vincula la solicitud con el conjunto de contexto creado previamente que se almacena en Knowledge Catalog, no en tu base de datos:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION:queryData \
  -d '{
  "prompt": "How many accounts in the Prague region are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": {
      "alloydb": {
        "database_reference": {
          "project_id": "PROJECT_ID",
          "region": "LOCATION",
          "cluster_id": "CLUSTER_ID",
          "instance_id": "INSTANCE_ID",
          "database_id": "DATABASE_ID"
        },
        "agent_context_reference": {
          "context_set_id": "projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID"
        }
      }
    }
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}'

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud que se usó para la solicitud.
  • LOCATION: Es la región de la solicitud, como us-central1.
  • CLUSTER_ID: Es el ID del clúster de AlloyDB.
  • INSTANCE_ID: el ID de la instancia de AlloyDB.
  • DATABASE_ID: Es el ID de la base de datos.
  • CONTEXT_SET_ID: Es el ID de tu conjunto de contextos.

El cuerpo de la solicitud contiene los siguientes campos:

  • prompt: Es la pregunta en lenguaje natural del usuario final.
  • context: Contiene información sobre las fuentes de datos.
    • datasource_references: Especifica el tipo de fuente de datos.
      • alloydbEs obligatorio cuando se consulta la base de datos.
        • database_reference: Especifica información relacionada con tu instancia de base de datos.
          • cluster_id: Es el ID del clúster de la instancia de base de datos.
          • project_id: Es el ID del proyecto de la instancia de base de datos.
          • region: Es la región de la instancia de AlloyDB.
          • instance_id: Es el ID de la instancia de AlloyDB.
          • database_id: Es el ID de la base de datos.
        • agent_context_reference: Vincula la solicitud QueryData sin estado al conjunto de contexto creado que se almacena en Knowledge Catalog, no en tu base de datos.
          • context_set_id: Es el nombre completo del recurso del conjunto de contexto almacenado en Knowledge Catalog. Puedes especificar el formato de 6 segmentos, projects/PROJECT_ID/locations/LOCATION/contextSets/CONTEXT_SET_ID, o el formato de 8 segmentos, projects/PROJECT_ID/locations/LOCATION/contextSetGroups/GROUP_ID/contextSets/CONTEXT_SET_ID@VERSION (por ejemplo, @v1).
  • generation_options: Configura el tipo de resultado que se generará.
    • generate_query_result: Se establece como verdadero para generar y mostrar los resultados de la consulta.
    • generate_natural_language_answer: Opcional Si se establece como verdadero, genera una respuesta en lenguaje natural.
    • generate_explanation: Opcional Si se establece como verdadero, genera una explicación de la consulta en SQL.
    • generate_disambiguation_question: Opcional Si se establece como verdadero, genera preguntas de desambiguación si la consulta es ambigua.

Respuesta de ejemplo de QueryData

Este es un ejemplo de una respuesta correcta de una llamada QueryData:

{
  "generatedQuery": "-- 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",
  "intentExplanation": "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.",
  "queryResult": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "totalRowCount": "1"
  },
  "naturalLanguageAnswer": "There are 2 accounts in Prague that are eligible for loans.",
  "tokenUsage": {
    "inputTokenCount": 312,
    "outputTokenCount": 148
  }
}

¿Qué sigue?