Adicionar uma habilidade personalizada a um pipeline de enriquecimento do Pesquisa de IA do Azure 

Um pipeline de enriquecimento de IA pode incluir habilidades internas e habilidades personalizadas que você cria e publica. Seu código personalizado é executado fora do serviço de pesquisa (por exemplo, como uma função Azure), mas aceita entradas e envia saídas para o conjunto de habilidades, assim como qualquer outra habilidade. Seus dados são processados na geography em que o modelo é implantado.

Habilidades personalizadas podem parecer complexas, mas podem ser simples de implementar. Se você tiver pacotes existentes que fornecem modelos de correspondência ou classificação de padrões, você poderá passar conteúdo extraído de blobs para esses modelos para processamento. Como o enriquecimento de IA é baseado em Azure, você também deve hospedar seu modelo no Azure. As opções comuns de hospedagem incluem Azure Functions ou containers.

Se você estiver criando uma habilidade personalizada, este artigo descreve a interface que você deve usar para integrar a habilidade ao pipeline. O principal requisito é a capacidade de aceitar entradas e emitir saídas de maneiras que o conjunto de habilidades pode consumir como um todo. Sendo assim, o foco deste artigo é sobre os formatos de entrada e saída exigidos pelo pipeline de enriquecimento.

Benefícios de habilidades personalizadas

Criar uma habilidade personalizada oferece a você uma maneira de adicionar transformações únicas ao seu conteúdo. Por exemplo, você poderá compilar modelos de classificação personalizada para diferenciar contratos e documentos financeiros e corporativos, ou adicionar uma habilidade de reconhecimento de fala para ir ainda mais longe com arquios de áudio para conteúdos relevantes. Para obter um exemplo passo a passo, consulte Exemplo: criando uma habilidade personalizada para enriquecimento de IA.

Definir o ponto de extremidade e o intervalo de tempo limite

Especifique a interface para uma habilidade personalizada por meio da habilidade de API Web Personalizada.

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230-second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

A URI é o ponto de extremidade HTTPS da sua função ou aplicativo. Ao definir o URI, certifique-se de que o URI seja seguro (HTTPS). Se você hospedar seu código em um aplicativo de funções Azure, inclua uma chave de API no cabeçalho ou como um parâmetro de URI no URI para autorizar a solicitação.

Se sua função ou aplicativo usa as identidades gerenciadas do Azure e as funções do Azure para autenticação e autorização, a habilidade personalizada pode incluir um token de autenticação na requisição. Os seguintes pontos descrevem os requisitos para essa abordagem:

• O serviço de pesquisa, que envia a solicitação em nome do indexador, deve ser configurado para usar uma identidade gerenciada (sistema ou atribuído pelo usuário) para que Microsoft Entra ID possa autenticar o chamador.

• Você deve configurar sua função ou aplicativo para Microsoft Entra ID.

• Sua definição de habilidade personalizadadeve incluir uma propriedade authResourceId. Essa propriedade utiliza um ID de aplicativo (cliente), em um formato suportado: api://<appId>.

Verifique se isso uri aponta para o ponto de extremidade do aplicativo identificado por authResourceId. Valores incompatíveis podem causar falhas de autenticação ou solicitações que estão sendo enviadas para um ponto de extremidade não intencional. Para obter diretrizes de segurança, práticas recomendadas e etapas para verificar sua configuração, consulte as considerações de segurança para autenticação de identidade gerenciada.

Por padrão, a conexão com o ponto de extremidade atingirá o tempo limite se uma resposta não for retornada em uma janela de 30 segundos (PT30S). O pipeline de indexação é síncrono, e a indexação produz um erro de tempo limite se uma resposta não for recebida nesse intervalo de tempo. Você pode aumentar o intervalo para um valor máximo de 230 segundos definindo o parâmetro timeout (PT230S).

Se um ponto de extremidade protegido por restrições de acesso IP não responder, defina timeout temporariamente como um valor curto, como PT10S, para exibir o erro de tempo limite mais rapidamente. Para um aplicativo de funções Azure, gerencie as regras de IP de entrada nasrestrições de Acesso> de >. Para que os endereços IP permitam, consulte Configurar regras de firewall de IP para permitir conexões de indexador.

Formatar entradas de API Web

A API Web deve aceitar uma matriz de registros para processar. Em cada registro, forneça um conjunto de propriedades como entrada na sua API Web.

Suponha que você queira criar um enriquecidor básico que identifique a primeira data mencionada no texto do contrato. Neste exemplo, a habilidade personalizada aceita uma única entrada. contractText A habilidade também tem uma única saída, que é a data do contrato. Para tornar o enriquecedor mais interessante, retorne contractDate na forma de um tipo complexo multiparte.

Sua API Web deve estar pronta para receber um lote de registros de entrada. Cada membro da values matriz representa a entrada para um registro específico. Cada registro deve ter os seguintes elementos:

• Um recordId membro que é o identificador exclusivo de um determinado registro. Quando o seu enriquecedor retornar resultados, ele deverá fornecer esse recordId para que o chamador possa corresponder resultados de registros com as entradas.

• Um data elemento, que é um conjunto de campos de entrada para cada registro.

A solicitação de API Web resultante pode ter esta aparência:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issued on November 3, 2023 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

Na prática, o código pode ser chamado com centenas ou milhares de registros em vez de apenas os três mostrados aqui.

Formatar saídas de API Web

O formato de saída é um conjunto de registros que contêm um recordId e um conjunto de propriedades. Este exemplo específico tem apenas uma saída, mas você pode retornar mais de uma propriedade. Como prática recomendada, considere retornar mensagens de erro e aviso se um registro não puder ser processado.

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2023 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

Adicionar uma habilidade personalizada a um conjunto de habilidades

Ao criar um enriquecidor de API Web, você pode definir cabeçalhos HTTP e parâmetros como parte da solicitação. O snippet a seguir mostra como os parâmetros de solicitação e os cabeçalhos HTTP opcionais podem ser incluídos na definição do conjunto de habilidades. Definir um cabeçalho HTTP será útil se você precisar passar as definições de configuração para seu código.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

Assista a este vídeo

Para ver uma introdução e demonstração em vídeo, assista à demonstração a seguir.

Próximas etapas

Este artigo cobriu os requisitos de interface necessários para a integração de uma habilidade personalizada em um conjunto de habilidades. Para saber mais sobre habilidades personalizadas e composição do conjunto de habilidades, confira os seguintes recursos:

• Power Skills: um repositório de habilidades personalizadas
• Exemplo: como criar uma habilidade personalizada para enriquecimento de IA
• Como definir um conjunto de qualificações
• Criar conjunto de habilidades (REST)
• Como mapear campos enriquecidos