Поделиться через

Справочник по REST API поиска ИИ Azure

  • Статья

поиска ИИ Azure (ранее известного как Когнитивного поиска Azure) — это полностью управляемая облачная служба поиска, которая предоставляет доступ к содержимому, принадлежащему пользователю.

REST API плоскости данных используются для индексирования и запросов рабочих процессов и описаны в этом разделе.

Операции уровня управления для администрирования служб рассматриваются в отдельных REST API управления.

Документация по API с версиями

Документация ПО REST API теперь версии. При открытии справочной страницы API селектор версий отображается над оглавлением. Убедитесь, что ссылка на API находится в папке Reference > Data Plane.

снимок экрана селектора версий.

Основные понятия

Поиск ИИ Azure содержит основные понятияслужб поиска , индексов, документов, индексаторов, источников данных, наборов навыкови сопоставления синонимов.

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

В целом можно создать следующие объекты в службе поиска:

Объектов Описание
Источники данных Подключение к источнику данных, используемое индексатором для извлечения и обновления документов для индексирования. Источники данных имеют type. Вы можете использовать предоставленные Корпорацией Майкрософт подключения для Azure или соединителей партнеров. Полный список см. в коллекции источников данных .
Документы Концептуально документ является сущностью в индексе. Сопоставление этой концепции с более знакомыми эквивалентами базы данных: индекс поиска соответствует таблице, а документы примерно эквивалентны строкам в таблице. Документы существуют только в индексе и извлекаются только через запросы, предназначенные для коллекции документов (/docs) индекса. Все операции, выполняемые в коллекции, такие как отправка, слияние, удаление или запрос документов, выполняются в контексте одного индекса, поэтому операции форматирования URL-адресов всегда включают /indexes/[index name]/docs для заданного имени индекса.
Индексы Индекс хранится в службе поиска и заполняется документами JSON, индексируемыми и маркеризованными для получения информации. Коллекция полей индекса определяет структуру документа поиска. Поля имеют имя, типы данных и атрибуты, определяющие использование. Например, searchable поля используются в полнотекстовом поиске и таким образом маркеризированы во время индексирования. Индекс также определяет другие конструкции, такие как профили оценки для настройки релевантности, предложения, семантические конфигурации и пользовательские анализаторы.
Индексаторы Индексаторы обеспечивают автоматизацию индексирования. Индексатор подключается к источнику данных, считывает данные и передает его поисковой системе для индексирования в целевой индекс поиска. Индексаторы считывают данные из внешнего источника с помощью сведений о подключении в источнике данных и сериализируют входящие данные в документы поиска JSON. Помимо источника данных индексатор также требует индексатора. Индекс задает поля и атрибуты документов поиска.
Наборы навыков Набор навыков добавляет внешние шаги обработки для выполнения индексатора и используется для применения моделей искусственного интеллекта или глубокого обучения для анализа или преобразования содержимого для повышения удобства поиска в индексе. Содержимое набора навыков — это один или несколько навыков, которые могут быть встроенных навыков, созданных корпорацией Майкрософт, пользовательскими навыками или сочетанием обоих навыков. Встроенные навыки существуют для анализа изображений, включая OCR и обработку естественного языка. Другие примеры встроенных навыков включают распознавание сущностей, извлечение ключевых фраз, фрагментирование текста на логические страницы, среди прочего. Набор навыков — это высокоуровневый автономный объект, который существует на уровне, эквивалентный индексам, индексаторам и источникам данных, но он работает только в процессе обработки индексатора. Как высокоуровневый объект можно создать набор навыков один раз, а затем ссылаться на него в нескольких индексаторов.
Карты синонимов Сопоставление синонимов — это объект уровня обслуживания, содержащий определяемые пользователем синонимы. Этот объект поддерживается независимо от индексов поиска. После отправки можно указать любое поле, доступные для поиска, на карту синонимов (по одному на поле).

Разрешения и управление доступом

Вы можете использовать проверку подлинности на основе ключей или на основе ролей с помощью идентификатора Microsoft Entra.

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

  • проверки подлинности и управления доступом на основе ролей Microsoft Entra ID требует наличия установленного клиента в Идентификаторе Microsoft Entra с субъектами безопасности и назначениями ролей. Члены следующих ролей имеют доступ к плоскости данных. Можно создать пользовательские роли, если встроенные роли недостаточно.

    Роль Доступ
    Участник службы поиска Доступ к объектам, но доступ к содержимому индекса отсутствует. Эта роль создает индекс поиска и другие объекты верхнего уровня, но не может запрашивать индекс поиска или добавлять, удалять или обновлять документы в индексе поиска. Эта роль предназначена для разработчиков, создающих, обновляющих и удаляющих определения объектов. Это также для администраторов, которым необходимо управлять объектами, но без возможности просматривать или получать доступ к данным объектов.
    Участник индекса данных поиска Доступ на чтение и запись к содержимому индекса. Эта роль предназначена для разработчиков или владельцев индексов, которые должны импортировать, обновить или запросить коллекцию документов индекса.
    Средство чтения индексов данных поиска Доступ на чтение к содержимому индекса. Эта роль предназначена для приложений и пользователей, выполняющих запросы.

При использовании ролей в подключении клиентское приложение представляет маркер носителя в заголовке авторизации. Дополнительные сведения о настройке см. в авторизации доступа к поисковому приложению с помощью идентификатора Microsoft Entra ID.

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

Вызов API

API, описанные в этом разделе, предоставляют доступ к операциям с данными поиска, такими как создание индекса и заполнение, отправка документов и запросы. При вызове API следует учитывать следующие моменты:

  • Запросы должны выдаваться по протоколу HTTPS (по умолчанию — порт 443).

  • URI запроса должны включать версию API. Значение должно быть задано в поддерживаемую версию, отформатированную, как показано в этом примере: GET https://[search service name].search.windows.net/indexes?api-version=2023-11-01

  • заголовки запросов должны включать ключ API или маркер носителя для прошедших проверку подлинности подключений. При необходимости можно задать заголовок Accept HTTP. Если заголовок типа контента не задан, предполагается, что значение по умолчанию application/json.

См. также