Questa pagina è stata tradotta dall'API Cloud Translation.

Registra e chiama i modelli di AI remota utilizzando la gestione degli endpoint dei modelli

MySQL | PostgreSQL | SQL Server

Questa pagina descrive come richiamare le previsioni o generare embedding utilizzando un modello, quindi registrare l'endpoint del modello con la gestione degli endpoint del modello.

Per ulteriori informazioni sulla funzione google_ml.create_model(), consulta la documentazione di riferimento per la gestione degli endpoint dei modelli.

Prima di iniziare

Se l'endpoint del modello richiede l'autenticazione, attiva l'estensione google_ml_integration.
Configura l'autenticazione in base al provider del modello.
Assicurati di utilizzare il nome utente predefinito postgres per accedere al database.

Attivare l'estensione

Imposta il flag del database google_ml_integration.enable_model_support su on per l'istanza. Per ulteriori informazioni sull'impostazione dei flag di database, vedi Configurare i flag di database.
Connettiti all'istanza principale utilizzando un client psql o Cloud SQL Studio.
Esegui il seguente comando per assicurarti che l'estensione google_ml_integration sia aggiornata alla versione 1.4.2:
```
    ALTER EXTENSION google_ml_integration UPDATE TO '1.4.2'
```
Aggiungi l'estensione google_ml_integration versione 1.4.2 utilizzando psql:
```
  CREATE EXTENSION google_ml_integration VERSION '1.4.2';
```
(Facoltativo) Concedi l'autorizzazione a un utente PostgreSQL non super di gestire i metadati del modello:
```
  GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;
```
Sostituisci NON_SUPER_USER con il nome utente PostgreSQL non super.

Configura l'autenticazione

Le sezioni seguenti mostrano come configurare l'autenticazione prima di aggiungere un endpoint del modello Vertex AI o endpoint del modello ospitati in Google Cloud.

Configurare l'autenticazione per Vertex AI

Per utilizzare gli endpoint del modello Google Vertex AI, devi aggiungere le autorizzazioni Vertex AI all'account di servizio Cloud SQL basato su IAM che utilizzi per connetterti al database. Per ulteriori informazioni sull'integrazione con Vertex AI, consulta Eseguire l'integrazione di Cloud SQL con Vertex AI.

Configurare l'autenticazione per i modelli ospitati in modo personalizzato

Questa sezione spiega come configurare l'autenticazione se utilizzi Secret Manager. Per tutti i modelli, ad eccezione degli endpoint dei modelli Vertex AI, puoi archiviare le chiavi API o i token bearer in Secret Manager.

Se l'endpoint del modello non gestisce l'autenticazione tramite Secret Manager, questa sezione è facoltativa. Ad esempio, se l'endpoint del modello utilizza intestazioni HTTP per trasmettere le informazioni di autenticazione o non utilizza affatto l'autenticazione, non completare i passaggi descritti in questa sezione.

Per creare e utilizzare una chiave API o un token di accesso, segui questi passaggi:

Crea un secret in Secret Manager. Per ulteriori informazioni, vedi Creare un secret e accedere a una versione del secret.

Il nome e il percorso del secret vengono utilizzati nella funzione SQL google_ml.create_sm_secret().
Concedi le autorizzazioni all'istanza Cloud SQL per accedere al segreto.
```
  gcloud secrets add-iam-policy-binding SECRET_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
      --role="roles/secretmanager.secretAccessor"
```
Sostituisci quanto segue:
- SECRET_ID: l'ID segreto in Secret Manager.
- SERVICE_ACCOUNT_EMAIL: l'indirizzo email dell'account di servizio Cloud SQL basato su IAM. Per trovare questo indirizzo email, utilizza il comando gcloud sql instances describe INSTANCE_NAME e sostituisci INSTANCE_NAME con il nome dell'istanza. Il valore visualizzato accanto al parametro serviceAccountEmailAddress è l'indirizzo email.

Modelli di embedding di testo con supporto integrato

Questa sezione mostra come registrare gli endpoint del modello per la relativa gestione.

Modelli di embedding Vertex AI

La gestione degli endpoint dei modelli fornisce il supporto integrato per tutte le versioni del text-embedding-gecko modello di Vertex AI. Utilizza il nome completo per impostare la versione del modello su textembedding-gecko@001 o textembedding-gecko@002.

Poiché sia gli ID endpoint del modello textembedding-gecko sia quelli del modello textembedding-gecko@001 sono preregistrati con la gestione degli endpoint del modello, puoi utilizzarne uno direttamente come ID modello. Per questi modelli, l'estensione configura automaticamente le funzioni di trasformazione predefinite.

Assicurati che sia l'istanza Cloud SQL sia il modello Vertex AI su cui stai eseguendo una query si trovino nella stessa regione.

Per registrare l'endpoint del modello textembedding-gecko@002, chiama la funzione create_model:

  CALL
    google_ml.create_model(
      model_id => 'textembedding-gecko@002',
      model_provider => 'google',
      model_qualified_name => 'textembedding-gecko@002',
      model_type => 'text_embedding',
      model_auth_type => 'cloudsql_service_agent_iam');

Modelli di embedding di testo ospitati in modo personalizzato

Questa sezione mostra come registrare gli endpoint dei modelli personalizzati ospitati nelle reti all'interno di Google Cloud.

L'aggiunta di endpoint del modello di incorporamento di testo ospitato in modo personalizzato comporta la creazione di funzioni di trasformazione e, facoltativamente, di intestazioni HTTP personalizzate. D'altra parte, l'aggiunta di endpoint di modelli generici ospitati in modo personalizzato comporta, facoltativamente, la generazione di intestazioni HTTP personalizzate e l'impostazione dell'URL di richiesta del modello.

L'esempio seguente aggiunge l'endpoint del modello di incorporamento del testo custom-embedding-model ospitato da Cymbal, che è ospitato in Google Cloud. Le funzioni di trasformazione cymbal_text_input_transform e cymbal_text_output_transform vengono utilizzate per trasformare il formato di input e di output del modello nel formato di input e di output della funzione di previsione.

Per registrare gli endpoint dei modelli di embedding di testo ospitati in modo personalizzato:

Chiama il secret archiviato 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');
```
Sostituisci quanto segue:
- SECRET_ID: l'ID segreto impostato e successivamente utilizzato per registrare un endpoint del modello, ad esempio key1.
- SECRET_MANAGER_SECRET_ID: l'ID segreto impostato in Secret Manager quando hai creato il segreto.
- PROJECT_ID: l'ID del tuo progetto Google Cloud.
- VERSION_NUMBER: il numero di versione dell'ID segreto.
Nota: per impostazione predefinita, Secret Manager genera un'intestazione Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER per l'autenticazione. Se questo formato corrisponde al formato del token di accesso dell'endpoint del modello, non devi generare le intestazioni di autenticazione utilizzando la funzione di generazione delle intestazioni.

Crea le funzioni di trasformazione di input e output in base alla seguente firma per la funzione di previsione per gli endpoint del modello di embedding del testo. Per ulteriori informazioni su come creare funzioni di trasformazione, consulta l'esempio di funzioni di trasformazione.

Di seguito sono riportati esempi di funzioni di trasformazione specifiche per l'endpoint del modello di embedding del testo custom-embedding-model:

-- Input Transform Function corresponding to the custom model endpoint
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;
$$;
-- Output Transform Function corresponding to the custom model endpoint
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;
$$;

Chiama la funzione di creazione del modello per registrare l'endpoint del modello di embedding personalizzato:
```
CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'REQUEST_URL',
    model_provider => 'custom',
    model_type => 'text_embedding',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    model_qualified_name => 'MODEL_QUALIFIED_NAME',
    model_in_transform_fn => 'cymbal_text_input_transform',
    model_out_transform_fn => 'cymbal_text_output_transform');
```
Sostituisci quanto segue:
- MODEL_ID: obbligatorio. Un ID univoco per l'endpoint del modello che definisci (ad es. custom-embedding-model). A questo ID modello viene fatto riferimento per i metadati di cui l'endpoint del modello ha bisogno per generare embedding o invocare le previsioni.
- REQUEST_URL: obbligatorio. L'endpoint specifico del modello quando aggiungi l'embedding di testo personalizzato e gli endpoint del modello generico, ad esempio https://cymbal.com/models/text/embeddings/v1. Assicurati che l'endpoint del modello sia accessibile tramite un indirizzo IP interno. La gestione degli endpoint dei modelli non supporta gli indirizzi IP esterni.
- MODEL_QUALIFIED_NAME: obbligatorio se l'endpoint del modello utilizza un nome qualificato. Il nome completo nel caso in cui l'endpoint del modello abbia più versioni.
- SECRET_ID: l'ID segreto che hai utilizzato in precedenza nella procedura google_ml.create_sm_secret().

Modelli generici

Questa sezione mostra come registrare un endpoint del modello gemini-pro generico da Vertex AI Model Garden, che non ha il supporto integrato. Puoi registrare qualsiasi endpoint del modello generico ospitato in Google Cloud.

Cloud SQL supporta solo gli endpoint dei modelli disponibili tramite Vertex AI Model Garden e gli endpoint dei modelli ospitati in reti all'interno di Google Cloud.

Modello Gemini

L'esempio seguente aggiunge l'endpoint del modello gemini-1.0-pro da Model Garden di Vertex AI.

Per registrare l'endpoint del modello gemini-1.0-pro, chiama la funzione create model:

```sql
CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-1.0-pro:streamGenerateContent',
    model_provider => 'google',
    model_auth_type => 'cloudsql_service_agent_iam');
```

Replace the following:
* <code><var>MODEL_ID</var></code>: a unique ID for the model endpoint that you define (for example,<br> `gemini-1`). This model ID is referenced for metadata that the model endpoint needs to generate embeddings or invoke predictions.
* <code><var>PROJECT_ID</var></code>: the ID of your Google Cloud project.

Per saperne di più, scopri come richiedere le previsioni per gli endpoint dei modelli generici.

Passaggi successivi

Consulta la documentazione di riferimento per la gestione degli endpoint dei modelli.