Prueba de QueryData

En este documento, se describe cómo probar QueryData para Spanner Graph llamando al método QueryData de la API de Conversational Analytics y cómo actualizar el archivo de conjunto de contexto. Puedes probar la capacidad de QueryData para generar consultas de Graph Query Language (GQL) a partir de preguntas en lenguaje natural. Si una consulta de GQL generada no es precisa, puedes actualizar el archivo de conjunto de contexto.

Para obtener información sobre los conjuntos de contexto para Spanner Graph, consulta Descripción general de los conjuntos de contexto.

Antes de comenzar

  • Asegúrate de que tu base de datos de Spanner tenga configurados el esquema de grafo de propiedades FinGraph y los datos de muestra. Para obtener instrucciones sobre cómo crear el esquema FinGraph y, luego, insertar los datos de muestra, consulta Configura y consulta Spanner Graph.
  • Asegúrate de que ya se haya creado un conjunto de contexto y de que el archivo del conjunto de contexto se haya subido a la base de datos. Para obtener más información, consulta Administra conjuntos de contexto en Spanner Studio.
  • Instala y, luego, inicializa Google Cloud CLI.

Busca el ID del conjunto de contextos existente

Para probar QueryData con tu conjunto de información contextual o conectar una aplicación de datos a QueryData, necesitas el ID del conjunto de información contextual.

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

    Ir a Spanner

  2. Selecciona una instancia de la lista y, luego, una base de datos.

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

  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. Toma nota del ID del conjunto de información contextual en ID del conjunto de información contextual. El formato del ID del conjunto de información contextual es similar a projects/my-project/locations/us-central1/contextSets/fingraph-assistant.

Prueba QueryData con HTTP POST

Para probar QueryData para Spanner Graph, envía una solicitud POST HTTP QueryData que incluya el campo graph_ids y el ID del conjunto de contexto:

  1. Crea un archivo llamado request.json con el siguiente contenido:

    {
      "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
      }
    }

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • INSTANCE_ID: Es el ID de tu instancia de Spanner.
    • DATABASE_ID: Es el ID de la base de datos de Spanner.
    • CONTEXT_SET_ID: Es el ID completo del conjunto de contextos que anotaste en Busca el ID del conjunto de contextos.
  2. Envía la solicitud:

    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. En la respuesta, revisa el campo generatedQuery (GRAPH FinGraph MATCH ...) para verificar la precisión y revisa el campo queryResult para ver las filas que se devolvieron.

Para probar otras preguntas, cambia el valor de prompt en request.json y vuelve a enviar la solicitud. Para ver cómo se comporta QueryData sin el contexto creado, quita el objeto agent_context_reference.

Para verificar que QueryData use tu conjunto de contexto, haz una pregunta que dependa de él (como "¿Quién es el propietario de la cuenta de ahorros para imprevistos?") y compara las respuestas con y sin el objeto agent_context_reference. Sin el contexto establecido, QueryData podría filtrar por 'rainy day' y no devolver ninguna fila. Con el contexto establecido, se filtra en 'Rainy Day Fund' y se devuelve Dana.

Descarga y actualiza el conjunto de contextos existente

Si las respuestas de prueba muestran que la consulta de GQL generada para una pregunta en lenguaje natural necesita mejoras, descarga el archivo de conjunto de contexto existente. Luego, puedes revisar y actualizar las plantillas de consultas de GQL, las facetas o las búsquedas de valores, y subir el archivo de conjunto de contexto actualizado al conjunto de contexto.

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

  1. En el panel Explorador, haz clic en Ver acciones junto a tu conjunto de contexto.
  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 conjunto de información contextual con pares de consultas adicionales de lenguaje natural a GQL.
  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 conjunto de contexto y selecciona el archivo de conjunto de contexto actualizado.
  7. Haz clic en Guardar para actualizar el conjunto de contextos.
  8. Vuelve a probar QueryData para verificar la consulta de GQL generada.

Una vez que estés conforme con la exactitud de tus respuestas, puedes usar el extremo QueryData para conectar tu aplicación al conjunto de contexto.

Conecta QueryData a tu aplicación

Establece el ID del conjunto de contexto y el graph_ids de destino en la llamada de método QueryData para proporcionar el contexto creado y habilitar la generación de consultas de GQL para Spanner Graph. Para obtener más información sobre el uso de QueryData con fuentes de datos de bases de datos, consulta Define el contexto del agente de datos para las fuentes de datos de bases de datos. Para ver un ejemplo en el que se conecta una aplicación de agente a QueryData a través de una herramienta HTTP personalizada que llama a la API de REST de QueryData, consulta Integra QueryData en una aplicación.

Ejemplo de solicitud QueryData con contexto creado

En el siguiente ejemplo, se muestra una solicitud QueryData que usa la fuente de datos de la base de datos spanner_reference para el grafo de propiedades FinGraph. Debes proporcionar graph_ids dentro de spanner_reference.database_reference para que QueryData se oriente a tu grafo de propiedades y genere consultas de GQL. El campo agent_context_reference.context_set_id se vincula al contexto creado previamente que se almacena en la base de datos:

{
  "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
  }
}

El cuerpo de la solicitud contiene los siguientes campos:

  • parent: Opcional El proyecto y la ubicación de la solicitud, en el formato projects/PROJECT_ID/locations/LOCATION. Usa el mismo proyecto y la misma ubicación que en la URL de la solicitud.
  • prompt: Es la pregunta en lenguaje natural del usuario final.
  • context: Contiene información sobre las fuentes de datos.
    • datasource_references: Especifica la fuente de datos. Este campo es un objeto, no una lista.
      • spanner_reference: Es obligatorio cuando se consulta una base de datos de Spanner.
        • database_reference: Especifica información relacionada con tu base de datos de Spanner y los grafos de propiedades.
          • engine: Es el dialecto de la base de datos. Establécelo en GOOGLE_SQL para las bases de datos de Spanner Graph.
          • project_id: Es el ID del proyecto de la instancia de Spanner.
          • instance_id: Es el ID de la instancia de Spanner.
          • database_id: Es el ID de la base de datos de Spanner.
          • graph_ids: Es obligatorio para Spanner Graph. Es una lista de nombres de gráficos de propiedades en la base de datos que se consultará (por ejemplo, ["FinGraph"]). Proporcionar graph_ids indica a QueryData que genere consultas de GQL en los gráficos de propiedades especificados. Si omites graph_ids, QueryData solo genera consultas en SQL relacionales en las tablas subyacentes.
        • agent_context_reference: Vínculos al contexto creado en la base de datos.
          • context_set_id: Es el ID completo del conjunto de contextos almacenado en la base de datos, como projects/my-project/locations/us-central1/contextSets/fingraph-assistant.
  • generation_options: Configura el tipo de resultado que se generará.
    • generate_query_result: Se establece en true para ejecutar la consulta de GQL generada y devolver los resultados de la consulta.
    • generate_natural_language_answer: Opcional Si se establece en true, genera una respuesta en lenguaje natural que resume los resultados de la consulta.
    • generate_explanation: Opcional Si se establece en true, genera una explicación de la consulta de GQL.
    • generate_disambiguation_question: Opcional Si se establece en true, genera preguntas de desambiguación si la instrucción en lenguaje natural es ambigua.

Respuesta de ejemplo de QueryData

En el siguiente ejemplo, se muestra una respuesta correcta de una llamada QueryData en el grafo de propiedades FinGraph. La API de REST devuelve nombres de campos en camelCase, como generatedQuery y queryResult. Debido a que la generación de GQL no es determinista, la consulta generada, los nombres de las columnas y el texto de la respuesta pueden diferir entre las llamadas.

{
  "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**"
}

¿Qué sigue?