Cette page présente la documentation de la version 15.7.0 d'AlloyDB Omni.
Accédez à Versions de la documentation AlloyDB Omni pour choisir une autre version.

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

Référence sur la gestion des points de terminaison du modèle

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 du modèle, ainsi que les secrets avec la gestion des points de terminaison du modèle.

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.

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 du modèle.

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 de modèle	Identifiant 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 lorsque vous ajoutez d'autres représentations vectorielles continues de texte et des points de terminaison de modèle génériques. Pour AlloyDB pour PostgreSQL, fournissez une URL `https`. L'URL de requête générée par la fonction pour les points de terminaison de modèle 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 la section URL de requête des points de terminaison de modèle Vertex AI. Pour les points de terminaison de modèle hébergés personnalisés, assurez-vous qu'ils sont accessibles depuis le réseau sur lequel se trouve AlloyDB.
`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 la valeur sur l'une des valeurs suivantes: `google` pour les points de terminaison de modèle Vertex AI `open_ai` pour les points de terminaison de modèle OpenAI `hugging_face` pour les points de terminaison de modèle Hugging Face `anthropic` pour les points de terminaison des modèles Anthropic `custom` pour d'autres fournisseurs
`MODEL_TYPE`	facultatif pour les points de terminaison de modèle génériques	Type de modèle. Définir sur l'une des valeurs suivantes: `text_embedding` pour les points de terminaison des modèles d'embeddings textuels `generic` pour tous les autres points de terminaison du 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 compatibles avec le traitement intégré. Pour connaître les noms qualifiés Vertex AI que vous devez utiliser pour les modèles préenregistrés, consultez Modèles Vertex AI préenregistrés. Pour connaître les noms qualifiés que vous devez utiliser pour les modèles OpenAI avec prise en charge intégrée, consultez Modèles 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 cette 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 ensuite utilisé 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 du 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 la page 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 prise en charge intégrée. Ne pas définir 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 la section Fonctions de transformation.
`OUTPUT_TRANSFORM_FUNCTION`	Facultatif pour les points de terminaison de modèle d'embedding textuel avec prise en charge intégrée. Ne pas définir 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 la section 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 que vous devez 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`	Identifiant 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 le point de terminaison du modèle:

  SELECT google_ml.list_model('MODEL_ID');

Paramètre	Description
`MODEL_ID`	Identifiant 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 sur les points de terminaison du modèle pour tous les points de terminaison du 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 ensuite utilisé 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 du 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 des 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 la section 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 secret que vous avez défini et qui a ensuite é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 représentations vectorielles continues ou d'appeler des prédictions.

Fonction `google_ml.embedding()`

Voici comment générer des représentations vectorielles continues:

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

Paramètre	Description
`MODEL_ID`	Identifiant unique du point de terminaison du 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 de texte, 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`	Identifiant 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.

Pour obtenir des exemples de requêtes SQL permettant d'appeler des prédictions, consultez la section 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 du modèle de représentation vectorielle continue 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 sortie

Vous trouverez ci-dessous la signature de la fonction de prédiction pour les points de terminaison du modèle de représentation vectorielle continue 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 votre point de terminaison de modèle, considérez un point de terminaison de modèle d'embedding de texte hébergé en mode personnalisé qui nécessite une entrée et une sortie JSON.

L'exemple de requête cURL suivant crée des représentations vectorielles continues basées sur l'invite et le 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"]}'

L'exemple de réponse suivant est renvoyé:

[[ 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 points suivants:

Le modèle s'attend à une entrée JSON via le champ prompt. Ce champ accepte un tableau d'entrées. Étant donné que 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 envoyée au modèle. Étant donné que la fonction google_ml.embedding() est une fonction au niveau des lignes, elle ne renvoie qu'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'encapsulation 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

La signature suivante montre 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 une sortie sous forme de paires clé-valeur JSON utilisées comme en-têtes HTTP, envisagez un point de terminaison de modèle d'encapsulation de texte hébergé en mode personnalisé.

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 à une entrée textuelle via le champ version et renvoie la valeur de 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 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', '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 inférer les URL de requête des points de terminaison du modèle avec prise en charge intégrée. La signature de cette fonction est la suivante:

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 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 représentation vectorielle continue de texte ou point de terminaison de modèle générique. La gestion des points de terminaison de modèle inclut également les modèles Vertex AI préenregistrés et les modèles compatibles intégrés. Pour en savoir plus sur les différents types de modèles, consultez la section 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érieures
`text_embedding`	`textembedding-gecko` `text-embedding-gecko@001`	Version 1.3 et ultérieures

Modèles compatibles en standard

Vertex AI

Nom du modèle qualifié	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`

OpenAI

Nom du modèle qualifié	Type de modèle
`text-embedding-ada-002`	`text-embedding`
`text-embedding-3-small`	`text-embedding`
`text-embedding-3-large`	`text-embedding`

Anthropic

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