Contexto de aptitud y lenguaje de anotación de entradas

  • Artículo

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 y 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 ejecutará 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" tendrá 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 Value
=42 42
=2.45E-4 0.000245
="some string" "some string"
='some other string' "some other string"
="unicod\u0065" "unicode"
=false false

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, mayor que y mayor o igual que '<''<=''>''>='

Expresión Value
=15<4 false
=4<=4 true
=15>4 true
=1>=2 false

Igualdad y no igualdad '==''!='

Expresión Value
=15==4 false
=4==4 true
=15!=4 true
=1!=1 false

Operaciones lógicas y, o y 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

Consulte también