Questa pagina è stata tradotta dall'API Cloud Translation.

Riferimento per la gestione degli endpoint dei modelli

Seleziona una versione della documentazione:

Questa pagina elenca i parametri per le diverse funzioni fornite dall'estensione google_ml_integration per registrare e gestire gli endpoint modello e i secret con la gestione degli endpoint modello.

Devi impostare il flag del database google_ml_integration.enable_model_support su on prima di poter iniziare a utilizzare l'estensione.

Per maggiori informazioni, vedi Utilizzare la gestione degli endpoint dei modelli con AlloyDB Omni perAIi IA.

Modelli

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

`google_ml.create_model()` funzione

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 altri 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. Per AlloyDB per PostgreSQL, fornisci un URL `https`. L'URL della richiesta che la funzione genera per gli endpoint dei modelli integrati 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 un elenco degli URL delle richieste per gli endpoint dei modelli Vertex AI, consulta URL delle richieste degli endpoint dei modelli Vertex AI. Per gli endpoint dei modelli ospitati personalizzati, assicurati che l'endpoint del modello sia accessibile dalla rete in cui si trova AlloyDB.
`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`. Imposta uno dei seguenti valori: `google` per gli endpoint dei modelli Vertex AI `open_ai` per gli endpoint del modello OpenAI `hugging_face` per gli endpoint del modello Hugging Face `anthropic` per gli endpoint del modello Anthropic `custom` per altri fornitori
`MODEL_TYPE`	facoltativo per gli endpoint del modello generico	Il tipo di modello. Imposta uno dei seguenti valori: `text_embedding` per gli endpoint del modello di text embedding `generic` per tutti gli altri endpoint del modello
`MODEL_QUALIFIED_NAME`	obbligatorio per i modelli di incorporamento di testo con supporto integrato; facoltativo per altri endpoint del modello	Il nome completo dei modelli di incorporamento di testo con supporto integrato. Per i nomi qualificati di Vertex AI che devi utilizzare per i modelli preregistrati, consulta Modelli Vertex AI preregistrati. Per i nomi qualificati che devi utilizzare per i modelli OpenAI con supporto integrato, consulta Modelli con supporto integrato.
`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 `alloydb_service_agent_iam` per i modelli Vertex AI o su `secret_manager` per altri provider, se utilizzano Secret Manager per l'autenticazione. Non devi impostare questo valore se utilizzi le intestazioni di autenticazione.
`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 genera intestazioni personalizzate. Per i modelli Anthropic, la gestione degli endpoint dei modelli fornisce una funzione `google_ml.anthropic_claude_header_gen_fn` che puoi utilizzare per le versioni predefinite. La firma di questa funzione dipende dalla funzione di previsione che utilizzi. Vedi Funzione di generazione delle intestazioni.
`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');

Per informazioni sui valori da impostare per ciascun parametro, vedi Crea un modello.

`google_ml.drop_model()` funzione

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 hai definito.

`google_ml.list_model()` funzione

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 hai definito.

`google_ml.model_info_view` visualizzazione

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()` funzione

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.
`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()` funzione

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');

Per informazioni sui valori che devi impostare per ogni parametro, vedi Crea un secret.

`google_ml.drop_sm_secret()` funzione

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 è stato 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()` funzione

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

Per esempi di query SQL per generare incorporamenti di testo, consulta Esempi di funzioni di trasformazione per AlloyDB Omni.

`google_ml.predict_row()` funzione

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, consulta Esempi per AlloyDB Omni.

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 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": ["AlloyDB 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, possiamo 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 previsione google_ml.embedding() 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 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": ["AlloyDB 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:

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

Funzione di generazione dell'intestazione utilizzando la chiave API

Gli esempi seguenti mostrano come configurare l'autenticazione utilizzando la chiave API.

modello di embedding

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
BEGIN
  RETURN json_build_object('Authorization', 'API_KEY')::JSON;
END;
$$;

Sostituisci API_KEY con la chiave API del fornitore del modello.

modello generico

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  response_json JSON
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
transformed_output REAL[];
BEGIN
  -- code to add Auth token to API request
RETURN json_build_object('x-api-key', 'API_KEY', 'anthropic-version', '2023-06-01')::JSON;
END;
$$;

Sostituisci API_KEY con la chiave API del fornitore del modello.

Generazione dell'URL di 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 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.

Modelli supportati

Puoi utilizzare la gestione degli endpoint del modello per registrare qualsiasi endpoint di modello generico o di incorporamento di testo. La gestione degli endpoint dei modelli include anche i modelli Vertex AI preregistrati e i modelli con supporto integrato. Per saperne di più sui diversi tipi di modelli, consulta Tipo di modello.

Modelli Vertex AI preregistrati

Tipo di modello	ID modello	Versione estensione
`generic`	`gemini-1.5-pro:streamGenerateContent` `gemini-1.5-pro:generateContent` `gemini-1.0-pro:generateContent`	versione 1.4.2 e successive
`text_embedding`	`textembedding-gecko` `text-embedding-gecko@001`	versione 1.3 e successive

Modelli con supporto integrato

Vertex AI

Nome del modello qualificato	Tipo di modello
`text-embedding-gecko@001`	`text-embedding`
`text-embedding-gecko@003`	`text-embedding`
`text-embedding-004`	`text-embedding`
`text-embedding-005`	`text-embedding`
`text-embedding-preview-0815`	`text-embedding`
`text-multilingual-embedding-002`	`text-embedding`

OpenAI

Nome del modello qualificato	Tipo di modello
`text-embedding-ada-002`	`text-embedding`
`text-embedding-3-small`	`text-embedding`
`text-embedding-3-large`	`text-embedding`

Anthropic

Nome del modello qualificato	Tipo di modello
`claude-3-opus-20240229`	`generic`
`claude-3-sonnet-20240229`	`generic`
`claude-3-haiku-20240307`	`generic`