Registrar e chamar modelos de IA remotos usando o gerenciamento de endpoints de modelo

Nesta página, descrevemos como invocar previsões ou gerar incorporações usando um modelo, registrando o endpoint do modelo com o gerenciamento de endpoints de modelo.

Antes de começar

• Verifique se a extensão google_ml_integration está instalada.

• Verifique se a flag google_ml_integration.enable_model_support está definida como on

Configurar a extensão

1. Conecte-se ao banco de dados usando psql ou o AlloyDB para PostgreSQL Studio usando o usuário postgres.

2. Opcional: Solicite acesso para interagir com os recursos das funções de IA do AlloyDB para PostgreSQL (prévia), incluindo suporte para modelos multimodais, modelos de classificação e funções de operador.

3. Opcional: conceda permissão a um usuário do PostgreSQL que não seja superusuário para gerenciar metadados do modelo:

     GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;
   

   Substitua a seguinte variável:

   • NON_SUPER_USER: o nome de usuário do PostgreSQL que não é superusuário.

4. Verifique se o IP de saída está ativado para acessar modelos hospedados fora da sua VPC, como modelos de terceiros. Para mais informações, consulte Adicionar conectividade de saída.

Configurar a autenticação

As seções a seguir mostram como configurar a autenticação antes de registrar um endpoint de modelo.

Integrar com a Vertex AI e instalar a extensão

Para usar os endpoints de modelo da Vertex AI, adicione permissões da Vertex AI à conta de serviço do AlloyDB baseada no IAM que você usa para se conectar ao banco de dados.

1. Configure o acesso do usuário aos modelos da Vertex AI.
2. Verifique se a versão mais recente do google_ml_integration está instalada.

   1. Para verificar a versão instalada, execute o seguinte comando:

              SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
              extversion 
              ------------
              1.5.2
              (1 row)
            

   2. Se a extensão não estiver instalada ou se a versão instalada for anterior à 1.5.2, atualize a extensão.

              CREATE EXTENSION IF NOT EXISTS google_ml_integration;
              ALTER EXTENSION google_ml_integration UPDATE;
            

      Se você tiver problemas ao executar os comandos anteriores ou se a extensão não for atualizada para a versão 1.5.2 depois de executar os comandos anteriores, entre em contato com o suporte doGoogle Cloud .

3. Para usar a funcionalidade do mecanismo de consulta da IA do AlloyDB, defina a flag google_ml_integration.enable_ai_query_engine como true.

   SQL

   1. Ative o mecanismo de consulta de IA para a sessão atual.
      

                    SET google_ml_integration.enable_ai_query_engine = true;
                    

   2. Ativar recursos para um banco de dados específico em várias sessões.
      

                    ALTER DATABASE DATABASE_NAME SET google_ml_integration.enable_ai_query_engine = 'on';
                    

   3. Ative o mecanismo de consulta de IA para um usuário específico em sessões e bancos de dados.
      

                    ALTER ROLE postgres SET google_ml_integration.enable_ai_query_engine = 'on';
                  

   Console

   Para modificar o valor da flag google_ml_integration.enable_ai_query_engine, siga as etapas em Configurar flags de bancos de dados de uma instância.

   gcloud

   Para usar a gcloud CLI, você pode instalar e inicializar a CLI do Google Cloud ou usar o Cloud Shell.

   É possível modificar o valor da flag google_ml_integration.enable_ai_query_engine. Para mais informações, consulte Configurar flags de banco de dados de uma instância.

                gcloud alloydb instances update INSTANCE_ID \
                  --database-flags google_ml_integration.enable_ai_query_engine=on \
                  --region=REGION_ID \
                  --cluster=CLUSTER_ID \
                  --project=PROJECT_ID
               

Configurar a autenticação usando o Secret Manager

Nesta seção, explicamos como configurar a autenticação se você estiver usando o Secret Manager para armazenar detalhes de autenticação de provedores terceirizados.

Esta etapa é opcional se o endpoint do modelo não processar a autenticação pelo Secret Manager. Por exemplo, se o endpoint do modelo usar cabeçalhos HTTP para transmitir informações de autenticação ou não usar autenticação.

Para criar e usar uma chave de API ou um token de acesso, siga estas etapas:

1. Crie o secret no Secret Manager. Para mais informações, consulte Criar um secret e acessar uma versão dele.

   O caminho secreto é usado na função SQL google_ml.create_sm_secret().

2. Conceda permissões ao cluster do AlloyDB para acessar o secret.

     gcloud secrets add-iam-policy-binding 'SECRET_NAME' \
         --member="serviceAccount:SERVICE_ACCOUNT_ID" \
         --role="roles/secretmanager.secretAccessor"
   

   Substitua:

   • SECRET_NAME: o nome do secret no Secret Manager.

   • SERVICE_ACCOUNT_ID: o ID da conta de serviço baseada no IAM no formato serviceAccount:[e-mail]. Por exemplo, [e-mail].

     Também é possível conceder esse papel à conta de serviço no nível do projeto. Para mais informações, consulte Adicionar uma vinculação de política do Identity and Access Management.

Configurar a autenticação usando cabeçalhos

O exemplo a seguir mostra como configurar a autenticação usando uma função. A função retorna um objeto JSON que contém os cabeçalhos necessários para fazer uma solicitação ao modelo de embedding.

  CREATE OR REPLACE FUNCTION HEADER_GEN_FUNCTION(
    model_id VARCHAR(100),
    input_text TEXT
  )
  RETURNS JSON
  LANGUAGE plpgsql
  AS $$
  #variable_conflict use_variable
  DECLARE
    api_key VARCHAR(255) := 'API_KEY';
    header_json JSON;
  BEGIN
    header_json := json_build_object(
      'Content-Type', 'application/json',
      'Authorization', 'Bearer ' || api_key
    );
    RETURN header_json;
  END;
  $$;

Substitua:

• HEADER_GEN_FUNCTION: o nome da função de geração de cabeçalho que você pode usar ao registrar um modelo.
• API_KEY: a chave de API do provedor do modelo.

Modelos de embedding de texto

Nesta seção, mostramos como registrar endpoints de modelo com o gerenciamento de endpoints de modelo.

O gerenciamento de endpoints de modelo é compatível com alguns modelos de embedding de texto e genéricos da Vertex AI como endpoints de modelo pré-registrados. Você pode usar diretamente o ID do modelo para gerar embeddings ou invocar previsões, com base no tipo de modelo. Para mais informações sobre os modelos pré-registrados compatíveis, consulte Modelos pré-registrados da Vertex AI.

Observação: o suporte a modelos da Vertex AI é regido pelas diretrizes de controle de versão e ciclo de vida de modelos da Vertex AI. Para mais informações sobre versões estáveis, consulte Versões e ciclo de vida do modelo.

O modelo gemini-embedding-001 está disponível apenas na região us-central1.

Por exemplo, para chamar o modelo gemini-embedding-001 pré-registrado, você pode chamar diretamente o modelo usando a função de incorporação:

SELECT
      embedding(
        model_id => 'gemini-embedding-001',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');

Se o cluster do AlloyDB e o endpoint da Vertex AI estiverem em projetos diferentes, defina model_id como o caminho qualificado do endpoint, por exemplo, projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/gemini-embedding-001.

Da mesma forma, para chamar o modelo gemini-1.5-pro:generateContent pré-registrado, você pode chamar diretamente o modelo usando a função de previsão:

 SELECT google_ml.predict_row(
            model_id => 'gemini-1.5-pro:generateContent',
            request_body => '{
        "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. Only provide SQL query with no explanation."
                    }
                ]
            }
        ]
        }')-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

Para gerar embeddings, saiba como gerar embeddings de texto. Para invocar previsões, saiba como invocar previsões.

Modelos de embedding de texto com suporte integrado

O gerenciamento de endpoints de modelo oferece suporte integrado a alguns modelos da Vertex AI e da OpenAI. Para conferir a lista de modelos com suporte integrado, consulte Modelos com suporte integrado.

Para modelos com suporte integrado, defina o nome qualificado como o nome qualificado do modelo e especifique o URL da solicitação. O gerenciamento de endpoints de modelo identifica automaticamente o modelo e configura funções de transformação padrão.

Modelos de embedding da Vertex AI

Observação: use a função public.embedding() para consultar modelos da Vertex AI sem registro ou personalização. Para transmitir informações personalizadas, como o tipo de tarefa, registre o modelo da Vertex AI e use a função google_ml.embedding().

As etapas a seguir mostram como registrar modelos da Vertex AI com suporte integrado. O endpoint do modelo gemini-embedding-001 e text-multilingual-embedding-002 é usado como exemplo.

Observação: apenas o endpoint do modelo text-multilingual-embedding-002 exige a configuração de funções de transformação fornecidas pelo gerenciamento de endpoints de modelo.

Verifique se o cluster do AlloyDB e o modelo da Vertex AI que você está consultando estão na mesma região.

1. Conecte-se ao seu banco de dados usando psql.

2. Configure a extensão google_ml_integration.

3. Chame a função de criação de modelo para adicionar o endpoint do modelo:

   gemini-embedding-001

     CALL
       google_ml.create_model(
         model_id => 'gemini-embedding-001',
         model_request_url => 'publishers/google/models/gemini-embedding-001',
         model_provider => 'google',
         model_qualified_name => 'gemini-embedding-001',
         model_type => 'text_embedding',
         model_auth_type => 'alloydb_service_agent_iam');
   

   text-multilingual-embedding-002

     CALL
       google_ml.create_model(
         model_id => 'text-multilingual-embedding-002',
         model_request_url => 'publishers/google/models/text-multilingual-embedding-002',
         model_provider => 'google',
         model_qualified_name => 'text-multilingual-embedding-002',
         model_type => 'text_embedding',
         model_auth_type => 'alloydb_service_agent_iam'
         model_in_transform_fn => 'google_ml.vertexai_text_embedding_input_transform',
         model_out_transform_fn => 'google_ml.vertexai_text_embedding_output_transform');
   

Se o modelo estiver armazenado em outro projeto e região que não o cluster do AlloyDB, defina o URL da solicitação como projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID, em que REGION_ID é a região em que o modelo está hospedado e MODEL_ID é o nome qualificado do modelo.

Além disso, conceda o papel de usuário da Vertex AI (roles/aiplatform.user) à conta de serviço do AlloyDB do projeto em que a instância do AlloyDB reside para que o AlloyDB possa acessar o modelo hospedado no outro projeto.

Modelo de embedding de texto da OpenAI

A extensão google_ml_integration configura automaticamente funções de transformação padrão e invoca chamadas aos modelos remotos da OpenAI. Para conferir a lista de modelos da OpenAI com suporte integrado, consulte Modelos com suporte integrado.

O exemplo a seguir adiciona o endpoint do modelo text-embedding-ada-002 da OpenAI. É possível registrar os endpoints de modelo text-embedding-3-small e text-embedding-3-large da OpenAI usando as mesmas etapas e definindo os nomes qualificados específicos para os modelos.

1. Conecte-se ao banco de dados usando psql.
2. Configure a extensão google_ml_integration.
3. Adicione a chave de API da OpenAI como um secret ao Secret Manager para autenticação.

4. Chame o secret armazenado no Secret Manager:

   CALL
   google_ml.create_sm_secret(
     secret_id => 'SECRET_ID',
     secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
   

   Substitua:

   • SECRET_ID: o ID do secret que você definiu e que é usado posteriormente ao registrar um endpoint de modelo, por exemplo, key1.
   • SECRET_MANAGER_SECRET_ID: o ID do secret definido no Secret Manager quando você criou o secret.
   • PROJECT_ID: o ID do seu projeto do Google Cloud .
   • VERSION_NUMBER: o número da versão do ID do secret.

5. Chame a função de criação de modelo para registrar o endpoint do modelo text-embedding-ada-002:

   CALL
     google_ml.create_model(
       model_id => 'MODEL_ID',
       model_provider => 'open_ai',
       model_type => 'text_embedding',
       model_qualified_name => 'text-embedding-ada-002',
       model_auth_type => 'secret_manager',
       model_auth_id => 'SECRET_ID');
   

   Substitua:

   • MODEL_ID: um ID exclusivo para o endpoint do modelo que você define. Esse ID é referenciado para metadados que o endpoint do modelo precisa gerar embeddings ou invocar previsões.
   • SECRET_ID: o ID do secret usado anteriormente no procedimento google_ml.create_sm_secret().

Para gerar embeddings, consulte gerar embeddings de texto.

Modelo de embedding de texto hospedado de maneira personalizada

Esta seção mostra como registrar um endpoint de modelo hospedado de forma personalizada, além de criar funções de transformação e, opcionalmente, cabeçalhos HTTP personalizados. Todos os endpoints de modelos hospedados de forma personalizada são compatíveis, não importa onde estejam hospedados.

O exemplo a seguir adiciona o endpoint do modelo personalizado custom-embedding-model hospedado pelo Cymbal. As funções de transformação cymbal_text_input_transform e cymbal_text_output_transform são usadas para transformar o formato de entrada e saída do modelo no formato de entrada e saída da função de previsão.

Para registrar endpoints de modelos de incorporação de texto hospedados de forma personalizada, siga estas etapas:

1. Conecte-se ao seu banco de dados usando psql.

2. Configure a extensão google_ml_integration.

3. Opcional: adicione a chave de API como um secret ao Secret Manager para autenticação.

4. Chame o secret armazenado no Secret Manager:

   CALL
     google_ml.create_sm_secret(
       secret_id => 'SECRET_ID',
       secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
   

   Substitua:

   • SECRET_ID: o ID do secret que você definiu e que é usado posteriormente ao registrar um endpoint de modelo, por exemplo, key1.
   • SECRET_MANAGER_SECRET_ID: o ID do secret definido no Secret Manager quando você criou o secret.
   • PROJECT_ID: o ID do seu projeto do Google Cloud .
   • VERSION_NUMBER: o número da versão do ID do secret.
   Observação: por padrão, o Secret Manager gera um cabeçalho Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER para autenticação. Se esse formato corresponder ao formato do token de autenticação do endpoint do modelo, não será necessário gerar cabeçalhos de autenticação usando a função de geração de cabeçalho.

5. Crie as funções de transformação de entrada e saída com base na seguinte assinatura da função de previsão para endpoints de modelo de embedding de texto. Para mais informações sobre como criar funções de transformação, consulte Exemplo de funções de transformação.

   Confira a seguir exemplos de funções de transformação específicas do endpoint do modelo de embedding de texto custom-embedding-model:

   -- Input Transform Function corresponding to the custom model endpoint
   CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
   RETURNS JSON
   LANGUAGE plpgsql
   AS $$
   DECLARE
     transformed_input JSON;
     model_qualified_name TEXT;
   BEGIN
     SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input;
     RETURN transformed_input;
   END;
   $$;
   -- Output Transform Function corresponding to the custom model endpoint
   CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
   RETURNS REAL[]
   LANGUAGE plpgsql
   AS $$
   DECLARE
     transformed_output REAL[];
   BEGIN
     SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
     RETURN transformed_output;
   END;
   $$;
   

6. Chame a função de criação de modelo para registrar o endpoint do modelo de embedding personalizado:

   CALL
     google_ml.create_model(
       model_id => 'MODEL_ID',
       model_request_url => 'REQUEST_URL',
       model_provider => 'custom',
       model_type => 'text_embedding',
       model_auth_type => 'secret_manager',
       model_auth_id => 'SECRET_ID',
       model_qualified_name => 'MODEL_QUALIFIED_NAME',
       model_in_transform_fn => 'cymbal_text_input_transform',
       model_out_transform_fn => 'cymbal_text_output_transform');
   

   Substitua:

   • MODEL_ID: obrigatório. Um ID exclusivo para o endpoint do modelo que você define, por exemplo, custom-embedding-model. Esse ID é referenciado para metadados que o endpoint do modelo precisa gerar embeddings ou invocar previsões.
   • REQUEST_URL: obrigatório. O endpoint específico do modelo ao adicionar embeddings de texto personalizados e endpoints de modelo genéricos, por exemplo, https://cymbal.com/models/text/embeddings/v1. Verifique se o endpoint do modelo está acessível por um endereço IP interno. O gerenciamento de endpoints de modelo não é compatível com endereços IP públicos.
   • MODEL_QUALIFIED_NAME: obrigatório se o endpoint do modelo usar um nome qualificado. O nome totalmente qualificado caso o endpoint do modelo tenha várias versões.
   • SECRET_ID: o ID do secret usado anteriormente no procedimento google_ml.create_sm_secret().

Modelo multimodal com suporte integrado

Pré-lançamento

Este recurso está sujeito aos "Termos da Oferta 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 assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Para informações sobre o acesso a esta versão, consulte a página de solicitação de acesso.

Observação: este lançamento experimental é uma oferta de pré-GA.

Integrar com a Vertex AI e instalar a extensão

Observação: para usar as funções da IA do AlloyDB, execute upgrade_to_preview_version.

1. Configure o acesso do usuário aos modelos da Vertex AI.
2. Verifique se a versão mais recente do google_ml_integration está instalada.

   1. Para verificar a versão instalada, execute o seguinte comando:

              SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
              extversion 
              ------------
              1.5.2
              (1 row)
            

   2. Se a extensão não estiver instalada ou se a versão instalada for anterior à 1.5.2, atualize a extensão.

              CREATE EXTENSION IF NOT EXISTS google_ml_integration;
              ALTER EXTENSION google_ml_integration UPDATE;
            

      Se você tiver problemas ao executar os comandos anteriores ou se a extensão não for atualizada para a versão 1.5.2 depois de executar os comandos anteriores, entre em contato com o suporte doGoogle Cloud .

3. Para usar a funcionalidade do mecanismo de consulta da IA do AlloyDB, defina a flag google_ml_integration.enable_ai_query_engine como true.

   SQL

   1. Ative o mecanismo de consulta de IA para a sessão atual.
      

                    SET google_ml_integration.enable_ai_query_engine = true;
                    

   2. Ativar recursos para um banco de dados específico em várias sessões.
      

                    ALTER DATABASE DATABASE_NAME SET google_ml_integration.enable_ai_query_engine = 'on';
                    

   3. Ative o mecanismo de consulta de IA para um usuário específico em sessões e bancos de dados.
      

                    ALTER ROLE postgres SET google_ml_integration.enable_ai_query_engine = 'on';
                  

   Console

   Para modificar o valor da flag google_ml_integration.enable_ai_query_engine, siga as etapas em Configurar flags de bancos de dados de uma instância.

   gcloud

   Para usar a gcloud CLI, você pode instalar e inicializar a CLI do Google Cloud ou usar o Cloud Shell.

   É possível modificar o valor da flag google_ml_integration.enable_ai_query_engine. Para mais informações, consulte Configurar flags de banco de dados de uma instância.

                gcloud alloydb instances update INSTANCE_ID \
                  --database-flags google_ml_integration.enable_ai_query_engine=on \
                  --region=REGION_ID \
                  --cluster=CLUSTER_ID \
                  --project=PROJECT_ID
               

Chamar o modelo para gerar embeddings multimodais

Como o gerenciamento de endpoints de modelo oferece suporte integrado ao modelo multimodalembedding@001 da Vertex AI, é possível chamar o modelo diretamente para gerar embeddings multimodais.

O exemplo a seguir usa o nome qualificado do modelo multimodalembedding@001 como ID para gerar embeddings de imagens multimodais:

1. Conecte-se ao banco de dados usando psql.
2. Configure a extensão google_ml_integration.

3. Gerar embeddings de imagens multimodais:

   SELECT
     ai.image_embedding(
       model_id => 'multimodalembedding@001',
       image => 'IMAGE_PATH_OR_TEXT',
       mimetype => 'MIMETYPE');
   

Substitua:

• IMAGE_PATH_OR_TEXT com o caminho do Cloud Storage para a imagem, por exemplo, gs://cymbal_user_data/image-85097193-cd9788aacebb.jpeg para traduzir em uma incorporação de vetor ou string base64 da imagem.
• MIMETYPE com o tipo MIME da imagem.

Modelos de classificação

Pré-lançamento

Este recurso está sujeito aos "Termos da Oferta 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 assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Para informações sobre o acesso a esta versão, consulte a página de solicitação de acesso.

Observação: esse recurso é uma oferta experimental pré-GA.

Modelos de classificação da Vertex AI

É possível usar os modelos da Vertex AI mencionados em Modelos compatíveis sem registro.

Para saber como classificar os resultados da pesquisa usando um modelo de classificação da Vertex AI, consulte Classificar resultados da pesquisa.

Observação: para usar as funções da IA do AlloyDB, execute upgrade_to_preview_version. Para mais informações, consulte Integrar à Vertex AI e instalar a extensão.

Registrar um modelo de classificação de terceiros

O exemplo a seguir mostra como registrar um modelo de reclassificação da Cohere.

CREATE OR REPLACE FUNCTION cohere_rerank_input_transform(
    model_id VARCHAR(100),
    search_string TEXT,
    documents TEXT[],
    top_n INT DEFAULT NULL
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
  transformed_input JSONB;
BEGIN
  -- Basic Input Validation
  IF search_string IS NULL OR search_string = '' THEN
    RAISE EXCEPTION 'Invalid input: search_string cannot be NULL or empty.';
  END IF;

  IF documents IS NULL OR array_length(documents, 1) IS NULL OR array_length(documents, 1) = 0 THEN
    RAISE EXCEPTION 'Invalid input: documents array cannot be NULL or empty.';
  END IF;

  IF top_n IS NOT NULL AND top_n < 0 THEN
    RAISE EXCEPTION 'Invalid input: top_n must be greater than or equal to zero. Provided value: %', top_n;
  END IF;

  -- Construct the base JSON payload for Cohere Rerank API
  transformed_input := jsonb_build_object(
    'model', google_ml.model_qualified_name_of(model_id),
    'query', search_string,
    'documents', to_jsonb(documents), -- Convert TEXT[] directly to JSON array
    'return_documents', false -- Explicitly set to false (optional, as its default)
  );

  -- Add top_n to the payload only if it's provided and valid
  IF top_n IS NOT NULL THEN
     transformed_input := transformed_input || jsonb_build_object('top_n', top_n);
  END IF;

  -- Return the final JSON payload
  RETURN transformed_input::JSON;

END;
$$;

CREATE OR REPLACE FUNCTION cohere_rerank_output_transform(
    model_id VARCHAR(100),
    response_json JSON
)
RETURNS TABLE (index INT, score REAL)
LANGUAGE plpgsql
AS $$
DECLARE
  result_item JSONB;
  response_jsonb JSONB;
  cohere_index INT; -- 0-based index from Cohere response
BEGIN
  -- Validate response_json
  IF response_json IS NULL THEN
    RAISE EXCEPTION 'Invalid model response: response cannot be NULL.';
  END IF;

  -- Convert JSON to JSONB for easier processing
  response_jsonb := response_json::JSONB;

  -- Check top-level structure
  IF jsonb_typeof(response_jsonb) != 'object' THEN
    RAISE EXCEPTION 'Invalid model response: response must be a JSON object. Found: %', jsonb_typeof(response_jsonb);
  END IF;

  -- Check for the 'results' array
  IF response_jsonb->'results' IS NULL OR jsonb_typeof(response_jsonb->'results') != 'array' THEN
    -- Check for potential Cohere error structure
    IF response_jsonb->'message' IS NOT NULL THEN
       RAISE EXCEPTION 'Cohere API Error: %', response_jsonb->>'message';
    ELSE
       RAISE EXCEPTION 'Invalid model response: response does not contain a valid "results" array.';
    END IF;
  END IF;

  -- Loop through the 'results' array (JSONB array indices are 0-based)
  FOR i IN 0..jsonb_array_length(response_jsonb->'results') - 1 LOOP
    result_item := response_jsonb->'results'->i;

    -- Validate individual result item structure
    IF result_item IS NULL OR jsonb_typeof(result_item) != 'object' THEN
      RAISE WARNING 'Skipping invalid result item at array index %.', i;
      CONTINUE;
    END IF;

    IF result_item->'index' IS NULL OR jsonb_typeof(result_item->'index') != 'number' THEN
       RAISE WARNING 'Missing or invalid "index" field in result item at array index %.', i;
       CONTINUE;
    END IF;

    IF result_item->'relevance_score' IS NULL OR jsonb_typeof(result_item->'relevance_score') != 'number' THEN
       RAISE WARNING 'Missing or invalid "relevance_score" field in result item at array index %.', i;
       CONTINUE;
    END IF;

    -- Extract values
    BEGIN
      cohere_index := (result_item->>'index')::INT;
      -- Assign values to the output table columns
      -- Cohere returns 0-based index, map it to 1-based for consistency
      -- with input document array position
      index := cohere_index + 1;
      score := (result_item->>'relevance_score')::REAL;
      RETURN NEXT; -- Return the current row
    EXCEPTION WHEN others THEN
      RAISE WARNING 'Error processing result item at array index %: %', i, SQLERRM;
      CONTINUE; -- Skip this item and continue with the next
    END;
  END LOOP;

  RETURN; -- End of function
END;
$$;

CALL
  google_ml.create_sm_secret(
    '<SECRET_ID>',
    'projects/<PROJECT_NUMBER>/secrets/<SECRET_ID>/versions/latest');

CALL
  google_ml.create_model(
    model_id => 'cohere-reranker',
    model_type => 'reranking',
    model_provider => 'custom',
    model_request_url => 'https://api.cohere.com/v2/rerank',
    model_qualified_name => 'rerank-v3.5',
    model_auth_type => 'secret_manager',
    model_auth_id => '<SECRET_ID>',
    model_in_transform_fn => 'cohere_rerank_input_transform',
    model_out_transform_fn => 'cohere_rerank_output_transform'
  );

Modelos genéricos

Esta seção mostra como registrar qualquer endpoint de modelo genérico disponível em um provedor de modelos hospedados, como Hugging Face, OpenAI, Vertex AI, Anthropic ou qualquer outro provedor. Esta seção mostra exemplos para registrar um endpoint de modelo genérico hospedado no Hugging Face, um modelo genérico gemini-pro do Model Garden da Vertex AI e o endpoint do modelo claude-haiku.

É possível registrar qualquer endpoint de modelo genérico, desde que a entrada e a saída estejam no formato JSON. Com base nos metadados do endpoint do modelo, talvez seja necessário gerar cabeçalhos HTTP ou definir URLs de solicitação.

Para mais informações sobre modelos genéricos pré-registrados e modelos com suporte integrado, consulte Modelos compatíveis.

Modelos genéricos do Gemini

Esta seção mostra como registrar modelos genéricos do Gemini.

Modelo gemini-1.5-pro

Como alguns modelos gemini-pro são pré-registrados, é possível chamar diretamente o ID do modelo para invocar previsões.

O exemplo a seguir usa o endpoint do modelo gemini-1.5-pro:generateContent do Model Garden da Vertex AI.

1. Conecte-se ao banco de dados usando psql.
2. Configure a extensão google_ml_integration.

3. Invocar previsões usando o ID do modelo pré-registrado:

   SELECT
       json_array_elements(
       google_ml.predict_row(
           model_id => 'gemini-1.5-pro:generateContent',
           request_body => '{
       "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';
   

Modelo genérico no Hugging Face

O exemplo a seguir adiciona o endpoint do modelo de classificação personalizada facebook/bart-large-mnli hospedado no Hugging Face.

1. Conecte-se ao banco de dados usando psql.
2. Configure a extensão google_ml_integration.
3. Adicione a chave de API da OpenAI como um secret ao Secret Manager para autenticação. Se você já tiver criado um secret para outro modelo da OpenAI, poderá reutilizar o mesmo.

4. Chame o secret armazenado no Secret Manager:

   CALL
     google_ml.create_sm_secret(
       secret_id => 'SECRET_ID',
       secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
   

   Substitua:

   • SECRET_ID: o ID secreto que você definiu e que é usado posteriormente ao registrar um endpoint de modelo.
   • SECRET_MANAGER_SECRET_ID: o ID do secret definido no Secret Manager quando você criou o secret.
   • PROJECT_ID: o ID do seu projeto do Google Cloud .
   • VERSION_NUMBER: o número da versão do ID do secret.

5. Chame a função de criação de modelo para registrar o endpoint do modelo facebook/bart-large-mnli:

   CALL
     google_ml.create_model(
       model_id => 'MODEL_ID',
       model_provider => 'hugging_face',
       model_request_url => 'REQUEST_URL',
       model_qualified_name => 'MODEL_QUALIFIED_NAME',
       model_auth_type => 'secret_manager',
       model_auth_id => 'SECRET_ID');
   

   Substitua:

   • MODEL_ID: um ID exclusivo para o endpoint do modelo que você define, por exemplo, custom-classification-model. Esse ID é referenciado para metadados que o endpoint do modelo precisa gerar embeddings ou invocar previsões.
   • REQUEST_URL: o endpoint específico do modelo ao adicionar incorporação de texto personalizada e endpoints de modelo genéricos, por exemplo, https://api-inference.huggingface.co/models/facebook/bart-large-mnli.
   • MODEL_QUALIFIED_NAME: o nome totalmente qualificado da versão do endpoint do modelo. Por exemplo, facebook/bart-large-mnli.
   • SECRET_ID: o ID do secret usado anteriormente no procedimento google_ml.create_sm_secret().

Modelo genérico da Anthropic

O exemplo a seguir adiciona o endpoint do modelo claude-3-opus-20240229. O gerenciamento de endpoints de modelo fornece a função de cabeçalho necessária para registrar modelos da Anthropic.

1. Conecte-se ao banco de dados usando psql.

2. Crie e ative a extensão google_ml_integration.

   Secret Manager

   1. Adicione o token do portador como um secret ao Secret Manager para autenticação.

   2. Chame o secret armazenado no Secret Manager:

      CALL
        google_ml.create_sm_secret(
          secret_id => 'SECRET_ID',
          secret_path => 'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');
      

      Substitua:

      • SECRET_ID: o ID secreto que você definiu e que é usado posteriormente ao registrar um endpoint de modelo.
      • SECRET_MANAGER_SECRET_ID: o ID do secret definido no Secret Manager quando você criou o secret.
      • PROJECT_ID: o ID do seu projeto do Google Cloud .
      • VERSION_NUMBER: o número da versão do ID do secret.

   3. Chame a função de criação de modelo para registrar o endpoint do modelo claude-3-opus-20240229.

      CALL
        google_ml.create_model(
          model_id => 'MODEL_ID',
          model_provider => 'anthropic',
          model_request_url => 'REQUEST_URL',
          model_auth_type => 'secret_manager',
          model_auth_id => 'SECRET_ID',
          generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');
      

      Substitua:

      • MODEL_ID: um ID exclusivo para o endpoint do modelo que você define, por exemplo, anthropic-opus. Esse ID é referenciado para metadados que o endpoint do modelo precisa gerar embeddings ou invocar previsões.
      • REQUEST_URL: o endpoint específico do modelo ao adicionar incorporação de texto personalizada e endpoints de modelo genéricos, por exemplo, https://api.anthropic.com/v1/messages.

   Cabeçalho do Auth

   1. Use a função padrão de geração de cabeçalho google_ml.anthropic_claude_header_gen_fn ou crie uma.

        CREATE OR REPLACE FUNCTION anthropic_sample_header_gen_fn(model_id VARCHAR(100), request_body JSON)
        RETURNS JSON
        LANGUAGE plpgsql
        AS $$
        #variable_conflict use_variable
        BEGIN
              RETURN json_build_object('x-api-key', 'ANTHROPIC_API_KEY', 'anthropic-version', 'ANTHROPIC_VERSION')::JSON;
        END;
        $$;
      

      Substitua:

      • ANTHROPIC_API_KEY: a chave de API da Anthropic.
      • ANTHROPIC_VERSION (opcional): a versão específica do modelo que você quer usar. Por exemplo, 2023-06-01.

   2. Chame a função de criação de modelo para registrar o endpoint do modelo claude-3-opus-20240229.

      CALL
        google_ml.create_model(
          model_id => 'MODEL_ID',
          model_provider => 'anthropic',
          model_request_url => 'REQUEST_URL',
          generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');
      

      Substitua:

      • MODEL_ID: um ID exclusivo para o endpoint do modelo que você define, por exemplo, anthropic-opus. Esse ID é referenciado para metadados que o endpoint do modelo precisa gerar embeddings ou invocar previsões.
      • REQUEST_URL: o endpoint específico do modelo ao adicionar incorporação de texto personalizada e endpoints de modelo genéricos, por exemplo, https://api.anthropic.com/v1/messages.

Para mais informações, consulte como invocar previsões para endpoints de modelos genéricos.

Modelos do Model Garden da Vertex AI

Além dos modelos genéricos, é possível registrar modelos do Vertex AI Model Garden otimizados para tarefas específicas. O processo comum é primeiro implantar um modelo do Model Garden em um endpoint público da Vertex AI e depois registrar esse endpoint no AlloyDB para PostgreSQL. Esses modelos específicos de tarefas geralmente são registrados com um model_type dedicado e usados com funções SQL especializadas.

Previsão de série temporal com o modelo TimesFM

Um caso de uso comum para modelos específicos para tarefas é realizar previsões de série temporal com o modelo TimesFM.

Para implantar e registrar esse modelo, siga estas etapas:

1. Implante o modelo TimesFM do Model Garden em um endpoint da Vertex AI para receber um URL de solicitação de modelo da seguinte maneira:

   1. Acesse a página Model Garden no console do Google Cloud :

      Acessar o Model Garden

   2. Encontre o modelo TimesFM e selecione Implantar.

   3. Nas configurações de implantação, selecione Público (endpoint compartilhado) em Acesso ao endpoint para tornar o endpoint acessível publicamente e alcançável pelo AlloyDB para PostgreSQL.

   4. Depois que a implantação for concluída, acesse a página de detalhes do endpoint e copie o URL de solicitação do modelo no painel Solicitação de amostra.

2. Para registrar o modelo TimesFM implantado no AlloyDB para PostgreSQL, use a função google_ml.create_model. Para previsão de série temporal, o model_type precisa ser ts_forecasting:

CALL
google_ml.create_model(
  model_id => 'vertex_timesfm',
  model_qualified_name => 'timesfm_v2',
  model_type => 'ts_forecasting',
  model_provider => 'google',
  model_request_url => 'https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints/ENDPOINT_ID:predict',
  model_auth_type => 'alloydb_service_agent_iam'
);

Observação: se a instância do AlloyDB para PostgreSQL estiver em um projeto Google Cloud diferente do endpoint do modelo da Vertex AI, conceda à conta de serviço do AlloyDB para PostgreSQL a função Vertex AI User - roles/aiplatform.user - no projeto em que o modelo está hospedado.

Depois de registrar o modelo, use a função ai.forecast() ou google_ml.forecast() para gerar previsões.

A seguir

• Aprenda mais sobre a referência de gerenciamento de endpoints de modelo.
• Use modelos de exemplo para registrar endpoints de modelo.
• Gerar embeddings multimodais.
• Classificar e pontuar resultados da pesquisa para RAG.
• Use linguagem natural em operadores SQL.