Habilidade de API Web personalizada em um pipeline de enriquecimento de Pesquisa de IA do Azure

Artigo
03/06/2024

A habilidade de API da Web personalizada permite que você estenda o enriquecimento da IA chamando para um ponto de extremidade da API da Web fornecendo operações personalizadas. Semelhante às habilidades internas, uma habilidade de API Web personalizada tem entradas e saídas. Dependendo das entradas, sua API Web recebe uma carga JSON quando o indexador é executado e gera uma carga JSON como resposta, juntamente com um código de status de sucesso. Espera-se que a resposta tenha as saídas especificadas pela sua habilidade personalizada. Qualquer outra resposta é considerada um erro e nenhum enriquecimento é realizado. A estrutura da carga JSON é descrita mais abaixo neste documento.

A habilidade API Web personalizada também é usada na implementação do recurso Azure OpenAI On Your Data . Se o Azure OpenAI estiver configurado para acesso baseado em função e você receber 403 Forbidden chamadas ao criar o índice vetorial, verifique se o Azure AI Search tem uma identidade atribuída ao sistema e é executado como um serviço confiável no Azure OpenAI.

Nota

O indexador tenta novamente duas vezes para determinados códigos de status HTTP padrão retornados da API da Web. Esses códigos de status HTTP são:

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parâmetros de habilidade

Os parâmetros diferenciam maiúsculas de minúsculas.

Nome do parâmetro	Description
`uri`	O URI da API Web para a qual a carga JSON é enviada. Somente o esquema de URI https é permitido.
`authResourceId`	(Opcional) Uma cadeia de caracteres que, se definida, indica que essa habilidade deve usar uma identidade gerenciada na conexão com a função ou aplicativo que hospeda o código. Esta propriedade leva um ID de aplicativo (cliente) ou registro do aplicativo no Microsoft Entra ID, em um formato suportado: `api://<appId>`. Esse valor é usado para definir o escopo do token de autenticação recuperado pelo indexador e é enviado junto com a solicitação personalizada da API de habilidade da Web para a função ou aplicativo. A definição dessa propriedade requer que seu serviço de pesquisa esteja configurado para identidade gerenciada e seu aplicativo de função do Azure esteja configurado para uma entrada do Microsoft Entra. Para usar esse parâmetro, chame a API com `api-version=2023-10-01-Preview`.
`httpMethod`	O método a utilizar durante o envio da carga. Os métodos permitidos são `PUT` ou `POST`
`httpHeaders`	Uma coleção de pares chave-valor em que as chaves representam nomes de cabeçalho e valores representam valores de cabeçalho que são enviados para sua API da Web junto com a carga útil. Os seguintes cabeçalhos são proibidos de estar nesta coleção: `Accept`, `Accept-Charset`, `Accept-Encoding`, `Content-Length`, `Content-Type`, `Cookie`, `Host`, `TEUpgrade`, . `Via`
`timeout`	(Opcional) Quando especificado, indica o tempo limite para o cliente http que faz a chamada de API. Ele deve ser formatado como um valor XSD "dayTimeDuration" (um subconjunto restrito de um valor de duração ISO 8601). Por exemplo, `PT60S` durante 60 segundos. Se não estiver definido, será escolhido um valor padrão de 30 segundos. O tempo limite pode ser definido para um máximo de 230 segundos e um mínimo de 1 segundo.
`batchSize`	(Opcional) Indica quantos "registros de dados" (consulte a estrutura de carga JSON abaixo) são enviados por chamada de API. Se não estiver definido, um padrão de 1000 será escolhido. Recomendamos que você use esse parâmetro para obter uma compensação adequada entre a taxa de transferência de indexação e a carga em sua API.
`degreeOfParallelism`	(Opcional) Quando especificado, indica o número de chamadas que o indexador faz em paralelo com o ponto de extremidade fornecido. Você pode diminuir esse valor se o endpoint estiver falhando sob pressão, ou aumentá-lo se o endpoint puder lidar com a carga. Se não estiver definido, um valor padrão de 5 será usado. O `degreeOfParallelism` pode ser ajustado para um máximo de 10 e um mínimo de 1.

Contributos para as competências

Não há entradas predefinidas para esta habilidade. As entradas são qualquer campo existente ou qualquer nó na árvore de enriquecimento que você deseja passar para sua habilidade personalizada.

Resultados em termos de competências

Não há saídas predefinidas para essa habilidade. Certifique-se de definir um mapeamento de campo de saída no indexador se a saída da habilidade deve ser enviada para um campo no índice de pesquisa.

Definição da amostra

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

Exemplo de estrutura JSON de entrada

Essa estrutura JSON representa a carga que é enviada para sua API da Web. Segue sempre estas restrições:

A entidade de nível superior é chamada values e é uma matriz de objetos. O número de tais objetos é, no máximo, o batchSize.
Cada objeto na values matriz tem:
- Uma recordId propriedade que é uma cadeia de caracteres exclusiva , usada para identificar esse registro.
- Uma data propriedade que é um objeto JSON. Os campos da data propriedade correspondem aos "nomes" especificados na inputs seção da definição de habilidade. Os valores desses campos são dos source campos (que podem ser de um campo no documento ou, potencialmente, de outra habilidade).

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

Exemplo de estrutura JSON de saída

A "saída" corresponde à resposta retornada da sua API Web. A API da Web só deve retornar uma carga JSON (verificada observando o cabeçalho de Content-Type resposta) e deve satisfazer as seguintes restrições:

Deve haver uma entidade de nível superior chamada values, que deve ser uma matriz de objetos.
O número de objetos na matriz deve ser o mesmo que o número de objetos enviados para a API da Web.
Cada objeto deve ter:
- Uma recordId propriedade.
- Uma data propriedade, que é um objeto onde os campos são enriquecimentos correspondentes aos "nomes" no output e cujo valor é considerado o enriquecimento.
- Uma errors propriedade, uma matriz que lista todos os erros encontrados que são adicionados ao histórico de execução do indexador. Esta propriedade é necessária, mas pode ter um null valor.
- Uma warnings propriedade, uma matriz que lista todos os avisos encontrados que são adicionados ao histórico de execução do indexador. Esta propriedade é necessária, mas pode ter um null valor.
A ordenação dos objetos na values solicitação ou na resposta não é importante. No entanto, o recordId é usado para correlação, portanto, qualquer registro na resposta que contenha um recordId, que não fazia parte da solicitação original para a API da Web é descartado.

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

Casos de erro

Além de sua API da Web estar indisponível ou enviar códigos de status sem sucesso, os seguintes são considerados casos errados:

Se a API da Web retornar um código de status de sucesso, mas a resposta indicar que não application/json é, a resposta será considerada inválida e nenhum enriquecimento será executado.
Se houver registros inválidos (por exemplo, recordId está faltando ou duplicado) na matriz de resposta values , nenhum enriquecimento será executado para os registros inválidos. É importante aderir ao contrato de habilidades da API Web ao desenvolver habilidades personalizadas. Você pode consultar este exemplo fornecido no repositório Power Skill que segue o contrato esperado.

Para casos em que a API da Web não está disponível ou retorna um erro HTTP, um erro amigável com todos os detalhes disponíveis sobre o erro HTTP é adicionado ao histórico de execução do indexador.