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

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

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

@odata.type

Microsoft.Skills.Custom.WebApiSkill

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

Параметры чувствительны к регистру.

Общие сведения о значении authResourceId

Если навык пользовательского веб-API использует проверку подлинности управляемого удостоверения, Поиск с использованием ИИ Azure получает маркер доступа Microsoft Entra и отправляет его в конечную точку пользовательского навыка. Свойство authResourceId задает идентификатор ресурса, также известный как URI аудитории или идентификатора приложения, для которого запрашивается маркер. Значение должно соответствовать ожидаемому целевому приложению во время проверки маркера. В противном случае проверка подлинности завершается ошибкой 401 Unauthorized с помощью ответа.

Значение authResourceId определяет приложение, в котором размещается пользовательский навык. Это не URL-адрес службы поиска или индексатора.

В следующей таблице показаны распространенные форматы:

Свойство принимает форматы с суффиксом области и без нее .default . Используется api://<appId> для сопоставления URI идентификатора приложения напрямую. Если включить суффикс, например.default, утверждение маркера api://<appId>/.default доступа содержит базовый aud URI идентификатора приложения без суффикса.

Инструкции по настройке проверки подлинности Microsoft Entra для функции Azure и задания authResourceIdсм. в разделе "Использование управляемого удостоверения службы поиска" для подключения к приложению-функции Azure.

Пример: функция Azure, защищенная Microsoft Entra ID

В этом примере Поиск с использованием ИИ Azure получает маркер доступа для аудитории, указанной authResourceId и включает маркер при вызове конечной точки пользовательского навыка.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso-function.azurewebsites.net/api/enrich",
  "authResourceId": "api://contoso-customskill"
}

Входные параметры навыков

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

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

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

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

{
  "@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"
    }
  ]
}

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso.example.org/api?code=<redacted>",
  "httpMethod": "POST",
  "name": "myCustomSkill",
  "httpHeaders": {
    "Authorization": "<redacted>",
    "Ocp-Apim-Subscription-Key": "<redacted>"
  }
}

{
  "uri": "<unchanged>",
  "httpHeaders": {
    "Authorization": "<unchanged>",
    "Ocp-Apim-Subscription-Key": "<unchanged>"
  }
}

Пример структуры входных данных 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.

Вопросы безопасности для проверки подлинности управляемых удостоверений

При использовании проверки подлинности управляемого удостоверения с навыком пользовательского веб-API Поиск с использованием ИИ Azure получает маркер доступа Microsoft Entra для приложения, определяемого authResourceId приложением, и включает этот маркер в запросы, отправленные в конечную точку, указанную в uriней. Конечная точка, на которую ссылаетсяuri, обычно это функция Azure, Служба приложений Azure, Azure API Management или другое приложение, защищенное Microsoft Entra. Вы несете ответственность за настройку и поддержание связи между конечной точкой и приложением, определяемым.authResourceId

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

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

Recommended security practices (Рекомендации по безопасности)

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

• uri Настройте свойство, чтобы указать только доверенные конечные точки, которые предназначены для получения запросов от Поиск с использованием ИИ Azure.
• Настройте authResourceId для идентификации приложения Microsoft Entra, которое, как ожидается, будет получать и проверять маркер доступа.
• Убедитесь, что приложение, получающее запросы, проверяет стандартные утверждения маркеров, включая аудиторию (), издателя (aud), клиента (isstid) и все необходимые роли приложения или разрешения перед обработкой запросов.
• При предоставлении разрешений управляемому удостоверению Поиск с использованием ИИ Azure применяется принцип наименьшей привилегии.
• Периодически просматривают определения навыков пользовательского веб-API, Microsoft Entra регистрации приложений, а также назначения ролей приложений и разрешения, предоставленные Поиск с использованием ИИ Azure управляемым удостоверениям. Просмотрите изменения конфигурации с помощью установленных процессов управления изменениями и проверки безопасности.
• Периодически просматривает конфигурации конечных точек для Функции Azure, служб приложений, API и шлюзов API.
• Отслеживайте журналы входа приложения, события проверки подлинности и журналы доступа API для непредвиденного или несанкционированного действия.
• Удалите неиспользуемые конечные точки, разрешения, регистрации приложений и назначения ролей, которые больше не требуются.

Ограничение доступа к конфигурации набора навыков

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

См. также

• Определение набора навыков
• Добавление пользовательского навыка в конвейер обогащения с помощью ИИ
• Пример. Создание пользовательского навыка для обогащения с помощью ИИ
• Репозиторий Power Skill