Добавление пользовательской функции в конвейер обогащения Поиск с использованием ИИ Azure

Note

Поиск с использованием ИИ Azure доступна через портал Azure, REST API и Azure SDKs. Он также лежит в основе Foundry IQ — управляемого слоя знаний, который преобразует корпоративный контент в многократно используемые базы знаний с учетом разрешений доступа для агентов на портале Microsoft Foundry.

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

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

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

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

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

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

Укажите интерфейс для пользовательского навыка с помощью навыка пользовательского веб-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, добавьте ключ API в заголовок или в качестве параметра URI в URI для авторизации запроса.

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

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

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

Если конечная точка, защищенная ограничениями доступа к IP-адресам, не отвечает, временно задайте timeout короткое значение, например PT10S, чтобы ускорить ошибку времени ожидания. Для приложения-функции Azure управляйте правилами входящегоIP-адреса в разделе >> доступа". Сведения о разрешенных IP-адресах см. в разделе "Настройка правил брандмауэра IP-адресов для разрешения подключений индексатора".

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

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

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

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

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

  • Элемент data , представляющий собой контейнер входных полей для каждой записи.

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

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issued 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"
          }
        ]
      }
  ]
}

Note

При получении набора навыков с помощью GET служба возвращает <redacted> для всех значений httpHeaders, чтобы предотвратить раскрытие учетных данных. Чтобы обновить навык без изменения сохраненных значений заголовков, задайте для каждого значения значение <unchanged>. Дополнительные сведения и примеры см. в разделе "Навык пользовательского веб-API" — параметры навыка.

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

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

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

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

  • Last updated on