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

MySQL | PostgreSQL | SQL Server

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

Para mais informações sobre a mysql.ml_create_model_registration() 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.

Conecte-se à instância principal usando um cliente mysql ou o Cloud SQL Studio.
Conecte-se ao banco de dados como um usuário do banco de dados MySQL com os privilégios de banco de dados descritos em Privilégios necessários do usuário do banco de dados.

Configurar a autenticação

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

Configurar a autenticação para a Agent Platform

Para usar os endpoints de modelo da Google Agent Platform, adicione permissões da Agent Platform à 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 Agent Platform, consulte Integrar o Cloud SQL à Agent Platform.

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 os endpoints de modelo da Agent Platform, é possível armazenar suas chaves de API ou tokens de portador 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 a autenticação, não conclua as etapas desta seção.

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

Criar 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 mysql.ml_create_sm_secret_registration() função SQL.
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 Agent Platform

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 Agent Platform. 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 Agent Platform 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 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 Agent Platform 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 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, opcionalmente, a geração 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:

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 Google Cloud projeto.
- VERSION_NUMBER: o número da versão do ID do secret.
Observação: o Secret Manager gera um cabeçalho Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER para autenticação por padrão. Se esse formato corresponder ao formato do token de portador de autorizaçã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.

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, estão 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
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 ;

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 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 embedding de texto personalizado e endpoints de modelo genéricos, 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 mysql.ml_create_sm_secret_registration().

Modelos genéricos

Esta seção mostra como registrar um endpoint de modelo genérico gemini-flash do Model Garden da Agent Platform, que é pré-registrado no catálogo por padrão. É 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 Agent Platform e endpoints de modelo hospedados em redes no Google Cloud.

Modelo do Gemini

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

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);