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 e, em seguida, registrar o endpoint do modelo com o gerenciamento de endpoints de modelo.

Para mais informações sobre a função mysql.ml_create_model_registration(), consulte Referência do gerenciamento de endpoints de modelo.

Antes de começar

  • Com base no provedor do modelo, configure a autenticação.

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 em Trusted Cloud by S3NS.

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 forma personalizada

Nesta seção, explicamos como configurar a autenticação se você estiver usando o Secret Manager. Para todos os modelos, exceto os 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 dele.

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

  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 comando gcloud sql instances describe INSTANCE_NAME 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 modelos text-embedding-gecko, text-embedding e gemini-embedding 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 endpoints de modelos de incorporação da Vertex AI são compatíveis por padrão com o gerenciamento de endpoints de modelos, é possível usar qualquer um deles diretamente como o ID do modelo. Para esses modelos, a função de embedding realiza automaticamente a transformação de entrada e saída.

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 gemini-embedding-001, chame a função ml_create_model_registration:

  CALL
    mysql.ml_create_model_registration(
      'gemini-embedding-001',
      'publishers/google/models/gemini-embedding-001',
      'google','text_embedding', 'gemini-embedding-001',
      'AUTH_TYPE_CLOUDSQL_SERVICE_AGENT_IAM',
       NULL,
      'mysql.cloudsql_ml_text_embedding_input_transform',
      'mysql.cloudsql_ml_text_embedding_output_transform', NULL);

Modelos de incorporação de texto hospedados de forma personalizada

Esta seção mostra como registrar endpoints de modelos personalizados hospedados em redes no Trusted Cloud by S3NS.

Para adicionar endpoints de modelo de incorporação de texto hospedados de forma personalizada, é necessário criar funções de transformação e, opcionalmente, cabeçalhos HTTP personalizados. Por outro lado, adicionar endpoints de modelo genérico hospedados personalizados envolve gerar cabeçalhos HTTP personalizados e definir o URL de solicitação do modelo.

O exemplo a seguir adiciona o endpoint do modelo de incorporação de texto custom-embedding-model hospedado pelo Cymbal, que está hospedado em Trusted Cloud by S3NS. 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. Chame o secret armazenado no Secret Manager:

    CALL
  mysql.ml_create_sm_secret_registration(
    'SECRET_ID',
    '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 Trusted Cloud by S3NS .
    • 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 seguinte assinatura para a função de previsão dos endpoints do 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 para o endpoint do modelo de embedding de texto custom-embedding-model:

    -- Input Transform Function corresponding to the custom model endpoint
DELIMITER $$
CREATE FUNCTION IF NOT EXISTS cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC

BEGIN
  RETURN JSON_OBJECT('prompt', JSON_ARRAY(input_text));
END $$

-- Output Transform Function corresponding to the custom model endpoint
CREATE FUNCTION IF NOT EXISTS cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS BLOB
DETERMINISTIC

BEGIN
  RETURN STRING_TO_VECTOR(
         JSON_EXTRACT(
              content,
              '$.predictions[0].embeddings.values'
            )
     );

END $$
DELIMITER ;

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

   CALL
      mysql.ml_create_model_registration(
        'MODEL_ID',
        'REQUEST_URL',
        'custom',
        'text_embedding',
        'MODEL_QUALIFIED_NAME',
        'auth_type_secret_manager',
        'SECRET_ID'
        'database_name.cymbal_text_input_transform',
        'database_name.cymbal_text_output_transform', NULL);

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 incorporações 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 aceita 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 usado anteriormente no procedimento mysql.ml_create_sm_secret_registration().

Modelos genéricos

Esta seção mostra como registrar um endpoint de modelo gemini-flash genérico do Model Garden da Vertex AI, que é pré-registrado no catálogo por padrão. É possível registrar qualquer endpoint de modelo genérico hospedado no Trusted Cloud by S3NS.

O Cloud SQL só é compatível com endpoints de modelo disponíveis no Model Garden da Vertex AI e endpoints de modelo hospedados em redes dentro de Trusted Cloud by S3NS.

Modelo do Gemini

O exemplo a seguir usa o endpoint do modelo gemini-2.5-flash do Model Garden da Vertex AI.

Para registrar o endpoint do modelo gemini-2.5-flash, chame a função mysql.ml_create_model_registration:

    CALL
      mysql.ml_create_model_registration(
        'MODEL_ID',
        'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.5-flash:streamGenerateContent',
        'google',
        'auth_type_cloudsql_service_agent_iam',
        NULL, NULL, NULL, NULL);

Substitua:

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

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

A seguir