Crie um skillset em Azure Cognitive Search

Artigo
12/05/2022
10 minutos para ler

Um conjunto de competências define as operações que extraem e melhoram os dados para os tornar pesquisáveis. Executa depois de extrair texto e imagens, e após o processo são processados os mapeamentos de campo .

Este artigo explica como criar um skillset com o Create Skillset (REST API), mas os mesmos conceitos e passos aplicam-se a outras linguagens de programação.

As regras para a definição de skillset incluem:

Um skillset deve ter um nome único dentro da coleção skillset. Quando se define um skillset, está a criar um recurso de alto nível que pode ser usado por qualquer indexante.
Uma habilidade deve conter pelo menos uma habilidade. Um skillset típico tem 3 a 5. O máximo é de 30.
Um skillset pode repetir habilidades do mesmo tipo (por exemplo, múltiplas habilidades shaper).
Um skillset suporta operações acorrentadas, looping e ramificação.

Indexantes impulsionam execução de skillset. Vai precisar de um indexante, fonte de dados e índice antes de testar o seu skillset.

Dica

Permitir o enriquecimento para reutilizar o conteúdo que já processou e reduzir o custo de desenvolvimento.

Adicione uma definição de skillset

Comece com a estrutura básica. Na API Create Skillset REST, o corpo do pedido é da autoria da JSON e tem as seguintes secções:

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[
       
   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"A Cognitive Services resource in the same region as Azure Cognitive Search",
      "key":"<Your-Cognitive-Services-Multiservice-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

Após o nome e descrição, um skillset tem quatro propriedades principais:

skills matriz, uma coleção de habilidades desordenada. As habilidades podem ser utilitárias (como dividir texto), transformacional (baseada em IA dos Serviços Cognitivos) ou habilidades personalizadas que você fornece. Um exemplo de um conjunto de habilidades é fornecido na secção seguinte.
cognitiveServicesé usado para habilidades de faturação que chamam APIs Serviços Cognitivos. Remova esta secção se não estiver a utilizar habilidades de faturação ou procura de entidades personalizadas. Anexe um recurso se estiver.
knowledgeStore (opcional) especifica uma conta de armazenamento Azure e configurações para projetar a saída de skillset em tabelas, bolhas e ficheiros no Azure Storage. Retire esta secção se não precisar, caso contrário , especifique uma loja de conhecimentos.
encryptionKey(opcional) especifica uma Key Vault Azure e chaves geridas pelo cliente utilizadas para encriptar conteúdo sensível (descrições, cadeias de ligação, chaves) numa definição de skillset. Remova esta propriedade se não estiver a usar encriptação gerida pelo cliente.

Adicionar competências

Dentro da definição de skillset, o conjunto de habilidades especifica quais as habilidades a executar. Três a cinco habilidades são comuns, mas pode adicionar o máximo de habilidades necessárias, sujeitos a limites de serviço.

O resultado final de um gasoduto de enriquecimento é o conteúdo textual num índice de pesquisa ou numa loja de conhecimento. Por esta razão, a maioria das habilidades ou cria texto a partir de imagens (texto OCR, legendas, tags) ou analisa texto existente para criar novas informações (entidades, frases-chave, sentimento). As competências que operam de forma independente são processadas em paralelo. As competências que dependem umas das outras especificam a saída de uma habilidade (como frases-chave) como a entrada de segunda habilidade (como a tradução de texto). O serviço de pesquisa determina a ordem de execução de habilidades e o ambiente de execução.

Todas as habilidades têm um tipo, contexto, entradas e saídas. Uma habilidade pode opcionalmente ter um nome e descrição. O exemplo a seguir mostra duas habilidades incorporadas não relacionadas para que possa comparar a estrutura básica.

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "name": "#1",
    "description": "This skill detects organizations in the source content",
    "context": "/document",
    "categories": [ "Organization" ],
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "organizations",
        "targetName": "orgs"
      }
    ]
  },
  {
      "name": "#2",
      "description": "This skill detects corporate logos in the source files",
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [
          "brands"
      ],
      "inputs": [
          {
              "name": "image",
              "source": "/document/normalized_images/*"
          }
      ],
      "outputs": [
          {
              "name": "brands"
          }
      ]
  }
]

Cada habilidade é única em termos dos seus valores de entrada e dos parâmetros que leva. Documentação de referência de habilidade descreve todos os parâmetros e propriedades de uma dada habilidade. Embora existam diferenças, a maioria das habilidades partilham um conjunto comum e são igualmente modeladas.

Nota

Você pode construir habilidades complexas com looping e ramificação usando a habilidade condicional para criar as expressões. A sintaxe baseia-se na notação do caminho do ponteiro JSON , com algumas modificações para identificar nós na árvore de enriquecimento. A "/" atravessa um nível mais baixo na árvore e "*" atua como um operador para cada operador no contexto. Numerosos exemplos neste artigo ilustram a sintaxe.

Definir contexto de habilidade

Cada habilidade tem uma propriedade de contexto que determina o nível a que as operações ocorrem. Se a propriedade "contextual" não estiver explicitamente definida, o padrão é "/document", onde o contexto é todo o documento (a habilidade é chamada uma vez por documento).

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

O contexto é geralmente definido para um dos seguintes exemplos:

Exemplo de contexto	Descrição
"contexto": "/documento"	(Predefinição) As entradas e saídas estão ao nível do documento.
"contexto": "/documento/páginas/*"	Algumas habilidades como a análise de sentimentos têm um melhor desempenho em pedaços menores de texto. Se estiver a dividir um grande campo de conteúdo em páginas ou frases, o contexto deve estar sobre cada parte do componente.
"contexto": "/documento/normalized_images/*"	Para o conteúdo da imagem, as entradas e saídas são uma por imagem no documento-mãe.

O contexto também determina onde as saídas são produzidas na árvore de enriquecimento. Por exemplo, a competência de Reconhecimento de Entidade devolve uma propriedade chamada "organizations", capturada como orgs. Se o contexto for "/document", então um nó de "organizações" é adicionado como uma criança de "/document". Se quisesse então fazer referência a este nó em habilidades a jusante, o caminho seria "/document/orgs".

Definir entradas

Competências lidas e escritas para um documento enriquecido. As entradas de habilidades especificam a origem dos dados recebidos. É frequentemente o nó de raiz do documento enriquecido. Para as bolhas, uma entrada de habilidade típica é a propriedade de conteúdo do documento.

Documentação de referência de habilidade para cada habilidade descreve as entradas que pode consumir. Cada entrada tem um "nome" que identifica uma entrada específica, e uma "fonte" que especifica a localização dos dados no documento enriquecido. O exemplo a seguir é da competência de Reconhecimento de Entidades:

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]

As habilidades podem ter múltiplas entradas. O "nome" é a entrada específica. Para o Reconhecimento de Entidades, as entradas específicas são "texto" e "languageCode".

A propriedade "fonte" especifica qual campo ou linha fornece o conteúdo a ser processado. Para competências baseadas em texto, a fonte é um campo no documento ou linha que fornece texto. Para habilidades baseadas na imagem, o nó que fornece a entrada é imagens normalizadas.

Exemplo de origem	Descrição
"fonte": "/documento"	Para um conjunto de dados tabulares, um documento corresponde a uma linha.
"fonte": "/documento/conteúdo"	Para as bolhas, a fonte é geralmente a propriedade de conteúdo da bolha.
"fonte": "/documento/algum campo nomeado"	Para competências baseadas em texto, como o reconhecimento de entidades ou a extração de frases-chave, a origem deve ser um campo que contenha texto suficiente para ser analisado, como uma "descrição" ou "resumo".
"fonte": "/documento/normalized_images/*"	Para o conteúdo da imagem, a fonte é a imagem que foi normalizada durante a quebra de documentos.

Se a habilidade fortale sobre uma matriz, tanto o contexto como a fonte de entrada devem incluir /* nas posições corretas.

Definir saídas

Cada habilidade é projetada para emitir tipos específicos de saída, que são referenciados pelo nome no skillset. Uma produção de habilidades tem um "nome" e um "nome-alvo" opcional.

Documentação de referência de habilidade para cada habilidade descreve as saídas que pode produzir. O exemplo a seguir é da competência de Reconhecimento de Entidades:

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]

As habilidades podem ter múltiplas saídas. O "nome" identifica uma saída específica. Por exemplo, para o Reconhecimento de Entidades, a produção pode ser "pessoas", "localizações", "organizações", entre outras.
"TargetName" especifica o nome que gostaria que este nó tivesse no documento enriquecido. Isto é útil se as saídas de habilidades têm o mesmo nome. Se tiver múltiplas habilidades que devolvem a mesma saída, use a desambiguação de "targetName" nome em caminhos de nó de enriquecimento. Se o nome do alvo não for especificado, a propriedade do nome é usada para ambos.

Algumas situações exigem a referência de cada elemento de uma matriz separadamente. Por exemplo, suponha que queira passar cada elemento separadamente "/document/orgs" para outra habilidade. Para tal, adicione um asterisco ao caminho: "/document/orgs/*".

A produção de habilidades é escrita para o documento enriquecido como um novo nó na árvore de enriquecimento. Pode ser um valor simples, como uma pontuação de sentimento ou código de linguagem. Também poderia ser uma coleção, como uma lista de organizações, pessoas ou locais. A produção de habilidades também pode ser uma estrutura complexa, como é o caso da habilidade do Shaper. As entradas da habilidade determinam a composição da forma, mas a saída é o objeto nomeado, que pode ser referenciado num índice de pesquisa, numa projeção de uma loja de conhecimento, ou outra habilidade pelo seu nome.

Adicione uma habilidade personalizada

Esta secção inclui um exemplo de uma habilidade personalizada. O URI aponta para uma Função Azure, que por sua vez invoca o modelo ou transformação que proporciona. Para mais informações, consulte Definir uma interface personalizada.

Embora a habilidade personalizada seja executar código que é externo ao oleoduto, numa matriz de habilidades, é apenas mais uma habilidade. Tal como as competências incorporadas, tem um tipo, contexto, entradas e saídas. Também lê e escreve para uma árvore de enriquecimento, tal como as habilidades incorporadas fazem. Note que o campo "contexto" é definido com um asterisco "/document/orgs/*" , o que significa que o passo de enriquecimento é chamado para cada organização sob "/document/orgs".

A produção, tal como a descrição da empresa neste exemplo, é gerada para cada organização que é identificada. Quando se refere ao nó num degrau a jusante (por exemplo, na extração de frases-chave), utilizaria o caminho "/document/orgs/*/companyDescription" para o fazer.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "This skill calls an Azure function, which in turn calls custom code",
  "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeCode?code=foo",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "foobar"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

Enviar saída para um destino

Embora a produção de habilidades possa ser opcionalmente em cache para fins de reutilização, geralmente é temporária e existe apenas enquanto a execução de habilidades está em andamento.

Para enviar a saída para um campo num índice de pesquisa, crie um mapeamento de campo de saída num indexante.
Para enviar a saída para uma loja de conhecimento, crie uma projeção.
Para enviar a saída para uma habilidade a jusante, refira a saída pelo seu nome de nó, como "/document/organization", por exemplo, na propriedade de fonte de entrada da habilidade a jusante. Consulte Referência uma anotação por exemplo.

Dicas para um primeiro skillset

Monte uma amostra representativa do seu conteúdo no Blob Storage ou noutra fonte de dados suportada e execute o assistente de dados De importação.

O assistente automatiza vários passos que podem ser desafiantes da primeira vez. Define o skillset, índice e indexador, incluindo mapeamentos de campo e mapeamentos de campo de saída. Também definirá projeções numa loja de conhecimento se estiver a usar uma. Para algumas habilidades, como o OCR ou a análise de imagem, o assistente adiciona habilidades de utilidade que fundem o conteúdo de imagem e texto que foi separado durante a quebra de documentos.

Depois de o assistente ser executado, pode abrir cada objeto no portal do Azure para visualizar a sua definição JSON. Também pode usar As Sessões de Debug para invocar a execução de skillset sobre um documento-alvo.
Em alternativa, pode importar amostras de coleções de Carteiro que proporcionam uma articulação completa das definições de objeto necessárias para avaliar uma habilidade.
Quando estiver pronto para começar do zero com uma nova habilidade, verificar os resultados preliminares é importante. Recomendamos um índice de pesquisa para validação de conteúdos porque é mais simples de configurar, em comparação com lojas de conhecimento.

Para cada produção de habilidade, defina um mapeamento de campo de saída no indexante e um campo no índice de pesquisa.

Depois de executar o indexer, utilize o Search Explorer para devolver documentos do índice e verifique o conteúdo de cada campo para determinar o que o skillset detetou ou criou.

Esta imagem mostra os resultados de uma competência de reconhecimento de entidade que detetou pessoas, locais, organizações e outras entidades num pedaço de texto. Pode ver os resultados para decidir se uma habilidade acrescenta valor à sua solução.

Passos seguintes

Os campos de origem de contexto e de entrada são caminhos para nós numa árvore de enriquecimento. Como próximo passo, saiba mais sobre a sintaxe do caminho para nós numa árvore de enriquecimento.

Referência a anotações em um skillset