Ajouter une compétence personnalisée à un pipeline d’enrichissement Recherche Azure AI

Un pipeline d’enrichissement par IA peut inclure des compétences intégrées et des compétences personnalisées que vous créez et publiez. Votre code personnalisé s’exécute en dehors du service de recherche (par exemple, en tant que fonction Azure), mais il accepte les entrées et envoie des sorties à l’ensemble de compétences comme n’importe quelle autre compétence. Vos données sont traitées dans la géographie où votre modèle est déployé.

Les compétences personnalisées peuvent sembler complexes, mais elles peuvent être simples à implémenter. Si vous avez des packages existants qui fournissent des modèles correspondants ou des modèles de classification, vous pouvez transmettre du contenu extrait d’objets blob à ces modèles à des fins de traitement. Étant donné que l’enrichissement par IA est basé sur Azure, vous devez également héberger votre modèle sur Azure. Les options d’hébergement courantes incluent Azure Functions ou containers.

Si vous créez une compétence personnalisée, cet article décrit l’interface que vous utilisez pour intégrer la compétence dans le pipeline. La principale exigence est la possibilité d’accepter des entrées et d’émettre des sorties de manière à ce que l’ensemble de compétences puisse consommer dans son ensemble. Cet article se concentre ainsi sur les formats d’entrée et de sortie que le pipeline d’enrichissement exige.

Avantages des compétences personnalisées

Construire une compétence personnalisée vous donne un moyen d’insérer des transformations uniques dans votre contenu. Par exemple, vous pouvez créer des modèles de classification personnalisés pour différencier des contrats et documents commerciaux et financiers, ou ajouter une compétence de reconnaissance vocale pour explorer plus profondément des fichiers audio afin d’en extraire du contenu pertinent. Pour un exemple pas à pas, voir Exemple : Création d’une compétence personnalisée pour l’enrichissement par IA.

Définir le point de terminaison et l’intervalle de délai d’expiration

Spécifiez l’interface d’une compétence personnalisée via la compétence API web personnalisée.

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230-second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

L’URI correspond au point de terminaison HTTPS de votre fonction ou application. Lors de la définition de l’URI, assurez-vous que l’URI est sécurisé (HTTPS). Si vous hébergez votre code dans une application de fonction Azure, incluez une clé API dans l’en-tête ou en tant que paramètre d’URI dans l’URI pour autoriser la requête.

Si votre fonction ou application utilise Azure identités managées et Azure rôles pour l’authentification et l’autorisation, la compétence personnalisée peut inclure un jeton d’authentification sur la demande. Les points suivants décrivent les exigences inhérentes à cette approche :

• Le service de recherche, qui envoie la requête au nom de l'indexeur, doit être configuré pour utiliser une identité managée (système ou affectée par l'utilisateur) afin que Microsoft Entra ID puisse authentifier l'appelant.

• Vous devez configurer votre fonction ou votre application pour Microsoft Entra ID.

• Votre définition de compétence personnalisée doit inclure une propriété authResourceId. Cette propriété accepte un ID d’application (client), au format pris en charge : api://<appId>.

Vérifiez que cela uri pointe vers le point de terminaison de l’application identifié par authResourceId. Les valeurs incompatibles peuvent entraîner des échecs d’authentification ou des demandes envoyées à un point de terminaison inattendu. Pour obtenir des conseils de sécurité, des pratiques recommandées et des étapes pour vérifier votre configuration, consultez Considérations relatives à la sécurité pour l’authentification d’identité managée.

Par défaut, la connexion au point de terminaison expire si une réponse n’est pas retournée dans une fenêtre de 30 secondes (PT30S). Le pipeline d’indexation est synchrone et l’indexation génère une erreur de délai d’expiration si une réponse n’est pas reçue dans ce délai. Vous pouvez augmenter l’intervalle jusqu’à une valeur maximale de 230 secondes en réglant le paramètretimeout (PT230S).

Si un point de terminaison protégé par des restrictions d’accès IP ne répond pas, définissez timeout temporairement sur une valeur courte, par PT10Sexemple, pour afficher plus rapidement l’erreur de délai d’expiration. Pour une application de fonction Azure, gérez les règles d’adresse IP entrantes sousrestrictions d’accès>>. Pour autoriser les adresses IP, consultez Configurer les règles de pare-feu IP pour autoriser les connexions d’indexeur.

Mettre en forme les entrées d’API web

L’API web doit accepter un tableau d’enregistrements à traiter. Dans chaque enregistrement, fournissez un conteneur de propriétés en tant qu’entrée à votre API web.

Supposons que vous souhaitez créer un enrichisseur de base qui identifie la première date mentionnée dans le texte du contrat. Dans cet exemple, la compétence personnalisée accepte une entrée unique. contractText La compétence possède également une seule sortie, qui est la date du contrat. Pour rendre l’enrichisseur plus pertinent, renvoyez contractDate sous la forme d’un type complexe multipartite.

Votre API web doit être prête à recevoir un lot d’enregistrements d’entrée. Chaque membre du values tableau représente l’entrée d’un enregistrement particulier. Chaque enregistrement doit comporter les éléments suivants :

• Membre recordId qui est l’identificateur unique d’un enregistrement particulier. Lorsque votre enrichisseur renvoie des résultats, il doit fournir cet élément recordId afin que l’appelant puisse faire correspondre les résultats des enregistrements aux entrées.

• Un membre data qui est essentiellement un jeu de champs d’entrée pour chaque enregistrement.

La requête d’API web résultante peut ressembler à ceci :

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issued on November 3, 2023 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

Dans la pratique, votre code peut être appelé avec des centaines ou des milliers d’enregistrements au lieu des trois affichés ici.

Mettre en forme les sorties de l’API web

Le format de sortie correspond à un ensemble d’enregistrements comprenant un recordId et un ensemble de propriétés Cet exemple particulier n’a qu’une seule sortie, mais vous pouvez renvoyer plusieurs propriétés. Il est recommandé de renvoyer des messages d’erreur et d’avertissement si un enregistrement n’a pas pu être traité.

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2023 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

Ajouter une compétence personnalisée à un ensemble de compétences

Lorsque vous créez un enrichisseur d’API web, vous pouvez définir des en-têtes et des paramètres HTTP dans le cadre de la requête. L’extrait de code suivant montre comment des paramètres de requête et des en-têtes HTTP facultatifs peuvent être inclus dans la définition d’un ensemble de compétences. La définition d’un en-tête HTTP est utile si vous devez transmettre des paramètres de configuration à votre code.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

Visionner la vidéo

Pour une présentation vidéo et une démonstration, regardez la démonstration suivante.

Étapes suivantes

Cet article a abordé les exigences d’interface nécessaires à l’intégration d’une compétence personnalisée dans un ensemble de compétences. Pour en savoir plus sur les compétences personnalisées et la composition de l’ensemble de compétences, consultez les ressources suivantes :

• Power Skills : référentiel de compétences personnalisées
• Exemple : Création d’une compétence personnalisée pour l’enrichissement de l’IA
• Guide pratique pour définir un ensemble de compétences
• Créer un jeu de compétences (REST)
• Guide pratique pour mapper des champs enrichis