Добавление пользовательского навыка в конвейер обогащения поиска ИИ Azure

Статья
06/29/2023

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

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

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

Преимущества пользовательских навыков

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

Установка конечной точки и интервала времени ожидания

Интерфейс для пользовательского навыка указывается с помощью навыка пользовательского веб-API.

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230 second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

URI — это конечная точка HTTPS функции или приложения. При настройке URI убедитесь, что универсальный код ресурса (URI) является безопасным (HTTPS). Если код размещен в приложении-функции Azure, URI должен включать ключ API в заголовок или в качестве параметра URI для авторизации запроса.

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

Служба поиска, которая отправляет запрос от имени индексатора, должна быть настроена для использования управляемого удостоверения (назначаемого системой или пользователем), чтобы вызывающий объект можно было пройти проверку подлинности с помощью идентификатора Microsoft Entra.
Функция или приложение должны быть настроены для идентификатора Microsoft Entra.
Определение пользовательского навыка должно содержать свойство authResourceId. Это свойство принимает идентификатор приложения (клиента) в поддерживаемом формате: api://<appId>

По умолчанию подключение к конечной точке истекает, если ответ не возвращается в 30-секундном окне. Конвейер индексирования синхронный, и индексирование приведет к ошибке времени ожидания, если ответ не получен в этом интервале времени. Интервал можно увеличить до максимального значения 230 секунд, задав параметр времени ожидания:

Форматирование входных данных веб-API

Веб-API должен принимать массив записей для обработки. Каждая запись должна содержать контейнер свойств, который является входным элементом, предоставленным веб-API.

Предположим, вы хотите создать базовый обогащение, определяющее первую дату, упоминание в тексте контракта. В этом примере пользовательский навык принимает один входной текст contractText в качестве текста контракта. Кроме того, навык имеет один выходной элемент — дату контракта. Чтобы сделать обогащение более интересным, верните этот "contractDate" в форме многокомпонентного сложного типа.

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

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

Полученный запрос веб-API может выглядеть следующим образом:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issues on November 3, 2017 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

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

Форматирование выходных данных веб-API

Формат выходных данных — это набор записей, содержащих "recordId" и контейнер свойств. Этот конкретный пример имеет всего один выходной элемент, но вывести можно более одного свойства. Рекомендуется возвращать сообщения об ошибках и предупреждениях, если запись не удалось обработать.

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2017 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

Добавление пользовательского когнитивного навыка к набору когнитивных навыков

При создании обогатителя веб-API можно в составе запроса описать HTTP-заголовки и параметры. В следующем фрагменте кода показано, как параметры запроса и необязательные заголовки HTTP можно включить в определение набора навыков. Если вам нужно передать параметры конфигурации в код, необходимо задать заголовок HTTP.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

Смотреть этот видеоролик

Чтобы просмотреть видео и демонстрацию, просмотрите следующую демонстрацию.

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

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