Partager via

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

Important

Cette référence d’API concerne une version héritée. Consultez les opérations REST du plan de données pour obtenir la documentation de référence mise à jour. Utilisez le filtre en haut à gauche pour sélectionner une version.

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é, l’extraction d’expressions clés, la segmentation du texte dans des 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 l’enrichissement, puis mapper les champs de sortie à un index. Un ensemble de compétences est une ressource de haut niveau, mais elle est opérationnelle uniquement dans le traitement de l’indexeur. En tant que ressource de haut niveau, 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 d’objet.

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

HTTPS est requis pour toutes les demandes 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.

Remarque

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

Paramètres d’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 nombre, n’avoir aucune barre oblique ni point, et être inférieur à 128 caractères. Le nom doit commencer par une lettre ou un nombre, mais le reste du nom peut inclure n’importe quelle lettre, nombre et tirets, tant que les tirets ne sont pas consécutifs.
version de l'API Obligatoire. Consultez les 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 requête obligatoires et facultatifs.

Champs Description
Type de contenu Obligatoire. Définissez cette valeur sur application/json
clé API 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 de sortie d’entrée, 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’existe aucune limite théorique quant au nombre maximal de compétences, mais trois à cinq sont une configuration commune.

Le code JSON suivant est une représentation générale des parties principales 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 contient les propriétés suivantes :

Propriété Description
nom Obligatoire. Nom de l’ensemble de compétences. Le nom doit être en minuscules, commencer par une lettre ou un nombre, n’avoir aucune barre oblique ni point, et être inférieur à 128 caractères. Le nom doit commencer par une lettre ou un nombre, mais le reste du nom peut inclure n’importe quelle lettre, nombre et tirets, tant que les tirets ne sont pas consécutifs.
compétences 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 Shaper , 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 des API Cognitive Services sur plus de 20 documents quotidiennement, 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 quotidiennes par indexeur.

Vous n’avez pas besoin de la 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 (conditionnel, modélisateur, fusion de texte, fractionnement de texte) ou de la compétence Extraction de document. Si vous souhaitez supprimer votre ressource cognitive service jointe d’un ensemble de compétences (pour revenir à l’utilisation des limites par défaut) spécifiez @odata.type comme #Microsoft.Azure.Search.DefaultCognitiveServices, consultez cet exemple pour plus d’informations.
knowledgeStore Optionnel. Destination pour 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, filesqui sont spécifiés ou null.

tables
Crée une ou plusieurs tables dans Stockage Table Azure, projetant du contenu à partir 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 de façon unique un document. Les valeurs de cette colonne seront générées lors de 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 Shaper. Les chemins commencent par /document/, représentant le document enrichi racine et sont ensuite étendus à /document/<shaper-output>/, ou /document/content/à 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 :
  • storageContainer est 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 fournit la forme de la projection. Il doit être json valide. Le nœud doit fournir un objet JSON, à partir d’une compétence qui émet un JSON valide ou la sortie d’une compétence Shaper.

files
Chaque entrée de fichier définit le stockage d’images binaires dans le stockage Blob. Les projections de fichiers ont deux propriétés requises :
  • storageContainer est 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é concerne "/document/normalized_images/*" les images provenant du stockage Blob.
encryptionKey Optionnel. Utilisé pour chiffrer une définition d’ensemble de compétences au repos avec vos propres clés, géré dans votre coffre de clés Azure. Disponible pour les services de recherche facturables créés le ou après 2019-01-01.

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

Vous pouvez éventuellement spécifier accessCredentials si vous n’utilisez pas d’identité de système managé. Propriétés d’include applicationId (ID d’application accessCredentials Microsoft Entra ID qui a reçu des autorisations d’accès à votre coffre de clés Azure spécifié) et applicationSecret (clé d’authentification de l’application inscrite). Un exemple dans la section suivante illustre la syntaxe.

Réponse

Pour une demande réussie, vous devez voir le code d’état « 201 Créé ».

Par défaut, le corps de la réponse contient le JSON pour la définition d’ensemble de compétences créée. Toutefois, si l’en-tête Prefer de requête est défini return=minimalsur , le corps de la réponse est vide et le code d’état de réussite est « 204 Aucun contenu » au lieu de « 201 Créé ». Cela est vrai, que PUT ou POST soit utilisé 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 façon asynchrone, en traitant /document/content indépendamment les deux transformations différentes. Les compétences sont La reconnaissance d’entité et le 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 à une base de connaissances dans stockage Azure. Il nécessite une chaîne de connexion à un compte de stockage Azure et des projections qui déterminent si le contenu enrichi atterrit dans un stockage table ou blob (en tant qu’objets ou fichiers). Les projections nécessitent généralement une compétence Shaper en amont qui collecte les nœuds d’une arborescence d’enrichissement en tant qu’entrée, en plaçant une forme unique qui peut être passée à la projection. Un modélisateur 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 un chiffrement supplémentaire du contenu sensible. Cet exemple montre comment spécifier le 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