Criar um conjunto de habilidades na IA do Azure Search

Artigo
03/13/2024

Um conjunto de habilidades define operações que geram conteúdo textual e estrutura de documentos que contêm imagens ou texto não estruturado. Exemplos são OCR para imagens, reconhecimento de entidade para texto não diferenciado 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 após os mapeamentos de campo serem processados.

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

As regras para a definição de conjuntos de habilidades incluem:

Um nome exclusivo dentro da coleção de conjuntos de habilidades. 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.
O conjunto de habilidades pode repetir habilidades do mesmo tipo (por exemplo, habilidades de várias formas).
Um conjunto de habilidades dá suporte a operações encadeadas, loops e ramificações.

Os indexadores conduzem a execução do conjunto de habilidades. Será necessário um indexador, uma fonte de dados e um índice para conseguir testar o seu conjunto de habilidades.

Dica

Habilite o cache de enriquecimento para reutilizar o conteúdo já processado e reduzir o custo de desenvolvimento.

Adicionar uma definição de conjunto de habilidades

Comece com a estrutura básica. Na API REST Criar conjunto de habilidades, 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":{ }
}

Depois do nome e da descrição, o conjunto de habilidades tem quatro propriedades principais:

skills matriz, uma coleção não ordenada 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. Há um exemplo de matriz de habilidades na próxima seção.
cognitiveServices é usado para habilidades faturáveis que chamam as 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 usando.
knowledgeStore (opcional) especifica uma conta do Armazenamento do Microsoft Azure e configurações para projetar a saída do conjunto de habilidades em tabelas, blobs e arquivos no Armazenamento do Microsoft Azure. Remova esta seção se não precisar dela. Caso contrário, especifique um repositório de conhecimento.
encryptionKey (opcional) especifica um Azure Key Vault 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 a criptografia gerenciada pelo cliente.

Adicionar habilidades

Dentro da definição de 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 aos limites de serviço.

O resultado final de um pipeline de enriquecimento é o conteúdo textual em um índice de pesquisa ou um repositório de conhecimento. Por esse motivo, a maioria das habilidades cria texto a partir de imagens (texto OCR, legendas, marcas) ou analisa texto existente para criar novas informações (entidades, frases-chave, sentimento). As habilidades que operam de forma independente são processadas em paralelo. Habilidades que dependem umas das outras especificam a saída de uma habilidade (como frases-chave) como a entrada de 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 tipo, contexto, entradas e saídas. Opcionalmente, uma habilidade pode 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 é exclusiva em termos de valores de entrada e dos parâmetros necessários. A documentação de referência de habilidade descreve todos os parâmetros e propriedades de uma determinada habilidade. Embora haja diferenças, a maioria das habilidades compartilha um conjunto comum e tem um padrão semelhante.

Observação

É possível criar conjuntos de habilidades complexas com loop e ramificação usando a Habilidade condicional para criar as expressões. A sintaxe é baseada na notação de caminho Ponteiro JSON com algumas modificações para identificar nós na árvore de enriquecimento. Um "/" percorre um nível mais baixo na árvore e "*" atua como um operador for-each no contexto. Diversos exemplos neste artigo ilustram a sintaxe.

Definir contexto de habilidade

Cada habilidade tem uma propriedade de contexto que determina o nível em que as operações ocorrem. Se a propriedade "context" não for definida explicitamente, o padrão será "/document", em que 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	Descrição
"context": "/document"	(Padrão) as entradas e saídas estão no nível do documento.
"context": "/document/pages/*"	Algumas habilidades, como a análise de sentimento, têm um desempenho melhor com partes 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.
"context": "/document/normalized_images/*"	Para conteúdo de 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 de Reconhecimento de Entidade retorna uma propriedade chamada "organizations", capturada como orgs. Se o contexto for "/document", um nó "organizações" será adicionado como um filho de "/document". Se você quisesse referenciar esse nó em habilidades downstream, o caminho seria "/document/orgs".

Definir entradas

Habilidades lidas e gravadas em um documento enriquecido. As entradas de habilidade especificam a origem dos dados recebidos. Geralmente, é o nó raiz do documento enriquecido. Para blobs, uma entrada de habilidade típica é a propriedade de conteúdo do documento.

A documentação de referência de habilidades para cada habilidade descreve as entradas que ela pode consumir. Cada entrada tem um "nome" que identifica uma entrada específica e uma "origem" que especifica a localização dos dados no documento enriquecido. O exemplo a seguir é da habilidade de 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 Entidade, as entradas específicas são "text" e "languageCode".

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

Exemplo de fonte	Descrição
"source": "/document"	Para um conjunto de dados tabular, um documento corresponde a uma linha.
"source": "/document/content"	Para blobs, a fonte costuma ser a propriedade de conteúdo do blob.
"source": "/document/some-named-field"	Se as habilidades são baseadas em texto, como reconhecimento de entidade ou extração de frases-chave, a fonte deve ser um campo que contenha texto suficiente para análise, como uma "descrição" ou um "resumo".
"source": "/document/normalized_images/*"	Se o conteúdo é de imagem, a fonte é uma imagem normalizada durante a quebra de documento.

Se a habilidade é iterada em uma matriz, tanto o contexto quanto 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 conjunto de habilidades. Uma saída de habilidade tem um "nome" e um "targetName" opcional.

A documentação de referência de habilidade para cada habilidade descreve as saídas que ele pode produzir. O exemplo a seguir é da habilidade de Reconhecimento de Entidade:

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

As habilidades podem ter várias saídas. O "nome" identifica uma saída específica. Por exemplo, para o Reconhecimento de Entidade, a saída pode ser "pessoas", "locais", "organizações", entre outras.
O "targetName" especifica o nome que você gostaria que esse nó tivesse no documento enriquecido. Isso será útil se as saídas de habilidade tiverem o mesmo nome. Se você tem várias habilidades que retornam a mesma saída, use o "targetName" para desambiguação de nome em caminhos de nó de enriquecimento. Se o nome de destino não for especificado, a propriedade de nome será usada para ambos.

Em algumas situações, é necessário referenciar cada elemento de uma matriz separadamente. Por exemplo, suponha que você queira transmitir cada elemento de "/document/orgs" separadamente para outra habilidade. Para isso, adicione um asterisco ao caminho: "/document/orgs/*".

A saída de habilidade é gravada no documento enriquecido como um novo nó na árvore de enriquecimento. Pode ser um valor simples, como uma pontuação de sentimento ou um 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 de 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 repositório 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, confira Definir uma interface personalizada.

Embora a habilidade personalizada esteja executando código externo ao pipeline, em uma matriz de habilidades, ela é apenas outra habilidade. Assim como as habilidades internas, ela tem tipo, contexto, entradas e saídas. Ela também lê e grava em uma árvore de enriquecimento, assim como as habilidades internas. Observe que o campo "context" está definido como "/document/orgs/*" com um asterisco, o 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. Para fazer referência ao nó em uma etapa downstream (por exemplo, na extração de frases-chave), você usaria o caminho "/document/orgs/*/companyDescription".

{
  "@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, ela geralmente é temporária e existe apenas enquanto a execução de habilidades está em andamento.

Para enviar saídas para um campo em um índice de pesquisa, crie um mapeamento de campo de saída em um indexador.
Se você quiser 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 de origem de entrada da habilidade downstream. Confira Referenciar uma anotação para ver exemplos.

Dicas para o primeiro conjunto de habilidades

Experimente o assistente de Importação de 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 definirá 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 a imagem e o conteúdo de texto que foi separado durante a quebra de documento.

Após a execução do assistente, você pode abrir cada objeto no portal do Azure para exibir sua definição JSON.
Tente Sessões de depuração para invocar a execução do conjunto de habilidades em um documento de destino e inspecionar o documento enriquecido que o conjunto de habilidades cria. Você pode exibir e modificar as configurações e os 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óximas etapas

Os campos de origem de entrada e contexto são caminhos para nós de uma árvore de enriquecimento. Para avançar, conheça melhor a sintaxe de caminho para nós em uma árvore de enriquecimento.

Referenciar anotações em um conjunto de habilidades