Riferimento per la gestione degli endpoint dei modelli

Anteprima

Questo prodotto è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. I prodotti pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

MySQL   |  PostgreSQL   |  SQL Server

Questa pagina elenca i parametri per le diverse funzioni fornite da Cloud SQL per registrare e gestire gli endpoint del modello. La pagina elenca anche i segreti che puoi gestire utilizzando la gestione degli endpoint del modello.

Nota: per saperne di più sulla gestione degli endpoint dei modelli, vedi Registrare e chiamare modelli di AI remoti in Cloud SQL.

Modelli

Utilizza questo riferimento per comprendere i parametri delle funzioni che ti consentono di gestire gli endpoint del modello.

mysql.ml_create_model_registration()

Di seguito viene mostrato come utilizzare la funzione mysql.ml_create_model_registration() per registrare i metadati dell'endpoint del modello:

  CALL
    mysql.ml_create_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

Parametro	Obbligatorio	Descrizione
MODEL_ID	Obbligatorio per tutti gli endpoint del modello	Un ID univoco per l'endpoint del modello che definisci.
REQUEST_URL	Può essere NULL per i modelli Vertex AI	L'endpoint specifico del modello quando si aggiungono altri endpoint di incorporamento di testo e di modelli generici. L'URL della richiesta generato dalla funzione per gli endpoint del modello integrato fa riferimento al progetto e alla regione o alla località del cluster. Se vuoi fare riferimento a un altro progetto, assicurati di specificare model_request_url in modo esplicito. Per gli endpoint dei modelli ospitati personalizzati, assicurati che l'endpoint del modello sia accessibile tramite internet.
PROVIDER_ID	Obbligatorio per gli endpoint del modello di embedding di testo con supporto integrato	Il fornitore dell'endpoint del modello. Il valore predefinito è custom. Per Cloud SQL, imposta il fornitore su google per gli endpoint dei modelli Vertex AI, open_ai per gli endpoint dei modelli OpenAI, anthropic per gli endpoint dei modelli Anthropic, hugging_face per gli endpoint dei modelli Hugging Face o custom per gli endpoint dei modelli ospitati personalizzati.
MODEL_TYPE	Può essere NULL per gli endpoint del modello generico	Il tipo di modello. Puoi impostare questo valore su text_embedding per gli endpoint del modello di incorporamento di testo o su generic per tutti gli altri endpoint del modello.
MODEL_QUALIFIED_NAME	Obbligatorio per gli endpoint del modello OpenAI; può essere NULL per altri endpoint del modello	Il nome completo nel caso in cui l'endpoint del modello abbia più versioni o se l'endpoint del modello lo definisce, ad esempio textembedding-gecko@001 o textembedding-gecko@002. Poiché il modello textembedding-gecko@001 è preregistrato con la gestione degli endpoint del modello, puoi generare incorporamenti utilizzando textembedding-gecko@001 come ID modello.
AUTH_TYPE	Può essere NULL a meno che l'endpoint del modello non abbia un requisito di autenticazione specifico	Il tipo di autenticazione utilizzato dall'endpoint del modello. Puoi impostarlo su auth_type_cloudsql_service_agent_iam per i modelli Vertex AI o su auth_type_secret_manager per altri provider.
AUTH_ID	Passa come NULL per gli endpoint Vertex AI; obbligatorio per tutti gli altri endpoint dei modelli che archiviano i secret in Secret Manager	L'ID secret che hai impostato e che viene utilizzato successivamente durante la registrazione di un endpoint del modello.
GENERATE_HEADER_FUNCTION	Può essere NULL	Il nome della funzione che hai impostato per generare intestazioni personalizzate. La firma di questa funzione dipende dalla funzione mysql.ml_predict_row(). Consulta Funzione di generazione dell'intestazione HTTP.
INPUT_TRANSFORM_FUNCTION	Facoltativo per gli endpoint del modello di incorporamento di testo con supporto integrato; non impostare per gli endpoint del modello generico	La funzione per trasformare l'input della funzione di previsione corrispondente nell'input specifico del modello. Consulta Funzioni di trasformazione.
OUTPUT_TRANSFORM_FUNCTION	Facoltativo per gli endpoint del modello di incorporamento di testo con supporto integrato; non impostare per gli endpoint del modello generico	La funzione per trasformare l'output specifico del modello nell'output della funzione di previsione. Consulta Funzioni di trasformazione.

mysql.ml_alter_model_registration()

Di seguito viene mostrato come chiamare la funzione SQL mysql.ml_alter_model_registration() utilizzata per aggiornare i metadati dell'endpoint del modello:

    CALL
    mysql.ml_alter_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

mysql.ml_drop_model_registration()

Di seguito viene mostrato come chiamare la funzione SQL mysql.ml_drop_model_registration() utilizzata per eliminare un endpoint del modello:

  CALL mysql.ml_drop_model_registration('MODEL_ID');

Parametro	Descrizione
MODEL_ID	Un ID univoco per l'endpoint del modello che definisci.

mysql.ml_list_registered_model()

Di seguito viene mostrato come chiamare la funzione SQL mysql.ml_list_registered_model() utilizzata per elencare le informazioni sull'endpoint del modello:

  SELECT mysql.ml_list_registered_model('MODEL_ID');

Parametro	Descrizione
MODEL_ID	Un ID univoco per l'endpoint del modello che definisci.

mysql.cloudsql_ml_models

Di seguito viene mostrato come eseguire una query sulla tabella mysql.cloudsql_ml_models utilizzata per elencare le informazioni sugli endpoint del modello per tutti gli endpoint del modello:

  SELECT * FROM mysql.cloudsql_ml_models;

Secret

Utilizza questo riferimento per comprendere i parametri delle funzioni che ti consentono di gestire i secret.

mysql.ml_create_sm_secret_registration()

Di seguito viene mostrato come chiamare la funzione SQL mysql.ml_create_sm_secret_registration() utilizzata per aggiungere il secret creato in Secret Manager:

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

Parametro	Descrizione
SECRET_ID	L'ID secret che hai impostato e che viene utilizzato successivamente durante la registrazione di un endpoint del modello.
PROJECT_ID	L'ID del tuo progetto Google Cloud che contiene il secret. Questo progetto può essere diverso da quello che contiene l'istanza Cloud SQL.
SECRET_MANAGER_SECRET_ID	L'ID secret impostato in Secret Manager durante la creazione del secret.
VERSION_NUMBER	Il numero di versione dell'ID secret.

mysql.ml_alter_sm_secret_registration()

Di seguito viene mostrato come chiamare la funzione SQL mysql.ml_alter_sm_secret_registration() utilizzata per aggiornare le informazioni sul secret:

  CALL
    mysql.ml_alter_sm_secret_registration(
      'SECRET_ID',
      'projects/PROJECT_ID/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

Parametro	Descrizione
SECRET_ID	L'ID secret che hai impostato e che viene utilizzato successivamente durante la registrazione di un endpoint del modello.
PROJECT_ID	L'ID del tuo progetto Google Cloud che contiene il secret. Questo progetto può essere diverso da quello che contiene l'istanza Cloud SQL.
SECRET_MANAGER_SECRET_ID	L'ID secret impostato in Secret Manager durante la creazione del secret.
VERSION_NUMBER	Il numero di versione dell'ID secret.

mysql.ml_drop_sm_secret_registration()

Di seguito viene mostrato come chiamare la funzione SQL mysql.ml_drop_sm_secret_registration() utilizzata per eliminare un secret:

  CALL mysql.ml_drop_sm_secret_registration('SECRET_ID');

Parametro	Descrizione
SECRET_ID	L'ID secret che hai impostato e che viene utilizzato successivamente durante la registrazione di un endpoint del modello.

Funzioni di previsione

Utilizza questo riferimento per comprendere i parametri delle funzioni che ti consentono di generare incorporamenti o richiamare previsioni.

mysql.ml_embedding()

Di seguito viene mostrato come generare incorporamenti:

SELECT
  mysql.ml_embedding(
    'MODEL_ID',
    'CONTENT');

Parametro	Descrizione
MODEL_ID	Un ID univoco per l'endpoint del modello che definisci.
CONTENT	il testo da tradurre in un embedding vettoriale.

Per esempi di query SQL per generare embedding di testo, consulta Esempi.

mysql.ml_predict_row()

Di seguito viene mostrato come richiamare le previsioni:

SELECT
  mysql.ml_predict_row(
    'MODEL_ID',
    'REQUEST_BODY');

Parametro	Descrizione
MODEL_ID	Un ID univoco per l'endpoint del modello che definisci.
REQUEST_BODY	i parametri della funzione di previsione, in formato JSON.

Per esempi di query SQL per richiamare le previsioni, vedi Esempi.

Funzioni di trasformazione

Utilizza questo riferimento per comprendere i parametri delle funzioni di trasformazione di input e output.

Funzione di trasformazione dell'input

Di seguito è riportata la firma della funzione di previsione per gli endpoint del modello di incorporamento di testo:

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

Parametro	Descrizione
INPUT_TRANSFORM_FUNCTION	La funzione per trasformare l'input della funzione di previsione corrispondente nell'input specifico dell'endpoint del modello.

Funzione di trasformazione dell'output

Di seguito è riportata la firma della funzione di previsione per gli endpoint del modello di incorporamento di testo:

  CREATE FUNCTION IF NOT EXISTS
  OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;

Parametro	Descrizione
OUTPUT_TRANSFORM_FUNCTION	La funzione per trasformare l'output specifico dell'endpoint del modello nell'output della funzione di previsione.

Esempio di funzioni di trasformazione

Per capire meglio come creare funzioni di trasformazione per l'endpoint del modello, considera un endpoint del modello di incorporamento di testo ospitato personalizzato che richiede input e output JSON.

La seguente richiesta curl di esempio crea incorporamenti basati sul prompt e sull'endpoint del modello:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json"
    -d '{"prompt": ["Cloud SQL Embeddings"]}'

Viene restituita la seguente risposta di esempio:

[[ 0.3522231  -0.35932037  0.10156056  0.17734447 -0.11606089 -0.17266059
   0.02509351  0.20305622 -0.09787305 -0.12154685 -0.17313677 -0.08075467
   0.06821183 -0.06896557  0.1171584  -0.00931572  0.11875633 -0.00077482
   0.25604948  0.0519384   0.2034983  -0.09952664  0.10347155 -0.11935943
  -0.17872004 -0.08706985 -0.07056875 -0.05929353  0.4177883  -0.14381726
   0.07934926  0.31368294  0.12543282  0.10758053 -0.30210832 -0.02951015
   0.3908268  -0.03091059  0.05302926 -0.00114946 -0.16233777  0.1117468
  -0.1315904   0.13947351 -0.29569918 -0.12330773 -0.04354299 -0.18068913
   0.14445548  0.19481727]]

In base a questo input e a questa risposta, puoi dedurre quanto segue:

• Il modello prevede un input JSON tramite il campo prompt. Questo campo accetta un array di input. Poiché la funzione mysql.ml_embedding() è una funzione a livello di riga, prevede un input di testo alla volta. Pertanto, devi creare una funzione di trasformazione dell'input che crei un array con un singolo elemento.

• La risposta del modello è un array di embedding, uno per ogni prompt inserito nel modello. Poiché la funzione mysql.ml_embedding() è una funzione a livello di riga, restituisce un singolo input alla volta. Pertanto, devi creare una funzione di trasformazione dell'output che possa essere utilizzata per estrarre l'incorporamento dall'array.

L'esempio seguente mostra le funzioni di trasformazione di input e output utilizzate per questo endpoint del modello quando viene registrato con la gestione degli endpoint del modello:

funzione di trasformazione dell'input

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 $$

funzione di trasformazione dell'output

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 ;

HTTP header generation function

The following shows signature for the header generation function that can be used with the `mysql.ml_embedding()` prediction function when registering other text embedding model endpoints.

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

For the mysql.ml_predict_row() prediction function, the signature is as follows:

CREATE FUNCTION IF NOT EXISTS GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON DETERMINISTIC;

Parameter	Description
GENERATE_HEADERS	The function to generate custom headers. You can also pass the authorization header generated by the header generation function while registering the model endpoint.

Header generation function example

To better understand how to create a function that generates output in JSON key value pairs that are used as HTTP headers, consider a custom-hosted text embedding model endpoint.

The following example curl request passes the version HTTP header, which is used by the model endpoint:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
      -H "Content-Type: application/json" \
      -H "version: 2024-01-01" \
      -d '{"prompt": ["Cloud SQL Embeddings"]}'

The model expects text input through the version field and returns the version value in JSON format. The following example shows the header generation function that is used for this text embedding model endpoint when it is registered with model endpoint management:

DELIMITER $$
CREATE FUNCTION IF NOT EXISTS header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC
BEGIN
  RETURN JSON_OBJECT('version', '2024-01-01');
END;
$$
DELIMITER ;