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

Article
12/18/2024

Important

La prise en charge des connexions d’indexeur au catalogue de modèles Azure AI Foundry 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 avec un modèle AML (Azure Machine Learning) personnalisé ou un modèle d’incorporation de base déployé sur Azure AI Foundry. Une fois qu’un modèle AML est entraîné et déployé, une compétence AML l’intègre dans un ensemble de compétences.

Utilisation des compétences AML

Comme d’autres compétences intégrées, une compétence AML personnalisée a des entrées et des sorties. Les entrées sont envoyées à un point de terminaison en ligne AML déployé en tant qu’objet JSON. La sortie du point de terminaison doit être une charge utile JSON dans la réponse, ainsi qu’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 fournir les sorties spécifiées par votre définition de compétence AML . Toute autre réponse est considérée comme une erreur et aucun enrichissement n’est effectué.

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

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

Compétence AML pour les modèles dans Azure AI Foundry

À compter de 2024-05-01-preview API REST et dans le Portail Azure (qui cible également la préversion 2024-05-01-preview), Azure AI Search fournit le vectoriseur de catalogue de modèles Azure AI Foundry pour les connexions de temps de requête au catalogue de modèles dans le portail Azure AI Foundry. Si vous souhaitez utiliser ce vectoriseur pour les requêtes, une 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 Foundry.

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. Consultez Utiliser des modèles d’incorporation à partir du catalogue de modèles Azure AI Foundry pour plus d’informations et pour obtenir la liste des modèles d’incorporation pris en charge.

Nous vous recommandons d’utiliser l’Assistant Importation et vectorisation des données pour générer un ensemble de compétences qui inclut une compétence AML pour les modèles incorporés déployés sur Azure AI Foundry. La définition de compétence AML pour les entrées, les sorties et les mappages sont générées par l’Assistant, ce qui vous permet de tester facilement un modèle avant d’écrire du code.

Prérequis

Un espace de travail AML pour un modèle personnalisé que vous créez ou un projet dans Azure AI Foundry si un modèle d’incorporation est déployé à partir du catalogue.
Points de terminaison en ligne (en temps réel) dans cet espace de travail pour un modèle personnalisé ou point de terminaison de modèle pour l’incorporation de modèles déployés à partir du catalogue.

@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é. Pour l’incorporation de modèles dans le catalogue de modèles Azure AI Foundry, il s’agit de l’URI cible.
`key`	(Obligatoire pour l’authentification par clé) Clé pour le point de terminaison en ligne AML ou le
`resourceId`	(Requis pour l’authentification par jeton). ID de ressource Azure Resource Manager du point de terminaison en ligne AML. Il doit respecter le 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.

Authentification

Les points de terminaison en ligne AML fournissent deux options d’authentification :

Authentification basée sur des clés. Une clé statique est fournie pour authentifier les demandes de scoring à partir des compétences AML. Définissez les paramètres et key les uri paramètres de cette connexion.
Authentification basée sur des jetons, où le point de terminaison en ligne AML est déployé à l’aide de l’authentification basée sur des jetons. L’identité managée d’Azure AI service Search doit être activée et avoir une attribution de rôle sur l’espace de travail. 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é du service de recherche doit être propriétaire ou contributeur. Définissez le resourceId paramètre et, si le service de recherche se trouve dans une région différente de l’espace de travail AML, définissez le region paramètre.

Entrées de la compétence

Les entrées de compétence sont un nœud du document enrichi créé lors du craquage de document. Par exemple, il peut s’agir du document racine, d’une image normalisée ou du contenu d’un objet blob. Il n’y a pas d’entrée prédéfinie pour cette compétence. Pour les entrées, vous devez spécifier un ou plusieurs nœuds renseignés au moment de l’exécution de la compétence AML.

Sorties de la compétence

Les sorties de compétence sont de nouveaux nœuds d’un document enrichi créé par la compétence. Il n’y a pas de sortie prédéfinie pour cette compétence. Pour les sorties, vous devez fournir des nœuds qui peuvent être remplis à partir de la réponse JSON de votre compétence AML.

Exemple de définition

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A custom model that detects the language in a document.",
    "uri": "https://language-model.models.contoso.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://language-model.models.contoso.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 :

Le point de terminaison en ligne AML retourne un code d’état de réussite, mais la réponse indique qu’elle n’est pas application/json, alors la réponse est considérée comme non valide et aucun enrichissement n’est effectué.
Le point de terminaison en ligne AML retourne json non valide.

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

Partager via