エンリッチされた出力を Azure AI Search の検索インデックス内のフィールドにマッピングする

[アーティクル]
09/03/2024

この記事では、出力フィールドのマッピングを設定することで、スキルセットの処理中に生成されたメモリ内のデータと、検索インデックス内のターゲットフィールド間のデータパスを定義する方法を説明します。インデクサーの実行中、スキルによって生成された情報はメモリ内のみにあります。この情報を検索インデックスに保持するには、データの送信先をインデクサーに指示する必要があります。

出力フィールドマッピングはインデクサーで定義され、次の要素を含んでいます。

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

逐語的なソースフィールドとインデックスフィールドの間のパスをマップする fieldMappings 定義とは対照的に、outputFieldMappings 定義はメモリ内のエンリッチメントを検索インデックス内のフィールドにマップします。

前提条件

インデクサー、インデックス、データソース、スキルセット。
インデックスフィールドは、シンプルなフィールドまたは最上位レベルのフィールドである必要があります。複合型に出力することはできませんが、複合型がある場合は、出力フィールド定義を使用して複合型の一部をフラット化すると、検索インデックス内のコレクションに送信できます。

出力フィールドマッピングを使用するタイミング

インデックスに必要な新しい情報を作成するスキルセットがインデクサ-にアタッチされている場合は、出力フィールドマッピングが必要です。以下に例を示します。

埋め込みスキルのベクター
画像スキルの OCR テキスト
エンティティ認識スキルの場所、組織、またはユーザー

出力フィールドのマッピングは、次の場合にも使用できます。

生成されたコンテンツの複数のコピー作成 (1 対多の出力フィールドマッピング)。
ソースドキュメントの複合型をフラット化します。たとえば、ソースドキュメントに複合型 (複数パートの住所など) があり、市区町村名のみが必要な場合を考えます。出力フィールドマッピングを使用して入れ子になったデータ構造をフラット化した後、出力フィールドマッピングを使用すると、検索インデックス内の文字列コレクションに出力を送信できます。

出力フィールドマッピングは、検索インデックスにのみ適用されます。データの送信先がナレッジストアである場合は、データパスの構成にプロジェクションを使用します。

出力フィールドマッピングを定義する

出力フィールドマッピングは、インデクサーの定義の中の outputFieldMappings 配列に追加され、通常は fieldMappings 配列の後に配置されます。出力フィールドマッピングは、3 つの部分で構成されます。

出力フィールドマッピングは、REST API または Azure SDK を使用して定義できます。

ヒント

データインポートウィザードによって作成されたインデクサーには、ウィザードによって生成された出力フィールドマッピングが含まれています。例が必要な場合は、データソースに対してウィザードを実行して、インデクサーの出力フィールドマッピングを確認します。

REST API
.NET SDK (C#)

インデクサーの作成またはインデクサーの作成または更新、または Azure SDK の同等のメソッドを参照してください。インデクサー定義の例を次に示します。

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

outputFieldMappings 配列に値を入力してマッピングを指定します。フィールドマッピングは、3 つの部分で構成されます。

"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 Search スキルセットでのエンリッチメントの参照に関する記事を参照してください。
targetFieldName	省略可能。エンリッチされたコンテンツの送信先となる検索フィールドを指定します。ターゲットフィールドは、最上位の単純なフィールドまたはコレクションである必要があります。複合型のサブフィールドへのパスにすることはできません。複雑な構造から特定のノードを取得したい場合は、メモリ内で個々のノードをフラット化してから、その出力をインデックス内の文字列コレクションに送信してください。
mappingFunction	省略可能。インデクサーでサポートされるマッピング関数によって提供される処理を別途追加します。エンリッチメントノードの場合、エンコードとデコードが最も一般的に使用される関数です。

targetFieldName は、常に検索インデックス内のフィールドの名前です。
sourceFieldName は、エンリッチメントされたドキュメント内のノードへのパスです。スキルの出力です。パスは常に /document で始まり、BLOB からインデックスを作成する場合、パスの 2 番目の要素は /content となります。 3 番目の要素は、スキルによって生成される値です。詳細と例については、「Azure AI Search スキルセットでのエンリッチメントの参照」を参照してください。

この例では、BLOB のコンテンツプロパティから抽出したエンティティラベルとセンチメントラベルを検索インデックス内のフィールドに追加しています。
```
{
    "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"
        }
    ]
}
```
フィールドの内容をインデックスに格納する前に、これ変換するために必要なマッピング関数を割り当てます。エンリッチメントノードの場合、エンコードとデコードが最も一般的に使用される関数です。

Azure SDK for .NET では、"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);

一対多出力フィールドのマッピング

出力フィールドマッピングを使用して、単一のソースフィールドを検索インデックス内の複数のフィールドにルーティングできます。これは、比較テストのために、または異なる属性を持つフィールドが必要な場合に行うことができます。

ベクターフィールドの埋め込みを生成するスキルセットと、アルゴリズムと圧縮設定によって異なる複数のベクターフィールドを持つインデックスがあると考えてください。インデクサー内で、埋め込みスキルの出力を検索インデックス内の複数のベクターフィールドにマップします。

"outputFieldMappings": [
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_hnsw" }, 
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_eknn" },
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_narrow" }, 
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_no_stored" },
    { "sourceFieldName" : "/document/content/text_vector", "targetFieldName" : "vector_scalar" }       
  ]

ソースフィールドのパスはスキル出力です。この例では、出力は text_vector です。ターゲット名は省略可能なプロパティです。出力マッピングにターゲット名を指定しない場合、パスは embedding になります (具体的には、/document/content/embedding)。

{
  "name": "test-vector-size-ss",  
  "description": "Generate embeddings using AOAI",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
      "name": "#1",
      "description": null,
      "context": "/document/content",
      "resourceUri": "https://my-demo-eastus.openai.azure.com",
      "apiKey": null,
      "deploymentId": "text-embedding-ada-002",
      "dimensions": 1536,
      "modelName": "text-embedding-ada-002",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "embedding",
          "targetName": "text_vector"
        }
      ],
      "authIdentity": null
    }
  ]
}

複雑な構造を文字列コレクションにフラット化する

ソースデータが入れ子や階層構造の JSON で構成されている場合、フィールドマッピングを使用してデータパスを設定することはできません。完全にインポートするためには、各レベルのソースデータ構造が検索インデックスに正確に反映されている必要があります。

このセクションでは、ソース側とターゲット側の両方で複雑なドキュメントの 1 対 1 のリフレクションを生成するインポートプロセスについて説明します。次に、同じソースドキュメントを使用して個々のノードを取得し、文字列コレクションにフラット化する方法を紹介します。

入れ子になった 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"
          ]
        }
      ]
    }
  ]
}

検索インデックスにレンダリングする方法はもう 1 つあります。ソース側の入れ子構造に含まれる個々のノードを、検索インデックス側の文字列コレクションにフラット化する方法です。

このタスクを実行するためには、メモリ内のノードをインデックス内の文字列コレクションにマッピングする 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}
  ]
}

以下に示したのは、入れ子になった JSON を、outputFieldMappings を使用して文字列コレクションフィールドに関連付けるインデクサー定義の例です。スキルセットはありませんが、ソースフィールドで、エンリッチメントノードにパス構文が使用されていることに注目してください。エンリッチされたドキュメントは、システム内でドキュメント解析中に作成されます。つまり、ドキュメントの解析時に各ドキュメントツリーのノードが存在する限り、それらのノードにアクセスすることができます。

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

上記の定義の結果は次のとおりです。このケースでは、構造を簡略化した結果、コンテキストが失われています。特定の色 (colors) とそれを利用できる表現手段 (medium) との関連付けはなくなりました。ただし、シナリオによっては、次に示すような結果がちょうど目的に適う場合もあるでしょう。

{
  "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 Search の検索インデックス内のフィールドにマッピングする

前提条件

出力フィールドマッピングを使用するタイミング

出力フィールドマッピングを定義する

一対多出力フィールドのマッピング

複雑な構造を文字列コレクションにフラット化する

関連項目

フィードバック

その他のリソース

次の方法で共有

エンリッチされた出力を Azure AI Search の検索インデックス内のフィールドにマッピングする

前提条件

出力フィールド マッピングを使用するタイミング

出力フィールド マッピングを定義する

一対多出力フィールドのマッピング

複雑な構造を文字列コレクションにフラット化する

関連項目

フィードバック

その他のリソース

出力フィールドマッピングを使用するタイミング

出力フィールドマッピングを定義する