Invocar previsões

A extensão google_ml_integration no AlloyDB para PostgreSQL permite invocar previsões on-line de modelos de machine learning diretamente nas suas consultas SQL. É possível chamar a função ml_predict_row() no esquema public para modelos genéricos hospedados na Gemini Enterprise Agent Platform sem registrar um endpoint ou chamar a função google_ml.predict_row() no esquema google_ml para modelos registrados com o gerenciamento de endpoints de modelo.

Para invocar previsões, selecione um dos esquemas a seguir.

Antes de começar

Para permitir que o AlloyDB invoque previsões, faça o seguinte:

Invocar previsões on-line

Use a função SQL ml_predict_row() para invocar previsões on-line nos seus dados.

O formato do argumento inicial da função depende se o modelo de ML que você quer usar está no Model Garden ou é um endpoint em execução em um projeto do Google Cloud .

Usar um modelo no Model Garden

Para invocar uma previsão on-line usando um modelo de ML em execução no Model Garden, use a seguinte sintaxe para a função SQL ml_predict_row():

SELECT ml_predict_row('projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID', '{ CONTENTS }');

Substitua:

  • PROJECT_ID: ID do projeto do Google Cloud

  • REGION_ID: o ID da região do Google Cloud ou do local do endpoint em que o modelo está, por exemplo, global para gemini-3.5-flash-lite, ou uma região com disponibilidade, como us-central1.

  • MODEL_ID: o ID do modelo de ML a ser usado, incluindo o sufixo do método (:generateContent ou :streamGenerateContent) para modelos do Gemini, por exemplo, gemini-3.5-flash-lite:generateContent ou gemini-3.5-flash-lite:streamGenerateContent

  • CONTENTS: as entradas para a chamada de previsão, no formato JSON. Por exemplo, "contents": [{"role": "user", "parts": [{"text": "..."}]}] para modelos do Gemini ou "instances": [...] para outros modelos da plataforma de agentes.

Se o modelo de ML estiver armazenado no mesmo projeto e região que o cluster do AlloyDB, será possível abreviar o primeiro argumento desta função:

SELECT ml_predict_row('publishers/google/models/MODEL_ID', '{ CONTENTS }');

Para informações sobre as mensagens de resposta JSON do modelo, consulte Referência do modelo básico de IA generativa.

Para obter exemplos, consulte Invocações de exemplo.

Usar um endpoint de modelo da Agent Platform

Para invocar uma previsão on-line usando um endpoint de modelo da Agent Platform, use a seguinte sintaxe para a função SQL ml_predict_row():

SELECT ml_predict_row('projects/PROJECT_ID/locations/REGION_ID/endpoints/ENDPOINT_ID', '{ CONTENTS }');

Substitua:

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

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

  • ENDPOINT_ID: o ID do endpoint do modelo

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

Se o endpoint estiver localizado no mesmo projeto e região que o cluster do AlloyDB, será possível abreviar o primeiro argumento dessa função:

SELECT ml_predict_row('endpoints/ENDPOINT_ID', '{ CONTENTS }');

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

Invocações de exemplo

O exemplo a seguir usa o gemini-3.5-flash-lite, disponível no Model Garden, para gerar texto com base em um comando curto fornecido como um argumento literal para ml_predict_row():

SELECT
  json_array_elements(ml_predict_row('publishers/google/models/gemini-3.5-flash-lite:streamGenerateContent',
      '{ "contents": [ { "role": "user", "parts": [ { "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
} ] } ] }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

A resposta é um objeto JSON. Para mais informações sobre o formato do objeto, consulte Corpo da resposta.

O exemplo a seguir modifica o anterior das seguintes maneiras:

Primeiro, crie uma tabela messages de amostra, se ainda não tiver uma:

CREATE TABLE IF NOT EXISTS messages (message TEXT);
INSERT INTO messages (message) VALUES ('Why is the sky blue?');

Em seguida, invoque ml_predict_row() na tabela messages:

SELECT
  ml_predict_row(
    'projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash-lite:generateContent',
    json_build_object(
      'contents',
      json_build_array(
        json_build_object(
          'role', 'user',
          'parts', json_build_array(
            json_build_object('text', message)
          )
        )
      )
    )
  )
FROM messages;

O objeto JSON retornado contém uma matriz candidates para cada linha na tabela messages.

Como a resposta é um objeto JSON, é possível extrair campos específicos dele usando o operador de seta do PostgreSQL:

SELECT
  ml_predict_row(
    'projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash-lite:generateContent',
    json_build_object(
      'contents',
      json_build_array(
        json_build_object(
          'role', 'user',
          'parts', json_build_array(
            json_build_object('text', message)
          )
        )
      )
    )
  ) -> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text'
FROM messages;

Para mais exemplos de argumentos para ml_predict_row(), consulte o Guia de início rápido sobre como usar a API Agent Platform.

A seguir