Créer et exécuter des extensions

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 :

Pour savoir comment importer et exécuter une extension fournie par Google, consultez les articles suivants :

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'authentification
  • API_KEY_AUTH : authentification par clé API
  • HTTP_BASIC_AUTH : authentification HTTP de base
  • OAUTH : authentification OAuth
  • OIDC_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 pour extensionOperation 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 de extensionOperation 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 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.

  1. Accédez à la page IAM.

    Accéder à IAM

  2. Sélectionnez l'onglet Comptes de service.

  3. Cliquez sur votre compte de service. La valeur de SERVICE_ACCOUNT_NAME dans authConfig doit correspondre au nom de votre compte de service.

  4. Cliquez sur l'onglet Autorisations.

  5. Cliquez sur Accorder l'accès.

  6. 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 service Vertex AI Extension Service Agent.

  7. Dans la section Attribuer des rôles, recherchez et sélectionnez le rôle Service Account Token Creator. Ce rôle inclut l'autorisation iam.serviceAccounts.getAccessToken.

  8. 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.

  1. Accédez à la page IAM.

    Accéder à IAM

  2. Sélectionnez l'onglet Comptes de service.

  3. Cliquez sur votre compte de service. La valeur de SERVICE_ACCOUNT_NAME dans authConfig doit correspondre au nom de votre compte de service.

  4. Cliquez sur l'onglet Autorisations.

  5. Cliquez sur Accorder l'accès.

  6. 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 service Vertex AI Extension Service Agent.

  7. Dans la section Attribuer des rôles, recherchez et sélectionnez le rôle Service Account Token Creator. Ce rôle inclut l'autorisation iam.serviceAccounts.getOpenIdToken.

  8. 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.

  1. 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.

  2. 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"

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

  3. 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

  4. 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 :

  1. 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.

  2. 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 :

  1. 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.

  2. 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 :

  1. 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.

  2. 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"

Étapes suivantes