Справочник по AZURE AI Поиск REST API

  • Статья

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

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

Доступ к операциям уровня управления осуществляется через отдельный REST API управления.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вы можете отключить проверку подлинности на основе ключей или проверку подлинности на основе ролей. Если отключить проверку подлинности на основе ролей, некоторые встроенные роли по-прежнему будут иметь доступ. Дополнительные сведения см. в статье проверка подлинности Microsoft Entra ID и управление доступом на основе ролей для azure AI Поиск.

Вызов API

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

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

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

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

См. также раздел