Erstellen eines Skillsets (Azure Cognitive Search REST-API)

Ein Skillset ist eine Sammlung kognitiver Qualifikationen, die für die KI-Anreicherung verwendet werden, mit einer optionalen Spezifikation zum Erstellen eines externen Wissensspeichers in Azure Storage. Qualifikationen rufen verarbeitung natürlicher Sprache und andere Transformationen auf, z. B. Entitätserkennung, Schlüsselbegriffserkennung, Blockierung von Text in logische Seiten, u.a.

Ein Skillset wird an einen Indexer angefügt. Um das Skillset zu verwenden, verweisen Sie in einem Indexer darauf, und führen Sie dann den Indexer aus, um Daten zu importieren, Transformationen und Anreicherungen aufzutreiben und die Ausgabefelder einem Index zu zuordnen. Ein Skillset ist eine Ressource auf hoher Ebene, funktioniert aber nur innerhalb der Indexerverarbeitung. Da es sich um eine Ressource auf hoher Ebene handelt, können Sie ein Skillset einmal erstellen und dann in mehreren Indexern darauf verweisen.

Sie können entweder POST oder PUT für die Anforderung verwenden. Für beide stellt das JSON-Dokument im Anforderungskörper die Objektdefinition zur Verfügung.

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

HTTPS ist für alle Dienstanforderungen erforderlich. Wenn das Skillset noch nicht vorhanden ist, wird es erstellt. Wenn er bereits vorhanden ist, wird er mit der neuen Definition aktualisiert.

Hinweis

Skillsets sind die Grundlage für die KI-Anreicherung. Eine kostenlose Ressource ist für die eingeschränkte Verarbeitung verfügbar, aber für größere oder häufigere Workloads ist eine Cognitive Services Ressource erforderlich.

URI-Parameter

Parameter Beschreibung
Dienstname Erforderlich. Legen Sie dies auf den eindeutigen, benutzerdefinierten Namen Ihres Suchdiensts fest.
Skillsetname Für den URI erforderlich, wenn PUT verwendet wird. Der Name muss klein geschrieben sein, mit einem Buchstaben oder einer Zahl beginnen, keine Schrägstriche oder Punkte enthalten und kleiner als 128 Zeichen sein. Nachdem der Name mit einem Buchstaben oder einer Zahl gestartet wurde, kann der Rest des Namens beliebige Buchstaben, Zahlen und Bindestriche enthalten, solange die Bindestriche nicht aufeinander folgenden sind.
api-version Erforderlich. Die aktuelle stabile Version ist api-version=2020-06-30 . Weitere Versionen finden Sie unter API-Versionen.

Anforderungsheader

Die folgende Tabelle beschreibt die erforderlichen und optionalen Anforderungsheader.

Felder BESCHREIBUNG
Content-Type Erforderlich. Auf application/json
api-key Erforderlich. api-key wird zum Authentifizieren der Anforderung beim Search-Dienst verwendet. Es handelt sich um einen für Ihren Dienst eindeutigen Zeichenfolgewert. Create requests must include an header set to your admin key (im Gegensatz api-key zu einem Abfrageschlüssel). Sie finden den API-Schlüssel in Ihrem Suchdienstdashboard im Azure-Portal.

Anforderungstext

Der Anforderungsteil enthält die Skillsetdefinition. Skills sind entweder eigenständig oder durch Eingabe-/Ausgabezuordnungen miteinander verkettet, wobei die Ausgabe einer Transformation zu einer Eingabe für eine andere transformation wird. Ein Skillset muss mindestens einen Skill umfassen. Theoretisch gibt es keine Obergrenze für die Anzahl von Skills, drei bis fünf ist jedoch eine gängige Konfiguration.

Der folgende JSON-Code ist eine darstellung der Hauptteile der Definition auf hoher Ebene.

{   
  "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) { }
} 

Die Anforderung enthält die folgenden Eigenschaften:

Eigenschaft Beschreibung
name Erforderlich. Der Name des Skillsets. Der Name muss klein geschrieben sein, mit einem Buchstaben oder einer Zahl beginnen, keine Schrägstriche oder Punkte enthalten und kleiner als 128 Zeichen sein. Nachdem der Name mit einem Buchstaben oder einer Zahl gestartet wurde, kann der Rest des Namens beliebige Buchstaben, Zahlen und Bindestriche enthalten, solange die Bindestriche nicht aufeinander folgenden sind.
skills Ein Array von Qualifikationen. Jeder Skill verfügt über einen odata.type-, Name-, Kontext- sowie Eingabe- und Ausgabeparameter. Das Array kann integrierte Qualifikationen und benutzerdefinierte Qualifikationen enthalten. Mindestens eine Qualifikation ist erforderlich. Wenn Sie einen Wissensspeicher verwenden, schließen Sie eine Shaper-Qualifikation ein, es sei denn, Sie definieren die Datenform innerhalb der Projektion.
cognitiveServices Ein All-in-One-Schlüssel ist für agerechnete Qualifikationen erforderlich, Cognitive Services-APIs täglich mehr als 20 Dokumente pro Indexer aufrufen. Der Schlüssel muss für eine Ressource in derselben Region wie der Suchdienst sein. Weitere Informationen finden Sie unter Anfügen einer Cognitive Services Ressource.

Sie können den Schlüssel und diesen Abschnitt weglassen, wenn Ihr Skillset nur aus benutzerdefinierten Qualifikationen, Hilfsprogrammkenntnissen (Bedingt, Shaper, Textzusammenführung, Textaufteilung) oder der Qualifikation Dokumentextraktion besteht.

Wenn Sie die Qualifikation Benutzerdefinierte Entitätssuche verwenden, fügen Sie diesen Abschnitt und einen Schlüssel ein, um Transaktionen über 20 Transaktionen pro Tag pro Indexer zu aktivieren.
knowledgeStore Optional. Ziel für die Anreicherungsausgabe Azure Storage. Erfordert eine Verbindungszeichenfolge für ein Azure Storage-Konto und Projektionen.

storageConnectionString (erforderlich) Eine Zeichenfolge in diesem Format: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net" .

projections (erforderlich) Ein Array von Projektionsobjekten, das tables aus , , besteht und entweder angegeben oder NULL objects files ist.

tables
Erstellt eine oder mehrere Tabellen in Azure Table Storage, die Inhalte aus jedem Dokument als Zeilen in einer Tabelle pro projectieren. Jede Tabelle kann die folgenden drei Eigenschaften aufweisen:
  • name(erforderlich) bestimmt die Tabelle, die in Azure Table Storage.
  • generatedKeyName (optional) ist der Name einer Spalte, die ein Dokument eindeutig identifiziert. Werte für diese Spalte werden während der Anreicherung generiert. Wenn Sie sie weglassen, erstellt der Suchdienst basierend auf dem Tabellennamen eine Standardschlüsselspalte.
  • source(erforderlich) ist der Pfad zu einem Knoten der Anreicherungsstruktur, der die Form der Projektion annimmt. Dies ist normalerweise die Ausgabe einer Shaper-Qualifikation. Pfade beginnen mit , die das mit dem Stamm angereicherte Dokument darstellen, und werden dann auf , oder oder einen anderen Knoten innerhalb der /document/ /document/<shaper-output>/ /document/content/ Anreicherungsstruktur erweitert. Beispiele: /document/countries/* (alle Länder) oder /document/countries/*/states/* (alle Bundesländer/-staaten in allen Ländern).

objects
Projekte für Dokumente als Blobs in Azure Blob Storage. Jedes Objekt verfügt über zwei erforderliche Eigenschaften:
  • storageContainerist der Name des Containers, der in Azure Blob Storage.
  • source ist der Pfad zum Knoten der Anreicherungsstruktur, der die Form der Projektion annimmt. Es muss ein gültiger JSON-Code sein. Der Knoten muss ein JSON-Objekt bereitstellen, entweder von einer Qualifikation, die gültigen JSON-Code aus gibt, oder der Ausgabe einer Shaper-Qualifikation.

files
Jeder Dateieintrag definiert die Speicherung von Binärbildern in Blob Storage. Dateiprojektionen verfügen über zwei erforderliche Eigenschaften:
  • storageContainerist der Name des Containers, der in Azure Blob Storage.
  • source ist der Pfad zum Knoten der Anreicherungsstruktur, der der Stamm der Projektion ist. Ein gültiger Wert für diese Eigenschaft ist "/document/normalized_images/*" für Bilder, die aus Blob-Storage.
encryptionKey Optional. Wird verwendet, um ruhende Skillsetdefinitionen mit Ihren eigenen Schlüsseln zu verschlüsseln, die in Ihrer Azure Key Vault. Verfügbar für agerechnete Suchdienste, die am oder nach dem 01.01.2019 erstellt wurden.

Ein Abschnitt enthält einen benutzerdefinierten (erforderlichen) , einen vom System generierten (erforderlich) und einen , der den Schlüssel (erforderlich, auch als encryptionKey keyVaultKeyName keyVaultKeyVersion keyVaultUri DNS-Name bezeichnet) enthält. Ein Beispiel-URI könnte " " https://my-keyvault-name.vault.azure.net sein.

Optional können Sie angeben, accessCredentials ob Sie keine verwaltete Systemidentität verwenden. Zu den Eigenschaften von accessCredentials applicationId gehören (Azure Active Directory Anwendungs-ID, der Zugriffsberechtigungen für ihre angegebene Azure Key Vault erteilt wurden) und (Authentifizierungsschlüssel der angegebenen Azure AD applicationSecret Anwendung). Ein Beispiel im nächsten Abschnitt veranschaulicht die Syntax.

Antwort

Bei einer erfolgreichen Anforderung wird der Statuscode „201 – erstellt“ angezeigt.

Standardmäßig enthält der Antworttext das JSON-Schema für die erstellte Skillsetdefinition. Wenn der Prefer-Anforderungsheader jedoch auf „return=minimal“ festgelegt ist, ist der Antworttext leer und der Statuscode lautet „204 – kein Inhalt“ statt „201 – erstellt“. Dies gilt unabhängig davon, ob zum Erstellen des Skillsets eine PUT- oder eine POST-Anforderung verwendet wurde.

Beispiele

Beispiel: Skillset, das Geschäftsentitäten und Stimmungen in Kundenbewertungen erkennt

Dieses Skillset verwendet zwei Qualifikationen asynchron, die unabhängig als /document/content zwei unterschiedliche Transformationen verarbeitet werden. Die Qualifikationen sind Entitätserkennung und Stimmung. Stellt in der /document/content Anreicherungsstruktur den Inhalt (oder Kundenüberprüfungen) aus der externen Datenquelle dar.

{
  "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": { }
}

Beispiel: Wissensspeicher

Ein Skillset kann optional Ausgaben an den Wissensspeicher im Azure Storage. Sie erfordert eine Verbindungszeichenfolge zu einem Azure Storage-Konto und Projektionen, die bestimmen, ob angereicherte Inhalte in Tabellen- oder Blobspeicher (als Objekte oder Dateien) landen. Projektionen erfordern in der Regel eine Vorstufen-Shaper-Qualifikation, die Knoten aus einer Anreicherungsstruktur als Eingabe sammelt und eine einzelne Form aus gibt, die an die Projektion übergeben werden kann. Ein Shaper ist in der Regel die letzte Zu verarbeitende Qualifikation.

{
  "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": { }
}

Beispiel: Verschlüsselungsschlüssel

Verschlüsselungsschlüssel sind vom Kunden verwaltete Schlüssel, die für die zusätzliche Verschlüsselung vertraulicher Inhalte verwendet werden. In diesem Beispiel wird gezeigt, wie Sie die vom Kunden verwaltete Verschlüsselung für ein Skillset angeben.

{
    "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)"}
    }
}

Siehe auch