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

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

  • Статья

Внимание

Индексатор Azure Cosmos DB для Apache Gremlin в настоящее время находится в общедоступной предварительной версии в рамках дополнительных условий использования. Сейчас пакет SDK не поддерживается.

В этой статье вы узнаете, как настроить индексатор , который импортирует содержимое из Azure Cosmos DB для Apache Gremlin и делает его доступным для поиска в Службе искусственного интеллекта Azure.

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

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

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

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

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

Для этого вызова укажите предварительную версию REST API, чтобы создать источник данных, который подключается через Azure Cosmos DB для Apache Gremlin. Вы можете использовать 2021-04-01-preview или более поздней версии. Рекомендуется использовать последнюю предварительную версию API.

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

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

  2. Задайте для параметра type "cosmosdb" (обязательный).

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

  4. Задайте для коллекции значение container. Требуется свойство name и указывает идентификатор графа.

    Свойство query является необязательным. По умолчанию индексатор поиска ИИ Azure для Azure Cosmos DB для Apache Gremlin делает каждую вершину в графе документом в индексе. Ребра графа будут игнорироваться. По умолчанию используется g.V()запрос. Вы также можете создать запрос только для индексирования ребер. Чтобы индексировать ребра, задайте для запроса значение g.E().

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

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

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

Индексаторы могут подключаться к коллекции с помощью следующих подключений. Для подключений, предназначенных для Azure Cosmos DB для Apache Gremlin, обязательно включите ApiKind в строка подключения.

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

Полный доступ строка подключения
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>;ApiKind=MongoDb" }
Вы можете получить строка подключения на странице учетной записи 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];)" }
Для этого строка подключения не требуется ключ учетной записи, но необходимо настроить службу поиска для подключения с помощью управляемого удостоверения и создать назначение ролей, которое предоставляет разрешения роли чтения учетных записей Cosmos DB. Дополнительные сведения см. в статье "Настройка подключения индексатора к базе данных Azure Cosmos DB с помощью управляемого удостоверения ".

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

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

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

     POST https://[service name].search.windows.net/indexes?api-version=2024-05-01-preview
 Content-Type: application/json
 api-key: [Search service admin key]
 {
    "name": "mysearchindex",
    "fields": [
     {
         "name": "rid",
         "type": "Edm.String",
         "facetable": false,
         "filterable": false,
         "key": true,
         "retrievable": true,
         "searchable": true,
         "sortable": false,
         "analyzer": "standard.lucene",
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "synonymMaps": [],
         "fields": []
     },{
     }, {
         "name": "label",
         "type": "Edm.String",
         "searchable": true,
         "filterable": false,
         "retrievable": true,
         "sortable": false,
         "facetable": false,
         "key": false,
         "indexAnalyzer": null,
         "searchAnalyzer": null,
         "analyzer": "standard.lucene",
         "synonymMaps": []
    }]
  }

  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

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

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

    POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [search service admin key]
{
    "name" : "[my-cosmosdb-indexer]",
    "dataSourceName" : "[my-cosmosdb-gremlin-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. Чтобы управлять выполнением индексатора, запустите индексатор по запросу или поместите его в расписание.

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

Чтобы отслеживать состояние индексатора и журнал выполнения, отправьте запрос состояния индексатора:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-05-01-preview
  Content-Type: application/json  
  api-key: [admin key]

Ответ включает состояние и количество обработанных элементов. Он должен выглядеть примерно так:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

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

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

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

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

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

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

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

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

При удалении данных графа можно также удалить соответствующий документ из индекса поиска. Политика обнаружения удаления данных предназначена для эффективного определения удаленных элементов данных и удаления полного документа из индекса. Политика обнаружения удаления данных не предназначена для частичного удаления информации из документа. В настоящее время единственная поддерживаемая политика — 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"
}

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

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

{
    "name": "[my-cosmosdb-gremlin-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name];ApiKind=Gremlin"
    },
    "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"
    }
}

Даже если включить политику обнаружения удаления, удаление сложных (Edm.ComplexType) полей из индекса не поддерживается. Эта политика требует, чтобы столбец "активный" в базе данных Gremlin был целочисленным, строковым или логическим.

Сопоставление данных графа с полями в индексе поиска

Индексатор Azure Cosmos DB для Apache Gremlin автоматически сопоставляет несколько фрагментов данных графа:

  1. Индексатор будет сопоставляться _rid с полем rid в индексе, если он существует, и Base64 закодирует его.

  2. Индексатор сопоставит свойство _id с полем id в индексе, если оно существует.

  3. При запросе базы данных Azure Cosmos DB с помощью Azure Cosmos DB для Apache Gremlin вы можете заметить, что выходные данные JSON для каждого свойства имеют и id a value. Индексатор автоматически сопоставляет свойства value в поле в индексе поиска, которое имеет то же имя, что и свойство, если оно существует. В следующем примере значение 450 будет сопоставлено с полем pages в индексе поиска.

    {
        "id": "Cookbook",
        "label": "book",
        "type": "vertex",
        "properties": {
          "pages": [
            {
              "id": "48cf6285-a145-42c8-a0aa-d39079277b71",
              "value": "450"
            }
          ]
        }
    }

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

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

    [
      {
        "vertex": {
          "id": "Cookbook",
          "label": "book",
          "type": "vertex",
          "properties": {
            "pages": [
              {
                "id": "48cf6085-a211-42d8-a8ea-d38642987a71",
                "value": "450"
              }
            ],
          }
        },
        "written_by": [
          {
            "yearStarted": "2017"
          }
        ]
      }
    ]

Если вы хотите сопоставить значение pages в JSON-структуре выше с полем totalpages в индексе, можно добавить в определение индексатора следующее сопоставление поля выходных данных:

    ... // rest of indexer definition 
    "outputFieldMappings": [
        {
          "sourceFieldName": "/document/vertex/pages",
          "targetFieldName": "totalpages"
        }
    ]

Обратите внимание, что сопоставление полей выходных данных начинается со строки /document и не содержит ссылку на ключ свойств в JSON-структуре. Это связано с тем, что индексатор помещает каждый документ в узел /document при обработке данных графа; индексатор также автоматически позволяет ссылаться на значение pages, просто указав ссылку на pages вместо того, чтобы ссылаться на первый объект в массиве pages.

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