Adicione uma skill personalizada a um pipeline de enriquecimento do Pesquisa de IA do Azure

Um pipeline de enriquecimento de IA pode incluir tanto competências incorporadas como competências personalizadas que cria e publica. O teu código personalizado corre fora do serviço de pesquisa (por exemplo, como uma função do Azure), mas aceita entradas e envia saídas para o conjunto de competências como qualquer outra competência. Os seus dados são processados na geografia onde o seu modelo é implementado.

Competências personalizadas podem parecer complexas, mas podem ser simples de implementar. Se tiver pacotes existentes que fornecem correspondência de padrões ou modelos de classificação, pode passar conteúdo extraído de blobs para esses modelos para processamento. Como o enriquecimento de IA é baseado no Azure, também deve hospedar o seu modelo no Azure. Opções comuns de alojamento incluem Funções do Azure ou contentores.

Se você estiver criando uma habilidade personalizada, este artigo descreve a interface que você usa para integrar a habilidade no pipeline. O requisito principal é a capacidade de aceitar entradas e emitir saídas de formas que o conjunto de competências possa consumir como um todo. Como tal, o foco deste artigo está nos formatos de entrada e saída que o pipeline de enriquecimento requer.

Benefícios das habilidades personalizadas

Construir uma habilidade personalizada dá-lhe uma forma de inserir transformações únicas no seu conteúdo. Por exemplo, pode compilar modelos de classificação personalizados para diferenciar contratos e documentos empresariais e financeiros ou adicionar uma competência de reconhecimento de voz para aceder mais detalhadamente aos ficheiros de áudio para obter conteúdo relevante. Para obter um exemplo passo a passo, consulte Exemplo: Criando uma habilidade personalizada para enriquecimento de IA.

Definir o ponto final e o intervalo de tempo

Especifique a interface para uma aptidão personalizada através da aptidão 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 da sua função ou aplicativo. Ao definir o URI, verifique se o URI é seguro (HTTPS). Se hospedar o seu código numa aplicação de funções do Azure, inclua uma chave API no cabeçalho ou como parâmetro URI no URI para autorizar o pedido.

Se a sua função ou aplicação usar identidades geridas pelo Azure e papéis Azure para autenticação e autorização, a habilidade personalizada pode incluir um token de autenticação no pedido. Os pontos seguintes descrevem os requisitos para esta abordagem:

• O serviço de pesquisa, que envia o pedido em nome do indexador, deve ser configurado para usar uma identidade gerida (seja do sistema ou atribuída pelo utilizador) para que o Microsoft Entra ID possa autenticar o chamador.

• Deve configurar a sua função ou aplicação para o Microsoft Entra ID.

• Sua definição de habilidade personalizada deve incluir uma authResourceId propriedade. Esta propriedade recebe um ID de aplicação (cliente), num formato suportado: api://<appId>.

Certifique-se de que uri aponta para o ponto final da aplicação identificado por authResourceId. Valores inadequados podem causar falhas de autenticação ou pedidos enviados para um endpoint não intencional. Para orientações de segurança, práticas recomendadas e passos para verificar a sua configuração, consulte Considerações de Segurança para autenticação de identidade gerida.

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

Se um endpoint protegido por restrições de acesso IP não responder, defina timeout temporariamente um valor curto, como PT10S, para mostrar o erro de timeout mais rapidamente. Para uma aplicação de funções do Azure, gere as regrasde IP de entrada em >>. Para os endereços IP a permitir, veja Configurar regras de firewall IP para permitir ligações ao indexador.

Formatar entradas de API da web

A API web deve aceitar um conjunto de registos para processar. Dentro de cada registo, forneça um conjunto de propriedades como entrada na sua API web.

Suponha que quer criar um enriquecedor básico que identifique a primeira data mencionada no texto do contrato. Neste exemplo, a habilidade personalizada aceita uma única entrada, contractText. A competência também tem uma única saída, que é a data do contrato. Para tornar o enriquecedor mais interessante, devolva contractDate sob a forma de um tipo complexo composto por várias partes.

A sua API web deve estar pronta para receber um lote de registos de entrada. Cada membro do values array representa a entrada para um registo específico. Cada registo deve conter os seguintes elementos:

• Um recordId membro que é o identificador único para um determinado registo. Quando o seu enriquecedor devolve resultados, deve fornecer isso recordId para que o chamador possa associar os resultados dos registos às entradas.

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

O pedido de API web resultante pode ser assim:

{
    "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, seu código pode ser chamado com centenas ou milhares de registros em vez de apenas os três mostrados aqui.

Formatar as saídas da API web

O formato de saída é um conjunto de registos que contém um recordId e um conjunto de propriedades. Este exemplo em particular tem apenas uma saída, mas pode devolver mais do que 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

Quando cria um enricher de API web, pode definir cabeçalhos e parâmetros HTTP como parte do pedido. O trecho a seguir mostra como os parâmetros de solicitação e cabeçalhos HTTP opcionais podem ser incluídos na definição do conjunto de habilidades. Definir um cabeçalho HTTP é útil se você precisar passar 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"
          }
        ]
      }
  ]
}

Veja este vídeo

Para um vídeo de introdução e demonstração, assista à demonstração a seguir.

Próximos passos

Este artigo abordou os requisitos de interface necessários para integrar uma habilidade personalizada em um conjunto de habilidades. Para saber mais sobre competências personalizadas e composição de conjuntos de competências, consulte os seguintes recursos:

• Power Skills: um repositório de competências personalizadas
• Exemplo: Criando uma habilidade personalizada para enriquecimento de IA
• Como definir um conjunto de competências
• Criar conjunto de habilidades (REST)
• Como mapear campos enriquecidos