Отладка набора навыков поиска ИИ Azure в портал Azure

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

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

Дополнительные сведения о том, как работает сеанс отладки, см. в разделе "Отладка сеансов" в службе "Поиск ИИ Azure". Инструкции по отладке рабочего процесса с примером документа см. в руководстве по отладке сеансов.

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

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

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

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

• Для назначений ролей идентификатор службы поиска должен иметь следующее:

  • Разрешения пользователей Cognitive Services в учетной записи многослужб Azure AI, используемой набором навыков.

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

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

Ограничения

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

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

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

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

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

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

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

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

2. В меню слева выберите сеансы отладки управления поиском>.

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

   

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

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

6. В учетной записи хранения найдите учетную запись хранения общего назначения для кэширования сеанса отладки.

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

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

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

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

10. В строка подключения хранилища можно указать строка подключения или изменить учетную запись хранения.

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

    Если ваш документ является большим двоичным объектом, укажите универсальный код ресурса (URI) BLOB-объектов. URI можно найти на странице свойств BLOB-объектов на портале.

    

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

13. Если вы внесли изменения, выберите "Сохранить сеанс", а затем выполните команду "Выполнить".

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   

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

   

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

   

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   • npm: npm install -g tunnelmole
   • Linux: curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
   • Mac: curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
   • Windows: установка с помощью npm. Или если у вас нет NodeJS, скачайте предварительно скомпилированные .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

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

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

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

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

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

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

Руководство. Изучение сеансов отладки