Registra e chiama i modelli di IA remota utilizzando la gestione degli endpoint dei modelli

Questa pagina descrive come richiamare le previsioni o generare embedding utilizzando un modello, quindi registrare l'endpoint del modello con la gestione degli endpoint del modello.

Per ulteriori informazioni sulla funzione mysql.ml_create_model_registration(), consulta il riferimento per la gestione degli endpoint del modello.

Prima di iniziare

  • Configura l'autenticazione in base al provider del modello.

Configura l'autenticazione

Le sezioni seguenti mostrano come configurare l'autenticazione prima di aggiungere un endpoint del modello Vertex AI o endpoint del modello ospitati all'interno di Cloud de Confiance by S3NS.

Configura l'autenticazione per Vertex AI

Per utilizzare gli endpoint del modello di AI Google Vertex AI, devi aggiungere le autorizzazioni Vertex AI al account di servizio Cloud SQL basato su IAM che utilizzi per connetterti al database. Per ulteriori informazioni sull'integrazione con Vertex AI, consulta Integra Cloud SQL con Vertex AI.

Configura l'autenticazione per i modelli ospitati dal cliente

Questa sezione spiega come configurare l'autenticazione se utilizzi Secret Manager. Per tutti i modelli di AI, ad eccezione degli endpoint dei modelli Vertex AI, puoi archiviare le chiavi API o i token di connessione in Secret Manager.

Se l'endpoint del modello non gestisce l'autenticazione tramite Secret Manager, questa sezione è facoltativa. Ad esempio, se l'endpoint del modello utilizza intestazioni HTTP per passare le informazioni di autenticazione o non utilizza affatto l'autenticazione, non completare i passaggi descritti in questa sezione.

Per creare e utilizzare una chiave API o un token di connessione, completa i seguenti passaggi:

  1. Crea un secret in Secret Manager. Per saperne di più, consulta Crea un secret e accedi a una versione del secret.

    Il nome e il percorso del secret vengono utilizzati nella funzione SQL mysql.ml_create_sm_secret_registration().

  2. Concedi all'istanza Cloud SQL le autorizzazioni per accedere al secret.

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

    Sostituisci quanto segue:

    • SECRET_ID: l'ID del secret in Secret Manager.
    • SERVICE_ACCOUNT_EMAIL: l'indirizzo email del account di servizio Cloud SQL basato su IAM. Per trovare questo indirizzo email, utilizza il comando gcloud sql instances describe INSTANCE_NAME e sostituisci INSTANCE_NAME con il nome dell'istanza. Il valore visualizzato accanto al parametro serviceAccountEmailAddress è l'indirizzo email.

Modelli di text embedding con supporto integrato

Questa sezione mostra come registrare gli endpoint del modello per la gestione degli endpoint del modello.

Modelli di embedding Vertex AI

La gestione degli endpoint dei modelli fornisce il supporto integrato per tutte le versioni dei modelli text-embedding-gecko, text-embedding e gemini-embedding di Vertex AI. Utilizza il nome completo per impostare la versione del modello su textembedding-gecko@001 o textembedding-gecko@002.

Poiché gli ID endpoint del modello di embedding di Vertex AI sono supportati per impostazione predefinita con la gestione degli endpoint del modello, puoi utilizzarli direttamente come ID modello. Per questi modelli, la funzione di embedding esegue automaticamente la trasformazione di input e output.

Assicurati che l'istanza Cloud SQL e il modello di AI Vertex AI su cui stai eseguendo query si trovino nella stessa regione.

Per registrare l'endpoint del modello gemini-embedding-001, chiama la funzione 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);

Modelli di text embedding ospitati dal cliente

Questa sezione mostra come registrare gli endpoint dei modelli personalizzati ospitati nelle reti all'interno di Cloud de Confiance by S3NS.

L'aggiunta di endpoint di modelli di text embedding ospitati dal cliente prevede la creazione di funzioni di trasformazione e, facoltativamente, di intestazioni HTTP personalizzate. D'altra parte, l'aggiunta di endpoint di modelli generici ospitati dal cliente comporta la generazione facoltativa di intestazioni HTTP personalizzate e l'impostazione dell'URL della richiesta del modello.

L'esempio seguente aggiunge l'endpoint del modello di text embedding custom-embedding-model ospitato da Cymbal, che è ospitato all'interno di Cloud de Confiance by S3NS. Le funzioni di trasformazione cymbal_text_input_transform e cymbal_text_output_transform vengono utilizzate per trasformare il formato di input e output del modello nel formato di input e output della funzione di previsione.

Per registrare gli endpoint dei modelli di text embedding ospitati dal cliente, completa i seguenti passaggi:

  1. Chiama il secret archiviato in Secret Manager:

    CALL
  mysql.ml_create_sm_secret_registration(
    'SECRET_ID',
    'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

    Sostituisci quanto segue:

    • SECRET_ID: l'ID secret che hai impostato e che viene utilizzato successivamente durante la registrazione di un endpoint del modello, ad esempio key1.
    • SECRET_MANAGER_SECRET_ID: l'ID secret impostato in Secret Manager al momento della creazione del secret.
    • PROJECT_ID: l'ID del tuo progetto Cloud de Confiance by S3NS .
    • VERSION_NUMBER: il numero di versione dell'ID secret.

  2. Crea le funzioni di trasformazione di input e output in base alla seguente firma per la funzione di previsione per gli endpoint dei modelli di text embedding. Per saperne di più su come creare funzioni di trasformazione, consulta Esempio di funzioni di trasformazione.

    Di seguito sono riportati esempi di funzioni di trasformazione specifiche per l'endpoint del modello di text embedding 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(JSON_UNQUOTE(
              content,
              '$.predictions[0].embeddings.values'
            ))
     );

END $$
DELIMITER ;

  3. Chiama la funzione di creazione del modello per registrare l'endpoint del modello di embedding personalizzato:

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

Sostituisci quanto segue:

  • MODEL_ID: obbligatorio. Un ID univoco per l'endpoint del modello che definisci (ad esempio, custom-embedding-model). Questo ID modello viene utilizzato per i metadati necessari all'endpoint del modello per generare embedding o richiamare previsioni.
  • REQUEST_URL: obbligatorio. L'endpoint specifico del modello quando aggiungi endpoint di text embedding personalizzati e modelli generici, ad esempio https://cymbal.com/models/text/embeddings/v1. Assicurati che l'endpoint del modello sia accessibile tramite un indirizzo IP interno. La gestione degli endpoint del modello non supporta gli indirizzi IP esterni.
  • MODEL_QUALIFIED_NAME: obbligatorio se l'endpoint del modello utilizza un nome qualificato. Il nome completo nel caso in cui l'endpoint del modello abbia più versioni.
  • SECRET_ID: l'ID secret utilizzato in precedenza nella procedura mysql.ml_create_sm_secret_registration().

Modelli generici

Questa sezione mostra come registrare un endpoint del modello gemini-flash generico da Vertex AI Model Garden, che è preregistrato nel catalogo per impostazione predefinita. Puoi registrare qualsiasi endpoint del modello generico ospitato all'interno di Cloud de Confiance by S3NS.

Cloud SQL supporta solo gli endpoint dei modelli disponibili tramite Vertex AI Model Garden e gli endpoint dei modelli ospitati in reti all'interno di Cloud de Confiance by S3NS.

Modello di Gemini

L'esempio seguente utilizza l'endpoint del modello gemini-2.5-flash di Vertex AI Model Garden.

Per registrare l'endpoint del modello gemini-2.5-flash, chiama la funzione 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);

Sostituisci quanto segue:

  • MODEL_ID: un ID univoco per l'endpoint del modello che definisci (ad esempio,
    gemini-1). Questo ID modello viene utilizzato per i metadati necessari all'endpoint del modello per generare embedding o richiamare previsioni.
  • PROJECT_ID: l'ID del tuo progetto Cloud de Confiance by S3NS .

Per saperne di più, consulta come richiamare le previsioni per gli endpoint dei modelli generici.

Passaggi successivi