Partager via

Créer ou mettre à jour un ensemble de compétences (API REST en préversion)

  • Article

s’applique à: 2023-07-01-Preview. Cette version n’est plus prise en charge. mettre à niveau immédiatement vers une version plus récente.

Important

2023-07-01-Preview (aucune modification).

2021-04-30-Preview ajoute la prise en charge des identités managées pour les connexions liées à l’ensemble de compétences :

  • « storageConnectionString » sous base de connaissances accepte un ID de ressource Azure pour l’authentification Azure AD.
  • « identité » accepte une identité managée affectée par l’utilisateur. Cette propriété se trouve sous base de connaissances. Il est également sous « encryptionKey » pour récupérer une clé gérée par le client dans Azure Key Vault.

Cette API en préversion prend également en charge une connexion d’identité managée à partir d’une compétence personnalisée. Pour plus d’informations, consultez informations de référence sur l’API web personnalisée.

Un ensemble de compétences est une collection de compétences cognitives utilisées pour l’enrichissement par IA, avec l’option de création d’une banque de connaissances externe dans stockage Azure. Les compétences appellent le traitement du langage naturel et d’autres processus de Machine Learning, tels 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 l’enrichissement et envoyer la 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 la référencer dans plusieurs indexeurs.

Vous pouvez utiliser POST ou PUT sur une demande de création. Pour l’une ou l’autre, le corps de la requête fournit la définition d’objet.

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

Pour les demandes de mise à jour, utilisez PUT et spécifiez le nom de l’ensemble de compétences sur l’URI.

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.

Création d’un ensemble de compétences l’ajoute à votre service de recherche.

La mise à jour d’un ensemble de compétences remplace entièrement un ensemble de compétences existant avec le contenu de la charge utile de la requête. Une bonne pratique pour les mises à jour consiste à récupérer la définition de l’ensemble de compétences avec une instruction GET, à la modifier, puis à la mettre à jour avec PUT.

Note

Les ensembles de compétences sont la base de '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 attacher une ressource Cognitive Services facturable.

Paramètres d’URI

Paramètre Description
nom du service Obligatoire. Définissez cette propriété 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. Une fois que vous avez démarré le nom avec une lettre ou un nombre, le reste du nom peut inclure n’importe quelle lettre, nombre et tirets, tant que les tirets ne sont pas consécutifs.
api-version Obligatoire. Consultez versions de l’API pour plus de versions.
disableCacheReprocessingChangeDetection Facultatif (false par défaut). S’applique aux scénarios de mise à jour et à l’utilisation d’enrichissements mis en cache pendant l’exécution de l’ensemble de compétences. Définissez la valeur true pour empêcher les mises à jour des documents existants en fonction de l’action actuelle, par exemple si vous souhaitez mettre à jour un ensemble de compétences sans exécuter l’ensemble de compétences. Pour plus d’informations, consultez Ignorer l’évaluation de l’ensemble de compétences.

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 propriété sur application/json
api-key Facultatif si vous utilisez rôles Azure et qu’un jeton du porteur est fourni sur la demande, sinon une clé est requise. Une clé API est une chaîne unique générée par le système qui authentifie la requête auprès de votre service de recherche. Les demandes de création doivent inclure un en-tête api-key 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. Une fois que vous avez démarré le nom avec une lettre ou un nombre, 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. Vous trouverez des informations de référence sur les compétences dans la documentation conceptuelle. Le tableau peut inclure compétences intégrées et 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 êtes définir la forme de données dans lede projection.
cognitiveServices Une clé tout-en-un est requise pour 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.

Vous pouvez omettre la clé et cette 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 d’extraction de documents .

Si vous utilisez la compétence recherche d’entité personnalisée, incluez cette section et une clé permettant d’activer les transactions au-delà de 20 transactions quotidiennes par indexeur.
knowledgeStore Optionnel. Destination pour la sortie d’enrichissement vers stockage Azure. Nécessite une chaîne de connexion à un compte de stockage Azure et projections.
encryptionKey Optionnel. Permet de chiffrer des données sensibles dans une définition d’ensemble de compétences avec vos propres clés, gérées dans votre coffre de clés Azure. Pour plus d’informations, consultez chiffrement Azure AI Search à l’aide de clés gérées par le client dans Azure Key Vault.

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 request est défini sur return=minimal, le corps de la réponse est vide et le code d’état de réussite est « 204 No Content » au lieu de « 201 Created ». Cela est vrai, que PUT ou POST soit utilisé pour créer l’ensemble de compétences.

Exemples

Exemple : Skillset 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 traitant de manière indépendante /document/content sous la forme de deux transformations différentes. Les compétences sont de 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 avec une chaîne de connexion d’accès complet et des entrées mises en forme

Une base de connaissances nécessite une chaîne de connexion à un compte de stockage Azure et projections qui déterminent si le contenu enrichi atterrit dans une table ou un stockage d’objets blob (en tant qu’objets ou fichiers).

Les projections, en particulier les projections de table, nécessitent une compétence d'Shaper en amont qui collecte les nœuds d’une arborescence d’enrichissement en entrée, en plaçant une forme unique qui peut être transmise à la projection. Un modélisateur est généralement la dernière compétence à traiter. Dans une projection de table, les nœuds de la compétence du modélisateur déterminent les champs de la table.

{
  "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": "DefaultEndpointsProtocol=https;AccountName=<storage-account-name>;AccountKey=<storage-account-key>;EndpointSuffix=core.windows.net;", 
      "projections": [ 
          { 
            "tables": [ 
                { "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
                . . .
            ], 
            "objects": [ ], 
            "files": [ ]  
          }
      ]     
  } 
  "encryptionKey": { }
}

exemple : Connexions à l’aide d’une d’identité managée

Les identités managées peuvent être utilisées sur les connexions à une base de connaissances et au code externe à partir d’une compétence personnalisée. Cet exemple illustre les deux scénarios. Pour la base de connaissances, la propriété « identité » supplémentaire spécifie une identité managée affectée par l’utilisateur affectée par l’utilisateur par le service de recherche qu’Azure AD utilise pour authentifier la demande. Si vous omettez « identité », l’identité managée affectée par le système du service de recherche est utilisée. Pour qu’Azure AD authentifie l’appelant, le service de recherche doit être configuré pour l’identité managée. L’identité de recherche doit disposer des autorisations « Contributeur aux données blob de stockage » pour écrire dans Stockage Azure.

Une compétence personnalisée peut utiliser une identité managée pour l’authentification auprès de la fonction Azure ou de l’application hébergeant votre code personnalisé. Il inclut une propriété « authResourceId » pour indiquer que la connexion est authentifiée à l’aide d’une identité managée. La valeur de « authResourceId » est l’ID d’application créé par le fournisseur d’identités Microsoft. Cette valeur sera utilisée pour valider le jeton d’authentification récupéré par l’indexeur, et sera envoyée avec la demande d’API de compétence Web personnalisée.

{
  "name": "reviews-ss",
  "description": "A short description",
  "skills":
  [
    { ... },
    { ... },
    {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "sampleCustomSkill",
        "description": "A custom skill that requests an access token for the application ID specified in authResourceID",
        "context": "/document",
        "uri": "https://[your-app-name].azurewebsites.net/api/EntitySearch",
        "authResourceId": "api://xyz*****-****-****-****-********9876",
        "batchSize": 4,
        "degreeOfParallelism": null,
        "inputs": [
          {
            "name": "text",
            "source": "/document/content"
          },
          {
            "name": "language",
            "source": "/document/languageCode"
          },
          {
            "name": "phraseList",
            "source": "/document/keyphrases"
          }
        ],
        "outputs": [
          {
            "name": "<customSkillOutput>"
          }
        ]
      }
    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "context": "/document/content",
      "inputs": [ ... ],
      "outputs": [ ...]
    }
  ],
  "cognitiveServices": { ... },
  "knowledgeStore": { 
      "storageConnectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;",
      "identity": {
          "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
          "userAssignedIdentity": "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user identity name]",
      "projections": [ 
          { 
            "tables": [ ], 
            "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 chiffrement supplémentaire de 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)"}
    }
}

Définitions

Lien Description
knowledgeStore Configure une connexion au stockage Azure et aux projets enrichis de contenu sous la forme d’objets, de fichiers et de tables pour utiliser des scénarios d’exploration de connaissances et de traitement des données.
encryptionKey Configure une connexion à Azure Key Vault pour le chiffrement géré par le client.

knowledgeStore

Une base de connaissances est un référentiel de données enrichies créées par un ensemble de compétences et un pipeline d’enrichissement par IA. Il réside dans stockage Azure et se compose de projections de données sous la forme d’objets, de fichiers et de tables. Il est utilisé pour les scénarios de non-recherche tels que l’exploration de connaissances, l’exploration des données dans Power BI ou comme récepteur de données pour un traitement plus en aval par d’autres applications.

La connexion au stockage Azure est une chaîne de connexion d’accès complet qui inclut une clé, ou l’ID de ressource de stockage fourni par le service de recherche exécuté sous une identité managée et dispose d’une attribution de rôle Azure lui accordant l’accès en écriture au point de terminaison du magasin de connaissances.

Attribut Description
storageConnectionString Obligatoire. Chaîne dans l’un des formats suivants :

"DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net"

"ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
identité Optionnel. Il contient une userAssignedIdentity de type #Microsoft.Azure.Search.DataUserAssignedIdentity et spécifie l’identité managée affectée par l’utilisateur du service de recherche. Cette propriété dépend de storageConnectionString avoir la chaîne de connexion qui spécifie un ID de ressource de votre compte de stockage.

Si la propriété identity a la valeur Null, la connexion à un ID de ressource est établie à l’aide de la propriété gérée par le système.

Si cette propriété est affectée au type #Microsoft.Azure.Search.DataNoneIdentity, toute identité explicite qui a été spécifiée précédemment est effacée.
projections Obligatoire. Tableau de projections composées de tables, objects, files, qui sont spécifiées ou null.

Projections

Les projections sont des définitions des structures de données au sein d’une base de connaissances. Tous les noms sont définis par l’utilisateur. Vous pouvez adopter une convention d’affectation de noms qui vous aide à identifier le contenu associé dans stockage Azure.

Attribut Description
Tables Projette des formes de données dans une ou plusieurs tables du Stockage Table Azure, où les éléments de chaque document sont projetés en lignes d’une table. Chaque table peut avoir les trois propriétés suivantes.

Tout d’abord, name (obligatoire) détermine la table à créer ou à utiliser dans stockage table Azure.

Deuxièmement, generatedKeyName (facultatif) est le nom d’une colonne qui identifie de manière 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.

Troisièmement, 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, puis é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 de tous les pays).
Objets Projette des documents en tant qu’objets blob dans Stockage Blob Azure. Chaque objet a deux propriétés requises.

Tout d’abord, storageContainer est le nom du conteneur à créer ou utiliser dans stockage Blob Azure.

Deuxièmement, 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.
Fichiers 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. Tout d’abord, storageContainer est le nom du conteneur à créer ou utiliser dans stockage Blob Azure.

Deuxièmement, 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 qui ont été sources à partir du stockage Blob.

encryptionKey

Configure une connexion à Azure Key Vault pour des clés de chiffrement gérées par le client (CMK) supplémentaires. Le chiffrement avec des clés gérées par le client n’est pas disponible pour les services gratuits. Pour les services facturables, il est disponible uniquement pour les services de recherche créés sur ou après 2019-01-01.

Une connexion au coffre de clés doit être authentifiée. Vous pouvez utiliser « accessCredentials » ou une identité managée à cet effet.

Les identités managées peuvent être affectées par le système ou par l’utilisateur (préversion). Si le service de recherche a une identité managée affectée par le système et une attribution de rôle qui accorde l’accès en lecture au coffre de clés, vous pouvez omettre à la fois « identité » et « accessCredentials », et la demande s’authentifie à l’aide de l’identité managée. Si le service de recherche a une identité affectée par l’utilisateur et une attribution de rôle, définissez la propriété « identity » sur l’ID de ressource de cette identité.

Attribut Description
keyVaultKeyName Obligatoire. Nom de la clé Azure Key Vault utilisée pour le chiffrement.
keyVaultKeyVersion Obligatoire. Version de la clé Azure Key Vault.
keyVaultUri Obligatoire. URI d’Azure Key Vault (également appelé nom DNS) qui fournit la clé. Un exemple d’URI peut être https://my-keyvault-name.vault.azure.net.
accessCredentials Omettez si vous utilisez une identité managée. Dans le cas contraire, les propriétés de accessCredentials incluent applicationId (ID d’application Azure Active Directory disposant des autorisations d’accès à votre coffre de clés Azure spécifié) et applicationSecret (clé d’authentification de l’application Azure AD spécifiée).
identité Facultatif, sauf si vous utilisez une identité managée affectée par l’utilisateur pour la connexion de service de recherche à Azure Key Vault. Le format est "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

Voir aussi