Documentation de référence sur la gestion des points de terminaison de modèle

Sélectionnez une version de la documentation :

Cette page 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 associés à la gestion des points de terminaison de modèles.

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

Pour en savoir plus, consultez Utiliser la gestion des points de terminaison de modèle avec AlloyDB Omni pour les modèles d'IA.

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 de modèle que vous définissez.
REQUEST_URL Facultatif pour les autres points de terminaison de modèle d'embedding textuel avec compatibilité intégrée Point de terminaison spécifique au modèle utilisé lors de l'ajout d'autres points de terminaison d'embeddings textuels et de modèle générique. Pour AlloyDB pour PostgreSQL, indiquez une URL https.

 L'URL de 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 obtenir la liste des URL de requête pour les points de terminaison de modèle Vertex AI, consultez URL de requête des points de terminaison de modèle Vertex AI.

 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 où se trouve AlloyDB.
PROVIDER_ID Obligatoire pour les points de terminaison de modèle d'embedding textuel avec compatibilité 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
  • open_ai pour les points de terminaison de modèles OpenAI
  • hugging_face pour les points de terminaison de modèles Hugging Face
  • anthropic pour les points de terminaison de modèles Anthropic
  • 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 cette option sur l'une des valeurs suivantes :
  • text_embedding pour les points de terminaison de 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'embeddings textuels avec compatibilité intégrée ; facultatif pour les autres points de terminaison de modèle Nom complet des modèles d'embeddings textuels avec compatibilité intégrée.

Pour les noms complets Vertex AI que vous devez utiliser pour les modèles préenregistrés, consultez Modèles Vertex AI préenregistrés.

Pour les noms complets que vous devez utiliser pour les modèles OpenAI avec compatibilité intégrée, consultez Modèles avec compatibilité 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 de 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.

Pour les modèles Anthropic, la gestion des points de terminaison de modèle fournit une fonction google_ml.anthropic_claude_header_gen_fn que vous pouvez utiliser pour les versions par défaut.

La signature de cette fonction dépend de la fonction de prédiction que vous utilisez. Consultez Fonction de génération d'en-tête.
INPUT_TRANSFORM_FUNCTION Facultatif pour les points de terminaison de modèle d'embedding textuel avec compatibilité intégrée ; ne pas définir 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. Consultez Fonctions de transformation.
OUTPUT_TRANSFORM_FUNCTION Facultatif pour les points de terminaison de modèle d'embedding textuel avec compatibilité intégrée ; ne pas définir 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. Consultez Fonctions de transformation.

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 de 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 de modèle que vous avez défini.

Vue google_ml.model_info_view

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 de 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.
SECRET_MANAGER_SECRET_ID ID de secret défini dans Secret Manager lorsque vous avez créé le secret.
VERSION_NUMBER Numéro de version de l'ID de 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 de secret :

  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 de 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 de modèle que vous définissez.
CONTENT Texte à traduire en embedding vectoriel.

Pour obtenir des exemples de requêtes SQL permettant de générer des embeddings textuels, consultez Exemples de fonctions de transformation pour AlloyDB Omni.

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 de modèle que vous définissez.
REQUEST_BODY Paramètres de l'appel de prédiction, au format JSON.

Pour obtenir des exemples de requêtes SQL permettant d'appeler des prédictions, consultez Exemples pour AlloyDB Omni.

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 d'entrée

Vous trouverez ci-dessous la signature de la fonction de prédiction pour les points de terminaison des modèles d'embeddings textuels :

  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 sortie

Vous trouverez ci-dessous la signature de la fonction de prédiction pour les points de terminaison des modèles d'embeddings textuels :

  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.

Exemples 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 textuel personnalisé et hébergé, qui nécessite des entrées et des sorties JSON.

L'exemple de requête cURL suivant crée des embeddings en fonction du prompt 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 prompt envoyé au 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 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 textuel.

  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 se présente comme suit :

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 textuel personnalisé et hébergé.

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 textuel lorsqu'il est enregistré auprès de la gestion des points de terminaison du 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 reposant sur 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', 'anthropic-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 créer les URL de requête pour les points de terminaison du modèle avec compatibilité 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 du modèle avec compatibilité 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 textuel. La gestion des points de terminaison de modèle inclut également les modèles Vertex AI préenregistrés et les modèles avec compatibilité intégrée. Pour en savoir plus sur les différents types de modèles, consultez Type de modèle.

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érieure
text_embedding
  • textembedding-gecko
  • text-embedding-gecko@001
 Version 1.3 et ultérieure

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-005 text-embedding
text-embedding-preview-0815 text-embedding
text-multilingual-embedding-002 text-embedding

Open AI

Nom complet du modèle Type de modèle
text-embedding-ada-002 text-embedding
text-embedding-3-small text-embedding
text-embedding-3-large text-embedding

Anthropic

Nom complet du modèle Type de modèle
claude-3-opus-20240229 generic
claude-3-sonnet-20240229 generic
claude-3-haiku-20240307 generic