Compétence API web personnalisée dans un pipeline d’enrichissement de Recherche Azure AI

La compétence API web personnalisée vous permet d’étendre l’enrichissement par IA en appelant un point de terminaison d’API web qui fournit des opérations personnalisées. Tout comme les compétences intégrées, une compétence API web personnalisée a des entrées et des sorties. Selon les entrées, votre API web reçoit une charge utile JSON pendant l’exécution de l’indexeur et génère une charge utile JSON en réponse, ainsi qu’un code d’état de réussite. La réponse est censée avoir les sorties spécifiées par votre compétence personnalisée. Toute autre réponse est considérée comme une erreur et aucun enrichissement n’est effectué. La structure des charges utiles JSON est décrite plus bas dans ce document.

La compétence API web personnalisée est également utilisée dans l’implémentation de la fonctionnalité Azure OpenAI sur vos données. Si Azure OpenAI est configuré pour l’accès en fonction du rôle et que vous recevez des appels 403 Forbidden lors de la création de l’index vectoriel, vérifiez que Recherche Azure AI dispose d’une identité affectée par le système et s’exécute en tant que service approuvé sur Azure OpenAI.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Paramètres de la compétence

Les paramètres respectent la casse.

Entrées de la compétence

Il n’y a pas d’entrée prédéfinie pour cette compétence. Les entrées sont n’importe quel champ existant ou n’importe quel nœud de l’arborescence d’enrichissement que vous souhaitez transmettre à votre compétence personnalisée.

Sorties de la compétence

Il n’y a pas de sortie prédéfinie pour cette compétence. Veillez à définir un mappage de champ de sortie dans l’indexeur si la sortie de la compétence doit être envoyée à un champ de l’index de recherche.

Exemple de définition

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

Exemple de structure JSON d’entrée

Cette structure JSON représente la charge utile envoyée à votre API web. Elle suit toujours ces contraintes :

• L’entité de niveau supérieur est appelée values et est un tableau d’objets. Le nombre de ces objets équivaut à batchSize au maximum.

• Chaque objet dans le tableau values a :

  • Une propriété recordId constituant une chaîne unique, utilisée pour identifier cet enregistrement.

  • Une propriété data constituant un objet JSON. Les champs de la propriété data 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 peuvent provenir d’un champ du document ou éventuellement une autre compétence).

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

Exemple de structure JSON de sortie

« output » correspond à la réponse renvoyée par votre API web. L’API web doit retourner uniquement une charge utile JSON (vérifiée en examinant l’en-tête de réponse Content-Type) et doit satisfaire les contraintes suivantes :

• Il doit y avoir une entité de niveau supérieur appelée values qui doit être un tableau d’objets.

• Le nombre d’objets dans le tableau doit être le même que le nombre d’objets envoyés à l’API web.

• Chaque objet doit avoir :

  • Une propriété recordId.

  • Une propriété data, qui est un objet dans lequel les champs sont des enrichissements correspondant aux « noms » dans output et dont la valeur est considérée comme l’enrichissement.

  • Une propriété errors, tableau listant toutes les erreurs rencontrées et qui est ajouté à l’historique d’exécution de l’indexeur. Cette propriété est obligatoire, mais peut avoir une valeur null.

  • Une propriété warnings, tableau listant tous les avertissements rencontrés et qui est ajouté à l’historique d’exécution de l’indexeur. Cette propriété est obligatoire, mais peut avoir une valeur null.

• L’ordre des objets dans les values indiquées dans la demande ou la réponse n’a pas d’importance. Toutefois, comme le recordId est utilisé pour la corrélation, tous les enregistrements dans la réponse contenant un recordId absent de la demande d’origine envoyée à l’API web sont ignorés.

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

Cas d’erreur

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

• Si l’API web 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 comme non valide et aucun enrichissement n’est effectué.

• S’il existe des enregistrements non valides (par exemple, absence ou duplication de recordId) dans le tableau values de réponses, aucun enrichissement n’est effectué pour les enregistrements non valides. Il est important d’adhérer au contrat de compétences de l’API web lors du développement de compétences personnalisées. Vous pouvez vous référer à cet exemple fourni dans le dépôt Power Skill qui suit le contrat prévu.

Quand l’API web n’est pas disponible ou retourne une erreur HTTP, une erreur amicale avec tous les détails disponibles sur l’erreur HTTP est ajoutée à l’historique d’exécution de l’indexeur.

Voir aussi

• How to create a skillset in an enrichment pipeline (Créer un ensemble de compétences dans un pipeline d’enrichissement)
• Ajouter une compétence personnalisée à un pipeline d’enrichissement par IA
• Exemple : Création d’une compétence personnalisée pour l’enrichissement de l’IA
• Dépôt Power Skill