將擴充的輸出對應至 Azure AI 搜尋服務中搜尋索引中的欄位

發行項
04/15/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.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 中，使用 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 搜尋服務中搜尋索引中的欄位

定義輸出欄位對應

將複雜結構壓平成字串集合

另請參閱

其他資源