Genera datos estructurados con la función AI.GENERATE_TABLE

En este documento, se muestra cómo generar datos estructurados con un modelo Gemini Pro 1.5, Gemini Flash 1.5 o Gemini Flash 2.0 y, luego, dar formato a la respuesta del modelo con un esquema SQL.

Para ello, completa las siguientes tareas:

• Crea un modelo remoto de BigQuery ML que represente un modelo Gemini 1.5 o 2.0 de Vertex AI alojado.
• Usar el modelo con la función AI.GENERATE_TABLE para generar datos estructurados basados en datos de tablas estándar

Permisos necesarios

• Para crear una conexión, necesitas membresía en el siguiente rol de Identity and Access Management (IAM):

  • roles/bigquery.connectionAdmin

• Para otorgar permisos a la cuenta de servicio de la conexión, necesitas el siguiente permiso:

  • resourcemanager.projects.setIamPolicy

• Para crear el modelo con BigQuery ML, necesitas los siguientes permisos de IAM:

  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

• Para ejecutar inferencias, necesitas los siguientes permisos:

  • bigquery.tables.getData en la tabla
  • bigquery.models.getData en el modelo
  • bigquery.jobs.create

Antes de comenzar

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

2. Make sure that billing is enabled for your Google Cloud project.

3. Enable the BigQuery, BigQuery Connection, and Vertex AI APIs.

   Enable the APIs

Crear una conexión

Crea una conexión de recurso de Cloud y obtén la cuenta de servicio de la conexión.

Selecciona una de las opciones siguientes:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Otorga acceso a la cuenta de servicio

Otorga a la cuenta de servicio de la conexión el rol de usuario de Vertex AI.

Si planeas especificar el extremo como una URL cuando crees el modelo remoto, por ejemplo, endpoint = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/publishers/google/models/gemini-1.5-flash', otorga este rol en el mismo proyecto que especifiques en la URL.

Si planeas especificar el extremo con el nombre del modelo cuando crees el modelo remoto, por ejemplo, endpoint = 'gemini-1.5-flash', otorga este rol en el mismo proyecto en el que planeas crear el modelo remoto.

Si otorgas el rol en un proyecto diferente, se produce el error bqcx-1234567890-xxxx@gcp-sa-bigquery-condel.iam.gserviceaccount.com does not have the permission to access resource.

Para otorgar el rol, sigue estos pasos:

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/aiplatform.user' --condition=None

Crea un modelo remoto de BigQuery ML

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

   Ir a BigQuery

2. Crea un modelo remoto con el editor de SQL:

   CREATE OR REPLACE MODEL
   `PROJECT_ID.DATASET_ID.MODEL_NAME`
   REMOTE WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS (ENDPOINT = 'ENDPOINT');

   Reemplaza lo siguiente:

   • PROJECT_ID: el ID de tu proyecto
   • DATASET_ID: El ID del conjunto de datos que contendrá el modelo. Este conjunto de datos debe estar en la misma ubicación que la conexión que usas
   • MODEL_NAME: Es el nombre del modelo.
   • REGION: la región que usa la conexión.
   • CONNECTION_ID: el ID de tu conexión de BigQuery

     Cuando ves los detalles de conexión en la consola de Google Cloud, este es el valor en la última sección del ID de conexión completamente calificado que se muestra en Conexión ID, por ejemplo, projects/myproject/locations/connection_location/connections/myconnection.

   • ENDPOINT: Es el nombre del modelo de Gemini que se usará. Se admiten los siguientes modelos:
     • gemini-2.0-flash-001
     • gemini-1.5-flash-001
     • gemini-1.5-flash-002
     • gemini-1.5-pro-001
     • gemini-1.5-pro-002
     Para obtener más información, consulta ENDPOINT.

Genera datos estructurados

Para generar datos estructurados, usa la función AI.GENERATE_TABLE con un modelo remoto y usa los datos de la instrucción de una columna de tabla:

SELECT *
FROM AI.GENERATE_TABLE(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  [TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME` / (PROMPT_QUERY)],
  STRUCT(TOKENS AS max_output_tokens, TEMPERATURE AS temperature,
  TOP_P AS top_p, STOP_SEQUENCES AS stop_sequences,
  SAFETY_SETTINGS AS safety_settings,
  OUTPUT_SCHEMA AS output_schema)
);

Reemplaza lo siguiente:

• PROJECT_ID: el ID de tu proyecto
• DATASET_ID: El ID del conjunto de datos que contiene el modelo.
• MODEL_NAME: el nombre del modelo
• TABLE_NAME: Es el nombre de la tabla que contiene el mensaje. Esta tabla debe tener una columna llamada prompt, o puedes usar un alias para usar una columna con nombre diferente.
• PROMPT_QUERY: Es la consulta de GoogleSQL que genera los datos del mensaje. El valor de la instrucción puede extraerse de una columna o puedes especificarlo como un valor de struct con una cantidad arbitraria de subcampos de cadena y nombre de columna. Por ejemplo:SELECT ('Analyze the sentiment in ', feedback_column, 'using the following categories: positive, negative, neutral') AS prompt
• TOKENS: Un valor INT64 que establece la cantidad máxima de tokens que se pueden generar en la respuesta. Este valor debe estar en el rango [1,8192]. Especifica un valor más bajo para respuestas más cortas y un valor más alto para respuestas más largas. El valor predeterminado es 128.
• TEMPERATURE: Un valor FLOAT64 en el rango [0.0,2.0] que controla el grado de aleatorización en la selección de tokens. El valor predeterminado es 1.0.

  Los valores más bajos para temperature son buenos para las instrucciones que requieren una respuesta más determinística y menos abierta o creativa, mientras que los valores más altos para temperature pueden generar resultados más diversos o creativos. Un valor de 0 para temperature es determinístico, lo que significa que siempre se selecciona la respuesta de mayor probabilidad.

• TOP_P: Un valor FLOAT64 en el rango [0.0,1.0] ayuda a determinar la probabilidad de los tokens seleccionados. Especifica un valor más bajo para respuestas menos aleatorias y un valor más alto para respuestas más aleatorias. El valor predeterminado es 0.95.
• STOP_SEQUENCES: Un valor ARRAY<STRING> que quita las cadenas especificadas si se incluyen en respuestas del modelo. Las cadenas coinciden de forma exacta, incluido el uso de mayúsculas. El valor predeterminado es un array vacío.
• SAFETY_SETTINGS: Un valor ARRAY<STRUCT<STRING AS category, STRING AS threshold>> que configura umbrales de seguridad del contenido para filtrar las respuestas. El primer elemento de la estructura especifica una categoría de daño, y el segundo elemento especifica un umbral de bloqueo correspondiente. El modelo filtra el contenido que incumple esta configuración. Solo puedes especificar cada categoría una vez. Por ejemplo, no puedes especificar STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_MEDIUM_AND_ABOVE' AS threshold) y STRUCT('HARM_CATEGORY_DANGEROUS_CONTENT' AS category, 'BLOCK_ONLY_HIGH' AS threshold) a la vez. Si no hay un parámetro de configuración de seguridad para una categoría determinada, se usa el parámetro de configuración de seguridad BLOCK_MEDIUM_AND_ABOVE.

  Las categorías admitidas son las siguientes:

  • HARM_CATEGORY_HATE_SPEECH
  • HARM_CATEGORY_DANGEROUS_CONTENT
  • HARM_CATEGORY_HARASSMENT
  • HARM_CATEGORY_SEXUALLY_EXPLICIT

  Los umbrales admitidos son los siguientes:

  • BLOCK_NONE (Restringido)
  • BLOCK_LOW_AND_ABOVE
  • BLOCK_MEDIUM_AND_ABOVE (predeterminado)
  • BLOCK_ONLY_HIGH
  • HARM_BLOCK_THRESHOLD_UNSPECIFIED

  Para obtener más información, consulta Categorías de daño y Cómo configurar filtros de contenido.

• OUTPUT_SCHEMA: Es un valor STRING que especifica el formato de la respuesta del modelo. El valor de output_schema debe ser una definición de esquema SQL, similar a la que se usa en la sentencia CREATE TABLE. Se admiten los siguientes tipos de datos:
  • INT64
  • FLOAT64
  • BOOL
  • STRING
  • ARRAY
  • STRUCT

  Para los modelos de Gemini 1.5, solo especifica un tipo de datos FLOAT64 si tienes la certeza de que el valor que se muestra no será un número redondo. Estos modelos, a veces, pueden mostrar valores INT64 en lugar de valores FLOAT64 para números redondos, por ejemplo, 2 en lugar de 2.0, y esto puede provocar un error de análisis en la consulta.

  Cuando usas el argumento output_schema para generar datos estructurados en función de instrucciones de una tabla, es importante comprender los datos de la instrucción para especificar un esquema adecuado.

  Por ejemplo, supongamos que analizas el contenido de las opiniones de películas de una tabla que tiene los siguientes campos:

  • movie_id
  • review
  • mensaje

  Luego, puedes crear texto de instrucciones ejecutando una consulta similar a la siguiente:

  UPDATE mydataset.movie_review
  SET prompt = CONCAT('Extract the key words and key sentiment from the text below: ', review)
  WHERE review IS NOT NULL;

  También puedes especificar un valor output_schema similar a "keywords ARRAY<STRING>, sentiment STRING" AS output_schema.

Ejemplos

En el siguiente ejemplo, se muestra una solicitud que toma datos de instrucciones de una tabla y proporciona un esquema de SQL para dar formato a la respuesta del modelo:

SELECT
*
FROM
AI.GENERATE_TABLE( MODEL `mydataset.gemini_model`,
  TABLE `mydataset.mytable`,
  STRUCT("keywords ARRAY<STRING>, sentiment STRING" AS output_schema));

En el siguiente ejemplo, se muestra una solicitud que toma datos de instrucciones de una consulta y proporciona un esquema de SQL para dar formato a la respuesta del modelo:

SELECT *
FROM
  AI.GENERATE_TABLE(
    MODEL `mydataset.gemini_model`,
    (
      SELECT
        'John Smith is a 20-year old single man living at 1234 NW 45th St, Kirkland WA, 98033. He has two phone numbers 123-123-1234, and 234-234-2345. He is 200.5 pounds.'
          AS prompt
    ),
    STRUCT("address STRUCT<street_address STRING, city STRING, state STRING, zip_code STRING>, age INT64, is_married BOOL, name STRING, phone_number ARRAY<STRING>, weight_in_pounds FLOAT64"
        AS output_schema));