Panoramica della gestione degli endpoint del modello

Questa pagina descrive come registrare un endpoint del modello di AI e richiamare le previsioni con la gestione degli endpoint del modello in Cloud SQL. Per utilizzare i modelli di AI negli ambienti di produzione, consulta Generare e gestire gli embedding vettoriali.

Panoramica

La gestione degli endpoint del modello ti consente di registrare un endpoint del modello, gestire i metadati dell'endpoint del modello nell'istanza Cloud SQL e quindi interagire con i modelli utilizzando query SQL. Puoi utilizzare questi modelli per generare embedding vettoriali o richiamare le previsioni.

Puoi registrare i seguenti tipi di modelli utilizzando la gestione degli endpoint del modello:

  • Modelli di text embedding di Vertex AI.
  • Modelli di text embedding ospitati dal cliente in reti all'interno di Google Cloud.

  • Modelli generici con un'API basata su JSON. Di seguito sono riportati alcuni esempi di questi modelli:

    • Il modello gemini-flash di Model Garden di Vertex AI
    • Il modello open_ai per i modelli OpenAI
    • Modelli ospitati in reti all'interno di Google Cloud

Come funziona

Puoi utilizzare la gestione degli endpoint del modello per registrare un endpoint del modello conforme a quanto segue:

  • L'input e l'output del modello supportano il formato JSON.
  • Puoi utilizzare il protocollo REST per chiamare il modello.

Quando registri un endpoint del modello con la gestione degli endpoint del modello, la gestione degli endpoint del modello registra ogni endpoint con un ID modello univoco come riferimento al modello. Puoi utilizzare questo ID modello per eseguire query sui modelli, come segue:

  • Generare embedding per tradurre i prompt di testo in vettori numerici. Puoi memorizzare gli embedding generati come dati vettoriali quando abiliti il supporto per gli embedding vettoriali sull'istanza. Per maggiori informazioni, consulta Abilitare e disabilitare gli embedding vettoriali sull'istanza.

  • Richiamare le previsioni per chiamare un modello utilizzando SQL all'interno di una transazione.

Per registrare e chiamare i modelli di AI remoti con l'istanza Cloud SQL, l'istanza deve essere installata con la versione di manutenzione MYSQL_VERSION.R20250531.01_14 o successive. Se l'istanza esegue una versione di manutenzione precedente a MYSQL_VERSION.R20250531.01_14, allora puoi utilizzare solo le seguenti funzioni come documentato con l' integrazione di Cloud SQL e Vertex AI.

Per eseguire l'upgrade dell'istanza alla versione di manutenzione MYSQL_VERSION.R20250531.01_14 o successive, consulta Manutenzione self-service. Dopo aver eseguito l'upgrade dell'istanza, puoi utilizzare le seguenti funzioni:

Inoltre, puoi utilizzare le seguenti funzioni con il provider di modelli registrato:

Privilegi utente del database obbligatori

Per registrare e chiamare i modelli di AI remoti, devi aver eseguito l'accesso come utente del database MySQL a cui sono stati concessi i privilegi SELECT ed EXECUTE su mysql.*.

Per impostazione predefinita, qualsiasi utente con il ruolo cloudsqlsuperuser dispone di questi privilegi o può creare un utente e concedere i privilegi richiesti.

Per maggiori informazioni sul ruolo cloudsqlsuperuser in Cloud SQL, consulta Privilegi utente MySQL 8.0 e Privilegi utente MySQL 8.4.

Concetti fondamentali

Prima di iniziare a utilizzare la gestione degli endpoint del modello, comprendi i concetti necessari per connetterti ai modelli e utilizzarli.

Provider del modello

Il provider del modello è il provider host dei modelli supportato. La tabella seguente mostra il valore del provider del modello che devi impostare in base al provider del modello che utilizzi:

Provider del modello Impostato nella funzione come…
Vertex AI (incluso Gemini) google
Anthropic anthropic
Hugging Face hugging_face
OpenAI open_ai
Altri modelli ospitati al di fuori di Vertex AI,
Anthropic, Hugging Face e OpenAI		 custom

Il provider di modelli predefinito è custom.

Tipi di modello

I tipi di modello sono i tipi di modello di AI. Quando registri un endpoint del modello, puoi impostare i tipi di modello text_embedding o generic per l'endpoint.

Se utilizzi Vertex AI come provider di modelli, non devi registrare un endpoint del modello perché gli endpoint sono supportati automaticamente. Per impostazione predefinita, con Vertex AI utilizzi il modello text-embedding-005.

Altri modelli di text embedding
Per altri modelli di text embedding, devi creare funzioni di trasformazione per gestire i formati di input e output supportati dal modello. Se vuoi, puoi utilizzare la funzione di generazione delle intestazioni HTTP che genera le intestazioni personalizzate richieste dal tuo modello.

Il tipo di modello per questi modelli è text_embedding.

Modelli generici
La gestione degli endpoint del modello supporta anche la registrazione di tutti gli altri tipi di modelli, ad eccezione dei modelli di text embedding. Per richiamare le previsioni per i modelli generici, utilizza la funzione mysql.ml_predict_row(). Puoi impostare i metadati dell'endpoint del modello, come un endpoint di richiesta e intestazioni HTTP specifiche per il tuo modello.
Non puoi passare funzioni di trasformazione quando registri un endpoint del modello generico. Assicurati che quando richiami le previsioni, l'input della funzione sia in formato JSON e di analizzare l'output JSON per derivare l'output finale.
Il tipo di modello per questi modelli è generic. Poiché generic è il tipo di modello predefinito, se registri gli endpoint del modello per questo tipo, l'impostazione del tipo di modello è facoltativa.
Con Vertex AI, la gestione degli endpoint del modello include il supporto preregistrato per il modello gemini-2.5-flash.

Metodi di autenticazione

Puoi abilitare il supporto per gli embedding vettoriali nell'istanza Cloud SQL per MySQL e poi specificare diversi metodi di autenticazione per accedere al modello. L'impostazione di questi metodi è facoltativa ed è necessaria solo se devi eseguire l'autenticazione per accedere al modello.

Per i modelli Vertex AI, viene utilizzato il service account Cloud SQL per l'autenticazione. Per altri modelli, la chiave API o il token di connessione memorizzato come secret in Secret Manager può essere utilizzato con la funzione SQL mysql.ml_create_sm_secret_registration().

La tabella seguente mostra i metodi di autenticazione che puoi impostare:

Metodo di autenticazione Impostato nella funzione come… Provider del modello
Agente di servizio Cloud SQL auth_type_cloudsql_service_agent_iam Provider di Vertex AI
Secret Manager auth_type_secret_manager Modelli ospitati al di fuori di Vertex AI

Funzioni di previsione

mysql.ml_embedding()
Chiama un endpoint del modello di text embedding registrato per generare embedding. Include il supporto integrato per tutti i modelli di embedding di Vertex AI.
Per i modelli di text embedding senza supporto integrato, i parametri di input e output sono univoci per un modello e devono essere trasformati affinché la funzione chiami il modello. Crea una funzione input di trasformazione per trasformare l'input della funzione di previsione nell'input specifico del modello, e una funzione di output di trasformazione per trasformare l'output specifico del modello nell'output della funzione di previsione.
mysql.ml_predict_row()
Chiama un endpoint del modello generico registrato, se l'endpoint supporta le API basate su JSON per richiamare le previsioni.

Funzioni di trasformazione

Le funzioni di trasformazione modificano l'input in un formato che il modello comprende e convertono la risposta del modello nel formato previsto dalla funzione di previsione. Le funzioni di trasformazione vengono utilizzate durante la registrazione dell'endpoint del modello text-embedding senza supporto integrato. La firma delle funzioni di trasformazione dipende dalla funzione di previsione per il tipo di modello.

Non puoi utilizzare le funzioni di trasformazione durante la registrazione di un endpoint del modello generic.

Di seguito sono riportate le firme per la funzione di previsione per i modelli di text embedding:

// define custom model specific input/output transform functions.
CREATE FUNCTION IF NOT EXISTS input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

// the returned BLOB should be of type VECTOR
CREATE FUNCTION IF NOT EXISTS output_transform_function(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;

Per maggiori informazioni su come creare funzioni di trasformazione, consulta Esempio di funzioni di trasformazione.

Funzione di generazione delle intestazioni HTTP

La funzione di generazione delle intestazioni HTTP genera l'output in coppie chiave-valore JSON utilizzate come intestazioni HTTP. La firma della funzione di previsione definisce le firme della funzione di generazione delle intestazioni.

L'esempio seguente mostra la firma per la funzione di previsione mysql.ml_embedding():

CREATE FUNCTION IF NOT EXISTS generate_headers(model_id VARCHAR(100), input TEXT) RETURNS JSON DETERMINISTIC;

Per la funzione di previsione mysql.ml_predict_row(), la firma è la seguente:

CREATE FUNCTION IF NOT EXISTS generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON DETERMINISTIC;

Per maggiori informazioni su come creare una funzione di generazione delle intestazioni, consulta Esempio di funzione di generazione delle intestazioni.

Limitazioni

  • Quando esegui una delle funzioni di registrazione del modello o di gestione dei secret, esegui implicitamente il commit di tutte le transazioni aperte nella sessione. Le funzioni di previsione non eseguono implicitamente il commit delle transazioni.

  • Se esporti o importi il database con mysqldump, il catalogo degli endpoint del modello non viene esportato.

  • Un database utente che contiene funzioni di trasformazione non può avere un punto ('.') nel nome. Ad esempio, un database denominato my.sql non è supportato.

  • La gestione degli endpoint del modello è disponibile solo per Cloud SQL per MySQL versione 8.0.36 e successive.

Passaggi successivi