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

Um conjunto de habilidades define operações que geram conteúdo e estrutura vetorial e textual a partir de documentos que contêm imagens ou conteúdo bruto. Exemplos são habilidades de fragmentação, habilidades de incorporação (vetorização), verbalização de imagem e outros processos, como reconhecimento ótico de caracteres (OCR) para imagens, reconhecimento de entidade para texto indiferenciado e tradução de texto. Um conjunto de habilidades é executado depois que o conteúdo bruto é extraído 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:

• Deve ter um nome exclusivo dentro da coleção de competências. Um conjunto de competências é um recurso de topo que qualquer indexador pode utilizar.
• Deve ter 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, um conjunto de habilidades pode ter várias habilidades de Shaper.
• Um conjunto de competências suporta operações encadeadas, loops e ramificação.

Associe um conjunto de competências a um indexador. Para usar o conjunto de habilidades, faça referência a ele em um indexador e, em seguida, execute o indexador para importar dados, invocar o processamento de habilidades e enviar a saída para um índice. Um conjunto de competências é um recurso de alto nível, mas só funciona dentro do processamento do indexador. Como um recurso de alto nível, você pode fazer referência a ele em vários indexadores.

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

Quando cria um conjunto de competências, adiciona-o ao seu serviço de pesquisa. Quando atualizas um conjunto de competências, sobrescreves totalmente um conjunto de competências existente com o conteúdo da carga útil do pedido. Para atualizar um conjunto de competências, recupere a definição do conjunto usando GET, modifique-a e depois atualize-a usando PUT.

Comece pela estrutura básica. Na API Create Skillset REST, crie o corpo do pedido em JSON. 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 Microsoft Foundry resource in the same region as Azure AI Search",
      "key":"<Your-Microsoft-Foundry-Resource-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 não ordenada de habilidades. As competências são autónomas ou encadeadas através de associações de entradas-saídas, em que a saída de uma transformação se torna entrada para outra. As competências podem ser utilitárias (como partir texto), transformacionais (baseadas em IA do Azure OpenAI ou Foundry Tools), ou competências personalizadas que forneças. Um exemplo de uma matriz de habilidades é fornecido na próxima seção.

• cognitiveServices é usado para competências faturáveis que chamam APIs das Foundry Tools. Remova esta seção caso não utilize competências faturáveis ou Pesquisa de Entidade Personalizada. Se estiveres, anexa um recurso da Foundry.

• 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. Remove esta secção se não precisares. 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.

Definir contexto de habilidades

Cada habilidade tem uma propriedade de contexto que determina o nível em que as operações ocorrem. Se a context propriedade 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": []
  }
]

Defina a context propriedade para um dos seguintes exemplos:

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ó organizations é adicionado como filho de "/document". Se quiser fazer referência a este nó em competências downstream, o caminho é "/document/orgs".

Definir entradas

Capacidades de ler e escrever num documento enriquecido. As entradas de habilidades especificam a origem dos dados recebidos. Freqüentemente, é o nó raiz do documento ampliado. No caso de blobs, uma entrada típica de habilidade é a propriedade de conteúdo do documento.

A documentação de referência de habilidades para cada habilidade descreve os insumos que ela pode consumir. Cada entrada tem um name que identifica uma entrada específica e um source que especifica o local 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 name é o input específico. Para Reconhecimento de Entidade, as entradas específicas são text e languageCode.

• A source propriedade 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
  source: /document	Para um conjunto de dados tabulares, um documento corresponde a uma linha.
  source: /document/content	Em relação aos blobs, a fonte geralmente é a propriedade de conteúdo do blob.
  source: /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.
  source: /document/normalized_images/*	Para o conteúdo de imagem, a fonte é a imagem que foi normalizada durante o processamento 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. Para obter mais informações sobre a sintaxe completa, consulte Contexto de habilidade e linguagem de anotação de entrada.

Definir saídas

Cada competência é concebida para emitir tipos específicos de resultados, que o conjunto de competências refere pelo nome. Uma saída de habilidade tem um name e um opcional targetName.

A documentação de referência de competências para cada competência descreve os resultados que 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. A name propriedade identifica uma saída específica. Por exemplo, para o Reconhecimento de Entidades, a saída pode ser pessoas, locais, organizações, entre outros.

• A propriedade targetName especifica o nome que pretende atribuir a este nó no documento enriquecido. Esta propriedade é útil se as saídas de habilidades tiverem o mesmo nome. Se tiver várias habilidades que retornam a mesma saída, use targetName para desambiguação de nomes em caminhos dos nós de enriquecimento. Se não especificares o nome alvo, a propriedade de nome é 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 de "/document/orgs" separadamente para outra competência. Para fazer isso, adicione um asterisco ao caminho: "/document/orgs/*".

O resultado das capacidades é gravado 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 Adicionar uma habilidade personalizada a um pipeline de enriquecimento do Pesquisa de IA do Azure.

Embora a habilidade personalizada execute 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 context está definido como "/document/orgs/*" com um asterisco, o que significa que a etapa de enriquecimento é chamada para cada organização sob "/document/orgs".

O resultado, como a descrição da empresa neste exemplo, é gerado para cada organização identificada. Ao referir-se ao nó numa etapa posterior (por exemplo, na extração de palavras-chave), use o caminho "/document/orgs/*/companyDescription" para tal.

{
  "@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=<YOUR-FUNCTION-KEY>",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "<YOUR-APIM-KEY>"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

Enviar saída para um destino

Embora possa opcionalmente armazenar em cache o resultado das competências para reutilização, este é geralmente temporário e existe apenas enquanto a execução das competências decorre.

• 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

• Experimenta o assistente de importação de dados.

  O assistente automatiza várias etapas que podem ser desafiantes à 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 capacidades, como OCR ou análise de imagem, o assistente adiciona ferramentas utilitárias que mesclam o conteúdo de imagem e texto que foram separados durante a análise de documentos.

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

• Tente utilizar as Sessões de depuração para invocar a execução do skillset sobre um documento de destino e inspecionar o documento enriquecido que o skillset 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óximo passo

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