Vytvoření úložiště znalostí pomocí REST

Článek
03/11/2024

Ve službě Azure AI Search je úložiště znalostí úložištěm obsahu generovaného AI, který se používá pro scénáře bez vyhledávání. Úložiště znalostí vytvoříte pomocí indexeru a sady dovedností a zadáte Azure Storage pro uložení výstupu. Po naplnění úložiště znalostí můžete obsah prozkoumat pomocí nástrojů, jako jsou Průzkumník služby Storage nebo Power BI.

V tomto článku použijete rozhraní REST API k příjmu, obohacení a prozkoumání sady recenzí zákazníků hotelů ve znalostním úložišti. Úložiště znalostí obsahuje původní textový obsah načítaný ze zdroje a navíc obsah vygenerovaný AI, který zahrnuje skóre mínění, extrakci klíčových frází, rozpoznávání jazyka a překlad textu neanglických komentářů zákazníků.

Aby byla počáteční sada dat dostupná, recenze hotelů se nejprve naimportují do Azure Blob Storage. Po zpracování se výsledky uloží jako úložiště znalostí ve službě Azure Table Storage.

Tip

Tento článek používá REST k podrobným vysvětlení jednotlivých kroků. Pokud chcete jen spustit příkazy, stáhněte si soubor REST. Alternativně můžete také vytvořit úložiště znalostí na webu Azure Portal.

Požadavky

Visual Studio Code s klientem REST Pokud potřebujete pomoc se zahájením práce, přečtěte si článek Rychlý start: Vyhledávání textu pomocí REST.
Azure AI Search. Vytvořte službu nebo vyhledejte existující službu. Pro toto cvičení můžete použít bezplatnou službu.
Azure Storage Vytvořte účet nebo vyhledejte existující účet. Typ účtu musí být StorageV2 (pro obecné účely V2).

Sada dovedností v těchto příkladech využívá služby Azure AI k rozšiřování. Vzhledem k tomu, že úloha je tak malá, služba Azure AI se na pozadí klepne, aby poskytovala bezplatné zpracování až pro 20 transakcí denně. Malá úloha znamená, že můžete přeskočit vytvoření nebo připojení prostředku Azure AI s více službami.

Nahrání dat do Azure Storage a získání připojovací řetězec

Stáhněte si HotelReviews_Free.csv. Tento csv obsahuje 19 částí názorů zákazníků na jeden hotel (pochází z Kaggle.com).
Na webu Azure Portal najděte svůj účet úložiště a pomocí Prohlížeče úložiště vytvořte kontejner objektů blob s názvem hotel-reviews.
Výběrem možnosti Nahrát v horní části stránky načtěte soubor HotelReviews-Free.csv , který jste stáhli z předchozího kroku.
Na levé straně vyberte Přístupové klíče, vyberte Zobrazit klíče a pak zkopírujte připojovací řetězec pro klíč1 nebo klíč2. Úplný přístupový připojovací řetězec má následující formát:

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

Poznámka:

Pokud nechcete na připojovací řetězec poskytovat citlivá data, podívejte se Připojení použití spravované identity.

Zkopírování klíče a adresy URL

V tomto příkladu volání REST vyžadují koncový bod vyhledávací služby a pro každý požadavek používají klíč rozhraní API. Tyto hodnoty můžete získat z webu Azure Portal.

Přihlaste se k webu Azure Portal, přejděte na stránku Přehled a zkopírujte adresu URL. Příkladem koncového bodu může být https://mydemo.search.windows.net.
V části Nastavení> Klíče zkopírujte klíč správce. Správa klíče slouží k přidávání, úpravám a odstraňování objektů. Existují dva zaměnitelné klíče správce. Zkopírujte jeden z nich.

Platný klíč rozhraní API vytváří na základě požadavku vztah důvěryhodnosti mezi aplikací, která požadavek odesílá, a vyhledávací službou, která ji zpracovává.

Vytvoření indexu

Vytvoření indexu (REST) vytvoří vyhledávací index ve vyhledávací službě. Index vyhledávání nesouvisí s úložištěm znalostí, ale indexer ho vyžaduje. Index vyhledávání obsahuje stejný obsah jako úložiště znalostí, které můžete prozkoumat odesláním požadavků na dotazy.

Otevřete nový textový soubor v editoru Visual Studio Code.

Nastavte proměnné na koncový bod vyhledávání a klíč rozhraní API, který jste shromáždili dříve.

@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)

Uložte soubor s příponou .rest souboru.

Vložte následující příklad a vytvořte požadavek indexu.

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

Vyberte Odeslat žádost. Měli byste mít HTTP/1.1 201 Created odpověď a text odpovědi by měl obsahovat reprezentaci JSON schématu indexu.

Vytvoření zdroje dat

Vytvoření zdroje dat vytvoří připojení ke zdroji dat ve službě Azure AI Search.

Vložte následující příklad a vytvořte zdroj dat.

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

Vyberte Odeslat žádost.

Vytvoření sady dovedností

Sada dovedností definuje rozšiřování (dovednosti) a vaše úložiště znalostí. Vytvořit sadu dovedností vytvoří objekt ve vyhledávací službě.

Vložte následující příklad a vytvořte sadu dovedností.

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

Klíčové body:

Dovednost Shaper je důležitá pro definici úložiště znalostí. Určuje, jak data proudí do tabulek úložiště znalostí. Vstupy jsou části rozšířeného dokumentu, který chcete uložit. Výstup je sloučení uzlů do jedné struktury.
Projekce určují tabulky, objekty a objekty blob vašeho úložiště znalostí. Každá položka projekce určuje "name" sloupec nebo pole, které se má vytvořit ve službě Azure Storage. Určuje "source" , která část výstupu shaperu je přiřazena k danému poli nebo sloupci.

Vytvoření indexeru

Vytvoření indexeru vytvoří a spustí indexer. Spuštění indexeru začíná tím, že prolomí dokumenty, extrahuje text a obrázky a inicializuje sadu dovedností. Indexer vyhledá další objekty, které jste vytvořili: zdroj dat, index a sadu dovedností.

Vložte následující příklad a vytvořte indexer.

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

Výběrem možnosti Odeslat požadavek vytvořte a spusťte indexer. Dokončení tohoto kroku trvá několik minut.

Klíčové body:

Objekt parameters/configuration řídí, jak indexer ingestuje data. V tomto případě jsou vstupní data v jednom souboru CSV, který obsahuje řádek záhlaví a hodnoty oddělené čárkami.
Mapování polí vytváří "AzureSearch_DocumentKey" je jedinečný identifikátor pro každý dokument vygenerovaný indexerem objektů blob (na základě cesty k úložišti metadat).
Mapování výstupních polí určují, jak se rozšířená pole mapují na pole v indexu vyhledávání. Mapování výstupních polí se nepoužívá v úložištích znalostí (úložiště znalostí používají k vyjádření fyzických datových struktur obrazce a projekce).

Zkontrolovat stav

Po odeslání každé žádosti by vyhledávací služba měla odpovědět zprávou o úspěchu 201.

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

Po několika minutách můžete dotazovat index a zkontrolovat obsah. I když index nepoužíváte, představuje tento krok pohodlný způsob, jak ověřit, že sada dovedností vytvořila očekávaný výstup.

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

Kontrola tabulek na webu Azure Portal

Na webu Azure Portal přepněte na svůj účet Azure Storage a pomocí Prohlížeče úložiště zobrazte nové tabulky. Měli byste vidět šest tabulek, jednu pro každou projekci definovanou v sadě dovedností.

Každá tabulka se vygeneruje s ID potřebnými pro křížové propojení tabulek v dotazech. Když otevřete tabulku, posuňte se za tato pole a zobrazte pole obsahu přidaná kanálem.

Screenshot of the knowledge store tables in Storage Browser

V tomto názorném postupu se úložiště znalostí skládá z různých tabulek, které znázorňují různé způsoby strukturování a strukturování tabulky. Tabulky 1 až tři používají výstup z dovednosti Shaper k určení sloupců a řádků. Tabulky čtyři až šest jsou vytvořeny z inline formování instrukce vložené do samotné projekce. K dosažení stejného výsledku můžete použít některý z přístupů.

Table	Popis
`hotelReviews1Document`	Obsahuje pole přenesená ze souboru CSV, jako jsou reviews_date a reviews_text.
`hotelReviews2Pages`	Obsahuje rozšířená pole vytvořená sadou dovedností, například skóre mínění a přeložený text.
`hotelReviews3KeyPhrases`	Obsahuje dlouhý seznam jenom klíčových frází.
`hotelReviews4InlineProjectionDocument`	Alternativou k první tabulce je použití vloženého tvarování místo dovednosti Shaper k tvarování dat pro projekci.
`hotelReviews5InlineProjectionPages`	Alternativou ke druhé tabulce je použití vloženého tvarování.
`hotelreviews6InlineProjectionKeyPhrases`	Alternativou ke třetí tabulce je použití vloženého tvarování.

Vyčištění

Pokud pracujete s vlastním předplatným, je vhodné vždy na konci projektu zkontrolovat, jestli budete vytvořené prostředky ještě potřebovat. Prostředky, které necháte spuštěné, vás stojí peníze. Prostředky můžete odstraňovat jednotlivě nebo můžete odstranit skupinu prostředků, a odstranit tak celou sadu prostředků najednou.

Prostředky můžete najít a spravovat na portálu pomocí odkazu Všechny prostředky nebo skupiny prostředků v levém navigačním podokně.

Další kroky

Teď, když jste data obohatili pomocí služeb Azure AI a promítli výsledky do úložiště znalostí, můžete k prozkoumání rozšířené datové sady použít Průzkumník služby Storage nebo jiné aplikace.

Začínáme s Průzkumníkem služby Storage