Contexto de habilidades e idioma da anotação de entrada

  • Artigo

Este artigo é a documentação de referência para o contexto de habilidade e a sintaxe de entrada. É uma descrição completa da linguagem de expressão usada para construir caminhos para nós em um documento enriquecido.

As habilidades da IA do Azure Search podem usar e enriquecer os dados provenientes da fonte de dados e da saída de outras habilidades. O conjunto de trabalho de dados que representa o estado atual do trabalho do indexador no documento atual começa com os dados brutos sendo recebidos da fonte de dados e é enriquecido progressivamente com os dados de saída de cada iteração de habilidade. Esses dados são organizados internamente em uma estrutura do tipo árvore que pode ser consultada para ser usada como entradas de habilidades ou para serem adicionados ao índice. Os nós da árvore podem ser valores simples, como cadeias de caracteres e números, matrizes ou objetos complexos e até arquivos binários. Até mesmo valores simples podem ser enriquecidos com informações estruturadas adicionais. Por exemplo, uma cadeia de caracteres pode ser anotada com informações adicionais armazenadas abaixo dela na árvore de enriquecimento. As expressões usadas para consultar essa estrutura interna usam uma sintaxe sofisticada que é detalhada neste artigo. A estrutura de dados enriquecida pode ser inspecionada nas sessões de depuração. Expressões que consultam a estrutura também podem ser testadas nas sessões de depuração.

No artigo, usaremos os dados enriquecidos a seguir como exemplo. Esses dados são típicos do tipo de estrutura que você obterá ao enriquecer um documento usando um conjunto de habilidades com o OCR, a extração de frases-chave, a tradução de texto, a detecção de idioma, as habilidades de reconhecimento de entidade e uma habilidade personalizada do gerador de token.

Caminho Valor
document
 merged_content "Estudo do BMN 110 em pacientes pediátricos"…
  keyphrases
   [0] "Estudo do BMN"
   [1] "Síndrome"
   [2] "Pacientes pediátricos"
   ...
  locations
   [0] "IVA"
  translated_text "Étude de BMN 110 chez les patients pédiatriques"…
  entities
   [0]
    category "Organização"
    subcategory null
    confidenceScore 0,72
    length 3
    offset 9
    text "BMN"
   ...
  organizations
   [0] "BMN"
  language "en"
 normalized_images
  [0]
   layoutText ...
   text
    words
     [0] "Estudo"
     [1] "do"
     [2] "BMN"
     [3] "110"
     ...
  [1]
   layoutText ...
   text
    words
     [0] "it"
     [1] "é"
     [2] "certamente"
     ...
    ...
  ...

Raiz do documento

Todos os dados estão sob um elemento raiz, para o qual o caminho é "/document". O elemento raiz é o contexto padrão para as habilidades.

Caminhos simples

Os caminhos simples por meio do documento enriquecido interno podem ser expressos com tokens simples separados por barras. Essa sintaxe é semelhante à especificação do Ponteiro JSON.

Propriedades de objeto

As propriedades de nós que representam objetos adicionam valores à árvore sob o nome da propriedade. Esses valores podem ser obtidos pela adição do nome da propriedade como um token separado por uma barra:

Expression Valor
/document/merged_content/language "en"

Os tokens de nomes da propriedade diferenciam maiúsculas de minúsculas.

Índice de item de matriz

Os elementos específicos de uma matriz podem ser referenciados usando o índice numérico como um nome de propriedade:

Expression Valor
/document/merged_content/keyphrases/1 "Syndrome"
/document/merged_content/entities/0/text "BMN"

Sequências de escape

Há dois caracteres que têm significado especial e precisarão ser seguidos por caracteres de escape se aparecerem em uma expressão e precisarem ser interpretados no estado em que se encontram em vez do significado especial: '/' e '~'. Esses caracteres precisam ser seguidos por caracteres de escape como '~0' e '~1', respectivamente.

Enumeração de matriz

Uma matriz de valores pode ser obtida com o token '*':

Expression Valor
/document/normalized_images/0/text/words/* ["Study", "of", "BMN", "110" ...]

O token '*' não precisa estar no final do caminho. É possível enumerar todos os nós correspondentes a um caminho com uma estrela no meio ou com várias estrelas:

Expression Valor
/document/normalized_images/*/text/words/* ["Study", "of", "BMN", "110" ... "it", "is", "certainly" ...]

Este exemplo retorna uma lista simples de todos os nós correspondentes.

É possível manter mais estrutura e obter uma matriz separada para as palavras de cada página usando um token '#' em vez do segundo token '*':

Expression Valor
/document/normalized_images/*/text/words/# [["Study", "of", "BMN", "110" ...], ["it", "is", "certainly" ...] ...]

O token '#' expressa que a matriz deve ser tratada como um só valor em vez de ser enumerada.

Como enumerar matrizes no contexto

Geralmente, é útil processar cada elemento de uma matriz isoladamente e ter um conjunto diferente de entradas e saídas de habilidades para cada um. Isso pode ser feito com a definição do contexto da habilidade como uma enumeração em vez do "/document" padrão.

No exemplo a seguir, usamos uma das expressões de entrada usadas antes, mas com um contexto diferente que altera o valor resultante.

Context Expression Valores
/document/normalized_images/* /document/normalized_images/*/text/words/* ["Study", "of", "BMN", "110" ...]
["it", "is", "certainly" ...]
...

Para essa combinação de contexto e entrada, a habilidade será executada uma vez para cada imagem normalizada: uma vez para "/document/normalized_images/0" e outra para "/document/normalized_images/1". Os dois valores de entrada correspondentes a cada execução de habilidade são detalhados na coluna de valores.

Ao enumerar uma matriz no contexto, todas as saídas que a habilidade produz também serão adicionadas ao documento como enriquecimentos do contexto. No exemplo acima, uma saída chamada "out" terá os valores para cada execução adicionados ao documento em "/document/normalized_images/0/out" e "/document/normalized_images/1/out", respectivamente.

Valores literais

As entradas de habilidades podem usar valores literais como entradas em vez de valores dinâmicos consultados no documento existente. Isso pode ser feito com o uso do sinal de igual como prefixo no valor. Os valores podem ser números, cadeias de caracteres ou boolianos. Os valores de cadeias de caracteres podem ser colocados entre aspas simples ' ou duplas ".

Expression Valor
=42 42
=2.45E-4 0.000245
="some string" "some string"
='some other string' "some other string"
="unicod\u0065" "unicode"
=false false

Expressões compostas

É possível combinar valores usando operadores unários, binários e ternários. Os operadores podem combinar valores literais e valores resultantes da avaliação do caminho. Quando usados dentro de uma expressão, os caminhos devem ser incluídos entre "$(" e ")".

Booliano não '!'

Expression Valor
=!false true

Negativo '-'

Expression Valor
=-42 -42
=-$(/document/merged_content/entities/0/offset) -9

Adição '+'

Expression Valor
=2+2 4
=2+$(/document/merged_content/entities/0/offset) 11

Subtração '-'

Expression Valor
=2-1 1
=$(/document/merged_content/entities/0/offset)-2 7

Multiplicação '*'

Expression Valor
=2*3 6
=$(/document/merged_content/entities/0/offset)*2 18

Divisão '/'

Expression Valor
=3/2 1.5
=$(/document/merged_content/entities/0/offset)/3 3

Módulo '%'

Expression Valor
=15%4 3
=$(/document/merged_content/entities/0/offset)%2 1

Menor que, menor que ou igual a, maior que e maior que ou igual a '<''<=''>''>='

Expression Valor
=15<4 false
=4<=4 true
=15>4 true
=1>=2 false

Igualdade e não igualdade '==''!='

Expression Valor
=15==4 false
=4==4 true
=15!=4 true
=1!=1 false

Operações lógicas e, ou e ou exclusivo '&&''||''^'

Expression Valor
=true&&true true
=true&&false false
=true||true true
=true||false true
=false||false false
=true^false true
=true^true false

Operador ternário '?:'

É possível dar a uma entrada valores diferentes com base na avaliação de uma expressão booliana usando o operador ternário.

Expression Valor
=true?"true":"false" "true"
=$(/document/merged_content/entities/0/offset)==9?"nine":"not nine" "nine"

Parênteses e prioridade do operador

Os operadores são avaliados com prioridades que correspondem às convenções usuais: operadores unários; depois, multiplicação, divisão e módulo; em seguida, adição e subtração; depois, comparação; em seguida, igualdade e, por fim, operadores lógicos. As regras de associatividade comuns também se aplicam.

Os parênteses podem ser usados para alterar ou remover a ambiguidade da ordem de avaliação.

Expression Valor
=3*2+5 11
=3*(2+5) 21

Confira também