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

Статья
04/27/2024

Конвейер обогащения ИИ может включать встроенные навыки и пользовательские навыки, которые вы лично создаете и публикуете. Пользовательский код выполняется вне службы поиска (например, как функция 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-секундном окне (PT30S). Конвейер индексирования синхронный, и индексирование приведет к ошибке времени ожидания, если ответ не получен в этом интервале времени. Интервал можно увеличить до максимального значения 230 секунд, задав параметр времени ожидания (PT230S).

Форматирование входных данных веб-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, 2023 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" : 2023 }                    
        }
      },
      {
        "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"
          }
        ]
      }
  ]
}

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

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

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

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