Création et gestion de modèles personnalisés

La première étape pour utiliser un modèle personnalisé consiste à en créer un. Une fois le modèle créé, vous pouvez le gérer en interrogeant ou en mettant à jour ses métadonnées et ses entrées, et en le supprimant lorsqu'il devient inutile. Avant de commencer, consultez les informations d'utilisation générale suivantes sur les modèles personnalisés.

Utilisation de remarques pour la personnalisation

Prenez en compte les instructions suivantes lorsque vous utilisez l'interface de personnalisation.

Propriété des modèles personnalisés

Un modèle personnalisé appartient à l'instance du service Text to Speech dont les données d'identification sont utilisées pour le créer. Vous devez utiliser les données d'identification créées pour cette instance de service avec les méthodes de l'interface de personnalisation afin de pouvoir utiliser le modèle personnalisé de quelque manière que ce soit.

Toutes les données d'identification obtenues pour la même instance du service Text to Speech partagent l'accès à tous les modèles personnalisés créés pour cette instance de service. Pour limiter l'accès à un modèle personnalisé, créez une instance distincte du service et utilisez uniquement les données d'identification de cette instance de service pour créer et utiliser le modèle. Les données d'identification pour d'autres instances de service ne peuvent pas affecter le modèle personnalisé.

L'un des avantages de partager la propriété entre les données d'identification est que vous pouvez annuler un ensemble de données d'identification, par exemple, si elles sont compromises. Vous pouvez ensuite créer de nouvelles données d'identification pour la même instance de service tout en conservant la propriété et l'accès aux modèles personnalisés créés avec les données d'identification d'origine.

Sécurité des informations

Le service vous permet d'associer un ID client aux données ajoutées ou mises à jour pour les modèles personnalisés. Vous pouvez associer un ID client à des mots personnalisés en transmettant l'en-tête X-Watson-Metadata avec les méthodes suivantes. Si nécessaire, vous pouvez ensuite supprimer les données associées à l'ID client à l'aide de la méthode DELETE /v1/user_data.

  • POST /v1/customizations/{customization_id}
  • POST /v1/customizations/{customization_id}/words
  • PUT /v1/customizations/{customization_id}/words/{word}

De plus, si vous supprimez une instance du service Text to Speech à partir de la console IBM Cloud, toutes les données associées à cette instance de service sont automatiquement supprimées. Cela inclut tous les modèles personnalisés et les paires mot/traduction. Ces données sont purgées automatiquement, qu'un ID client soit associé ou non aux données.

Pour plus d'informations, voir Sécurité des informations.

Journalisation des demandes et confidentialité des données

IBM Cloud

La façon dont le service gère la journalisation des demandes pour les appels de l'interface de personnalisation dépend de la demande :

  • Le service n'enregistre pas les données (mots et traductions) qui sont utilisées pour construire des modèles personnalisés. Vous n'avez pas besoin de définir l'en-tête de demande X-Watson-Learning-Opt-Out lorsque vous utilisez l'interface de personnalisation pour gérer les mots et les traductions dans un modèle personnalisé. Vos données de formation ne sont jamais utilisées pour améliorer les modèles de base du service.
  • Le service enregistre les données lorsqu'un modèle personnalisé est utilisé avec une demande de synthèse. Vous pouvez désactiver l'enregistrement des demandes au niveau du compte ou en définissant l'en-tête de demande X-Watson-Learning-Opt-Out sur true.

Pour plus d'informations, voir Journalisation des demandes.

Création d'un modèle personnalisé

Pour créer un nouveau modèle personnalisé, utilisez la méthode POST /v1/customizations. Un nouveau modèle est toujours vide lors de sa création. Vous devez utiliser d'autres méthodes pour le remplir avec des paires mot/traduction. Le nouveau modèle personnalisé appartient à l'instance de service dont les données d'identification sont utilisées pour créer le service. Pour plus d'informations, voir Propriété des modèles personnalisés.

Vous transmettez les attributs suivants en tant qu’objet JSON avec le corps d'une demande POST /v1/customizations :

name (chaîneobligatoire)
Nom défini par l'utilisateur pour désigner le nouveau modèle personnalisé. Utilisez un nom localisé qui correspond à la langue du modèle personnalisé et qui décrit le domaine du modèle, tel que Medical custom model ou Legal custom model.
  • Le nom ne doit pas comporter plus de 256 caractères.
  • N'utilisez pas de barres obliques inversées, de barres obliques, de deux-points, de signes égal, de signes « et » ou de points d'interrogation dans le nom.
  • Utilisez un nom unique parmi tous les modèles personnalisés que vous possédez.
language (chaînefacultative )
Identificateur de la langue du modèle personnalisé. La valeur par défaut est en-US pour l'anglais américain. Le modèle personnalisé peut être utilisé avec n'importe quelle voix disponible dans la langue spécifiée. Par exemple, un modèle personnalisé qui est créé pour la langue en-US peut être utilisé avec n'importe quelle voix en anglais américain. En revanche, il ne peut pas être utilisé avec une voix en-GB.
description (chaînefacultative )
Description recommandée du nouveau modèle personnalisé.
  • Utilisez une description localisée correspondant à la langue du modèle personnalisé.
  • La description ne doit pas dépasser 128 caractères.

L'exemple suivant crée un nouveau modèle personnalisé en anglais américain nommé Test. L'en-tête Content-Type identifie le type d'entrée comme étant application/json.

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"name\":\"Test\", \"language\":\"en-US\", \"description\":\"Customization test\"}" \
"{url}/v1/customizations"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"name\":\"Test\", \"language\":\"en-US\", \"description\":\"Customization test\"}" \
"{url}/v1/customizations"

La méthode renvoie un objet JSON contenant un identificateur global unique (GUID) pour le nouveau modèle. L'identificateur global unique (GUID) est utilisé comme paramètre customization_id dans les appels d'accès au modèle, tels que ceux permettant d'interroger, de modifier et d'utiliser le modèle et ses mots.

{
  "customization_id": "64f4807f-a5f1-5867-924f-7bba1a84fe97"
}

Demande d'un modèle personnalisé

Pour demander des informations sur un modèle personnalisé existant, utilisez la méthode GET /v1/customizations/{customization_id}. Il s'agit du moyen le plus direct de voir toutes les informations relatives à un modèle, y compris ses métadonnées et les paires de mots/de traduction et les invites personnalisées qu'il contient.

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}"

La méthode renvoie ses résultats sous forme d'objet JSON sous la forme suivante :

{
  "customization_id": "64f4807f-a5f1-5867-924f-7bba1a84fe97",
  "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
  "created": "2016-07-15T18:12:31.743Z",
  "name": "Test",
  "language": "en-US",
  "description": "Customization test",
  "last_modified": "2016-07-15T18:12:31.743Z",
  "words": [],
  "prompts": []
}

Outre les informations saisies lors de la création du modèle, la sortie inclut les données d'identification du propriétaire du modèle, la langue du modèle, l'heure de création du modèle et l'heure de dernière modification. Dans la mesure où le modèle n'a pas été modifié depuis sa création, les deux horodatages de l'exemple sont identiques.

La sortie inclut également un tableau words qui répertorie les mots personnalisés du modèle et un tableau prompts qui répertorie les invites personnalisées du modèle. Comme le modèle n'a pas encore été mis à jour, les tableaux de l'exemple sont vides.

Demande de tous les modèles personnalisés

Pour afficher des informations sur tous les modèles personnalisés que vous possédez, utilisez la méthode GET /v1/customizations :

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations"

La méthode renvoie un tableau JSON qui inclut un objet pour chaque modèle personnalisé appartenant au demandeur. Les données d'identification du propriétaire sont affichées dans la zone owner.

{
  "customizations": [
    {
      "customization_id": "64f4807f-a5f1-5867-924f-7bba1a84fe97",
      "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
      "created": "2016-07-15T19:15:17.926Z",
      "name": "Test",
      "language": "en-US",
      "description": "Customization test",
      "last_modified": "2016-07-15T19:15:17.926Z"
    },
    {
      "customization_id": "63f5807f-a4f2-5766-914e-7abb1a84fe97",
      "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
      "created": "2016-07-15T18:12:31.743Z",
      "name": "Test Two",
      "language": "en-US",
      "description": "Second customization test",
      "last_modified": "2016-07-15T18:23:50.912Z"
    }
  ]
}

Les horodatages created et last_modified pour le premier modèle sont identiques car le modèle n'a pas encore été mis à jour. Les horodatages du deuxième modèle sont différents, ce qui indique qu’il a été modifié depuis sa création. Les informations n'incluent pas les entrées personnalisées définies pour les modèles.

Mise à jour d'un modèle personnalisé

Pour mettre à jour des informations sur un modèle personnalisé, utilisez la méthode POST /v1/customizations/{customization_id}. Vous spécifiez les mises à jour en tant qu'objet JSON. En plus de modifier son nom et sa description, vous pouvez également utiliser cette méthode pour ajouter ou mettre à jour des paires de mots/traduction dans le modèle. Vous ne pouvez pas changer la langue d'un modèle une fois qu'il est créé.

L'exemple suivant met à jour le nom et la description d'un modèle personnalisé. Un tableau JSON vide est envoyé avec le paramètre words pour indiquer que les entrées du modèle doivent rester inchangées.

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"name\":\"Test Update\", \"description\":\"Customization test update\", \"words\":[]}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"name\":\"Test Update\", \"description\":\"Customization test update\", \"words\":[]}" \
"{url}/v1/customizations/{customization_id}"

Pour plus d'informations sur la mise à jour des mots dans un modèle, voir Ajout de plusieurs mots à un modèle personnalisé.

Suppression d'un modèle personnalisé

Pour supprimer un modèle personnalisé dont vous n'avez plus besoin, utilisez la méthode DELETE /v1/customizations/{customization_id}. Utilisez cette méthode uniquement si vous êtes certain de ne plus avoir besoin du modèle, car la suppression est irréversible.

IBM Cloud

curl -X DELETE -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X DELETE \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}"