スキル コンテキストと入力注釈言語
この記事は、スキル コンテキストと入力構文の参照ドキュメントです。 エンリッチされたドキュメント内のノードへのパスを構築するために使用される式言語について詳しく説明します。
Azure AI Search のスキルは、データ ソースや他のスキルの出力から取得したデータをエンリッチするのに使用することができます。 現在のドキュメントのインデクサー作業の現在の状態を表すデータ ワーキング セットは、データ ソースからの生データから始まり、各スキル イテレーションの出力データで段階的にエンリッチされます。 そのデータは、スキル入力として使用したり、インデックスに追加したりするためにクエリを実行できるツリーのような構造で内部的編成されています。 ツリー内のノードには、文字列、数値、配列、複合オブジェクト、バイナリ ファイルなどの単純な値を指定できます。 単純な値でも、構造化情報を追加してエンリッチすることができます。 たとえば、エンリッチメント ツリーの下に格納される追加情報で文字列に注釈付けすることができます。 その内部構造のクエリに使用される式には、この記事で詳しく説明されている豊富な構文が使用されます。 エンリッチされたデータ構造は、デバッグ セッションから検査することができます。 構造体のクエリを実行する式は、デバッグ セッションからテストすることもできます。
この記事全体で、次のエンリッチされたデータを例として使用します。 このデータは、カスタム トークナイザー スキルに加え、OCR、キー フレーズ抽出、テキスト翻訳、言語検出、エンティティ認識スキルを使用してドキュメントをエンリッチするときに得られる構造の種類として一般的です。
| Path | 値 |
|---|---|
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 |
"Étude de BMN 110 chez les patients pédiatriques"... |
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] |
"Study" |
[1] |
"of" |
[2] |
"BMN" |
[3] |
"110" |
| ... | |
[1] |
|
layoutText |
... |
text |
|
words |
|
[0] |
"it" |
[1] |
"is" |
[2] |
"certainly" |
| ... | |
| ... | |
| ... |
ドキュメントのルート
すべてのデータは、パスが "/document" である 1 つのルート要素の下に置かれます。 ルート要素は、スキルの既定のコンテキストです。
単純なパス
内部のエンリッチされたドキュメントの単純なパスは、スラッシュで区切られた単純なトークンで表現することができます。 この構文は、JSON ポインターの仕様に似ています。
オブジェクトのプロパティ
オブジェクトを表すノードのプロパティは、プロパティの名前の下のツリーに値を追加します。 これらの値は、スラッシュで区切られたトークンとしてプロパティ名を追加することで取得できます。
| Expression | 値 |
|---|---|
/document/merged_content/language |
"en" |
プロパティ名のトークンでは、大文字と小文字が区別されます。
配列項目インデックス
配列の特定の要素は、プロパティ名のような数値インデックスを使用して参照できます。
| Expression | 値 |
|---|---|
/document/merged_content/keyphrases/1 |
"Syndrome" |
/document/merged_content/entities/0/text |
"BMN" |
エスケープ シーケンス
特別な意味を持つ文字として '/' と '~' の 2 つがあります。これらが式に現れる場合はエスケープする必要があり、その特別な意味ではなく、そのまま解釈する必要があります。
これらの文字は、'~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" ...] |
この例では、一致するすべてのノードの単純なリストが返されます。
2 番目のトークン '*' の代わりに '#' トークンを使用することで、より構造を維持したまま、各ページの単語に個別の配列を取得することができます。
| Expression | 値 |
|---|---|
/document/normalized_images/*/text/words/# |
[["Study", "of", "BMN", "110" ...], ["it", "is", "certainly" ...] ...] |
'#' トークンは、配列が、列挙ではなく、1 つの値として扱う必要があるということを表しています。
コンテキストでの配列の列挙
多くの場合、配列の各要素を個別に処理し、それぞれに異なるスキルの入力と出力のセットを持たせることが有用です。
これを行うには、スキルのコンテキストを既定の "/document" ではなく、列挙型に設定します。
次の例では、先ほど使用した入力式の 1 つを使用しますが、別のコンテキストを使用することで、結果の値が異なります。
| コンテキスト | Expression | 値 |
|---|---|---|
/document/normalized_images/* |
/document/normalized_images/*/text/words/* |
["Study", "of", "BMN", "110" ...]["it", "is", "certainly" ...]... |
このコンテキストと入力の組み合わせの場合、スキルは正規化された画像ごとに ("/document/normalized_images/0" に対して 1 回、"/document/normalized_images/1" に対して 1 回) 実行されます。 各スキルの実行に対応する 2 つの入力値の詳細については、values 列を参照してください。
コンテキストで配列を列挙する場合、スキルによって生成される出力は、コンテキストのエンリッチメントとしてドキュメントにも追加されます。
上の例では、"out" という名前の出力が、ドキュメントに追加された各実行ごとの値を "/document/normalized_images/0/out" と "/document/normalized_images/1/out" の下にそれぞれ保持します。
リテラル値
スキル入力は、既存のドキュメントからクエリを実行する動的な値ではなく、リテラル値を入力として受け取ることができます。 これは、値の前に等号を付けることで実現できます。 値には、数値、文字列、またはブール値を指定できます。
文字列の値は、一重引用符 ' または二重引用符 " で囲むことができます。
| Expression | Value |
|---|---|
=42 |
42 |
=2.45E-4 |
0.000245 |
="some string" |
"some string" |
='some other string' |
"some other string" |
="unicod\u0065" |
"unicode" |
=false |
false |
インライン配列
特定のスキル入力でデータの配列が必要であるにも関わらずデータが現在単一の値として表されている場合、または複数の異なる単一の値を配列フィールドへとまとめる必要がある場合は、かっこ ([ と ]) 内にコンマで区切られた式のリストをラップすることで、スキル入力式の一部として配列値をインラインで作成できます。 配列値は、必要に応じて式のパスまたはリテラル値の組み合わせにすることができます。 この方法で、配列内に入れ子になった配列を作成することもできます。
| Expression | Value |
|---|---|
=['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"]] |
スキルに配列入力ごとにスキルを実行することを説明するコンテキストがある場合 ("context": "/document/pages/*" は、そのようにしてスキルが pages の "page" ごとに実行されることを表します)、その式としての値をインライン配列への入力として渡すと、それらの値は一度に 1 つずつ使用されます。
ここでのエンリッチされたサンプル データの例では、スキルの context が /document/merged_content/keyphrases/* であり、そのスキルの入力で次の =['key phrase', $(/document/merged_content/keyphrases/*)] のインライン配列を作成した場合、スキルは 3 回実行されます。1 回は ["key phrase", "Study of BMN"] という値で、次の 1 回は ["key phrase", "Syndrome"] という値で、最後は ["key phrase", "Pediatric Patients"] という値でです。 "key phrase" というリテラルの値は毎回同じままですが、式のパスの値はスキルの実行ごとに変化します。
複合式
単項演算子、二項演算子、三項演算子を使用して、値を結合することができます。
演算子は、リテラル値とパス評価の結果の値を結合することができます。
式内で使用する場合、パスを "$(" と ")" で囲む必要があります。
ブール型演算子 not '!'
| 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 | Value |
|---|---|
=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 |
三項演算子 '?:'
三項演算子を使用したブール式の評価に基づいて、異なる入力値を指定することができます。
| 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 |