Сопоставления полей и преобразования с помощью индексаторов поиска ИИ Azure

Статья
09/01/2024

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

Когда необходимо задать сопоставление полей

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

Сопоставления полей также можно использовать для преобразования данных с легким весом, таких как кодировка или декодирование, с помощью функций сопоставления. Если требуется больше обработки, рассмотрите возможность Фабрика данных Azure для преодоления разрыва.

Сопоставления полей применяются к:

Физические структуры данных на обеих сторонах пути к данным. Логические структуры данных, созданные навыками, находятся только в памяти. Используйте outputFieldMappings для сопоставления узлов в памяти с полями вывода в индексе поиска.
Только индексы родительского поиска ИИ. Дополнительные индексы с дочерними документами или блоками см. в сценариях расширенного сопоставления полей.
Только поля поиска верхнего уровня, где targetFieldName это простое поле или коллекция. Целевое поле не может быть сложным типом.

Поддерживаемые сценарии

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

Вариант использования	Description
Несоответствие имен	Предположим, что источник данных имеет поле с именем `_city`. Учитывая, что поиск по искусственному интеллекту Azure не разрешает имена полей, начинающиеся с подчеркивания, сопоставление полей позволяет эффективно сопоставлять "_city" с "городом". Если требования к индексированию включают получение содержимого из нескольких источников данных, где имена полей зависят от источников, можно использовать сопоставление полей для уточнения пути.
Несоответствие типов	Предположим, что нужно, чтобы исходное целочисленное поле было типом `Edm.String` , чтобы он был доступен для поиска в индексе поиска. Так как типы отличаются, необходимо определить сопоставление полей, чтобы путь к данным был успешно выполнен. Обратите внимание, что поиск по искусственному интеллекту Azure имеет меньший набор поддерживаемых типов данных, чем многие источники данных. При импорте данных SQL сопоставление полей позволяет сопоставить нужный тип данных SQL в индексе поиска.
Пути данных "один ко многим"	Вы можете заполнить несколько полей в индексе содержимым из одного исходного поля. Например, может потребоваться применить различные анализаторы к каждому полю для поддержки различных вариантов использования в клиентском приложении.
Кодировка и декодирование	Функции сопоставления можно применить для поддержки кодировки Base64 или декодирования данных во время индексирования.
Разделение строк или переадресовка массивов в коллекции	Можно применить функции сопоставления для разделения строки, включающей разделитель, или отправить массив JSON в поле поиска типа `Collection(Edm.String)`.

Примечание.

Если сопоставления полей отсутствуют, индексаторы предполагают, что поля источника данных должны быть сопоставлены с полями индекса с тем же именем. Добавление сопоставления полей переопределяет сопоставления полей по умолчанию для исходного и целевого полей. Некоторые индексаторы, такие как индексатор хранилища BLOB-объектов, автоматически добавляют сопоставления полей по умолчанию для поля ключа индекса.

Сложные поля не поддерживаются в сопоставлении полей. Исходная структура (вложенные или иерархические структуры) должна точно соответствовать сложному типу в индексе, чтобы сопоставления по умолчанию работали. Дополнительные сведения см. в руководстве по индексу вложенных BLOB-объектов JSON, например. Если вы получите ошибку, аналогичную "Field mapping specifies target field 'Address/city' that doesn't exist in the index"ошибке, это связано с тем, что сопоставления целевых полей не могут быть сложным типом.

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

Определение сопоставления полей

В этом разделе описаны действия по настройке сопоставлений полей.

REST API;
Пакет SDK для .NET (C#)

Используйте create Indexer или Create or Update Indexer или эквивалентный метод в пакете SDK Azure. Ниже приведен пример определения индексатора.

{
   "name": "myindexer",
   "description": null,
   "dataSourceName": "mydatasource",
   "targetIndexName": "myindex",
   "schedule": { },
   "parameters": { },
   "fieldMappings": [],
   "disabled": false,
   "encryptionKey": { }
 }

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

"fieldMappings": [
  {
    "sourceFieldName": "_city",
    "targetFieldName": "city",
    "mappingFunction": null
  }
]

Свойство	Description
sourceFieldName	Обязательный. Представляет поле в источнике данных.
targetFieldName	Необязательно. Представляет поле в индексе поиска. Если опущено, `sourceFieldName` значение предполагается для целевого объекта. Целевые поля должны быть простыми полями верхнего уровня или коллекциями. Это не может быть сложный тип или коллекция. При обработке проблемы с типом данных в определении индекса указывается тип данных поля. Сопоставление полей просто должно иметь имя поля.
сопоставлениеFunction	Необязательно. Состоит из предопределенных функций , которые преобразуют данные.

Пример: несоответствие имен или типов

Явное сопоставление полей устанавливает путь к данным для случаев, когда имя и тип не совпадают.

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

PUT https://[service name].search.windows.net/indexers/myindexer?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
{
    "dataSourceName" : "mydatasource",
    "targetIndexName" : "myindex",
    "fieldMappings" : [ { "sourceFieldName" : "_city", "targetFieldName" : "city" } ]
}

Пример: пути к одному ко многим или вилку данных

В этом примере сопоставляется одно исходное поле с несколькими целевыми полями (сопоставления "один ко многим"). Поле можно "вилировать", копируя одно и то же содержимое исходного поля в два разных поля индекса, которые будут анализироваться или атрибутироваться по-разному в индексе.


"fieldMappings" : [
    { "sourceFieldName" : "text", "targetFieldName" : "textStandardEnglishAnalyzer" },
    { "sourceFieldName" : "text", "targetFieldName" : "textSoundexAnalyzer" }
]

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

В пакете SDK Azure для .NET используйте класс FieldMapping , предоставляющий SourceFieldName и TargetFieldName свойства и необязательную MappingFunction ссылку.

Укажите сопоставления полей при создании индексатора или более поздней версии путем непосредственного задания SearchIndexer.FieldMappings. В следующем примере на языке C# сопоставления полей задаются при построении индексатора.

var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
    Description = "SQL data indexer",
    Schedule = schedule,
    Parameters = parameters,
    FieldMappings =
    {
        new FieldMapping("_hotelId") {TargetFieldName = "HotelId", FieldMappingFunction.Base64Encode()},
        new FieldMapping("Amenities") {TargetFieldName = "Tags"}
    }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

Сопоставление функций и примеров

Функция сопоставления полей преобразует содержимое поля до его сохранения в индексе. В настоящее время поддерживаются следующие функции сопоставления:

base64Encode
base64Decode
extractTokenAtPosition
jsonArrayToStringCollection
urlEncode
urlDecode

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

Функция base64Encode

Выполняет безопасное кодирование строки входных данных в Base64. Входные данные должны быть в кодировке UTF-8.

Пример: базовая кодировка ключа документа

Только безопасные URL-адреса символы могут отображаться в ключе документа поиска ИИ Azure (чтобы вы могли обращаться к документу с помощью API подстановки). Если исходное поле для ключа содержит небезопасные символы URL-адреса, например - и \используйте base64Encode функцию для преобразования его во время индексирования.

В следующем примере указывается функция base64Encode для metadata_storage_name обработки неподдерживаемых символов.

PUT /indexers?api-version=2024-07-01
{
  "dataSourceName" : "my-blob-datasource ",
  "targetIndexName" : "my-search-index",
  "fieldMappings" : [
    { 
        "sourceFieldName" : "metadata_storage_name", 
        "targetFieldName" : "key", 
        "mappingFunction" : { 
            "name" : "base64Encode",
            "parameters" : { "useHttpServerUtilityUrlTokenEncode" : false }
        } 
    }
  ]
}

Ключ документа (как до, так и после преобразования) не может превышать 1024 символов. При получении закодированного ключа во время поиска используйте base64Decode функцию, чтобы получить исходное значение ключа и использовать ее для извлечения исходного документа.

Пример. Создание поля в кодировке base "searchable"

Иногда требуется использовать закодированную версию поля, например metadata_storage_path ключа, но также требуется незакодированная версия для полнотекстового поиска. Для поддержки обоих сценариев можно сопоставить metadata_storage_path два поля: один для ключа (закодированный), а второй для поля пути, который можно предположить, является атрибутом searchable схемы индекса.

PUT /indexers/blob-indexer?api-version=2024-07-01
{
    "dataSourceName" : " blob-datasource ",
    "targetIndexName" : "my-target-index",
    "schedule" : { "interval" : "PT2H" },
    "fieldMappings" : [
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "key", "mappingFunction" : { "name" : "base64Encode" } },
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "path" }
      ]
}

Пример: сохранение исходных значений

Индексатор хранилища BLOB-объектов автоматически добавляет сопоставление полей из metadata_storage_path, URI большого двоичного объекта, в поле ключа индекса, если сопоставление полей не указано. Это значение закодировано в кодировке Base64, поэтому оно безопасно использовать в качестве ключа документа поиска ИИ Azure. В следующем примере показано, как одновременно сопоставлять безопасную для URL-адреса версию metadata_storage_path, закодированную с помощью Base64, с полем index_key и сохранить исходное значение в поле metadata_storage_path.

"fieldMappings": [
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "metadata_storage_path"
  },
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "index_key",
    "mappingFunction": {
       "name": "base64Encode"
    }
  }
]

Если свойство parameters для функции сопоставления не указано, по умолчанию используется значение {"useHttpServerUtilityUrlTokenEncode" : true}.

Служба "Поиск ИИ Azure" поддерживает два разных кодировки Base64. При кодировании и декодировании одного и того же поля следует использовать одни и те же параметры. Чтобы решить, какие параметры использовать, см. дополнительные сведения в разделе о вариантах кодировки Base64.

Функция base64Decode

Выполняет декодирование входной строки в Base64. Предполагается, что входные данные представляют собой безопасную для URL-адреса строку в кодировке Base64.

Пример. декодирование метаданных BLOB-объектов или URL-адресов

Исходные данные могут содержать строки в кодировке Base64, например строки метаданных BLOB-объектов или URL-адреса веб-узлов, которые требуется включить в поиск в виде обычного текста. Можно использовать функцию base64Decode, чтобы при заполнении индекса поиска снова превратить закодированные данные в обычные строки.

"fieldMappings" : [
  {
    "sourceFieldName" : "Base64EncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : { 
      "name" : "base64Decode", 
      "parameters" : { "useHttpServerUtilityUrlTokenDecode" : false }
    }
  }
]

Если свойство parameters не указано, по умолчанию используется значение {"useHttpServerUtilityUrlTokenEncode" : true}.

Варианты кодировки Base64

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

Если параметрам useHttpServerUtilityUrlTokenEncode или useHttpServerUtilityUrlTokenDecode для кодирования и декодирования соответственно присвоено значение true, то base64Encode ведет себя как HttpServerUtility.UrlTokenEncode, а base64Decode — как HttpServerUtility.UrlTokenDecode.

Предупреждение

Если для получения значений ключей используется base64Encode, для параметра useHttpServerUtilityUrlTokenEncode необходимо установить значение true. Для значений ключа можно использовать только безопасную для URL-адреса кодировку Base64. См . правила именования для полного набора ограничений на символы в ключевых значениях.

Библиотеки .NET в поиске ИИ Azure предполагают полную платформа .NET Framework, которая обеспечивает встроенную кодировку. useHttpServerUtilityUrlTokenDecode Эти встроенные useHttpServerUtilityUrlTokenEncode функции применяются и параметры. Если вы используете .NET Core или другую платформу, рекомендуется задать эти параметры и false вызвать кодирование и декодирование функций платформы напрямую.

В следующей таблице сравниваются различные кодировки Base64 строки 00>00?00. Чтобы определить необходимую обработку (если есть) для функций base64, примените функцию кодирования библиотеки к строке 00>00?00 и сравните выходные данные с ожидаемыми выходными данными MDA-MDA_MDA.

Кодировка	Выводные данные кодировки Base64	Дополнительная обработка после кодирования библиотеки	Дополнительная обработка перед декодированием библиотеки
Base64 с заполнением	`MDA+MDA/MDA=`	Использовать безопасные знаки URL-адреса и удалить заполнение	Использовать стандартные знаки Base64 и добавить заполнение
Base64 без заполнения	`MDA+MDA/MDA`	Использовать безопасные знаки URL-адреса	Использовать стандартные знаки Base64
Безопасное кодирование строки вводных данных в Base64 с заполнением	`MDA-MDA_MDA=`	Удаление заполнения	Добавление заполнения
Безопасное кодирование строки вводных данных в Base64 без заполнения	`MDA-MDA_MDA`	нет	нет

Функция extractTokenAtPosition

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

Эта функция использует следующие параметры:

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

Например, если при входных данных Jane Doe параметр delimiter имеет значение " " (пробел), а параметр position — значение 0, то результатом будет Jane; если параметр position имеет значение 1, то результатом будет Doe. Если позиция ссылается на несуществующий токен, выдается ошибка.

Пример: извлечение имени

Источник данных содержит поле PersonName, и вам нужно индексировать его как два отдельных поля — FirstName и LastName. Эта функция позволяет разбить входные данные, используя пробел как разделитель.

"fieldMappings" : [
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "FirstName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 0 } }
  },
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "LastName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 1 } }
  }]

Функция jsonArrayToStringCollection

Преобразует строку, отформатированную как массив строк JSON, в массив строк, который можно использовать для заполнения поля Collection(Edm.String) в индексе.

Например, если исходной строкой является ["red", "white", "blue"], то целевое поле типа Collection(Edm.String) будет заполнено следующими тремя значениями: red, white и blue. Для входных значений, которые не могут быть проанализированы как массивы строк JSON, возвращается ошибка.

Пример: заполнение коллекции реляционными данными

База данных SQL Azure не имеет встроенный тип данных, который естественно сопоставляется с полями Collection(Edm.String) в поиске ИИ Azure. Чтобы заполнить поля сбора строк, можно предварительно обработать исходные данные в виде массива строк JSON, а затем использовать функцию jsonArrayToStringCollection сопоставления.

"fieldMappings" : [
  {
    "sourceFieldName" : "tags", 
    "mappingFunction" : { "name" : "jsonArrayToStringCollection" }
  }]

Функция urlEncode

Эту функцию можно использовать для кодирования строки, чтобы она была безопасной для URL-адреса. При использовании со строкой, содержащей символы, которые не разрешены в URL-адресе, эта функция преобразует эти символы "небезопасные" в эквиваленты сущностей символов. Эта функция использует формат кодировки UTF-8.

Пример: поиск ключа документа

Функцию urlEncode можно использовать в качестве альтернативы функции base64Encode, если требуется преобразовать только небезопасные символы URL-адреса и оставить другие символы как есть.

Например, если исходной строкой является <hello>, то в целевое поле типа (Edm.String) будет внесено значение %3chello%3e

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

"fieldMappings" : [
  {
    "sourceFieldName" : "SourceKey",
    "targetFieldName" : "IndexKey",
    "mappingFunction" : {
      "name" : "urlEncode"
    }
  }
]

Функция urlDecode

Эта функция преобразует строку в кодировке URL в декодированную строку, используя формат кодирования UTF-8.

Пример. декодирование метаданных BLOB-объекта

Некоторые клиенты службы хранилища Azure автоматически кодируют метаданные BLOB-объектов, если они содержат символы, отличные от ASCII. Однако если вы хотите сделать такие метаданные доступными для поиска (в виде обычного текста), можно использовать функцию urlDecode, чтобы снова преобразовать закодированные данные в обычные строки при заполнении индекса поиска.

"fieldMappings" : [
  {
    "sourceFieldName" : "UrlEncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : {
      "name" : "urlDecode"
    }
  }
]

Функция fixedLengthEncode

Эта функция преобразует строку любой длины в строку фиксированной длины.

Пример: сопоставление слишком длинных ключей документов

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


"fieldMappings" : [
 {
   "sourceFieldName" : "metadata_storage_path",
   "targetFieldName" : "your key field",
   "mappingFunction" : {
     "name" : "fixedLengthEncode"
   }
 }
]

Функция toJson

Эта функция преобразует строку в форматированный объект JSON. Это можно использовать для сценариев, когда источник данных, например SQL Azure, не поддерживает составные или иерархические типы данных, а затем сопоставляет его со сложными полями.

Пример. Сопоставление текстового содержимого со сложным полем

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

{
    "id": "5",
    "info": {
        "name": "Jane",
        "surname": "Smith",
        "skills": [
            "SQL",
            "C#",
            "Azure"
        ],
        "dob": "2005-11-04T12:00:00"
    }
}

Его можно достичь с помощью toJson функции сопоставления в столбце строки JSON в строке SQL, которая выглядит следующим образом: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}

Сопоставление полей должно быть указано, как показано ниже.


"fieldMappings" : [
  {
    "sourceFieldName" : "content",
    "targetFieldName" : "complexField",
    "mappingFunction" : {
      "name" : "toJson"
    }
  }
]

Сценарии расширенного сопоставления полей

В сценариях, когда у вас есть отношения "один ко многим", такие как фрагментирование или разделение данных, следуйте этим рекомендациям для сопоставления полей из родительских документов с дочерними документами (блоки):

1. Пропуск индексирования родительского документа

Если вы пропускаете индексирование родительских документов (задав значение skipIndexingParentDocuments projectionMode в наборе indexProjectionsнавыков), используйте проекции индекса для сопоставления полей из родительских документов с дочерними документами.

2. Индексирование родительских и дочерних документов

Если индексировать родительские документы и дочерние документы:

Используйте сопоставления полей для сопоставления полей с родительскими документами.
Используйте проекции индекса для сопоставления полей с дочерними документами.

3. Сопоставление преобразованных функций значений с родительскими и/или дочерними документами

Если поле в родительском документе требует преобразования (с помощью функций сопоставления, таких как кодировка) и должно быть сопоставлено с родительскими и/или дочерними документами:

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

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