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

Статья
03/10/2024

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

Навык пользовательского веб-API также используется в реализации функции Azure OpenAI On Your Data. Если Azure OpenAI настроен для доступа на основе ролей и вы получаете 403 Forbidden вызовы при создании векторного индекса, убедитесь, что служба поиска ИИ Azure назначена системой и выполняется в качестве доверенной службы в Azure OpenAI.

Примечание.

Индексатор дважды повторяется для определенных стандартных кодов состояния HTTP, возвращаемых веб-API. Это такие коды состояния HTTP:

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Параметры навыков

Параметры зависят от регистра.

Наименование параметра	Description
`uri`	Универсальный код ресурса (URI) веб-API, в который отправляется полезные данные JSON. Допускается только схема URI HTTPS.
`authResourceId`	(Необязательно) Строка, которая если задана, указывает, что этот навык должен использовать управляемое удостоверение для подключения к функции или приложению, в котором размещен код. Это свойство принимает идентификатор приложения (клиента) или регистрацию приложения в идентификаторе Microsoft Entra в поддерживаемом формате: `api://<appId>` Это значение используется для область маркера проверки подлинности, полученного индексатором, и отправляется вместе с пользовательским запросом API веб-навыка в функцию или приложение. Установка этого свойства требует, чтобы служба поиска была настроена для управляемого удостоверения, а приложение-функция Azure настроено для входа в Microsoft Entra. Чтобы использовать этот параметр, вызовите API с `api-version=2023-10-01-Preview`помощью .
`httpMethod`	Метод, используемый при отправке полезных данных. Допустимые методы: `PUT` или `POST`.
`httpHeaders`	Коллекция пар "ключ-значение", в которых ключи представляют имена заголовков и значения, представляют значения заголовков, отправляемые веб-API вместе с полезными данными. Следующие заголовки запрещены в этой коллекции: `Accept`, `Content-TypeHostCookieTEAccept-EncodingContent-LengthAccept-Charset`, . `UpgradeVia`
`timeout`	(Необязательно.) Если указано, означает время ожидания вызова API HTTP-клиента. Значение должно быть отформатировано как значение dayTimeDuration XSD (ограниченное подмножество значения продолжительности ISO 8601 ). Например, `PT60S` для 60 секунд. Если не задано, выбирается значение по умолчанию — 30 секунд. Время ожидания можно задать в диапазоне от 1 до 230 секунд.
`batchSize`	(Необязательно) Указывает, сколько записей данных (см. структуру полезных данных JSON ниже) отправляется на вызов API. В противном случае выбирается значение по умолчанию — 1000. Мы рекомендуем использовать этот параметр для достижения подходящего компромисса между пропускной способностью индексирования и загрузкой в API.
`degreeOfParallelism`	(Необязательно) При указании указывает количество вызовов индексатора параллельно заданной конечной точке. Это значение можно уменьшить, если конечная точка не работает под давлением, или вызвать ее, если конечная точка может обработать нагрузку. Если не задано, используется значение по умолчанию — 5 секунд. Для `degreeOfParallelism` можно задать значение от 1 до 10.

Входные данные навыков

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

Выходные данные навыка

Для этого навыка нет предопределенных выходных данных. Обязательно определите сопоставление полей выходных данных в индексаторе, если выходные данные навыка должны быть отправлены в поле в индексе поиска.

Пример определения

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

Пример структуры входных данных JSON

Эта структура JSON представляет полезные данные, отправляемые в веб-API. Он всегда следует этим ограничениям:

Вызывается values сущность верхнего уровня и представляет собой массив объектов. Число таких объектов в большинстве batchSizeслучаев.
Каждый объект в массиве values имеет:
- Свойство recordId, которое является уникальной строкой, используемой для идентификации этой записи.
- data Свойство, которое является объектом JSON. Поля data свойства соответствуют "именам", указанным в inputs разделе определения навыка. Значения этих полей относятся к этим полям (которые могут быть из source поля в документе или потенциально из другого навыка).

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

Пример структуры выходных данных JSON

Выходные данные соответствуют ответу, возвращенному от веб-API. Веб-API должен возвращать полезные данные JSON (проверенные с помощью просмотра заголовка Content-Type ответа) и удовлетворять следующим ограничениям:

Должна быть вызываемая valuesсущность верхнего уровня, которая должна быть массивом объектов.
Количество объектов в массиве должно быть таким же, как количество объектов, отправляемых в веб-API.
Каждый объект должен иметь:
- Свойство recordId .
- Свойство data, являющееся объектом, в котором поля представляют собой обогащения, соответствующие именам в output (их значения считаются обогащением).
- Свойство errors , массив, в котором перечислены все ошибки, которые добавляются в журнал выполнения индексатора. Это свойство является обязательным, но может иметь значение null.
- Свойство warnings , массив с описанием всех предупреждений, добавленных в журнал выполнения индексатора. Это свойство является обязательным, но может иметь значение null.
Порядок объектов в values запросе или ответе не важен. Тем не менее, recordId используется для корреляции, поэтому любая запись в ответе, содержащая ответrecordId, который не был частью исходного запроса к веб-API, не является карта.

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

Варианты ошибок

В дополнение к недоступности веб-API или отправке неуспешных кодов состояния случаями ошибок также считаются следующие:

Если веб-API возвращает код состояния успешности, но ответ указывает, что ответ не application/json является недопустимым, и обогащения не выполняются.
Если в массиве ответов values отсутствуют недопустимые записи (например, recordId отсутствуют или дублируются), обогащение для недопустимых записей не выполняется. При разработке пользовательских навыков важно придерживаться контракта навыков веб-API. Этот пример можно найти в репозитории Power Skill, который следует ожидаемому контракту.

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