Habilidade de API Web personalizada em um pipeline de enriquecimento do Azure AI Search

Artigo
03/10/2024

A habilidade de API Web Personalizada permite que você amplie o enriquecimento de IA chamando um ponto de extremidade de API Web que fornece operações personalizadas. Semelhante a habilidades internas, uma habilidade API Web Personalizada tem entradas e saídas. Dependendo das entradas, sua API Web recebe um conteúdo JSON quando o indexador é executado e gera um conteúdo JSON como uma resposta, juntamente com um código de status de êxito. A resposta deve ter as saídas especificadas pela sua habilidade personalizada. Qualquer outra resposta é considerada um erro e nenhum aprimoramento é executado. A estrutura do payload JSON é descrita mais detalhadamente abaixo neste documento.

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

Observação

O indexador tenta mais duas vezes determinados códigos de status HTTP padrão retornados da API 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 habilidades

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

Nome do parâmetro	Descrição
`uri`	O URI da API Web para o qual o conteúdo JSON é enviado. Somente o esquema do 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 o aplicativo que hospeda o código. A propriedade usa uma ID do aplicativo (cliente) ou o registro do aplicativo no Microsoft Entra ID, em um formato com suporte: `api://<appId>`. Esse valor será usado para definir o escopo do token de autenticação recuperado pelo indexador e enviado junto com a solicitação de API de habilidade da Web personalizada para a função ou aplicativo. Definir essa propriedade requer que seu serviço de pesquisa esteja configurado para identidade gerenciada e seu aplicativo de funções do Azure esteja configurado para um logon do Microsoft Entra. Para usar esse parâmetro, chame a API com `api-version=2023-10-01-Preview`.
`httpMethod`	O método a ser usado ao enviar o conteúdo. Os métodos permitidos são `PUT` ou `POST`
`httpHeaders`	Uma coleção de pares chave-valor em que as chaves representam os nomes de cabeçalho e os valores representam valores de cabeçalho que são enviados para sua API Web, juntamente com o conteúdo. Os seguintes cabeçalhos são proibidos de estarem nesta coleção: `Accept`, `Accept-Charset`, `Accept-Encoding`, `Content-Length`, `Content-Type`, `Cookie`, `Host`, `TE`, `Upgrade`, `Via`.
`timeout`	(Opcional) Quando especificado, indica o tempo limite para o cliente http que fez a chamada à API. Ele deve ser formatado como um valor XSD de "dayTimeDuration" (um subconjunto restrito de um valor de duração ISO 8601 ). Por exemplo, `PT60S` por 60 segundos. Se não for definido, um valor padrão de 30 segundos será escolhido. 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” (veja estrutura de conteúdo JSON abaixo) são enviados por chamada à API. Se não for definido, um padrão de 1.000 será escolhido. É recomendável que você faça uso desse parâmetro para alcançar um equilíbrio adequado entre a taxa de transferência de indexação e de carga em sua API.
`degreeOfParallelism`	(Opcional) Quando especificado, indica o número de chamadas que o indexador faz em paralelo ao ponto de extremidade que você fornece. Você poderá diminuir esse valor se o ponto de extremidade estiver falhando sob pressão ou elevá-lo se o ponto de extremidade conseguir manipular a carga. Se não for definido, um valor padrão de 5 segundos será usado. O `degreeOfParallelism` pode ser definido como um máximo de 10 e um mínimo de 1.

Entradas de habilidades

Não há nenhuma entrada predefinida para essa habilidade. As entradas são qualquer campo existente ou qualquer nó na árvore de enriquecimento que você queira passar para a habilidade personalizada.

Saídas de habilidades

Não há nenhuma saída predefinida para essa habilidade. Defina 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 de exemplo

{
  "@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"
    }
  ]
}

Estrutura JSON de entrada de exemplo

Essa estrutura JSON representa o conteúdo enviado para sua API Web. Ele sempre segue essas restrições:

A entidade de nível superior é chamada values é uma matriz de objetos. O número desses objetos é, no máximo, batchSize.
Cada objeto na matriz values tem:
- Uma propriedade recordId que é uma cadeia de caracteres exclusiva usada para identificar esse registro.
- Uma propriedade data que é um objeto JSON. Os campos da propriedade data correspondem aos “nomes” especificados na seção inputs da definição de habilidade. Os valores desses campos são da source desses campos (que poderia 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": []
           }
      }
    ]
}

Estrutura JSON de saída de exemplo

A "saída" corresponde à resposta retornada da sua API Web. A API Web deve retornar apenas um conteúdo JSON (verificado examinando o cabeçalho de resposta Content-Type) e deve atender às 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 Web.
Cada objeto deve ter:
- Uma propriedade recordId.
- Uma propriedade data, que é um objeto no qual os campos são aprimoramentos correspondendo aos "nomes" no output e cujo valor é considerado o aprimoramento.
- Uma propriedade errors, uma matriz listando os erros encontrados que são adicionados ao histórico de execução do indexador. Essa propriedade é necessária, mas pode ter um valor null.
- Uma propriedade warnings, uma matriz listando os avisos encontrados que são adicionados ao histórico de execução do indexador. Essa propriedade é necessária, mas pode ter um valor null.
A ordenação de objetos no values na solicitação ou na resposta não é importante. No entanto, recordId é usado para correlação, de modo que qualquer registro na resposta que contenha um recordId, que não fazia parte da solicitação original para a API Web, seja 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 Web não estar disponível ou enviar códigos de status sem êxito, os seguintes são considerados casos incorretos:

Se a API Web retornar um código de status de êxito, 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 ausente ou duplicado) na matriz values de resposta, nenhum aprimoramento será executado para os registros inválidos. É importante aderir ao contrato de habilidade da API Web ao desenvolver habilidades personalizadas. Você pode consultar este exemplo fornecido no Repositório do Power Skill que segue o contrato esperado.

Para casos em que a API 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.