Como adicionar uma habilidade personalizada a um pipeline de enriquecimento de Pesquisa Cognitiva do AzureHow to add a custom skill to an Azure Cognitive Search enrichment pipeline

Um pipeline de enriquecimento no Azure pesquisa cognitiva pode ser montado de habilidades cognitivas internas , bem como habilidades personalizadas que você cria pessoalmente e adiciona ao pipeline.An enrichment pipeline in Azure Cognitive Search can be assembled from built-in cognitive skills as well as custom skills that you personally create and add to the pipeline. Neste artigo, saiba como criar uma habilidade personalizada que expõe uma interface que permite que ela seja incluída em um pipeline de enriquecimento de ia.In this article, learn how to create a custom skill that exposes an interface allowing it to be included in an AI enrichment pipeline.

Criar uma habilidade personalizada oferece a você uma maneira de adicionar transformações únicas ao seu conteúdo.Building a custom skill gives you a way to insert transformations unique to your content. Uma habilidade personalizada será executada de forma independente, aplicando qualquer etapa de enriquecimento que você precisar.A custom skill executes independently, applying whatever enrichment step you require. Por exemplo, você poderá definir entidades personalizadas específicas por campo, 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.For example, you could define field-specific custom entities, build custom classification models to differentiate business and financial contracts and documents, or add a speech recognition skill to reach deeper into audio files for relevant content. Para obter um exemplo passo a passo, consulte exemplo: criando uma habilidade personalizada para o enriquecimento de ia.For a step-by-step example, see Example: Creating a custom skill for AI enrichment.

Para qualquer recurso personalizado que você precisar, haverá uma interface simples e clara para conectar uma habilidade personalizada ao resto do pipeline de enriquecimento.Whatever custom capability you require, there is a simple and clear interface for connecting a custom skill to the rest of the enrichment pipeline. O único requisito para a inclusão em um conjunto de qualificações é a capacidade de aceitar entradas e saídas de maneiras que possam ser utilizadas no conjunto de qualificações como um todo.The only requirement for inclusion in a skillset is the ability to accept inputs and emit outputs in ways that are consumable within the skillset as a whole. O foco deste artigo é sobre os formatos de entrada e saída exigidos pelo pipeline de enriquecimento.The focus of this article is on the input and output formats that the enrichment pipeline requires.

Interface de habilidades personalizadas da API da WebWeb API custom skill interface

Personalize os pontos de extremidade da habilidade da API da Web por tempo limite padrão caso eles não retornem uma resposta dentro de uma janela de 30 segundos.Custom WebAPI skill endpoints by default timeout if they don't return a response within a 30 second window. 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 intervalo.The indexing pipeline is synchronous and indexing will produce a timeout error if a response is not received in that window. É possível configurar o tempo limite para até 230 segundos, definindo o parâmetro timeout:It is possible to configure the timeout to be up to 230 seconds, by setting the timeout parameter:

        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "description": "This skill has a 230 second timeout",
        "uri": "https://[your custom skill uri goes here]",
        "timeout": "PT230S",

Verifique se o URI é seguro (HTTPS).Make sure the URI is secure (HTTPS).

Atualmente, o único mecanismo para interagir com uma habilidade personalizada é por meio de uma interface da API da Web.Currently, the only mechanism for interacting with a custom skill is through a Web API interface. A API da Web precisa atender aos requisitos descritos nesta seção.The Web API needs must meet the requirements described in this section.

1. formato de entrada da API Web1. Web API Input Format

A API da Web deve aceitar uma matriz de registros a serem processados.The Web API must accept an array of records to be processed. Cada registro deve conter um “recipiente de propriedades” que é a entrada fornecida à API da Web.Each record must contain a "property bag" that is the input provided to your Web API.

Suponha que você deseja criar um enriquecedor simples que identifica a primeira data mencionada no texto de um contrato.Suppose you want to create a simple enricher that identifies the first date mentioned in the text of a contract. Neste exemplo, a habilidade aceita uma única entrada contractText como o texto do contrato.In this example, the skill accepts a single input contractText as the contract text. A habilidade também tem uma única saída, que é a data do contrato.The skill also has a single output, which is the date of the contract. Para tornar o enriquecedor mais interessante, retorne este contractDate na forma de um tipo complexo de várias partes.To make the enricher more interesting, return this contractDate in the shape of a multi-part complex type.

Sua API da Web deve estar pronta para receber um lote de registros de entrada.Your Web API should be ready to receive a batch of input records. Cada membro da matriz de valores representa a entrada de um registro específico.Each member of the values array represents the input for a particular record. Cada registro deve ter os seguintes elementos:Each record is required to have the following elements:

  • Um membro recordId que é o identificador exclusivo de um registro específico.A recordId member that is the unique identifier for a particular record. Quando seu enriquecedor retornar os resultados, ele deve fornecer este recordId para permitir que o chamador corresponda aos resultados do registro de entrada.When your enricher returns the results, it must provide this recordId in order to allow the caller to match the record results to their input.

  • Um membro dos dados, que é essencialmente um recipiente de campos de entrada para cada registro.A data member, which is essentially a bag of input fields for each record.

Para ser mais concreto, conforme o exemplo acima, a API da Web deve esperar solicitações com esta aparência:To be more concrete, per the example above, your Web API should expect requests that look like this:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issues on November 3, 2017 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 realidade, o serviço pode ser chamado com centenas ou milhares de registros em vez de apenas os três mostrados aqui.In reality, your service may get called with hundreds or thousands of records instead of only the three shown here.

2. formato de saída da API Web2. Web API Output Format

O formato da saída é um conjunto de registros que contêm um recordId e um recipiente de propriedadesThe format of the output is a set of records containing a recordId, and a property bag

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

Esse exemplo específico tem apenas uma saída, mas você pode gerar mais de uma propriedade.This particular example has only one output, but you could output more than one property.

Erros e AvisoErrors and Warning

Conforme mostrado no exemplo anterior, você pode retornar mensagens de erro e de aviso para cada registro.As shown in the previous example, you may return error and warning messages for each record.

Utilizando qualificações personalizadas do conjunto de qualificaçõesConsuming custom skills from skillset

Ao criar um enriquecedor da API da Web, você pode descrever parâmetros e cabeçalhos HTTP como parte da solicitação.When you create a Web API enricher, you can describe HTTP headers and parameters as part of the request. O trecho de código a seguir mostra como os parâmetros de solicitação e os cabeçalhos HTTP opcionais podem ser descritos como parte da definição do congrau de habilidade.The snippet below shows how request parameters and optional HTTP headers may be described as part of the skillset definition. Os cabeçalhos HTTP não são um requisito, mas permitem que você adicione recursos de configuração adicionais à sua habilidade e defina-os a partir da definição de conjunto de qualificações.HTTP headers are not a requirement, but they allow you to add additional configuration capabilities to your skill and to set them from the skillset definition.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "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"
          }
        ]
      }
  ]
}

Próximas etapasNext steps

Este artigo abordou os requisitos de interface necessários para integrar uma habilidade personalizada em um contratador de habilidades.This article covered the interface requirements necessary for integrating a custom skill into a skillset. Clique nos links a seguir para saber mais sobre habilidades personalizadas e composição do contratador de habilidades.Click the following links to learn more about custom skills and skillset composition.