Questa pagina è stata tradotta dall'API Cloud Translation.

Riferimento per la gestione degli endpoint dei modelli

MySQL | PostgreSQL | SQL Server

Questa pagina elenca i parametri per le diverse funzioni fornite dall'estensione google_ml_integration per registrare e gestire gli endpoint del modello. La pagina elenca anche i segreti 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 mostrato 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 incorporamento di testo con supporto integrato	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 incorporamento 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`	facoltativo 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; facoltativo per gli 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`	facoltativo, 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 `cloudsql_service_agent_iam` per i modelli Vertex AI o su `secret_manager` per altri provider.
`AUTH_ID`	non impostare per gli endpoint dei modelli 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`	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 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.

`google_ml.alter_model()`

Di seguito viene mostrato 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 mostrato 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 mostrato 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 sugli 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 mostrato 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 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.

`google_ml.alter_sm_secret()`

Di seguito viene mostrato 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 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.

`google_ml.drop_sm_secret()`

Di seguito viene mostrato 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 incorporamenti o richiamare previsioni.

`google_ml.embedding()`

Di seguito viene mostrato come generare incorporamenti:

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 embedding vettoriale.

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

`google_ml.predict_row()`

Di seguito viene mostrato 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, 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 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 dell'output

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

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

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 dell'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 dell'intestazione HTTP

Di seguito è riportata la firma della funzione di generazione dell'intestazione che può essere utilizzata con la funzione di google_ml.embedding() previsione durante la registrazione di altri endpoint del modello di incorporamento di testo.

  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 trasmettere l'intestazione di autorizzazione generata dalla funzione di generazione dell'intestazione durante la registrazione dell'endpoint del modello.

Esempio di funzione di generazione dell'intestazione

Per comprendere meglio come creare una funzione che genera output in coppie chiave-valore JSON utilizzate come intestazioni HTTP, considera un endpoint del modello di incorporamento di testo ospitato personalizzato.

La seguente richiesta curl di esempio passa l'intestazione HTTP version, che viene 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 l'input di testo tramite il campo version e restituisce il valore della versione in formato JSON. L'esempio seguente mostra la funzione di generazione dell'intestazione utilizzata per questo endpoint del modello di incorporamento di testo 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 di richiesta

Utilizza la funzione di generazione degli URL di richiesta per dedurre gli URL di richiesta per gli endpoint del modello con supporto integrato. Di seguito è riportata la firma di 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.

Riferimento per la gestione degli endpoint dei modelli Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Modelli

google_ml.create_model()

google_ml.alter_model()

google_ml.drop_model()

google_ml.list_model()

google_ml.model_info_view