Descripción general de los conjuntos de contexto

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio y las Condiciones Adicionales para Productos de IA Generativa en Versión Preliminar. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Nota de la interfaz de PostgreSQL: Los ejemplos de este tema están diseñados para bases de datos con dialecto de GoogleSQL. Esta función no admite la interfaz de PostgreSQL.

Un conjunto de contexto es una colección de información específica de la base de datos que permite que herramientas como QueryData generen consultas con alta precisión. El conjunto de contexto incluye plantillas, facetas y búsquedas de valores que ayudan a QueryData a comprender el esquema de tu base de datos y la lógica empresarial de tus aplicaciones.

Se admiten las siguientes bases de datos:

• AlloyDB para PostgreSQL
• Cloud SQL para MySQL
• Cloud SQL para PostgreSQL
• Spanner

Qué son los conjuntos de contextos

Para crear aplicaciones basadas en agentes eficaces, herramientas como QueryData deben comprender la organización de tus datos y la lógica empresarial. Proporcionas esta información en forma de conjunto de contexto.

Defines el contexto en archivos que contienen objetos JSON para cada tipo de contexto. Estos archivos de contexto se crean con la ayuda de la CLI de Gemini. Luego, subirás el archivo de contexto a un conjunto de contexto que crearás en la consola de Google Cloud. Este proceso permite que herramientas como QueryData aprendan el esquema específico de la base de datos y la lógica empresarial de la aplicación.

El archivo de contexto es similar al siguiente:

{
  "templates": [
    {
      "nl_query": "Count Prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" ='Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
      "concept_type": "Account Type",
      "description": "Exact match for account types"
    }
   ]
}

Formato del archivo de conjunto de contextos

El archivo de conjunto de contexto consta de un conjunto seleccionado de plantillas y facetas en formato JSON que guían a herramientas como QueryData para traducir preguntas en lenguaje natural en consultas para una base de datos específica. Definir el contexto garantiza una generación de SQL de alta precisión para los patrones de consultas comunes.

Asegúrate de que el conjunto de contexto sea preciso y completo en su cobertura de las búsquedas esperadas de la aplicación para maximizar la precisión.

Los conjuntos de contexto se pueden crear en las regiones us-central1, us-east1, europe-west4 y asia-southeast1.

Plantillas de consulta

Las plantillas de preguntas son un conjunto seleccionado de preguntas representativas en lenguaje natural con las consultas en SQL correspondientes. También incluyen explicaciones para proporcionar una justificación declarativa de la generación de lenguaje natural a SQL.

Un objeto de plantilla de consulta tiene un aspecto similar al siguiente:

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ]
},
...

Los componentes principales del objeto JSON de la plantilla de consulta son los siguientes:

• nl_query: Ejemplo de una búsqueda en lenguaje natural que controlan herramientas como QueryData.
• sql: Es la consulta en SQL para la consulta en lenguaje natural.
• intent: Es el objetivo o propósito de la búsqueda en lenguaje natural. Si no se establece, este valor se establece de forma predeterminada en la búsqueda en lenguaje natural.
• manifest: Es una forma generalizada y generada automáticamente del intent.
• parameterized_intent: Es una forma de la intent generada automáticamente y basada en plantillas, con valores de entidades reemplazados por parámetros.
• parameterized_sql: Es una forma de plantilla generada de forma automática de la consulta en SQL que corresponde a la intención parametrizada.

Facetas de búsqueda

Las facetas de búsqueda son un conjunto seleccionado de condiciones representativas en lenguaje natural con predicados SQL correspondientes. Las facetas administran los filtros y las condiciones, lo que permite que las plantillas de búsqueda realicen búsquedas por facetas.

Un objeto de faceta de búsqueda es similar al siguiente:

{
...
"facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

Los componentes principales del objeto JSON de faceta son los siguientes:

• sql_snippet: Es un fragmento de SQL. Para evitar ambigüedades, califica los nombres de las columnas con los nombres de las tablas (por ejemplo, table_name.column_name).
• intent: Es una explicación del predicado de SQL.
• manifest: Es una forma generalizada y generada automáticamente del intent.
• parameterized_intent: Es una forma de la intent generada automáticamente y basada en plantillas, con valores de entidades reemplazados por parámetros.
• parameterized_sql_snippet: Es una forma de sql_snippet generada automáticamente y basada en plantillas que corresponde a la intención parametrizada.

Búsquedas de valor

Las búsquedas de valores son búsquedas definidas por el desarrollador que usan funciones de coincidencia para encontrar valores y su contexto dentro de una base de datos. La vinculación de valores usa los resultados de estas búsquedas para identificar qué tablas y columnas contienen un valor coincidente, comprender el tipo de concepto del valor y corregir errores ortográficos.

La API de QueryData usa la vinculación de valores para convertir el lenguaje natural en SQL con mayor precisión. Con las búsquedas por valor, la API puede corregir errores ortográficos y resolver tipos de valores según los valores de la base de datos, lo que mejora la precisión de la conversión.

La vinculación de valores mejora la precisión de la conversión de lenguaje natural a SQL. Por ejemplo, si un usuario pregunta: "¿Hay vuelos desde Heathrow?", la base de datos podría almacenar el nombre del aeropuerto como "London Heathrow". Sin la vinculación de valores, es posible que el SQL generado filtre por WHERE name = 'Heathrow' y no muestre resultados. Las búsquedas de valores guían al agente para que asigne "Heathrow" al valor de base de datos correcto "London Heathrow" y a su ubicación de esquema (airports.name), lo que garantiza que el código SQL generado sea preciso.

Un ejemplo de búsqueda de valores es el siguiente:

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    }
  ]
}

Los principales componentes del objeto JSON de búsqueda de valores son los siguientes:

• query: Es una instrucción de SQL parametrizada que define la lógica para hacer coincidir una frase de valor con los valores almacenados en una columna de una tabla en una base de datos. Por lo general, el conjunto de resultados proyecta el valor coincidente, la ubicación del esquema, el tipo de concepto y una métrica de distancia normalizada (entre 0 y 1).
• concept_type: Es una etiqueta semántica asignada al valor, por ejemplo, district o loan_status. Esta etiqueta ayuda a la vinculación de valores y, finalmente, a las herramientas, como la API de QueryData, a comprender el rol de la frase de valor en el esquema. También ayuda a generar una instrucción de SQL que se dirige al concepto del valor, así como a la tabla y la columna en las que aparece la frase del valor.
• description: Es una descripción de la lógica de búsqueda.

Limitaciones

Los conjuntos de contexto tienen las siguientes limitaciones:

• Los conjuntos de contexto para bases de datos solo admiten plantillas, facetas y búsquedas de valores.
• Los conjuntos de contexto para bases de datos solo los usa el extremo QueryData en la API de Conversational Analytics.

Advertencia: Todos los contextos de agentes asociados con una base de datos son visibles para todos los usuarios que tengan acceso de lectura a esa base de datos. En los casos en que los usuarios tienen un acceso más limitado a la base de datos, como el control de acceso detallado de Spanner, es posible que descubran otros campos y tablas del contexto del agente.

¿Qué sigue?

• Obtén más información para crear o borrar un conjunto de contexto en Spanner Studio.