Registe e chame modelos de IA remotos através da gestão de pontos finais de modelos

Esta página descreve como invocar previsões ou gerar incorporações através de um modelo e, em seguida, registar o ponto final do modelo na gestão de pontos finais de modelos.

Para mais informações sobre a função mysql.ml_create_model_registration(), consulte a referência de gestão de pontos finais de modelos.

Antes de começar

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

Configure a autenticação

As secções seguintes mostram como configurar a autenticação antes de adicionar um ponto final de modelo do Vertex AI ou pontos finais de modelo alojados no Google Cloud.

Configure a autenticação para o Vertex AI

Para usar os pontos finais do modelo do Google Vertex AI, tem de adicionar autorizações do Vertex AI à conta de serviço do Cloud SQL baseada no IAM que usa para se ligar à base de dados. Para mais informações sobre a integração com o Vertex AI, consulte o artigo Integre o Cloud SQL com o Vertex AI.

Configure a autenticação para modelos alojados de forma personalizada

Esta secção explica como configurar a autenticação se estiver a usar o Secret Manager. Para todos os modelos, exceto os pontos finais de modelos da Vertex AI, pode armazenar as suas chaves da API ou tokens de autorização no Secret Manager.

Se o seu ponto final do modelo não processar a autenticação através do Secret Manager, esta secção é opcional. Por exemplo, se o seu ponto final do modelo usar cabeçalhos HTTP para transmitir informações de autenticação ou não usar autenticação, não conclua os passos nesta secção.

Para criar e usar uma chave da API ou um token de autorização, conclua os seguintes passos:

  1. Crie um segredo no Secret Manager. Para mais informações, consulte o artigo Crie um segredo e aceda a uma versão secreta.

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

  2. Conceda autorizações à instância do Cloud SQL para aceder ao segredo.

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

    Substitua o seguinte:

    • SECRET_ID: o ID do segredo no Secret Manager.
    • SERVICE_ACCOUNT_EMAIL: o endereço de email da conta de serviço do Cloud SQL baseada no IAM. Para encontrar este endereço de email, use o comando gcloud sql instances describe INSTANCE_NAME e substitua INSTANCE_NAME pelo nome da instância. O valor apresentado junto ao parâmetro serviceAccountEmailAddress é o endereço de email.

Modelos de incorporação de texto com suporte integrado

Esta secção mostra como registar pontos finais de modelos para a gestão de pontos finais de modelos.

Modelos de incorporação da Vertex AI

A gestão de pontos finais de modelos oferece suporte integrado para 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.

Uma vez que os IDs dos pontos finais do modelo de incorporação do Vertex AI são suportados por predefinição com a gestão de pontos finais de modelos, pode usar qualquer um deles diretamente como o ID do modelo. Para estes modelos, a função de incorporação realiza automaticamente a transformação de entrada e saída.

Certifique-se de que a instância do Cloud SQL e o modelo do Vertex AI que está a consultar estão na mesma região.

Para registar o ponto final 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 alojados de forma personalizada

Esta secção mostra como registar pontos finais de modelos personalizados alojados em redes dentro de Google Cloud.

A adição de pontos finais de modelos de incorporação de texto alojados de forma personalizada envolve a criação de funções de transformação e, opcionalmente, cabeçalhos HTTP personalizados. Por outro lado, a adição de pontos finais de modelos genéricos alojados de forma personalizada envolve, opcionalmente, a geração de cabeçalhos HTTP personalizados e a definição do URL do pedido do modelo.

O exemplo seguinte adiciona o ponto final do custom-embedding-model modelo de incorporação de texto alojado pela Cymbal, que está alojado 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 registar pontos finais de modelos de incorporação de texto alojados de forma personalizada, conclua os seguintes passos:

  1. Chame o segredo 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 o seguinte:

    • SECRET_ID: o ID secreto que define e que é usado posteriormente quando regista um ponto final do modelo, por exemplo, key1.
    • SECRET_MANAGER_SECRET_ID: o ID secreto definido no Secret Manager quando criou o segredo.
    • PROJECT_ID: o ID do seu projeto Google Cloud .
    • VERSION_NUMBER: o número da versão do ID secreto.

  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 para os pontos finais do modelo de incorporação de texto. Para mais informações sobre como criar funções de transformação, consulte o exemplo de funções de transformação.

    Seguem-se exemplos de funções de transformação específicas do custom-embedding-model ponto final do modelo de incorporação de texto:

    -- 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 modelos para registar o ponto final do modelo de incorporação 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 o seguinte:

  • MODEL_ID: obrigatório. Um ID exclusivo para o ponto final do modelo que define (por exemplo, custom-embedding-model). Este ID do modelo é referenciado para metadados de que o ponto final do modelo precisa para gerar incorporações ou invocar previsões.
  • REQUEST_URL: obrigatório. O ponto final específico do modelo quando adiciona incorporação de texto personalizada e pontos finais de modelos genéricos, por exemplo, https://cymbal.com/models/text/embeddings/v1. Certifique-se de que o ponto final do modelo é acessível através de um endereço IP interno. A gestão de pontos finais de modelos não suporta endereços IP externos.
  • MODEL_QUALIFIED_NAME: obrigatório se o ponto final do modelo usar um nome qualificado. O nome totalmente qualificado, caso o ponto final do modelo tenha várias versões.
  • SECRET_ID: o ID secreto que usou anteriormente no procedimento mysql.ml_create_sm_secret_registration().

Modelos genéricos

Esta secção mostra como registar um ponto final do modelo genérico gemini-flash do Vertex AI Model Garden, que está pré-registado no catálogo por predefinição. Pode registar qualquer ponto final de modelo genérico alojado no Google Cloud.

O Cloud SQL só suporta pontos finais de modelos disponíveis através do Vertex AI Model Garden e pontos finais de modelos alojados em redes no Google Cloud.

Modelo do Gemini

O exemplo seguinte usa o ponto final do modelo gemini-2.5-flash do Vertex AI Model Garden.

Para registar o ponto final 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 o seguinte:

  • MODEL_ID: um ID exclusivo para o ponto final do modelo que define (por exemplo,
    gemini-1). Este ID do modelo é referenciado para metadados de que o ponto final do modelo precisa para gerar incorporações ou invocar previsões.
  • PROJECT_ID: o ID do seu projeto Google Cloud .

Para mais informações, veja como invocar previsões para pontos finais de modelos genéricos.

O que se segue?