Langage d’annotation du contexte et des entrées de compétences
Cet article est la documentation de référence de la syntaxe du contexte et des entrées de compétences. Il s’agit d’une description complète du langage d’expression utilisé pour construire des chemins vers des nœuds dans un document enrichi.
Les compétences de la Recherche Azure AI peuvent utiliser et enrichir les données provenant de la source de données et de la sortie d’autres compétences. La plage de travail des données qui représente l’état actuel du travail de l’indexeur pour le document actif commence avec les données brutes provenant de la source de données et est progressivement enrichie avec les données de sortie de chaque itération de compétence. Ces données sont organisées en interne dans une structure d’arborescence qui peut être interrogée pour servir d’entrée de compétence ou être ajoutée à l’index. Les nœuds de l’arborescence peuvent être des valeurs simples comme des chaînes et des nombres, des tableaux ou des objets complexes, et même des fichiers binaires. Même les valeurs simples peuvent être enrichies avec des informations structurées supplémentaires. Par exemple, une chaîne peut être annotée avec des informations supplémentaires qui sont stockées sous celle-ci dans l’arborescence d’enrichissement. Les expressions utilisées pour interroger cette structure interne utilisent une syntaxe riche qui est détaillée dans cet article. Vous pouvez inspecter la structure des données enrichies dans des sessions de débogage. Les expressions qui interrogent la structure peuvent également être testées dans des sessions de débogage.
Tout au long de l’article, nous utilisons les données enrichies suivantes comme exemple. Ces données sont typiques du type de structure que vous obtenez quand vous enrichissez un document en utilisant un ensemble de compétences avec OCR, l’extraction de phrases clés, la traduction de texte, la détection de langue, la reconnaissance d’entités, ainsi qu’une compétence de génération de jetons personnalisée.
| Chemin d’accès | Valeur |
|---|---|
document |
|
merged_content |
« Study of BMN 110 in Pediatric Patients »... |
keyphrases |
|
[0] |
« Study of BMN » |
[1] |
« Syndrome » |
[2] |
« Pediatric Patients » |
| ... | |
locations |
|
[0] |
« IVA » |
translated_text |
« Études de BMN 110 chez les patients en pédiatrie »... |
entities |
|
[0] |
|
category |
« Organization » |
subcategory |
null |
confidenceScore |
0,72 |
length |
3 |
offset |
9 |
text |
« BMN » |
| ... | |
organizations |
|
[0] |
« BMN » |
language |
« en » |
normalized_images |
|
[0] |
|
layoutText |
... |
text |
|
words |
|
[0] |
« Étude » |
[1] |
« of » |
[2] |
« BMN » |
[3] |
« 110 » |
| ... | |
[1] |
|
layoutText |
... |
text |
|
words |
|
[0] |
« it » |
[1] |
« is » |
[2] |
« certainly » |
| ... | |
| ... | |
| ... |
Racine du document
Toutes les données se trouvent sous un élément racine, dont le chemin est "/document". L’élément racine est le contexte par défaut des compétences.
Chemins simples
Les chemins simples dans le document enrichi interne peuvent être exprimés avec des jetons simples séparés par des barres obliques. Cette syntaxe est équivalente à la spécification du pointeur JSON.
Propriétés des objets
Les propriétés des nœuds qui représentent les objets ajoutent leurs valeurs à l’arborescence sous le nom de la propriété. Ces valeurs peuvent être obtenues en ajoutant le nom de la propriété sous la forme d’un jeton séparé par une barre oblique :
| Expression | Valeur |
|---|---|
/document/merged_content/language |
"en" |
Les jetons de nom de propriété respectent la casse.
Index d’éléments de tableau
Des éléments spécifiques d’un tableau peuvent être référencés en utilisant leur index numérique comme nom de propriété :
| Expression | Valeur |
|---|---|
/document/merged_content/keyphrases/1 |
"Syndrome" |
/document/merged_content/entities/0/text |
"BMN" |
Séquences d’échappement
Deux caractères ont une signification particulière et doivent être échappés s’ils apparaissent dans une expression et qu’ils doivent être interprétés tel quel plutôt qu’avec leur signification particulière : '/' et '~'.
Ces caractères doivent être échappés respectivement avec '~0' et '~1'.
Énumération de tableau
Un tableau de valeurs peut être obtenu en utilisant le jeton '*' :
| Expression | Valeur |
|---|---|
/document/normalized_images/0/text/words/* |
["Study", "of", "BMN", "110" ...] |
Le jeton '*' n’a pas besoin d’être à la fin du chemin. Vous pouvez énumérer tous les nœuds correspondant à un chemin avec une étoile au milieu ou avec plusieurs étoiles :
| Expression | Valeur |
|---|---|
/document/normalized_images/*/text/words/* |
["Study", "of", "BMN", "110" ... "it", "is", "certainly" ...] |
Cet exemple retourne une liste plate de tous les nœuds correspondants.
Vous pouvez conserver plus de structure et obtenir un tableau séparé pour les mots de chaque page en utilisant un jeton '#' au lieu du deuxième jeton '*' :
| Expression | Valeur |
|---|---|
/document/normalized_images/*/text/words/# |
[["Study", "of", "BMN", "110" ...], ["it", "is", "certainly" ...] ...] |
Le jeton '#' indique que le tableau doit être traité comme une seule valeur au lieu d’être énuméré.
Énumération de tableaux dans le contexte
Il est souvent utile de traiter chaque élément d’un tableau séparément et d’avoir un ensemble différent d’entrées et de sorties de compétence pour chacun d’entre eux.
Pour ce faire, définissez le contexte de la compétence sur une énumération plutôt que sur la valeur par défaut "/document".
Dans l’exemple suivant, nous utilisons une des expressions d’entrée que nous avons utilisées précédemment, mais avec un contexte différent qui change la valeur obtenue.
| Context | Expression | Valeurs |
|---|---|---|
/document/normalized_images/* |
/document/normalized_images/*/text/words/* |
["Study", "of", "BMN", "110" ...]["it", "is", "certainly" ...]... |
Pour cette combinaison de contexte et d’entrée, la compétence est exécutée une fois pour chaque image normalisée : une fois pour "/document/normalized_images/0" et une fois pour "/document/normalized_images/1". Les deux valeurs d’entrée correspondant à chaque exécution de compétence sont détaillées dans la colonne de valeurs.
Quand vous énumérez un tableau dans le contexte, toutes les sorties générées par la compétence sont également ajoutées au document sous forme d’enrichissements du contexte.
Dans l'exemple ci-dessus, une sortie nommée "out" a ses valeurs pour chaque exécution ajoutée au document respectivement sous "/document/normalized_images/0/out" et "/document/normalized_images/1/out".
Valeurs littérales
Les entrées de compétence peuvent prendre des valeurs littérales comme entrées au lieu de valeurs dynamiques interrogées à partir du document existant. Pour ce faire, ajoutez un signe égal en préfixe de la valeur. Les valeurs peuvent être des nombres, des chaînes ou des valeurs booléennes.
Les valeurs de chaîne doivent être placées entre guillemets simples ' ou doubles ".
| Expression | Valeur |
|---|---|
=42 |
42 |
=2.45E-4 |
0.000245 |
="some string" |
"some string" |
='some other string' |
"some other string" |
="unicod\u0065" |
"unicode" |
=false |
false |
Dans les tableaux de lignes
Si une certaine entrée de compétence nécessite un tableau de données, mais que les données sont représentées sous la forme d’une valeur unique actuellement ou que vous devez combiner plusieurs valeurs uniques dans un champ de tableau, vous pouvez créer une valeur de tableau inline dans le cadre d’une expression d’entrée de compétence en encapsulant une liste séparée par des virgules d’expressions entre crochets ([ et ]). La valeur de tableau peut être une combinaison de chemins d’expression ou de valeurs littérales si nécessaire. Vous pouvez également créer des tableaux imbriqués dans des tableaux de cette façon.
| Expression | Valeur |
|---|---|
=['item'] |
["item"] |
=[$(/document/merged_content/entities/0/text), 'item'] |
["BMN", "item"] |
=[1, 3, 5] |
[1, 3, 5] |
=[true, true, false] |
[true, true, false] |
=[[$(/document/merged_content/entities/0/text), 'item'],['item2', $(/document/merged_content/keyphrases/1)]] |
[["BMN", "item"], ["item2", "Syndrome"]] |
Si la compétence a un contexte qui explique comment exécuter la compétence par entrée de tableau (autrement dit, comment "context": "/document/pages/*" signifie que la compétence s’exécute une fois par « page » dans pages) puis en passant cette valeur en tant qu’expression comme entrée à un tableau de lignes utilise l’une de ces valeurs à la fois.
Pour obtenir un exemple avec nos exemples de données enrichies, si votre compétence context est /document/merged_content/keyphrases/* et que vous créez un tableau inline des éléments suivants =['key phrase', $(/document/merged_content/keyphrases/*)] sur une entrée de cette compétence, la compétence est exécutée trois fois, une fois avec une valeur ["key phrase", "Study of BMN"], une autre avec une valeur ["key phrase", "Syndrome"] et enfin avec une valeur ["key phrase", "Pediatric Patients"]. La valeur littérale « phrase clé » reste la même à chaque fois, mais la valeur du chemin d’accès d’expression change avec chaque exécution de compétence.
Expressions composites
Vous pouvez combiner des valeurs en utilisant des opérateurs unaires, binaires et ternaires.
Les opérateurs peuvent combiner des valeurs littérales et des valeurs résultant de l’évaluation du chemin.
Quand ils sont utilisés dans une expression, les chemins doivent être placés entre "$(" et ")".
Opérateur booléen NOT '!'
| Expression | Valeur |
|---|---|
=!false |
true |
Négatif '-'
| Expression | Valeur |
|---|---|
=-42 |
-42 |
=-$(/document/merged_content/entities/0/offset) |
-9 |
Addition '+'
| Expression | Valeur |
|---|---|
=2+2 |
4 |
=2+$(/document/merged_content/entities/0/offset) |
11 |
Soustraction '-'
| Expression | Valeur |
|---|---|
=2-1 |
1 |
=$(/document/merged_content/entities/0/offset)-2 |
7 |
Multiplication '*'
| Expression | Valeur |
|---|---|
=2*3 |
6 |
=$(/document/merged_content/entities/0/offset)*2 |
18 |
Division '/'
| Expression | Valeur |
|---|---|
=3/2 |
1.5 |
=$(/document/merged_content/entities/0/offset)/3 |
3 |
Modulo '%'
| Expression | Valeur |
|---|---|
=15%4 |
3 |
=$(/document/merged_content/entities/0/offset)%2 |
1 |
Inférieur ou égal '<' '<=' '>', supérieur ou égal à '>='
| Expression | Valeur |
|---|---|
=15<4 |
false |
=4<=4 |
true |
=15>4 |
true |
=1>=2 |
false |
Égalité et aucune qualité '==' '!='
| Expression | Valeur |
|---|---|
=15==4 |
false |
=4==4 |
true |
=15!=4 |
true |
=1!=1 |
false |
Opérations logiques et, ou exclusives ou exclusives ou '&&' '||' '^'
| Expression | Valeur |
|---|---|
=true&&true |
true |
=true&&false |
false |
=true||true |
true |
=true||false |
true |
=false||false |
false |
=true^false |
true |
=true^true |
false |
Opérateur ternaire '?:'
Vous pouvez attribuer des valeurs différentes à une entrée en fonction de l’évaluation d’une expression booléenne en utilisant l’opérateur ternaire.
| Expression | Valeur |
|---|---|
=true?"true":"false" |
"true" |
=$(/document/merged_content/entities/0/offset)==9?"nine":"not nine" |
"nine" |
Parenthèses et priorité d’opérateurs
Les opérateurs sont évalués avec des priorités qui correspondent aux conventions habituelles : les opérateurs unaires, puis la multiplication, la division et le modulo, puis l’addition et la soustraction, puis la comparaison, puis l’égalité, puis les opérateurs logiques. Les règles d’associativité habituelles s’appliquent également.
Vous pouvez utiliser des parenthèses pour changer ou lever l’ambiguïté de l’ordre d’évaluation.
| Expression | Valeur |
|---|---|
=3*2+5 |
11 |
=3*(2+5) |
21 |