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'estensionegoogle_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 Creare 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 definito.
`REQUEST_URL`	Facoltativo per gli endpoint del modello di incorporamento di testo con supporto integrato	L'endpoint specifico del modello quando aggiungi altri endpoint di embedding del testo e modelli generici. L'URL di richiesta generato dalla funzione per gli endpoint dei modelli integrati fa riferimento al progetto e alla regione o alla posizione 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 in modo personalizzato, 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 provider 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 in modo personalizzato.
`MODEL_TYPE`	facoltativo per gli endpoint dei modelli generici	Il tipo di modello. Puoi impostare questo valore su `text_embedding` per gli endpoint dei modelli di embedding del testo o su `generic` per tutti gli altri endpoint del modello.
`MODEL_QUALIFIED_NAME`	obbligatorio per gli endpoint dei modelli OpenAI; facoltativo per gli altri endpoint dei modelli	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 dei modelli, 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 su `secret_manager` per altri provider.
`AUTH_ID`	non impostato per gli endpoint dei modelli Vertex AI; obbligatorio per tutti gli altri endpoint dei modelli che archiviano i segreti in Secret Manager	L'ID segreto impostato e utilizzato successivamente per registrare un endpoint del modello.
`GENERATE_HEADER_FUNCTION`	facoltativo	Il nome della funzione impostata per generare intestazioni personalizzate. La firma di questa funzione dipende dalla funzione `google_ml.predict_row()`. Consulta la funzione di generazione dell'intestazione HTTP.
`INPUT_TRANSFORM_FUNCTION`	Facoltativo per gli endpoint dei modelli di embedding di testo con supporto integrato; non impostare per gli endpoint dei modelli generici	La funzione per trasformare l'input della funzione di previsione corrispondente nell'input specifico del modello. Consulta la sezione Funzioni di trasformazione.
`OUTPUT_TRANSFORM_FUNCTION`	Facoltativo per gli endpoint del modello di embedding del testo 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 la sezione 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 definito.

`google_ml.list_model()`

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

  SELECT google_ml.list_model('MODEL_ID');

Parametro	Descrizione
`MODEL_ID`	Un ID univoco per l'endpoint del modello definito.

`google_ml.model_info_view`

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

`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 segreto impostato e utilizzato successivamente per registrare un endpoint del modello.
`PROJECT_ID`	L'ID del progetto Google Cloud contenente il segreto. Questo progetto può essere diverso da quello 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 segreto.

`google_ml.alter_sm_secret()`

Di seguito viene mostrato come chiamare la funzione SQL google_ml.alter_sm_secret() utilizzata per aggiornare le informazioni riservate:

  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 segreto impostato e utilizzato successivamente per registrare un endpoint del modello.
`PROJECT_ID`	L'ID del progetto Google Cloud contenente il segreto. Questo progetto può essere diverso da quello 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 segreto.

`google_ml.drop_sm_secret()`

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

  CALL google_ml.drop_sm_secret('SECRET_ID');

Parametro	Descrizione
`SECRET_ID`	L'ID segreto impostato e utilizzato successivamente per registrare un endpoint del modello.

Funzioni di previsione

Utilizza questo riferimento per comprendere i parametri delle funzioni che ti consentono di generare embedding o invocare le previsioni.

`google_ml.embedding()`

Di seguito viene mostrato come generare gli embedding:

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    contents => 'CONTENT');

Parametro	Descrizione
`MODEL_ID`	Un ID univoco per l'endpoint del modello definito.
`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 definito.
`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 per le 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 embedding del 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 embedding del 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 comprendere meglio come creare funzioni di trasformazione per l'endpoint del modello, considera un endpoint del modello di embedding di testo ospitato in modo personalizzato che richiede input e output JSON.

Il seguente esempio di richiesta cURL 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 a questa risposta, puoi dedurre quanto segue:

Il modello si aspetta 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 fornito 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 dell'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 è registrato nella 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 previsione google_ml.embedding() durante la registrazione di altri endpoint del modello di embedding del 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 passare l'intestazione di autorizzazione generata dalla funzione di generazione dell'intestazione durante la registrazione dell'endpoint del modello.

Esempio di funzione di generazione di intestazioni

Per comprendere meglio come creare una funzione che generi output in coppie chiave/valore JSON utilizzate come intestazioni HTTP, valuta la possibilità di utilizzare un endpoint del modello di incorporamento di testo ospitato in modo personalizzato.

Il seguente esempio di richiesta cURL 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 si aspetta un 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 embedding del testo quando è registrato con la gestione degli endpoint del modello:

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 dell'URL di richiesta per dedurre gli URL di richiesta per gli endpoint del modello con il 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 il supporto integrato.