Les extensions sont des connexions à des API externes. Elles peuvent traiter des données en temps réel et se connecter à des API externes pour effectuer des actions réelles. Vertex AI fournit un service d'extension qui peut importer, gérer et exécuter des extensions.
Ce service d'extension peut être lié à une application qui traite les requêtes des utilisateurs et communique avec un LLM. Le service d'extension peut fournir à l'application un ensemble d'extensions et les opérations que ces extensions peuvent effectuer. Chaque fois que l'application reçoit une requête utilisateur, elle fournit ces informations au LLM. Si le modèle détermine qu'il doit déléguer le traitement des requêtes à une extension, il fournit alors un appel d'extension demandé et les valeurs de paramètres associées. L'application relaie cette requête au service d'extension, qui exécute ensuite l'extension. Enfin, le service d'extension envoie le résultat de cette opération à l'application, qui le renvoie ensuite au modèle.
Ce document présente les principales fonctionnalités du service d'extension Vertex AI :
- Découvrez comment créer et importer des extensions.
- Comment gérer les extensions.
- Comment exécuter des extensions.
Pour savoir comment importer et exécuter une extension fournie par Google, consultez les articles suivants :
- Utilisez l'extension de l'interpréteur de code pour générer et exécuter du code.
- Utilisez l'extension Vertex AI Search pour accéder à des corpus de sites Web et à des données non structurées, et y effectuer des recherches, afin de fournir des réponses pertinentes aux questions en langage naturel.
Créer et importer des extensions
Dans ce document, nous partons du principe que vous disposez déjà d'un service d'API en cours d'exécution pouvant sauvegarder une extension. Pour créer une extension, vous devez définir son interface avec une API externe dans un fichier de spécification d'API. Vous devez importer ce fichier de spécification dans un bucket Cloud Storage ou le convertir en chaîne. Vous devez ensuite définir un fichier manifeste d'extension, inclure le fichier de spécification et envoyer une requête d'enregistrement au service d'extension.
Créer un fichier de spécification d'API
Une extension peut être créée par n'importe quel utilisateur via des fichiers qui définissent et décrivent les points de terminaison de l'API des extensions. Les points de terminaison de l'API peuvent être publics ou privés, et hébergés sur n'importe quel cloud ou sur site.
Un fichier de spécification d'API décrit l'interface d'un service d'API. Vous devez fournir un fichier de spécification d'API au format YAML compatible avec OpenAPI 3.0. Ce fichier de spécification doit définir les éléments suivants :
Un objet serveur. Cet objet doit définir une URL de serveur d'API. Le service d'extension Vertex AI n'est pas compatible avec plusieurs serveurs.
servers: - url: API_SERVICE_URL
Un objet chemins. Cet objet doit décrire les différentes opérations fournies par le service d'API et les paramètres d'entrée correspondant à chaque opération. Chaque opération doit avoir un identifiant unique et une réponse.
paths: ... get: operationId: API_SERVICE_OPERATION_ID ... parameters: - name: API_SERVICE_INPUT_VAR ... responses: ...
Un objet de composants. Cet objet est facultatif. Vous pouvez utiliser l'objet components pour définir des objets réutilisables. Par exemple, vous pouvez utiliser l'objet composants pour fournir une définition des schémas d'objet définis dans l'objet de chemins. Vous pouvez également utiliser l'objet composants pour décrire les paramètres de sortie du service d'API.
components: schemas: Result: ... properties: API_SERVICE_OUTPUT_VAR: ...
Pour en savoir plus sur OpenAPI, consultez la page Spécification OpenAPI.
L'exemple suivant est un fichier de spécification d'API pour un service d'API qui dit "hello" dans le langage demandé :
openapi: "3.0.0"
info:
version: 1.0.0
title: Hello Extension
description: Learn to build Vertex AI extensions
servers:
- url: [API_SERVICE_URL]
paths:
/hello:
get:
operationId: "say_hello"
description: "Say hello in prompted language."
parameters:
- name: "apiServicePrompt"
in: query
description: "Language"
required: true
schema:
type: string
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
$ref: "#/components/schemas/Result"
components:
schemas:
Result:
description: "Hello in the requested language."
properties:
apiServiceOutput:
type: string
Importer le fichier de spécification
Vous pouvez importer le fichier de spécification dans un bucket Cloud Storage ou le convertir en chaîne.
Si vous importez le fichier de spécification dans un bucket Cloud Storage, accordez au compte de service Vertex AI Extension Service Agent
(service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com
) le rôle Lecteur des objets de l'espace de stockage. Pour savoir comment répertorier les buckets de votre projet, consultez la page Répertorier les buckets.
Pour savoir comment copier un objet dans un bucket Cloud Storage, consultez la page Copier, renommer et déplacer des objets.
Définir une requête d'importation d'extension
Une fois que vous avez créé un fichier de spécification d'API, vous pouvez définir une requête d'importation d'extensions dans un fichier JSON. Une requête d'importation d'extensions doit contenir une référence à votre fichier de spécification d'API (apiSpec
) et à la configuration d'authentification (authConfig
). Pour connecter l'extension à un grand modèle de langage (LLM) afin de voir comment l'extension fonctionne, incluez le paramètre toolUseExamples
facultatif. Si vous souhaitez n'exécuter que l'extension, n'incluez pas le paramètre toolUseExamples
.
Une requête d'importation d'extension a le format suivant :
{
"displayName": "DISPLAY_NAME_HUMAN",
"description": "DESCRIPTION_HUMAN",
"manifest": {
"name": "EXTENSION_NAME_LLM",
"description": "DESCRIPTION_LLM",
"apiSpec": { ... },
"authConfig": { ... },
}
"toolUseExamples": [ ... ],
}
- DISPLAY_NAME_HUMAN : nom de l'extension affichée aux utilisateurs.
- DESCRIPTION_HUMAN : description de l'extension affichée auprès des utilisateurs.
- EXTENSION_NAME_LLM : nom de l'extension utilisée par le LLM pour le raisonnement.
- DESCRIPTION_LLM : description de l'extension utilisée par le LLM pour le raisonnement. Vous devez fournir une description pertinente et informative.
Référence à votre fichier de spécification d'API
Votre requête d'importation d'extensions doit contenir une référence à votre fichier de spécification d'API. Vous pouvez fournir le fichier de spécification de deux manières :
Utilisez
openApiGcsUri
pour transmettre l'URI Cloud Storage du fichier YAML."apiSpec": { "openApiGcsUri": "gs://BUCKET_NAME/SPECIFICATION_FILE_NAME.yaml" },
- BUCKET_NAME : nom du bucket Cloud Storage qui stocke le fichier de spécification.
- SPECIFICATION_FILE_NAME : nom du fichier de spécification de l'API.
Utilisez
openApiYaml
pour transmettre le fichier YAML en tant que chaîne.
Configuration de l'authentification
Les extensions peuvent être publiques, accessibles à tous les utilisateurs, ou privées, uniquement accessibles aux utilisateurs autorisés dans une ou plusieurs organisations.
Une requête d'importation d'extension doit contenir une configuration d'authentification. Vous avez le choix entre les méthodes d'authentification suivantes :
NO_AUTH
: pas d'authentificationAPI_KEY_AUTH
: authentification par clé APIHTTP_BASIC_AUTH
: authentification HTTP de baseOAUTH
: authentification OAuthOIDC_AUTH
: authentification OIDC
Pour en savoir plus sur les configurations d'authentification, consultez la page Spécifier une configuration d'authentification.
Exemples illustrant le fonctionnement de l'extension
Pour de meilleurs résultats, une requête d'importation d'extensions doit contenir des exemples illustrant le fonctionnement de l'extension. Utilisez le paramètre toolUseExamples
pour fournir ces exemples.
Le code suivant présente le format de toolUseExamples
pour un seul exemple, avec un seul paramètre d'entrée et un seul paramètre de sortie. Dans cet exemple, les paramètres de requête et de réponse sont tous deux de type string
.
"toolUseExamples": [
{
"extensionOperation": {
"operationId": "API_SERVICE_OPERATION_ID",
},
"displayName": "EXAMPLE_DISPLAY_NAME",
"query": "EXAMPLE_QUERY",
"requestParams": {
"fields": [
{
"key": "API_SERVICE_INPUT_VAR",
"value": {
"string_value": "EXAMPLE_INPUT",
}
}
]
},
"responseParams": {
"fields": [
{
"key": "API_SERVICE_OUTPUT_VAR",
"value": {
"string_value": "EXAMPLE_OUTPUT",
},
}
],
},
"responseSummary": "EXAMPLE_SUMMARY"
}
],
query
: exemple de requête pouvant tirer parti de cette extension. Utilisez EXAMPLE_QUERY pour fournir le texte de la requête.extensionOperation
: opération d'extension adaptée pour répondre àquery
. Utilisez API_SERVICE_OPERATION_ID pour fournir l'ID d'une opération d'extension définie dans le fichier de spécifications de l'API.displayName
: nom à afficher pour l'exemple. Utilisez EXAMPLE_DISPLAY_NAME pour fournir une brève description.requestParams
: paramètres de requête nécessaires pourextensionOperation
et les exemples de valeurs, au format clé-valeur. Utilisez API_SERVICE_INPUT_VAR pour fournir un paramètre d'entrée défini dans le fichier de spécification de l'API et correspondant à API_SERVICE_OPERATION_ID. Utilisez EXAMPLE_INPUT pour fournir un exemple de valeur d'entrée correspondant à EXAMPLE_QUERY.responseParams
: paramètres de réponse deextensionOperation
et exemples de valeurs au format clé-valeur. Utilisez API_SERVICE_OUTPUT_VAR pour fournir un paramètre de sortie défini dans le fichier de spécification de l'API et correspondant au service d'API. Utilisez EXAMPLE_OUTPUT pour fournir un exemple de valeur de sortie correspondant à EXAMPLE_INPUT.responseSummary
: exemple de résumé que l'application peut fournir en réponse àquery
. Utilisez EXAMPLE_SUMMARY pour fournir le texte récapitulatif.
Voici un exemple de toolUseExamples
pour un service d'API qui dit "hello" dans le langage demandé :
"toolUseExamples": [
{
"extensionOperation": {
"operationId": "say_hello",
},
"displayName": "Say hello in the requested language",
"query": "Say hello in French",
"requestParams": {
"fields": [
{
"key": "apiServicePrompt",
"value": {
"string_value": "French",
}
}
]
},
"responseParams": {
"fields": [
{
"key": "apiServiceOutput",
"value": {
"string_value": "bonjour",
},
}
],
},
"responseSummary": "Bonjour"
}
],
Spécifier une configuration d'authentification
Vous devez spécifier une configuration d'authentification lorsque vous définissez une requête d'importation d'extension.
Si votre extension ne nécessite pas d'authentification, définissez la variable authType
sur NO_AUTH
:
"authConfig": {
"authType": "NO_AUTH"
}
Si votre extension nécessite une authentification, vous devez définir le type d'authentification dans la variable authType
et fournir une configuration d'authentification. Vous avez le choix entre les méthodes d'authentification suivantes :
- Authentification HTTP par clé API
- Authentification HTTP de base
- Authentification OAuth
- Authentification OIDC
Authentification par clé API
Pour permettre l'authentification par clé API, Vertex AI s'intègre à SecretManager pour le stockage et l'accès aux secrets. La plate-forme Vertex AI ne stocke pas directement les données des secrets.
Vous êtes responsable de la gestion du cycle de vie de votre ressource SecretManager
.
Spécifiez authConfig
comme suit :
"authConfig": {
"authType": "API_KEY_AUTH",
"apiKeyConfig": {
"name": "API_KEY_CONFIG_NAME",
"apiKeySecret": "API_KEY_SECRET",
"httpElementLocation": "HTTP_ELEMENT_LOCATION",
},
}
- API_KEY_CONFIG_NAME : nom de la clé API. Par exemple, dans la requête API
https://example.com/act?api_key=<API KEY>
, API_KEY_CONFIG_NAME correspond àapi_key
. - API_KEY_SECRET : ressource de version de secret
SecretManager
qui stocke la clé. Ce paramètre a le format suivant :projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION
. HTTP_ELEMENT_LOCATION : emplacement de la clé API dans la requête HTTP. Les valeurs possibles sont les suivantes :
HTTP_IN_QUERY
HTTP_IN_HEADER
HTTP_IN_PATH
HTTP_IN_BODY
HTTP_IN_COOKIE
Pour en savoir plus, consultez la section Décrire des paramètres.
Authentification HTTP de base
Pour permettre l'authentification HTTP de base, Vertex AI s'intègre à SecretManager pour le stockage et l'accès aux secrets. La plate-forme Vertex AI ne stocke pas directement les données des secrets.
Vous devez gérer vous-même le cycle de vie de votre ressource SecretManager
.
Spécifiez authConfig
comme suit :
"authConfig": {
"authType": "HTTP_BASIC_AUTH",
"httpBasicAuthConfig": {
"credentialSecret": "CREDENTIAL_SECRET"
},
}
- CREDENTIAL_SECRET : ressource de version de secret
SecretManager
qui stocke les identifiants encodés en base64. Ce paramètre a le format suivant :projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION
.
Authentification OAuth
Vertex AI accepte deux méthodes d'authentification OAuth : le jeton d'accès et le compte de service.
Jeton d'accès
Spécifiez authConfig
comme suit :
"authConfig": {
"authType": "OAUTH",
"oauthConfig": {}
}
Laissez le champ oauthConfig
vide lorsque vous importez l'extension. Si vous choisissez d'exécuter une extension enregistrée, vous devez fournir un jeton d'accès dans le champ oauthConfig
de la requête de vérification. Pour en savoir plus, consultez la section Exécuter l'extension.
Compte de service
Spécifiez authConfig
comme suit :
"authConfig": {
"authType": "OAUTH",
"oauthConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
- SERVICE_ACCOUNT_NAME : Vertex AI utilise ce compte de service pour générer des jetons d'accès.
Procédez comme suit pour autoriser Vertex AI Extension Service Agent
à obtenir des jetons d'accès de SERVICE_ACCOUNT_NAME.
Accédez à la page IAM.
Sélectionnez l'onglet Comptes de service.
Cliquez sur votre compte de service. La valeur de
SERVICE_ACCOUNT_NAME
dansauthConfig
doit correspondre au nom de votre compte de service.Cliquez sur l'onglet Autorisations.
Cliquez sur Accorder l'accès.
Dans la section Ajouter des comptes principaux, saisissez
service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com
dans le champ Nouveaux comptes principaux. Ce compte principal correspond au compte de serviceVertex AI Extension Service Agent
.Dans la section Attribuer des rôles, recherchez et sélectionnez le rôle
Service Account Token Creator
. Ce rôle inclut l'autorisationiam.serviceAccounts.getAccessToken
.Cliquez sur le bouton Save (Enregistrer).
Authentification OIDC
Vertex AI accepte deux méthodes d'authentification OIDC : le jeton d'ID et le compte de service.
Jeton d'ID
Spécifiez authConfig
comme suit :
"authConfig": {
"authType": "OIDC_AUTH",
"oidcConfig": {}
}
Laissez le champ oidcConfig
vide lorsque vous importez l'extension. Si vous choisissez d'exécuter une extension enregistrée, vous devez fournir un jeton d'ID dans le champ oidcConfig
de la requête d'exécution. Pour en savoir plus, consultez la section Exécuter l'extension.
Compte de service
Spécifiez authConfig
comme suit :
"authConfig": {
"authType": "OIDC_AUTH",
"oidcConfig": {"service_account": "SERVICE_ACCOUNT_NAME"}
}
- SERVICE_ACCOUNT_NAME : Vertex AI utilise ce compte de service pour générer des jetons OpenID Connect (OIDC). Vertex AI définit l'audience du jeton sur API_SERVICE_URL, comme défini dans le fichier de spécifications de l'API.
Procédez comme suit pour autoriser Vertex AI Extension Service Agent
à obtenir des jetons d'accès de SERVICE_ACCOUNT_NAME.
Accédez à la page IAM.
Sélectionnez l'onglet Comptes de service.
Cliquez sur votre compte de service. La valeur de
SERVICE_ACCOUNT_NAME
dansauthConfig
doit correspondre au nom de votre compte de service.Cliquez sur l'onglet Autorisations.
Cliquez sur Accorder l'accès.
Dans la section Ajouter des comptes principaux, saisissez
service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com
dans le champ Nouveaux comptes principaux. Ce compte principal correspond au compte de serviceVertex AI Extension Service Agent
.Dans la section Attribuer des rôles, recherchez et sélectionnez le rôle
Service Account Token Creator
. Ce rôle inclut l'autorisationiam.serviceAccounts.getOpenIdToken
.Cliquez sur le bouton Save (Enregistrer).
Importer l'extension avec Vertex AI
Après avoir défini une requête d'importation d'extension, vous pouvez importer l'extension avec Vertex AI.
Définissez les variables d'interface système suivantes :
ENDPOINT="LOCATION-aiplatform.googleapis.com" URL="https://${ENDPOINT}/v1beta1/projects/PROJECT_ID/locations/LOCATION"
- PROJECT_ID : votre projet.
- LOCATION : région de votre choix. En cas de doute, choisissez
us-central1
.
Exécutez la commande
curl
suivante pour envoyer la requête d'importation :curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d @IMPORT_REQUEST.json "${URL}/extensions:import"
- IMPORT_REQUEST : nom du fichier JSON contenant la requête d'importation d'extension.
La réponse a le format suivant :
{ "name": "projects/[PROJECT_NUMBER]/locations/[LOCATION]/extensions/[EXTENSION_ID]/operations/[IMPORT_OPERATION_ID]", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.ImportExtensionOperationMetadata", "genericMetadata": { "createTime": "[CREATE_TIME]", "updateTime": "[UPDATE_TIME]" } } }
Définissez les variables d'interface système en fonction du résultat de la requête d'importation :
EXTENSION_ID=EXTENSION_ID IMPORT_OPERATION_ID=IMPORT_OPERATION_ID
Pour vérifier l'état de l'importation, exécutez la commande
curl
suivante :curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ "${URL}/operations/${IMPORT_OPERATION_ID}"
Gérer les extensions
Pour répertorier toutes les extensions enregistrées, exécutez la commande curl
suivante :
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions"
Pour obtenir une extension, exécutez la commande curl
suivante :
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"${URL}/extensions/${EXTENSION_ID}"
Vous pouvez mettre à jour les paramètres displayName
, description
ou toolUseExamples
de l'extension. Si vous spécifiez toolUseExamples
lorsque vous mettez à jour une extension, la mise à jour remplace les exemples. Par exemple, si vous avez les exemples a
et b
, mettez à jour l'extension avec l'exemple c
, l'extension mise à jour ne contient que l'exemple c
. Pour mettre à jour une extension description, exécutez la commande curl
suivante :
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}?update_mask="description" \
-d '{
"description": "A nice tool.",
}'
Pour supprimer une extension, exécutez la commande curl
suivante :
curl \
-X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
${URL}/extensions/${EXTENSION_ID}
Exécuter une extension
Si votre extension utilise l'authentification OAuth et un jeton d'accès, consultez la section Exécuter une extension avec l'authentification OAuth et un jeton d'accès.
Si votre extension utilise l'authentification OIDC et un jeton d'ID, consultez la section Exécuter une extension avec l'authentification OIDC et un jeton d'ID.
Sinon, vous pouvez l'exécuter en procédant comme suit :
Créez un fichier nommé
execute-extension.json
avec le contenu suivant :{ "operation_id": "API_SERVICE_OPERATION_ID", "operation_params": { "API_SERVICE_INPUT_VAR": "API_SERVICE_INPUT_VALUE" } }
- API_SERVICE_OPERATION_ID : ID de l'opération de service d'API que vous souhaitez exécuter. Les opérations de service d'API sont définies dans le fichier de spécifications de l'API.
- API_SERVICE_INPUT_VAR : variable d'entrée correspondant à API_SERVICE_OPERATION_ID et définie dans le fichier de spécification de l'API.
- API_SERVICE_INPUT_VALUE : valeur d'entrée pour l'extension.
Exécutez la commande
curl
suivante :curl \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \ "${URL}/extensions/${EXTENSION_ID}:execute"
La réponse a le format suivant :
{ "output": { "content": "{\"API_SERVICE_OUTPUT_VAR\": \"API_SERVICE_OUTPUT_VALUE\"}" } }
- API_SERVICE_OUTPUT_VAR : paramètre de sortie défini dans le fichier de spécification de l'API et correspondant au service d'API.
- API_SERVICE_OUTPUT_VALUE : valeur de chaîne qui est une sérialisation de l'objet de réponse. Si votre fichier de spécification d'API définit un schéma de réponse JSON, vous devez analyser cette chaîne de sortie au format JSON vous-même.
Exécuter une extension avec l'authentification OAuth et un jeton d'accès
Si votre extension utilise l'authentification OAuth et un jeton d'accès, vous pouvez l'exécuter en procédant comme suit :
Créez un fichier nommé
execute-extension.json
avec le contenu suivant :{ "operation_id": "API_SERVICE_OPERATION_ID", "operation_params": {...}, "runtime_auth_config": { "authType": "OAUTH", "oauth_config": {"access_token": "'$(gcloud auth print-access-token)'"} } }
- API_SERVICE_OPERATION_ID : ID de l'opération de service d'API que vous souhaitez exécuter. Les opérations de service d'API sont définies dans le fichier de spécifications de l'API.
Exécutez la commande
curl
suivante :curl \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \ "${URL}/extensions/${EXTENSION_ID}:execute"
Exécuter une extension avec l'authentification OIDC et un jeton d'ID
Si votre extension utilise l'authentification OIDC et un jeton d'ID, vous pouvez l'exécuter en procédant comme suit :
Créez un fichier nommé
execute-extension.json
avec le contenu suivant :{ "operation_id": "API_SERVICE_OPERATION_ID", "operation_params": {...}, "runtime_auth_config": { "authType": "OIDC_AUTH", "oidc_config": {"id_token": "$(gcloud auth print-identity-token)"} } }
- API_SERVICE_OPERATION_ID : ID de l'opération de service d'API que vous souhaitez exécuter. Les opérations de service d'API sont définies dans le fichier de spécifications de l'API.
Exécutez la commande
curl
suivante :curl \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" -d @execute-extension.json \ "${URL}/extensions/${EXTENSION_ID}:execute"