Отладка набора навыков Azure AI Search в портале Azure

Запустите сеанс отладки на портале для выявления и устранения ошибок, проверки внесённых изменений и отправки изменений в существующий список навыков в службе поиска Azure AI.

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

Сведения о том, как работает сеанс отладки, см. в разделе Debug session in Azure AI Search. Инструкции по отладке рабочего процесса с примером документа см. в руководстве по отладке сеансов.

Предварительные требования

• Служба поиска Azure ИИ, любой регион или уровень.

• Учетная запись Azure Storage, используемая для сохранения состояния сеанса.

• Существующий конвейер обогащения, включая источник данных, набор навыков, индексатор и индекс.

Ограничения

Сеансы отладки работают со всеми общедоступными источниками данных индексатора и большинством предварительных версий данных с следующими исключениями:

• Индексатор SharePoint.

• Azure Индексатор Cosmos DB для MongoDB.

• При использовании Azure Cosmos DB для NoSQL, если строка завершается с ошибкой во время индексации и отсутствуют соответствующие метаданные, сеанс отладки может не выбрать правильную строку.

• Для API NoSQL Azure Cosmos DB, если секционированная коллекция ранее не секционирована, сеанс отладки не найдет документ.

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

Безопасность и разрешения

• Чтобы сохранить сеанс отладки в Azure Storage, удостоверение службы поиска должно иметь разрешения Участник данных BLOB-объектов в хранилище на Azure Storage. В противном случае выберите строку подключения для полноценного доступа для подключения сеанса отладки к Azure Storage.

• Если учетная запись Azure Storage находится за брандмауэром, настройте ее на allow search service access.

• Если Azure AI Search настроено использовать ключ шифрования, управляемый клиентом (CMK), конфиденциальная информация в сеансе отладки шифруется с этим ключом при сохранении данных.

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

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

2. На левой панели выберите Управление поиском>Сеансы отладки.

3. На панели действий в верхней части нажмите кнопку "Добавить сеанс отладки".

   

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

5. В поле Шаблон индексатора выберите индексатор, который управляет набором навыков, который вы хотите отладить. Копии индексатора и набора навыков используются для инициализации сеанса.

6. В поле Документе для отладки выберите первый документ в индексе или выберите определенный документ. Если выбрать определенный документ в зависимости от источника данных, вам будет предложено указать универсальный код ресурса (URI) или идентификатор строки.

   Для конкретного документа в Blob-хранилище укажите URI BLOB-объекта. URI можно найти на странице свойств BLOB-объектов в Azure portal.

   

   Для конкретного документа в Azure Cosmos DB для NoSQL укажите ключ документа в индексе поиска для значения и идентификатор сущности в Cosmos DB для ключа секции.

   

   Ниже приведена конфигурация сеанса отладки для примера Cosmos DB.

   

7. В Storage выберите учетную запись storage общего назначения для кэширования сеанса отладки.

8. Выберите Аутентификация с помощью управляемого удостоверения, если вы ранее назначили разрешения участника данных BLOB-объектов Storage для управляемого системой удостоверения поискового сервиса. Если этот флажок не установлен, служба поиска подключается с помощью строки подключения с полным доступом.

9. Выберите Сохранить.

   • Azure AI Search создает контейнер BLOB-объектов Azure Storage с именем ms-az-cognitive-search-debugsession.
   • В этом контейнере создается папка, используя имя, указанное для имени сеанса.
   • Он запускает сеанс отладки.

Сеанс отладки начинается с выполнения индексатора и набора функций в выбранном документе. Содержимое и метаданные документа отображаются и доступны в сеансе.

Сеанс отладки можно отменить в процессе выполнения. Если нажмите кнопку "Отмена" , вы сможете проанализировать частичные результаты.

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

Начните с ошибок и предупреждений

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

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

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

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

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

1. Нажмите кнопку "Сохранить " в области сведений о навыке, чтобы сохранить изменения.

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

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

Просмотр обогащенного или созданного содержимого

Пайплайны обогащения ИИ извлекают или выводят информацию и структуру из исходных документов, в результате создавая обогащенный документ. Обогащенный документ сначала создается во время взлома документов и заполняется корневым узлом (/document), а также узлами для любого содержимого, которое поднимается непосредственно из источника данных, например метаданных и ключа документа. Дополнительные узлы создаются в процессе выполнения навыков, и каждый результат навыка добавляет новый узел в дерево обогащения.

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

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

   

2. Выберите навык.

   

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

   

Проверьте сопоставления индексов

Если навыки создают выходные данные, но индекс поиска пуст, проверьте сопоставления полей. Сопоставления полей указывают, как содержимое перемещается из конвейера в индекс поиска.

Выберите один из вариантов сопоставления и разверните представление сведений для просмотра исходных и целевых определений.

• Сопоставления проекций находятся в наборах навыков, которые обеспечивают интегрированную векторизацию, например навыки, созданные мастером импорта данных. Эти сопоставления определяют сопоставления полей родительского и дочернего (блока) и будет ли создан вторичный индекс только для фрагментированного содержимого.

• Сопоставления полей выходных данных находятся в индексаторах и используются при вызове встроенных или пользовательских наборов навыков. Эти сопоставления используются для установки пути данных от узла в дереве обогащения к полю в индексе поиска. Для получения дополнительной информации о путях см. синтаксис пути узла обогащения.

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

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

Изменение определений навыков

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

Другие проблемы, такие как недопустимое контекстное или входное выражение, могут быть сложнее устранить, так как ошибка сообщит вам, что неправильно, но не как исправить его. Сведения о контексте и синтаксисе ввода см. в разделе Справка обогащений в наборе навыков Azure AI Search. Дополнительные сведения об отдельных сообщениях см. в разделе "Устранение распространенных ошибок и предупреждений индексатора".

В следующих шагах показано, как получить сведения о навыке.

1. Выберите навык на рабочей поверхности. Откроется область сведений о навыке справа.

2. Изменение определения навыка с помощью параметров навыка. Вы можете напрямую изменить JSON.

3. Проверьте синтаксис пути для ссылок на узлы в дереве обогащения. Ниже приведены некоторые из наиболее распространенных входных путей:

   • /document/content для фрагментов текста. Этот узел заполняется из свойства содержимого BLOB.
   • /document/merged_content для фрагментов текста в инструментах, включающих умение объединения текста.
   • /document/normalized_images/* для текста, распознанного или выводимого из изображений.

Отладьте пользовательский навык локально

Пользовательские навыки (Custom Skills) могут быть более сложными для отладки, поскольку код выполняется внешне, поэтому сеанс отладки не может использоваться для отладки этих навыков. В этом разделе описывается, как локально выполнить отладку навыка пользовательского веб-API, сеанс отладки, Visual Studio Code и ngrok или Tunnelmole. Этот метод взаимодействует с пользовательскими навыками, которые выполняются в Azure Functions или любом другом веб-фреймворке, который запускается локально (например, FastAPI).

Получение общедоступного URL-адреса

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

Использование Tunnelmole

Tunnelmole — это средство open source туннелирования, которое может создать общедоступный URL-адрес, который пересылает запросы на локальный компьютер через туннель.

1. Установите Tunnelmole:

   • Npm: npm install -g tunnelmole
   • Линукс: curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
   • Мак: curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
   • Windows: установка с помощью npm. Или если вы не установили Node.js, скачайте предварительно скомпилированные .exe-файл для Windows и поместите его в папку PATH.

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

   tmole 7071
   

   Вы увидите ответ, который выглядит следующим образом:

   http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   

   В предыдущем примере https://m5hdpb-ip-49-183-170-144.tunnelmole.net перенаправляет на порт 7071 на вашем локальном компьютере, который является портом по умолчанию, где доступны функции Azure.

Используйте ngrok

ngrok — это популярное кроссплатформенное приложение закрытого кода, которое может создавать URL-адрес для туннелирования или пересылки, чтобы интернет-запросы достигали вашего локального компьютера. Используйте ngrok для пересылки запросов из конвейера обогащения в вашей поисковой службы на ваш компьютер для отладки на локальной машине.

1. Установите ngrok.

2. Откройте терминал и перейдите в папку с исполняемым файлом ngrok.

3. Чтобы создать новый туннель, выполните команду ngrok:

   ngrok http 7071 
   

   Примечание.

   По умолчанию функции Azure доступны на порту 7071. Другие средства и конфигурации могут потребовать предоставления другого порта.

4. При запуске ngrok скопируйте и сохраните общедоступный URL-адрес пересылки для следующего шага. URL-адрес пересылки создается случайным образом.

   

Настройка в Azure portal

После того как у вас есть общедоступный URL-адрес для пользовательского навыка, измените URI навыка пользовательского веб-API в сеансе отладки, чтобы вызвать URL-адрес переадресации Tunnelmole или ngrok. При использовании функции Azure для выполнения кода набора навыков обязательно добавьте значение "/api/FunctionName".

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

Тестирование кода

На этом этапе новые запросы из сеанса отладки теперь должны отправляться в локальную функцию Azure. Точки останова можно использовать в коде Visual Studio для отладки кода или пошагового выполнения.

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

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