Azure AI 검색에서 검색 인덱스의 필드에 풍부한 출력 매핑

아티클
01/18/2024

이 문서에서는 기술 세트 처리 중에 만들어진 메모리 내 데이터 구조와 검색 인덱스의 대상 필드 사이의 데이터 경로를 결정하는 출력 필드 매핑을 설정하는 방법을 설명합니다. 출력 필드 매핑은 인덱서에서 정의되며 다음 요소를 포함합니다.

"outputFieldMappings": [
  {
    "sourceFieldName": "document/path-to-a-node-in-an-enriched-document",
    "targetFieldName": "some-search-field-in-an-index",
    "mappingFunction": null
  }
],

두 개의 실제 데이터 구조 사이의 경로를 매핑하는 fieldMappings 정의와 달리 outputFieldMappings 정의는 메모리 내 보강을 검색 인덱스의 필드에 매핑합니다.

인덱서에 텍스트 번역이나 핵심 구 추출과 같은 새로운 정보를 만드는 연결된 기술 세트가 있는 경우 출력 필드 매핑이 필요합니다. 인덱서 실행 중에 AI 생성 정보는 메모리에만 존재합니다. 이 정보를 검색 인덱스에 유지하려면 데이터를 보낼 위치를 인덱서에 알려야 합니다.

출력 필드 매핑을 사용하여 원본 문서의 복합 형식에서 특정 노드를 검색할 수도 있습니다. 예를 들어, 여러 부분으로 구성된 "FullName" 속성에 "FullName/LastName"만 필요할 수 있습니다. 복잡한 전체 구조가 필요하지 않은 경우 중첩된 데이터 구조에서 개별 노드를 평면화한 다음 출력 필드 매핑을 사용하여 출력을 검색 인덱스의 문자열 컬렉션으로 보낼 수 있습니다.

출력 필드 매핑은 다음에 적용됩니다.

기술에 의해 만들어지거나 인덱서에 의해 추출되는 메모리 내 콘텐츠. 원본 필드는 풍부한 문서 트리의 노드입니다.
인덱스를 검색합니다. 지식 저장소를 채우는 경우 데이터 경로 구성에 프로젝션을 사용합니다. 벡터 필드를 채우는 경우 출력 필드 매핑이 사용되지 않습니다.

출력 필드 매핑은 기술 세트 실행 후이거나 연결된 기술 세트가 없는 경우 문서 크래킹 후에 적용됩니다.

출력 필드 매핑 정의

출력 필드 매핑은 일반적으로 fieldMappings 배열 뒤에 배치되는 인덱서 정의의 outputFieldMappings 배열에 추가됩니다. 출력 필드 매핑은 세 부분으로 구성됩니다.

"fieldMappings": []
"outputFieldMappings": [
  {
    "sourceFieldName": "/document/path-to-a-node-in-an-enriched-document",
    "targetFieldName": "some-search-field-in-an-index",
    "mappingFunction": null
  }
],

속성	설명
sourceFieldName	필수입니다. 풍부한 콘텐츠에 대한 경로를 지정합니다. 예를 들면 `/document/content`입니다. 경로 구문 및 예제는 Azure AI 검색 기술 세트의 참조 보강을 참조하세요.
targetFieldName	선택 사항. 풍부한 콘텐츠를 수신하는 검색 필드를 지정합니다. 대상 필드는 최상위 단순 필드 또는 컬렉션이어야 합니다. 복합 형식의 하위 필드에 대한 경로일 수 없습니다. 복잡한 구조에서 특정 노드를 검색하려는 경우 메모리에서 개별 노드를 평면화한 다음 출력을 인덱스의 문자열 컬렉션으로 보낼 수 있습니다.
mappingFunction	선택 사항. 인덱서에서 지원하는 매핑 함수에서 제공하는 추가 처리를 추가합니다. 보강 노드의 경우 인코딩과 디코딩이 가장 일반적으로 사용되는 함수입니다.

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

팁

데이터 가져오기 마법사에서 만든 인덱서에는 마법사에서 만든 출력 필드 매핑이 포함됩니다. 예가 필요한 경우 데이터 원본에 대해 마법사를 실행하여 렌더링된 정의를 확인합니다.

REST API
.NET SDK(C#)

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

이 예에서는 Blob의 콘텐츠 속성에서 추출한 엔터티 및 감정 레이블을 검색 인덱스의 필드에 추가합니다.

PUT https://[service name].search.windows.net/indexers/myindexer?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
{
    "name": "myIndexer",
    "dataSourceName": "myDataSource",
    "targetIndexName": "myIndex",
    "skillsetName": "myFirstSkillSet",
    "fieldMappings": [],
    "outputFieldMappings": [
        {
            "sourceFieldName": "/document/content/organizations/*/description",
            "targetFieldName": "descriptions",
            "mappingFunction": {
                "name": "base64Decode"
            }
        },
        {
            "sourceFieldName": "/document/content/organizations",
            "targetFieldName": "orgNames"
        },
        {
            "sourceFieldName": "/document/content/sentiment",
            "targetFieldName": "sentiment"
        }
    ]
}

각 출력 필드 매핑의 경우 보강 필드(sourceFieldName)의 데이터 위치 및 인덱스(targetFieldName)에서 참조한 필드 이름을 설정합니다. 인덱스에 저장되기 전에 필드의 콘텐츠를 변환하는 데 필요한 매핑 함수를 할당합니다.

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

인덱서를 구성할 때 또는 나중에 SearchIndexer.OutputFieldMappings를 직접 설정하여 출력 필드 매핑을 지정합니다. 다음 C# 예에서는 인덱서를 구성할 때 출력 필드 매핑을 설정합니다.

string indexerName = "cog-search-demo";
SearchIndexer indexer = new SearchIndexer(
    indexerName,
    dataSourceConnectionName,
    indexName)
{
    // Field mappings omitted for this example (assume default mappings)
    OutputFieldMappings =
    {
        new FieldMapping("/document/content/organizations") { TargetFieldName = "orgNames" },
        new FieldMapping("/document/content/sentiment") { TargetFieldName = "sentiment" }
    },
    SkillsetName = skillsetName
};

await indexerClient.CreateIndexerAsync(indexer);

복잡한 구조를 문자열 컬렉션으로 평면화

원본 데이터가 중첩 또는 계층적 JSON으로 구성된 경우 필드 매핑을 사용하여 데이터 경로를 설정할 수 없습니다. 대신 검색 인덱스는 전체 가져오기를 위해 각 수준에서 원본 데이터 구조를 미러링해야 합니다.

이 섹션에서는 원본 및 대상 쪽 모두에서 복잡한 문서의 일 대 일 반영을 생성하는 가져오기 프로세스를 안내합니다. 다음으로 동일한 원본 문서를 사용하여 개별 노드를 문자열 컬렉션으로 검색하고 평면화하는 방법을 설명합니다.

다음은 중첩된 JSON이 있는 Azure Cosmos DB에 있는 문서의 예입니다.

{
   "palette":"primary colors",
   "colors":[
      {
         "name":"blue",
         "medium":[
            "acrylic",
            "oil",
            "pastel"
         ]
      },
      {
         "name":"red",
         "medium":[
            "acrylic",
            "pastel",
            "watercolor"
         ]
      },
      {
         "name":"yellow",
         "medium":[
            "acrylic",
            "watercolor"
         ]
      }
   ]
}

위의 원본 문서를 완전히 인덱싱하려면 필드 이름, 수준 및 형식이 복합 형식으로 반영되는 인덱스 정의를 만듭니다. 검색 인덱스의 복합 형식에 대해서는 필드 매핑이 지원되지 않으므로 인덱스 정의는 원본 문서를 미러링해야 합니다.

{
  "name": "my-test-index",
  "defaultScoringProfile": "",
  "fields": [
    { "name": "id", "type": "Edm.String", "searchable": false, "retrievable": true, "key": true},
    { "name": "palette", "type": "Edm.String", "searchable": true, "retrievable": true },
    { "name": "colors", "type": "Collection(Edm.ComplexType)",
      "fields": [
        {
          "name": "name",
          "type": "Edm.String",
          "searchable": true,
          "retrievable": true
        },
        {
          "name": "medium",
          "type": "Collection(Edm.String)",
          "searchable": true,
          "retrievable": true,
        }
      ]
    }
  ]
}

다음은 가져오기를 실행하는 샘플 인덱서 정의입니다(필드 매핑 및 기술 세트가 없음에 유의).

{
  "name": "my-test-indexer",
  "dataSourceName": "my-test-ds",
  "skillsetName": null,
  "targetIndexName": "my-test-index",

  "fieldMappings": [],
  "outputFieldMappings": []
}

결과는 Azure Cosmos DB의 원본과 유사한 다음 샘플 검색 문서입니다.

{
  "value": [
    {
      "@search.score": 1,
      "id": "240a98f5-90c9-406b-a8c8-f50ff86f116c",
      "palette": "primary colors",
      "colors": [
        {
          "name": "blue",
          "medium": [
            "acrylic",
            "oil",
            "pastel"
          ]
        },
        {
          "name": "red",
          "medium": [
            "acrylic",
            "pastel",
            "watercolor"
          ]
        },
        {
          "name": "yellow",
          "medium": [
            "acrylic",
            "watercolor"
          ]
        }
      ]
    }
  ]
}

검색 인덱스의 대체 렌더링은 원본의 중첩 구조에 있는 개별 노드를 검색 인덱스의 문자열 컬렉션으로 평면화하는 것입니다.

이 작업을 수행하려면 메모리 내 노드를 인덱스의 문자열 컬렉션에 매핑하는 outputFieldMappings이 필요합니다. 출력 필드 매핑은 주로 기술 출력에 적용되지만 인덱서가 원본 문서를 열고 메모리로 읽어들이는 "문서 크래킹" 후 노드를 처리하는 데 사용할 수도 있습니다.

아래는 평면화된 출력을 수신하기 위해 문자열 컬렉션을 사용하는 샘플 인덱스 정의입니다.

{
  "name": "my-new-flattened-index",
  "defaultScoringProfile": "",
  "fields": [
    { "name": "id", "type": "Edm.String", "searchable": false, "retrievable": true, "key": true },
    { "name": "palette", "type": "Edm.String", "searchable": true, "retrievable": true },
    { "name": "color_names", "type": "Collection(Edm.String)", "searchable": true, "retrievable": true },
    { "name": "color_mediums", "type": "Collection(Edm.String)", "searchable": true, "retrievable": true}
  ]
}

다음은 outputFieldMappings를 사용하여 중첩된 JSON을 문자열 컬렉션 필드와 연결하는 샘플 인덱서 정의입니다. 기술 세트가 없더라도 원본 필드는 보강 노드에 대한 경로 구문을 사용합니다. 보강된 문서는 문서 크래킹 중에 시스템에 만들어집니다. 즉, 문서가 크래킹될 때 해당 노드가 존재하는 한 각 문서 트리의 노드에 액세스할 수 있습니다.

{
  "name": "my-test-indexer",
  "dataSourceName": "my-test-ds",
  "skillsetName": null,
  "targetIndexName": "my-new-flattened-index",
  "parameters": {  },
  "fieldMappings": [   ],
  "outputFieldMappings": [
    {
       "sourceFieldName": "/document/colors/*/name",
       "targetFieldName": "color_names"
    },
    {
       "sourceFieldName": "/document/colors/*/medium",
       "targetFieldName": "color_mediums"
    }
  ]
}

위 정의의 결과는 다음과 같습니다. 이 경우 구조를 단순화하면 컨텍스트가 손실됩니다. 지정된 색상과 사용 가능한 매체 사이에 더 이상 연관이 없습니다. 그러나 시나리오에 따라 아래 표시된 것과 유사한 결과가 정확히 필요한 것일 수 있습니다.

{
  "value": [
    {
      "@search.score": 1,
      "id": "240a98f5-90c9-406b-a8c8-f50ff86f116c",
      "palette": "primary colors",
      "color_names": [
        "blue",
        "red",
        "yellow"
      ],
      "color_mediums": [
        "[\"acrylic\",\"oil\",\"pastel\"]",
        "[\"acrylic\",\"pastel\",\"watercolor\"]",
        "[\"acrylic\",\"watercolor\"]"
      ]
    }
  ]
}

Azure AI 검색에서 검색 인덱스의 필드에 풍부한 출력 매핑

출력 필드 매핑 정의

복잡한 구조를 문자열 컬렉션으로 평면화

참고 항목

추가 리소스