Créer un ensemble de compétences (API REST Azure AI Search)

  • Article

Un ensemble de compétences est une collection de compétences cognitives utilisées pour l’enrichissement par IA, avec une spécification facultative pour la création d’une base de connaissances externe dans stockage Azure. Les compétences appellent le traitement du langage naturel et d’autres transformations, telles que la reconnaissance d’entités, l’extraction de phrases clés, la segmentation du texte en pages logiques, entre autres.

Un ensemble de compétences est attaché à un indexeur. Pour utiliser l’ensemble de compétences, référencez-le dans un indexeur, puis exécutez l’indexeur pour importer des données, appeler des transformations et un enrichissement, puis mapper les champs de sortie à un index. Un ensemble de compétences est une ressource de haut niveau, mais il est opérationnel uniquement dans le traitement de l’indexeur. En tant que ressource générale, vous pouvez concevoir un ensemble de compétences une seule fois, puis le référencer dans plusieurs indexeurs.

Vous pouvez utiliser POST ou PUT sur la demande. Pour l’une ou l’autre, le document JSON dans le corps de la demande fournit la définition de l’objet.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
  Content-Type: application/json  
  api-key: [admin key]

Le protocole HTTPS est requis pour toutes les requêtes de service. Si l’ensemble de compétences n’existe pas, il est créé. S’il existe déjà, il est mis à jour vers la nouvelle définition.

Notes

Les ensembles de compétences sont la base de l’enrichissement par IA. Une ressource gratuite est disponible pour un traitement limité, mais pour les charges de travail plus volumineuses ou plus fréquentes, une ressource Cognitive Services facturable est nécessaire.

Paramètres URI

Paramètre Description
nom du service Obligatoire. Définissez cette valeur sur le nom unique défini par l’utilisateur de votre service de recherche.
nom de l’ensemble de compétences Obligatoire sur l’URI si vous utilisez PUT. Le nom doit être en minuscules, commencer par une lettre ou un chiffre, ne comporter ni barres obliques ni points et comporter moins de 128 caractères. Le nom doit commencer par une lettre ou un chiffre, mais le reste du nom peut inclure n’importe quelle lettre, chiffre et tirets, tant que les tirets ne sont pas consécutifs.
api-version Obligatoire. Consultez Versions d’API pour obtenir la liste des versions prises en charge.

En-têtes de requête

Le tableau suivant décrit les en-têtes de demande obligatoires et facultatifs.

Champs Description
Content-Type Obligatoire. À définir avec la valeur application/json
api-key Facultatif si vous utilisez des rôles Azure et qu’un jeton de porteur est fourni sur la demande, sinon une clé est requise. Les demandes de création doivent inclure un api-key en-tête défini sur votre clé d’administration (par opposition à une clé de requête). Pour plus d’informations, consultez Se connecter à Azure AI Search à l’aide de l’authentification par clé .

Corps de la demande

Le corps de la requête contient la définition de l’ensemble de compétences. Les compétences sont autonomes ou chaînées par le biais d’associations entrée-sortie, où la sortie d’une transformation devient entrée vers une autre. Un ensemble de compétences doit avoir au moins une compétence. Il n’y a pas de limite théorique sur le nombre maximal de compétences, mais trois à cinq est une configuration courante.

Le code JSON suivant est une représentation générale des parties main de la définition.

{   
  "name" : (optional on PUT; required on POST) "Name of the skillset",  
  "description" : (optional) "Anything you want, or nothing at all",   
  "skills" : (required) ["An array of skills. Each skill has an odata.type, name, input and output parameters"],
  "cognitiveServices": 
      {
        "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
        "description": "Optional. Anything you want, or null",
        "key": "<YOUR-COGNITIVE-SERVICES-ALL-IN-ONE-KEY>"
      },
  "knowledgeStore": (optional) { ... },
  "encryptionKey": (optional) { }
}

La requête peut contenir les propriétés suivantes :

Propriété Description
name Obligatoire. Nom de l’ensemble de compétences. Le nom doit être en minuscules, commencer par une lettre ou un chiffre, ne comporter ni barres obliques ni points et comporter moins de 128 caractères. Le nom doit commencer par une lettre ou un chiffre, mais le reste du nom peut inclure n’importe quelle lettre, chiffre et tirets, tant que les tirets ne sont pas consécutifs.
skills Tableau de compétences. Chaque compétence a un odata.type, un nom, un contexte et des paramètres d’entrée et de sortie. Le tableau peut inclure des compétences intégrées et des compétences personnalisées. Au moins une compétence est requise. Si vous utilisez une base de connaissances, incluez une compétence Modélisateur , sauf si vous définissez la forme de données dans la projection.
cognitiveServices Une clé tout-en-un est requise pour les compétences facturables qui appellent API Cognitive Services sur plus de 20 documents par jour, par indexeur. La clé doit être pour une ressource dans la même région que le service de recherche. Pour plus d’informations, consultez Attacher une ressource Cognitive Services. Si vous utilisez la compétence Recherche d’entité personnalisée , incluez cette section et une clé pour activer les transactions au-delà de 20 transactions par jour par indexeur.

Vous n’avez pas besoin de clé Cognitive Services et vous pouvez donc exclure cognitiveServices la section si votre ensemble de compétences se compose uniquement de compétences personnalisées, de compétences utilitaires (conditionnelles, modélisateur, fusion de texte, fractionnement de texte) ou de la compétence Extraction de documents. Si vous souhaitez supprimer votre ressource de service cognitif attachée d’un ensemble de compétences (pour revenir à l’utilisation des limites « par défaut ») spécifiez @odata.type en tant que #Microsoft.Azure.Search.DefaultCognitiveServices, consultez cet exemple pour plus d’informations.
knowledgeStore facultatif. Destination de la sortie d’enrichissement vers stockage Azure. Nécessite une chaîne de connexion à un compte de stockage Azure et des projections.

storageConnectionString (obligatoire) Chaîne au format suivant : "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net".

projections (obligatoire) Tableau d’objets de projection constitués de tables, objects, files, qui sont spécifiés ou null.

tables
Crée une ou plusieurs tables dans stockage Table Azure, en projetant le contenu de chaque document sous forme de lignes dans une table. Chaque table peut avoir les trois propriétés suivantes :
  • name (obligatoire) détermine la table à créer ou à utiliser dans Stockage Table Azure.
  • generatedKeyName (facultatif) est le nom d’une colonne qui identifie un document de manière unique. Les valeurs de cette colonne seront générées pendant l’enrichissement. Si vous l’omettez, le service de recherche crée une colonne clé par défaut en fonction du nom de la table.
  • source (obligatoire) est le chemin d’accès à un nœud de l’arborescence d’enrichissement qui fournit la forme de la projection. Il s’agit généralement de la sortie d’une compétence Modélisateur. Les chemins commencent par /document/, représentant le document enrichi racine, puis sont étendus à /document/<shaper-output>/, ou /document/content/, ou à un autre nœud dans l’arborescence d’enrichissement. Exemples : /document/countries/* (tous les pays) ou /document/countries/*/states/* (tous les États dans tous les pays).

objects
Projette des documents en tant qu’objets blob dans Stockage Blob Azure. Chaque objet a deux propriétés requises :
  • storageContainerest le nom du conteneur à créer ou à utiliser dans Stockage Blob Azure.
  • source est le chemin du nœud de l’arborescence d’enrichissement qui fournit la forme de la projection. Il doit s’agir d’un JSON valide. Le nœud doit fournir un objet JSON, soit à partir d’une compétence qui émet un code JSON valide, soit à partir de la sortie d’une compétence Modélisateur.

files
Chaque entrée de fichier définit le stockage des images binaires dans stockage Blob. Les projections de fichiers ont deux propriétés requises :
  • storageContainerest le nom du conteneur à créer ou à utiliser dans Stockage Blob Azure.
  • source est le chemin d’accès au nœud de l’arborescence d’enrichissement qui est la racine de la projection. Une valeur valide pour cette propriété est "/document/normalized_images/*" pour les images provenant du Stockage Blob.
encryptionKey facultatif. Permet de chiffrer une définition d’ensemble de compétences au repos avec vos propres clés, gérées dans votre Key Vault Azure. Disponible pour les services de recherche facturables créés le 01/01/2019.

Une encryptionKey section contient un défini par keyVaultKeyName l’utilisateur (obligatoire), un généré par keyVaultKeyVersion le système (obligatoire) et un keyVaultUri qui fournit la clé (obligatoire, également appelé nom DNS). Un exemple d’URI peut être « https://my-keyvault-name.vault.azure.net".

Si vous le souhaitez, vous pouvez spécifier accessCredentials si vous n’utilisez pas d’identité système managée. Propriétés de accessCredentials include applicationId (Microsoft Entra ID ID d’application qui a obtenu des autorisations d’accès à votre Key Vault Azure spécifié) et applicationSecret (clé d’authentification de l’application inscrite). Un exemple de la section suivante illustre la syntaxe.

response

Pour que votre demande aboutisse, vous devez voir le code d’état « 201 créé ».

Par défaut, le corps de la réponse contient le code JSON de la définition de l’ensemble de compétences qui a été créée. Toutefois, si l’en-tête Prefer de la requête est défini sur return=minimal, le corps de la réponse est vide et le code de réussite status est « 204 Aucun contenu » au lieu de « 201 Créé ». Cela est vrai, quelle que soit la méthode utilisée (PUT ou POST) pour créer l’ensemble de compétences.

Exemples

Exemple : Ensemble de compétences qui reconnaît les entités métier et les sentiments dans les avis des clients

Cet ensemble de compétences utilise deux compétences de manière asynchrone, en les traitant /document/content indépendamment sous la forme de deux transformations différentes. Les compétences sont Reconnaissance d’entité et sentiment. Dans l’arborescence d’enrichissement, /document/content fournit le contenu (ou les avis des clients) à partir de la source de données externe.

{
  "name": "reviews-ss",
  "description": 
  "Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
  "skills":
  [
    {
      "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
      "context": "/document/content",
      "categories": [ "Organization" ],
      "defaultLanguageCode": "en",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "organizations",
          "targetName": "companyName"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
      "inputs": [
           {
              "name": "text",
              "source": "/document/content"
           },
          {
               "name": "languageCode",
               "source": "/document/languageCode"
           }
        ],
      "outputs": [
        {
            "name": "sentiment",
            "targetName": "reviewSentiment"
        },
        {
            "name": "confidenceScores",
            "targetName": "sentimentScore"
        }
      ]
    }
  ],
  "cognitiveServices": 
    {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "description": "mycogsvcs resource in West US 2",
    "key": "<your cognitive services all-in-one key goes here>"
    },
  "knowledgeStore": { },
  "encryptionKey": { }
}

Exemple : Base de connaissances

Un ensemble de compétences peut éventuellement envoyer une sortie à la base de connaissances dans Stockage Azure. Il nécessite une chaîne de connexion à un compte stockage Azure et des projections qui déterminent si le contenu enrichi arrive dans le stockage de table ou d’objets blob (sous forme d’objets ou de fichiers). Les projections nécessitent généralement une compétence shaper amont qui collecte les nœuds d’une arborescence d’enrichissement en tant qu’entrée, en sortant une forme unique qui peut être passée à la projection. Un shaper est généralement la dernière compétence à traiter.

{
  "name": "reviews-ss",
  "description": 
  "Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
  "skills":
  [
    { ... },
    { ... },
    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "context": "/document/content",
      "inputs": [
        {
            "name": "Company",
            "source": "/document/content/companyName"
        },
        {
            "name": "Sentiment_Score",
            "source": "/document/content/sentimentScore"
        },
        {
            "name": "Sentiment_Label",
            "source": "/document/content/reviewSentiment"
        }
      ],
      "outputs": [
        {
          "name": "output",
          "targetName": "shapeCustomerReviews"
        }
      ]
    }
  ],
  "cognitiveServices": 
    {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "description": "mycogsvcs resource in West US 2",
    "key": "<your cognitive services all-in-one key goes here>"
    },
  "knowledgeStore": { 
      "storageConnectionString": "<your storage account connection string>", 
      "projections": [ 
          { 
            "tables": [ 
                { "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
                . . .
            ], 
            "objects": [ ], 
            "files": [ ]  
          }
      ]     
  } 
  "encryptionKey": { }
}

Exemple : clés de chiffrement

Les clés de chiffrement sont des clés gérées par le client utilisées pour le chiffrement supplémentaire du contenu sensible. Cet exemple montre comment spécifier un chiffrement géré par le client sur un ensemble de compétences.

{
    "name": "reviews-ss",
    "description": "A brief description of the skillset",
    "skills":  [ omitted for brevity ],
    "cognitiveServices": { omitted for brevity },
    "knowledgeStore":  { omitted for brevity  },
    "encryptionKey": (optional) { 
        "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
        "keyVaultKeyVersion": "Version of the Azure Key Vault key",
        "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
        "accessCredentials": (optional, only if not using managed system identity) {
            "applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
            "applicationSecret": "Authentication key of the specified Azure AD application)"}
    }
}

Voir aussi