Fazer referência a um caminho para nós enriquecidos usando propriedades de contexto e origem um conjunto de habilidades do Azure AI Search

2025-05-28

Durante a execução do conjunto de habilidades, o mecanismo cria uma árvore de enriquecimento na memória que captura cada enriquecimento, como entidades reconhecidas ou texto traduzido. Neste artigo, saiba como fazer referência a um nó de enriquecimento na árvore de enriquecimento para que você possa passar a saída para habilidades downstream ou especificar um mapeamento de campo de saída para um campo de índice de pesquisa.

Este artigo usa exemplos para ilustrar vários cenários. Para obter a sintaxe completa, consulte Contexto de habilidade e linguagem de anotação de entrada.

Conceitos básicos

Antes de revisar a sintaxe, vamos revisitar alguns conceitos importantes para entender melhor os exemplos fornecidos mais adiante neste artigo.

Termo	Descrição
"Documento enriquecido"	Um documento enriquecido é uma estrutura na memória que coleta resultados de habilidades à medida que é criado e contém todos os enriquecimentos relacionados a um documento. Pense num documento enriquecido como uma árvore. Geralmente, a árvore começa no nível do documento raiz e cada novo enriquecimento é criado a partir de um nó anterior como seu descendente.
"Nó"	Dentro de um documento enriquecido, um nó (às vezes chamado de "anotação") é uma saída específica, como "text" ou "layoutText" do recurso OCR, ou um valor de campo de origem original, como o conteúdo de um campo de ID do produto, ou metadados copiados da fonte, como metadata_storage_path de blobs no Armazenamento do Azure.
"contexto"	O escopo do enriquecimento, que é o documento inteiro, uma parte de um documento (páginas ou frases) ou, se você estiver trabalhando com imagens, as imagens extraídas de um documento. Por padrão, o contexto de enriquecimento está no `"/document"` nível, com escopo para documentos individuais contidos na fonte de dados. Quando uma habilidade é executada, os resultados dessa habilidade tornam-se propriedades do contexto definido.

Caminhos para diferentes cenários

Os caminhos são especificados nas propriedades "contexto" e "origem" de um conjunto de habilidades e nos mapeamentos de campo de saída em um indexador.

O exemplo na captura de tela ilustra o caminho para um item em uma coleção do Azure Cosmos DB.

context path é /document/HotelId porque a coleção é particionada em documentos pelo /HotelId campo.
source caminho é /document/Description porque a habilidade é uma habilidade de tradução, e o campo que desejas traduzir em cada documento é Description.

Todos os caminhos começam com /document. Um documento enriquecido é criado no estágio de "quebra de documento" da execução do indexador, quando o indexador abre um documento ou lê em uma linha da fonte de dados. Inicialmente, o único nó em um documento enriquecido é o nó raiz (/document), e é o nó a partir do qual todos os outros enriquecimentos ocorrem.

A lista a seguir inclui vários exemplos comuns:

/document é o nó raiz e indica um blob inteiro no Armazenamento do Azure ou uma linha em uma tabela SQL.
/document/{key} é a sintaxe de um documento ou item em uma coleção do Azure Cosmos DB, onde {key} é a chave real, como /document/HotelId no exemplo anterior.
/document/content especifica a propriedade "content" de um blob JSON.
/document/{field} é a sintaxe de uma operação executada em um campo específico, como a tradução do /document/Description campo, vista no exemplo anterior.
/document/pages/* ou /document/sentences/* torne-se o contexto se você estiver dividindo um documento grande em partes menores para processamento. Se "contexto" for /document/pages/*, a habilidade é executada uma vez em cada página do documento. Como pode haver mais de uma página ou frase, você pode adicionar /* para capturar todas.
/document/normalized_images/* é criado durante a quebra de documentos se o documento contiver imagens. Todos os caminhos para imagens começam com normalized_images. Como geralmente há várias imagens incorporadas em um documento, anexe /*.

Os exemplos no restante deste artigo são baseados no campo "conteúdo" gerado automaticamente pelos indexadores de blob do Azure como parte da fase de quebra de documentos. Ao se referir a documentos de um contêiner de Blob, use um formato como "/document/content", onde o campo "conteúdo" faz parte do "documento".

Exemplo 1: Referência de anotação simples

No Armazenamento de Blobs do Azure, suponha que você tenha vários arquivos contendo referências aos nomes das pessoas que deseja extrair usando o reconhecimento de entidade. Na seguinte definição de habilidade, "/document/content" está a representação textual de todo o documento, e "pessoas" é uma extração de nomes completos para entidades identificadas como pessoas.

Como o contexto padrão é "/document", a lista de pessoas agora pode ser referenciada como "/document/people". Neste caso "/document/people" específico é uma anotação, que agora pode ser mapeada para um campo em um índice, ou usada em outra habilidade no mesmo conjunto de habilidades.

  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "categories": [ "Person"],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "persons",
        "targetName": "people"
      }
    ]
  }

Exemplo 2: Fazer referência a uma matriz dentro de um documento

Este exemplo se baseia no anterior, mostrando como invocar uma etapa de enriquecimento várias vezes sobre o mesmo documento. Suponha que o exemplo anterior gerou uma matriz de cadeias de caracteres com nomes de 10 pessoas de um único documento. Um próximo passo razoável pode ser um segundo enriquecimento que extraia o sobrenome de um nome completo. Como existem 10 nomes, você deseja que essa etapa seja chamada 10 vezes neste documento, uma vez para cada pessoa.

Para invocar o número correto de iterações, defina o contexto como "/document/people/*", onde o asterisco ("*") representa todos os nós no documento enriquecido como descendentes de "/document/people". Embora essa habilidade seja definida apenas uma vez na matriz de habilidades, ela é chamada para cada membro dentro do documento até que todos os membros sejam processados.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the last name from a full name",
    "uri": "http://names.azurewebsites.net/api/GetLastName",
    "context" : "/document/people/*",
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "fullname",
        "source": "/document/people/*"
      }
    ],
    "outputs": [
      {
        "name": "lastname",
        "targetName": "last"
      }
    ]
  }

Quando as anotações são matrizes ou coleções de cadeias de caracteres, convém direcionar membros específicos em vez da matriz como um todo. O exemplo anterior gera uma anotação chamada "last" em cada nó representado pelo contexto. Se você quiser se referir a essa família de anotações, você pode usar a sintaxe "/document/people/*/last". Se você quiser se referir a uma anotação específica, você pode usar um índice explícito: "/document/people/1/last" para fazer referência ao sobrenome da primeira pessoa identificada no documento. Observe que nesta sintaxe as matrizes são "0 indexadas".

Exemplo 3: Membros de referência dentro de uma matriz

Às vezes, você precisa agrupar todas as anotações de um tipo específico para passá-las para uma habilidade específica. Considere uma habilidade personalizada hipotética que identifique o sobrenome mais comum de todos os sobrenomes extraídos no Exemplo 2. Para fornecer apenas os sobrenomes para a habilidade personalizada, especifique o contexto como "/document" e a entrada como "/document/people/*/lastname".

Observe que a cardinalidade de "/document/people/*/lastname" é maior do que a de documento. Pode haver 10 nós de sobrenome enquanto há apenas um nó de documento para este documento. Nesse caso, o sistema criará automaticamente uma matriz contendo "/document/people/*/lastname" todos os elementos do documento.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the most common string from an array of strings",
    "uri": "http://names.azurewebsites.net/api/MostCommonString",
    "context" : "/document",
    "inputs": [
      {
        "name": "strings",
        "source": "/document/people/*/lastname"
      }
    ],
    "outputs": [
      {
        "name": "mostcommon",
        "targetName": "common-lastname"
      }
    ]
  }

Dicas para solução de problemas de caminho de anotação

Se você estiver tendo problemas com a especificação de entradas de habilidades, estas dicas podem ajudá-lo a avançar:

Execute o assistente Importar dados sobre seus dados para revisar as definições do conjunto de habilidades e os mapeamentos de campo gerados pelo assistente.
Inicie uma sessão de depuração em um conjunto de habilidades para exibir a estrutura de um documento enriquecido. Você pode editar os caminhos e outras partes da definição de habilidade e, em seguida, executar a habilidade para validar suas alterações.

Partilhar via