定義知識存放區中的投影

Note

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

Note

知識儲存是存在於 Azure 儲存體 中的次級儲存,包含 Foundry IQ(Azure AI 搜尋服務)技能組合的輸出。 它們與知識來源和知識庫是分開的,後者用於 代理檢索 工作流程。

投影是知識庫定義中的一個組成部分,用來決定 AI 豐富內容如何儲存在 Azure 儲存體 中。 投影會決定包含您內容的資料結構類型、數量和組合。

在本文中,了解每種投影類型的語法:

回想一下,投影是在技能集的 knowledgeStore 屬性下定義。

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
      {
        "tables": [ ],
        "objects": [ ],
        "files": [ ]
      }
    ]
}

如果在開始前需要更多背景知識,請檢閱此檢查清單以了解秘訣和工作流程。

Tip

開發投影時,啟用擴充快取 (預覽) 以便在編輯投影定義時重複使用現有擴充。 擴充快取為預覽功能,因此請務必在索引子要求中使用預覽 REST API。 在沒有快取的情況下,對投影的簡單編輯將導致對擴充內容進行全面重新處理。 您可以藉由快取擴充來逐一查看投影,不會產生任何技能集處理費用。

Requirements

所有投影都具有來源和目的地屬性。 來源一律為技能集執行期間所建立擴充樹狀結構的內部內容。 目的地是 Azure 儲存體中建立和填入的外部物件名稱和類型。

除了只接受二進位映像的檔案投影外,來源必須是:

  • 有效的 JSON
  • 擴充樹狀結構中節點的路徑 (例如 "source": "/document/objectprojection")

雖然節點可能會解析為單一欄位,但更常見的表示法是對複雜圖形的參考。 複雜圖形是透過塑形方法所建立,可能是塑形器技能或內嵌塑形定義,但通常是塑形器技能。 圖形的欄位或元素會決定容器和資料表中的欄位。

由於大部分技能不會自行輸出有效的 JSON,因此會輸出 JSON 的塑形器技能較受偏好。 在多數情況下,塑形器技能所建立的相同資料圖形同樣可用於資料表和物件投影。

鑑於來源輸入要求,了解如何塑形資料已成為投影定義的實用條件,特別是當您使用資料表時。

定義資料表投影

針對呼叫資料探索的案例,建議使用資料表投影,例如使用 Power BI 進行分析或取用資料框架的工作負載。 投影陣列的資料表區段是您要投影的資料表清單。

若要定義資料表投影,請使用投影屬性中的 tables 陣列。 資料表投影具有三個必要屬性:

Property Description
tableName 決定在 Azure 資料表儲存體中建立的新資料表名稱。
generatedKeyName 可唯一識別各資料列的索引鍵資料行名稱。 此值是由系統所產生。 如果您省略這個屬性,系統會自動建立一個使用數據表名稱和 “key” 作為命名慣例的數據行。
來源 擴充樹狀結構中節點的路徑。 節點應該是對複雜圖形的參考,可決定資料表中建立哪些資料行。

在資料表投影中,「來源」通常是定義資料表圖形的塑形器技能輸出。 資料表具有資料列和資料行,塑形則為指定資料列和資料行的機制。 您可以使用塑形器技能或內嵌圖形。 塑形器技能會產生有效的 JSON,但如果是有效的 JSON,來源可以是任何技能的輸出。

Note

資料表投影受限於 Azure 儲存體施加的儲存體限制。 實體大小不能超過 1 MB,而且單一屬性不能大於 64 KB。 這些條件約束使資料表成為儲存大量小型實體的優秀解決方案。

單一資料表範例

資料表的結構描述部分由投影 (資料表名稱和索引鍵) 指定,也由提供資料表圖形 (資料行) 的來源指定。 此範例只會顯示一個資料表,以便您專注於定義的詳細資料。

"projections" : [
  {
    "tables": [
      { "tableName": "Hotels", "generatedKeyName": "HotelId", "source": "/document/tableprojection" }
    ]
  }
]

資料行衍生自「來源」。 下列資料圖形包含 HotelId、HotelName、類別和描述,將導致在資料表中建立這些資料行。

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "name": "#3",
    "description": null,
    "context": "/document",
    "inputs": [
    {
        "name": "HotelId",
        "source": "/document/HotelId"
    },
    {
        "name": "HotelName",
        "source": "/document/HotelName"
    },
    {
        "name": "Category",
        "source": "/document/Category"
    },
    {
        "name": "Description",
        "source": "/document/Description"
    },
    ],
    "outputs": [
    {
        "name": "output",
        "targetName": "tableprojection"
    }
    ]
}

多個資料表 (切割) 範例

資料表投影的常見模式是有多個相關資料表,其中會建立由系統產生的 partitionKey 和 rowKey 資料行,以支援相同投影群組下所有資料表的跨資料表關聯性。

如果您想要控制相關資料的彙總方式,建立多個資料表會相當實用。 如果擴充的內容具有不相關或獨立的元件,例如,從檔擷取的關鍵詞可能與相同檔中辨識的實體無關,您可以將這些字段分割成相鄰的數據表。

在您投影至多個資料表時,除非子節點是相同群組內另一個資料表的來源,否則系統會將完整圖形投影至各資料表中。 若新增投影的來源路徑為現有投影的子節點,會導致子節點從父節點中切割,並投影至新的相關資料表中。 這項技術可讓您在塑形器技能中定義單一節點,該節點可以是所有投影的來源。

多個資料表的模式包括:

  • 一個資料表做為父資料表或主資料表
  • 包含擴充內容分割的其他資料表

例如,假設塑形器技能輸出「EnrichedShape」,其中包含旅館資訊及擴充內容,例如關鍵片語、位置和組織。 主資料表會包含描述旅館 (識別碼、名稱、描述、位址、類別) 的欄位。 關鍵片語會取得關鍵片語資料行。 實體會取得實體資料行。

"projections" : [
  {
    "tables": [
    { "tableName": "MainTable", "generatedKeyName": "HotelId", "source": "/document/EnrichedShape" },
    { "tableName": "KeyPhrases", "generatedKeyName": "KeyPhraseId", "source": "/document/EnrichedShape/*/KeyPhrases/*" },
    { "tableName": "Entities", "generatedKeyName": "EntityId", "source": "/document/EnrichedShape/*/Entities/*" }
    ]
  }
]

命名關係

generatedKeyName 和 referenceKeyName 屬性可用於與資料建立關聯,無論是跨資料表或甚至是跨投影類型。 子資料表中的每個資料列都有指回父代的屬性。 子系中資料行或屬性的名稱是父代中的 referenceKeyName。 若未提供 referenceKeyName,服務會將其預設為來自上層的 generatedKeyName。

Power BI 依賴這些產生的索引鍵,來探索資料表內的關聯性。 若您需要在子資料表中以不同方式命名的資料行,請在父資料表上設定 referenceKeyName 屬性。 其中一個範例是將 generatedKeyName 設定為 tblDocument 資料表的識別碼,並將 referenceKeyName 設定為 DocumentID。 這會導致 tblEntities 和 tblKeyPhrases 資料表中的資料行包含名為 DocumentID 的文件識別碼。

定義物件投影

物件投影是擴充樹狀結構的 JSON 表示法,可能源自於任何節點。 相較於資料表投影,物件投影更易於定義,並且會在投影整份文件時使用。 物件投影僅限於容器中的單一投影,且無法進行分割。

若要定義物件投影,請使用投影屬性中的 objects 陣列。 物件投影具有三個必要屬性:

Property Description
storageContainer 決定在 Azure 儲存體中建立的新容器名稱。
generatedKeyName 可唯一識別各資料列的索引鍵資料行名稱。 此值是由系統所產生。 如果您省略這個屬性,系統會自動建立一個使用數據表名稱和 “key” 作為命名慣例的數據行。
來源 擴充樹狀結構 (亦即投影的根目錄) 的節點路徑。 節點通常是決定 Blob 結構的複雜資料圖形參考。

下列範例會將個別旅館文件 (每個 Blob 一份旅館文件) 投影至名為 hotels 的容器中。

"knowledgeStore": {
  "storageConnectionString": "an Azure storage connection string",
  "projections" : [
    {
      "tables": [ ]
    },
    {
      "objects": [
        {
        "storageContainer": "hotels",
        "source": "/document/objectprojection",
        }
      ]
    },
    {
        "files": [ ]
    }
  ]
}

來源是名為 "objectprojection" 的塑形器技能輸出。 每個 Blob 都有每個欄位輸入的 JSON 表示法。

    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "name": "#3",
      "description": null,
      "context": "/document",
      "inputs": [
        {
          "name": "HotelId",
          "source": "/document/HotelId"
        },
        {
          "name": "HotelName",
          "source": "/document/HotelName"
        },
        {
          "name": "Category",
          "source": "/document/Category"
        },
        {
          "name": "keyPhrases",
          "source": "/document/HotelId/keyphrases/*"
        },
      ],
      "outputs": [
        {
          "name": "output",
          "targetName": "objectprojection"
        }
      ]
    }

定義檔案投影

檔案投影一律為二進位正規化映像,其中正規化是指在技能集執行中使用的潛在調整大小和旋轉。 檔案投影類似於物件投影,會在 Azure 儲存體中建立為 Blob,並包含二進位資料 (而非 JSON)。

若要定義檔案投影,請使用投影屬性中的 files 陣列。 檔案投影具有三個必要屬性:

Property Description
storageContainer 決定在 Azure 儲存體中建立的新容器名稱。
generatedKeyName 可唯一識別各資料列的索引鍵資料行名稱。 此值是由系統所產生。 如果您省略這個屬性,系統會自動建立一個使用數據表名稱和 “key” 作為命名慣例的數據行。
來源 擴充樹狀結構 (亦即投影的根目錄) 的節點路徑。 對於映像檔案,來源一律為 /document/normalized_images/*。 檔案投影僅對 normalized_images 集合採取動作。 索引子或技能集都不會通過原始的非正規化映像。

目的地一律為 Blob 容器,其中包含文件識別碼 base64 編碼值的資料夾前置詞。 如果有多個影像,它們會放在相同的資料夾中。 檔案投影無法與物件投影共用相同容器,而且必須投影至不同容器中。

在下列範例中,從擴充文件的文件節點中擷取的所有標準化映像會投影至名為 myImages 的容器。

"projections": [
    {
        "tables": [ ],
        "objects": [ ],
        "files": [
            {
                "storageContainer": "myImages",
                "source": "/document/normalized_images/*"
            }
        ]
    }
]

測試預測

您可以依照下列步驟處理投影:

  1. 將知識存放區的 storageConnectionString 屬性設定為有效的 V2 一般用途儲存體帳戶連接字串。

  2. 透過發出 PUT 請求,並在請求主體中附上技能集的投影定義,來更新技能組。

  3. 執行索引器,使技能集開始執行。

  4. 監控索引器的執行 情況,以檢查進度並發現任何錯誤。

  5. 使用 Azure 入口網站,驗證在 Azure 儲存體中的物件建立。

  6. 若您要投影資料表,請將資料表匯入 Power BI 以進行資料表操作和視覺效果。 在大部分情況下,Power BI 會自動探索數據表之間的關聯性。

常見問題

省略下列任何步驟都可能導致非預期的結果。 若輸出看起來不正確,請檢查下列條件。

  • 字串擴充不會塑形為有效的 JSON。 當字串擴充時,例如 merged_content 使用關鍵片語擴充時,擴充屬性會以擴充樹狀結構內的 merged_content 子系表示。 預設表示法不是語式正確的 JSON。 在投影時間,請務必將擴充轉換為具有名稱和值的有效 JSON 物件。 使用 Shaper 技能或定義內嵌圖形有助於解決此問題。

  • 在來源路徑結尾處省略 /*。 如果投影的來源為 /document/projectionShape/keyPhrases,則關鍵片語陣列會投影為單一物件/資料列。 請改將來源路徑設定為 /document/projectionShape/keyPhrases/*,以便為每個關鍵片語產生單一資料列或物件。

  • 路徑語法錯誤。 路徑選擇器 區分大小寫,若未使用完全相同的大小寫,可能會導致缺少輸入警告。

後續步驟

下一個步驟會逐步引導您完成豐富技能集輸出的塑形和投影。 若您的技能集很複雜,下文提供圖形和投影的範例。