Riferimento per la gestione degli endpoint dei modelli

Questa pagina elenca i parametri per le diverse funzioni fornite da l'estensione google_ml_integrationper registrare e gestire gli endpoint del modello. La pagina elenca anche i secret che puoi gestire utilizzando la gestione degli endpoint del modello. Per utilizzare i modelli di AI negli ambienti di produzione, consulta Crea applicazioni di AI generativa utilizzando Cloud SQL.

Modelli

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

google_ml.create_model()

Di seguito viene illustrato come chiamare la funzione SQL google_ml.create_model() utilizzata per registrare i metadati dell'endpoint del modello:

  CALL
    google_ml.create_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => '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

facoltativo per gli endpoint del modello di text embedding con supporto integrato

 L'endpoint specifico del modello quando aggiungi altri endpoint del modello di text embedding e generici.

L'URL della richiesta che la funzione genera per gli endpoint del modello integrati fa riferimento al progetto e alla regione o alla località del cluster. Se vuoi fare riferimento a un altro progetto, assicurati di specificare esplicitamente model_request_url.

Per gli endpoint del modello ospitati personalizzati, assicurati che l'endpoint del modello sia accessibile tramite internet.
PROVIDER_ID obbligatorio per gli endpoint del modello di text embedding con supporto integrato Il fornitore dell'endpoint del modello. Il valore predefinito è custom. Per Cloud SQL, imposta il provider su google per gli endpoint del modello Vertex AI, open_ai per gli endpoint del modello OpenAI, anthropic per gli endpoint del modello Anthropic, hugging_face per gli endpoint del modello Hugging Face o custom per gli endpoint del modello ospitati personalizzati.
MODEL_TYPE facoltativo per gli endpoint del modello generici Il tipo di modello. Puoi impostare questo valore su text_embedding per gli endpoint del modello di text embedding o generic per tutti gli altri endpoint del modello.
MODEL_QUALIFIED_NAME obbligatorio per gli endpoint del modello OpenAI; facoltativo 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 embedding utilizzando textembedding-gecko@001 come ID modello.
AUTH_TYPE facoltativo a meno che l'endpoint del modello non abbia requisiti di autenticazione specifici Il tipo di autenticazione utilizzato dall'endpoint del modello. Puoi impostarlo su cloudsql_service_agent_iam per i modelli Vertex AI o secret_manager per altri fornitori.
AUTH_ID non impostare per gli endpoint del modello Vertex AI; obbligatorio per tutti gli altri endpoint del modello 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 facoltativo Il nome della funzione che hai impostato per generare intestazioni personalizzate. La firma di questa funzione dipende dalla funzione google_ml.predict_row(). Consulta Funzione di generazione delle intestazioni HTTP.
INPUT_TRANSFORM_FUNCTION facoltativo per gli endpoint del modello di text embedding con supporto integrato;non impostare per gli endpoint del modello generici 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 text embedding con supporto integrato;non impostare per gli endpoint del modello generici La funzione per trasformare l'output specifico del modello nell'output della funzione di previsione. Consulta Funzioni di trasformazione.

google_ml.alter_model()

Di seguito viene illustrato come chiamare la funzione SQL google_ml.alter_model() utilizzata per aggiornare i metadati dell'endpoint del modello:

    CALL
    google_ml.alter_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');

google_ml.drop_model()

Di seguito viene illustrato come chiamare la funzione SQL google_ml.drop_model() utilizzata per eliminare un endpoint del modello:

  CALL google_ml.drop_model('MODEL_ID');
Parametro Descrizione
MODEL_ID Un ID univoco per l'endpoint del modello che definisci.

google_ml.list_model()

Di seguito viene illustrato come chiamare la funzione SQL google_ml.list_model() utilizzata per elencare le informazioni sull'endpoint del modello:

  SELECT google_ml.list_model('MODEL_ID');
Parametro Descrizione
MODEL_ID Un ID univoco per l'endpoint del modello che definisci.

google_ml.model_info_view

Di seguito viene illustrato come chiamare la visualizzazione google_ml.model_info_view utilizzata per elencare le informazioni sull'endpoint del modello per tutti gli endpoint del modello:

  SELECT * FROM google_ml.model_info_view;

Secret

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

google_ml.create_sm_secret()

Di seguito viene illustrato come chiamare la funzione SQL google_ml.create_sm_secret() utilizzata per aggiungere il secret creato in Secret Manager:

    CALL
    google_ml.create_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => '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 progetto che contiene il secret. Google Cloud Questo progetto può essere diverso dal progetto che contiene l'istanza Cloud SQL.
SECRET_MANAGER_SECRET_ID L'ID secret impostato in Secret Manager quando hai creato il secret.
VERSION_NUMBER Il numero di versione dell'ID secret.

google_ml.alter_sm_secret()

Di seguito viene illustrato come chiamare la funzione SQL google_ml.alter_sm_secret() utilizzata per aggiornare le informazioni sul secret:

  CALL
    google_ml.alter_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => '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 progetto che contiene il secret. Google Cloud Questo progetto può essere diverso dal progetto che contiene l'istanza Cloud SQL.
SECRET_MANAGER_SECRET_ID L'ID secret impostato in Secret Manager quando hai creato il secret.
VERSION_NUMBER Il numero di versione dell'ID secret.

google_ml.drop_sm_secret()

Di seguito viene illustrato come chiamare la funzione SQL google_ml.drop_sm_secret() utilizzata per eliminare un secret:

  CALL google_ml.drop_sm_secret('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 embedding o richiamare le previsioni.

google_ml.embedding()

Di seguito viene illustrato come generare embedding:

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    contents => 'CONTENT');
Parametro Descrizione
MODEL_ID Un ID univoco per l'endpoint del modello che definisci.
CONTENT il testo da tradurre in un vector embedding.

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

google_ml.predict_row()

Di seguito viene illustrato come richiamare le previsioni:

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => '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, consulta Esempi.

Funzioni di trasformazione

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

Funzione di trasformazione di input

Di seguito è riportata la firma per la funzione di previsione per gli endpoint del modello di text embedding:

  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;
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 di output

Di seguito è riportata la firma per la funzione di previsione per gli endpoint del modello di text embedding:

  CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];
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 comprendere meglio come creare funzioni di trasformazione per l'endpoint del modello, prendi in considerazione un endpoint del modello di text embedding ospitato personalizzato che richiede input e output JSON.

La seguente richiesta curl di esempio crea embedding in base al prompt e all'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 alla risposta, puoi dedurre quanto segue:

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

  • La risposta del modello è un array di embedding, uno per ogni input del prompt al modello. Poiché la funzione google_ml.embedding() è una funzione a livello di riga, restituisce un singolo input alla volta. Pertanto, devi creare una funzione di trasformazione di output che possa essere utilizzata per estrarre l'embedding 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 di input

CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;

Funzione di trasformazione di output

CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS REAL[]
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_output REAL[];
BEGIN
SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
RETURN transformed_output;
END;
$$;

Funzione di generazione delle intestazioni HTTP

Di seguito è riportata la firma per la funzione di generazione delle intestazioni che può essere utilizzata con la google_ml.embedding() funzione di previsione durante la registrazione di altri endpoint del modello di text embedding.

  CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

Per la funzione di previsione google_ml.predict_row(), la firma è la seguente:

CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON;
Parametro Descrizione
GENERATE_HEADERS La funzione per generare intestazioni personalizzate. Puoi anche passare l'intestazione di autorizzazione generata dalla funzione di generazione delle intestazioni durante la registrazione dell'endpoint del modello.

Esempio di funzione di generazione delle intestazioni

Per comprendere meglio come creare una funzione che generi output in coppie chiave-valore JSON utilizzate come intestazioni HTTP, prendi in considerazione un endpoint del modello di text embedding ospitato personalizzato.

La seguente richiesta curl di esempio passa l'intestazione HTTP version, utilizzata dall'endpoint del modello:

  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"]}'

Il modello prevede input di testo tramite il campo version e restituisce il valore della versione in formato JSON. L'esempio seguente mostra la funzione di generazione delle intestazioni utilizzata per questo endpoint del modello di text embedding quando viene registrato con la gestione degli endpoint del modello:

sql CREATE OR REPLACE FUNCTION header_gen_fn(model_id VARCHAR(100), input_text TEXT) RETURNS JSON LANGUAGE plpgsql AS $$ BEGIN RETURN json_build_object('version', '2024-01-01')::JSON; END; $$;

Generazione dell'URL della richiesta

Utilizza la funzione di generazione dell'URL della richiesta per dedurre gli URL delle richieste per gli endpoint del modello con supporto integrato. Di seguito è riportata la firma per questa funzione:

CREATE OR REPLACE FUNCTION GENERATE_REQUEST_URL(provider google_ml.model_provider, model_type google_ml.MODEL_TYPE, model_qualified_name VARCHAR(100), model_region VARCHAR(100) DEFAULT NULL)
Parametro Descrizione
GENERATE_REQUEST_URL La funzione per generare l'URL della richiesta generato dall'estensione per gli endpoint del modello con supporto integrato.