Een kennisarchief maken met behulp van REST

  • Artikel

In Azure AI Search is een kennisarchief een opslagplaats met door AI gegenereerde inhoud die wordt gebruikt voor niet-zoekscenario's. U maakt het kennisarchief met behulp van een indexeerfunctie en vaardighedenset en geeft Azure Storage op om de uitvoer op te slaan. Nadat het kennisarchief is ingevuld, gebruikt u hulpprogramma's zoals Storage Explorer of Power BI om de inhoud te verkennen.

In dit artikel gebruikt u de REST API om een set klantbeoordelingen van hotelverblijven in een kennisarchief op te nemen, te verrijken en te verkennen. Het kennisarchief bevat oorspronkelijke tekstinhoud die is opgehaald uit de bron, plus door AI gegenereerde inhoud met een gevoelsscore, sleuteltermextractie, taaldetectie en tekstomzetting van niet-Engelse opmerkingen van klanten.

Als u de eerste gegevensset beschikbaar wilt maken, worden de hotelbeoordelingen eerst geïmporteerd in Azure Blob Storage. Na verwerking worden de resultaten opgeslagen als kennisarchief in Azure Table Storage.

Tip

In dit artikel wordt REST gebruikt voor gedetailleerde uitleg van elke stap. Download het REST-bestand als u alleen de opdrachten wilt uitvoeren. U kunt ook een kennisarchief maken in Azure Portal.

Vereisten

De vaardighedenset in deze voorbeelden maakt gebruik van Azure AI Services voor verrijkingen. Omdat de workload zo klein is, wordt achter de schermen op Azure AI-services getikt om maximaal 20 transacties dagelijks gratis te verwerken. Een kleine workload betekent dat u het maken of koppelen van een Azure AI-resource met meerdere services kunt overslaan.

Gegevens uploaden naar Azure Storage en een verbindingsreeks

  1. Download HotelReviews_Free.csv. Deze CSV bevat 19 stukjes feedback van klanten over één hotel (afkomstig van Kaggle.com).

  2. Zoek uw opslagaccount in Azure Portal en gebruik Opslagbrowser om een blobcontainer met de naam hotelbeoordelingen te maken.

  3. Selecteer Uploaden boven aan de pagina om het HotelReviews-Free.csv bestand te laden dat u uit de vorige stap hebt gedownload.

    Screenshot of Storage Browser with uploaded file and left nav pane

  4. Selecteer aan de linkerkant Toegangssleutels, selecteer Sleutels weergeven en kopieer de verbindingsreeks voor key1 of key2. Een volledige toegang verbindingsreeks heeft de volgende indeling:

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

Notitie

Zie Verbinding maken een beheerde identiteit gebruiken als u geen gevoelige gegevens op de verbindingsreeks wilt opgeven.

Een sleutel en URL kopiëren

In dit voorbeeld vereisen REST-aanroepen het eindpunt van de zoekservice en gebruiken ze een API-sleutel voor elke aanvraag. U kunt deze waarden ophalen uit Azure Portal.

  1. Meld u aan bij Azure Portal, navigeer naar de pagina Overzicht en kopieer de URL. Een eindpunt ziet er bijvoorbeeld uit als https://mydemo.search.windows.net.

  2. Kopieer onder Instellingen> Sleutels een beheerderssleutel. Beheer sleutels worden gebruikt om objecten toe te voegen, te wijzigen en te verwijderen. Er zijn twee uitwisselbare beheerderssleutels. Kopieer een van beide.

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

Een geldige API-sleutel brengt een vertrouwensrelatie tot stand, per aanvraag, tussen de toepassing die de aanvraag verzendt en de zoekservice die deze verwerkt.

Een index maken

Index maken (REST) maakt een zoekindex voor de zoekservice. Een zoekindex is niet gerelateerd aan een kennisarchief, maar de indexeerfunctie vereist er een. De zoekindex bevat dezelfde inhoud als het kennisarchief, dat u kunt verkennen door queryaanvragen te verzenden.

  1. Open een nieuw tekstbestand in Visual Studio Code.

  2. Stel variabelen in op het zoekeindpunt en de API-sleutel die u eerder hebt verzameld.

    @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. Sla het bestand op met een .rest bestandsextensie.

  4. Plak in het volgende voorbeeld om de indexaanvraag te maken.

    ### 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. Selecteer Verzoek verzenden. U moet een HTTP/1.1 201 Created antwoord hebben en de hoofdtekst van het antwoord moet de JSON-weergave van het indexschema bevatten.

Een gegevensbron maken

Gegevensbron maken maakt een gegevensbronverbinding in Azure AI Search.

  1. Plak in het volgende voorbeeld om de gegevensbron te maken.

    ### 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. Selecteer Verzoek verzenden.

Een vaardighedenset maken

Een vaardighedenset definieert verrijkingen (vaardigheden) en uw kennisarchief. Vaardighedenset maken maakt het object in uw zoekservice.

  1. Plak in het volgende voorbeeld om de vaardighedenset te maken.

    ### 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": []
                }
            ]
        }
    }

Belangrijkste punten:

  • De shaper-vaardigheid is belangrijk voor de definitie van het kennisarchief. Hiermee geeft u op hoe de gegevens in de tabellen van het kennisarchief stromen. De invoer is de onderdelen van het verrijkte document dat u wilt opslaan. De uitvoer is een consolidatie van de knooppunten in één structuur.

  • Projecties geven de tabellen, objecten en blobs van uw kennisarchief op. Elk projectie-item geeft de "name" kolom of het veld op die moet worden gemaakt in Azure Storage. Hiermee "source" geeft u op welk deel van de shaper-uitvoer wordt toegewezen aan dat veld of die kolom.

Een indexeerfunctie maken

Indexeerfunctie maken en voert de indexeerfunctie uit. De uitvoering van de indexeerfunctie begint met het kraken van de documenten, het extraheren van tekst en afbeeldingen en het initialiseren van de vaardighedenset. De indexeerfunctie controleert op de andere objecten die u hebt gemaakt: de gegevensbron, de index en de vaardighedenset.

  1. Plak in het volgende voorbeeld om de indexeerfunctie te maken.

    ### 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. Selecteer Aanvraag verzenden om de indexeerfunctie te maken en uit te voeren. Deze stap duurt enkele minuten.

Belangrijkste punten:

  • Het parameters/configuration-object bepaalt hoe de indexeerfunctie de gegevens opneemt. In dit geval bevindt de invoergegevens zich in één CSV-bestand met een koptekstregel en door komma's gescheiden waarden.

  • Veldtoewijzingen maken 'AzureSearch_DocumentKey' is een unieke id voor elk document dat wordt gegenereerd door de blobindexeerfunctie (op basis van het opslagpad voor metagegevens).

  • Uitvoerveldtoewijzingen geven aan hoe verrijkte velden worden toegewezen aan velden in een zoekindex. Uitvoerveldtoewijzingen worden niet gebruikt in kennisarchieven (kennisarchieven gebruiken vormen en projecties om de fysieke gegevensstructuren uit te drukken).

Status controleren

Nadat u elke aanvraag hebt verzonden, moet de zoekservice reageren met een 201-bericht.

### 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}}

Na enkele minuten kunt u een query uitvoeren op de index om de inhoud te controleren. Zelfs als u de index niet gebruikt, is deze stap een handige manier om te bevestigen dat de vaardighedenset de verwachte uitvoer heeft geproduceerd.

### 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
  }

Tabellen controleren in Azure Portal

Schakel in Azure Portal over naar uw Azure Storage-account en gebruik Opslagbrowser om de nieuwe tabellen weer te geven. U ziet zes tabellen, één voor elke projectie die is gedefinieerd in de vaardighedenset.

Elke tabel wordt gegenereerd met de id's die nodig zijn om de tabellen in query's kruislings te koppelen. Wanneer u een tabel opent, schuift u voorbij deze velden om de inhoudsvelden weer te geven die door de pijplijn zijn toegevoegd.

Screenshot of the knowledge store tables in Storage Browser

In dit scenario bestaat het kennisarchief uit verschillende tabellen met verschillende manieren om een tabel vorm te geven en te structureren. Tabellen één tot en met drie gebruiken uitvoer van een Shaper-vaardigheid om de kolommen en rijen te bepalen. Tabellen vier tot en met zes worden gemaakt op basis van inline-vormgevingsinstructies, die zijn ingesloten in de projectie zelf. U kunt beide benaderingen gebruiken om hetzelfde resultaat te bereiken.

Table Beschrijving
hotelReviews1Document Bevat velden die worden overgedragen vanuit het CSV-bestand, zoals reviews_date en reviews_text.
hotelReviews2Pages Bevat verrijkte velden die zijn gemaakt door de vaardighedenset, zoals gevoelsscore en vertaalde tekst.
hotelReviews3KeyPhrases Bevat een lange lijst met alleen de sleuteltermen.
hotelReviews4InlineProjectionDocument U kunt ook de eerste tabel gebruiken door inline-vormgeving te gebruiken in plaats van de Shaper-vaardigheid om gegevens voor de projectie vorm te geven.
hotelReviews5InlineProjectionPages Alternatief voor de tweede tabel, met behulp van inline-vormgeving.
hotelreviews6InlineProjectionKeyPhrases Alternatief voor de derde tabel, met behulp van inline-vormgeving.

Opschonen

Wanneer u in uw eigen abonnement werkt, is het een goed idee om aan het einde van een project te bepalen of u de gemaakte resources nog nodig hebt. Resources die actief blijven, kunnen u geld kosten. U kunt resources afzonderlijk verwijderen, maar u kunt ook de resourcegroep verwijderen als u de volledige resourceset wilt verwijderen.

U kunt resources vinden en beheren in de portal via de koppeling Alle resources of Resourcegroepen in het navigatiedeelvenster aan de linkerkant.

Volgende stappen

Nu u uw gegevens hebt verrijkt met behulp van Azure AI-services en de resultaten hebt geprojecteerd naar een kennisarchief, kunt u Storage Explorer of andere apps gebruiken om uw verrijkte gegevensset te verkennen.

Aan de slag met Storage Explorer