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

  • Artigo

Um pipeline de enriquecimento de IA pode incluir habilidades embutidas e habilidades personalizadas que você cria e publicada pessoalmente. Seu código personalizado é executado externamente do serviço de pesquisa (por exemplo, como uma função do Azure), mas aceita entradas e envia saídas para o conjunto de habilidades, assim como qualquer outra habilidade.

As habilidades personalizadas podem parecer complexas, mas sua implementação é simples e direta. Se você tiver pacotes que oferecem modelos de classificação ou correspondência de padrões, o conteúdo extraído dos blobs poderá ser passado para esses modelos para processamento. Como o enriquecimento de IA é baseado no Azure, seu modelo também deve estar no Azure. Algumas metodologias de hospedagem comuns incluem o uso de Azure Functions ou contêineres.

Se você criar uma habilidade personalizada, este artigo descreve a interface que você deve usar para integrar a habilidade ao pipeline. O único requisito é a capacidade de aceitar entradas e saídas de maneiras que possam ser utilizadas no conjunto de qualificações 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 domínios personalizados

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-tempo

A interface para uma habilidade personalizada é especificada 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",

O URI é o ponto de extremidade HTTPS de sua função ou aplicativo. Ao definir o URI, certifique-se de que o URI seja seguro (HTTPS). Se o seu código estiver hospedado em um aplicativo de funções do Azure, o URI deverá incluir uma chave de API no cabeçalho ou como um parâmetro de URI para autorizar a solicitação.

Se, em vez disso, sua função ou aplicativo usar identidades gerenciadas do Azure e funções do Azure para autenticação e autorização, a habilidade personalizada poderá incluir um token de autenticação na solicitação. Os seguintes pontos descrevem os requisitos para essa abordagem:

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 produzirá um erro de tempo limite se a resposta não for recebida nesse período. Você pode aumentar o intervalo para um valor máximo de 230 segundos definindo o parâmetro de tempo limite (PT230S).

Formatar entradas da API Web

A API da Web deve aceitar uma matriz de registros a serem processados. Em cada registro, forneça um recipiente de propriedades como entrada para sua API Web.

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

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

  • Um membro "recordId" que é o identificador exclusivo de um registro específico. Quando seu enriquecedor retornar os resultados, ele deve fornecer este "recordId" para permitir que o chamador corresponda aos resultados do registro de entrada.

  • Um membro dos "dados", que é essencialmente um recipiente 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 issues 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 da API Web

O formato da saída é um conjunto de registros que contêm um "recordId" e um recipiente de propriedades Esse exemplo específico tem apenas uma saída, mas você pode gerar 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 enriquecedor da API da Web, você pode descrever parâmetros e cabeçalhos HTTP 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. Clique nos links a seguir para saber mais sobre habilidades personalizadas e composição do conjunto de habilidades.