Tworzenie magazynu wiedzy przy użyciu interfejsu REST

Artykuł
09/01/2024

W usłudze Azure AI Search magazyn wiedzy to repozytorium zawartości generowanej przez sztuczną inteligencję, która jest używana w scenariuszach niezwiązanych z wyszukiwaniem. Magazyn wiedzy jest tworzony przy użyciu indeksatora i zestawu umiejętności oraz określasz usługę Azure Storage do przechowywania danych wyjściowych. Po wypełnieniu magazynu wiedzy użyj narzędzi, takich jak Eksplorator usługi Storage lub Power BI, aby eksplorować zawartość.

W tym artykule używasz interfejsu API REST do pozyskiwania, wzbogacania i eksplorowania zestawu recenzji hotelowych pobytów w magazynie wiedzy. Magazyn wiedzy zawiera oryginalną zawartość tekstową pobraną ze źródła oraz zawartość wygenerowaną przez sztuczną inteligencję, która zawiera wynik tonacji, wyodrębnianie kluczowych fraz, wykrywanie języka i tłumaczenie tekstu komentarzy klientów innych niż angielski.

Aby udostępnić początkowy zestaw danych, opinie hotelowe są najpierw importowane do usługi Azure Blob Storage. Po przetworzeniu wyniki są zapisywane jako magazyn wiedzy w usłudze Azure Table Storage.

Napiwek

W tym artykule użyto interfejsu REST w celu uzyskania szczegółowych wyjaśnień dotyczących każdego kroku. Pobierz plik REST, jeśli chcesz po prostu uruchomić polecenia. Alternatywnie możesz również utworzyć magazyn wiedzy w witrynie Azure Portal.

Wymagania wstępne

Program Visual Studio Code z klientem REST. Jeśli potrzebujesz pomocy dotyczącej rozpoczynania pracy, zobacz Szybki start: wyszukiwanie tekstu przy użyciu interfejsu REST.
Azure AI Search. Utwórz usługę lub znajdź istniejącą. W tym ćwiczeniu możesz użyć bezpłatnej usługi.
Azure Storage. Utwórz konto lub znajdź istniejące. Typ konta musi mieć wartość StorageV2 (ogólnego przeznaczenia w wersji 2).

Zestaw umiejętności w tych przykładach używa usług Azure AI Services do wzbogacania. Ponieważ obciążenie jest tak małe, usługi azure AI są zakulisowe, aby zapewnić bezpłatne przetwarzanie do 20 transakcji dziennie. Małe obciążenie oznacza, że można pominąć tworzenie lub dołączanie zasobu obejmującego wiele usług w usłudze Azure AI.

Przekazywanie danych do usługi Azure Storage i uzyskiwanie parametry połączenia

Pobierz HotelReviews_Free.csv. Ten plik CSV zawiera 19 elementów opinii klientów dotyczących pojedynczego hotelu (pochodzi z Kaggle.com).
W witrynie Azure Portal znajdź konto magazynu i użyj przeglądarki usługi Storage, aby utworzyć kontener obiektów blob o nazwie hotel-reviews.
Wybierz pozycję Przekaż w górnej części strony, aby załadować plik HotelReviews-Free.csv pobrany z poprzedniego kroku.
Po lewej stronie wybierz pozycję Klucze dostępu, wybierz pozycję Pokaż klucze, a następnie skopiuj parametry połączenia dla klucza key1 lub key2. Pełny parametry połączenia dostępu ma następujący format:

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

Uwaga

Jeśli nie chcesz udostępniać poufnych danych na parametry połączenia, zobacz Nawiązywanie połączenia przy użyciu tożsamości zarządzanej.

Kopiowanie klucza i adresu URL

W tym przykładzie wywołania REST wymagają punktu końcowego usługi wyszukiwania i używają klucza interfejsu API dla każdego żądania. Te wartości można uzyskać w witrynie Azure Portal.

Zaloguj się do witryny Azure Portal, przejdź do strony Przegląd i skopiuj adres URL. Przykładowy punkt końcowy może wyglądać podobnie jak https://mydemo.search.windows.net.
W obszarze Klucze ustawień>skopiuj klucz administratora. Klucze administracyjne służą do dodawania, modyfikowania i usuwania obiektów. Istnieją dwa zamienne klucze administratora. Skopiuj jedną z nich.

Prawidłowy klucz interfejsu API ustanawia relację zaufania dla poszczególnych żądań między aplikacją wysyłającą żądanie a usługą wyszukiwania, która go obsługuje.

Tworzenie indeksu

Tworzenie indeksu (REST) powoduje utworzenie indeksu wyszukiwania w usłudze wyszukiwania. Indeks wyszukiwania nie jest związany z magazynem wiedzy, ale indeksator wymaga takiego indeksatora. Indeks wyszukiwania zawiera tę samą zawartość co magazyn wiedzy, którą można eksplorować, wysyłając żądania zapytań.

Otwórz nowy plik tekstowy w programie Visual Studio Code.

Ustaw zmienne na punkt końcowy wyszukiwania i zebrany wcześniej klucz interfejsu API.

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

Zapisz plik z .rest rozszerzeniem pliku.

Wklej poniższy przykład, aby utworzyć żądanie indeksu.

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

Wybierz pozycję Wyślij wniosek. Powinna zostać wyświetlona HTTP/1.1 201 Created odpowiedź, a treść odpowiedzi powinna zawierać reprezentację JSON schematu indeksu.

Utwórz źródło danych

Tworzenie źródła danych tworzy połączenie ze źródłem danych w usłudze Azure AI Search.

Wklej poniższy przykład, aby utworzyć źródło danych.

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

Wybierz pozycję Wyślij wniosek.

Tworzenie zestawu umiejętności

Zestaw umiejętności definiuje wzbogacania (umiejętności) i twój magazyn wiedzy. Utwórz zestaw umiejętności, aby utworzyć obiekt w usłudze wyszukiwania.

Wklej poniższy przykład, aby utworzyć zestaw umiejętności.

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

Kluczowe punkty:

Umiejętność kształtowania jest ważna dla definicji magazynu wiedzy. Określa sposób przepływu danych do tabel magazynu wiedzy. Dane wejściowe to części wzbogaconego dokumentu, które chcesz przechowywać. Dane wyjściowe to konsolidacja węzłów w jedną strukturę.
Projekcje określają tabele, obiekty i obiekty blob magazynu wiedzy. Każdy element projekcji określa "name" kolumnę lub pole do utworzenia w usłudze Azure Storage. Określa "source" , która część danych wyjściowych kształtu jest przypisana do tego pola lub kolumny.

Tworzenie indeksatora

Tworzenie indeksatora powoduje utworzenie i uruchomienie indeksatora. Wykonywanie indeksatora rozpoczyna się od złamania dokumentów, wyodrębniania tekstu i obrazów oraz inicjowania zestawu umiejętności. Indeksator sprawdza inne utworzone obiekty: źródło danych, indeks i zestaw umiejętności.

Wklej poniższy przykład, aby utworzyć indeksator.

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

Wybierz pozycję Wyślij żądanie , aby utworzyć i uruchomić indeksator. Wykonanie tego kroku zajmuje kilka minut.

Kluczowe punkty:

Obiekt parameters/configuration steruje sposobem pozyskiwania danych przez indeksator. W takim przypadku dane wejściowe są w jednym pliku CSV, który zawiera wiersz nagłówka i wartości rozdzielane przecinkami.
Mapowania pól tworzą "AzureSearch_DocumentKey" to unikatowy identyfikator każdego dokumentu generowanego przez indeksator obiektów blob (na podstawie ścieżki magazynu metadanych).
Mapowania pól wyjściowych określają sposób mapowania wzbogaconych pól na pola w indeksie wyszukiwania. Mapowania pól wyjściowych nie są używane w magazynach wiedzy (magazyny wiedzy używają kształtów i projekcji do wyrażania fizycznych struktur danych).

Sprawdź stan

Po wysłaniu każdego żądania usługa wyszukiwania powinna odpowiedzieć z komunikatem o powodzeniu 201.

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

Po kilku minutach możesz wykonać zapytanie dotyczące indeksu, aby sprawdzić zawartość. Nawet jeśli nie używasz indeksu, ten krok jest wygodnym sposobem potwierdzenia, że zestaw umiejętności wygenerował oczekiwane dane wyjściowe.

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

Sprawdzanie tabel w witrynie Azure Portal

W witrynie Azure Portal przejdź do konta usługi Azure Storage i użyj przeglądarki usługi Storage, aby wyświetlić nowe tabele. Powinny zostać wyświetlone sześć tabel, po jednym dla każdej projekcji zdefiniowanej w zestawie umiejętności.

Każda tabela jest generowana przy użyciu identyfikatorów niezbędnych do łączenia krzyżowego tabel w zapytaniach. Po otwarciu tabeli przewiń obok tych pól, aby wyświetlić pola zawartości dodane przez potok.

Zrzut ekranu przedstawiający tabele magazynu wiedzy w przeglądarce usługi Storage

W tym przewodniku magazyn wiedzy składa się z różnych tabel pokazujących różne sposoby kształtowania i tworzenia struktury tabeli. Tabele od trzech do trzech używają danych wyjściowych umiejętności kształtowania w celu określenia kolumn i wierszy. Tabele od czterech do sześciu są tworzone na podstawie wbudowanych instrukcji kształtowania osadzonych w samym projekcji. Możesz użyć dowolnego podejścia, aby osiągnąć ten sam wynik.

Table	opis
`hotelReviews1Document`	Zawiera pola przenoszone z woluminu CSV, takie jak reviews_date i reviews_text.
`hotelReviews2Pages`	Zawiera wzbogacone pola utworzone przez zestaw umiejętności, takie jak ocena tonacji i przetłumaczony tekst.
`hotelReviews3KeyPhrases`	Zawiera długą listę tylko kluczowych fraz.
`hotelReviews4InlineProjectionDocument`	Alternatywą dla pierwszej tabeli jest użycie kształtowania wbudowanego zamiast umiejętności Kształtowanie w celu kształtowania danych dla projekcji.
`hotelReviews5InlineProjectionPages`	Alternatywą dla drugiej tabeli przy użyciu kształtowania wbudowanego.
`hotelreviews6InlineProjectionKeyPhrases`	Alternatywą dla trzeciej tabeli przy użyciu kształtowania wbudowanego.

Czyszczenie

Jeśli pracujesz w ramach własnej subskrypcji, dobrym pomysłem po zakończeniu projektu jest sprawdzenie, czy dalej potrzebujesz utworzonych zasobów. Uruchomione zasoby mogą generować koszty. Zasoby możesz usuwać pojedynczo lub jako grupę zasobów, usuwając cały zestaw zasobów.

Zasoby można znaleźć w portalu i zarządzać nimi, korzystając z linku Wszystkie zasoby lub Grupy zasobów w okienku nawigacji po lewej stronie.

Następne kroki

Po wzbogaceniu danych przy użyciu usług Azure AI i projekcji wyników do magazynu wiedzy możesz użyć Eksplorator usługi Storage lub innych aplikacji do eksplorowania wzbogaconego zestawu danych.

Wprowadzenie do Eksploratora usługi Storage

Udostępnij za pośrednictwem