Azure AI 검색 인덱서를 사용하여 필드 매핑 및 변환

아티클
03/15/2024

Azure AI 검색 인덱서는 검색 인덱스를 로드할 때 원본-대상 필드 매핑을 사용하여 데이터 경로를 결정합니다. 암시적 필드 매핑은 내부이며 필드 이름과 데이터 형식이 원본 및 대상 간에 호환되는 경우에 발생합니다. 입력과 출력이 일치하지 않는 경우 이 문서에서 설명한 것처럼 명시적 필드 매핑을 정의하여 데이터 경로를 설정할 수 있습니다.

필드 매핑은 매핑 함수를 통해 인코딩 또는 디코딩과 같은 경량 데이터 변환에 사용될 수도 있습니다. 더 많은 처리가 필요한 경우 간격을 메우기 위해 Azure Data Factory를 고려하는 것이 좋습니다.

필드 매핑은 다음을 적용합니다.

데이터 스트림의 양쪽에 있는 물리적 데이터 구조(지원되는 데이터 원본의 필드와 검색 인덱스의 필드 사이). 메모리에 상주하는 기술 보강 콘텐츠를 가져오는 경우 outputFieldMappings를 사용하여 메모리 내 노드를 검색 인덱스의 출력 필드에 매핑합니다.
인덱스만 검색합니다. 지식 저장소를 채우는 경우 데이터 경로 구성에 프로젝션을 사용합니다.
최상위 검색 필드만(여기서 targetFieldName은 단순 필드 또는 컬렉션임). 대상 필드는 복합 형식일 수 없습니다.

참고 항목

복잡한 데이터(중첩 또는 계층 구조)로 작업하고 검색 인덱스에서 해당 데이터 구조를 미러링하려는 경우 검색 인덱스가 원본 구조와 정확히 일치해야(동일한 필드 이름, 수준 및 형식) 기본 매핑이 작동합니다. 필요에 따라 복잡한 구조에서 몇 개의 노드만 원할 수 있습니다. 개별 노드를 가져오기 위해 들어오는 데이터를 문자열 컬렉션으로 평면화할 수 있습니다(이 해결 방법은 outputFieldMappings 참조).

지원되는 시나리오

사용 사례	설명
이름 불일치	데이터 원본에 `_city`라는 필드가 있다고 가정하겠습니다. Azure AI 검색은 밑줄로 시작하는 필드 이름을 허용하지 않으므로 필드 매핑을 사용하면 효과적으로 "_city"를 "city"로 매핑할 수 있습니다. 인덱싱 요구 사항에 필드 이름이 원본마다 다른 여러 데이터 원본에서의 콘텐츠 검색이 포함된 경우 필드 매핑을 사용하여 경로를 명확히 할 수 있습니다.
형식 불일치	검색 인덱스에서 검색할 수 있도록 원본 정수 필드를 `Edm.String` 형식으로 지정해야 합니다. 형식이 다르기 때문에 데이터 경로가 성공하려면 필드 매핑을 정의해야 합니다. Azure AI 검색에는 데이터 원본보다 지원되는 데이터 형식 집합이 더 적게 있습니다. SQL 데이터를 가져오는 경우 필드 매핑을 사용하면 검색 인덱스에 원하는 SQL 데이터 형식을 매핑할 수 있습니다.
일대다 데이터 경로	인덱스에서 여러 필드를 동일한 원본 필드의 콘텐츠로 채울 수 있습니다. 예를 들어 클라이언트 앱의 다양한 사용 사례를 지원하기 위해 각 필드에 서로 다른 분석기를 적용할 수 있습니다.
인코딩 및 디코딩	매핑 함수를 적용하여 인덱싱 중에 데이터의 Base64 인코딩 또는 디코딩을 지원할 수 있습니다.
문자열을 분할하거나 배열을 컬렉션으로 다시 캐스팅	매핑 함수를 적용하여 구분 기호가 포함된 문자열을 분할하거나 JSON 배열을 `Collection(Edm.String)` 형식의 검색 필드로 보낼 수 있습니다.

필드 매핑 정의

필드 매핑은 인덱서 정의의 fieldMappings 배열에 추가됩니다. 필드 매핑은 다음 세 부분으로 구성됩니다.

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

속성	설명
sourceFieldName	필수입니다. 데이터 원본의 필드를 나타냅니다.
targetFieldName	선택 사항. 검색 인덱스의 필드를 나타냅니다. 생략하면 대상에 `sourceFieldName` 값이 사용됩니다. 대상 필드는 최상위 단순 필드 또는 컬렉션이어야 합니다. 복합 형식 또는 컬렉션일 수 없습니다. 데이터 형식 문제를 처리하는 경우 필드의 데이터 형식이 인덱스 정의에 지정됩니다. 필드 매핑에는 필드 이름이 있어야 합니다.
mappingFunction	선택 사항. 데이터를 변환하는 미리 정의된 함수로 구성됩니다.

유사한 "Field mapping specifies target field 'Address/city' that doesn't exist in the index"오류가 발생하면 대상 필드 매핑이 복합 형식일 수 없기 때문입니다. 해결 방법은 필드 이름 및 데이터 형식의 원시 콘텐츠와 동일한 인덱스 스키마를 만드는 것입니다. 예제는 자습서: 중첩된 JSON Blob 인덱스를 참조하세요.

Azure AI 검색은 대/소문자 구분 비교를 사용하여 필드 매핑의 필드와 함수 이름을 확인합니다. 이는 편리(모든 대/소문자를 올바르게 할 필요가 없음)하지만 데이터 원본 또는 인덱스가 대/소문자만으로 다른 필드를 가질 수 없음을 의미합니다.

참고 항목

필드 매핑이 없는 경우 인덱서는 데이터 원본 필드가 동일한 이름의 인덱스 필드에 매핑되어야 한다고 가정합니다. 필드 매핑을 추가하면 원본 및 대상 필드에 대한 기본 필드 매핑이 재정의됩니다. Blob Storage 인덱서 같은 일부 인덱서는 인덱스 키 필드에 대한 기본 필드 매핑을 추가합니다.

REST API 또는 Azure SDK를 사용하여 필드 매핑을 정의할 수 있습니다.

REST API
.NET SDK(C#)

모든 API 버전에서 인덱서 만들기(REST) 또는 인덱서 업데이트(REST)를 사용합니다.

이 예제에서는 필드 이름 불일치를 처리합니다.

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" }
]

.NET용 Azure SDK에서 SourceFieldName 및 TargetFieldName 속성과 선택적 MappingFunction 참조를 제공하는 FieldMapping 클래스를 사용합니다.

인덱서를 구성할 때 또는 나중에 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 함수

입력된 문자열의 URL 안전 Base64 인코딩을 수행합니다. 입력이 UTF-8 인코딩되었다고 가정합니다.

예: 문서 키 기본 인코딩

조회 API를 사용하여 문서를 처리할 수 있으므로 URL이 안전히 지원되는 문자만 Azure AI 검색 문서 키에 나타날 수 있습니다. 키의 원본 필드에 - 및 \와 같은 URL이 안전히 지원되지 않는 문자가 포함된 경우 base64Encode 함수를 사용하여 인덱싱할 때 변환할 수 있습니다.

다음 예제에서는 metadata_storage_name 에서 base64Encode 함수를 지정하여 지원되지 않는 문자를 처리합니다.

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 }
        } 
    }
  ]
}

문서 키는 1,024자를 초과할 수 없습니다(변환 전후 모두). 검색 시 인코딩된 키를 검색하는 경우 base64Decode 함수를 사용하여 원래 키 값을 가져온 다음 이를 사용하여 원본 문서를 검색합니다.

예: 기본으로 인코딩된 필드를 "검색 가능"으로 만들기

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 Storage 인덱서는 필드 매핑이 지정되지 않은 경우 Blob의 URI metadata_storage_path에 있는 필드 매핑을 인덱스 키 필드에 자동으로 추가합니다. 이 값은 Base64로 인코딩되므로 Azure AI 검색 문서 키로 사용할 수 있습니다. 다음 예제에서는 'URL이 안전히 지원되는' Base64 인코딩된 버전의 metadata_storage_path를 index_key 필드에 동시에 매핑하고 원래 값을 metadata_storage_path 필드에 유지하는 방법을 보여 줍니다.

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

매핑 함수에 대한 매개 변수 속성을 포함하지 않으면 기본값은 {"useHttpServerUtilityUrlTokenEncode" : true}입니다.

Azure AI 검색은 두 가지의 Base64 인코딩을 지원합니다. 동일한 필드를 인코딩 및 디코딩할 때 동일한 매개 변수를 사용해야 합니다. 자세한 내용은 사용할 매개 변수를 결정하기 위한 base64 인코딩 옵션을 참조하세요.

base64Decode 함수

입력 문자열의 Base64 디코딩을 수행합니다. 입력은 'URL이 안전히 지원되는' Base64 인코딩된 문자열로 간주됩니다.

예제 - Blob 메타데이터 또는 URL 디코딩

원본 데이터에는 일반 텍스트로 검색하려는 Blob 메타데이터 문자열 또는 웹 URL과 같은 Base64 인코딩 문자열이 포함될 수 있습니다. base64Decode 함수를 사용하여 검색 인덱스를 채울 때 인코딩된 데이터를 일반 문자열로 다시 전환할 수 있습니다.

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

매개 변수 속성을 포함하지 않으면 기본값은 {"useHttpServerUtilityUrlTokenEncode" : true}입니다.

base64 인코딩 옵션

Azure AI 검색은 URL이 안전하게 지원되는 base64 인코딩과 일반 base64 인코딩을 지원합니다. 인덱싱을 수행할 때 base64 인코딩된 문자열은 나중에 동일한 인코딩 옵션을 사용하여 디코딩해야 합니다. 그렇지 않으면 결과가 원본과 일치하지 않습니다.

인코딩 및 디코딩을 위한 useHttpServerUtilityUrlTokenEncode 또는 useHttpServerUtilityUrlTokenDecode 매개 변수가 각각 true로 설정되면 base64Encode는 HttpServerUtility.UrlTokenEncode처럼 작동하고, base64Decode는 HttpServerUtility.UrlTokenDecode처럼 작동합니다.

Warning

키 값을 생성하는 데 base64Encode를 사용하는 경우에는 useHttpServerUtilityUrlTokenEncode를 true로 설정해야 합니다. 키 값에는 URL이 안전히 지원되는 base64 인코딩만 사용할 수 있습니다. 키 값의 문자에 대한 전체 제한 사항은 명명 규칙을 참조하세요.

Azure AI 검색의 .NET 라이브러리는 기본 제공 인코딩을 제공하는 전체 .NET Framework를 가정합니다. useHttpServerUtilityUrlTokenEncode 및 useHttpServerUtilityUrlTokenDecode 옵션은 이 기본 제공 기능을 적용합니다. .NET Core 또는 다른 프레임워크를 사용하는 경우 해당 옵션을 false로 설정하고 프레임워크의 인코딩 및 디코딩 함수를 직접 호출하는 것이 좋습니다.

다음 표에서는 문자열 00>00?00의 서로 다른 base64 인코딩을 비교합니다. base64 함수에 필요한 처리를 판단하려면(있는 경우) 00>00?00 문자열에서 라이브러리 인코딩 함수를 적용하고 출력을 MDA-MDA_MDA 예상 출력과 비교합니다.

인코딩	Base64 인코딩 출력	라이브러리 인코딩 후 추가 처리	라이브러리 디코딩 전 추가 처리
Base64(패딩 있음)	`MDA+MDA/MDA=`	URL 지원 문자 사용 및 패딩 제거	표준 base64 문자 사용 및 패딩 추가
Base64(패딩 없음)	`MDA+MDA/MDA`	URL 지원 문자 사용	표준 base64 문자 사용
URL 지원 Base64(패딩 있음)	`MDA-MDA_MDA=`	패딩 제거	패딩 추가
URL 지원 Base64(패딩 없음)	`MDA-MDA_MDA`	없음	없음

extractTokenAtPosition 함수

지정된 구분 기호를 사용하여 문자열 필드를 분할하고 결과 분할의 지정된 위치에서 토큰을 선택합니다.

이 함수는 다음 매개 변수를 사용합니다.

delimiter: 입력 문자열을 분할할 때 구분 기호로 사용할 문자열입니다.
position: 입력 문자열을 분할한 후 선택할 정수 0부터 시작하는 토큰의 위치입니다.

예를 들어 입력은 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 문자열 배열로 구문 분석할 수 없는 입력 값의 경우 오류가 반환됩니다.

예제 - 관계형 데이터에서 컬렉션 채우기

Azure SQL Database에는 Azure AI 검색의 Collection(Edm.String) 필드에 자연스럽게 매핑하는 데이터 형식이 기본 제공되지 않습니다. 문자열 컬렉션 필드를 채우려면 원본 데이터를 JSON 문자열 배열로 전처리한 다음 jsonArrayToStringCollection 매핑 함수를 사용할 수 있습니다.

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

urlEncode 함수

이 함수를 사용하여 문자열을 'URL이 안전히 지원되도록' 인코딩할 수 있습니다. URL에 허용되지 않는 문자가 포함된 문자열을 사용하는 경우 이 함수는 '안전하지 않은' 문자를 해당하는 문자 엔터티로 변환합니다. 이 함수는 UTF-8 인코딩 형식을 사용합니다.

예제 - 문서 키 조회

URL이 안전히 지원되지 않는 문자만 변환하고 다른 문자는 그대로 유지하는 경우 urlEncode 함수를 base64Encode 함수 대신 사용할 수 있습니다.

예를 들어 입력 문자열이 <hello>이면 (Edm.String) 형식의 대상 필드는 %3chello%3e 값으로 채워집니다.

검색 시 인코딩된 키를 검색하는 경우 urlDecode 함수를 사용하여 원래 키 값을 가져온 다음 이를 사용하여 원본 문서를 검색할 수 있습니다.

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

urlDecode 함수

이 함수는 UTF-8 인코딩 형식을 사용하여 URL 인코딩된 문자열을 디코딩된 문자열로 변환합니다.

예제 - Blob 메타데이터 디코딩

일부 Azure Storage 클라이언트는 ASCII가 아닌 문자를 포함하는 경우 Blob 메타데이터를 자동으로 인코딩합니다. 그러나 이러한 메타데이터를 일반 텍스트로 검색할 수 있게 하려면 검색 인덱스를 채울 때 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 개체로 변환합니다. Azure SQL과 같은 데이터 원본에서 기본적으로 복합 또는 계층적 데이터 형식을 지원하지 않는 시나리오에 사용한 다음, 복합 필드에 매핑할 수 있습니다.

예제 - 텍스트 콘텐츠를 복합 필드에 매핑

인덱 toJson 스의 (그에 따라 정의된) 복합 필드에 매핑해야 하는 JSON 문자열이 있는 SQL 행이 있다고 가정합니다. 이 함수를 사용하여 이를 달성할 수 있습니다. 예를 들면 인덱스에 있는 복합 필드를 다음 데이터로 채워야 하는 경우입니다.

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

{"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}과 같은 SQL 행의 JSON 문자열 열에 toJson 매핑 함수를 사용하여 달성할 수 있습니다.

다음과 같이 필드 매핑을 지정해야 합니다.


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

Azure AI 검색 인덱서를 사용하여 필드 매핑 및 변환

지원되는 시나리오

필드 매핑 정의

함수 및 예제 매핑

base64Encode 함수

예: 문서 키 기본 인코딩

예: 기본으로 인코딩된 필드를 "검색 가능"으로 만들기

예제 - 원래 값 유지

base64Decode 함수

예제 - Blob 메타데이터 또는 URL 디코딩

base64 인코딩 옵션

extractTokenAtPosition 함수

예제 - 이름 추출

jsonArrayToStringCollection 함수

예제 - 관계형 데이터에서 컬렉션 채우기

urlEncode 함수

예제 - 문서 키 조회

urlDecode 함수

예제 - Blob 메타데이터 디코딩

fixedLengthEncode 함수

예제 - 너무 긴 문서 키 매핑

toJson 함수

예제 - 텍스트 콘텐츠를 복합 필드에 매핑

참고 항목

추가 리소스