Gerar previsões de ML usando SQL

Nesta página, mostramos como gerar previsões de machine learning (ML) de um banco de dados do Spanner. As previsões de ML funcionam com bancos de dados do dialeto GoogleSQL e do dialeto PostgreSQL.

A integração da plataforma de agentes do Spanner permite gerar previsões usando o código SQL chamando a ML.PREDICT função para o GoogleSQL ou a spanner.ML_PREDICT_ROW função para o PostgreSQL. Para mais informações sobre a integração da plataforma de agentes do Spanner, consulte Visão geral da integração da plataforma de agentes do Spanner.

Antes de começar

Antes de gerar previsões de uma instância do Spanner, prepare o banco de dados e selecione um modelo.

Configurar o acesso para a integração da plataforma de agentes do Spanner aos endpoints da Vertex AI

O Spanner cria o agente de serviço e concede as permissões necessárias automaticamente quando executa a primeira instrução DDL do modelo. Se o banco de dados do Spanner e o endpoint da Vertex AI estiverem no mesmo projeto, nenhuma configuração adicional será necessária.

Se a conta do agente de serviço do Spanner não existir para o seu projeto do Spanner, crie-a executando o comando a seguir:

gcloud beta services identity create --service=spanner.googleapis.com --project={PROJECT}`

Siga as etapas descritas em Conceder um único papel para conceder o papel Spanner API Service Agent à conta de agente de serviço do Spanner [e-mail] no seu projeto da Vertex AI.

Selecione um modelo

Ao usar a função ML.PREDICT (para GoogleSQL) ou spanner.ML_PREDICT_ROW (para PostgreSQL), você precisa especificar o local do modelo de ML. O modelo selecionado pode ser um dos seguintes:

• Um modelo em execução no Model Garden da Vertex AI.

• Um modelo da Vertex AI com um endpoint ativo a que o agente de serviço do Spanner tem permissão de IAM para acessar.

Para saber mais sobre a integração da plataforma de agentes do Spanner, consulte Como funciona a integração da plataforma de agentes do Spanner?.

gere previsões

Dependendo do tipo de modelo selecionado, as etapas para gerar as previsões serão diferentes.

Usar um modelo no Model Garden da Vertex AI

Para gerar uma previsão usando um modelo do Model Garden da Vertex AI, selecione um modelo no Model Garden.

GoogleSQL

Antes de usar um modelo com ML.PREDICT(), registre-o usando a instrução CREATE MODEL.

CREATE MODEL 'MODEL_NAME'
INPUT (INPUT_COLUMN_NAME INPUT_COLUMN_TYPE)
OUTPUT (OUTPUT_COLUMN_NAME OUTPUT_COLUMN_TYPE)
REMOTE
OPTIONS (
  endpoint = '//aiplatform.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/publishers/google/models/model_id'
);

Substitua:

• MODEL_NAME: o nome que você quer dar ao modelo

• INPUT_COLUMN_NAME: o nome da coluna de entrada. Por exemplo, se você estiver usando o modelo gemini-pro, o nome da coluna de entrada será prompt.

• INPUT_COLUMN_TYPE: o tipo de dados para INPUT_COLUMN_NAME

• OUTPUT_COLUMN_NAME: o nome da coluna de saída. Por exemplo, se você estiver usando o modelo gemini-pro, o nome da coluna de saída será content.

• OUTPUT_COLUMN_TYPE: o tipo de dados para OUTPUT_COLUMN_NAME

• PROJECT_ID: o ID do Google Cloud projeto

• REGION_ID: o ID daregião em que o modelo está localizado. Por exemplo, us-central1 Google Cloud

• MODEL_ID: o ID do modelo de ML que você quer usar. Por exemplo, gemini-pro

  Para mais informações sobre modelos, consulte Referência da API modelo para IA generativa.

Use a função ML.PREDICT GoogleSQL com o modelo selecionado no Model Garden para gerar a previsão.

SELECT * FROM ML.PREDICT(
  MODEL `MODEL_NAME`,
  `INPUT_RELATION`[, `PARAMETERS`])

Substitua:

• MODEL_NAME: o nome que você quer dar ao modelo

  Para mais informações sobre modelos, consulte Referência da API modelo para IA generativa.

• INPUT_RELATION: TABLE table_name ou uma subconsulta da tabela ou subconsulta que fornece dados para executar a previsão de ML.

• PARAMETERS: um valor STRUCT que contém parâmetros compatíveis com model_id.

Você também pode usar SAFE.ML.PREDICT para retornar null em vez de um erro nas previsões. Isso é útil em casos em que a execução de consultas grandes em que algumas previsões falhas são toleráveis.

PostgreSQL

Use a função ML_PREDICT_ROW do PostgreSQL com o modelo selecionado no Model Garden para gerar a previsão.

SELECT spanner.ml_predict_row(
  'projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID'::text,
  '{
    "instances": [ INSTANCES ],
    "parameters": { PARAMETERS }
   }'::jsonb);

Substitua:

• PROJECT_ID: o ID do Google Cloud projeto

• REGION_ID: o ID daregião em que o modelo está localizado. Por exemplo, us-central1 Google Cloud

• MODEL_ID: o ID do modelo de ML que você quer usar. Por exemplo, gemini-pro

  Para mais informações sobre modelos, consulte Referência da API modelo para IA generativa.

• INSTANCES: as entradas para a chamada de previsão, no formato JSON

• PARAMETERS: parâmetros opcionais para a chamada de previsão, no formato JSON

Essa consulta produz uma resposta JSON. Para informações sobre as mensagens de resposta JSON do modelo, consulte PredictResponse.

Usar um endpoint de modelo da Vertex AI

Para usar um modelo treinado ou transferido por download com a integração da plataforma de agentes do Spanner, implante o modelo na Vertex AI. Para mais informações sobre como implantar um modelo em um endpoint na Vertex AI, consulte Implantar um modelo em um endpoint.

GoogleSQL

Use a função ML.PREDICT do GoogleSQL com o modelo em um endpoint da Vertex AI para gerar a previsão. Antes de usar um modelo com ML.PREDICT(), registre-o usando a instrução CREATE MODEL. Cada modelo implantado tem seu próprio esquema exclusivo. Confira a seguir um exemplo de esquema de Visão geral de classificação e regressão

CREATE MODEL MyClassificationModel
INPUT (
  length FLOAT64,
  material STRING(MAX),
  tag_array ARRAY<STRING(MAX)>
)
OUTPUT (
  scores ARRAY<FLOAT64>,
  classes ARRAY<STRING(MAX)>
)
REMOTE
OPTIONS (
  endpoint = '//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID'
)

Substitua:

• PROJECT_ID: o ID do Google Cloud projeto

• LOCATION: o ID da Google Cloud região em que o modelo está localizado. Por exemplo, us-central1

• ENDPOINT_ID: o ID do modelo de ML que você quer usar. Por exemplo, gemini-pro

  Para mais informações sobre modelos, consulte Referência da API modelo para IA generativa.

Use a função ML.PREDICT GoogleSQL com o modelo selecionado no Model Garden para gerar a previsão.

SELECT * FROM ML.PREDICT(
  `MODEL_ID`,
  `INPUT_RELATION`[, `PARAMETERS`])

Substitua:

• MODEL_ID: o ID do modelo de ML que você quer usar.

• INPUT_RELATION: a tabela ou subconsulta em que você quer executar a previsão de ML.

• PARAMETERS: um valor STRUCT que contém parâmetros compatíveis com model_name.

Essa consulta produz uma relação que contém todas as colunas de saída do modelo e todas as colunas da relação de entrada.

PostgreSQL

Use a função ML.PREDICT do PostgreSQL com o modelo em um endpoint da Vertex AI para gerar a previsão.

  SELECT spanner.ml_predict_row(
    'projects/PROJECT_ID/locations/REGION_ID/endpoints/ENDPOINT_ID'::text,
    '{
      "instances": [ INSTANCES ],
      "parameters": { PARAMETERS }
      }'::jsonb);
  ```

Replace the following:

• PROJECT_ID: o ID do Google Cloud projeto em que o modelo está localizado

• REGION_ID: o ID da Google Cloud região em que o modelo está localizado. Por exemplo, us-central1

• ENDPOINT_ID: o ID do endpoint do modelo

• INSTANCES: as entradas para a chamada de previsão, no formato JSON

• PARAMETERS: parâmetros opcionais para a chamada de previsão, no formato JSON

Essa consulta produz uma resposta JSON. Para informações sobre as mensagens de resposta JSON do modelo, consulte PredictResponse.

Exemplos de uso de funções de ML para gerar previsões

Visualização — Gemini no Spanner

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

O exemplo a seguir usa o gemini-pro modelo, do Model Garden, para gerar texto com base em um breve comando fornecido como argumento. Esse modelo está disponível como parte do Gemini no Spanner.

GoogleSQL

Registrar o modelo gemini-pro

CREATE MODEL GeminiPro
INPUT (prompt STRING(MAX))
OUTPUT (content STRING(MAX))
REMOTE
OPTIONS (
  endpoint = '//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/publishers/google/models/gemini-pro',
  default_batch_size = 1
);

Substitua:

• PROJECT: o ID do projeto
• LOCATION: a região em que você está usando a Vertex AI

Executar o modelo

SELECT content
FROM ML.PREDICT(
  MODEL GeminiPro,
  (SELECT "Is 7 a prime number?" AS prompt),
  STRUCT(256 AS maxOutputTokens, 0.2 AS temperature, 40 as topK, 0.95 AS topP)
);

Saída esperada

A saída esperada é a seguinte:

+--------------------+
| content            |
+--------------------+
| "Yes"              |
+--------------------+

PostgreSQL

Executar o modelo

select spanner.ml_predict_row(
  '{
    "endpoint": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-pro",
    "default_batch_size": 1
   }'::jsonb,
  '{
    "instances":[{"prompt": "Is 7 a prime number?"}],
    "parameters":{"maxOutputTokens":256, "topK": 40, "topP":0.96, "temperature":0.2}
    }'
);

Saída esperada

A saída esperada é a seguinte:

+--------------------+
| content            |
+--------------------+
| "Yes"              |
+--------------------+