Создание хранилища знаний с помощью REST

Статья
03/11/2024

В службе "Поиск ИИ Azure" хранилище знаний — это репозиторий содержимого, созданного ИИ, используемого для сценариев, отличных от поиска. Вы создаете хранилище знаний с помощью индексатора и набора навыков и задаете служба хранилища Azure для хранения выходных данных. После заполнения хранилища знаний используйте такие средства, как Обозреватель службы хранилища или Power BI для изучения содержимого.

В этой статье вы используете REST API для приема, обогащения и изучения набора отзывов клиентов о пребывании в магазине знаний. Хранилище знаний содержит исходное текстовое содержимое, полученное из источника, а также содержимое, созданное СИ, которое включает оценку тональности, извлечение ключевых фраз, обнаружение языка и перевод комментариев клиентов, отличных от английского языка.

Для предоставления доступа к первоначальному набору данных отзывы об отеле сначала импортируются в Хранилище BLOB-объектов Azure. После обработки результаты сохраняются как хранилище знаний в Хранилище таблиц Azure.

Совет

В этой статье используется REST для подробных объяснений каждого шага. Скачайте REST-файл , если вы хотите просто выполнить команды. Кроме того, можно создать хранилище знаний в портал Azure.

Необходимые компоненты

Visual Studio Code с клиентом REST. Если вам нужна помощь по началу работы, см . краткое руководство. Поиск текста с помощью REST.
Поиск по искусственному интеллекту Azure. Создайте службу или найдите существующую. Вы можете использовать бесплатную службу для этого упражнения.
служба хранилища Azure; Создайте учетную запись или найдите существующую. Необходимо использовать учетную запись типа StorageV2 (общего назначения версии 2).

Набор навыков в этом примере использует службы ИИ Azure для обогащения. Так как рабочая нагрузка настолько мала, службы ИИ Azure касаются за кулисами, чтобы обеспечить бесплатную обработку до 20 транзакций ежедневно. Небольшая рабочая нагрузка означает, что вы можете пропустить создание или присоединение ресурса нескольких служб Azure AI.

Отправка данных в служба хранилища Azure и получение строка подключения

Скачайте HotelReviews_Free.csv. Этот CSV-файл содержит 19 частей отзывов клиентов об одном отеле (происходит из Kaggle.com).
В портал Azure найдите учетную запись хранения и используйте браузер служба хранилища для создания контейнера BLOB-объектов с именем hotel-reviews.
В верхней части страницы выберите Передать, чтобы загрузить файл HotelReviews-Free.csv, скачанный на предыдущем шаге.
Слева выберите ключи доступа, выберите "Показать ключи", а затем скопируйте строка подключения для ключа 1 или key2. Полный доступ строка подключения имеет следующий формат:

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

Примечание.

См. Подключение использование управляемого удостоверения, если вы не хотите предоставлять конфиденциальные данные в строка подключения.

Копирование ключа и URL-адреса

В этом примере вызовы REST требуют конечной точки службы поиска и используют ключ API для каждого запроса. Эти значения можно получить из портал Azure.

Войдите в портал Azure, перейдите на страницу обзора и скопируйте URL-адрес. Пример конечной точки может выглядеть так: https://mydemo.search.windows.net.
В разделе Параметры> Keys скопируйте ключ администратора. Администратор ключи используются для добавления, изменения и удаления объектов. Существует два взаимозаменяемых ключа администратора. Скопируйте любой из них.

Допустимый ключ API устанавливает доверие на основе каждого запроса между приложением, отправляя запрос и службу поиска, обрабатывая ее.

Создание индекса

Создание индекса (REST) создает индекс поиска в службе поиска. Индекс поиска не связан с хранилищем знаний, но индексатору требуется один. Индекс поиска содержит то же содержимое, что и хранилище знаний, которое можно исследовать, отправляя запросы.

Откройте новый текстовый файл в Visual Studio Code.

Задайте переменные в конечную точку поиска и ключ 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)

Сохраните файл с расширением .rest файла.

Вставьте в следующий пример, чтобы создать запрос индекса.

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

Щелкните Отправить запрос. Должен быть HTTP/1.1 201 Created ответ, а текст ответа должен содержать представление JSON схемы индекса.

Создание источника данных

Создание источника данных создает подключение к источнику данных в службе "Поиск ИИ Azure".

Вставьте в следующий пример, чтобы создать источник данных.

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

Щелкните Отправить запрос.

Создание набора навыков

Набор навыков определяет обогащения (навыки) и хранилище знаний. Создание набора навыков создает объект в службе поиска.

Вставьте следующий пример, чтобы создать набор навыков.

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

Основные моменты:

Навык фигуры важен для определения хранилища знаний. Он указывает, как данные передаются в таблицы хранилища знаний. Входные данные — это части обогащенного документа, который требуется сохранить. Выходные данные — это консолидация узлов в одну структуру.
Проекции указывают таблицы, объекты и большие двоичные объекты хранилища знаний. Каждый элемент проекции указывает "name" столбец или поле для создания в служба хранилища Azure. Указывает "source" , какая часть выходных данных фигуратора назначается данному полю или столбцу.

Создать индексатор

Создание индексатора создает и запускает индексатор . Выполнение индексатора начинается с взлома документов, извлечения текста и изображений и инициализации набора навыков. Индексатор проверка для других объектов, созданных: источника данных, индекса и набора навыков.

Вставьте в следующий пример, чтобы создать индексатор.

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

Выберите "Отправить запрос" , чтобы создать и запустить индексатор. Этот шаг занимает несколько минут.

Основные моменты:

Объект parameters/configuration управляет процессом приема данных индексатором. В этом примере входные данные находятся в одном CSV-файле со строкой заголовка и значениями, разделенными запятыми.
При сопоставлении полей создается AzureSearch_DocumentKey — уникальный идентификатор для каждого документа, создаваемого индексатором BLOB-объектов (на основе пути к хранилищу метаданных).
Сопоставления полей выходных данных определяют, как обогащенные поля сопоставляются с полями в индексе поиска. Сопоставления полей выходных данных не используются в хранилищах знаний (хранилища знаний используют фигуры и проекции для выражения структур физических данных).

Проверить состояние

После отправки каждого запроса служба поиска должна отправить сообщение с кодом 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}}

Через несколько минут можно запросить индекс для проверки содержимого. Даже если вы не используете индекс, этот шаг является удобным способом подтвердить, что набор навыков создал ожидаемые выходные данные.

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

Проверка таблиц в портал Azure

На портале Azure перейдите к учетной записи службы хранилища Azure и просмотрите новые таблицы в Обозревателе службы хранилища. Должны отобразиться шесть таблиц, по одной для каждой проекции, определенной в наборе навыков.

Каждая таблица создается с идентификаторами, необходимыми для перекрестного связывания таблиц в запросах. При открытии таблицы прокрутите эти поля, чтобы просмотреть поля содержимого, добавленные конвейером.

Screenshot of the knowledge store tables in Storage Browser

В этом пошаговом руководстве показано, что хранилище знаний состоит из различных таблиц для демонстрации разных способов формирования и структурирования таблицы. Таблицы с первой по третью используют выходные данные из навыка формирователя для определения столбцов и строк. Таблицы с четвертой по шестую создаются из встроенных инструкций по формированию, внедренных в саму проекцию. Для достижения того же результата можно использовать любой из этих подходов.

Таблицу	Description
`hotelReviews1Document`	Содержит поля, перенесенные из CSV-файла, такие как reviews_date и reviews_text.
`hotelReviews2Pages`	Содержит обогащенные поля, созданные набором навыков, например поля оценки тональности и переведенного текста.
`hotelReviews3KeyPhrases`	Содержит длинный список только ключевых фраз.
`hotelReviews4InlineProjectionDocument`	Альтернатива первой таблице с использованием встроенного формирования, а не навыка формирователя для формирования данных для проекции.
`hotelReviews5InlineProjectionPages`	Альтернатива второй таблице с использованием встроенного формирования.
`hotelreviews6InlineProjectionKeyPhrases`	Альтернатива третьей таблице с использованием встроенного формирования.

Очистка

Если вы работаете в собственной подписке, в конце проекта следует решить, нужны ли вам созданные ресурсы. Ресурсы, которые продолжат работать, могут быть платными. Вы можете удалить ресурсы по отдельности либо удалить всю группу ресурсов.

Просматривать ресурсы и управлять ими можно на портале с помощью ссылок Все ресурсы или Группы ресурсов на панели навигации слева.

Следующие шаги

Теперь, когда вы обогатили данные с помощью служб ИИ Azure и проецировали результаты в хранилище знаний, вы можете использовать Обозреватель службы хранилища или другие приложения для изучения обогащенного набора данных.

Начало работы с Обозревателем службы хранилища.