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

Nesta página, descrevemos como invocar previsões ou gerar embeddings usando um modelo e, em seguida, registrar o endpoint do modelo com o gerenciamento de endpoints de modelo.

Para mais informações sobre a google_ml.create_model() função, consulte a referência de gerenciamento de endpoints de modelo.

Antes de começar

  • Com base no provedor do modelo, configure a autenticação.
  • Use o nome de usuário padrão postgres para acessar o banco de dados.

Ativar a extensão

  1. Defina a flag de banco de dados google_ml_integration.enable_model_support como on para sua instância. Para mais informações sobre como definir flags de banco de dados, consulte Configurar flags de banco de dados.

  2. Conecte-se à instância principal usando um cliente psql ou Cloud SQL Studio.

  3. Execute o comando a seguir para garantir que a extensão google_ml_integration seja atualizada para a versão 1.4.2:

        ALTER EXTENSION google_ml_integration UPDATE TO '1.4.2'

  4. Adicione a extensão google_ml_integration versão 1.4.2 usando psql:

      CREATE EXTENSION google_ml_integration VERSION '1.4.2';

  5. 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 NON_SUPER_USER pelo nome de usuário do PostgreSQL que não seja superusuário.

Configurar a autenticação

As seções a seguir mostram como configurar a autenticação antes de adicionar um endpoint de modelo da Vertex AI ou endpoints de modelo hospedados no Google Cloud.

Configurar a autenticação para a Vertex AI

Para usar os endpoints de modelo da Vertex AI do Google, adicione permissões da Vertex AI à conta de serviço do Cloud SQL baseada no IAM que você usa para se conectar ao banco de dados. Para mais informações sobre a integração com a Vertex AI, consulte Integrar o Cloud SQL à Vertex AI.

Configurar a autenticação para modelos hospedados de maneira personalizada

Esta seção explica como configurar a autenticação se você estiver usando o Secret Manager. Para todos os modelos, exceto endpoints de modelo da Vertex AI, é possível armazenar suas chaves de API ou tokens de acesso no Secret Manager.

Se o endpoint do modelo não processar a autenticação pelo Secret Manager, esta seção será opcional. Por exemplo, se o endpoint do modelo usar cabeçalhos HTTP para transmitir informações de autenticação ou não usar autenticação, não conclua as etapas desta seção.

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

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

    O nome e o caminho do secret são usados na google_ml.create_sm_secret() função SQL.

  2. Conceda permissões à instância do Cloud SQL para acessar o secret.

      gcloud secrets add-iam-policy-binding SECRET_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
      --role="roles/secretmanager.secretAccessor"

    Substitua:

    • SECRET_ID: o ID do secret no Secret Manager.
    • SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da conta de serviço do Cloud SQL baseada no IAM. Para encontrar esse endereço de e-mail, use o gcloud sql instances describe INSTANCE_NAME comando e substitua INSTANCE_NAME pelo nome da instância. O valor que aparece ao lado do parâmetro serviceAccountEmailAddress é o endereço de e-mail.

Modelos de embedding de texto com suporte integrado

Esta seção mostra como registrar endpoints de modelo para gerenciamento de endpoints de modelo.

Modelos de embedding da Vertex AI

O gerenciamento de endpoints de modelo oferece suporte integrado a todas as versões dos text-embedding-gecko, text-embedding, e gemini-embedding modelos da Vertex AI. Use o nome qualificado para definir a versão do modelo como textembedding-gecko@001 ou textembedding-gecko@002.

Como os IDs de endpoint do modelo de embedding da Vertex AI são compatíveis por padrão com o gerenciamento de endpoints de modelo, é possível usar qualquer um deles diretamente como o ID do modelo. Para esses modelos, a extensão configura automaticamente funções de transformação padrão.

Verifique se a instância do Cloud SQL e o modelo da Vertex AI que você está consultando estão na mesma região.

Para registrar o endpoint do modelo textembedding-gecko@002, chame a função create_model:

  CALL
    google_ml.create_model(
      model_id => 'textembedding-gecko@002',
      model_provider => 'google',
      model_qualified_name => 'textembedding-gecko@002',
      model_type => 'text_embedding',
      model_auth_type => 'cloudsql_service_agent_iam');

Modelos de embedding de texto hospedados de maneira personalizada

Esta seção mostra como registrar endpoints de modelo personalizados hospedados em redes no Google Cloud.

A adição de endpoints de modelo de embedding de texto hospedados de maneira personalizada envolve a criação de funções de transformação e, opcionalmente, cabeçalhos HTTP personalizados. Por outro lado, a adição de endpoints de modelo genéricos hospedados de maneira personalizada envolve a geração opcional de cabeçalhos HTTP personalizados e a definição do URL de solicitação do modelo.

O exemplo a seguir adiciona o endpoint do modelo de embedding de texto custom-embedding-model hospedado pelo Cymbal, que está hospedado no Google Cloud. 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 modelo de embedding de texto hospedados de maneira personalizada, siga estas etapas:

  1. 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 Google Cloud projeto.
    • VERSION_NUMBER: o número da versão do ID do secret.

  2. Crie as funções de transformação de entrada e saída com base na assinatura a seguir para a função de previsão de 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.

    A seguir, mostramos 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;
$$;

  3. 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 do modelo é 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 endpoints de modelo genéricos e de embedding de texto personalizados, por exemplo, https://cymbal.com/models/text/embeddings/v1. Verifique se o endpoint do modelo pode ser acessado por um endereço IP interno. O gerenciamento de endpoints de modelo não oferece suporte a endereços IP externo.
  • 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 que você usou anteriormente no procedimento google_ml.create_sm_secret().

Modelos genéricos

Esta seção mostra como registrar um endpoint de modelo genérico gemini-pro do Model Garden da Vertex AI, que não tem suporte integrado. É possível registrar qualquer endpoint de modelo genérico hospedado no Google Cloud.

O Cloud SQL oferece suporte apenas a endpoints de modelo disponíveis no Model Garden da Vertex AI e endpoints de modelo hospedados em redes no Google Cloud.

Modelo do Gemini

O exemplo a seguir adiciona o endpoint do modelo gemini-1.0-pro do Model Garden da Vertex AI.

Para registrar o endpoint do modelo gemini-1.0-pro, chame a função create model:

    CALL
      google_ml.create_model(
        model_id => 'MODEL_ID',
        model_request_url => 'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-1.0-pro:streamGenerateContent',
        model_provider => 'google',
        model_auth_type => 'cloudsql_service_agent_iam');

Substitua:

  • MODEL_ID: um ID exclusivo para o endpoint do modelo que você define (por exemplo,
    gemini-1). Esse ID do modelo é referenciado para metadados que o endpoint do modelo precisa gerar embeddings ou invocar previsões.
  • PROJECT_ID: o ID do seu Google Cloud projeto.

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

A seguir