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

  • Статья

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

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

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

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

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

  • Назначение роли участника в службе поиска.

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

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

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

Ограничения

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

  • Azure Cosmos DB для MongoDB в настоящее время не поддерживается.

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

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

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

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

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

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

  2. На левой странице навигации выберите "Отладка сеансов".

  3. В верхней строке действий выберите "Добавить сеанс отладки".

    Снимок экрана: команды сеансов отладки на странице портала.

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

  5. В поле Подключение к хранилищу найдите учетную запись хранения общего назначения для кэширования сеанса отладки. Вам будет предложено выбрать и при необходимости создать контейнер BLOB-объектов в служба хранилища или Azure Data Lake Storage 2-го поколения. Вы можете повторно использовать один и тот же контейнер для всех последующих сеансов отладки, которые вы создаете. Полезное имя контейнера может быть "cognitive-search-debug-session".

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

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

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

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

    Снимок экрана: свойство URI в хранилище BLOB-объектов.

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

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

    Снимок экрана: страница сеанса отладки.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Начните с представлений по умолчанию: Граф навыка обогащения > ИИ с типом графа, заданным для Графа зависимостей.

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

  3. В области сведений справа выберите "Выполнение", выберите выходной объект, а затем откройте средство оценки выражений (</>), чтобы просмотреть выражение и его результат.

    Снимок экрана: выполнение навыка с выходными значениями.

  4. Кроме того, откройте обогащение обогащения> ИИ, чтобы прокрутить список узлов вниз. Список включает потенциальные и фактические узлы, столбец для выходных данных и другой столбец, указывающий объект вышестоящий, используемый для создания выходных данных.

    Снимок экрана: обогащенный документ с выходными значениями.

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

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

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

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

  1. В Графе навыка обогащения > искусственного интеллекта выберите навык. Откроется область сведений о навыке справа.

  2. Измените определение навыка с помощью любого подхода:

    • Навык Параметры, если вы предпочитаете визуальный редактор
    • Редактор JSON навыка для редактирования документа JSON напрямую

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

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

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

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

  1. Начните с представлений по умолчанию: Граф навыка обогащения > ИИ с типом графа, заданным для Графа зависимостей.

  2. Выберите сопоставления полей в верхней части. Необходимо найти по крайней мере ключ документа, который однозначно идентифицирует и связывает каждый документ поиска в индексе поиска с исходным документом в источнике данных.

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

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

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

    Снимок экрана: узел сопоставления полей вывода и сведения.

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

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

Получение общедоступного 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-адрес пересылки создается случайным образом.

    Снимок экрана: терминал ngrok.

Настройка на портале Azure

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

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

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

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

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

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

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