Como fazer referência a anotações em um Azure Pesquisa Cognitiva skillsetHow to reference annotations in an Azure Cognitive Search skillset

Neste artigo, você aprende a referenciar anotações em definições de habilidades usando exemplos para ilustrar diferentes cenários.In this article, you learn how to reference annotations in skill definitions, using examples to illustrate various scenarios. Conforme o conteúdo de um documento flui por um conjunto de habilidades, ele é enriquecido com anotações.As the content of a document flows through a set of skills, it gets enriched with annotations. Anotações podem ser usadas como entradas para mais enriquecimento downstream ou podem ser mapeadas para um campo de saída em um índice.Annotations can be used as inputs for further downstream enrichment, or mapped to an output field in an index.

Os exemplos neste artigo são baseados campo content gerado automaticamente pelos indexadores de Blobs do Azure como parte da fase de quebra de documento.Examples in this article are based on the content field generated automatically by Azure Blob indexers as part of the document cracking phase. Ao fazer referência a documentos de um contêiner de Blob, use um formato como "/document/content", em que o campo content faz parte de document.When referring to documents from a Blob container, use a format such as "/document/content", where the content field is part of the document.

Conceitos em segundo planoBackground concepts

Antes de examinarmos a sintaxe, vamos rever alguns conceitos importantes para entender melhor os exemplos fornecidos mais adiante neste artigo.Before reviewing the syntax, let's revisit a few important concepts to better understand the examples provided later in this article.

TermoTerm DescriçãoDescription
Documento enriquecidoEnriched Document Um documento enriquecido é uma estrutura interna criada e usada pelo pipeline para reter todas as anotações relacionadas a um documento.An enriched document is an internal structure created and used by the pipeline to hold all annotations related to a document. Pense em um documento enriquecido como uma árvore de anotações.Think of an enriched document as a tree of annotations. Em geral, uma anotação criada de uma anotação anterior se torna seu filho.Generally, an annotation created from a previous annotation becomes its child.

Documentos enriquecidos existem somente pela duração da execução do conjunto de habilidades.Enriched documents only exist for the duration of skillset execution. Após o conteúdo ser mapeado para o índice de pesquisa, o documento enriquecido deixará de ser necessário.Once content is mapped to the search index, the enriched document is no longer needed. Embora você não interaja diretamente com documentos enriquecidos, é útil ter um modelo mental dos documentos ao criar um conjunto de habilidades.Although you don't interact with enriched documents directly, it's useful to have a mental model of the documents when creating a skillset.

Contexto de enriquecimentoEnrichment Context O contexto em que o enriquecimento ocorre, em termos de qual elemento é enriquecido.The context in which the enrichment takes place, in terms of which element is enriched. Por padrão, o contexto de enriquecimento está no nível do "/document" e seu escopo são documentos individuais.By default, the enrichment context is at the "/document" level, scoped to individual documents. Quando uma habilidade é executada, suas saídas se tornam propriedades do contexto definido.When a skill runs, the outputs of that skill become properties of the defined context.

Exemplo 1: referência de anotação simplesExample 1: Simple annotation reference

No armazenamento de BLOBs do Azure, suponha que você tenha uma variedade de arquivos contendo referências a nomes de pessoas que você deseja extrair usando o reconhecimento de entidade.In Azure Blob storage, suppose you have a variety of files containing references to people's names that you want to extract using entity recognition. Na definição de habilidade abaixo, "/document/content" é a representação textual de todo o documento e "people" é uma extração de nomes completos para entidades identificadas como pessoas.In the skill definition below, "/document/content" is the textual representation of the entire document, and "people" is an extraction of full names for entities identified as persons.

Como o contexto padrão é "/document", a lista de pessoas agora pode ser referenciada como "/document/people".Because the default context is "/document", the list of people can now be referenced as "/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.In this specific case "/document/people" is an annotation, which could now be mapped to a field in an index, or used in another skill in the same skillset.

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

Exemplo 2: referenciar uma matriz em um documentoExample 2: Reference an array within a document

Este exemplo dá continuidade ao anterior, mostrando como invocar uma etapa de enriquecimento várias vezes no mesmo documento.This example builds on the previous one, showing you how to invoke an enrichment step multiple times over the same document. Suponha que o exemplo anterior tenha gerado uma matriz de cadeias de caracteres com 10 nomes de pessoas provenientes de um único documento.Assume the previous example generated an array of strings with 10 people names from a single document. Faz sentido que a próxima etapa seja um segundo enriquecimento que extrai o sobrenome de um nome completo.A reasonable next step might be a second enrichment that extracts the last name from a full name. Como há 10 nomes, esta etapa precisa ser chamada 10 vezes no documento, uma vez para cada pessoa.Because there are 10 names, you want this step to be called 10 times in this document, once for each person.

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".To invoke the right number of iterations, set the context as "/document/people/*", where the asterisk ("*") represents all the nodes in the enriched document as descendants of "/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.Although this skill is only defined once in the skills array, it is called for each member within the document until all members are processed.

  {
    "@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.When annotations are arrays or collections of strings, you might want to target specific members rather than the array as a whole. O exemplo anterior gera uma anotação chamada "last" em cada nó representado pelo contexto.The above example generates an annotation called "last" under each node represented by the context. Se quiser fazer referência a essa família de anotações, você poderá usar a sintaxe "/document/people/*/last".If you want to refer to this family of annotations, you could use the syntax "/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.If you want to refer to a particular annotation, you could use an explicit index: "/document/people/1/last" to reference the last name of the first person identified in the document. Observe que nessa sintaxe as matrizes são "indexadas em 0".Notice that in this syntax arrays are "0 indexed".

Exemplo 3: referenciar membros de uma matrizExample 3: Reference members within an array

Às vezes, você precisa agrupar todas as anotações de um tipo específico para passá-las para uma habilidade específica.Sometimes you need to group all annotations of a particular type to pass them to a particular skill. Considere uma habilidade personalizada hipotética que identifica o sobrenome mais comum de todos os sobrenomes extraídos no exemplo 2.Consider a hypothetical custom skill that identifies the most common last name from all the last names extracted in Example 2. Para fornecer apenas os sobrenomes à habilidade personalizada, especifique o contexto como "/document" e a entrada como "/document/people/*/lastname".To provide just the last names to the custom skill, specify the context as "/document" and the input as "/document/people/*/lastname".

Observe que a cardinalidade de "/document/people/*/lastname" é maior do que a do documento.Notice that the cardinality of "/document/people/*/lastname" is larger than that of document. Pode haver 10 nós de sobrenome, enquanto há apenas um nó de documento para este documento.There may be 10 lastname nodes while there is only one document node for this document. Neste caso, o sistema criará automaticamente uma matriz de "/document/people/*/lastname" contendo todos os elementos no documento.In that case, the system will automatically create an array of "/document/people/*/lastname" containing all of the elements in the document.

  {
    "@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"
      }
    ]
  }

Confira tambémSee also