定義知識存放區中的投影

發行項
09/03/2024

投影是知識存放區定義的元件，可決定 AI 擴充內容儲存在 Azure 儲存體中的方式。投影會決定包含您內容的資料結構類型、數量和組合。

在本文中，了解每種投影類型的語法：

資料表投影
物件投影
檔案投影

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

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

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

提示

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

需求

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

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

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

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

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

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

定義資料表投影

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

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

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

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

注意

資料表投影受限於 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 陣列。物件投影具有三個必要屬性：

屬性	說明
storageContainer	決定在 Azure 儲存體中建立的新容器名稱。
generatedKeyName	可唯一識別各資料列的索引鍵資料行名稱。此值是由系統所產生。如果您省略此屬性，系統會自動建立使用資料表名稱和「索引鍵」作為命名慣例的資料行。
來源	擴充樹狀結構 (亦即投影的根目錄) 的節點路徑。節點通常是決定 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 陣列。檔案投影具有三個必要屬性：

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

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

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

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

測試投影

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

將知識存放區的 storageConnectionString 屬性設定為有效的 V2 一般用途儲存體帳戶連接字串。
在技能集主體中使用投影定義發出 PUT 要求，藉此更新技能集。
執行索引子以便推動技能集執行。
監視索引子執行以便檢查進度並攔截任何錯誤。
使用 Azure 入口網站，驗證在 Azure 儲存體中的物件建立。
若您要投影資料表，請將資料表匯入 Power BI 以進行資料表操作和視覺效果。在大部分情況下，Power BI 會自動探索資料表之間的關聯性。

常見問題

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

字串擴充不會塑形為有效的 JSON。當字串擴充時，例如 merged_content 使用關鍵片語擴充時，擴充屬性會以擴充樹狀結構內的 merged_content 子系表示。預設表示法不是語式正確的 JSON。在投影時間，請務必將擴充轉換為具有名稱和值的有效 JSON 物件。使用塑形器技能或定義內嵌圖形，將有助於解決此問題。
在來源路徑結尾處省略 /*。如果投影的來源為 /document/projectionShape/keyPhrases，則關鍵片語陣列會投影為單一物件/資料列。請改將來源路徑設定為 /document/projectionShape/keyPhrases/*，以便為每個關鍵片語產生單一資料列或物件。
路徑語法錯誤。路徑選取器會區分大小寫，若您未針對選取器使用確切大小寫，可能會導致輸入警告遺失。

下一步

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

圖形和投影的詳細範例

共用方式為