Créer des entités

Voici comment créer une entité.

Pour créer une entité :

Cliquez sur Entities (Entités) () dans la barre de navigation latérale.
Cliquez sur Add Entity (Ajouter une entité), puis entrez son nom et sélectionnez son type. Les champs de la boîte de dialogue reflètent le type d'entité. Par exemple, pour les entités d'expressions rationnelles, vous pouvez ajouter l'expression. Pour les entités de liste de valeurs, ajoutez les valeurs et les synonymes.
Si votre compétence prend en charge plusieurs langues grâce à la prise en charge linguistique native de Digital Assistant, vous devez ajouter les équivalents en langue étrangère pour les valeurs et synonymes de l'entité de liste de valeurs.

Description de l'illustration multilingual-entity-values.png

Étant donné que ces valeurs doivent être mappées à la valeur correspondante de la langue principale (la valeur de la langue principale), vous devez sélectionner la valeur principale avant d'ajouter son équivalent dans la langue secondaire. Par exemple, si vous avez ajouté le français comme langue secondaire à une compétence dont la langue principale est l'anglais, vous devez d'abord sélectionner small comme valeur de la langue principale, puis ajouter petite.

Description de l'illustration add-ml-entity-value.png
Facultativement, entrez une description. Vous pouvez utiliser la description pour préciser l'entité, par exemple garnitures de pizza pour une entité PizzaTopping. Cette description n'est pas conservée lorsque vous ajoutez l'entité à une entité composite.
Vous pouvez ajouter les fonctions suivantes, qui sont facultatives. Elles peuvent être remplacées si vous ajoutez l'entité à une entité composite.
- Si une entité de type liste de valeurs contient une longue liste de valeurs, mais que vous voulez limiter l'affichage à quelques options à la fois, vous pouvez définir la pagination pour ces valeurs en entrant un nombre dans le champ Enumeration Range Size (Taille de l'intervalle d'énumération) ou en définissant une expression Apache FreeMarker qui donne ce nombre. Par exemple, vous pouvez définir une expression qui retourne des valeurs enum en fonction du canal.
  Lorsque vous réglez cette propriété à 0, la compétence n'affiche aucune liste, mais elle compare l'entrée de l'utilisateur à une valeur d'entité.
  
  Si vous indiquez un nombre inférieur au nombre total de valeurs définies pour l'entité, le groupe de pages Résoudre entités affichera un bouton d'affichage des données supplémentaires. Si vous utilisez un groupe de pages Réponse commune pour résoudre l'entité, vous pouvez configurer ce bouton vous-même.
  
  Vous pouvez modifier le texte du bouton Afficher plus à l'aide de la propriété showMoreLabel qui appartient aux composants Résoudre les entités et Réponse commune.
- Ajoutez un message d'erreur pour une entrée utilisateur non valide. Utilisez une expression Apache FreeMarker qui inclut la propriété system.entityToResolve.value.userInput. Par exemple, ${system.entityToResolve.value.userInput!'This'}' is not a valid pizza type.
- Pour permettre aux utilisateurs de sélectionner plusieurs valeurs dans une entité de type liste de valeurs, activez Multiple Values (Valeurs multiples). Lorsque vous activez cette option, les valeurs s'affichent sous forme de liste numérotée.
  
  Si vous la désactivez, les valeurs sont affichées dans une liste d'options qui n'autorise qu'un seul choix.
- L'activation de l'option Fuzzy Match (Correspondance floue) augmente les chances d'appariement de l'entrée utilisateur à une valeur, particulièrement si vos valeurs n'ont pas de nombreux synonymes. La mise en correspondance floue utilise l'ajustement de mot pour identifier les correspondances à partir de l'entrée utilisateur. La désactivation de la correspondance floue impose une correspondance stricte, ce qui signifie que l'entrée de l'utilisateur doit correspondre exactement aux valeurs et aux synonymes; "voitures" ne correspondra pas à une valeur appelée "voiture", ni "gestionnaire" à une valeur "gestionnaire de développement".
- Pour les compétences configurées avec un service de traduction, la mise en correspondance d'entité est basée sur la traduction de l'entrée. Si vous activez Match Original Value (Correspondance avec la valeur originale), l'entrée initiale est également prise en compte dans la mise en correspondance d'entité, ce qui pourrait être utile pour les valeurs correspondantes intraduisibles.
- Pour forcer un utilisateur à sélectionner une seule valeur, activez Prompt for Disambiguation (Invite pour désambiguïsation) et ajoutez une invite de désambiguïsation. Par défaut, ce message est Please select one value of <item name> (Sélectionnez une seule valeur de <nom d'élément>), mais vous pouvez le remplacer par un message comportant uniquement du texte (Vous ne pouvez commander qu'une pizza à la fois. Quelle pizza voulez-vous commander?) ou une combinaison de texte et d'expressions FreeMarker. Par exemple :
```
"I found multiple dates: <#list system.entityToResolve.value.disambiguationValues.Date as date>${date.date?number_to_date}<#sep> and </#list>. Which date should I use as expense date?"
```
- Définissez une règle de validation à l'aide d'une expression FreeMarker.
  Note
  
  Vous ne pouvez ajouter des invites, des invites de désambiguïsation et des règles de validation qu'aux entités intégrées appartenant à une entité composite.
Cliquez sur Create (Créer).
Étapes suivantes :
1. Ajoutez l'entité à une intention. La compétence est ainsi informée des valeurs qu'elle doit extraire de l'entrée utilisateur au cours du traitement du langage. Voir Ajouter des entités à des intentions.
2. Dans le flux de dialogue, déclarez une variable pour l'entité.
3. Accédez aux valeurs de variable au moyen d'expressions Apache FreeMarker. Voir Opérations de tableau FreeMarker intégrées.
4. Cliquez sur Validate (Valider) et consultez les messages de validation pour détecter les erreurs liées aux programmes de traitement d'événements d'entité (le cas échéant), les problèmes potentiels comme plusieurs valeurs dans une entité de liste de valeurs partageant le même synonyme, et pour obtenir des conseils sur l'application des meilleures pratiques, telles que l'ajout de plusieurs invites pour rendre la compétence plus engageante.

Entités de liste de valeurs pour plusieurs langues

Lorsque vous avez une compétence ciblée pour plusieurs langues qui utilise la prise en charge linguistique native de Digital Assistant, vous pouvez définir des valeurs pour chaque langue de la compétence. Pour chaque valeur d'entité dans la langue principale d'une compétence, vous devez désigner une valeur correspondante dans chaque langue supplémentaire.

Conseil :

Pour vous assurer que votre compétence retourne systématiquement les réponses dans la langue détectée, incluez toujours useFullEntityMatches: true dans les états Réponse commune, Résoudre les entités et Correspondance d'entité. Comme décrit dans Ajouter des langues prises en charge de manière native à une compétence, le réglage de cette propriété à true (valeur par défaut) retourne la valeur d'entité en tant qu'objet dont les propriétés différencient la langue principale de la langue détectée. Lorsqu'elles sont référencées dans des expressions Apache FreeMarker, ces propriétés garantissent que la langue appropriée s'affiche dans le texte et les étiquettes de message de la compétence.

Prise en charge de l'ajustement de mot dans une correspondance floue

À partir de la version 22.10, la mise en correspondance floue pour les entités de valeur de liste est basée sur la mise en séquence de mots, où une mise en correspondance de valeurs est basée sur la racine lexicale du mot. Dans les versions précédentes, la mise en correspondance floue était activée au moyen de la mise en correspondance partielle et de la correction automatique. Bien que cette approche était tolérante aux fautes de frappe dans l'entrée utilisateur, y compris les mots transposés, elle pourrait également entraîner des correspondances avec plus d'une valeur dans l'entité de liste de valeurs. Avec stemming, cette dispersion est éliminée : les correspondances sont basées sur l'ordre des mots de l'entrée utilisateur, donc soit une seule correspondance est faite, soit aucune du tout. Par exemple, "Lovers Veggie" n'entraînerait aucune correspondance, mais "Veggie Lover" correspondrait à la valeur Veggie Lovers d'une entité de type pizza. (Notez que "Lover" est décrété.) Les mots d'arrêt, tels que les articles et les prépositions, sont ignorés dans les valeurs extraites, tout comme les caractères spéciaux. Par exemple, "Veggie l'amant" et "Veggie///Lover" correspondraient à la valeur Veggie Lovers.

Créer des entités d'apprentissage automatique

Les entités ML sont une approche basée sur un modèle pour l'extraction d'entités. Comme les intentions, vous créez des entités ML à partir d'énoncés d'entraînement, probablement les mêmes énoncés d'entraînement que ceux que vous avez utilisés pour créer vos intentions. Toutefois, pour les entités ML, vous annotez les mots des énoncés d'entraînement qui correspondent à une entité.

Pour commencer, vous pouvez annoter vous-même certaines données d'entraînement, mais comme c'est le cas pour les intentions, vous pouvez développer un jeu d'entraînement plus varié (et donc robuste) par approvisionnement en clientèle. Comme indiqué dans les directives de formation, une détection robuste des entités nécessite entre 600 et 5000 occurrences de chaque entité ML dans l'ensemble de l'entraînement. De plus, si les données d'entraînement d'intention sont déjà étendues, vous pouvez vouloir les alimenter en foule plutôt que de les annoter vous-même. Dans les deux cas, vous devez analyser vos données d'entraînement pour savoir si les entités sont représentées de manière égale et si les valeurs des entités sont suffisamment variées. Une fois les annotations terminées, vous entraînez le modèle, puis vous le testez. Après avoir vérifié les entités détectées dans les exécutions de test, vous pouvez continuer à mettre à jour le corpus et réentraîner pour améliorer l'exactitude.

Pour créer une entité d'apprentissage automatique :

Cliquez sur + Add Entity (Ajouter une entité).
Remplissez la boîte de dialogue Create Entity (Créer une entité). Gardez à l'esprit que le nom et la description apparaissent dans les pages du contributeur pour les travaux d'annotation d'entité.
- Entrez un nom identifiant le contenu annoté. Un nom unique aide les contributeurs.
- Entrer une description. Bien qu'il s'agisse d'une propriété facultative, les contributeurs l'utilisent, avec la propriété Name, pour différencier les entités.
- Sélectionnez Entité ML dans la liste.
Activez Exclure les correspondances d'entités système lorsque les annotations d'entraînement contiennent des noms, des emplacements, des nombres ou d'autres contenus qui pourraient être en conflit avec les valeurs d'entités système. La définition de cette option empêche le modèle d'extraire les valeurs d'entité système qui se trouvent dans l'entrée résolue pour cette entité d'apprentissage automatique. Il applique une limite autour de cette entrée afin que le modèle ne la reconnaisse qu'en tant que valeur d'entité ML et ne l'analyse pas plus loin pour les valeurs d'entité système. Vous pouvez définir cette option pour les entités composites qui référencent des entités d'apprentissage automatique.
Cliquez sur Create (Créer).
Cliquez sur +Value Lister les entités pour associer cette entité à un maximum de cinq entités de liste de valeurs. Cette option est facultative, mais l'association d'une entité ML à une entité de liste de valeurs combine l'extraction contextuelle de l'entité ML et l'extraction indépendante du contexte de l'entité de liste de valeurs.
Cliquez sur l'onglet DataSet. Cette page répertorie tous les énoncés de chaque entité d'apprentissage automatique de votre compétence, qui incluent les énoncés que vous avez ajoutés vous-même pour amorcer l'entité, ceux soumis à partir de tâches d'approvisionnement participatif ou ceux qui ont été importés en tant qu'objets JSON. À partir de cette page, vous pouvez ajouter des énoncés manuellement ou en masse en chargeant un fichier JSON. Vous pouvez également gérer les énoncés de cette page en les modifiant (y compris en les annotant ou en les annotant de nouveau), ou en les supprimant, en les important et en les exportant.
- Ajoutez les énoncés manuellement :
  - Cliquez sur Add Utterance (Ajouter une expression). Après avoir ajouté l'énoncé, cliquez sur Modifier les annotations pour ouvrir la liste d'entités.
    Note
    
    Vous ne pouvez ajouter qu'un énoncé à la fois. Si vous voulez ajouter des énoncés en masse, vous pouvez les ajouter au moyen d'une tâche d'annotation d'entité ou vous pouvez charger un fichier JSON.
  - Mettez en surbrillance le texte pertinent pour l'entité ML, puis complétez l'étiquetage en sélectionnant l'entité ML dans la liste des entités. Vous pouvez supprimer une annotation en cliquant sur x dans l'étiquette.
- Ajoutez des énoncés à partir d'un fichier JSON. Ce fichier JSON contient une liste d'objets d'énoncé.
```
[
  {
    "Utterance": {
      "utterance": "I expensed $35.64 for group lunch at Joe's on 4/7/21",
      "languageTag": "en",
      "entities": [
        {
          "entityValue": "Joe's"   
          "entityName": "VendorName",
          "beginOffset": 37,
          "endOffset": 42
        }
      ]
    }
  },
  {
    "Utterance": {
      "utterance": "Give me my $30 for Coffee Klatch on 7/20",
      "languageTag": "en",
      "entities": [
        {
          "entityName": "VendorName",
          "beginOffset": 19,
          "endOffset": 32
        }
      ]
    }
  }
]
```
  Vous pouvez le charger en cliquant sur More (Plus) > Import (Importer) pour l'extraire de votre système local.
  L'objet entities décrit les entités ML qui ont été identifiées dans l'énoncé. Bien que l'exemple précédent illustre un seul objet entities pour chaque énoncé, un énoncé peut contenir plusieurs entités ML, ce qui signifie plusieurs objets entities :
```
[
  {
    "Utterance": {
      "utterance": "I want this and that",
      "languageTag": "en",
      "entities": [
        {
          "entityName": "ML_This",
          "beginOffset": 7,
          "endOffset": 11
        },
        {
          "entityName": "ML_That",
          "beginOffset": 16,
          "endOffset": 20
        }
      ]
    }
  },
  {
    "Utterance": {
      "utterance": "I want less of this and none of that",
      "languageTag": "en",
      "entities": [
        {
          "entityName": "ML_This",
          "beginOffset": 15,
          "endOffset": 19
        },
        {
          "entityName": "ML_That",
          "beginOffset": 32,
          "endOffset": 36
        }
      ]
    }
  }
]
```
  entityName identifie l'entité ML elle-même et entityValue identifie le texte étiqueté pour l'entité. entityValue est une clé facultative que vous pouvez utiliser pour valider le texte étiqueté par rapport aux modifications apportées à l'énoncé. L'étiquette elle-même est identifiée par les propriétés beginOffset et endOffset, qui représentent le décalage des caractères qui commencent et finissent l'étiquette. Ce décalage est déterminé par caractère, et non par mot, et est calculé à partir du premier caractère de l'énoncé (0-1).
  Note
  
  Vous ne pouvez pas créer les entités d'apprentissage automatique à partir de ce fichier JSON. Elles doivent exister avant le chargement du fichier.
  Si vous ne voulez pas déterminer les décalages, vous pouvez laisser l'objet entities non défini, puis appliquer les étiquettes après avoir chargé le fichier JSON.
```
[
  {
    "Utterance": {
      "utterance": "I expensed $35.64 for group lunch at Joe's on 4/7/21",
      "languageTag": "en",
      "entities": []
        
      
    }
  },
  {
    "Utterance": {
      "utterance": "Give me my $30 for Coffee Klatch on 7/20",
      "languageTag": "en",
      "entities": []
      
    }
  }
]
```
  Le système recherche les doublons pour éviter les entrées redondantes. Seules les modifications apportées à la définition entities dans le fichier JSON sont appliquées. Si un énoncé a été modifié dans le fichier JSON, il est considéré comme un nouvel énoncé.
- Modifier un énoncé annoté :
  - Cliquez sur Modifier pour supprimer l'annotation.
    Note
    
    Un énoncé modifié est considéré comme un nouvel énoncé (non annoncé).
  - Cliquez sur Modifier les annotations pour ouvrir la liste des entités.
  - Mettez le texte en surbrillance, puis sélectionnez une entité ML dans la liste des entités.
  - Si vous devez supprimer une annotation, cliquez sur x dans l'étiquette.
Lorsque vous avez terminé d'annoter les énoncés. Cliquez sur Entraîner pour mettre à jour le modèle d'entraînement Tm et le modèle Entité.
Testez la reconnaissance en entrant une expression de test dans le testeur d'énoncé, idéalement avec une valeur introuvable dans les données d'entraînement. Vérifiez les résultats pour savoir si le modèle a détecté la bonne entité ML et si le texte a été étiqueté correctement et complètement.
Associez l'entité ML à une intention.

Exclure les correspondances d'entités de système

L'activation de l'option Exclure les correspondances d'entités système empêche le modèle de remplacer les valeurs d'entités système précédemment extraites par des valeurs concurrentes trouvées dans les limites d'une entité d'apprentissage automatique. Avec cette option activée, "Créer une réunion le lundi pour discuter du produit livrable du mardi" sépare les valeurs d'entité DATE_TIME et ML en résolvant l'entité DATE_TIME applicable (lundi) et en ignorant "Mardi" dans le texte reconnu comme entité ML ("discuter du produit livrable du mardi").

Lorsque cette option est désactivée, la compétence résout plutôt deux valeurs d'entité DATE_TIME, lundi et mardi. Des valeurs clignotantes comme celles-ci diminuent l'expérience utilisateur en mettant à jour une valeur d'entité précédemment insérée avec une valeur involontaire ou en interjetant une invite de désambiguïsation qui interrompt le flux de la conversation.

Note

Vous pouvez définir l'option Exclure les correspondances d'entités système pour les entités composites qui référencent une entité d'apprentissage automatique.

Importer des entités de type liste de valeurs à partir d'un fichier CSV

Au lieu de créer vos entités une par une, vous pouvez définir des jeux complets par l'importation d'un fichier CSV contenant des définitions d'entité.

Ce fichier CSV contient des colonnes pour le nom de l'entité (entity), la valeur de l'entité (value) et tous les synonymes (synonyms). Vous pouvez créer ce fichier à partir de zéro, ou réutiliser ou adapter un fichier CSV créé à partir d'une exportation.

Qu'il s'agisse d'un nouveau fichier ou d'un fichier exporté, vous devez garder à l'esprit la version de la compétence vers laquelle vous effectuez l'importation en raison des modifications de format et de contenu pour la prise en charge linguistique native qui ont été introduites dans la version 20.12. Bien que vous puissiez importer un fichier CSV à partir d'une version antérieure dans une compétence 20.12 sans incident dans la plupart des cas, vous aurez peut-être à résoudre des problèmes de compatibilité. Mais avant cela, examinons le format d'un fichier pour une version antérieure à la version 20.12. Ce fichier est divisé en colonnes : entity, value et synonyms. Par exemple :

entity,value,synonyms
PizzaSize,Large,lrg:lrge:big
PizzaSize,Medium,med
PizzaSize,Small,little

Pour les compétences créées avec la version 20.12 ou mises à niveau vers cette version, des balises de langue sont ajoutées aux en-têtes de colonne value et synonyms des fichiers d'importation. Par exemple, si la langue native principale de la compétence est l'anglais (en), les colonnes value et synonyms deviennent en:value et en:synonyms:

entity,en:value,en:synonyms
PizzaSize,Large,lrg:lrge:big
PizzaSize,Medium,med
PizzaSize,Small,
PizzaSize,Extra Large,XL

Les fichiers CSV prenant en charge plusieurs langues natives nécessitent d'autres jeux de colonnes value et synonyms pour chaque langue secondaire. Si la langue secondaire d'une compétence qui utilise l'anglais comme langue native est le français (fr), le fichier CSV comporte les colonnes fr:value et fr:synonymes comme équivalents des colonnes en:

entity,en:value,en:synonyms,fr:value,fr:synonyms
PizzaSize,Large,lrg:lrge:big,grande,grde:g
PizzaSize,Medium,med,moyenne,moy
PizzaSize,Small,,petite,p
PizzaSize,Extra Large,XL,pizza extra large,

Notez les points suivants si vous prévoyez importer des fichiers CSV entre versions :

Si vous importez un fichier CSV pré-20.12 dans une compétence 20.12 (y compris celles qui prennent en charge les langues de manière native ou utilisent des services de traduction), les valeurs et les synonymes sont importés en tant que langues principales.
Toutes les valeurs d'entité pour les langues principale et secondaire doivent être uniques au sein d'une entité. Ainsi, vous ne pouvez pas importer de fichier CSV si la même valeur a été définie plusieurs fois pour une seule entité. Des valeurs en double peuvent se produire dans les versions pré-20.12, où les valeurs peuvent être considérées comme uniques en raison de variations dans la casse. Cela n'est pas le cas pour 20.12, où le respect de la casse est plus strictement appliqué. Par exemple, vous ne pouvez pas importer un fichier CSV contenant à la fois PizzaSize, Small et PizzaSize, SMALL. Si vous prévoyez de mettre à niveau la version 20.12, vous devez d'abord résoudre toutes les valeurs d'entité identiques, mais différenciées uniquement par la casse.
La prise en charge de la langue principale s'applique aux compétences créées à l'aide des versions 20.12 et supérieures. Vous devez d'abord supprimer les balises de langue et toutes les entrées de langue secondaire avant de pouvoir importer un fichier CSV de version 20.12 dans une compétence créée avec une version antérieure.

Lorsque vous importez un fichier CSV 20.12 dans une compétence 20.12 :

Vous pouvez importer un fichier CSV multilingue dans des compétences qui n'utilisent pas la prise en charge linguistique native, y compris celles qui se servent de services de traduction.
Si vous importez un fichier CSV multilingue dans une compétence qui prend en charge les langues de manière native ou utilise des services de traduction, seules les rangées qui fournissent une valeur valide pour la langue principale sont importées. Le reste est ignoré.

En gardant ces mises en garde à l'esprit, voici comment vous créez des entités au moyen d'une importation :

Cliquez sur Entities (Entités) () dans la barre de navigation latérale.
Cliquez sur More (Plus), sélectionnez Importer des entités de liste de valeurs, puis le fichier .csv de votre système local.

Description de l'illustration import-entities.png
Ajoutez l'entité ou les entités à une intention (ou à une liste d'entités, puis à une intention).

Exporter des entités de type liste de valeurs vers un fichier CSV

Vous pouvez exporter les valeurs et synonymes dans un fichier CSV pour les réutiliser dans une autre compétence. Les fichiers CSV exportés ont le même format que ceux utilisés pour créer des entités grâce à des importations en ce qu'ils contiennent les colonnes entity, value et synonyms. Ces fichiers CSV ont des exigences propres à la version, ce qui peut avoir une incidence sur leur réutilisation.

Les fichiers CSV exportés à partir de compétences créées avec la version 20.12, ou mises à niveau vers cette version, permettent la prise en charge linguistique native grâce aux balises de langue principale (et parfois secondaire) qui sont ajoutées aux colonnes value et synonyms. Par exemple, le fichier CSV de l'extrait de code suivant comporte un jeu de colonnes value et synonyms pour la langue principale de la compétence, l'anglais (en) et un autre pour la langue secondaire, le français (fr) :
```
entity,en:value,en:synonyms,fr:value,fr:synonyms
```
Les balises de langue principale sont incluses dans tous les fichiers CSV 20.12 indépendamment de la prise en charge linguistique native. Elles sont présentes dans les compétences qui ne sont pas destinées à effectuer des traductions (nativement ou par l'intermédiaire d'un service de traduction) et dans les compétences qui utilisent des services de traduction.
Les fichiers CSV exportés à partir de compétences exécutées sur des versions antérieures à 20.12 comportent des colonnes entity, value et synonyms, mais aucune balise de langue.

Pour exporter des entités de liste de valeurs :

Cliquez sur Entities (Entités) () dans la barre de navigation latérale.
Cliquez sur More (Entités de liste de valeurs d'exportation), sélectionnez Export Value list (Exporter les entités de liste de valeurs), puis enregistrez le fichier.

Description de l'illustration export-entities.png

Le fichier .csv exporté est nommé d'après votre compétence. Si vous allez utiliser ce fichier comme importation, vous devrez peut-être effectuer certaines des modifications décrites dans Importer des intentions à partir d'un fichier CSV si vous allez l'importer ou l'exporter à partir de compétences de versions 20.12 et antérieures.

Créer des entités dynamiques

Les valeurs d'entité dynamique sont gérées au moyen des points d'extrémité de l'API d'entités dynamiques, décrite dans API REST pour Oracle Digital Assistant. Pour ajouter, modifier et supprimer les valeurs d'entité et les synonymes, vous devez d'abord créer une entité dynamique afin de générer la propriété entityId utilisée dans les appels REST.

Pour créer l'entité dynamique :

Cliquez sur + Entity (Entité).
Choisissez Dynamic Entities (Entités dynamiques) dans la liste Type.
Si le service dorsal n'est pas disponible ou qu'il n'a encore poussé aucune valeur, ou si vous ne tenez pas à jour le service, cliquez sur + Value (+ Valeur) pour ajouter des valeurs de simulation que vous pouvez utiliser à des fins de test. Généralement, vous ajoutez ces valeurs statiques avant que l'infrastructure d'entité dynamique ne soit en place. Ces valeurs sont perdues lorsque vous clonez ou exportez une compétence, ou créez une nouvelle version. Une fois que vous avez provisionné les valeurs de l'entité à l'aide de l'API, vous pouvez remplacer ou conserver ces valeurs (dans la plupart des cas, vous les remplacez).
Cliquez sur Create (Créer).

Conseil :

Si l'API actualise les valeurs d'entité lors du test de la conversation, cliquez sur Reset (Réinitialiser) pour redémarrer la conversation.

Notes pour les développeurs de services :

Vous pouvez interroger les entités dynamiques configurées pour une compétence à l'aide de la propriété entityId générée avec botId. Ces valeurs sont incluses dans les appels de création des demandes de poussée et des objets qui mettent à jour les valeurs d'entité.
Une entité ne peut pas avoir plus de 150 000 valeurs. Pour limiter le risque de dépasser cette limite lorsque vous traitez de grandes quantités de données, envoyez des demandes PATCH avec vos suppressions avant d'envoyer des demandes PATCH avec vos ajouts.

Note

Les entités dynamiques ne sont prises en charge que dans les instances Oracle Digital Assistant qui ont été provisionnées sur Oracle Cloud Infrastructure (parfois appelée infrastructure en nuage de 2e génération). Si votre instance est provisionnée sur la plate-forme Oracle Cloud (comme c'est le cas pour toutes les instances de la version 19.4.1), vous ne pouvez pas utiliser cette fonction.

Directives pour la création d'entités ML

Voici une approche générale pour créer une entité d'apprentissage automatique.

Créer des entités ML concises. La définition de l'entité d'apprentissage automatique est à la base d'un jeu d'entraînement utile. La clarté est donc essentielle en termes de nom et de description qui aident les contributeurs à annoter les énoncés.
Comme les contributeurs dépendent des descriptions et des noms des entités d'apprentissage automatique, vous devez vous assurer que vos entités d'apprentissage automatique sont facilement distinguables les unes des autres, en particulier en cas de chevauchement potentiel. Si les différences ne sont pas claires pour vous, il est probable que les contributeurs seront confus. Par exemple, les entités Marchand et Type de compte peuvent être difficiles à différencier dans certains cas. Dans "Transférer 100 $ de mon compte d'épargne à Pacific Gas and Electric", vous pouvez clairement étiqueter "économies" comme type de compte et Pacific Gas and Electric comme commerçant. Cependant, la frontière entre les deux peut être floue dans des phrases comme "Nécessité d'envoyer de l'argent à John, transférer 100 $ de mon épargne à son compte courant". Le "compte de chèques" est-il un type de compte ou un nom de commerçant? Dans ce cas, vous pouvez décider que tout destinataire doit toujours être un nom de commerçant plutôt qu'un type de compte.

Pour préparer l'approvisionnement participatif des énoncés d'entraînement, tenez compte de l'entrée utilisateur typique pour différents contextes d'extraction d'entités. Par exemple, la valeur peut-elle être extraite dans le message initial de l'utilisateur (contexte d'énoncé initial) ou est-elle extraite des réponses aux invites de la compétence (contexte d'énoncé de créneau)?

Context (Contexte)	Description	Exemples d'énoncés (valeurs d'entité d'apprentissage automatique détectées en gras)
Contexte d'énoncé initial	Message généralement bien structuré et comprenant des valeurs d'entité d'apprentissage automatique. Pour une compétence de rapport de frais, par exemple, l'énoncé inclurait une valeur que le modèle peut détecter pour une entité d'apprentissage automatique appelée Marchand.	Créez des frais pour le dîner d'équipe au magasin de pâtes John's pour 85 $ le 3 mai
Contexte d'énoncé d'emplacement	Message d'utilisateur qui fournit l'entité ML en réponse à une invite, soit en raison de la conception de la conversation (la compétence invite à indiquer "Qui est le commerçant?"), soit pour définir une valeur, car elle n'a pas été fournie par une réponse soumise précédemment. Dans d'autres circonstances, la valeur de l'entité d'apprentissage automatique a peut-être déjà été fournie, mais peut être incluse dans d'autres messages utilisateur dans la même conversation. Par exemple, la compétence peut inviter les utilisateurs à fournir des détails supplémentaires sur les frais ou à décrire l'image d'un reçu chargé.	Le commerçant est John's Pasta Shop. Dîner d'équipe. Montant $85. Atelier de pâtes John. La description est TurboTaxi de la maison à l'aéroport CMH. Réception relative au Grandiose Shack Hotel pour le symposium sur le nuage

Collectez vos données d'entraînement et de test.

Si vous disposez déjà d'une collection suffisante d'énoncés, vous pouvez les évaluer pour la répartition des entités et la diversité des valeurs d'entité avant de lancer une tâche d'annotation d'entité.
Si vous n'avez pas assez de données d'entraînement, ou si vous partez de zéro, lancez une tâche de paraphrasage d'intention. Pour collecter des énoncés viables (et abondants) aux fins d'entraînement et de test, intégrez le contexte d'entité dans le travail en créant des tâches pour chaque intention. Pour rassembler diverses phrases, pensez à décomposer chaque intention par contexte de conversation.

Pour l'invite de la tâche, fournissez le contexte des contributeurs et demandez-leur : " Comment répondriez-vous? " ou " Que diriez-vous? " Utilisez les conseils d'accompagnement pour fournir des exemples et illustrer différents contextes. Par exemple :

Invite	Conseil
Vous parlez à un robot de production de rapports de frais et vous voulez créer des frais. Quelle serait la première chose que vous diriez?	Assurez-vous que le nom du commerçant figure dans l'énoncé. Vous pourriez dire quelque chose comme : "Créez une dépense pour le dîner d'équipe à John's Pasta Shop pour 85 $ le 3 mai."

Cette tâche demande des expressions qui non seulement lancent la conversation, mais incluent également un nom de commerçant. Vous pouvez également vouloir des énoncés qui reflètent les réponses demandées par la compétence lorsque l'utilisateur ne fournit pas de valeur. Par exemple, "Merchant is John's Pasta Shop" en réponse à l'invite "Qui est le commerçant?" de la compétence.

Invite	Conseil
Vous avez soumis des frais à un robot de production de rapports de frais, mais vous n'avez pas fourni de nom de commerçant. Comment répondriez-vous?	Identifiez le commerçant. Par exemple, "Merchant is John's Pasta Shop".
Vous avez chargé une image d'un reçu dans un robot de production de rapports de frais. Il vous demande maintenant de décrire le reçu. Comment répondriez-vous?	Identifiez le nom du commerçant sur le reçu. Par exemple : " Reçu du Grandiose Shack Hotel pour le symposium sur le nuage ".

Pour tester les faux positifs aux fins de test - mots et expressions que le modèle ne doit pas identifier en tant qu'entités ML - vous pouvez également collecter des "exemples négatifs". Ces énoncés incluent une valeur d'entité ML.

Context (Contexte)	Exemples d'énoncés
Contexte d'énoncé initial	Ramenez-moi pour le dîner de mardi
Contexte d'énoncé d'emplacement	Dîner de présentation Pos. Montant 50$. 4 personnes. Description xerox déjeuner pour 5 Reçu d'hôtel pour séjour d'entrevue

Rassemblez un jeu d'entraînement volumineux en définissant un nombre approprié de paraphrases par intention. Pour que le modèle puisse être généralisé avec succès, votre jeu de données doit contenir entre 500 et 5000 occurrences pour chaque entité d'apprentissage automatique. Idéalement, vous devriez éviter le bas de cette gamme.

Une fois que les contributeurs ont terminé le travail (ou ont terminé suffisamment d'énoncés pour que vous puissiez annuler le travail), vous pouvez ajouter les énoncés ou lancer un travail de validation d'intention pour les vérifier. Vous pouvez également télécharger les résultats dans votre système local pour une révision supplémentaire.
Réservez environ 20 % des énoncés à des fins de test. Pour créer des valeurs CSV pour le testeur d'énoncé à partir des fichiers CSV téléchargés pour les tâches de paraphrasage d'intention et de validation d'intention :
- Pour les tâches de paraphrasage d'intention : transférez le contenu de la colonne result (les énoncés fournis par les contributeurs) vers la colonne utterance dans le fichier CSV du testeur d'énoncé. Transférez le contenu de la colonne intentName vers la colonne expectedIntent dans le fichier CSV du testeur d'énoncé.
- Pour les tâches de validation d'intention : transférez le contenu de la colonne prompt (les énoncés fournis par les contributeurs) vers la colonne utterance dans le fichier CSV du testeur d'énoncé. Transférez le contenu de la colonne intentName vers la colonne expectedIntent dans le fichier CSV du testeur d'énoncé.
Ajoutez les énoncés restants à un fichier CSV avec une seule colonne, utterance. Créez une tâche d'annotation d'entité en chargeant ce fichier CSV. Comme les travailleurs étiquettent les valeurs d'entité, ils classeront probablement les énoncés négatifs comme "Je ne suis pas sûr" ou "Aucune des entités ne s'applique".
Une fois la tâche d'annotation d'entité terminée, vous pouvez ajouter les résultats ou lancer une tâche de validation d'entité pour vérifier l'étiquetage. Seuls les énoncés que les travailleurs jugent corrects dans une tâche de validation d'entité peuvent être ajoutés au corpus.

Conseil :
Vous pouvez ajouter, supprimer ou ajuster les étiquettes d'annotation dans l'onglet Jeu de données de la page Entités.
Entraînez l'entité en sélectionnant Entité.
Exécutez des cas de test pour évaluer la reconnaissance d'entités à l'aide des énoncés que vous avez réservés à partir de la tâche de paraphrasage d'intention. Vous pouvez diviser ces énoncés en différentes séries de tests pour tester différents comportements (valeurs inconnues, ponctuation qui peut ne pas être présente dans les données d'entraînement, faux positifs, etc.). Comme il peut y avoir un grand nombre de ces énoncés, vous pouvez créer des séries de tests en chargeant un fichier CSV dans le testeur d'énoncé.

Description de l'illustration ml-test-suites.png

Note

Le testeur d'énoncé affiche uniquement les étiquettes d'entité pour les scénarios de test réussis. Utilisez plutôt un test rapide pour voir les étiquettes des énoncés dont la résolution est inférieure au seuil de confiance.
Utilisez les résultats pour affiner le jeu de données. Ajoutez, supprimez ou modifiez les énoncés d'entraînement de manière itérative jusqu'à ce que les résultats de l'exécution du test indiquent que le modèle identifie efficacement les entités ML.
Note

Pour empêcher les correspondances d'entités par inadvertance qui dégradent l'expérience utilisateur, activez l'option Exclure les correspondances d'entités système si les données d'entraînement contiennent des noms, des emplacements, des numéros.

Directives de formation sur les entités ML

Le modèle généralise une entité en utilisant à la fois le contexte autour d'un mot (ou de mots) et l'information lexicale sur le mot lui-même. Pour que le modèle se généralise efficacement, nous recommandons que le nombre d'annotations par entité soit compris entre 500 et 5000. Vous disposez peut-être déjà d'un jeu d'entraînement suffisamment volumineux et présentant la variation des valeurs d'entité que vous attendez des utilisateurs finaux. Si tel est le cas, vous pouvez lancer une tâche d'annotation d'entité, puis incorporer les résultats dans les données d'entraînement. Toutefois, si vous ne disposez pas de suffisamment de données d'entraînement ou si les données que vous avez manquent d'une couverture suffisante pour toutes les entités d'apprentissage automatique, vous pouvez collecter des énoncés à partir de travaux de paraphrasage d'intention sources multiples.

Quelle que soit la source, la répartition des valeurs d'entité doit refléter votre idée générale des valeurs que le modèle peut rencontrer. Pour bien former le modèle :

Ne surutilisez pas les mêmes valeurs d'entité dans vos données d'entraînement. Les valeurs d'entité répétitives dans les données d'entraînement empêchent le modèle de généraliser des valeurs inconnues. Par exemple, vous attendez de l'entité ML qu'elle reconnaisse une variété de valeurs, mais elle n'est représentée que par 10 à 20 valeurs différentes dans votre jeu d'entraînement. Dans ce cas, le modèle ne généralisera pas, même s'il y a deux ou trois mille annotations.
Variez le nombre de mots pour chaque valeur d'entité. Si vous prévoyez que les utilisateurs entrent des valeurs d'entité de trois à cinq mots, mais que vos données d'entraînement sont annotées avec des valeurs d'entité d'un ou de deux mots, le modèle peut ne pas identifier l'entité à mesure que le nombre de mots augmente. Dans certains cas, il ne peut identifier que partiellement l'entité. Le modèle suppose la limite d'entité à partir des énoncés que vous avez fournis. Si vous avez entraîné le modèle sur des valeurs avec un ou deux mots, il suppose que la limite de l'entité ne comporte qu'un ou deux mots. L'ajout d'entités avec plus de mots permet au modèle de reconnaître des limites d'entité plus longues.
La longueur de l'énoncé doit refléter votre cas d'utilisation et l'entrée utilisateur prévue. Vous pouvez entraîner le modèle à détecter les entités pour les messages de longueurs variables en collectant des énoncés courts et longs. Les énoncés peuvent même avoir plusieurs phrases. Si vous prévoyez des énoncés courts qui reflètent le contexte de remplissage des emplacements, rassemblez vos données-échantillons en conséquence. De même, si vous prévoyez des énoncés pour le scénario de contexte initial, le jeu d'entraînement doit contenir des expressions complètes.
Inclure la ponctuation. Si les noms d'entité nécessitent des caractères spéciaux, tels que '-' et '/', incluez-les dans les valeurs d'entité des données d'entraînement.
Assurez-vous que toutes les entités ML sont également représentées dans vos données d'entraînement. Un jeu d'entraînement déséquilibré comporte trop d'instances d'une entité et trop peu d'autres. Les modèles produits à partir de jeux d'entraînement déséquilibrés échouent parfois à détecter l'entité avec trop peu d'instances et prédisent trop pour les entités avec des instances disproportionnées. Cela conduit à des faux positifs.

Directives de test des entités ML

Avant d'entraîner votre compétence, vous devez réserver environ 20 % des énoncés non annotés pour savoir comment le modèle se généralise lorsqu'il est présenté avec des énoncés ou des valeurs d'entité qui ne font pas partie de ses données d'entraînement. Ce jeu d'énoncés peut ne pas être votre seul jeu de tests, selon les comportements que vous souhaitez évaluer. Par exemple :

Utilisez uniquement des énoncés de contexte d'emplacement pour déterminer dans quelle mesure le modèle prédit les entités avec moins de contexte.
Utilisez des énoncés avec des valeurs "inconnues" pour déterminer dans quelle mesure le modèle se généralise avec des valeurs qui ne sont pas présentes dans les données d'entraînement.
Utilisez des énoncés sans entités ML pour déterminer si le modèle détecte des faux positifs.
Utilisez des énoncés qui contiennent des valeurs d'entité d'apprentissage automatique avec ponctuation pour déterminer le rendement du modèle avec des valeurs d'entité inhabituelles.

Documentation sur Oracle Cloud Infrastructure