Contexto de aptitud y lenguaje de anotación de entradas
Este artículo es la documentación de referencia del contexto de aptitud y la sintaxis de entrada. Es una descripción completa del lenguaje de expresiones que se usa para construir rutas de acceso a nodos en un documento enriquecido.
Las aptitudes de Azure AI Search pueden usar y enriquecer los datos procedentes del origen de datos y de la salida de otras aptitudes. El conjunto de datos de trabajo que representa el estado actual del trabajo del indexador para el documento actual parte de los datos sin procesar procedentes del origen de datos y se enriquece progresivamente con los datos de salida de cada iteración de aptitud. Estos datos se organizan internamente en una estructura similar a un árbol que se puede consultar para su uso como entradas de aptitud o para agregarse al índice. Los nodos del árbol pueden ser valores simples, como cadenas y números, matrices u objetos complejos e incluso archivos binarios. Incluso los valores simples se pueden enriquecer con información estructurada adicional. Por ejemplo, una cadena se puede anotar con información adicional que se almacena debajo de ella en el árbol de enriquecimiento. Las expresiones usadas para consultar esa estructura interna emplean una sintaxis enriquecida que se detalla en este artículo. La estructura de datos enriquecida se puede inspeccionar desde sesiones de depuración. Las expresiones que consultan la estructura también se pueden probar desde sesiones de depuración.
A lo largo del artículo, se usarán los siguientes datos enriquecidos como ejemplo. Estos datos son típicos del tipo de estructura que obtendría al enriquecer un documento mediante un conjunto de aptitudes con OCR, extracción de frases clave, traducción de texto, detección de idioma, reconocimiento de entidades, así como una aptitud de tokenizador personalizado.
| Ruta de acceso | Value |
|---|---|
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" |
| ... | |
| ... | |
| ... |
Raíz del documento
Todos los datos están en un elemento raíz, para el que la ruta de acceso es "/document". El elemento raíz es el contexto predeterminado de las aptitudes.
Rutas de acceso sencillas
Las rutas de acceso sencillas a través del documento enriquecido interno se pueden expresar con tokens simples separados por barras diagonales. Esta sintaxis es similar a la especificación del puntero JSON.
Propiedades de objeto
Las propiedades de los nodos que representan objetos agregan sus valores al árbol bajo el nombre de la propiedad. Estos valores se pueden obtener anexando el nombre de propiedad como un token separado por una barra diagonal:
| Expresión | Value |
|---|---|
/document/merged_content/language |
"en" |
Los tokens de nombre de propiedad distinguen mayúsculas de minúsculas.
Índice de elementos de matriz
Se puede hacer referencia a elementos específicos de una matriz mediante su índice numérico, como un nombre de propiedad:
| Expresión | Value |
|---|---|
/document/merged_content/keyphrases/1 |
"Syndrome" |
/document/merged_content/entities/0/text |
"BMN" |
Secuencias de escape
Hay dos caracteres que tienen un significado especial y deben escaparse si aparecen en una expresión y que se deben interpretar tal cual en lugar de con su significado especial: '/' y '~'.
Estos caracteres deben escaparse respectivamente, como '~0' y '~1'.
Enumeración de matriz
Se puede obtener una matriz de valores mediante el token '*':
| Expresión | Value |
|---|---|
/document/normalized_images/0/text/words/* |
["Study", "of", "BMN", "110" ...] |
El token '*' no tiene que estar al final de la ruta de acceso. Es posible enumerar todos los nodos que coinciden con una ruta de acceso con una estrella en el centro o con varias estrellas:
| Expresión | Value |
|---|---|
/document/normalized_images/*/text/words/* |
["Study", "of", "BMN", "110" ... "it", "is", "certainly" ...] |
En este ejemplo se devuelve una lista plana de todos los nodos coincidentes.
Es posible mantener más estructura y obtener una matriz independiente para las palabras de cada página mediante un token '#' en lugar del segundo token '*':
| Expresión | Value |
|---|---|
/document/normalized_images/*/text/words/# |
[["Study", "of", "BMN", "110" ...], ["it", "is", "certainly" ...] ...] |
El token '#' expresa que la matriz debe tratarse como un valor único en lugar de enumerarse.
Enumeración de matrices en contexto
A menudo resulta útil procesar cada elemento de una matriz de forma aislada y tener un conjunto diferente de entradas y salidas de aptitudes para cada uno.
Esto se puede hacer estableciendo el contexto de la aptitud en una enumeración en lugar del valor de "/document" predeterminado.
En el ejemplo siguiente, se usa una de las expresiones de entrada que se utilizó antes, pero con un contexto diferente que cambia el valor resultante.
| Context | Expresión | Valores |
|---|---|---|
/document/normalized_images/* |
/document/normalized_images/*/text/words/* |
["Study", "of", "BMN", "110" ...]["it", "is", "certainly" ...]... |
Para esta combinación de contexto y entrada, la aptitud se ejecuta una vez para cada imagen normalizada: una para "/document/normalized_images/0" y otra para "/document/normalized_images/1". Los dos valores de entrada correspondientes a cada ejecución de aptitud se detallan en la columna de valores.
Al enumerar una matriz en contexto, las salidas que genera la aptitud también se agregarán al documento como enriquecimientos del contexto.
En el ejemplo anterior, una salida denominada "out" tiene agregados sus valores de cada ejecución al documento respectivamente en "/document/normalized_images/0/out" y "/document/normalized_images/1/out".
Valores literales
Las entradas de aptitud pueden tomar valores literales como entradas en lugar de valores dinámicos que se consultan desde el documento existente. Esto se puede lograr anteponiendo al valor un signo igual. Los valores pueden ser números, cadenas o booleanos.
Los valores de cadena se pueden incluir entre comillas simples ' o dobles ".
| Expresión | Valor |
|---|---|
=42 |
42 |
=2.45E-4 |
0.000245 |
="some string" |
"some string" |
='some other string' |
"some other string" |
="unicod\u0065" |
"unicode" |
=false |
false |
Matrices de líneas
Si una determinada entrada de aptitud requiere una matriz de datos, pero los datos se representan como un solo valor actualmente o necesita combinar varios valores únicos diferentes en un campo de matriz, puede crear un valor de matriz insertado como parte de una expresión de entrada de aptitud ajustando una lista separada por comas de expresiones entre corchetes ([ y ]). El valor de matriz puede ser una combinación de rutas de acceso de expresión o valores literales según sea necesario. También puede crear matrices anidadas dentro de matrices de esta manera.
| Expresión | Valor |
|---|---|
=['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 aptitud tiene un contexto que explica cómo ejecutar la aptitud por una entrada de matriz (es decir, cómo "context": "/document/pages/*" significa que la aptitud se ejecuta una vez por "página" en pages) y luego pasa ese valor como expresión como entrada a una matriz de líneas usa uno de esos valores a la vez.
Para obtener un ejemplo con nuestros datos enriquecidos de ejemplo, si la context de su aptitud es /document/merged_content/keyphrases/* y, a continuación, crea una matriz insertada de los siguientes =['key phrase', $(/document/merged_content/keyphrases/*)] en una entrada de esa aptitud, la aptitud se ejecuta tres veces, una vez con un valor de ["key phrase", "Study of BMN"], otro con un valor de ["key phrase", "Syndrome"], y finalmente con un valor de ["key phrase", "Pediatric Patients"]. El valor literal de "key phrase" permanece igual cada vez, pero el valor de la ruta de acceso de expresión cambia con cada ejecución de aptitud.
Expresiones compuestas
Es posible combinar valores mediante operadores unarios, binarios y ternarios.
Los operadores pueden combinar valores literales y valores resultantes de la evaluación de la ruta de acceso.
Cuando se usan dentro de una expresión, las rutas de acceso deben incluirse entre "$(" y ")".
NOT booleano '!'
| Expresión | Value |
|---|---|
=!false |
true |
Negativo '-'
| Expresión | Value |
|---|---|
=-42 |
-42 |
=-$(/document/merged_content/entities/0/offset) |
-9 |
Suma '+'
| Expresión | Value |
|---|---|
=2+2 |
4 |
=2+$(/document/merged_content/entities/0/offset) |
11 |
Resta '-'
| Expresión | Value |
|---|---|
=2-1 |
1 |
=$(/document/merged_content/entities/0/offset)-2 |
7 |
Multiplicación '*'
| Expresión | Value |
|---|---|
=2*3 |
6 |
=$(/document/merged_content/entities/0/offset)*2 |
18 |
División '/'
| Expresión | Value |
|---|---|
=3/2 |
1.5 |
=$(/document/merged_content/entities/0/offset)/3 |
3 |
Módulo '%'
| Expresión | Value |
|---|---|
=15%4 |
3 |
=$(/document/merged_content/entities/0/offset)%2 |
1 |
Menor que, menor o igual que y mayor que o igual '<' '<=' '>' que '>='
| Expresión | Valor |
|---|---|
=15<4 |
false |
=4<=4 |
true |
=15>4 |
true |
=1>=2 |
false |
Igualdad y desigualdad '==' '!='
| Expresión | Value |
|---|---|
=15==4 |
false |
=4==4 |
true |
=15!=4 |
true |
=1!=1 |
false |
Operaciones lógicas, o, o exclusivas o '&&' '||' '^'
| Expresión | Value |
|---|---|
=true&&true |
true |
=true&&false |
false |
=true||true |
true |
=true||false |
true |
=false||false |
false |
=true^false |
true |
=true^true |
false |
Operador ternario '?:'
Es posible proporcionar a una entrada valores diferentes en función de la evaluación de una expresión booleana mediante el operador ternario.
| Expresión | Value |
|---|---|
=true?"true":"false" |
"true" |
=$(/document/merged_content/entities/0/offset)==9?"nine":"not nine" |
"nine" |
Paréntesis y prioridad del operador
Los operadores se evalúan con prioridades que coinciden con convenciones habituales: operadores unarios, multiplicación, división y módulo, suma y resta, luego comparación, después igualdad y operadores lógicos. También se aplican reglas de asociatividad habituales.
Se pueden usar paréntesis para cambiar o eliminar la ambigüedad del orden de evaluación.
| Expresión | Value |
|---|---|
=3*2+5 |
11 |
=3*(2+5) |
21 |