Referenciar um caminho para nós enriquecidos usando propriedades de contexto e origem de um conjunto de habilidades do Pesquisa de IA do Azure

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 referenciar 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 ver a sintaxe completa, confira Contexto de habilidade e linguagem de anotação de entrada.

Conceitos em segundo plano

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

Caminhos para diferentes cenários

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

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

• context caminho é /document/HotelId porque a coleção é particionada em documentos pelo campo /HotelId.

• source caminho é /document/Description porque a habilidade é uma habilidade de tradução e o campo que você deseja que a habilidade traduza é o campo Description em cada documento.

Todos os caminhos começam com /document. Um documento enriquecido é criado na fase 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ó do qual todos os outros enriquecimentos ocorrem.

A seguinte lista 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 de um item em uma coleção do Azure Cosmos DB, em que {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 campo /document/Description, vista no exemplo anterior.
• /document/pages/* ou /document/sentences/* passa a ser o contexto se você está dividindo um documento grande em partes menores para processamento. Se o "context" for /document/pages/*, a habilidade será executada uma vez em cada página do documento. Como pode haver mais de uma página ou frase, você acrescentará /* para capturar todas elas.
• /document/normalized_images/* é criado durante a quebra de documento se o documento contém imagens. Todos os caminhos para as imagens começam com normalized_images. Como muitas vezes há várias imagens inseridas em um documento, acrescente /*.

Os exemplos no restante deste artigo baseiam-se no campo "conteúdo" gerado automaticamente por indexadores de blob do Azure como parte da fase de quebra de documento. Ao referenciar documentos de um contêiner de Blob, use um formato como "/document/content", em que o campo "content" faz parte de "document".

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

No Armazenamento de Blobs do Azure, considere que você tem diversos arquivos contendo referências a nomes de pessoas que você deseja extrair usando o reconhecimento de entidade. Na definição de habilidade a seguir, "/document/content" é 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 específico, "/document/people" é uma anotação que agora poderia ser mapeada para um campo em um índice ou usada em outra habilidade do 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: referenciar uma matriz em um documento

Este exemplo dá continuidade ao anterior, mostrando como invocar uma etapa de enriquecimento várias vezes no mesmo documento. Suponha que o exemplo anterior tenha gerado uma matriz de cadeias de caracteres com 10 nomes de pessoas provenientes de um único documento. Faz sentido que a próxima etapa seja um segundo enriquecimento que extrai o sobrenome de um nome completo. Como há 10 nomes, esta etapa precisa ser chamada 10 vezes no documento, uma vez para cada pessoa.

Para invocar o número correto de iterações, defina o contexto como "/document/people/*", em que 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 no 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 forem matrizes ou coleções de cadeias de caracteres, talvez você queira que o alvo sejam membros específicos em vez da matriz inteira. O exemplo anterior gera uma anotação chamada "last" em cada nó representado pelo contexto. Se quiser fazer referência a essa família de anotações, você poderá usar a sintaxe "/document/people/*/last". Se quiser fazer referência a uma anotação específica, você poderá usar um índice explícito: "/document/people/1/last" para referenciar o sobrenome da primeira pessoa identificada no documento. Observe que nessa sintaxe as matrizes são "indexadas em 0".

Exemplo 3: referenciar membros 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 identifica o sobrenome mais comum de todos os sobrenomes extraídos no exemplo 2. Para fornecer apenas os sobrenomes à habilidade personalizada, especifique o contexto como "/document" e a entrada como "/document/people/*/lastname".

Observe que a cardinalidade de "/document/people/*/lastname" é maior que a do documento. Pode haver dez nós de sobrenome, enquanto há apenas um nó de documento para esse documento. Neste caso, o sistema criará automaticamente uma matriz de "/document/people/*/lastname" contendo todos os elementos no 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 para especificar as entradas de habilidades, essas dicas poderão ajudar você a seguir em frente:

• Execute o assistente de importação de dados nos seus dados para analisar 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 ver a estrutura de um documento enriquecido. Você pode editar os caminhos e outras partes da definição de habilidade e executar a habilidade para validar as alterações.

Confira também

• Contexto de habilidades e idioma da anotação de entrada
• Como integrar uma habilidade personalizada a um pipeline de enriquecimento
• Como definir um conjunto de qualificações
• Criar conjunto de qualificações (REST)
• How to map enriched fields to an index (Como mapear campos enriquecidos para um índice)