Contexto de habilidades e linguagem de anotação de entrada

Este artigo é a documentação de referência para contexto de habilidade e 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 do Azure AI 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 para o documento atual começa a partir dos dados brutos provenientes da fonte de dados e é progressivamente enriquecido com os dados de saída de cada iteração de habilidade. Esses dados são organizados internamente em uma estrutura semelhante a uma árvore que pode ser consultada para ser usada como entrada de habilidades ou para ser adicionada ao índice. Os nós na árvore podem ser valores simples, como cadeias de caracteres e números, matrizes ou objetos complexos e até mesmo arquivos binários. 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 rica que é detalhada neste artigo. A estrutura de dados enriquecida pode ser inspecionada a partir de sessões de depuração. As expressões que consultam a estrutura também podem ser testadas a partir de sessões de depuração.

Ao longo do artigo, usaremos os seguintes dados enriquecidos como exemplo. Esses dados são típicos do tipo de estrutura que você obteria ao enriquecer um documento usando um conjunto de habilidades com OCR, extração de frases-chave, tradução de texto, deteção de idioma e habilidades de reconhecimento de entidade, bem como uma habilidade de tokenizador personalizado.

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 habilidades.

Caminhos simples

Caminhos simples através do documento interno enriquecido podem ser expressos com fichas simples separadas por barras. Essa sintaxe é semelhante à especificação JSON Pointer.

Propriedades do objeto

As propriedades dos nós que representam objetos adicionam seus valores à árvore sob o nome da propriedade. Esses valores podem ser obtidos anexando o nome da propriedade como um token separado por uma barra:

Os tokens de nome de propriedade diferenciam maiúsculas de minúsculas.

Índice de itens de matriz

Elementos específicos de uma matriz podem ser referenciados usando seu índice numérico como um nome de propriedade:

Sequências de fuga

Há dois caracteres que têm um significado especial e precisam ser escapados se aparecerem em uma expressão e devem ser interpretados como estão em vez de como seu significado especial: '/' e '~'. Esses caracteres devem ser escapados, respectivamente, como '~0' e '~1'.

Enumeração de matriz

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

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

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:

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

Enumerando matrizes no contexto

Muitas vezes, é ú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 definindo o contexto da habilidade como uma enumeração em vez do padrão "/document".

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

Para essa combinação de contexto e entrada, a habilidade é executada uma vez para cada imagem normalizada: uma vez para "/document/normalized_images/0" e uma vez 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, quaisquer saídas que a habilidade produza também serão adicionadas ao documento como enriquecimento do contexto. No exemplo acima, uma saída nomeada "out" tem seus valores para cada execução adicionada ao documento respectivamente em "/document/normalized_images/0/out" e "/document/normalized_images/1/out".

Valores literais

As entradas de habilidade podem tomar valores literais como suas entradas, em vez de valores dinâmicos consultados a partir do documento existente. Isso pode ser conseguido prefixando o valor com um sinal de igual. Os valores podem ser números, strings ou booleanos. Os valores de cadeia de caracteres podem ser colocados entre aspas simples ' ou duplas " .

Matrizes em linha

Se uma determinada entrada de habilidade requer uma matriz de dados, mas os dados são representados como um único valor atualmente ou você precisa combinar vários valores únicos diferentes em um campo de matriz, então você pode criar um valor de matriz embutido como parte de uma expressão de entrada de habilidade quebrando uma lista separada por vírgulas de expressões entre colchetes ([ e ]). O valor da matriz pode ser uma combinação de caminhos de expressão ou valores literais, conforme necessário. Você também pode criar matrizes aninhadas dentro de matrizes dessa maneira.

Se a habilidade tiver um contexto que explique para executar a habilidade por uma entrada de matriz (ou seja, como "context": "/document/pages/*" significa que a habilidade é executada uma vez por "página" em pages), então passar esse valor como a expressão como entrada para uma matriz em linha usa um desses valores de cada vez.

Para um exemplo com nossos dados enriquecidos de amostra, se a sua habilidade context é /document/merged_content/keyphrases/* e, em seguida, você cria uma matriz embutida do seguinte =['key phrase', $(/document/merged_content/keyphrases/*)] em uma entrada dessa habilidade, então a habilidade é executada três vezes, uma com um valor de ["frase-chave", "Estudo de BMN"], outra com um valor de ["frase-chave", "Síndrome"], e finalmente com um valor de ["frase-chave", "Doentes Pediátricos"]. O valor literal de "frase-chave" permanece o mesmo sempre, mas o valor do caminho da expressão muda a cada execução de habilidade.

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 de caminho. Quando usados dentro de uma expressão, os caminhos devem ser colocados entre "$(" e ")".

Booleano não '!'

Negativo '-'

Adição '+'

Subtração '-'

Multiplicação '*'

Divisão '/'

Módulo '%'

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

Igualdade e desigualdade '==' '!='

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

Operador ternário '?:'

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

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, depois adição e subtração, depois comparação, depois igualdade e, em seguida, operadores lógicos. Aplicam-se também as regras habituais de associatividade.

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

Consulte também

• Criar um conjunto de competências na Pesquisa de IA do Azure
• Enriquecimentos de referência em um conjunto de habilidades de Pesquisa de IA do Azure