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

Индексирование данных из Azure Cosmos DB для NoSQL для запросов в поиске ИИ Azure

  • Статья

Из этой статьи вы узнаете, как настроить индексатор , который импортирует содержимое из Azure Cosmos DB для NoSQL и делает его доступным для поиска в Azure AI Search.

В этой статье описано , как создать индексатор с информацией, относяющейся к Cosmos DB. В нем используются портал Azure и REST API для демонстрации трех частей рабочего процесса, общего для всех индексаторов: создание источника данных, создание индекса, создание индексатора. Извлечение данных происходит при отправке запроса create Indexer.

Так как терминология может быть запутана, стоит отметить, что индексирование Azure Cosmos DB и индексирование поиска ИИ Azure отличаются операциями. Индексирование в службе поиска ИИ Azure создает и загружает индекс поиска в службе поиска.

Необходимые компоненты

Для работы с примерами, приведенными в этой статье, вам потребуется портал Azure или клиент REST. Если вы используете портал Azure, убедитесь, что доступ ко всем общедоступным сетям включен. Другие подходы к созданию индексатора Cosmos DB включают пакеты SDK Azure.

Попробуйте использовать примеры данных

Используйте эти инструкции для создания контейнера и базы данных в Cosmos DB для тестирования.

  1. Скачайте HotelsData_toCosmosDB.JSON из GitHub, чтобы создать контейнер в Cosmos DB, содержащий подмножество примера набора данных отелей.

  2. Войдите в портал Azure и создайте учетную запись, базу данных и контейнер в Cosmos DB.

  3. В Cosmos DB выберите Обозреватель данных для нового контейнера, укажите следующие значения.

    Свойство Значение
    База данных создание
    Идентификатор базы данных hotelsdb
    Разделить пропускную способность между контейнерами Не выбирайте
    Идентификатор контейнера Отели
    Ключ раздела /HotelId
    Пропускная способность контейнера (автомасштабирование) Автомасштабирование
    Максимальное количество единиц запросов в контейнере 1000

  4. В обозревателе данных разверните hotelsdb и *hotels, а затем выберите "Элементы".

  5. Выберите "Отправить элемент" и выберите HotelsData_toCosmosDB.JSON файл, скачанный с GitHub.

  6. Щелкните правой кнопкой мыши "Элементы" и выберите "Создать SQL-запрос". По умолчанию используется SELECT * FROM cзапрос.

  7. Выберите "Выполнить запрос", чтобы запустить запрос и просмотреть результаты. У вас должно быть 50 документов отеля.

Теперь, когда у вас есть контейнер, вы можете использовать портал Azure, клиент REST или пакет SDK Azure для индексирования данных.

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

Использование портала Azure

С помощью мастера импорта данных или мастера импорта и векторизации данных можно автоматизировать индексирование из таблицы базы данных SQL или представления. Конфигурация источника данных аналогична обоим мастерам.

  1. Запустите мастер.

  2. При подключении к данным выберите или убедитесь, что тип источника данных — Azure Cosmos DB или учетная запись NoSQL.

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

  3. Укажите имя базы данных и коллекцию. Запрос необязателен. Это полезно, если у вас есть иерархические данные, и вы хотите импортировать определенный срез.

  4. Укажите метод проверки подлинности, управляемое удостоверение или встроенный ключ API. Если подключение к управляемому удостоверению не указано, портал использует ключ.

    Если вы настраиваете поиск azure AI для использования управляемого удостоверения и создаете назначение ролей в Cosmos DB, которое предоставляет средству чтения учетных записей Cosmos DB и встроенных разрешений средства чтения данных Cosmos DB для удостоверения, индексатор может подключаться к Cosmos DB с помощью идентификатора и ролей Microsoft Entra.

  5. В мастере импорта и векторизации данных можно указать параметры отслеживания изменений и удаления.

    Обнаружение изменений поддерживается по умолчанию с помощью _ts поля (метка времени). При отправке содержимого с помощью подхода, описанного в разделе Try with sample data, коллекция создается с _ts помощью поля.

    Для обнаружения удаления требуется, чтобы у вас было предварительно существующее поле верхнего уровня в коллекции, которое можно использовать в качестве флага обратимого удаления. Это должно быть логическое поле (можно назвать его IsDeleted). Укажите true в качестве значения обратимого удаления. В индексе поиска добавьте соответствующее поле поиска с именем IsDeleted , чтобы получить и отфильтровать его.

  6. Выполните оставшиеся действия, чтобы завершить работу мастера:

использованию REST API

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

Определение источника данных

Определение источника данных указывает данные для индексирования, учетных данных и политик для выявления изменений в данных. Источник данных — это независимый ресурс, который может использоваться несколькими индексаторами.

  1. Создайте или обновите источник данных, чтобы задать его определение:

    POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
      "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "container": {
      "name": "[my-cosmos-db-collection]",
      "query": null
    },
    "dataChangeDetectionPolicy": {
      "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
    "  highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": null,
    "encryptionKey": null,
    "identity": null
}

  2. Задайте для параметра type "cosmosdb" (обязательный). Если вы используете более старый API поиска версии 2017-11-11, используется "documentdb"синтаксис типа. В противном случае для 2019-05-06 и более поздних версий используйте "cosmosdb".

  3. Задайте для параметра "Учетные данные" значение строка подключения. В следующем разделе описаны поддерживаемые форматы.

  4. Задайте для коллекции значение container. Свойство name является обязательным и указывает идентификатор коллекции баз данных для индексирования. Свойство query является необязательным. Используйте его для выравнивания произвольного документа JSON в неструктурированной схеме, которую может индексировать поиск ИИ Azure.

  5. Задайте значение dataChangeDetectionPolicy, если данные являются переменными, и индексатор будет получать только новые и обновленные элементы при последующих запусках.

  6. Установите параметр dataDeletionDetectionPolicy, если вы хотите удалить документы поиска из индекса поиска при удалении исходного элемента.

Поддерживаемые учетные данные и строка подключения

Индексаторы могут подключаться к коллекции с помощью следующих подключений.

Избегайте номеров портов в URL-адресе конечной точки. Если включить номер порта, подключение завершается ошибкой.

Полный доступ строка подключения
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>" }`
Вы можете получить строка подключения на странице учетной записи Azure Cosmos DB в портал Azure, выбрав "Ключи" в области навигации слева. Не забудьте выбрать полную строка подключения и не только ключ.
Управляемое удостоверение строка подключения
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=[identity-auth-type])" }
Для этого строка подключения не требуется ключ учетной записи, но у вас должна быть служба поиска, которая может подключаться с помощью управляемого удостоверения. Для подключений, предназначенных для API SQL, можно исключить ApiKind из строка подключения. Дополнительные сведения см. в ApiKindIdentityAuthType статье "Настройка подключения индексатора к базе данных Azure Cosmos DB с помощью управляемого удостоверения".

Использование запросов для формирования индексированных данных

В свойстве query в разделе "контейнер" можно указать SQL-запрос для плоских вложенных свойств или массивов, свойств проекта JSON и отфильтровать данные для индексирования.

Пример документа:

    {
        "userId": 10001,
        "contact": {
            "firstName": "andy",
            "lastName": "hoh"
        },
        "company": "microsoft",
        "tags": ["azure", "cosmosdb", "search"]
    }

Запрос на фильтрацию:

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

Преобразование запросов:

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Запрос на проектирование:

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Массив преобразованных запросов:

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

Неподдерживаемые запросы (DISTINCT и GROUP BY)

Запросы, использующие ключевое слово DISTINCT или предложение GROUP BY, не поддерживаются. Поиск ИИ Azure использует разбиение на страницы SQL-запроса, чтобы полностью перечислить результаты запроса. Ни ключевое слово DISTINCT, ни предложения GROUP BY не совместимы с маркерами продолжения, используемыми для разбивки результатов.

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

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

Хотя Azure Cosmos DB имеет обходное решение для поддержки разбиения запросов SQL с ключевым словом DISTINCT с помощью предложения ORDER BY, оно несовместимо с поиском ИИ Azure. Запрос возвращает одно значение JSON, в то время как служба "Поиск ИИ Azure" ожидает объект JSON.

-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

Добавление полей поиска в индекс

В индексе поиска добавьте поля, чтобы принять исходные документы JSON или выходные данные пользовательской проекции запроса. Убедитесь, что схема индекса поиска совместима с исходными данными. Для содержимого в Azure Cosmos DB схема индекса поиска должна соответствовать элементам Azure Cosmos DB в источнике данных.

  1. Создайте или обновите индекс , чтобы определить поля поиска, в которые хранятся данные:

    POST https://[service name].search.windows.net/indexes?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]
{
    "name": "mysearchindex",
    "fields": [{
        "name": "rid",
        "type": "Edm.String",
        "key": true,
        "searchable": false
    }, 
    {
        "name": "description",
        "type": "Edm.String",
        "filterable": false,
        "searchable": true,
        "sortable": false,
        "facetable": false,
        "suggestions": true
    }
  ]
}

  2. Создайте поле ключа документа ("key": true"). Для секционированных коллекций ключ документа по умолчанию — это свойство Azure Cosmos DB _rid , в которое служба "Поиск ИИ Azure" автоматически переименовывается rid , так как имена полей не могут начинаться с символа подчеркивания. Кроме того, значения Azure Cosmos DB _rid содержат символы, недопустимые в ключах поиска ИИ Azure. Поэтому значения _rid представлены в кодировке Base64.

  3. Создайте дополнительные поля для более доступных для поиска содержимого. Дополнительные сведения см. в статье "Создание индекса ".

Сопоставление типов данных

Типы данных JSON Типы полей поиска ИИ Azure
Bool Edm.Boolean, Edm.String
Числа, которые выглядят как целые числа Edm.Int32, Edm.Int64, Edm.String
Числа, которые выглядят как числа с плавающей запятой Edm.Double, Edm.String
Строка Edm.String
Массивы примитивных типов, таких как ["a", "b", "c"] Collection(Edm.String)
Строки, которые выглядят как даты Edm.DateTimeOffset, Edm.String
Объекты GeoJSON, такие как { type: Point, "координаты": [long, lat] } Edm.GeographyPoint
Другие объекты JSON Н/П

Настройка и запуск индексатора Azure Cosmos DB для NoSQL

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

  1. Создайте или обновите индексатор , предоставив ему имя и ссылаясь на источник данных и целевой индекс:

    POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-ds]",
    "targetIndexName" : "[my-search-index]",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": 0,
        "maxFailedItemsPerBatch": 0,
        "base64EncodeKeys": false,
        "configuration": {}
        },
    "fieldMappings": [],
    "encryptionKey": null
}

  2. Укажите сопоставления полей, если существуют различия в имени или типе поля, или если в индексе поиска требуется несколько версий исходного поля.

  3. Дополнительные сведения о других свойствах см. в статье "Создание индексатора ".

Индексатор запускается автоматически при его создании. Это можно предотвратить, задав для параметра "Отключено" значение true. Чтобы управлять выполнением индексатора, запустите индексатор по запросу или поместите его в расписание.

Проверка состояния индексатора

Чтобы отслеживать состояние индексатора и журнал выполнения, проверьте журнал выполнения индексатора в портал Azure или отправьте REST APIrequest состояния индексатора.

  1. На странице службы поиска откройте индексаторы управления>поиском.

  2. Выберите индексатор для доступа к конфигурации и журналу выполнения.

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

Журнал выполнения содержит до 50 последних завершенных выполнений, которые сортируются в обратном хронологическом порядке, чтобы последнее выполнение было первым.

Индексирование новых и измененных документов

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

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

Для индексаторов Azure Cosmos DB только поддерживаемая политика — это HighWaterMarkChangeDetectionPolicy _ts свойство (метка времени), предоставленное Azure Cosmos DB.

В следующем примере показано определение источника данных с политикой обнаружения изменений:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"  highWaterMarkColumnName": "_ts"
},

Примечание.

При назначении null значения полю в Azure Cosmos DB индексатор поиска ИИ не может различаться null и отсутствующее значение поля. Таким образом, если поле в индексе пусто, оно не будет заменено null значением, даже если это изменение было сделано в вашей базе данных.

Добавочное индексирование и пользовательские запросы

Если вы используете пользовательский запрос для получения документов, убедитесь, что запрос упорядочивает результаты по столбцу _ts . Это позволяет периодически проверять, используется ли поиск ИИ Azure для обеспечения добавочного прогресса в присутствии сбоев.

В некоторых случаях, даже если запрос содержит ORDER BY [collection alias]._ts предложение, поиск ИИ Azure может не определить порядок _tsзапроса. Вы можете сообщить Службе поиска ИИ Azure, что результаты упорядочены, задав assumeOrderByHighWaterMarkColumn свойство конфигурации.

Чтобы указать это указание, создайте или обновите определение индексатора следующим образом:

{
    ... other indexer definition properties
    "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
}

Индексация удаленных документов

Строки, удаляемые из исходной коллекции, вероятно, также следует удалить из индекса поиска. Политика обнаружения удаления данных предназначена для эффективного определения удаленных элементов данных. В настоящее время единственная поддерживаемая политика — Soft Delete это политика (удаление помечается флагом определенного типа), которое указывается в определении источника данных следующим образом:

"dataDeletionDetectionPolicy"": {
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

Если вы используете пользовательский запрос, убедитесь, что свойство, на которое softDeleteColumnName ссылается ссылка, проецируется запросом.

Должно softDeleteColumnName быть поле верхнего уровня в индексе. Использование вложенных полей в сложных типах данных, так как softDeleteColumnName оно не поддерживается.

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

POST https://[service name].search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

Использование .NET

Для доступа к данным через протокол API SQL можно использовать пакет SDK для .NET для автоматизации с помощью индексаторов. Мы рекомендуем ознакомиться с предыдущими разделами REST API, чтобы узнать о понятиях, рабочих процессах и требованиях. Затем можно обратиться к следующей справочной документации по API .NET, чтобы реализовать индексатор JSON в управляемом коде:

Следующие шаги

Теперь вы можете управлять запуском индексатора, отслеживания состояния или расписания выполнения индексатора. Следующие статьи относятся к индексаторам, которые извлекает содержимое из Azure Cosmos DB: