将扩充的输出映射到 Azure AI 搜索的搜索索引中的字段

项目
03/08/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”。如果不需要完整的复杂结构，可以平展嵌套数据结构中的各个节点，然后使用输出字段映射将输出发送到搜索索引中的字符串集合。

输出字段映射适用于：

由技能创建或由索引器提取的内存中内容。源字段是扩充文档树中的一个节点。
搜索索引。如果要填充知识存储，请将投影用于数据路径配置。如果要填充向量存储，则不使用输出字段映射。

如果没有关联的技能组，将在完成技能组执行或文档破解后应用输出字段映射。

定义输出字段映射

输出字段映射将添加到索引器定义中的 outputFieldMappings 数组，通常放在 fieldMappings 数组之后。输出字段映射由三部分组成。

"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#)

使用创建索引器 (REST) 或更新索引器 (REST)（任何 API 版本）。

此示例将从 Blob 的内容属性中提取的实体和情绪标签添加到搜索索引中的字段。

PUT https://[service name].search.azure.cn/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 中，可以使用 OutputFieldMappingEntry 类，该类提供“Name”和“TargetFieldName”属性以及可选的“MappingFunction”引用。

可以在构造索引器时指定输出字段映射，也可以在以后通过直接设置 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 组成，则你无法使用字段映射来设置数据路径。在这种情况下，搜索索引必须在每个级别镜像源数据结构以进行完整导入。

本部分引导你完成一个导入过程，该过程在源端和目标端生成复杂文档的一对一反映。接下来，该过程使用同一源文档来演示如何检索各个节点并将其平展为字符串集合。

下面是 Azure Cosmos DB 中包含嵌套 JSON 的文档示例：

{
   "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 搜索的搜索索引中的字段

定义输出字段映射

将复杂结构平展为字符串集合

请参阅

其他资源