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 destinados a 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 contexto

Para compilar aplicaciones de agentes eficaces, las 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. Creas estos archivos de contexto con la ayuda de la CLI de Gemini. Luego, subes el archivo de contexto a un conjunto de contexto que creas en la Google Cloud consola. 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": "T.\"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": "T.\"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 contexto

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 en la traducción de preguntas en lenguaje natural a consultas para una base de datos específica. La definición de contexto garantiza la generación de SQL de alta precisión para patrones de consulta comunes.

Asegúrate de que el conjunto de contexto sea preciso y completo en su cobertura de las consultas de aplicaciones esperadas 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 consulta 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 para la generación de lenguaje natural a SQL.

Un objeto de plantilla de consulta 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"
      }
    }
  ]
},
...

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

• nl_query: Un ejemplo de una consulta en lenguaje natural que controlan herramientas como QueryData.
• sql: La consulta en SQL para la consulta en lenguaje natural.
• intent: El objetivo o propósito de la consulta en lenguaje natural. Si no se establece, este valor se establece de forma predeterminada en la consulta en lenguaje natural.
• manifest: Una forma generalizada y generada automáticamente de la intención.
• parameterized_intent: Una forma de plantilla generada automáticamente de la intención, con valores de entidad reemplazados por parámetros.
• parameterized_sql: Una forma de plantilla generada automáticamente de la consulta en SQL que corresponde a la intención parametrizada.

Facetas de consulta

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

Un objeto de faceta de consulta es similar al siguiente:

{
...
"facets": [
    {
      "sql_snippet": "T.\"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": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

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

• sql_snippet: Un fragmento de SQL.
• intent: Una explicación del predicado de SQL.
• manifest: Una forma generalizada y generada automáticamente de la intención.
• parameterized_intent: Una forma de plantilla generada automáticamente de la intención, con valores de entidad reemplazados por parámetros.
• parameterized_sql_snippet: Una forma de plantilla generada automáticamente del sql_snippet que corresponde a la intención parametrizada.

Consultas de búsqueda de valores

Las [consultas de búsqueda de valores](/spanner/docs/build-context-gemini-cli#generate-value-searches) son consultas 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 consultas 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. Cuando se usan consultas de búsqueda de valores, la API puede corregir errores ortográficos y resolver tipos de valores en función de 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, el SQL generado podría filtrar por WHERE name = 'Heathrow' y no mostrar ningún resultado. Las consultas de búsqueda de valores guían al agente para asignar "Heathrow" al valor correcto de la base de datos "London Heathrow" y su ubicación de esquema (airports.name), lo que garantiza que el SQL generado sea preciso.

Un ejemplo de consulta 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 componentes principales del objeto JSON de búsqueda de valores son los siguientes:

• query: 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: Una etiqueta semántica asignada al valor, por ejemplo, el district o el 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 producir una instrucción de SQL que se oriente al concepto del valor, así como a la tabla y la columna en las que aparece la frase de valor.
• description: 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 con 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, los usuarios pueden descubrir otros campos y tablas del contexto del agente.

¿Qué sigue?

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