Векторизатор пользовательского веб-API

Note

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

Векторизатор пользовательского веб-API позволяет настроить поисковые запросы для вызова конечной точки веб-API, которая создает векторные представления во время выполнения запроса. Требуемая структура полезных данных JSON для конечной точки описана далее в этой статье. Данные обрабатываются в географии, где развернута модель.

Хотя векторизаторы используются во время запроса, вы указываете их в определениях индекса и ссылаетесь на них на поля векторов через профиль вектора. Дополнительные сведения см. в разделе "Настройка векторизатора" в индексе поиска.

Настраиваемый векторизатор веб-API называется WebApiVectorizer в REST API. Используйте последнюю стабильную версию Indexes — создание (REST API) или пакет пакета SDK Azure, который предоставляет эту функцию.

Параметры векторизатора

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

Наименование параметра Описание
uri Универсальный код ресурса (URI) веб-API, в который отправляется нагрузка JSON. Допускается только схема URI HTTPS. При получении индекса с помощью GET служба возвращает значение параметра запроса ?code= как ?code=<redacted>, чтобы предотвратить раскрытие ключей функций. Чтобы обновить векторизатор, не изменив сохраненный URI, установите значение uri<unchanged>.
httpMethod Метод, используемый для отправки полезных данных. Допустимые методы: PUT или POST.
httpHeaders Коллекция пар "ключ-значение", в которых ключи соответствуют именам заголовков, а значения - их значениям, отправляемым веб-API с полезной нагрузкой. В этой коллекции запрещены следующие заголовки: Accept, Accept-CharsetAccept-EncodingContent-LengthContent-TypeCookie, . HostTEUpgradeVia При получении индекса с помощью метода GET служба возвращает <redacted> для всех значений заголовков, чтобы предотвратить раскрытие учетных данных. Чтобы обновить векторизатор без изменения сохраненных значений заголовков, задайте для каждого значения <unchanged>значение . Служба восстанавливает исходное сохраненное значение.
authResourceId (Необязательно) Строка, которая, если задано, указывает, что этот векторизатор использует управляемое удостоверение для подключения к функции или приложению, в котором размещен код. Это свойство принимает идентификатор приложения (клиента) или регистрацию приложения в Microsoft Entra ID в одном из следующих форматов: api://<appId>, <appId>/.default, api://<appId>/.default. Это значение определяет маркер проверки подлинности, полученный конвейером запросов, и отправляется с помощью пользовательского запроса веб-API в функцию или приложение. Для настройки этого свойства требуется, чтобы ваш поисковый сервис был настроен для управляемого удостоверения, а ваше приложение-функция Azure было настроено для входа в систему Microsoft Entra.
authIdentity (Необязательно) Управляемое пользователем удостоверение, используемое службой поиска для подключения к функции или приложению, которое выполняет код. Можно использовать управляемое системой удостоверение или управляемое пользователем удостоверение. Чтобы использовать управляемое системой удостоверение, оставьте authIdentity пустым.
timeout (Необязательно) Время ожидания для HTTP-клиента, выполняющего вызов API. Он должен быть отформатирован как значение XSD dayTimeDuration (ограниченное подмножество значения длительности ISO 8601 ). Например, PT60S означает 60 секунд. Если значение не задано, значение по умолчанию равно 30 секундам. Время ожидания может составлять от 1 до 230 секунд.

Поддерживаемые типы векторных запросов

Векторизатор пользовательского веб-API поддерживает textи imageUrlimageBinaryвекторные запросы.

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

"vectorizers": [
    {
        "name": "my-custom-web-api-vectorizer",
        "kind": "customWebApi",
        "customWebApiParameters": {
            "uri": "https://contoso.embeddings.com",
            "httpMethod": "POST",
            "httpHeaders": {
                "api-key": "0000000000000000000000000000000000000"
            },
            "timeout": "PT60S",
            "authResourceId": null,
            "authIdentity": null
        }
    }
]

Note

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

В следующем примере показан ответ GET для предыдущего векторизатора:

{
    "name": "my-custom-web-api-vectorizer",
    "kind": "customWebApi",
    "customWebApiParameters": {
        "uri": "https://contoso.embeddings.com",
        "httpMethod": "POST",
        "httpHeaders": {
            "api-key": "<redacted>"
        },
        "timeout": "PT60S",
        "authResourceId": null,
        "authIdentity": null
    }
}


To update this vectorizer without changing the existing `api-key` value, use `<unchanged>`:

```json
"httpHeaders": {
    "api-key": "<unchanged>"
}

Структура полезных данных JSON

Требуемая структура полезных данных JSON для конечной точки, используемой с векторизатором пользовательского веб-API, совпадает со структурой, используемой навыком пользовательского веб-API. Дополнительные сведения см. в документации по навыку.

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

  • Векторизатор отправляет только одну запись в values массиве при выполнении запроса к конечной точке.

  • Векторизатор помещает данные, которые необходимо векторизовать, в определенный ключ объекта JSON в data полезной нагрузке запроса. Этот ключ имеет textзначение , imageUrlили imageBinaryв зависимости от типа запроса вектора.

  • Векторизатор ожидает, что результирующее встраивание будет находиться под ключом vector в объекте JSON data в теле ответа.

  • Векторизатор игнорирует ошибки или предупреждения, возвращаемые конечной точкой. Эти ошибки и предупреждения недоступны для отладки во время запроса.

  • Если был произведен запрос векторного запроса, полезная нагрузка запроса, отправляемая в конечную точку, приведена ниже.

    {
    "values": [
        {
            "recordId": "0",
            "data":
            {
                "imageBinary": {
                    "data": "<base 64 encoded image binary data>"
                }
            }
        }
    ]
}

См. также

  • Last updated on