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

Use a competência Custom Web API para estender o enriquecimento da IA, chamando um endpoint Web API que forneça operações personalizadas. Tal como as competências integradas, uma competência de API Web Personalizada tem entradas e saídas. Dependendo das entradas, a sua Web API recebe um payload JSON quando o indexador corre, e devolve um payload JSON como resposta, juntamente com um código de estado de sucesso. A resposta deve incluir os resultados especificados pela tua competência personalizada. Qualquer outra resposta é considerada um erro e nenhum enriquecimento é realizado. A estrutura da carga útil JSON é descrita mais adiante neste documento.

A competência Custom Web API também é utilizada na implementação da funcionalidade Azure OpenAI On Your Data. Se o Azure OpenAI estiver configurado para acesso baseado em funções e tiver 403 Forbidden erros ao criar o índice vetorial, verifique se o Pesquisa de IA do Azure tem uma identidade atribuída ao sistema e corre como um serviço de confiança no Azure OpenAI.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parâmetros de habilidade

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

Compreende o authResourceId valor

Quando uma competência Custom Web API utiliza autenticação de identidade gerida, o Pesquisa de IA do Azure obtém um token de acesso Microsoft Entra e envia-o para o endpoint da skill personalizada. A authResourceId propriedade especifica o identificador de recurso, também conhecido como audience ou URI de ID de aplicação, para o qual o token é solicitado. O valor deve corresponder ao que a aplicação alvo espera durante a validação do token. Caso contrário, a autenticação falha com uma 401 Unauthorized resposta.

O authResourceId valor identifica a aplicação que hospeda a sua competência personalizada. Não é o URL do seu serviço de pesquisa ou indexador.

A tabela seguinte mostra os formatos comuns:

A propriedade aceita formatos com e sem o .default sufixo de âmbito (scope suffix). Use api://<appId> para corresponder diretamente ao URI do ID da Aplicação. Se incluir um .default sufixo, como api://<appId>/.default, a reivindicação aud do token de acesso contém o URI base do ID da Aplicação sem o sufixo.

Para os passos para configurar a autenticação Microsoft Entra para uma Função Azure e definir authResourceId, veja Usar uma identidade gerida de serviço de pesquisa para se ligar a uma aplicação Azure Function.

Exemplo: Azure Function protegido pelo Microsoft Entra ID

Neste exemplo, o Pesquisa de IA do Azure adquire um token de acesso para o público especificado por authResourceId e inclui o token ao invocar o endpoint personalizado da habilidade.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso-function.azurewebsites.net/api/enrich",
  "authResourceId": "api://contoso-customskill"
}

Entradas de habilidades

Esta competência não tem entradas pré-definidas. 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

Esta competência não tem saídas predefinidas. 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"
    }
  ]
}

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso.example.org/api?code=<redacted>",
  "httpMethod": "POST",
  "name": "myCustomSkill",
  "httpHeaders": {
    "Authorization": "<redacted>",
    "Ocp-Apim-Subscription-Key": "<redacted>"
  }
}

{
  "uri": "<unchanged>",
  "httpHeaders": {
    "Authorization": "<unchanged>",
    "Ocp-Apim-Subscription-Key": "<unchanged>"
  }
}

Exemplo de estrutura JSON de entrada

Esta estrutura JSON representa a carga útil que envia para a sua API Web. Segue sempre estas restrições:

• A entidade de nível superior é chamada values e é uma matriz de objetos. O número destes objetos é, no máximo, o batchSize.

• Cada objeto na values matriz tem:

  • Uma recordId propriedade que é uma cadeia única , usada para identificar esse registo.

  • 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 vêm de um source desses campos (que podem ser de um campo no documento, ou potencialmente de outra competência).

{
    "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 a sua Web API estar indisponível ou enviar códigos de estado não bem-sucedidos, considere os seguintes casos como erros:

• Se a Web API devolver um código de estado de sucesso mas a resposta indicar que não application/jsoné , a resposta é inválida e não são realizados enriquecimentos.

• Se o array de respostas values contiver registos inválidos (por exemplo, em falta ou duplicados recordId), os registos inválidos não são enriquecidos. Ao desenvolver competências personalizadas, cumpra o contrato de competências da Web API. Você pode consultar este exemplo fornecido no repositório Power Skill que segue o contrato esperado.

Nos casos em que a Web API não está disponível ou devolve um erro HTTP, o histórico de execução do indexador inclui um erro amigável com quaisquer detalhes disponíveis sobre o erro HTTP.

Considerações de segurança para autenticação de identidade gerida

Ao utilizar autenticação de identidade gerida com uma competência Custom Web API, o Pesquisa de IA do Azure obtém um token de acesso Microsoft Entra para a aplicação identificada por authResourceId e inclui esse token em pedidos enviados ao endpoint especificado por uri. O endpoint referenciado uri por é tipicamente a sua Azure Function, Serviço de Aplicações do Azure, API Management do Azure endpoint ou outra aplicação protegida pela Microsoft Entra. És responsável por configurar e manter a relação entre o endpoint e a aplicação identificada por authResourceId.

Independentemente do método de autenticação, as entradas de competências personalizadas podem conter valores provenientes de documentos fornecidos pelo cliente ou valores derivados desses documentos. Trata todas as entradas de habilidades personalizadas como não confiáveis. O Pesquisa de IA do Azure encaminha os inputs configurados no conjunto de competências para o seu endpoint sem interpretar, validar ou restringir o seu conteúdo para a sua implementação personalizada.

Valide e limite valores derivados de documentos na sua competência personalizada antes de os usar em pedidos de saída ou outras operações sensíveis à segurança. Use validação de entrada, listas de destino, validação de URL e nomes de host, restrições de protocolo e acesso à rede com privilégio mínimo que permita apenas os destinos e portas que a competência necessita. Para mais informações, consulte Estratégias de Arquitetura para redes e conectividade.

Práticas de segurança recomendadas

Para ajudar a manter uma implantação segura, siga estas práticas:

• Configure a uri propriedade para apontar apenas para endpoints confiáveis que estejam destinados a receber pedidos do Pesquisa de IA do Azure.
• Configure authResourceId para identificar a aplicação Microsoft Entra que se espera receber e validar o token de acesso.
• Certifique-se de que a aplicação que recebe pedidos valida as reivindicações padrão de tokens, incluindo audiência (aud), emissor (iss), tenant (tid) e quaisquer funções ou permissões de aplicação necessárias, antes de processar os pedidos.
• Aplicar o princípio do menor privilégio ao conceder permissões à identidade gerida do Pesquisa de IA do Azure.
• Revise periodicamente as definições de competências da API Web Personalizada, registos de aplicações Microsoft Entra e atribuições de funções e permissões concedidas às identidades geridas pelo Pesquisa de IA do Azure. Revise as alterações de configuração através dos seus processos estabelecidos de gestão de alterações e revisão de segurança.
• Revise periodicamente configurações de endpoints para Funções do Azure, App Services, APIs e gateways de API.
• Monitorize os registos de login da aplicação, eventos de autenticação e registos de acesso à API para atividades inesperadas ou não autorizadas.
• Remover endpoints não utilizados, permissões, registos de aplicações e atribuições de funções que já não são necessários.

Restringir o acesso à configuração de competências

Utilizadores que conseguem criar, modificar ou executar conjuntos de competências podem controlar tanto o endpoint de destino como a configuração de autenticação usada por uma competência da API Web Personalizada. Restrinja estas permissões a administradores de confiança e siga os seus processos padrão de gestão de alterações e revisão de segurança ao configurar competências personalizadas com identidade gerida.

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