Skapa ett kunskapslager med hjälp av REST

  • Artikel

I Azure AI Search är ett kunskapslager en lagringsplats med AI-genererat innehåll som används för scenarier som inte är sökscenarier. Du skapar kunskapsarkivet med hjälp av en indexerare och kompetensuppsättning och anger Azure Storage för att lagra utdata. När kunskapsarkivet har fyllts i använder du verktyg som Storage Explorer eller Power BI för att utforska innehållet.

I den här artikeln använder du REST API för att mata in, berika och utforska en uppsättning kundrecensioner av hotellvistelser i ett kunskapslager. Kunskapsarkivet innehåller originaltextinnehåll som hämtats från källan, plus AI-genererat innehåll som innehåller attitydpoäng, extrahering av nyckelfraser, språkidentifiering och textöversättning av icke-engelska kundkommenter.

För att göra den första datamängden tillgänglig importeras hotellgranskningarna först till Azure Blob Storage. Efter bearbetningen sparas resultatet som ett kunskapslager i Azure Table Storage.

Dricks

Den här artikeln använder REST för detaljerade förklaringar av varje steg. Ladda ned REST-filen om du bara vill köra kommandona. Du kan också skapa ett kunskapslager i Azure Portal.

Förutsättningar

Kompetensuppsättningen i de här exemplen använder Azure AI Services för berikanden. Eftersom arbetsbelastningen är så liten används Azure AI-tjänster i bakgrunden för att tillhandahålla kostnadsfri bearbetning för upp till 20 transaktioner dagligen. En liten arbetsbelastning innebär att du kan hoppa över att skapa eller ansluta en Azure AI-resurs med flera tjänster.

Ladda upp data till Azure Storage och få en anslutningssträng

  1. Ladda ned HotelReviews_Free.csv. Denna CSV innehåller 19 kundfeedback om ett enda hotell (kommer från Kaggle.com).

  2. I Azure Portal hittar du ditt lagringskonto och använder Storage Browser för att skapa en blobcontainer med namnet hotel-reviews.

  3. Välj Ladda upp överst på sidan för att läsa in den HotelReviews-Free.csv fil som du laddade ned från föregående steg.

    Skärmbild av Storage Browser med uppladdad fil och det vänstra navigeringsfönstret

  4. Till vänster väljer du Åtkomstnycklar, visar nycklar och kopierar sedan anslutningssträng för antingen key1 eller key2. En fullständig åtkomst anslutningssträng har följande format:

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

Kommentar

Se Ansluta med en hanterad identitet om du inte vill ange känsliga data på anslutningssträng.

Kopiera en nyckel och EN URL

I det här exemplet kräver REST-anrop söktjänstens slutpunkt och använder en API-nyckel för varje begäran. Du kan hämta dessa värden från Azure Portal.

  1. Logga in på Azure Portal, gå till sidan Översikt och kopiera URL:en. Här följer ett exempel på hur en slutpunkt kan se ut: https://mydemo.search.windows.net.

  2. Under Inställningar>Nycklar kopierar du en administratörsnyckel. Administratörsnycklar används för att lägga till, ändra och ta bort objekt. Det finns två utbytbara administratörsnycklar. Kopiera någon av dem.

    Skärmbild av URL:en och API-nycklarna i Azure Portal.

En giltig API-nyckel upprättar förtroende per begäran mellan programmet som skickar begäran och söktjänsten som hanterar den.

Skapa ett index

Skapa index (REST) skapar ett sökindex i söktjänsten. Ett sökindex är inte relaterat till ett kunskapslager, men indexeraren kräver ett. Sökindexet innehåller samma innehåll som kunskapsarkivet, som du kan utforska genom att skicka frågebegäranden.

  1. Öppna en ny textfil i Visual Studio Code.

  2. Ange variabler till sökslutpunkten och API-nyckeln som du samlade in tidigare.

    @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. Spara filen med ett .rest filnamnstillägg.

  4. Klistra in i följande exempel för att skapa indexbegäran.

    ### Create a new index
POST {{baseUrl}}/indexes?api-version=2024-07-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. Välj Skicka begäran. Du bör ha ett HTTP/1.1 201 Created svar och svarstexten bör innehålla JSON-representationen av indexschemat.

Skapa en datakälla

Skapa datakälla skapar en datakällaanslutning i Azure AI Search.

  1. Klistra in följande exempel för att skapa datakällan.

    ### Create a data source
POST {{baseUrl}}/datasources?api-version=2024-07-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. Välj Skicka begäran.

Skapa en kunskapsuppsättning

En kompetensuppsättning definierar berikanden (färdigheter) och ditt kunskapslager. Skapa Kunskapsuppsättning skapar objektet i söktjänsten.

  1. Klistra in i följande exempel för att skapa kunskapsuppsättningen.

    ### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2024-07-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": []
                }
            ]
        }
    }

Viktiga punkter:

  • Formningsfärdigheten är viktig för definitionen av kunskapslager. Den anger hur data flödar in i tabellerna i kunskapsarkivet. Indata är de delar av det berikade dokumentet som du vill lagra. Utdata är en konsolidering av noderna i en enda struktur.

  • Projektioner anger tabeller, objekt och blobar i ditt kunskapslager. Varje projektionsobjekt anger vilken kolumn eller fält som "name" ska skapas i Azure Storage. Anger "source" vilken del av shaperutdata som tilldelas till fältet eller kolumnen.

Skapa en indexerare

Skapa Indexer skapar och kör indexeraren. Indexerarens körning börjar med att knäcka dokumenten, extrahera text och bilder och initiera kompetensuppsättningen. Indexeraren söker efter de andra objekten som du skapade: datakällan, indexet och kompetensuppsättningen.

  1. Klistra in i följande exempel för att skapa indexeraren.

    ### Create indexer
POST {{baseUrl}}/indexers?api-version=2024-07-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. Välj Skicka begäran för att skapa och köra indexeraren. Det här steget tar flera minuter att slutföra.

Viktiga punkter:

  • Objektet parameters/configuration styr hur indexeraren matar in data. I det här fallet finns indata i en enda CSV-fil som har en rubrikrad och kommaavgränsade värden.

  • Fältmappningar skapar "AzureSearch_DocumentKey" är en unik identifierare för varje dokument som genereras av blobindexeraren (baserat på metadatalagringssökväg).

  • Utdatafältmappningar anger hur berikade fält mappas till fält i ett sökindex. Utdatafältmappningar används inte i kunskapslager (kunskapslager använder former och projektioner för att uttrycka de fysiska datastrukturerna).

Kontrollera status

När du har skickat varje begäran bör söktjänsten svara med ett meddelande om att 201 lyckades.

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

Efter flera minuter kan du fråga indexet för att inspektera innehållet. Även om du inte använder indexet är det här steget ett praktiskt sätt att bekräfta att kunskapsuppsättningen skapade förväntade utdata.

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

Kontrollera tabeller i Azure Portal

I Azure Portal växlar du till ditt Azure Storage-konto och använder Storage Browser för att visa de nya tabellerna. Du bör se sex tabeller, en för varje projektion som definierats i kompetensuppsättningen.

Varje tabell genereras med de ID:er som krävs för korslänkning av tabellerna i frågor. När du öppnar en tabell bläddrar du förbi de här fälten för att visa de innehållsfält som läggs till av pipelinen.

Skärmbild av kunskapslagertabellerna i Storage Browser

I den här genomgången består kunskapsarkivet av olika tabeller som visar olika sätt att forma och strukturera en tabell. Tabeller en till tre använder utdata från en Shaper-färdighet för att fastställa kolumner och rader. Tabeller fyra till sex skapas från infogade formningsinstruktioner, inbäddade i själva projektionen. Du kan använda endera metoden för att uppnå samma resultat.

Register beskrivning
hotelReviews1Document Innehåller fält som överförs från CSV:en, till exempel reviews_date och reviews_text.
hotelReviews2Pages Innehåller berikade fält som skapats av kompetensuppsättningen, till exempel attitydpoäng och översatt text.
hotelReviews3KeyPhrases Innehåller en lång lista över bara nyckelfraserna.
hotelReviews4InlineProjectionDocument Alternativ till den första tabellen, med infogad formning i stället för Shaper-färdigheten för att forma data för projektionen.
hotelReviews5InlineProjectionPages Alternativ till den andra tabellen, med hjälp av infogad formning.
hotelreviews6InlineProjectionKeyPhrases Alternativ till den tredje tabellen med infogad formning.

Rensa

När du arbetar i din egen prenumeration kan det dock vara klokt att i slutet av ett projekt kontrollera om du fortfarande behöver de resurser som du skapade. Resurser som fortsätter att köras kostar pengar. Du kan ta bort enstaka resurser eller hela resursgruppen om du vill ta bort alla resurser.

Du kan hitta och hantera resurser i portalen med hjälp av länken Alla resurser eller Resursgrupper i det vänstra navigeringsfönstret.

Nästa steg

Nu när du har utökat dina data med hjälp av Azure AI-tjänster och projicerat resultaten till ett kunskapslager kan du använda Storage Explorer eller andra appar för att utforska din berikade datauppsättning.

Kom igång med Storage Explorer