Share via

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

  • Статья

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вы можете отключить проверку подлинности на основе ключей или проверку подлинности на основе ролей. Если отключить проверку подлинности на основе ролей, она применяется только к операциям плоскости данных. Операции уровня управления, такие как администрирование служб, всегда используют проверку подлинности на основе ролей. Дополнительные сведения см. в статье 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 или маркер носителя для подключений, прошедших проверку подлинности. При необходимости можно задать заголовок Принять HTTP. Если заголовок типа контента не задан, предполагается, что по умолчанию используется application/jsonзначение .

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