Questa pagina mostra la documentazione per la versione 15.7.0 di AlloyDB Omni.
Vai a Versioni della documentazione di AlloyDB Omni per scegliere una versione diversa.

Questa pagina è stata tradotta dall'API Cloud Translation.

Riferimento per la gestione degli endpoint dei modelli

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

Prima di poter iniziare a utilizzare l'estensione, devi impostare il flag del database google_ml_integration.enable_model_support su on.

Per ulteriori informazioni, vedi Utilizzare la gestione degli endpoint dei modelli con AlloyDB Omni per AI 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 definito.
`REQUEST_URL`	Facoltativo per altri 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. Per AlloyDB per PostgreSQL, fornisci un URL `https`. L'URL della 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 un elenco di URL di richiesta per gli endpoint dei modelli Vertex AI, consulta URL di richiesta 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 embedding di testo con supporto integrato	Il provider 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 dei modelli OpenAI `hugging_face` per gli endpoint dei modelli Hugging Face `anthropic` per gli endpoint dei modelli Anthropic `custom` per altri fornitori
`MODEL_TYPE`	facoltativo per gli endpoint dei modelli generici	Il tipo di modello. Imposta una delle seguenti opzioni: `text_embedding` per gli endpoint dei modelli di incorporamento di testo `generic` per tutti gli altri endpoint del modello
`MODEL_QUALIFIED_NAME`	obbligatorio per i modelli di embedding di testo con supporto integrato; facoltativo per altri endpoint del modello	Il nome completo dei modelli di embedding 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 è necessario impostare questo valore se utilizzi le intestazioni di autenticazione.
`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 successivamente utilizzato per registrare un endpoint del modello.
`GENERATE_HEADER_FUNCTION`	facoltativo	Il nome della funzione che genera intestazioni personalizzate. Per i modelli Anthropic, la gestione degli endpoint del modello 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 utilizzata. Vedi Funzione di generazione di intestazioni.
`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 dei modelli di embedding di testo con supporto integrato; non impostare per gli endpoint dei modelli 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');

Per informazioni sui valori da impostare per ciascun parametro, consulta Creare 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 sugli 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 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()` 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 segreto impostato e successivamente utilizzato per registrare un endpoint del modello.
`PROJECT_ID`	L'ID del progetto Google Cloud che contiene il segreto.
`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()` funzione

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

Per informazioni sui valori da impostare per ciascun parametro, consulta Creare un segreto.

`google_ml.drop_sm_secret()` funzione

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 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 invocare le previsioni.

`google_ml.embedding()` funzione

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.

Ad esempio, per le query SQL per generare embedding 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 definito.
`REQUEST_BODY`	I parametri della funzione di previsione in formato JSON.

Ad esempio, per le query SQL per richiamare le previsioni, consulta Esempi per AlloyDB Omni.

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": ["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 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() quando registri 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 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 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;
$$;

Funzione di generazione dell'intestazione che utilizza 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 provider 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 provider del modello.

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.

Modelli supportati

Puoi utilizzare la gestione degli endpoint dei modelli per registrare qualsiasi embedding di testo o endpoint del modello generico. 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`