Erstellen eines Wissensspeichers mithilfe von REST

  • Artikel

In Azure AI Search ist ein Wissensspeicher ein Repository von KI-generierten Inhalten, die für Nicht-Suchszenarien verwendet werden. Sie erstellen den Wissensspeicher mit einem Indexer und Skillset, und geben den Azure Storage an, um die Ausgabe zu speichern. Nachdem der Wissensspeicher gefüllt wurde, können Sie Tools wie Storage-Explorer oder Power BI zum Untersuchen des Inhalts verwenden.

In diesem Artikel verwenden Sie die REST-API zum Erfassen, Anreichern und Untersuchen von Kundenbewertungen zu Hotelaufenthalten in einem Wissensspeicher. Der Wissensspeicher enthält Originaltext aus der Quelle sowie mittels KI generierte Inhalte, darunter eine Stimmungsbewertung, Schlüsselbegriffsextraktion, Spracherkennung und Textübersetzungen von nicht englischsprachigen Kundenkommentaren.

Um das anfängliche DataSet verfügbar zu machen, werden die Hotelrezensionen zuerst in Azure Blob Storage importiert. Bei der Nachbearbeitung werden die Ergebnisse als Wissensspeicher in Azure Table Storage gespeichert.

Tipp

In diesem Artikel wird REST für detaillierte Erläuterungen zu den einzelnen Schritten verwendet. Laden Sie die REST-Datei herunter, wenn Sie nur die Befehle ausführen möchten. Alternativ können Sie auch einen Wissensspeicher im Azure-Portal erstellen.

Voraussetzungen

Das Skillset in diesen Beispielen verwendet Azure KI Services für Anreicherungen. Aufgrund der geringen Workloadgröße wird Azure AI Services im Hintergrund genutzt und bietet eine kostenlose Verarbeitung von bis zu 20 Transaktionen pro Tag. Eine kleine Workload bedeutet, dass Sie das Erstellen oder Anfügen einer Azure AI Multi-Service-Ressource überspringen können.

Hochladen von Daten in Azure Storage und Abrufen einer Verbindungszeichenfolge

  1. Laden Sie „HotelReviews_Free.csv“ herunter. Diese CSV-Datei enthält 19 Einträge mit Kundenfeedback zu einem einzigen Hotel (aus Kaggle.com).

  2. Suchen Sie im Azure-Portal Ihr Speicherkonto, und verwenden Sie Speicherbrowser, um einen BLOB-Container mit dem Namen hotel-reviews zu erstellen.

  3. Wählen Sie oben auf der Seite Hochladen aus, um die Datei HotelReviews-Free.csv zu laden, die Sie im vorherigen Schritt heruntergeladen haben.

    Screenshot of Storage Browser with uploaded file and left nav pane

  4. Wählen Sie auf der linken Seite Zugriffstasten aus, wählen Sie Schlüssel anzeigen aus, und kopieren Sie dann die Verbindungszeichenfolge für key1 oder key2. Eine vollständige Verbindungszeichenfolge weist das folgende Format auf:

"knowledgeStore": {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-ACCOUNT-NAME>;AccountKey=<YOUR-ACCOUNT-KEY>;EndpointSuffix=core.windows.net;"
}

Hinweis

Lesen Sie Herstellen einer Verbindung mithilfe einer verwalteten Identität, wenn Sie keine vertraulichen Daten in der Verbindungszeichenfolge bereitstellen möchten.

Kopieren eines Schlüssels und einer URL

In diesem Beispiel erfordern REST-Aufrufe den Suchdienstendpunkt und verwenden einen API-Schlüssel für jede Anforderung. Diese Werte erhalten Sie im Azure-Portal.

  1. Melden Sie sich im Azure-Portal an, navigieren Sie zur Seite Übersicht, und kopieren Sie die URL. Ein Beispiel für einen Endpunkt ist https://mydemo.search.windows.net.

  2. Kopieren Sie unter Einstellungen>Schlüssel einen Administratorschlüssel. Mit einem Administratorschlüssel können Sie Objekte hinzufügen, ändern und löschen. Es gibt zwei austauschbare Administratorschlüssel. Kopieren Sie einen der beiden Schlüssel.

    Screenshot of the URL and API keys in the Azure portal.

Ein gültiger API-Schlüssel stellt für jede Anforderung eine Vertrauensstellung her zwischen der Anwendung, die die Anforderung sendet, und dem Suchdienst, der sie verarbeitet.

Erstellen eines Index

Index erstellen (REST) erstellt einen Suchindex für den Suchdienst. Ein Suchindex hat nichts mit einem Wissensspeicher zu tun, aber der Indexer verlangt einen. Der Suchindex enthält denselben Inhalt wie der Wissensspeicher, den Sie durchsuchen können, indem Sie Abfrageanforderungen senden.

  1. Öffnen Sie eine neue Textdatei in Visual Studio Code.

  2. Legen Sie Variablen auf den Suchendpunkt und den API-Schlüssel fest, den Sie zuvor gesammelt haben.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@apiKey = PUT-YOUR-ADMIN-API-KEY-HERE
@storageConnection = PUT-YOUR-STORAGE-CONNECTION-STRING-HERE
@blobContainer = PUT-YOUR-CONTAINER-NAME-HERE (hotel-reviews)

  3. Speichern Sie die Datei nicht mit einer .rest-Dateierweiterung.

  4. Fügen Sie das folgende Beispiel ein, um die Indexanforderung zu erstellen.

    ### Create a new index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-idx",  
        "fields": [
            { "name": "name", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_date", "type": "Edm.DateTimeOffset", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_rating", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_text", "type": "Edm.String", "filterable": false,  "sortable": false, "facetable": false },
            { "name": "reviews_title", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_username", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "AzureSearch_DocumentKey", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false, "key": true },
            { "name": "language", "type": "Edm.String", "filterable": true, "sortable": false, "facetable": true },
            { "name": "translated_text", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false },
            { "name": "sentiment", "type": "Collection(Edm.String)", "searchable": false, "filterable": true, "retrievable": true, "sortable": false, "facetable": true },
            { "name": "keyphrases", "type": "Collection(Edm.String)", "filterable": true, "sortable": false, "facetable": true }
        ]
    }

  5. Klicken Sie auf Anforderung senden. Es sollte die Antwort HTTP/1.1 201 Created angezeigt werden, deren Antworttext die JSON-Darstellung des Indexschemas enthält.

Erstellen einer Datenquelle

Datenquelle erstellen erstellt eine Datenquellenverbindung in Azure KI-Suche.

  1. Fügen Sie das folgende Beispiel ein, um die Datenquelle zu erstellen.

    ### Create a data source
POST {{baseUrl}}/datasources?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-ds",
        "description": null,
        "type": "azureblob",
        "subtype": null,
        "credentials": {
            "connectionString": "{{storageConnectionString}}"
        },
        "container": {
            "name": "{{blobContainer}}",
            "query": null
        },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null
    }

  2. Klicken Sie auf Anforderung senden.

Erstellen eines Skillsets

Ein Skillset definiert Anreicherungen (Fähigkeiten) und Ihren Wissensspeicher. Skillset erstellen erstellt das Objekt in Ihrem Suchdienst.

  1. Fügen Sie das folgende Beispiel ein, um das Skillset zu erstellen.

    ### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-ss",
        "description": "Skillset to detect language, translate text, extract key phrases, and score sentiment",
        "skills": [ 
            {
                "@odata.type": "#Microsoft.Skills.Text.SplitSkill", 
                "context": "/document/reviews_text", "textSplitMode": "pages", "maximumPageLength": 5000,
                "inputs": [ 
                    { "name": "text", "source": "/document/reviews_text" }
                ],
                "outputs": [
                    { "name": "textItems", "targetName": "pages" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
                "context": "/document/reviews_text/pages/*",
                "inputs": [
                    { "name": "text", "source": "/document/reviews_text/pages/*" },
                    { "name": "languageCode", "source": "/document/language" }
                ],
                "outputs": [
                    { "name": "sentiment", "targetName": "sentiment" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
                "context": "/document",
                "inputs": [
                    { "name": "text", "source": "/document/reviews_text" }
                ],
                "outputs": [
                    { "name": "languageCode", "targetName": "language" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.TranslationSkill",
                "context": "/document/reviews_text/pages/*",
                "defaultFromLanguageCode": null,
                "defaultToLanguageCode": "en",
                "inputs": [
                    { "name": "text", "source": "/document/reviews_text/pages/*" }
                ],
                "outputs": [
                    { "name": "translatedText", "targetName": "translated_text" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
                "context": "/document/reviews_text/pages/*",
                "inputs": [
                    { "name": "text",  "source": "/document/reviews_text/pages/*" },
                    { "name": "languageCode",  "source": "/document/language" }
                ],
                "outputs": [
                    { "name": "keyPhrases" , "targetName": "keyphrases" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
                "context": "/document",
                "inputs": [
                    { "name": "name",  "source": "/document/name" },
                    { "name": "reviews_date",  "source": "/document/reviews_date" },
                    { "name": "reviews_rating",  "source": "/document/reviews_rating" },
                    { "name": "reviews_text",  "source": "/document/reviews_text" },
                    { "name": "reviews_title",  "source": "/document/reviews_title" },
                    { "name": "reviews_username",  "source": "/document/reviews_username" },
                    { "name": "AzureSearch_DocumentKey",  "source": "/document/AzureSearch_DocumentKey" },
                    {
                    "name": "pages",
                    "sourceContext": "/document/reviews_text/pages/*",
                    "inputs": [
                        {
                        "name": "languageCode",
                        "source": "/document/language"
                        },
                        {
                        "name": "translatedText",
                        "source": "/document/reviews_text/pages/*/translated_text"
                        },
                        { 
                        "name": "sentiment",
                        "source": "/document/reviews_text/pages/*/sentiment"
                        },
                        {
                        "name": "keyPhrases",
                        "source": "/document/reviews_text/pages/*/keyphrases/*"
                        },
                        {
                        "name": "Page",
                        "source": "/document/reviews_text/pages/*"
                        }
                    ]
                    }
                ],
                "outputs": [
                    { "name": "output" , "targetName": "tableprojection" }
                ]
            }
        ],
        "knowledgeStore": {
            "storageConnectionString": "{{storageConnectionString}}",
            "projections": [
                {
                    "tables": [
                        { "tableName": "hotelReviews1Document", "generatedKeyName": "Documentid", "source": "/document/tableprojection" },
                        { "tableName": "hotelReviews2Pages", "generatedKeyName": "Pagesid", "source": "/document/tableprojection/pages/*" },
                        { "tableName": "hotelReviews3KeyPhrases", "generatedKeyName": "KeyPhrasesid", "source": "/document/tableprojection/pages/*/keyPhrases/*" }
                    ],
                    "objects": []
                },
                {
                    "tables": [
                        { 
                            "tableName": "hotelReviews4InlineProjectionDocument", "generatedKeyName": "Documentid", "sourceContext": "/document",
                            "inputs": [
                                { "name": "name", "source": "/document/name"},
                                { "name": "reviews_date", "source": "/document/reviews_date"},
                                { "name": "reviews_rating", "source": "/document/reviews_rating"},
                                { "name": "reviews_username", "source": "/document/reviews_username"},
                                { "name": "reviews_title", "source": "/document/reviews_title"},
                                { "name": "reviews_text", "source": "/document/reviews_text"},
                                { "name": "AzureSearch_DocumentKey", "source": "/document/AzureSearch_DocumentKey" }
                            ]
                        },
                        { 
                            "tableName": "hotelReviews5InlineProjectionPages", "generatedKeyName": "Pagesid", "sourceContext": "/document/reviews_text/pages/*",
                            "inputs": [
                                { "name": "Sentiment", "source": "/document/reviews_text/pages/*/sentiment"},
                                { "name": "LanguageCode", "source": "/document/language"},
                                { "name": "Keyphrases", "source": "/document/reviews_text/pages/*/keyphrases"},
                                { "name": "TranslatedText", "source": "/document/reviews_text/pages/*/translated_text"},
                                { "name": "Page", "source": "/document/reviews_text/pages/*" }
                            ]
                        },
                        { 
                            "tableName": "hotelReviews6InlineProjectionKeyPhrases", "generatedKeyName": "kpidv2", "sourceContext": "/document/reviews_text/pages/*/keyphrases/*",
                            "inputs": [
                                { "name": "Keyphrases", "source": "/document/reviews_text/pages/*/keyphrases/*" }
                            ]
                        }
                    ],
                    "objects": []
                }
            ]
        }
    }

Die wichtigsten Punkte:

  • Die Shaper-Fähigkeit ist wichtig für die Definition des Wissensspeichers. Sie gibt an, wie die Daten in die Tabellen des Wissensspeichers fließen. Die Eingaben sind die Teile des angereicherten Dokuments, die Sie speichern möchten. Die Ausgabe ist eine Konsolidierung der Knoten in einer einzigen Struktur.

  • Projektionen geben die Tabellen, Objekte und Blobs Ihres Wissensspeichers an. Jedes Projektionselement gibt die "name" der Spalten oder Felder an, die in Azure Storage erstellt werden sollen. Die "source" gibt an, welcher Teil der Shaper-Ausgabe diesem Feld oder dieser Spalte zugewiesen ist.

Erstellen eines Indexers

Indexer erstellen erstellt den Indexer und führt ihn aus. Die Ausführung des Indexers beginnt mit der Entschlüsselung der Dokumente, dem Extrahieren von Text und Bildern und der Initialisierung des Skillsets. Der Indexer sucht nach den anderen Objekten, die Sie erstellt haben: Datenquelle, Index und Skillset.

  1. Fügen Sie das folgende Beispiel ein, um den Indexer zu erstellen.

    ### Create indexer
POST {{baseUrl}}/indexers?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-idxr",
        "dataSourceName": "hotel-reviews-kstore-ds",
        "skillsetName": "hotel-reviews-kstore-ss",
        "targetIndexName": "hotel-reviews-kstore-idx",
        "parameters": {
            "configuration": {
                "dataToExtract": "contentAndMetadata",
                "parsingMode": "delimitedText",
                "firstLineContainsHeaders": true,
                "delimitedTextDelimiter": ","
    }
},
"fieldMappings": [
    {
        "sourceFieldName": "AzureSearch_DocumentKey",
        "targetFieldName": "AzureSearch_DocumentKey",
        "mappingFunction": { "name": "base64Encode" }
    }
],
"outputFieldMappings": [
    { "sourceFieldName": "/document/reviews_text/pages/*/Keyphrases/*", "targetFieldName": "Keyphrases" },
    { "sourceFieldName": "/document/Language", "targetFieldName": "Language" },
    { "sourceFieldName": "/document/reviews_text/pages/*/Sentiment", "targetFieldName": "Sentiment" }
    ]
}

  2. Wählen Sie Anforderung senden aus, um den Indexer zu erstellen und auszuführen. Dieser Schritt dauert mehrere Minuten.

Die wichtigsten Punkte:

  • Das parameters/configuration-Objekt steuert die Erfassung der Daten durch den Indexer. In diesem Fall befinden sich die Eingabedaten in einer einzigen CSV-Datei, die über eine Kopfzeile und durch Trennzeichen getrennte Werte verfügt.

  • Feldzuordnungen erstellen „AzureSearch_DocumentKey“, einen eindeutigen Bezeichner jedes Dokuments, der (basierend auf dem Speicherpfad der Metadaten) vom Blobindexer generiert wird.

  • Ausgabefeldzuordnungen geben an, wie angereicherte Felder Feldern in einem Suchindex zugeordnet werden. Ausgabefeldzuordnungen werden nicht in Wissensspeichern verwendet (denn Wissensspeicher nutzen Formen und Projektionen, um die physischen Datenstrukturen auszudrücken).

Status überprüfen

Nach dem Senden der einzelnen Anforderungen sollte der Dienst mit der Erfolgsmeldung 201 antworten.

### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/hotel-reviews-kstore-idxr/status?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

Nach einigen Minuten können Sie den Index abfragen, um den Inhalt zu prüfen. Auch wenn Sie den Index nicht verwenden, ist dieser Schritt eine bequeme Möglichkeit zu bestätigen, dass das Skillset die erwartete Ausgabe erzeugt hat.

### Query the index (indexer status must be "success" before querying the index)
POST {{baseUrl}}/indexes/hotel-reviews-kstore-idxr/docs/search?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}
  
  {
    "search": "*",
    "select": "reviews_title, reviews_username, language, translated_text, sentiment",
    "count": true
  }

Überprüfen von Tabellen im Azure-Portal

Wechseln Sie im Azure-Portal zu Ihrem Azure Storage-Konto, und zeigen Sie im Speicherbrowser die neuen Tabellen an. Es sollten sechs Tabellen angezeigt werden, und zwar eine für jede im Skillset definierte Projektion.

Jede Tabelle wird mit den IDs generiert, die für die Kreuzverknüpfung der Tabellen in Abfragen erforderlich sind. Scrollen Sie beim Öffnen einer Tabelle über diese Felder, um die von der Pipeline hinzugefügten Inhaltsfelder anzuzeigen.

Screenshot of the knowledge store tables in Storage Browser

In dieser exemplarischen Vorgehensweise besteht der Wissensspeicher aus einer Reihe von Tabellen, die verschiedene Möglichkeiten zur Gestaltung und Strukturierung einer Tabelle aufzeigen. Die erste Gruppe mit drei Tabellen zeigt, wie die Ausgabe eines Skills für Shaper die Spalten und Zeilen festlegt. Die Tabellen 4 bis 6 werden aus Anweisungen zur Inline-Gestaltung erstellt, die in die Projektion selbst eingebettet sind. Bei beiden Ansätzen erzielen Sie das gleiche Ergebnis.

Tabelle Beschreibung
hotelReviews1Document Enthält Felder, die der CSV-Datei entnommen werden, z. B. reviews_date und reviews_text.
hotelReviews2Pages Enthält angereicherte Felder, die vom Skillset erstellt wurden, z. B. Stimmungsbewertung und übersetzter Text.
hotelReviews3KeyPhrases Enthält eine lange Liste nur der Schlüsselbegriffe.
hotelReviews4InlineProjectionDocument Alternative zur ersten Tabelle, wobei die Inlinegestaltung anstelle des Skills für Shaper verwendet wird, um Daten für die Projektion zu strukturieren.
hotelReviews5InlineProjectionPages Alternative zur zweiten Tabelle mit Inlinegestaltung.
hotelreviews6InlineProjectionKeyPhrases Alternative zur dritten Tabelle mit Inlinegestaltung.

Bereinigen

Wenn Sie in Ihrem eigenen Abonnement arbeiten, sollten Sie sich am Ende eines Projekts überlegen, ob Sie die erstellten Ressourcen noch benötigen. Ressourcen, die weiterhin ausgeführt werden, können Sie Geld kosten. Sie können entweder einzelne Ressourcen oder aber die Ressourcengruppe löschen, um den gesamten Ressourcensatz zu entfernen.

Ressourcen können im Portal über den Link Alle Ressourcen oder Ressourcengruppen im linken Navigationsbereich gesucht und verwaltet werden.

Nächste Schritte

Nachdem Sie Ihre Daten mit Azure AI Services angereichert und die Ergebnisse in einen Wissensspeicher projiziert haben, können Sie mit Storage-Explorer oder anderen Apps Ihr angereichertes Dataset erkunden.

Erste Schritte mit dem Storage-Explorer