Tudástár létrehozása a REST használatával

  • Cikk

Az Azure AI Searchben a tudástár az AI által létrehozott tartalmak adattára, amelyet nem keresési forgatókönyvekhez használnak. A tudástárat indexelő és képességkészlet használatával hozhatja létre, és megadhatja az Azure Storage-t a kimenet tárolásához. A tudástár feltöltése után használja az olyan eszközöket, mint a Storage Explorer vagy a Power BI , hogy megismerje a tartalmat.

Ebben a cikkben a REST API-val betöltheti, gazdagíthatja és felfedezheti a szállodai tartózkodásokról szóló ügyfélértékelések egy készletét egy tudástárban. A tudástár tartalmazza a forrásból lekért eredeti szöveges tartalmat, valamint az AI által létrehozott tartalmakat, amelyek tartalmazzák a hangulatpontszámot, a kulcskifejezések kinyerását, a nyelvfelismerést és a nem angol nyelvű ügyfelek megjegyzéseinek szövegfordítását.

A kezdeti adatkészlet elérhetővé tétele érdekében a rendszer először importálja a szállodai felülvizsgálatokat az Azure Blob Storage-ba. A feldolgozás után a rendszer az eredményeket tudástárként menti az Azure Table Storage-ban.

Tipp.

Ez a cikk a REST függvényt használja az egyes lépések részletes magyarázatához. Töltse le a REST-fájlt , ha csak futtatni szeretné a parancsokat. Másik lehetőségként létrehozhat egy tudástárat is az Azure Portalon.

Előfeltételek

A példában szereplő készségkészlet az Azure AI-szolgáltatásokat használja a bővítéshez. Mivel a számítási feladat annyira kicsi, hogy az Azure AI-szolgáltatások a színfalak mögött leképezve naponta legfeljebb 20 tranzakció ingyenes feldolgozását teszik lehetővé. A kis számítási feladatok azt jelentik, hogy kihagyhatja egy többszolgáltatásos Azure AI-erőforrás létrehozását vagy csatolását.

Adatok feltöltése az Azure Storage-ba, és kapcsolati sztring

  1. Töltse le HotelReviews_Free.csv. Ez a CSV 19 darab ügyfél-visszajelzést tartalmaz egyetlen szállodáról (Kaggle.com származik).

  2. Az Azure Portalon keresse meg a tárfiókot, és a Storage Browser használatával hozzon létre egy hotel-reviews nevű blobtárolót.

  3. Válassza a Lap tetején található Feltöltés lehetőséget az előző lépésből letöltött HotelReviews-Free.csv fájl betöltéséhez.

    Screenshot of Storage Browser with uploaded file and left nav pane

  4. A bal oldalon válassza a Hozzáférési kulcsok lehetőséget, válassza a Kulcsok megjelenítése lehetőséget, majd másolja a kapcsolati sztring az 1. vagy a 2. kulcshoz. A teljes hozzáférésű kapcsolati sztring formátuma a következő:

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

Feljegyzés

Ha nem szeretne bizalmas adatokat megadni a kapcsolati sztring, tekintse meg Csatlakozás felügyelt identitás használatával.

Kulcs és URL másolása

Ebben a példában a REST-hívásokhoz a keresési szolgáltatás végpontja szükséges, és minden kéréshez egy API-kulcsot kell használni. Ezeket az értékeket az Azure Portalon szerezheti be.

  1. Jelentkezzen be az Azure Portalra, lépjen az Áttekintés lapra, és másolja ki az URL-címet. A végpontok például a következőképpen nézhetnek ki: https://mydemo.search.windows.net.

  2. A Gépház> Keys területen másolja a rendszergazdai kulcsot. Rendszergazda kulcsok objektumok hozzáadására, módosítására és törlésére szolgálnak. Két felcserélhető rendszergazdai kulcs van. Másolja valamelyiket.

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

Az érvényes API-kulcs kérésenként megbízhatóságot hoz létre a kérelmet küldő alkalmazás és az azt kezelő keresési szolgáltatás között.

Index létrehozása

Az Index létrehozása (REST) létrehoz egy keresési indexet a keresési szolgáltatásban. A keresési index nem kapcsolódik a tudástárhoz, de az indexelőnek szüksége van rá. A keresési index ugyanazokat a tartalmakat tartalmazza, mint a tudástár, amelyet lekérdezési kérések küldésével vizsgálhat meg.

  1. Nyisson meg egy új szövegfájlt a Visual Studio Code-ban.

  2. Állítsa be a változókat a keresési végpontra és a korábban gyűjtött API-kulcsra.

    @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. Mentse a fájlt fájlkiterjesztéssel .rest .

  4. Illessze be az alábbi példába az indexkérelmet.

    ### 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. Válassza a Kérés elküldése elemet. Válasznak kell lennie HTTP/1.1 201 Created , és a válasz törzsének tartalmaznia kell az indexséma JSON-ábrázolását.

Adatforrás létrehozása

Adatforrás létrehozása adatforrás-kapcsolatot hoz létre az Azure AI Search szolgáltatásban.

  1. Illessze be az alábbi példába az adatforrás létrehozásához.

    ### 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. Válassza a Kérés elküldése elemet.

Képességcsoport létrehozása

A képességkészletek a bővítéseket (készségeket) és a tudástárat határozzák meg. A Skillset létrehozása létrehozza az objektumot a keresési szolgáltatásban.

  1. Illessze be a következő példába a készségkészlet létrehozásához.

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

Főbb pontok:

  • A Shaper-képesség fontos a tudástár definíciójában. Meghatározza, hogy az adatok hogyan áramoljanak a tudástár tábláiba. A bemenetek a bővített dokumentum tárolni kívánt részei. A kimenet a csomópontok egyetlen struktúrába való összesítése.

  • A leképezések a tudástár tábláit, objektumait és blobjait határozzák meg. Minden vetítési elem megadja az "name" Azure Storage-ban létrehozandó oszlopot vagy mezőt. Ez "source" adja meg, hogy az alakzat kimenetének mely része legyen hozzárendelve ehhez a mezőhöz vagy oszlophoz.

Indexelő létrehozása

Az Indexelő létrehozása létrehozza és futtatja az indexelőt. Az indexelő végrehajtása a dokumentumok feltörésével, a szöveg és képek kinyerésével, valamint a képességkészlet inicializálásával kezdődik. Az indexelő ellenőrzi a többi létrehozott objektumot: az adatforrást, az indexet és a képességkészletet.

  1. Illessze be az alábbi példába az indexelő létrehozásához.

    ### 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. Válassza a Kérés küldése lehetőséget az indexelő létrehozásához és futtatásához. Ez a lépés több percet vesz igénybe.

Főbb pontok:

  • Az parameters/configuration objektum szabályozza, hogy az indexelő hogyan betölti az adatokat. Ebben az esetben a bemeneti adatok egyetlen CSV-fájlban vannak, amely fejlécsort és vesszővel elválasztott értékeket tartalmaz.

  • A mezőleképezések létrehoznak egy "AzureSearch_DocumentKey" egy egyedi azonosítót minden olyan dokumentumhoz, amelyet a blobindexelő hoz létre (a metaadattár elérési útja alapján).

  • A kimeneti mezőleképezések megadják, hogy a bővített mezők hogyan vannak leképezve a keresési index mezőire. A kimeneti mezőleképezések nem használhatók a tudástárakban (a tudástárak alakzatokkal és kivetítésekkel fejezik ki a fizikai adatstruktúrákat).

Állapot ellenőrzése

Az egyes kérések elküldése után a keresési szolgáltatásnak egy 201-ben sikeres üzenettel kell válaszolnia.

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

Néhány perc elteltével lekérdezheti az indexet a tartalom vizsgálatához. Még akkor is, ha nem használja az indexet, ez a lépés kényelmes módszer annak ellenőrzésére, hogy a képességkészlet a várt kimenetet hozta-e létre.

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

Táblák ellenőrzése az Azure Portalon

Az Azure Portalon váltson az Azure Storage-fiókra, és a Storage Browser használatával tekintse meg az új táblákat. Hat táblát kell látnia, egyet a készségkészletben definiált minden egyes vetítéshez.

Minden tábla a lekérdezésekben lévő táblák keresztkapcsolásához szükséges azonosítókkal jön létre. Amikor megnyit egy táblát, görgessen ezeken a mezőkön a folyamat által hozzáadott tartalommezők megtekintéséhez.

Screenshot of the knowledge store tables in Storage Browser

Ebben az útmutatóban a tudástár különböző táblákból áll, amelyek a táblák formázásának és strukturálásának különböző módjait mutatják be. Az 1–3. táblázat egy Shaper-képesség kimenetét használja az oszlopok és sorok meghatározásához. A négytől a hatig tartó táblázat beágyazott formázási utasításokból jön létre, és magában a vetítésben van beágyazva. Ugyanazt az eredményt bármelyik megközelítéssel érheti el.

Tábla Leírás
hotelReviews1Document A CSV-ből továbbított mezőket tartalmazza, például reviews_date és reviews_text.
hotelReviews2Pages A képességkészlet által létrehozott bővített mezőket tartalmaz, például a hangulatpontszámot és a lefordított szöveget.
hotelReviews3KeyPhrases Csak a kulcskifejezések hosszú listáját tartalmazza.
hotelReviews4InlineProjectionDocument Az első táblázat alternatívája, ha a Shaper-képesség helyett beágyazott formázást használ a vetítés adatainak alakításához.
hotelReviews5InlineProjectionPages A második táblázat alternatívája, beágyazott formázással.
hotelreviews6InlineProjectionKeyPhrases A harmadik táblázat alternatívája beágyazott formázással.

A fölöslegessé vált elemek eltávolítása

Ha a saját előfizetésében dolgozik, érdemes az egyes projektek végén eldöntenie, hogy szüksége lesz-e még a létrehozott erőforrásokra. A továbbra is futó erőforrások költségekkel járhatnak. Az erőforrásokat törölheti egyesével, vagy az erőforráscsoport törlésével eltávolíthatja a benne lévő összes erőforrást is.

A portálon a bal oldali navigációs panel Minden erőforrás vagy Erőforráscsoport hivatkozásával kereshet és kezelhet erőforrásokat.

Következő lépések

Most, hogy az Azure AI-szolgáltatások használatával bővítette az adatokat, és az eredményeket egy tudástárba kivetítette, a Storage Explorer vagy más alkalmazások segítségével felfedezheti a bővített adatkészletet.

A Storage Explorer használatának első lépései