在 Foundry IQ(Azure AI 搜尋服務)技能組中使用上下文與來源屬性,參照擴充節點的路徑

Note

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

在技能集執行期間,引擎會建置記憶體內的擴充樹,以擷取每個擴充,例如已辨識的實體或已翻譯的文字。 在本文中,了解如何在擴充樹中參考擴充節點,以便將輸出傳遞至下游技能,或為搜尋索引欄位指定輸出欄位對應。

本文使用範例來說明各種案例。 如需完整的語法,請參閱 技能內容和輸入批注語言。

背景概念

在檢閱語法之前,讓我們先回顧幾個重要概念,以便更好理解本文稍後提供的範例。

詞彙 描述
「擴充文件」 擴充文件是記憶體內結構,會在建立技能輸出時收集技能輸出,並保存與文件相關的所有擴充。 您可以將擴充文件視為一棵樹。 一般而言,樹會從根文件層級開始,每個新的擴充都會從先前節點建立為其子節點。
「節點」 在擴充文件中,節點 (有時也稱為「標註」) 是特定輸出,例如 OCR 技能的「text」或「layoutText」,或原始來源欄位值,例如產品 ID 欄位內容,或從來源複製的中繼資料,例如 Azure 儲存體中 Blob 的 metadata_storage_path。
「內容」 擴充的範圍,可能是整份文件、文件的一部分 (頁面或句子),或若您處理的是影像,則為從文件擷取的影像。 預設情況下,擴充內容位於 "/document" 層級,並以資料來源中包含的個別文件為範圍。 技能執行時,該技能的輸出會成為已定義內容的屬性。

不同案例的路徑

路徑會在技能集的內容與來源屬性中指定,並在索引子中的輸出欄位對應中指定。

技能組定義的截圖,並標示了上下文與來源元素。

螢幕擷取畫面中的範例說明 Azure Cosmos DB 集合中某個項目的路徑。

  • context 路徑是 /document/HotelId,因為集合會依據 /HotelId 欄位分割成文件。

  • source 路徑是 /document/Description 因為該技能屬於翻譯技能,而您想翻譯的欄位就是 Description 每份文件中的欄位。

所有路徑都以 /document 開頭。 擴充文件會在索引子執行的文件破解階段建立,也就是索引子開啟文件或從資料來源讀取資料列時。 一開始,擴充文件中唯一的節點是根節點 (/document),且它是所有其他擴充發生的起點。

下列清單包含幾個常見範例:

  • /document是根節點,並表示 Azure 儲存體 中的整個 blob,或 SQL 資料表中的一列。
  • /document/{key}是 Azure Cosmos DB 集合中文件或項目的語法,其中 {key} 為實際鍵碼,如/document/HotelId前述範例所示。
  • /document/content 指定 JSON blob 的「content」屬性。
  • /document/{field} 是對特定欄位執行的運算語法,例如前述範例中所見的翻譯 /document/Description 欄位。
  • /document/pages/* 或者 /document/sentences/* 如果你要把大型文件拆成更小的區塊來處理,也可以成為上下文。 如果內容為 /document/pages/*,技能會針對文件中的每一頁各執行一次。 因為頁面或句子可能不只一個,您可以附加 /* 來一次涵蓋全部。
  • /document/normalized_images/* 如果文件包含影像,則會在文件剖析期間建立。 所有影像路徑都以 normalized_images 開頭。 由於文件中通常會內嵌多個影像,請附加 /*。

本文其餘部分的範例以 Azure Blob 索引子在文件破解階段自動產生的「內容」欄位為基礎。 當您參考 Blob 容器中的文件時,請使用 "/document/content" 之類的格式,其中「內容」欄位屬於「文件」的一部分。

範例 1:簡單標註參考

在 Azure Blob 儲存體中,假設您有各種檔案包含人員姓名參考,且您想使用實體辨識將其擷取。 在下列技能定義中,"/document/content" 是整份文件的文字表示,而「人員」是針對識別為人員的實體所擷取之完整姓名。

由於預設內容為 "/document",因此人員清單現在可參考為 "/document/people"。 在此特定案例中,"/document/people" 是標註,現在可對應至索引中的欄位,或在同一個技能集中供另一個技能使用。

  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "categories": [ "Person"],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "persons",
        "targetName": "people"
      }
    ]
  }

範例 2:參考文件內的陣列

此範例延續前一個範例,示範如何在同一份文件上多次調用某個擴充步驟。 假設前一個範例從單一文件產生了包含 10 個人員名稱的字串陣列。 合理的下一步可能是第二個擴充,用來從完整姓名擷取姓氏。 由於有 10 個名稱,您希望在此文件中將此步驟呼叫 10 次,每個人各一次。

若要調用正確的迭代次數,請將內容設為 "/document/people/*",其中星號 ("*") 代表擴充文件中作為 "/document/people" 子系的所有節點。 雖然此技能只在 skills 陣列中定義一次,但它會針對文件內的每個成員呼叫,直到處理完所有成員。

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the last name from a full name",
    "uri": "http://names.azurewebsites.net/api/GetLastName",
    "context" : "/document/people/*",
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "fullname",
        "source": "/document/people/*"
      }
    ],
    "outputs": [
      {
        "name": "lastname",
        "targetName": "lastname"
      }
    ]
  }

當標註是陣列或字串集合時,您可能想鎖定特定成員,而不是整個陣列。 上一個範例會在內容所代表的每個節點下產生名為 "lastname" 的批注。 如果你想參考這一系列註解,請使用語法 "/document/people/*/lastname"。 如果你想參考某個註解,可以用明確索引"/document/people/1/lastname"()來指代文件中第一個被識別的人的姓氏。 注意在這個語法中,陣列是零索引的。

範例 3:參考陣列中的成員

有時您需要將特定類型的所有標註分組,並將其傳遞給特定技能。 請考慮一個假想的自訂技能,用於識別範例 2 中擷取到的所有姓氏裡,最常見的姓氏。 若要只提供姓氏給自訂技能,請將內容指定為 "/document",並將輸入指定為 "/document/people/*/lastname"。

請注意,"/document/people/*/lastname" 的基數大於 document 的基數。 可能有10個姓氏節點,而這份檔只有一個文件節點。 在這種情況下,系統會自動建立一個包含文件中所有元素的陣列 "/document/people/*/lastname" 。

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the most common string from an array of strings",
    "uri": "http://names.azurewebsites.net/api/MostCommonString",
    "context" : "/document",
    "inputs": [
      {
        "name": "strings",
        "source": "/document/people/*/lastname"
      }
    ],
    "outputs": [
      {
        "name": "mostcommon",
        "targetName": "common-lastname"
      }
    ]
  }

標註路徑疑難排解提示

如果您在指定技能輸入時遇到問題,下列提示可能有助於您繼續進行:

另請參閱