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

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.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parâmetros de habilidade

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

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.

Consulte também

• Definir um conjunto de competências
• Adicionar habilidade personalizada a um pipeline de enriquecimento de IA
• Exemplo: Criando uma habilidade personalizada para enriquecimento de IA
• Repositório Power Skill