Compétence AML dans un pipeline d’enrichissement de la Recherche Azure AI

Article
09/01/2024

Important

La prise en charge des connexions d’indexeur au catalogue de modèles Azure AI Studio est disponible en préversion publique sous conditions d’utilisation supplémentaires. Les API REST en préversion prennent en charge cette compétence.

La compétence AML vous permet d’étendre l’enrichissement par IA à l’aide d’un modèle Azure Machine Learning (AML) personnalisé. Une fois qu’un modèle AML est formé et déployé, une compétence AML l’intègre dans l’enrichissement par IA.

À l’instar des autres compétences intégrées, une compétence AML a des entrées et des sorties. Les entrées sont envoyées à votre point de terminaison en ligne AML déployé sous la forme d’un objet JSON, qui génère une charge utile JSON en réponse avec un code d’état de réussite. Vos données sont traitées dans l’emplacement géographique où votre modèle est déployé. La réponse est censée avoir les sorties spécifiées par votre compétence AML. Toute autre réponse est considérée comme une erreur et aucun enrichissement n’est effectué.

La compétence AML peut être appelée avec la version d’API stable 2024-07-01 ou la version d’API 2024-05-01-preview pour les connexions au catalogue de modèles dans Azure AI Studio.

Depuis 2024-05-01-preview REST API et dans le Portail Azure (qui cible également la préversion 2024-05-01-preview), Azure AI Search a introduit le vectoriseur de catalogue de modèles Azure AI Studio pour les connexions de temps de requête au catalogue de modèles dans Azure AI Studio. Si vous souhaitez utiliser ce vectoriseur pour les requêtes, la compétence AML est l’équivalent d’indexation pour générer des incorporations à l’aide d’un modèle dans le catalogue de modèles Azure AI Studio.

Pendant l’indexation, la compétence AML peut se connecter au catalogue de modèles pour générer des vecteurs pour l’index. Au moment de la requête, les requêtes peuvent utiliser un vectoriseur pour se connecter au même modèle pour vectoriser des chaînes de texte pour une requête vectorielle. Dans ce flux de travail, la compétence AML et le vectoriseur de catalogue de modèles doivent être utilisés ensemble afin que vous utilisiez le même modèle d’incorporation pour l’indexation et les requêtes. Découvrez comment implémenter la vectorisation intégrée à l’aide de modèles d’Azure AI Studio pour plus d’informations sur ce flux de travail.

Remarque

L’indexeur réessaie deux fois pour certains codes d’état HTTP standard retournés par le point de terminaison en ligne AML. Ces codes d’état HTTP sont les suivants :

503 Service Unavailable
429 Too Many Requests

Prérequis

Un espace de travail AML
Un Point de terminaison en ligne (en temps réel) dans cet espace de travail.

@odata.type

Microsoft.Skills.Custom.AmlSkill

Paramètres de la compétence

Les paramètres respectent la casse. Les paramètres que vous choisissez d’utiliser dépendent de l’authentification dont votre point de terminaison en ligne AML a besoin, le cas échéant

Nom du paramètre	Description
`uri`	(Obligatoire pour l’authentification par clé) L’URI de scoring du point de terminaison en ligne AML auquel la charge utile JSON est envoyée. Seul le schéma d’URI https est autorisé.
`key`	(Requis pour l’authentification par clé) Clé du point de terminaison en ligne AML.
`resourceId`	(Requis pour l’authentification par jeton). ID de ressource Azure Resource Manager du point de terminaison en ligne AML. Il doit être au format subscriptions/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name}.
`region`	(Facultatif pour l’authentification par jeton). La région dans laquelle le point de terminaison en ligne AML est déployé.
`timeout`	(Facultatif) Si spécifié, indique le délai d’expiration pour le client http qui effectue l’appel d’API. Il doit être formaté en tant que valeur « dayTimeDuration » XSD (un sous-ensemble limité d'une valeur de durée ISO 8601 ). Par exemple, `PT60S` pour 60 secondes. S’il n’est pas défini, une valeur par défaut de 30 secondes est choisie. Le délai d’expiration peut être défini sur 230 secondes maximum et 1 seconde minimum.
`degreeOfParallelism`	(Facultatif) Lorsqu’il est spécifié, indique le nombre d’appels que l’indexeur effectue en parallèle au point de terminaison que vous avez fourni. Vous pouvez diminuer cette valeur si votre point d’accès échoue en raison d’une charge de requêtes trop élevée. Vous pouvez l’augmenter si votre point de terminaison est en mesure d’accepter davantage de requêtes et que vous souhaitez augmenter les performances de l’indexeur. S’il n’est pas défini, une valeur par défaut de 5 secondes est utilisée. Le degreeOfParallelism peut avoir une valeur maximale de 10 et un minimum de 1.

Paramètres de compétence à utiliser

Les paramètres de compétence AML requis dépendent de l’authentification utilisée par votre point de terminaison en ligne AML, le cas échéant. Les points de terminaison en ligne AML fournissent deux options d’authentification :

Authentification basée sur une clé. Une clé statique est fournie pour authentifier les demandes de scoring des compétences AML
- Utiliser les paramètres uri et key
Authentification basée sur un jeton. Le point de terminaison en ligne AML est déployé à l’aide de l’authentification basée sur des jetons. L’identité managée du service Recherche Azure AI doit être activée. La compétence AML utilise ensuite l’identité managée du service pour s’authentifier auprès du point de terminaison en ligne AML, sans clés statiques requises. L’identité doit avoir le rôle de propriétaire ou de contributeur.
- Utiliser le paramètre resourceId
- Si le service Recherche se trouve dans une autre région que celle de l’espace de travail AML, utilisez le paramètre région pour définir la région dans laquelle le point de terminaison en ligne AML a été déployé

Entrées de la compétence

Il n’y a pas d’entrée « prédéfinie » pour cette compétence. Si vous choisissez comme entrées un ou plusieurs champs déjà disponibles au moment de l’exécution de cette compétence, la charge utile JSON envoyée au point de terminaison en ligne AML aura des champs différents.

Sorties de la compétence

Il n’y a pas de sortie « prédéfinie » pour cette compétence. En fonction de la réponse envoyée par votre point de terminaison en ligne AML, ajoutez des champs de sortie à récupérer dans la réponse JSON.

Exemple de définition

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

Exemple de structure JSON d’entrée

Cette structure JSON représente la charge utile envoyée à votre point de terminaison en ligne AML. Les champs de haut niveau de la structure correspondent aux « noms » spécifiés dans la section inputs de la définition de compétence. Les valeurs de ces champs proviennent de la source de ces champs (qui peut être un champ dans le document ou éventuellement une autre compétence)

{
  "text": "Este es un contrato en Inglés"
}

Exemple de structure JSON de sortie

Le terme « output » correspond à la réponse renvoyée par votre point de terminaison en ligne AML. Le point de terminaison en ligne AML ne doit retourner qu’une charge utile JSON (vérifiée en examinant l’en-tête de réponse Content-Type) et doit être un objet dans lequel les champs sont des enrichissements correspondant aux « noms » dans la section output et dont la valeur est l’enrichissement.

{
    "detected_language_code": "es"
}

Exemple de définition de mise en forme inlined

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "shapedText",
        "sourceContext": "/document",
        "inputs": [
            {
              "name": "content",
              "source": "/document/content"
            }
        ]
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

Structure JSON d’entrée de mise en forme inlined

{
  "shapedText": { "content": "Este es un contrato en Inglés" }
}

Structure JSON d’exemple de sortie de mise en forme inlined

{
    "detected_language_code": "es"
}

Cas d’erreur

En plus de la non-disponibilité de votre service AML ou de l’envoi de codes d’état non réussis, les cas suivants sont considérés comme erronés :

Si le point de terminaison en ligne AML retourne un code d’état de réussite, mais que la réponse indique que ce n’est pas application/json, la réponse est considérée non valide et aucun enrichissement n’est effectué.
Si le point de terminaison en ligne AML retourne un json non valide

Quand le point de terminaison en ligne AML n’est pas disponible ou retourne une erreur HTTP, une erreur conviviale avec tous les détails disponibles sur l’erreur HTTP est ajoutée à l’historique des exécutions de l’indexeur.

Partager via