다음을 통해 공유

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

  • 아티클

인덱서 스테이지

이 문서에서는 지원되는 데이터 원본의 원본 필드와 검색 인덱스에 있는 대상 필드 간의 데이터 경로를 설정하는 명시적 필드 매핑을 설정하는 방법을 설명합니다.

필드 매핑을 설정해야 하는 때

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

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

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

  • 데이터 경로의 양쪽에 있는 물리적 데이터 구조입니다. 기술에 의해 만들어진 논리적 데이터 구조는 메모리에만 상주합니다. outputFieldMappings를 사용하여 메모리 내 노드를 검색 인덱스의 출력 필드에 매핑합니다.

  • 부모 AI Search 인덱스만 해당합니다. "자식" 문서 또는 "청크"가 있는 "보조" 인덱스의 경우 고급 필드 매핑 시나리오를 참조하세요.

  • 최상위 검색 필드만(여기서 targetFieldName은 단순 필드 또는 컬렉션임). 대상 필드는 복합 형식일 수 없습니다.

지원되는 시나리오

인덱서 구동 인덱싱에 지원되는 데이터 원본을 사용하고 있는지 확인합니다.

사용 사례 설명
이름 불일치 데이터 원본에 _city라는 필드가 있다고 가정하겠습니다. Azure AI 검색은 밑줄로 시작하는 필드 이름을 허용하지 않으므로 필드 매핑을 사용하면 효과적으로 "_city"를 "city"로 매핑할 수 있습니다.

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

참고 항목

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

필드 매핑에서는 복합 필드가 지원되지 않습니다. 기본 매핑이 작동하려면 원본 구조(중첩 구조 또는 계층적 구조)가 인덱스의 복합 형식과 정확히 일치해야 합니다. 자세한 내용은 자습서: 인덱스 중첩 JSON Blob 예시를 참조하세요. "Field mapping specifies target field 'Address/city' that doesn't exist in the index"와 유사한 오류가 발생하는 경우 대상 필드 매핑이 복합 형식일 수 없기 때문입니다.

필요에 따라 복잡한 구조에서 몇 개의 노드만 원할 수 있습니다. 개별 노드를 가져오기 위해 들어오는 데이터를 문자열 컬렉션으로 평면화할 수 있습니다(이 해결 방법은 outputFieldMappings 참조).

필드 매핑 정의

이 섹션에서는 필드 매핑을 설정하는 단계를 설명합니다.

  1. Azure SDK에서 인덱서 만들기 또는 인덱서 만들기 또는 업데이트 또는 이와 동등한 방법을 사용합니다. 다음은 인덱서 정의의 예입니다.

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

  2. 매핑을 지정하려면 fieldMappings 배열을 작성합니다. 필드 매핑은 다음 세 부분으로 구성됩니다.

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

예: 이름 또는 형식 불일치

명시적 필드 매핑은 이름과 형식이 동일하지 않은 경우에 대한 데이터 경로를 설정합니다.

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

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

기술 생성 콘텐츠에 유사한 방법을 사용할 수 있습니다.

함수 및 예제 매핑

필드 매핑 함수는 인덱스에 저장되기 전에 필드의 내용을 변환합니다. 현재 지원되는 매핑 함수는 다음과 같습니다.

현재 이러한 함수는 부모 인덱스에 대해서만 지원됩니다. 청크 분할 인덱스 매핑과 호환되지 않으므로 이러한 함수는 인덱스 프로젝션에 사용할 수 없습니다.

base64Encode 함수

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

예: 문서 키 기본 인코딩

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

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

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

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

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

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 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}입니다.

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

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과 같은 데이터 원본에서 기본적으로 복합 또는 계층적 데이터 형식을 지원하지 않는 시나리오에 사용한 다음, 복합 필드에 매핑할 수 있습니다.

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

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

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

고급 필드 매핑 시나리오

데이터 청크 또는 분할과 같은 "일대다" 문서 관계가 있는 시나리오에서는 부모 문서에서 "자식" 문서(청크)로 필드를 매핑하기 위해 다음 지침을 따릅니다.

1. 부모 문서 인덱싱 건너뛰기

기술 세트의 indexProjections에서 projectionMode를 skipIndexingParentDocuments로 설정하여 부모 문서의 인덱싱을 건너뛰는 경우 인덱스 프로젝션을 사용하여 부모 문서의 필드를 "자식" 문서에 매핑합니다.

2. 부모 및 "자식" 문서 인덱싱

부모 문서와 "자식" 문서를 모두 인덱싱하는 경우:

  • 필드 매핑을 사용하여 상위 문서에 필드를 매핑합니다.
  • 인덱스 프로젝션을 사용하여 필드를 "자식" 문서에 매핑합니다.

3. 함수 변환 값을 부모 및/또는 "자식" 문서에 매핑

부모 문서의 필드에 변환이 필요하고(인코딩과 같은 매핑 함수 사용) 부모 및/또는 "자식" 문서에 매핑해야 하는 경우:

  • 인덱서에서 필드 매핑의 함수를 사용하여 변환을 적용합니다.
  • 기술 세트의 인덱스 프로젝션을 사용하여 변환된 필드를 "자식" 문서에 매핑합니다.

참고 항목