Руководство. Исправление набора навыков с помощью сеансов отладки

В службе "Поиск ИИ Azure" набор навыков координирует действия навыков, которые анализируют, преобразуют или создают содержимое, которое можно найти. Часто выходные данные одного навыка становятся входными данными другого. Если входные данные зависят от выходных, ошибки в определениях набора навыков и связываниях полей могут привести к отсутствию операций и данных.

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

В этом руководстве вы используете сеансы отладки для поиска и исправления отсутствующих входных и выходных данных. Это руководство всеобъемлющее. Он предоставляет примеры данных, REST-файл, который создает объекты и инструкции по отладке проблем в наборе навыков.

Prerequisites

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .

• Поиск по искусственному интеллекту Azure. Создайте службу или найдите существующую службу в текущей подписке. Вы можете использовать бесплатную службу для выполнения инструкций, описанных в этом учебнике. Уровень "Бесплатный" не предоставляет поддержку управляемой идентификации для службы поиска искусственного интеллекта Azure. Вы должны использовать ключи для подключений к Azure хранилищу.

• Учетная запись хранения Azure с хранилищем объектов Blob, используемая для размещения образцов данных и хранения кэшированных данных, созданных во время сеанса отладки. Если вы используете бесплатную службу поиска, учетная запись хранения должна иметь ключи общего доступа и разрешить доступ к общедоступной сети.

• Visual Studio Code с клиентом REST.

• Примеры PDF-файлов (клинические испытания).

• Пример файла debug-session.rest, используемого для создания конвейера обогащения.

Настройка примеров данных

С помощью инструкций из этого раздела вы создадите пример набора данных в Хранилище BLOB-объектов Azure, с которыми будут работать индексатор и набор навыков.

1. Скачайте пример данных (clinical-trials-pdf-19), состоящий из 19 файлов.

2. Создайте учетную запись хранения Azure или найдите имеющуюся учетную запись.

   • Выберите тот же регион, что и Поиск с использованием ИИ Azure, чтобы избежать расходов на пропускную способность.

   • Выберите тип учетной записи StorageV2 (общего назначения версии 2).

3. Перейдите на страницы служб хранилища Azure на портале Azure и создайте контейнер BLOB-объектов. Рекомендуется указать уровень доступа "частный". Присвойте контейнеру имя clinicaltrialdataset.

4. В контейнере выберите "Отправить ", чтобы отправить скачанные и распакованные примеры файлов на первом шаге.

5. На портале Azure выберите "Параметры>доступа" и скопируйте строку подключения для службы хранилища Azure.

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

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

1. Перейдите в службу поиска в портал Azure.

2. На странице обзора скопируйте URL-адрес конечной точки. Пример конечной точки может выглядеть так: https://mydemo.search.windows.net.

3. В разделе "Ключи> параметров" скопируйте ключ администратора. Ключи администратора используются для добавления, изменения и удаления объектов. Существует два взаимозаменяемых ключа администратора. Скопируйте любой из них.

   

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

Создание источника данных, набора навыков, индекса и индексатора

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

1. Запустите Visual Studio Code и откройте debug-sessions.rest файл.

2. Укажите следующие переменные: URL-адрес службы поиска, ключ API администрирования служб поиска, строка подключения хранилища и имя контейнера BLOB-объектов, в котором хранятся PDF-файлы.

3. Отправьте каждый запрос в свою очередь. Создание индексатора занимает несколько минут.

4. Закройте файл.

Проверьте результаты в портале Azure

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

1. В Azure portal на странице Обзор службы поиска выберите вкладку Индексы.

2. Выберите клинические испытания.

3. Введите эту строку запроса JSON в представлении JSON поискового обозревателя. Он возвращает поля для определенных документов (идентифицируется уникальным metadata_storage_path полем).

   "search": "*",
   "select": "metadata_storage_path, organizations, locations",
   "count": true
   

4. Выполните запрос. Вы должны увидеть пустые значения для organizations и locations.

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

Ошибки и предупреждения также можно изучить на портале Azure.

1. На вкладке Индексаторов выберите клинические испытания-idxr.

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

2. Выберите "Успех", чтобы просмотреть предупреждения. Если в основном возникают ошибки, ссылка на сведения отображает ошибку. Вы увидите длинный список всех предупреждений, создаваемых индексатором.

   

Запуск сеанса отладки

1. В области навигации слева от службы поиска в разделе "Управление поиском" выберите сеансы отладки.

2. Выберите + Добавить сеанс отладки.

3. Присвойте сеансу имя.

4. В шаблоне индексатора укажите имя индексатора. Индексатор содержит ссылки на источник данных, набор навыков и индекс.

5. Выберите учетную запись хранилища.

6. Сохраните сеанс.

   

7. Сеанс отладки открывается на странице параметров. Вы можете внести изменения в начальную конфигурацию и переопределить все значения по умолчанию. Сеанс отладки работает только с одним документом. По умолчанию необходимо принять первый документ в коллекции в качестве основы сеансов отладки. Вы можете выбрать определенный документ для отладки, предоставив URI в службе хранилища Azure.

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

   

Определение проблем с набором навыков

Все проблемы, сообщаемые индексатором, указываются как ошибки и предупреждения.

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

Выберите предупреждения , чтобы просмотреть уведомления. Вы должны увидеть четыре:

• "Не удалось выполнить навык, так как один или несколько входных данных навыка были недопустимыми. Отсутствует обязательный входной параметр навыка. Имя: "text", источник: "/document/content".

• Не удалось сопоставить выходное поле 'locations' с индексом поиска. Не удалось сопоставить выходное поле 'locations' с индексом поиска. Отсутствует значение '/document/merged_content/locations'. Проверьте свойство 'outputFieldMappings' вашего индексатора. Отсутствует значение /document/merged_content/locations.)

• Не удалось сопоставить выходное поле 'organizations' с индексом поиска. Проверьте свойство 'outputFieldMappings' в вашем индекслере. Отсутствует значение '/document/merged_content/organizations'. Проверьте свойство 'outputFieldMappings' вашего индексатора. Отсутствует значение "/document/merged_content/organizations".

• "Навык выполнен, но может иметь непредвиденные результаты, так как один или несколько входных данных навыка были недопустимыми. Отсутствуют необязательные входные данные навыка. Имя: languageCode; источник: /document/languageCode. Проблемы синтаксического анализа языка выражений: отсутствующее значение "/document/languageCode".

Многие навыки имеют параметр languageCode. Проверив операцию, вы увидите, что входные данные кода языка отсутствуют в EntityRecognitionSkill.#1, что касается того же навыка распознавания сущностей, который испытывает проблемы с выводом «расположений» и «организаций».

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

Исправить отсутствующие значения входных данных навыков

1. На рабочей поверхности выберите навык, который сообщает предупреждения. В этом руководстве это навык распознавания сущностей.

2. Область сведений о навыке открывается справа с разделами для итераций и их соответствующих входных и выходных данных, параметрами навыка для JSON-определения навыка и сообщениями об ошибках и предупреждениях, которые этот навык выдает.

   

3. Наведите указатель мыши на все входные данные (или выберите входные данные), чтобы отобразить значения в вычислителе выражений. Обратите внимание, что отображаемый результат для этого ввода не выглядит как текстовый ввод. Он выглядит как ряд символов новой строки \n \n\n\n\n вместо текста. Отсутствие текста означает, что сущности не могут быть идентифицированы. Либо этот документ не соответствует предварительным требованиям навыка, либо следует использовать другой документ.

   

4. Вернитесь в структуру обогащенных данных и просмотрите узлы обогащения для этого документа. Обратите внимание, что \n \n\n\n\n для "содержимого" нет исходного источника, но другое значение для "merged_content" имеет выходные данные OCR. Хотя нет никаких признаков, содержимое этого PDF-файла, как представляется, является файлом JPEG, как показывают извлеченный и обработанный текст в "merged_content".

   

5. Вернитесь к навыку и выберите параметры набора навыков, чтобы открыть определение JSON.

6. Измените выражение на /document/content/document/merged_content, а затем нажмите кнопку "Сохранить". Обратите внимание, что предупреждение больше не указано.

   

7. Выберите "Запустить " в меню окна сеанса. Это запускает другое выполнение набора навыков с помощью документа.

8. После завершения выполнения сеанса отладки обратите внимание, что число предупреждений сократилось на один. Предупреждения показывают, что ошибка ввода текста исчезла, но остальные предупреждения остаются. Следующий шаг — устранение предупреждения об отсутствующих или пустых значениях /document/languageCode.

   

9. Выберите навык и наведите курсор /document/languageCode. Значение для этого ввода равно NULL, которое не является допустимым входным.

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

11. Скопируйте выражение /document/language.

12. В области сведений о навыке выберите "Параметры навыка" для навыка #1 и вставьте новое значение /document/language.

13. Нажмите кнопку "Сохранить".

14. Выберите Выполнить.

15. После завершения выполнения сеанса отладки можно проверить результаты в области сведений о навыках. При наведении указателя мыши на /document/language вы должны увидеть en в качестве значения в вычислителе выражений .

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

Исправить отсутствие выходных значений навыков

Сообщения говорят, чтобы проверить свойство outputFieldMappings индексатора, поэтому давайте начнем с этого.

1. Выберите сопоставления полей вывода на рабочей поверхности. Обратите внимание, что отсутствуют сопоставления выходных полей.

   

2. Сначала убедитесь, что индекс поиска имеет ожидаемые поля. В этом случае индекс содержит поля для "расположения" и "организации".

3. Если нет проблем с индексом, следующий шаг — проверить результаты навыка. Как и раньше, выберите структуру обогащенных данных и прокрутите узлы, чтобы найти "расположения" и "организации". Обратите внимание, что родительским элементом является "content", а не "merged_content". Контекст неправильный.

4. Переключитесь на панель сведений "Навыки" для навыка распознавания сущностей.

5. В параметрах навыка измените значение contextdocument/merged_content. На этом этапе необходимо внести три изменения в определение навыка.

   

6. Нажмите кнопку "Сохранить".

7. Выберите Выполнить.

Все ошибки разрешаются.

Фиксация изменений в наборе навыков

При запуске сеанса отладки служба "Поиск" создала копию набора навыков. Это сделано для защиты исходного набора навыков в вашей службе поиска. Теперь, когда вы отладили набор навыков, исправления можно зафиксировать (перезаписать исходный набор навыков).

Кроме того, если вы не готовы зафиксировать изменения, вы можете сохранить сеанс отладки и открыть его позже.

1. Выберите "Зафиксировать изменения" в главном меню сеансов отладки.

2. Нажмите кнопку "ОК ", чтобы подтвердить, что вы хотите обновить набор навыков.

3. Закройте сеанс отладки и откройте индексаторы из левой области.

4. Выберите "clinical-trials-idxr".

5. Выберите Сброс.

6. Выберите Выполнить.

7. Выберите Обновить, чтобы отобразить состояние команд сброса и их выполнения.

Когда индексатор завершит работу, должен быть зеленый флажок и слово Success рядом с меткой времени для последнего запуска на вкладке журнала выполнения . Чтобы убедиться, что изменения применяются:

1. В левой области откройте индексы.

2. Выберите индекс "клинические испытания" и на вкладке обозревателя поиска введите эту строку запроса: $select=metadata_storage_path, organizations, locations&$count=true чтобы вернуть поля для определенных документов (идентифицируемых уникальным metadata_storage_path полем).

3. Нажмите Поиск.

В результатах должно быть указано, что теперь сущности "организации" и "локации" заполнены ожидаемыми значениями.

Очистка ресурсов

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

Ресурсы и управление ими можно найти в портал Azure, используя ссылку "Все ресурсы" или "Группы ресурсов" в области навигации слева.

Бесплатная служба ограничена тремя индексами, индексаторами и источниками данных. Вы можете удалить отдельные элементы в портале Azure, чтобы остаться в пределах ограничения.

Дальнейшие шаги

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

• Сопоставление выходных полей набора навыков с полями в индексе поиска

• Компетенции в поиске ИИ Azure

• Настройка кэширования для добавочного обогащения (предварительная версия)