Partage via

Faire évoluer efficacement une compétence personnalisée

  • Article

Les compétences personnalisées sont des API web qui implémentent une interface spécifique. Une compétence personnalisée peut être implémentée sur n’importe quelle ressource adressable publiquement. Les implémentations les plus courantes pour les compétences personnalisées sont les suivantes :

  • Azure Functions pour les compétences logiques personnalisées
  • Azure Web Apps pour des compétences IA en conteneur simple
  • Azure Kubernetes Service pour des compétences plus complexes ou plus volumineuses.

Configuration d’un ensemble de compétences

Les propriétés suivantes sur une compétence personnalisée sont utilisées pour la mise à l’échelle. Passez en revue l’interface de compétence personnalisée pour une introduction aux entrées et sorties qu’une compétence personnalisée doit implémenter.

  1. Définissez la batchSize de la compétence personnalisée pour configurer le nombre d’enregistrements envoyés à la compétence dans un unique appel à la compétence.

  2. Définissez la degreeOfParallelism pour étalonner le nombre de demandes simultanées que l’indexeur effectue à votre compétence.

  3. Définissez timeout sur une valeur suffisante pour que la compétence réponde avec une réponse valide.

  4. Dans la définition indexer, définissez batchSize sur le nombre de documents qui doivent être lus à partir de la source de données et enrichis simultanément.

À propos de l’installation

Il n’existe aucun ensemble de recommandations de taille unique. Vous devez planifier le test de différentes configurations pour atteindre un résultat optimal. Les stratégies de montée en puissance sont basées sur moins de demandes volumineuses ou de nombreuses petites demandes.

  • Cardinalité d’appel de compétence : assurez-vous de savoir si la compétence personnalisée s’exécute une fois pour chaque document (/document/content) ou plusieurs fois par document (/document/reviews_text/pages/*). S’il s’agit de plusieurs fois par document, restez sur le côté inférieur de batchSize et degreeOfParallelism pour réduire l’activité et essayez de définir la taille de lot de l’indexeur sur des valeurs plus élevées de manière incrémentielle pour une plus grande échelle.

  • Coordonnez la compétence personnalisée batchSize et l’indexeur batchSize, et assurez-vous que vous ne créez pas de goulots d’étranglement. Par exemple, si la taille du lot de l’indexeur est 5 et que la taille du lot de compétence est 50, vous avez besoin de 10 lots d’indexeur pour remplir une demande de compétence personnalisée. Dans l’idéal, la taille du lot de compétences doit être inférieure ou égale à la taille du lot de l’indexeur.

  • Pour degreeOfParallelism, utilisez le nombre moyen de requêtes qu’un lot d’indexeur peut générer pour guider votre décision sur la façon de définir cette valeur. Si votre infrastructure hébergeant la compétence, par exemple une fonction Azure, ne peut pas prendre en charge des niveaux élevés d’accès concurrentiel, envisagez de composer les degrés de parallélisme. Vous pouvez tester votre configuration avec quelques documents pour valider votre compréhension du nombre moyen de demandes.

  • Bien que votre objet soit mis à l’échelle et la prise en charge de volumes élevés, le test avec un échantillon plus petit de documents permet de quantifier différentes étapes d’exécution. Par exemple, vous pouvez évaluer le temps d’exécution de votre compétence, par rapport au temps global nécessaire pour traiter le sous-ensemble de documents. Cela vous aide à répondre à la question : votre indexeur passe-t-il plus de temps à créer un lot ou à attendre une réponse de votre compétence ?

  • Tenez compte des implications en amont du parallélisme. Si l’entrée d’une compétence personnalisée est une sortie d’une compétence antérieure, toutes les compétences de l’ensemble sont-elles mises à l’échelle efficacement pour réduire la latence ?

Gestion des erreurs dans la compétence personnalisée

Les compétences personnalisées doivent renvoyer un code d’état de réussite HTTP 200 lorsque la compétence se termine correctement. Si un ou plusieurs enregistrements d’un lot génèrent des erreurs, envisagez de renvoyer le code d’état multiple 207. La liste d’erreurs ou d’avertissements de l’enregistrement doit contenir le message approprié.

Tout élément d’un lot qui génère des erreurs entraînera l’échec du document correspondant. Si vous avez besoin que le document aboutisse, retournez un avertissement.

Tout code d’état supérieur à 299 est évalué comme une erreur et tous les enrichissements échouent, ce qui entraîne l’échec du document.

Messages d’erreur courants

  • 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. Définissez le paramètre de délai d’expiration sur la compétence pour permettre une durée d’exécution plus longue.

  • Could not execute skill because Web Api skill response is invalid. Indique que la compétence ne renvoie pas de message au format de réponse de la compétence personnalisée. Cela peut être le résultat d’une exception non interceptée dans la compétence.

  • Could not execute skill because the Web Api request failed. Très probablement causé par des erreurs d’autorisation ou des exceptions.

  • Could not execute skill. Généralement, le résultat du mappage de la réponse de compétence à une propriété existante dans la hiérarchie du document.

Test des compétences personnalisées

Commencez par tester vos compétences personnalisées avec un client d’API REST pour confirmer que :

  • La compétence implémente l’interface de compétence personnalisée pour les demandes et les réponses

  • La compétence retourne un JSON valide avec le type MIME application/JSON

  • La compétence retourne un code d’état HTTP valide

Créez une session de débogage pour ajouter votre compétence aux compétences et vous assurer qu’elle produit un enrichissement valide. Bien qu’une session de débogage ne vous permet pas de régler les performances de la compétence, elle vous permet de vous assurer que la compétence est configurée avec des valeurs valides et retourne les objets enrichis attendus.

Bonnes pratiques

  • Bien que les compétences peuvent accepter et renvoyer des charges utiles plus volumineuses, envisagez de limiter la réponse à 150 Mo ou moins lors du retour de JSON.

  • Envisagez de définir la taille du lot sur l’indexeur et la compétence pour vous assurer que chaque lot de sources de données génère une charge utile complète pour vos compétences.

  • Pour les tâches de longue durée, définissez le délai d’expiration sur une valeur suffisamment élevée pour vous assurer que l’indexeur n’ait pas d’erreur d’expiration lors du traitement de plusieurs documents simultanément.

  • Optimisez la taille des lots de l’indexeur, la taille des lots de compétences et les degrés de parallélisme des compétences pour générer le modèle de charge attendu par vos compétences, avec moins de requêtes volumineuses ou de nombreuses petites requêtes.

  • Surveillez les compétences personnalisées avec des journaux détaillés des défaillances, car vous pouvez avoir des scénarios dans lesquels des requêtes spécifiques échouent systématiquement en raison de la variabilité des données.