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

Статья
03/15/2024

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

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

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

Физические структуры данных на обеих сторонах потока данных (между полями в поддерживаемом источнике данных и полях в индексе поиска). Если вы импортируете обогащенное навыком содержимое, которое находится в памяти, используйте outputFieldMappings для сопоставления узлов в памяти с полями вывода в индексе поиска.
Только индексы поиска. Если вы заполняете хранилище знаний, используйте проекции для конфигурации пути к данным.
Только поля поиска верхнего уровня, где targetFieldName это простое поле или коллекция. Целевое поле не может быть сложным типом.

Примечание.

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

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

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

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

Сопоставления полей добавляются в fieldMappings массив определения индексатора. Сопоставление полей состоит из трех частей.

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

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

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

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

Примечание.

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

Для определения сопоставлений полей можно использовать REST API или пакет SDK Azure.

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

Используйте создание индексатора (REST) или индексатора обновлений (REST), любой версии API.

В этом примере выполняется несоответствие имени поля.

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=2020-06-30
{
  "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=2020-06-30
{
    "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"
    }
  }
]