Contesto di competenza e linguaggio di annotazione di input
Questo articolo è la documentazione di riferimento per il contesto di competenza e la sintassi di input. È una descrizione completa delle espressioni di linguaggio usate per costruire percorsi ai nodi in un documento arricchito.
Le competenze di Azure AI Search possono usare e arricchire i dati provenienti dall'origine dati e dall'output di altre competenze. Il working set di dati che rappresenta lo stato corrente dell'indicizzatore per il documento corrente inizia dai dati non elaborati provenienti dall'origine dati e viene progressivamente arricchito con i dati di output di ogni iterazione delle competenze. Tali dati sono organizzati internamente in una sorta di struttura ad albero su cui è possibile eseguire query che possono essere usate come input di competenza o da aggiungere all'indice. I nodi nell'albero possono essere valori semplici, ad esempio stringhe e numeri, matrici o oggetti complessi e persino file binari. Anche i valori semplici possono essere arricchiti con informazioni strutturate aggiuntive. Ad esempio, una stringa può essere annotata con informazioni aggiuntive archiviate sotto di essa nell'albero di arricchimento. Le espressioni usate per eseguire query sulla struttura interna usano una sintassi avanzata descritta in questo articolo. La struttura dei dati arricchiti può essere esaminata da sessioni di debug. Le espressioni che eseguono query sulla struttura possono anche essere testate da sessioni di debug.
Nell'articolo verranno usati i dati arricchiti seguenti come esempio. Questi dati sono tipici del tipo di struttura che si otterrebbe arricchendo un documento tramite un set di competenze con OCR, estrazione di frasi chiave, traduzione testuale, rilevamento della lingua e competenze di riconoscimento delle entità, nonché una competenza tokenizer personalizzata.
| Percorso | Valore |
|---|---|
document |
|
merged_content |
"Studio del BMN 110 nei pazienti pediatrici"... |
keyphrases |
|
[0] |
"Studio del BMN" |
[1] |
“Sindrome” |
[2] |
"Pazienti pediatrici" |
| ... | |
locations |
|
[0] |
"IVA" |
translated_text |
"Étude de BMN 110 chez les patients pédiatriques"... |
entities |
|
[0] |
|
category |
"Organizzazione" |
subcategory |
null |
confidenceScore |
0,72 |
length |
3 |
offset |
9 |
text |
"BMN" |
| ... | |
organizations |
|
[0] |
"BMN" |
language |
"en" |
normalized_images |
|
[0] |
|
layoutText |
... |
text |
|
words |
|
[0] |
"Studio" |
[1] |
"di" |
[2] |
"BMN" |
[3] |
”110” |
| ... | |
[1] |
|
layoutText |
... |
text |
|
words |
|
[0] |
"it" |
[1] |
"is" |
[2] |
"certamente" |
| ... | |
| ... | |
| ... |
Radice documento
Tutti i dati si trovano in un elemento radice, il cui percorso è "/document". L'elemento radice è il contesto predefinito per le competenze.
Percorsi semplici
I percorsi semplici attraverso il documento arricchito interno possono essere espressi con token semplici separati da barre. Questa sintassi è simile alla specifica del puntatore JSON.
Proprietà degli oggetti
Le proprietà dei nodi che rappresentano oggetti aggiungono i relativi valori all'albero sotto il nome della proprietà. Questi valori possono essere ottenuti aggiungendo il nome della proprietà come token separato da una barra:
| Espressione | Valore |
|---|---|
/document/merged_content/language |
"en" |
I token dei nomi di proprietà fanno distinzione tra maiuscole e minuscole.
Indice dell'elemento della matrice
È possibile fare riferimento a elementi specifici di una matrice usando il relativo indice numerico, ad esempio un nome di proprietà:
| Espressione | Valore |
|---|---|
/document/merged_content/keyphrases/1 |
"Syndrome" |
/document/merged_content/entities/0/text |
"BMN" |
Sequenze di escape
Esistono due caratteri che hanno un significato particolare e, se appaiono in un’espressione, devono essere evitati e interpretati così come sono anziché per il loro significato particolare: '/' e '~'.
Tali caratteri devono essere preceduti rispettivamente da '~0' e '~1'.
Enumerazione matrice
È possibile ottenere una matrice di valori usando il token '*':
| Espressione | Valore |
|---|---|
/document/normalized_images/0/text/words/* |
["Study", "of", "BMN", "110" ...] |
Il token '*' non deve trovarsi alla fine del percorso. È possibile enumerare tutti i nodi corrispondenti a un percorso con una stella al centro o con più stelle:
| Espressione | Valore |
|---|---|
/document/normalized_images/*/text/words/* |
["Study", "of", "BMN", "110" ... "it", "is", "certainly" ...] |
In questo esempio viene restituito un elenco semplice di tutti i nodi corrispondenti.
È possibile mantenere più struttura e ottenere una matrice diversa per le parole di ogni pagina usando un token '#' anziché il secondo token '*':
| Espressione | Valore |
|---|---|
/document/normalized_images/*/text/words/# |
[["Study", "of", "BMN", "110" ...], ["it", "is", "certainly" ...] ...] |
Il token '#' indica che la matrice deve essere considerata come un singolo valore anziché essere enumerata.
Enumerazione di matrici nel contesto
È spesso utile elaborare ogni elemento di una matrice in isolamento e avere un set diverso di input e output delle competenze per ciascuno di essi.
Questa operazione può essere eseguita impostando il contesto della competenza su un'enumerazione anziché sull’impostazione predefinita "/document".
Nell'esempio seguente viene usata una delle espressioni di input usate in precedenza, ma con un contesto diverso che ne modifica il valore risultante.
| Contesto | Espressione | Valori |
|---|---|---|
/document/normalized_images/* |
/document/normalized_images/*/text/words/* |
["Study", "of", "BMN", "110" ...]["it", "is", "certainly" ...]... |
Per questa combinazione di contesto e input, la competenza viene eseguita una volta per ogni immagine normalizzata: una volta per "/document/normalized_images/0" e una per "/document/normalized_images/1". I due valori di input corrispondenti a ogni esecuzione della competenza sono descritti in dettaglio nella colonna dei valori.
Quando si enumera una matrice nel contesto, qualsiasi output prodotto dalla competenza verrà aggiunto anche al documento come arricchimento del contesto.
Nell'esempio precedente, un output denominato "out" ha i relativi valori per ogni esecuzione aggiunta al documento rispettivamente in "/document/normalized_images/0/out" e "/document/normalized_images/1/out".
Valori letterali
Gli input delle competenze possono accettare come input valori letterali anziché valori dinamici sottoposti a query dal documento esistente. A tale scopo, anteporre al valore un segno di uguale. I valori possono essere numeri, stringhe o booleani.
I valori stringa possono essere racchiusi tra virgolette singole ' o doppie ".
| Espressione | Valore |
|---|---|
=42 |
42 |
=2.45E-4 |
0.000245 |
="some string" |
"some string" |
='some other string' |
"some other string" |
="unicod\u0065" |
"unicode" |
=false |
false |
In matrici di righe
Se un determinato input di competenza richiede una matrice di dati, ma i dati sono rappresentati come un singolo valore o è necessario combinare più valori singoli diversi in un campo di matrice, è possibile creare un valore di matrice inline come parte di un'espressione di input della competenza eseguendo il wrapping di un elenco delimitato da virgole di espressioni tra parentesi quadre ([ e ]). Il valore della matrice può essere una combinazione di percorsi di espressione o valori letterali in base alle esigenze. È anche possibile creare matrici annidate all'interno di matrici in questo modo.
| Espressione | Valore |
|---|---|
=['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"]] |
Se la competenza ha un contesto che spiega per eseguire la competenza per ogni input di una matrice (ovvero, come "context": "/document/pages/*" significa che la competenza viene eseguita una volta per "pagina" in pages), il passaggio di tale valore come espressione come input a una matrice di righe usa uno di questi valori alla volta.
Per un esempio con dati arricchiti campione, se la competenza context è /document/merged_content/keyphrases/* e quindi si crea una matrice inline del seguente =['key phrase', $(/document/merged_content/keyphrases/*)] su un input di tale competenza, la competenza viene eseguita tre volte, una volta con un valore di ["key phrase", "Study of BMN"], un altro con un valore ["key phrase", "Syndrome"] e infine con un valore di ["key phrase", "Pediatric Patients"]. Il valore letterale "key phrase" rimane invariato ogni volta, ma il valore del percorso dell'espressione cambia con ogni esecuzione della competenza.
Espressioni composite
È possibile combinare valori usando operatori unari, binari e ternari.
Gli operatori possono combinare valori letterali e valori risultanti dalla valutazione del percorso.
Se usati all'interno di un'espressione, i percorsi devono essere racchiusi tra "$(" e ")".
Valore booleano non '!'
| Espressione | Valore |
|---|---|
=!false |
true |
Negativo '-'
| Espressione | Valore |
|---|---|
=-42 |
-42 |
=-$(/document/merged_content/entities/0/offset) |
-9 |
Addizione '+'
| Espressione | Valore |
|---|---|
=2+2 |
4 |
=2+$(/document/merged_content/entities/0/offset) |
11 |
Sottrazione '-'
| Espressione | Valore |
|---|---|
=2-1 |
1 |
=$(/document/merged_content/entities/0/offset)-2 |
7 |
Moltiplicazione '*'
| Espressione | Valore |
|---|---|
=2*3 |
6 |
=$(/document/merged_content/entities/0/offset)*2 |
18 |
Divisione '/'
| Espressione | Valore |
|---|---|
=3/2 |
1.5 |
=$(/document/merged_content/entities/0/offset)/3 |
3 |
Modulo '%'
| Espressione | Valore |
|---|---|
=15%4 |
3 |
=$(/document/merged_content/entities/0/offset)%2 |
1 |
Minore di, minore o uguale, maggiore di e maggiore o uguale a '<' '<=' '>' '>='
| Espressione | Valore |
|---|---|
=15<4 |
false |
=4<=4 |
true |
=15>4 |
true |
=1>=2 |
false |
Uguaglianza e disuguaglianza '==' '!='
| Espressione | Valore |
|---|---|
=15==4 |
false |
=4==4 |
true |
=15!=4 |
true |
=1!=1 |
false |
Operazioni logiche e, o ed esclusive o '&&' '||' '^'
| Espressione | Valore |
|---|---|
=true&&true |
true |
=true&&false |
false |
=true||true |
true |
=true||false |
true |
=false||false |
false |
=true^false |
true |
=true^true |
false |
Operatore ternario '?:'
È possibile assegnare un input a valori diversi in base alla valutazione di un'espressione booleana usando l'operatore ternario.
| Espressione | Valore |
|---|---|
=true?"true":"false" |
"true" |
=$(/document/merged_content/entities/0/offset)==9?"nine":"not nine" |
"nine" |
Parentesi e priorità dell'operatore
Gli operatori vengono valutati con priorità come da consuete convenzioni: operatori unari, quindi moltiplicazione, divisione e modulo, addizione e sottrazione, quindi confronto, uguaglianza e quindi operatori logici. Si applicano anche le normali regole di associatività.
Le parentesi possono essere usate per modificare o disambiguare l'ordine di valutazione.
| Espressione | Valore |
|---|---|
=3*2+5 |
11 |
=3*(2+5) |
21 |