Контекст навыка и язык заметок ввода
В этой статье приведена справочная документация по контексту навыка и синтаксису входных данных. Это полное описание языка выражений, используемого для создания путей к узлам в обогащенном документе.
Навыки поиска ИИ Azure могут использовать и дополнять данные, поступающие из источника данных, и из выходных данных других навыков. Рабочий набор данных, представляющий текущее состояние работы индексатора для текущего документа, начинается с необработанных данных, поступающих из источника данных, и постепенно обогащен выходными данными каждого навыка. Эти данные внутренне упорядочены в виде дерева, которую можно запрашивать для использования в качестве входных данных навыка или добавления в индекс. Узлы в дереве могут быть простыми значениями, такими как строки и числа, массивы или сложные объекты и даже двоичные файлы. Даже простые значения можно дополнить дополнительными структурированными сведениями. Например, строка может быть аннотирована с дополнительными сведениями, хранящимися под ним в дереве обогащения. Выражения, используемые для запроса внутренней структуры, используют расширенный синтаксис, подробно описанный в этой статье. Обогащенную структуру данных можно проверить из сеансов отладки. Выражения, запрашивающие структуру, также можно протестировать из сеансов отладки.
В этой статье мы будем использовать следующие обогащенные данные в качестве примера. Эти данные типичны для типа структуры, которые вы получаете при обогащении документа с помощью набора навыков с помощью OCR, извлечения ключевых фраз, перевода текста, распознавания речи и навыков распознавания сущностей, а также пользовательского навыка токенизатора.
| Путь | Значение |
|---|---|
document |
|
merged_content |
"Исследование BMN 110 в педиатрических пациентов"... |
keyphrases |
|
[0] |
"Исследование BMN" |
[1] |
"Синдром" |
[2] |
"Педиатрические пациенты" |
| ... | |
locations |
|
[0] |
"IVA" |
translated_text |
"Étude de BMN 110 chez les пациентов pédiatriques"... |
entities |
|
[0] |
|
category |
"Организация" |
subcategory |
null |
confidenceScore |
0,72 |
length |
3 |
offset |
9 |
text |
"BMN" |
| ... | |
organizations |
|
[0] |
"BMN" |
language |
"en" |
normalized_images |
|
[0] |
|
layoutText |
... |
text |
|
words |
|
[0] |
"Исследование" |
[1] |
"of" |
[2] |
"BMN" |
[3] |
"110" |
| ... | |
[1] |
|
layoutText |
... |
text |
|
words |
|
[0] |
"it" |
[1] |
"is" |
[2] |
"конечно" |
| ... | |
| ... | |
| ... |
Корневой каталог документа
Все данные находится под одним корневым элементом, для которого находится "/document"путь. Корневой элемент — это контекст по умолчанию для навыков.
Простые пути
Простые пути через внутренний обогащенный документ можно выразить с помощью простых маркеров, разделенных косыми чертами. Этот синтаксис аналогичен спецификации указателя JSON.
Свойства объекта
Свойства узлов, представляющих объекты, добавляют значения в дерево под именем свойства. Эти значения можно получить путем добавления имени свойства в виде маркера, разделенного косой чертой:
| Expression | Значение |
|---|---|
/document/merged_content/language |
"en" |
Маркеры имен свойств чувствительны к регистру.
Индекс элемента массива
На определенные элементы массива можно ссылаться с помощью числового индекса, например имени свойства:
| Expression | Значение |
|---|---|
/document/merged_content/keyphrases/1 |
"Syndrome" |
/document/merged_content/entities/0/text |
"BMN" |
Escape-последовательности
Есть два символа, которые имеют особое значение и должны быть экранированы, если они отображаются в выражении и должны быть интерпретированы как вместо их специального значения: '/' и '~'.
Эти символы должны быть экранированы соответственно как '~0' и '~1'.
Перечисление массива
Массив значений можно получить с помощью маркера '*' :
| Expression | Значение |
|---|---|
/document/normalized_images/0/text/words/* |
["Study", "of", "BMN", "110" ...] |
Маркер '*' не должен находиться в конце пути. Можно перечислить все узлы, соответствующие пути со звездой в середине или с несколькими звездами:
| Expression | Значение |
|---|---|
/document/normalized_images/*/text/words/* |
["Study", "of", "BMN", "110" ... "it", "is", "certainly" ...] |
В этом примере возвращается плоский список всех соответствующих узлов.
Можно поддерживать большую структуру и получить отдельный массив для слов каждой страницы с помощью '#' маркера вместо второго '*' маркера:
| Expression | Значение |
|---|---|
/document/normalized_images/*/text/words/# |
[["Study", "of", "BMN", "110" ...], ["it", "is", "certainly" ...] ...] |
Маркер '#' выражает, что массив должен рассматриваться как одно значение вместо перечисления.
Перечисление массивов в контексте
Часто полезно обрабатывать каждый элемент массива в изоляции и иметь разные наборы входных и выходных данных навыка для каждого элемента.
Это можно сделать, задав контекст навыка перечислению вместо значения по умолчанию "/document".
В следующем примере мы используем одно из входных выражений, которые мы использовали раньше, но с другим контекстом, который изменяет результирующее значение.
| Контекст | Expression | Значения |
|---|---|---|
/document/normalized_images/* |
/document/normalized_images/*/text/words/* |
["Study", "of", "BMN", "110" ...]["it", "is", "certainly" ...]... |
Для этого сочетания контекста и ввода навык выполняется один раз для каждого нормализованного изображения: один раз и "/document/normalized_images/0" один раз."/document/normalized_images/1" Два входных значения, соответствующих каждому выполнению навыка, подробно описаны в столбце значений.
При перечислении массива в контексте все выходные данные навыка также будут добавлены в документ в качестве обогащения контекста.
В приведенном выше примере выходные данные с именем "out" имеют свои значения для каждого выполнения, добавленного в документ соответственно в разделе "/document/normalized_images/0/out" и "/document/normalized_images/1/out".
Литеральные значения
Входные данные навыка могут принимать литеральные значения в качестве входных данных вместо динамических значений, запрашиваемых из существующего документа. Это можно сделать, префиксируя значение с знаком равенства. Значения могут быть числами, строками или логическими значениями.
Строковые значения могут быть заключены в одинарные ' или двойные " кавычки.
| Expression | Значение |
|---|---|
=42 |
42 |
=2.45E-4 |
0.000245 |
="some string" |
"some string" |
='some other string' |
"some other string" |
="unicod\u0065" |
"unicode" |
=false |
false |
В массивах строк
Если для определенного ввода навыка требуется массив данных, но данные представлены как одно значение в данный момент или необходимо объединить несколько разных отдельных значений в поле массива, то можно создать встроенное значение массива как часть выражения ввода навыка, упаковав разделенный запятыми список выражений в скобках ([ и ]). Значение массива может быть сочетанием путей выражений или литеральных значений по мере необходимости. Вы также можете создать вложенные массивы в массивах таким образом.
| Expression | Значение |
|---|---|
=['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", "Синдром"]] |
Если у навыка есть контекст, который объясняет выполнение навыка на входные данные массива (то есть как это означает, что "context": "/document/pages/*" навык выполняется один раз на страницу) pagesзатем передает это значение как выражение в качестве входных данных в массив строк использует одно из этих значений одновременно.
Пример с нашим примером обогащенных данных, если ваш навык context является /document/merged_content/keyphrases/* , а затем вы создаете встроенный массив следующего =['key phrase', $(/document/merged_content/keyphrases/*)] на входе этого навыка, то навык выполняется три раза, один раз со значением ["ключевой фразы", "Исследование BMN"], другой со значением ["ключевой фразы", "Синдром"] и, наконец, со значением ["ключевой фразы", "Педиатрические пациенты"]. Значение литерала "ключевой фразы" остается одинаковым каждый раз, но значение пути выражения изменяется при каждом выполнении навыка.
Составные выражения
Можно объединить значения с помощью унарных, двоичных и тернарных операторов.
Операторы могут объединять литеральные значения и значения, полученные из оценки пути.
При использовании внутри выражения пути должны быть заключены между "$(" и ")".
Логическое значение не '!'
| Expression | Значение |
|---|---|
=!false |
true |
Отрицательная '-'
| Expression | Значение |
|---|---|
=-42 |
-42 |
=-$(/document/merged_content/entities/0/offset) |
-9 |
Сложение '+'
| Expression | Значение |
|---|---|
=2+2 |
4 |
=2+$(/document/merged_content/entities/0/offset) |
11 |
Вычитание '-'
| Expression | Значение |
|---|---|
=2-1 |
1 |
=$(/document/merged_content/entities/0/offset)-2 |
7 |
Умножение '*'
| Expression | Значение |
|---|---|
=2*3 |
6 |
=$(/document/merged_content/entities/0/offset)*2 |
18 |
Деление '/'
| Expression | Значение |
|---|---|
=3/2 |
1.5 |
=$(/document/merged_content/entities/0/offset)/3 |
3 |
По модулю '%'
| Expression | Значение |
|---|---|
=15%4 |
3 |
=$(/document/merged_content/entities/0/offset)%2 |
1 |
Меньше, чем или равно, больше и больше или равно '<' '<=' '>' '>='
| Expression | Значение |
|---|---|
=15<4 |
false |
=4<=4 |
true |
=15>4 |
true |
=1>=2 |
false |
Равенство и неравенство '==' '!='
| Expression | Значение |
|---|---|
=15==4 |
false |
=4==4 |
true |
=15!=4 |
true |
=1!=1 |
false |
Логические операции, а также и монопольные или '&&' '||' эксклюзивные '^'
| Expression | Значение |
|---|---|
=true&&true |
true |
=true&&false |
false |
=true||true |
true |
=true||false |
true |
=false||false |
false |
=true^false |
true |
=true^true |
false |
Оператор Ternary '?:'
Можно дать входные значения, основанные на оценке логического выражения с помощью тернарного оператора.
| Expression | Значение |
|---|---|
=true?"true":"false" |
"true" |
=$(/document/merged_content/entities/0/offset)==9?"nine":"not nine" |
"nine" |
Круглые скобки и приоритет оператора
Операторы оцениваются с приоритетами, которые соответствуют обычным соглашениям: унарные операторы, а затем умножение, деление и модуло, а затем сложение и вычитание, а затем сравнение, а затем равенство, а затем логические операторы. Также применяются обычные правила ассоциативности.
Круглые скобки можно использовать для изменения или диамбигуации порядка оценки.
| Expression | Значение |
|---|---|
=3*2+5 |
11 |
=3*(2+5) |
21 |