Référencer un chemin d’accès aux nœuds enrichis à l’aide des propriétés de contexte et de source d’un ensemble de compétences de la Recherche Azure AI

Article
09/03/2024

Pendant l’exécution de l’ensemble de compétences, le moteur génère une arborescence d’enrichissement en mémoire qui capture chaque enrichissement, comme les entités reconnues ou le texte traduit. Dans cet article, découvrez comment référencer un nœud d’enrichissement dans l’arborescence d’enrichissement afin de pouvoir transmettre la sortie aux compétences en aval ou spécifier un mappage de champ de sortie pour un champ d’index de recherche.

Cet article utilise des exemples pour illustrer différents scénarios. Pour obtenir la syntaxe complète, consultez Langage d’annotation du contexte et des entrées de compétences.

Concepts de base

Avant d’examiner la syntaxe, revenons sur quelques concepts importants pour mieux comprendre les exemples fournis plus loin.

Terme	Description
« document enrichi »	Un document enrichi est une structure en mémoire qui collecte la sortie des compétences lors de sa création et contient tous les enrichissements liés à un document. Imaginez un document enrichi comme une arborescence. En règle générale, l’arborescence commence au niveau du document racine, et chaque nouvel enrichissement est créé à partir d’un précédent en tant qu’enfant.
« node »	Dans un document enrichi, un nœud (parfois appelé « annotation ») est créé et rempli par une compétence, tel que « text » et « layoutText » dans la compétence OCR. Un document enrichi est rempli à la fois avec des enrichissements et des valeurs de champ source d’origine ou des métadonnées copiées à partir de la source.
« contexte »	Étendue de l’enrichissement, qui est l’ensemble du document, une partie d’un document ou, si vous utilisez des images, les images extraites d’un document. Par défaut, le contexte d’enrichissement est au niveau `"/document"`, limité à des documents individuels contenus dans la source de données. Quand une compétence est appliquée, ses résultats deviennent des propriétés du contexte défini.

Chemins pour différents scénarios

Les chemins sont spécifiés dans les propriétés « context » et « source » d’un ensemble de compétences et dans les mappages de champs de sortie dans un indexeur.

L’exemple de la capture d’écran illustre le chemin d’un élément dans une collection Azure Cosmos DB.

Le chemin context est /document/HotelId car la collection est partitionnée en documents en fonction du champ /HotelId.
Le chemin source est /document/Description parce que la compétence est une compétence de traduction et que le champ que vous souhaitez traduire est le champ Description de chaque document.

Tous les chemins commencent par /document. Un document enrichi est créé à l’étape de « craquage de document » de l’exécution de l’indexeur, quand l’indexeur ouvre un document ou lit dans une ligne à partir de la source de données. Initialement, le seul nœud d’un document enrichi est le nœud racine (/document) ; il s’agit du nœud à partir duquel tous les autres enrichissements se produisent.

La liste suivante comprend plusieurs exemples courants :

/document est le nœud racine et indique un objet blob entier dans Stockage Azure ou une ligne dans une table SQL.
/document/{key} est la syntaxe d’un document ou d’un élément dans une collection Azure Cosmos DB, où {key} est la clé réelle, comme /document/HotelId dans l’exemple précédent.
/document/content spécifie la propriété « content » d’un objet blob JSON.
/document/{field} est la syntaxe d’une opération effectuée sur un champ spécifique, comme la traduction du champ /document/Description, vue dans l’exemple précédent.
/document/pages/* or /document/sentences/* deviennent le contexte si vous scindez un grand document en blocs plus petits en vue du traitement. Si « context » est /document/pages/*, la compétence s’exécute une fois sur chaque page du document. Étant donné qu’il peut y avoir plusieurs pages ou phrases, vous ajoutez /* pour les intercepter.
/document/normalized_images/* est créé pendant le craquage de document si le document contient des images. Tous les chemins des images commencent par normalized_images. Étant donné qu’il existe souvent plusieurs images incorporées dans un document, ajoutez /*.

Les exemples présentés dans le reste de cet article sont basés sur le champ « content » généré automatiquement par les indexeurs d’objets blob Azure durant la phase de craquage de document. Quand vous faites référence à des documents à partir d’un conteneur d’objets blob, utilisez un format tel que "/document/content", où le champ « content » fait partie du « document ».

Exemple 1 : référencer une annotation simple

Dans Stockage Blob Azure, supposons que vous ayez une variété de fichiers contenant des références à des noms de personnes que vous souhaitez extraire à l’aide d’une reconnaissance d’entité. Dans la définition de compétence suivante, "/document/content" est la représentation textuelle du document entier, et « people » une extraction de noms complets d’entités identifiées en tant que personnes.

Le contexte par défaut étant "/document", la liste de personnes peut désormais être référencée comme "/document/people". En l’occurrence, "/document/people" est une annotation qui peut maintenant être mappée à un champ dans un index, ou utilisée dans une autre compétence du même jeu de compétences.

  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "categories": [ "Person"],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "persons",
        "targetName": "people"
      }
    ]
  }

Exemple 2 : référencer un tableau à l’intérieur d’un document

Cet exemple s’appuie sur le précédent pour montrer comment appeler une étape d’enrichissement plusieurs fois sur le même document. Supposons que l’exemple précédent a généré un tableau de chaînes comprenant 10 noms de personnes à partir d’un seul document. L’étape suivante pourrait raisonnablement être un deuxième enrichissement extrayant le nom de famille d’un nom complet. Étant donné qu’il y a 10 noms, vous voulez que cette étape soit appelée 10 fois dans ce document, soit une fois par personne.

Pour appeler le nombre approprié d’itérations, définissez le contexte comme "/document/people/*", où l’astérisque ("*") représente tous les nœuds figurant dans le document enrichi en tant que descendants de "/document/people". Même si cette compétence n’est définie qu’une seule fois dans le tableau des compétences, elle est appelée pour chaque membre figurant dans le document jusqu’à ce que tous les membres soient traités.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the last name from a full name",
    "uri": "http://names.azurewebsites.net/api/GetLastName",
    "context" : "/document/people/*",
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "fullname",
        "source": "/document/people/*"
      }
    ],
    "outputs": [
      {
        "name": "lastname",
        "targetName": "last"
      }
    ]
  }

Lorsque les annotations sont des tableaux ou des collections de chaînes, vous pouvez cibler des membres spécifiques plutôt que le tableau dans son ensemble. L’exemple ci-dessus génère une annotation appelée "last" sous chaque nœud représenté par le contexte. Si vous souhaitez faire référence à cette famille d’annotations, vous pouvez utiliser la syntaxe "/document/people/*/last". Si vous voulez faire référence à une annotation particulière, vous pouvez utiliser un index explicite "/document/people/1/last pour faire référence au nom de famille de la première personne identifiée dans le document. Notez que, dans cette syntaxe, les tableaux sont « indexés sur 0 ».

Exemple 3 : référencer des membres à l’intérieur d’un tableau

Parfois, vous devez regrouper toutes les annotations d’un type particulier pour les transmettre à une compétence particulière. Imaginez une compétence personnalisée hypothétique qui identifie le nom de famille le plus courant parmi tous les noms de famille extraits dans l’Exemple 2. Pour fournir uniquement les noms de famille à la compétence personnalisée, spécifiez le contexte comme "/document" et l’entrée comme "/document/people/*/lastname".

Notez que la cardinalité de "/document/people/*/lastname" est supérieure à celle du document. Il peut y avoir 10 nœuds de nom de famille alors qu’il n’y a qu’un seul nœud de document pour ce document. Dans ce cas, le système crée automatiquement un tableau de "/document/people/*/lastname" contenant tous les éléments du document.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the most common string from an array of strings",
    "uri": "http://names.azurewebsites.net/api/MostCommonString",
    "context" : "/document",
    "inputs": [
      {
        "name": "strings",
        "source": "/document/people/*/lastname"
      }
    ],
    "outputs": [
      {
        "name": "mostcommon",
        "targetName": "common-lastname"
      }
    ]
  }

Conseils pour la résolution des problèmes de chemin d’annotation

Si vous rencontrez des problèmes avec la spécification des entrées de compétence, ces conseils peuvent vous aider à avancer :

Exécutez l’Assistant Importation de données sur vos données pour passer en revue les définitions d’ensemble de compétences et les mappages de champs générés par l’Assistant.
Démarrez une session de débogage sur un ensemble de compétences pour afficher la structure d’un document enrichi. Vous pouvez modifier les chemins et d’autres parties de la définition de compétence, puis exécuter la compétence pour valider vos modifications.

Partage via