Escalar horizontalmente com eficiência uma habilidade personalizada

  • Artigo

As habilidades personalizadas são APIs Web que implementam uma interface específica. Uma habilidade personalizada pode ser implementada em qualquer recurso publicamente endereçável. As implementações mais comuns para habilidades personalizadas são:

  • O Azure Functions para habilidades de lógica personalizada
  • Aplicativos Web do Azure para habilidades simples de IA em contêineres
  • Serviço de Kubernetes do Azure para habilidades mais complexas ou maiores.

Configuração do conjunto de habilidades

As propriedades a seguir em uma habilidade personalizada são usadas para escala. Revise a interface de habilidades personalizadas para obter uma introdução às entradas e saídas que uma habilidade personalizada deve implementar.

  1. Defina o batchSize da habilidade personalizada para configurar o número de registros enviados para a habilidade em uma única invocação da habilidade.

  2. Defina degreeOfParallelism para calibrar o número de solicitações simultâneas que o indexador faz para sua habilidade.

  3. Defina o timeout como um valor suficiente para que a habilidade responda com uma resposta válida.

  4. Na definição indexer, defina batchSize como o número de documentos que devem ser lidos da fonte de dados e aprimorados simultaneamente.

Considerações

Não existe um conjunto de recomendações "tamanho único". Você deve planejar testar diferentes configurações para alcançar um resultado ideal. As estratégias de expansão baseiam-se em menos solicitações grandes ou em muitas solicitações pequenas.

  • Cardinalidade de invocação de habilidade: certifique-se de saber se a habilidade personalizada é executada uma vez para cada documento (/document/content) ou várias vezes por documento (/document/reviews_text/pages/*). Se for várias vezes por documento, fique na parte inferior batchSize e degreeOfParallelism para reduzir a rotatividade e tente definir o tamanho do lote do indexador para valores cada vez mais altos para maior escala.

  • Coordene a habilidade personalizada batchSize e o indexador batchSize e certifique-se de não criar gargalos. Por exemplo, se o tamanho do lote do indexador for 5 e o tamanho do lote de habilidades for 50, serão necessários 10 lotes do indexador para preencher uma solicitação de habilidade personalizada. Idealmente, o tamanho do lote de habilidades deve ser menor ou igual ao tamanho do lote do indexador.

  • Para degreeOfParallelism, use o número médio de solicitações que um lote do indexador pode gerar para orientar sua decisão sobre como definir esse valor. Se a sua infraestrutura que hospeda a habilidade, por exemplo, uma função do Azure, não puder suportar altos níveis de simultaneidade, considere diminuir os graus de paralelismo. Você pode testar sua configuração com alguns documentos para validar sua compreensão do número médio de solicitações.

  • Embora seu objeto seja escala e suporte de grandes volumes, testar com uma amostra menor de documentos ajuda a quantificar diferentes etapas de execução. Por exemplo, você pode avaliar o tempo de execução da sua habilidade em relação ao tempo total necessário para processar o subconjunto de documentos. Isso ajuda você a responder à pergunta: seu indexador gasta mais tempo construindo um lote ou aguardando uma resposta de sua habilidade?

  • Considere as implicações de upstream de paralelismo. Se a entrada para uma habilidade personalizada for uma saída de uma habilidade anterior, todas as habilidades no conjunto de habilidades foram escaladas horizontalmente com eficiência para minimizar a latência?

Tratamento de erros na habilidade personalizada

As habilidades personalizadas devem retornar um código de status de êxito HTTP 200 quando a habilidade for concluída com êxito. Se um ou mais registros em um lote resultarem em erros, considere retornar o código de vários status 207. A lista de erros ou avisos para o registro deve conter a mensagem apropriada.

Todos os itens em um lote com erros resultarão na falha do documento correspondente. Se você precisar que o documento tenha sucesso, retorne um aviso.

Qualquer código de status acima de 299 é avaliado como um erro e todos os enriquecimentos falham resultando em um documento com falha.

Mensagens de erro comuns

  • Could not execute skill because it did not execute within the time limit '00:00:30'. This is likely transient. Please try again later. For custom skills, consider increasing the 'timeout' parameter on your skill in the skillset. Defina o parâmetro de tempo limite na habilidade para permitir uma duração de execução mais longa.

  • Could not execute skill because Web Api skill response is invalid. Indicativo de que a habilidade não está retornando uma mensagem no formato de resposta de habilidade personalizada. Isso pode ser o resultado de uma exceção não percebida na habilidade.

  • Could not execute skill because the Web Api request failed. Provavelmente causado por erros ou exceções de autorização.

  • Could not execute skill. Normalmente, o resultado da resposta da habilidade está sendo mapeado para uma propriedade existente na hierarquia do documento.

Testar habilidades personalizadas

Comece testando sua habilidade personalizada com um cliente de API REST para validar:

  • A habilidade implementa a interface de habilidade personalizada para solicitações e respostas

  • A habilidade retorna um JSON válido com o tipo MIME do application/JSON

  • Retorna um código de status HTTP válido

Crie uma sessão de depuração para adicionar sua habilidade ao conjunto de habilidades e verifique se ela produz um enriquecimento válido. Embora uma sessão de depuração não permita ajustar o desempenho da habilidade, ela permite garantir que a habilidade esteja configurada com valores válidos e retorne os objetos enriquecidos esperados.

Práticas recomendadas

  • Embora as habilidades possam aceitar e retornar payloads maiores, considere limitar a resposta a 150 MB ou menos ao retornar JSON.

  • Considere definir o tamanho do lote no indexador e a habilidade para garantir que cada lote de fonte de dados gere um payload completo para sua habilidade.

  • Para tarefas de execução prolongada, defina o tempo limite para um valor alto o suficiente para garantir que o indexador não apresente erros ao processar documentos simultaneamente.

  • Otimize o tamanho do lote do indexador, o tamanho do lote de habilidades e os graus de habilidade de paralelismo para gerar o padrão de carga que sua habilidade espera, menos solicitações grandes ou muitas solicitações pequenas.

  • Monitore habilidades personalizadas com logs detalhados de falhas, pois você pode ter cenários em que solicitações específicas falham consistentemente como resultado da variabilidade dos dados.