Criar um conjunto de competências na Pesquisa de IA do Azure

  • Artigo

Estágios do indexador

Um conjunto de habilidades define operações que geram conteúdo textual e estrutura a partir de documentos que contêm imagens ou texto não estruturado. Exemplos são OCR para imagens, reconhecimento de entidade para texto indiferenciado e tradução de texto. Um conjunto de habilidades é executado depois que o texto e as imagens são extraídos de uma fonte de dados externa e depois que os mapeamentos de campo são processados.

Este artigo explica como criar um conjunto de habilidades usando APIs REST, mas os mesmos conceitos e etapas se aplicam a outras linguagens de programação.

As regras para a definição do conjunto de competências incluem:

  • Um nome exclusivo dentro da coleção skillset. Um conjunto de habilidades é um recurso de nível superior que pode ser usado por qualquer indexador.
  • Pelo menos uma habilidade. Três a cinco habilidades são típicas. O máximo é 30.
  • Um conjunto de habilidades pode repetir habilidades do mesmo tipo (por exemplo, várias habilidades de Shaper).
  • Um conjunto de habilidades suporta operações encadeadas, looping e ramificação.

Os indexadores impulsionam a execução do conjunto de habilidades. Você precisa de um indexador, fonte de dados e índice antes de poder testar seu conjunto de habilidades.

Gorjeta

Habilite o cache de enriquecimento para reutilizar o conteúdo que você já processou e reduza o custo de desenvolvimento.

Adicionar uma definição de conjunto de competências

Comece pela estrutura básica. Na API REST Create Skillset, o corpo da solicitação é criado em JSON e tem as seguintes seçõ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":"An Azure AI services resource in the same region as Azure AI Search",
      "key":"<Your-Cognitive-Services-Multiservice-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

Após o nome e a descrição, um conjunto de habilidades tem quatro propriedades principais:

  • skills array, uma coleção desordenada de habilidades. As habilidades podem ser utilitárias (como dividir texto), transformacionais (com base na IA dos serviços de IA do Azure) ou habilidades personalizadas que você fornece. Um exemplo de uma matriz de habilidades é fornecido na próxima seção.

  • cognitiveServices é usado para habilidades faturáveis que chamam APIs de serviços de IA do Azure. Remova esta seção se você não estiver usando habilidades faturáveis ou Pesquisa de entidade personalizada. Anexe um recurso , se estiver.

  • knowledgeStore (opcional) especifica uma conta de Armazenamento do Azure e configurações para projetar a saída do conjunto de habilidades em tabelas, blobs e arquivos no Armazenamento do Azure. Remova esta seção se não precisar dela, caso contrário , especifique um armazenamento de conhecimento.

  • encryptionKey (opcional) especifica um Cofre de Chaves do Azure e chaves gerenciadas pelo cliente usadas para criptografar conteúdo confidencial (descrições, cadeias de conexão, chaves) em uma definição de conjunto de habilidades. Remova essa propriedade se você não estiver usando criptografia gerenciada pelo cliente.

Adicionar competências

Dentro da definição do conjunto de habilidades, a matriz de habilidades especifica quais habilidades executar. Três a cinco habilidades são comuns, mas você pode adicionar quantas habilidades forem necessárias, sujeitas a limites de serviço.

O resultado final de um pipeline de enriquecimento é o conteúdo textual em um índice de pesquisa ou em um repositório de conhecimento. Por esse motivo, a maioria das habilidades cria texto a partir de imagens (texto OCR, legendas, tags) ou analisa o 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 habilidades que dependem umas das outras especificam o resultado de uma habilidade (como frases-chave) como a entrada de uma segunda habilidade (como 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 uma descrição. O exemplo a seguir mostra duas habilidades internas não relacionadas para que você 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 de seus valores de entrada e os parâmetros que ela toma. A documentação de referência de habilidade descreve todos os parâmetros e propriedades de uma determinada habilidade. Embora existam diferenças, a maioria das habilidades compartilha um conjunto comum e tem padrões semelhantes.

Nota

Você pode criar conjuntos de habilidades complexos com looping e ramificação usando a habilidade Condicional para criar as expressões. A sintaxe é baseada na notação de caminho de 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 um no contexto. Numerosos exemplos neste artigo ilustram a sintaxe.

Definir contexto de habilidades

Cada habilidade tem uma propriedade de contexto que determina o nível em que as operações ocorrem. Se a propriedade "context" não estiver definida explicitamente, o padrão será "/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 como um dos seguintes exemplos:

Exemplo de contexto Description
"contexto": "/documento" (Padrão) As entradas e saídas estão no nível do documento.
"contexto": "/document/pages/*" Algumas habilidades, como análise de sentimento, têm melhor desempenho em pedaços menores de texto. Se você estiver dividindo um campo de conteúdo grande em páginas ou frases, o contexto deverá estar sobre cada parte do componente.
"contexto": "/document/normalized_images/*" Para o conteúdo da imagem, as entradas e saídas são uma por imagem no documento pai.

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

Definir inputs

Habilidades de leitura e escrita em um documento enriquecido. As entradas de habilidades especificam a origem dos dados recebidos. Muitas vezes, é o nó raiz do documento enriquecido. Para blobs, uma entrada de habilidade típica é a propriedade content do documento.

A documentação de referência de habilidades para cada habilidade descreve os insumos que ela 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 habilidade Reconhecimento de Entidade:

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

  • As habilidades podem ter várias entradas. O "nome" é a entrada específica. Para o Reconhecimento de Entidades, as entradas específicas são "text" e "languageCode".

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

    Exemplo de fonte Description
    "fonte": "/documento" Para um conjunto de dados tabulares, um documento corresponde a uma linha.
    "fonte": "/documento/conteúdo" Para blobs, a fonte geralmente é a propriedade content do blob.
    "fonte": "/document/some-named-field" Para habilidades baseadas em texto, como reconhecimento de entidade ou 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": "/document/normalized_images/*" Para conteúdo de imagem, a fonte é a imagem que foi normalizada durante a quebra de documentos.

Se a habilidade iterar em uma matriz, tanto o contexto quanto a fonte de entrada devem ser incluídos /* 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 conjunto de habilidades. Uma saída de habilidade tem um "nome" e um opcional "targetName".

A documentação de referência de habilidades para cada habilidade descreve os resultados que ela pode produzir. O exemplo a seguir é da habilidade Reconhecimento de Entidade:

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

  • As habilidades podem ter vários resultados. O "nome" identifica uma saída específica. Por exemplo, para o Reconhecimento de Entidades, os resultados podem ser "pessoas", "locais", "organizações", entre outros.

  • "targetName" especifica o nome que você gostaria que esse nó tivesse no documento enriquecido. Isso é útil se os resultados de habilidades tiverem o mesmo nome. Se você tiver várias habilidades que retornam a mesma saída, use a "targetName" desambiguação para nome em caminhos de nó de enriquecimento. Se o nome de destino não for especificado, a propriedade name será usada para ambos.

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

A saída de habilidades é gravada no 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 idioma. Também pode ser uma coleção, como uma lista de organizações, pessoas ou locais. A saída de habilidades também pode ser uma estrutura complexa, como é o caso da habilidade Shaper. As entradas da habilidade determinam a composição da forma, mas a saída é o objeto nomeado, que pode ser referenciado em um índice de pesquisa, uma projeção de armazenamento de conhecimento ou outra habilidade por seu nome.

Adicionar uma habilidade personalizada

Esta seção inclui um exemplo de uma habilidade personalizada. O URI aponta para uma Função do Azure, que, por sua vez, invoca o modelo ou a transformação que você fornece. Para obter mais informações, consulte Definir uma interface personalizada.

Embora a habilidade personalizada esteja executando código externo ao pipeline, em uma matriz de habilidades, é apenas outra habilidade. Como as habilidades internas, ele tem um tipo, contexto, entradas e saídas. Ele também lê e escreve em uma árvore de enriquecimento, assim como as habilidades incorporadas. Observe que o campo "contexto" está definido como um asterisco, o "/document/orgs/*" que significa que a etapa de enriquecimento é chamada para cada organização em "/document/orgs".

A saída, como a descrição da empresa neste exemplo, é gerada para cada organização identificada. Ao se referir ao nó em uma etapa a jusante (por exemplo, na extração de frase-chave), você usaria o caminho "/document/orgs/*/companyDescription" para fazer isso.

{
  "@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 saída de habilidades possa ser opcionalmente armazenada 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 em um índice de pesquisa, crie um mapeamento de campo de saída em um indexador.

  • Para enviar a saída para um repositório de conhecimento, crie uma projeção.

  • Para enviar a saída para uma habilidade downstream, faça referência à saída pelo nome do nó, como "/document/organization", na propriedade input source da habilidade downstream. Consulte Fazer referência a uma anotação para obter exemplos.

Dicas para um primeiro conjunto de habilidades

  • Experimente o assistente Importar dados.

    O assistente automatiza várias etapas que podem ser desafiadoras na primeira vez. Ele define o conjunto de habilidades, índice e indexador, incluindo mapeamentos de campo e mapeamentos de campo de saída. Ele também define projeções em um repositório de conhecimento, se você estiver usando um. Para algumas habilidades, como OCR ou análise de imagem, o assistente adiciona habilidades de utilidade que mesclam o conteúdo de imagem e texto que foi separado durante a quebra de documentos.

    Depois que o assistente for executado, você poderá abrir cada objeto no portal do Azure para exibir sua definição JSON.

  • Tente Depurar sessões para invocar a execução do conjunto de habilidades sobre um documento de destino e inspecione o documento enriquecido que o conjunto de habilidades cria. Você pode visualizar e modificar configurações e valores de entrada e saída. Este tutorial é um bom lugar para começar: Tutorial: Depurar um conjunto de habilidades usando sessões de depuração.

Próximos passos

Os campos de contexto e de origem de entrada são caminhos para nós em uma árvore de enriquecimento. Como próxima etapa, saiba mais sobre a sintaxe de caminho para nós em uma árvore de enriquecimento.

Referenciando anotações em um conjunto de habilidades