Cette page a été traduite par l'API Cloud Translation.

Appeler des modèles à l'aide de points de terminaison de modèles dans AlloyDB

L'aperçu de la gestion des points de terminaison de modèle vous permet d'enregistrer un point de terminaison de modèle, de gérer les métadonnées de point de terminaison de modèle dans votre cluster de base de données, puis d'interagir avec les modèles à l'aide de requêtes SQL. Il fournit l'extension google_ml_integration qui inclut des fonctions permettant d'ajouter et d'enregistrer les métadonnées du point de terminaison du modèle liées aux modèles, puis d'utiliser les modèles pour générer des embeddings vectoriels ou appeler des prédictions.

Voici quelques exemples de types de modèles que vous pouvez enregistrer à l'aide de la gestion des points de terminaison de modèle :

Modèles d'embedding textuel Vertex AI
Modèles d'embedding fournis par des fournisseurs tiers.
Modèles d'embedding de texte hébergés sur mesure
Modèles génériques avec une API basée sur JSON (par exemple, le modèle gemini-pro de Vertex AI Model Garden)

Fonctionnement

Vous pouvez utiliser la gestion des points de terminaison de modèle pour enregistrer un point de terminaison de modèle qui respecte les conditions suivantes :

Les entrées et sorties du modèle sont compatibles avec le format JSON.
Le modèle peut être appelé à l'aide du protocole REST.

Lorsque vous enregistrez un point de terminaison de modèle avec la gestion des points de terminaison de modèle, chaque point de terminaison est enregistré avec un ID de modèle unique que vous avez fourni comme référence au modèle. Vous pouvez utiliser cet ID de modèle pour interroger les modèles :

Générez des embeddings pour traduire les requêtes de texte en vecteurs numériques. Vous pouvez stocker les embeddings générés sous forme de données vectorielles lorsque l'extension pgvector est activée dans la base de données.
Appelez des prédictions pour appeler un modèle à l'aide de SQL dans une transaction.

Vos applications peuvent accéder à la gestion des points de terminaison de modèle à l'aide de l'extension google_ml_integration. Cette extension fournit les fonctions suivantes :

La fonction SQL google_ml.create_model(), qui permet d'enregistrer le point de terminaison du modèle utilisé dans la fonction de prédiction ou d'embedding.
La fonction SQL google_ml.create_sm_secret(), qui utilise des secrets dans Secret Manager Google Cloud, où les clés API sont stockées.
La fonction SQL google_ml.embedding(), qui est une fonction de prédiction générant des embeddings de texte.
Fonction SQL google_ml.predict_row() qui génère des prédictions lorsque vous appelez des modèles génériques compatibles avec le format d'entrée et de sortie JSON.
Autres fonctions d'assistance qui gèrent la génération d'URL personnalisées, la génération d'en-têtes HTTP ou la transmission de fonctions de transformation pour vos modèles génériques.
Fonctions permettant de gérer les points de terminaison et les secrets des modèles enregistrés.

Concepts clés

Avant de commencer à utiliser la gestion des points de terminaison de modèle, comprenez les concepts nécessaires pour vous connecter aux modèles et les utiliser.

Fournisseur de modèles

Fournisseur de modèle indique les fournisseurs d'hébergement de modèles compatibles. Le tableau suivant indique la valeur du fournisseur de modèle que vous devez définir en fonction du fournisseur de modèle que vous utilisez :

Fournisseur de modèles	Définir la fonction sur…
Vertex AI	`google`
Autres modèles	`custom`

Le fournisseur de modèle par défaut est custom.

La méthode d'authentification compatible varie en fonction du type de fournisseur. Les modèles Vertex AI utilisent le compte de service Distributed Cloud pour s'authentifier, tandis que d'autres fournisseurs peuvent utiliser Secret Manager pour s'authentifier.

Type de modèle

Type de modèle indique le type de modèle d'IA. L'extension est compatible avec l'embedding de texte ainsi qu'avec tout type de modèle générique. Les types de modèles compatibles que vous pouvez définir lorsque vous enregistrez un point de terminaison de modèle sont text-embedding et generic. La définition du type de modèle est facultative lors de l'enregistrement des points de terminaison de modèle génériques, car generic est le type de modèle par défaut.

Modèles d'embedding de texte avec prise en charge intégrée: La gestion des points de terminaison de modèle fournit une assistance intégrée pour toutes les versions du modèle textembedding-gecko par Vertex AI. Pour enregistrer ces points de terminaison de modèle, utilisez la fonction google_ml.create_model(). Distributed Cloud configure automatiquement des fonctions de transformation par défaut pour ces modèles.; Le type de modèle pour ces modèles est text-embedding.
Autres modèles d'embedding de texte: Pour les autres modèles d'embedding de texte, vous devez créer des fonctions de transformation pour gérer les formats d'entrée et de sortie compatibles avec le modèle. Si vous le souhaitez, vous pouvez utiliser la fonction de génération d'en-têtes HTTP qui génère les en-têtes personnalisés requis par votre modèle.; Le type de modèle pour ces modèles est text-embedding.
Modèles génériques: La gestion des points de terminaison de modèle permet également d'enregistrer tous les autres types de modèles, à l'exception des modèles d'embedding de texte. Pour appeler des prédictions pour des modèles génériques, utilisez la fonction google_ml.predict_row(). Vous pouvez définir des métadonnées de point de terminaison de modèle, telles qu'un point de terminaison de requête et des en-têtes HTTP spécifiques à votre modèle.; Vous ne pouvez pas transmettre de fonctions de transformation lorsque vous enregistrez un point de terminaison de modèle générique. Assurez-vous que, lorsque vous appelez des prédictions, l'entrée de la fonction est au format JSON et que vous analysez la sortie JSON pour obtenir la sortie finale.; Le type de modèle pour ces modèles est generic.

Authentification

Les types d'authentification indiquent le type d'authentification que vous pouvez utiliser pour vous connecter à la gestion des points de terminaison de modèle à l'aide de l'extension google_ml_integration. La configuration de l'authentification est facultative et n'est requise que si vous devez vous authentifier pour accéder à votre modèle.

Pour les modèles Vertex AI, le compte de service Distributed Cloud est utilisé pour l'authentification. Pour les autres modèles, une clé API ou un jeton du porteur stocké en tant que secret dans Secret Manager peuvent être utilisés avec la fonction SQL google_ml.create_sm_secret().

Le tableau suivant présente les types d'authentification que vous pouvez définir :

Méthode d'authentification	Définir la fonction sur…	Fournisseur de modèles
Agent de service Distributed Cloud	`alloydb_service_agent_iam`	Fournisseur Vertex AI
Secret Manager	`secret_manager`	fournisseurs tiers

Fonctions de prédiction

L'extension google_ml_integration inclut les fonctions de prédiction suivantes :

google_ml.embedding(): Utilisé pour appeler un point de terminaison de modèle d'embedding textuel enregistré afin de générer des embeddings. Il inclut une compatibilité intégrée avec le modèle textembedding-gecko de Vertex AI.; Pour les modèles d'embedding de texte sans prise en charge intégrée, les paramètres d'entrée et de sortie sont propres à un modèle et doivent être transformés pour que la fonction appelle le modèle. Créez une fonction de transformation des entrées pour transformer les entrées de la fonction de prédiction en entrées spécifiques au modèle, et une fonction de transformation des sorties pour transformer les sorties spécifiques au modèle en sorties de la fonction de prédiction.
google_ml.predict_row(): Utilisé pour appeler un point de terminaison de modèle générique enregistré, à condition qu'il soit compatible avec l'API basée sur JSON, afin d'appeler des prédictions.

Fonctions de transformation

Les fonctions de transformation modifient l'entrée dans un format que le modèle comprend et convertissent la réponse du modèle dans le format attendu par la fonction de prédiction. Les fonctions de transformation sont utilisées lors de l'enregistrement du point de terminaison du modèle text-embedding sans prise en charge intégrée. La signature des fonctions de transformation dépend de la fonction de prédiction pour le type de modèle.

Vous ne pouvez pas utiliser de fonctions de transformation lorsque vous enregistrez un point de terminaison de modèle generic.

Vous trouverez ci-dessous les signatures de la fonction de prédiction pour les modèles d'embedding de texte :

// define custom model specific input/output transform functions.
CREATE OR REPLACE FUNCTION input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

CREATE OR REPLACE FUNCTION output_transform_function(model_id VARCHAR(100), response_json JSON) RETURNS real[];

Fonction de génération d'en-tête HTTP

La fonction de génération d'en-têtes HTTP génère la sortie sous forme de paires clé/valeur JSON qui sont utilisées comme en-têtes HTTP. La signature de la fonction de prédiction définit les signatures de la fonction de génération d'en-tête.

L'exemple suivant montre la signature de la fonction de prédiction google_ml.embedding().

CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input TEXT) RETURNS JSON;

Pour la fonction de prédiction google_ml.predict_row(), la signature est la suivante :

CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON;

Enregistrer un modèle

Pour appeler des prédictions ou générer des embeddings à l'aide d'un modèle, enregistrez le point de terminaison du modèle avec la gestion des points de terminaison de modèle.

Pour en savoir plus sur la fonction google_ml.create_model(), consultez la documentation de référence sur la gestion des points de terminaison de modèle.

Avant d'enregistrer un point de terminaison de modèle avec la gestion des points de terminaison de modèle, vous devez activer l'extension google_ml_integration et configurer l'authentification en fonction du fournisseur de modèle, si votre point de terminaison de modèle nécessite une authentification.

Assurez-vous d'accéder à votre base de données avec le nom d'utilisateur par défaut postgres.

Configurer l'authentification

Les sections suivantes expliquent comment configurer l'authentification avant d'ajouter un point de terminaison de modèle Vertex AI ou des points de terminaison de modèle d'autres fournisseurs.

Configurer l'authentification pour Vertex AI

Pour utiliser les points de terminaison de modèle Google Vertex AI, vous devez ajouter des autorisations Vertex AI au compte de service que vous avez utilisé lors de l'installation d'AlloyDB Omni.

Configurer l'authentification pour d'autres fournisseurs de modèles

Pour tous les modèles, à l'exception des modèles Vertex AI, vous pouvez stocker vos clés API ou vos jetons du porteur dans Secret Manager. Cette étape est facultative si votre point de terminaison de modèle ne gère pas l'authentification via Secret Manager, par exemple s'il utilise des en-têtes HTTP pour transmettre les informations d'authentification ou s'il n'utilise pas du tout l'authentification.

Cette section explique comment configurer l'authentification si vous utilisez Secret Manager.

Pour créer et utiliser une clé API ou un jeton du porteur, procédez comme suit :

Créez le secret dans Secret Manager.

Le nom et le chemin du secret sont utilisés dans la fonction SQL google_ml.create_sm_secret().
Accordez au cluster Distributed Cloud les autorisations d'accès au secret.
```
  gcloud secrets add-iam-policy-binding 'SECRET_ID' \
      --member="serviceAccount:SERVICE_ACCOUNT_ID" \
      --role="roles/secretmanager.secretAccessor"
```
Remplacez les éléments suivants :
- SECRET_ID : ID du secret dans Secret Manager.
- SERVICE_ACCOUNT_ID : ID du compte de service que vous avez créé à l'étape précédente. Assurez-vous qu'il s'agit du même compte que celui que vous avez utilisé lors de l'installation d'AlloyDB Omni. Cela inclut le suffixe complet PROJECT_ID.iam.gserviceaccount.com. Par exemple : my-service@my-project.iam.gserviceaccount.com.
  
  Vous pouvez également attribuer ce rôle au compte de service au niveau du projet.

Générer des embeddings

Cette section décrit un aperçu qui vous permet d'expérimenter l'enregistrement d'un point de terminaison de modèle d'IA et l'appel de prédictions avec la gestion des points de terminaison de modèle.

Une fois les points de terminaison de modèle ajoutés et enregistrés dans la gestion des points de terminaison de modèle, vous pouvez les référencer à l'aide de l'ID de modèle pour générer des embeddings.

Avant de commencer

Assurez-vous d'avoir enregistré le point de terminaison de votre modèle auprès du service de gestion des points de terminaison de modèles.

Générer des embeddings

Utilisez la fonction SQL google_ml.embedding() pour appeler le point de terminaison du modèle enregistré avec le type de modèle d'embedding de texte afin de générer des embeddings.

Pour appeler le modèle et générer des embeddings, utilisez la requête SQL suivante :

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

Remplacez les éléments suivants :

MODEL_ID : ID du modèle que vous avez défini lors de l'enregistrement du point de terminaison du modèle.
CONTENT : texte à traduire en embedding vectoriel.

Exemples

Vous trouverez dans cette section quelques exemples de génération d'embeddings à l'aide du point de terminaison du modèle enregistré.

Modèles d'embeddings textuels avec prise en charge intégrée

Pour générer des embeddings pour un point de terminaison de modèle textembedding-gecko@002 enregistré, exécutez l'instruction suivante :

    SELECT
      google_ml.embedding(
        model_id => 'textembedding-gecko@002',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');

Appeler des prédictions

Une fois les points de terminaison de modèle ajoutés et enregistrés dans la gestion des points de terminaison de modèle, vous pouvez les référencer à l'aide de l'ID de modèle pour appeler des prédictions.

Avant de commencer

Assurez-vous d'avoir enregistré le point de terminaison de votre modèle auprès du service de gestion des points de terminaison de modèles.

Appeler des prédictions pour des modèles génériques

Utilisez la fonction SQL google_ml.predict_row() pour appeler un point de terminaison de modèle générique enregistré afin d'appeler des prédictions. Vous pouvez utiliser la fonction google_ml.predict_row() avec n'importe quel type de modèle.

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');

Remplacez les éléments suivants :

MODEL_ID : ID du modèle que vous avez défini lors de l'enregistrement du point de terminaison du modèle.
REQUEST_BODY : paramètres de la fonction de prédiction, au format JSON.

Exemples

Cette section présente quelques exemples d'appel de prédictions à l'aide de points de terminaison de modèles enregistrés.

Pour générer des prédictions pour un point de terminaison de modèle gemini-pro enregistré, exécutez l'instruction suivante :

    SELECT
        json_array_elements(
        google_ml.predict_row(
            model_id => 'gemini-pro',
            request_body => '{
        "contents": [
            {
                "role": "user",
                "parts": [
                    {
                        "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
                    }
                ]
            }
        ]
        }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

Documentation de référence de l'API de gestion des points de terminaison de modèle

Cette section liste les paramètres des différentes fonctions fournies par l'extension google_ml_integration pour enregistrer et gérer les points de terminaison de modèles, ainsi que les secrets avec la gestion des points de terminaison de modèles.

Vous devez définir l'indicateur de base de données google_ml_integration.enable_model_support sur on avant de pouvoir commencer à utiliser l'extension.

Modèles

Utilisez cette référence pour comprendre les paramètres des fonctions qui vous permettent de gérer les points de terminaison des modèles.

Fonction `google_ml.create_model()`

L'exemple suivant montre comment appeler la fonction SQL google_ml.create_model() utilisée pour enregistrer les métadonnées du point de terminaison du modèle :

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

Paramètre	Obligatoire	Description
`MODEL_ID`	Obligatoire pour tous les points de terminaison du modèle	ID unique du point de terminaison du modèle que vous définissez.
`REQUEST_URL`	Facultatif pour les autres points de terminaison de modèle d'embedding de texte avec prise en charge intégrée	Point de terminaison spécifique au modèle lors de l'ajout d'autres points de terminaison d'intégration de texte et de modèle générique. Pour AlloyDB pour PostgreSQL, indiquez une URL `https`. L'URL de la requête que la fonction génère pour les points de terminaison de modèles intégrés fait référence au projet et à la région ou à l'emplacement de votre cluster. Si vous souhaitez faire référence à un autre projet, assurez-vous de spécifier explicitement `model_request_url`. Pour les points de terminaison de modèles hébergés personnalisés, assurez-vous que le point de terminaison du modèle est accessible depuis le réseau sur lequel se trouve Distributed Cloud.
`PROVIDER_ID`	Obligatoire pour les points de terminaison de modèle d'embedding de texte avec prise en charge intégrée	Fournisseur du point de terminaison du modèle. La valeur par défaut est `custom`. Définissez l'une des valeurs suivantes : `google` pour les points de terminaison de modèles Vertex AI `custom` pour les autres fournisseurs
`MODEL_TYPE`	facultatif pour les points de terminaison de modèle génériques.	Type de modèle. Définissez l'une des options suivantes : `text_embedding` pour les points de terminaison des modèles d'embeddings textuels `generic` pour tous les autres points de terminaison de modèle
`MODEL_QUALIFIED_NAME`	Obligatoire pour les modèles d'embedding de texte avec prise en charge intégrée ; facultatif pour les autres points de terminaison de modèle	Nom complet des modèles d'embedding de texte avec prise en charge intégrée.
`AUTH_TYPE`	Facultatif, sauf si le point de terminaison du modèle présente des exigences d'authentification spécifiques	Type d'authentification utilisé par le point de terminaison du modèle. Vous pouvez définir la valeur sur `alloydb_service_agent_iam` pour les modèles Vertex AI ou sur `secret_manager` pour les autres fournisseurs, s'ils utilisent Secret Manager pour l'authentification. Vous n'avez pas besoin de définir cette valeur si vous utilisez des en-têtes d'authentification.
`AUTH_ID`	Ne pas définir pour les points de terminaison de modèle Vertex AI ; obligatoire pour tous les autres points de terminaison de modèle qui stockent des secrets dans Secret Manager	ID secret que vous définissez et qui est utilisé par la suite lors de l'enregistrement d'un point de terminaison de modèle.
`GENERATE_HEADER_FUNCTION`	facultatif	Nom de la fonction qui génère des en-têtes personnalisés. La signature de cette fonction dépend de la fonction de prédiction que vous utilisez.
`INPUT_TRANSFORM_FUNCTION`	Facultatif pour les points de terminaison de modèle d'embedding de texte avec prise en charge intégrée. Ne définissez pas cette valeur pour les points de terminaison de modèle génériques.	Fonction permettant de transformer l'entrée de la fonction de prédiction correspondante en entrée spécifique au modèle.
`OUTPUT_TRANSFORM_FUNCTION`	Facultatif pour les points de terminaison de modèle d'embedding de texte avec prise en charge intégrée. Ne définissez pas cette valeur pour les points de terminaison de modèle génériques.	Fonction permettant de transformer la sortie spécifique au modèle en sortie de la fonction de prédiction.

`google_ml.alter_model()`

L'exemple suivant montre comment appeler la fonction SQL google_ml.alter_model() utilisée pour mettre à jour les métadonnées du point de terminaison du modèle :

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

Pour en savoir plus sur les valeurs à définir pour chaque paramètre, consultez Créer un modèle.

Fonction `google_ml.drop_model()`

L'exemple suivant montre comment appeler la fonction SQL google_ml.drop_model() utilisée pour supprimer un point de terminaison de modèle :

  CALL google_ml.drop_model('MODEL_ID');

Paramètre	Description
`MODEL_ID`	ID unique du point de terminaison du modèle que vous avez défini.

Fonction `google_ml.list_model()`

L'exemple suivant montre comment appeler la fonction SQL google_ml.list_model() utilisée pour lister les informations sur les points de terminaison de modèle :

  SELECT google_ml.list_model('MODEL_ID');

Paramètre	Description
`MODEL_ID`	ID unique du point de terminaison du modèle que vous avez défini.

`google_ml.model_info_view` vue

L'exemple suivant montre comment appeler la vue google_ml.model_info_view utilisée pour lister les informations des points de terminaison de modèle pour tous les points de terminaison de modèle :

  SELECT * FROM google_ml.model_info_view;

Secrets

Utilisez cette référence pour comprendre les paramètres des fonctions qui vous permettent de gérer les secrets.

Fonction `google_ml.create_sm_secret()`

L'exemple suivant montre comment appeler la fonction SQL google_ml.create_sm_secret() utilisée pour ajouter le secret créé dans 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');

Paramètre	Description
`SECRET_ID`	ID secret que vous définissez et qui est utilisé par la suite lors de l'enregistrement d'un point de terminaison de modèle.
`PROJECT_ID`	ID de votre projet Google Cloud contenant le secret. Ce projet peut être différent de celui qui contient votre cluster AlloyDB pour PostgreSQL. Pour AlloyDB Omni, ID de votre projet Google Cloud contenant le secret.
`SECRET_MANAGER_SECRET_ID`	ID du secret défini dans Secret Manager lorsque vous avez créé le secret.
`VERSION_NUMBER`	Numéro de version de l'ID du secret.

Fonction `google_ml.alter_sm_secret()`

L'exemple suivant montre comment appeler la fonction SQL google_ml.alter_sm_secret() utilisée pour mettre à jour les informations secrètes :

  CALL
    google_ml.alter_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

Pour en savoir plus sur les valeurs que vous devez définir pour chaque paramètre, consultez Créer un secret.

Fonction `google_ml.drop_sm_secret()`

L'exemple suivant montre comment appeler la fonction SQL google_ml.drop_sm_secret() utilisée pour supprimer un secret :

  CALL google_ml.drop_sm_secret('SECRET_ID');

Paramètre	Description
`SECRET_ID`	ID du secret que vous avez défini et qui a été utilisé lors de l'enregistrement d'un point de terminaison de modèle.

Fonctions de prédiction

Utilisez cette référence pour comprendre les paramètres des fonctions qui vous permettent de générer des embeddings ou d'appeler des prédictions.

Fonction `google_ml.embedding()`

Voici comment générer des embeddings :

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

Paramètre	Description
`MODEL_ID`	ID unique du point de terminaison du modèle que vous définissez.
`CONTENT`	Texte à traduire en embedding vectoriel.

Fonction `google_ml.predict_row()`

Voici comment appeler des prédictions :

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');

Paramètre	Description
`MODEL_ID`	ID unique du point de terminaison du modèle que vous définissez.
`REQUEST_BODY`	Paramètres de la fonction de prédiction, au format JSON.

Fonctions de transformation

Utilisez cette référence pour comprendre les paramètres des fonctions de transformation d'entrée et de sortie.

Fonction de transformation des entrées

Vous trouverez ci-dessous la signature de la fonction de prédiction pour les points de terminaison des modèles de représentations vectorielles continues de texte :

  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

Paramètre	Description
`INPUT_TRANSFORM_FUNCTION`	Fonction permettant de transformer l'entrée de la fonction de prédiction correspondante en entrée spécifique au point de terminaison du modèle.

Fonction de transformation de la sortie

Vous trouverez ci-dessous la signature de la fonction de prédiction pour les points de terminaison des modèles de représentations vectorielles continues de texte :

  CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];

Paramètre	Description
`OUTPUT_TRANSFORM_FUNCTION`	Fonction permettant de transformer la sortie spécifique au point de terminaison du modèle en sortie de la fonction de prédiction.

Exemple de fonctions de transformation

Pour mieux comprendre comment créer des fonctions de transformation pour le point de terminaison de votre modèle, prenons l'exemple d'un point de terminaison de modèle d'embedding de texte hébergé sur mesure qui nécessite des entrées et des sorties JSON.

L'exemple de requête cURL suivant crée des embeddings en fonction de l'invite et du point de terminaison du modèle :

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json"
    -d '{"prompt": ["AlloyDB Embeddings"]}'

La réponse suivante est renvoyée :

[[ 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]]

Sur la base de cette entrée et de cette réponse, nous pouvons déduire les éléments suivants :

Le modèle s'attend à une entrée JSON via le champ prompt. Ce champ accepte un tableau d'entrées. Comme la fonction google_ml.embedding() est une fonction au niveau de la ligne, elle s'attend à une entrée de texte à la fois. Vous devez donc créer une fonction de transformation d'entrée qui crée un tableau avec un seul élément.
La réponse du modèle est un tableau d'embeddings, un pour chaque requête saisie dans le modèle. Comme la fonction google_ml.embedding() est une fonction au niveau de la ligne, elle renvoie une seule entrée à la fois. Vous devez donc créer une fonction de transformation de sortie qui peut être utilisée pour extraire l'embedding du tableau.

L'exemple suivant montre les fonctions de transformation d'entrée et de sortie utilisées pour ce point de terminaison de modèle lorsqu'il est enregistré auprès de la gestion des points de terminaison de modèle :

fonction de transformation d'entrée

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

fonction de transformation de la sortie

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

Fonction de génération d'en-tête HTTP

Vous trouverez ci-dessous la signature de la fonction de génération d'en-tête qui peut être utilisée avec la fonction de prédiction google_ml.embedding() lors de l'enregistrement d'autres points de terminaison de modèle d'embedding de texte.

  CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

Pour la fonction de prédiction google_ml.predict_row(), la signature est la suivante :

CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON;

Paramètre	Description
`GENERATE_HEADERS`	Fonction permettant de générer des en-têtes personnalisés. Vous pouvez également transmettre l'en-tête d'autorisation généré par la fonction de génération d'en-tête lors de l'enregistrement du point de terminaison du modèle.

Exemple de fonction de génération d'en-tête

Pour mieux comprendre comment créer une fonction qui génère des résultats sous forme de paires clé/valeur JSON utilisées comme en-têtes HTTP, prenons l'exemple d'un point de terminaison de modèle d'embedding de texte hébergé sur mesure.

L'exemple de requête cURL suivant transmet l'en-tête HTTP version utilisé par le point de terminaison du modèle :

  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"]}'

Le modèle s'attend à recevoir une entrée de texte via le champ version et renvoie la valeur de la version au format JSON. L'exemple suivant montre la fonction de génération d'en-tête utilisée pour ce point de terminaison de modèle d'embedding de texte lorsqu'il est enregistré auprès de la gestion des points de terminaison de modèle :

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

Fonction de génération d'en-tête à l'aide d'une clé API

Les exemples suivants montrent comment configurer l'authentification à l'aide de la clé API.

modèle d'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;
$$;

Remplacez API_KEY par la clé API du fournisseur de modèles.

modèle générique

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', 'model-version', '2023-06-01')::JSON;
END;
$$;

Remplacez API_KEY par la clé API du fournisseur de modèles.

Génération d'URL de requête

Utilisez la fonction de génération d'URL de requête pour déduire les URL de requête pour les points de terminaison de modèle avec prise en charge intégrée. Vous trouverez ci-dessous la signature de cette fonction :

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)

Paramètre	Description
`GENERATE_REQUEST_URL`	Fonction permettant de générer l'URL de la requête générée par l'extension pour les points de terminaison de modèle avec prise en charge intégrée.

Modèles compatibles

Vous pouvez utiliser la gestion des points de terminaison de modèle pour enregistrer n'importe quel point de terminaison de modèle générique ou d'embedding de texte. La gestion des points de terminaison de modèle inclut également les modèles Vertex AI préenregistrés et les modèles avec assistance intégrée.

Modèles Vertex AI préenregistrés

Type de modèle	ID du modèle	Version de l'extension
`generic`	`gemini-1.5-pro:streamGenerateContent` `gemini-1.5-pro:generateContent` `gemini-1.0-pro:generateContent`	version 1.4.2 et ultérieures
`text_embedding`	`textembedding-gecko` `text-embedding-gecko@001`	version 1.3 et ultérieures

Modèles avec compatibilité intégrée

Vertex AI

Nom complet du modèle	Type de modèle
`text-embedding-gecko@001`	`text-embedding`
`text-embedding-gecko@003`	`text-embedding`
`text-embedding-004`	`text-embedding`
`text-embedding-preview-0815`	`text-embedding`
`text-multilingual-embedding-002`	`text-embedding`

Appeler des modèles à l'aide de points de terminaison de modèles dans AlloyDB Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Fonctionnement

Concepts clés

Fournisseur de modèles

Type de modèle

Authentification

Fonctions de prédiction

Fonctions de transformation

Fonction de génération d'en-tête HTTP

Enregistrer un modèle

Configurer l'authentification

Configurer l'authentification pour Vertex AI

Configurer l'authentification pour d'autres fournisseurs de modèles

Générer des embeddings

Avant de commencer

Générer des embeddings

Exemples

Modèles d'embeddings textuels avec prise en charge intégrée

Appeler des prédictions

Avant de commencer

Appeler des prédictions pour des modèles génériques

Exemples

Documentation de référence de l'API de gestion des points de terminaison de modèle

Modèles

Fonction google_ml.create_model()

google_ml.alter_model()

Fonction google_ml.drop_model()

Fonction google_ml.list_model()

google_ml.model_info_view vue

Secrets

Fonction google_ml.create_sm_secret()

Fonction google_ml.alter_sm_secret()

Fonction google_ml.drop_sm_secret()

Fonctions de prédiction

Fonction google_ml.embedding()

Fonction google_ml.predict_row()

Fonctions de transformation

Fonction de transformation des entrées

Fonction de transformation de la sortie

Exemple de fonctions de transformation

fonction de transformation d'entrée

fonction de transformation de la sortie

Fonction de génération d'en-tête HTTP

Exemple de fonction de génération d'en-tête

Fonction de génération d'en-tête à l'aide d'une clé API

modèle d'embedding

modèle générique

Génération d'URL de requête

Modèles compatibles

Modèles Vertex AI préenregistrés

Modèles avec compatibilité intégrée

Vertex AI

Appeler des modèles à l'aide de points de terminaison de modèles dans AlloyDB

Fonction `google_ml.create_model()`

`google_ml.alter_model()`

Fonction `google_ml.drop_model()`

Fonction `google_ml.list_model()`

`google_ml.model_info_view` vue

Fonction `google_ml.create_sm_secret()`

Fonction `google_ml.alter_sm_secret()`

Fonction `google_ml.drop_sm_secret()`

Fonction `google_ml.embedding()`

Fonction `google_ml.predict_row()`