知識存放區中圖形和投影的詳細範例
本文提供詳細範例，逐步解說完整表達知識存放區中豐富技能集輸出所需的塑形和投影步驟，進而補充高階概念和語法型文章。
如果您的應用程式需求要求多個技能和投影，此範例可讓您更清楚了解圖形和投影如何交集。
設定範例資料
範例文件並未隨附於投影集合中，但 AI 擴充示範資料檔案包含文字和影像，並將使用此範例中所述的投影。
在 Azure 儲存體中建立 Blob 容器，並上傳所有 14 個項目。
在 Azure 儲存體中，複製連接字串。
您可以使用 projections.rest 檔案來執行本文中的範例。
範例技能集
若要了解圖形和投影之間的相依性，請檢閱下列建立擴充內容的技能集。 此技能集會處理原始影像和文字，產生將在圖形和投影中參考的輸出。
請密切注意技能輸出 (targetNames)。 寫入擴充文件樹狀結構的輸出會在投影和圖形中參考 (透過塑形器技能)。
{
"name": "projections-demo-ss",
"description": "Skillset that enriches blob data found in "merged_content". The enrichment granularity is a document.",
"skills": [
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"name": "#1",
"description": null,
"context": "/document/merged_content",
"categories": [
"Person",
"Quantity",
"Organization",
"URL",
"Email",
"Location",
"DateTime"
],
"defaultLanguageCode": "en",
"minimumPrecision": null,
"inputs": [
{
"name": "text",
"source": "/document/merged_content"
},
{
"name": "languageCode",
"source": "/document/language"
}
],
"outputs": [
{
"name": "persons",
"targetName": "people"
},
{
"name": "organizations",
"targetName": "organizations"
},
{
"name": "locations",
"targetName": "locations"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
"name": "#2",
"description": null,
"context": "/document/merged_content",
"defaultLanguageCode": "en",
"maxKeyPhraseCount": null,
"inputs": [
{
"name": "text",
"source": "/document/merged_content"
},
{
"name": "languageCode",
"source": "/document/language"
}
],
"outputs": [
{
"name": "keyPhrases",
"targetName": "keyphrases"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
"name": "#3",
"description": null,
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_content"
}
],
"outputs": [
{
"name": "languageCode",
"targetName": "language"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.MergeSkill",
"name": "#4",
"description": null,
"context": "/document",
"insertPreTag": " ",
"insertPostTag": " ",
"inputs": [
{
"name": "text",
"source": "/document/content"
},
{
"name": "itemsToInsert",
"source": "/document/normalized_images/*/text"
},
{
"name": "offsets",
"source": "/document/normalized_images/*/contentOffset"
}
],
"outputs": [
{
"name": "mergedText",
"targetName": "merged_content"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
"name": "#5",
"description": null,
"context": "/document/normalized_images/*",
"textExtractionAlgorithm": "printed",
"lineEnding": "Space",
"defaultLanguageCode": "en",
"detectOrientation": true,
"inputs": [
{
"name": "image",
"source": "/document/normalized_images/*"
}
],
"outputs": [
{
"name": "text",
"targetName": "text"
},
{
"name": "layoutText",
"targetName": "layoutText"
}
]
}
],
"cognitiveServices": {
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "An Azure AI services resource in the same region as Search.",
"key": "<Azure AI services All-in-ONE KEY>"
},
"knowledgeStore": null
}
範例塑形器技能
塑形器技能是公用程式，用於處理現有擴充內容，而非建立新的擴充內容。 將塑形器新增至技能集，可讓您建立可投影到資料表或 Blob 儲存體的自訂圖形。 如果沒有自訂圖形，投影會限制於參考單一節點 (每個輸出一個投影)，這並不適用於資料表。 建立自訂圖形會將各種元素彙總成新邏輯，可完全投影成單一資料表或進行分割並散發到整個資料表集合中。
在此範例中，自訂圖形會結合 Blob 中繼資料和已識別的實體與主要片語。 自訂圖形稱為 projectionShape，並在 /document 下作為父項。
塑形的其中一個目的是確保所有擴充節點以語式正確的 JSON 表示，這是投影到知識存放區的必要動作。 當擴充樹狀結構包含並非語式正確 JSON 的節點時，尤其如此 (例如當擴充作為如字串的基本類型父項時)。
請注意最後兩個節點：KeyPhrases 和 Entities。 這些項目會包裝成含 sourceContext 的有效 JSON 物件。 這是必要項目，因為 keyphrases 和 entities 是基本類型的擴充且必須先轉換成有效 JSON，才可進行投影。
{
"@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
"name": "ShaperForTables",
"description": null,
"context": "/document",
"inputs": [
{
"name": "metadata_storage_content_type",
"source": "/document/metadata_storage_content_type",
"sourceContext": null,
"inputs": []
},
{
"name": "metadata_storage_name",
"source": "/document/metadata_storage_name",
"sourceContext": null,
"inputs": []
},
{
"name": "metadata_storage_path",
"source": "/document/metadata_storage_path",
"sourceContext": null,
"inputs": []
},
{
"name": "metadata_content_type",
"source": "/document/metadata_content_type",
"sourceContext": null,
"inputs": []
},
{
"name": "keyPhrases",
"source": null,
"sourceContext": "/document/merged_content/keyphrases/*",
"inputs": [
{
"name": "KeyPhrases",
"source": "/document/merged_content/keyphrases/*"
}
]
},
{
"name": "Entities",
"source": null,
"sourceContext": "/document/merged_content/entities/*",
"inputs": [
{
"name": "Entities",
"source": "/document/merged_content/entities/*/name"
}
]
}
],
"outputs": [
{
"name": "output",
"targetName": "projectionShape"
}
]
}
將塑形器新增至資料集
本文開頭介紹的範例技能集不包含塑形器技能，但塑形器技能屬於資料集且通常會置於結尾。
在技能集內，塑形器技能可能如下所示：
{
"name": "projections-demo-ss",
"skills": [
{
<Shaper skill goes here>
}
],
"cognitiveServices": "A key goes here",
"knowledgeStore": []
}
投影到資料表
在上述範例上繪製時，有已知數量的擴充和資料圖形，可在資料表投影中參考。 在下方資料圖表投影中，三個資料表已透過設定 tableName、source 和 generatedKeyName 屬性來定義。
所有三個資料表會透過產生的金鑰，由共用父系 /document/projectionShape 相關聯。
"knowledgeStore" : {
"storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
"projections": [
{
"tables": [
{
"tableName": "tblDocument",
"generatedKeyName": "Documentid",
"source": "/document/projectionShape"
},
{
"tableName": "tblKeyPhrases",
"generatedKeyName": "KeyPhraseid",
"source": "/document/projectionShape/keyPhrases/*"
},
{
"tableName": "tblEntities",
"generatedKeyName": "Entityid",
"source": "/document/projectionShape/Entities/*"
}
],
"objects": [],
"files": []
}
]
}
儲存您的工作
您可遵循下列步驟，檢查投影定義：
將知識存放區的
storageConnectionString屬性設定為有效的 V2 一般用途儲存體帳戶連接字串。發出 PUT 要求，藉以更新技能集。
更新技能集之後，請執行索引子。
您現在有工作投影及包含的三個資料表。 將這些資料表匯入 Power BI 應會導致 Power BI 探索關聯性。
繼續進行下一個範例之前，讓我們重新瀏覽資料表投影的各層面，了解分割和關聯資料的機制。
將資料表分割成多個子資料表
分割是一種技術，用於將整個合併圖形細分成組成部分。 結果包含不同但關聯的資料表，您可個別使用。
在範例中，projectionShape 是合併圖形 (或擴充節點)。 在投影定義中，projectionShape 會分割成額外的資料表，這可讓您提取圖形的部分：keyPhrases 和 Entities。 這在 Power BI 中非常實用，因為多個實體和 keyPhrases 會與每個文件相關聯，而且如果您可將實體和 keyPhrases 視為分類的資料，您將取得更多見解。
分割隱含產生父與子資料表之間的關聯，在父資料表中使用 generatedKeyName 來建立與子資料表名稱相同的資料行。
命名關聯性
generatedKeyName 和 referenceKeyName 屬性可用於與資料建立關聯，無論是跨資料表或甚至是跨投影類型。 子資料表中的每個資料列都有指回父代的屬性。 子系中資料行或屬性的名稱是父代中的 referenceKeyName。 若未提供 referenceKeyName，服務會將其預設為來自上層的 generatedKeyName。
Power BI 依賴這些產生的索引鍵，來探索資料表內的關聯性。 若您需要在子資料表中以不同方式命名的資料行，請在父資料表上設定 referenceKeyName 屬性。 其中一個範例是將 generatedKeyName 設定為 tblDocument 資料表的識別碼，並將 referenceKeyName 設定為 DocumentID。 這會導致 tblEntities 和 tblKeyPhrases 資料表中的資料行包含名為 DocumentID 的文件識別碼。
投影 Blob 文件
物件投影是擴充樹狀結構的 JSON 表示法，可能源自於任何節點。 相較於資料表投影，物件投影更易於定義，並且會在投影整份文件時使用。 物件投影僅限於容器中的單一投影，且無法進行分割。
若要定義物件投影，請使用投影屬性中的 objects 陣列。
來源是擴充樹狀結構 (亦即投影的根目錄) 的節點路徑。 雖然這並非必要，但節點路徑通常是塑形器技能的輸出。 這是因為大部分技能都不會自行輸出有效的 JSON 物件，這表示需要某種形式的塑形。 在許多情況下，建立資料表投影的相同塑形器技能可用來產生物件投影。 或者，來源也可設定為含內嵌塑形的節點，以提供結構。
目的地一律是 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，並包含影像。
若要定義檔案投影，請使用投影屬性中的 files 陣列。
來源一律為 /document/normalized_images/*。 檔案投影僅對 normalized_images 集合採取動作。 索引子或技能集都不會通過原始的非正規化映像。
目的地一律為 Blob 容器，其中包含文件識別碼 base64 編碼值的資料夾前置詞。 檔案投影無法與物件投影共用相同容器，而且必須投影至不同容器中。
在下列範例中，從擴充文件的文件節點中擷取的所有標準化映像會投影至名為 myImages 的容器。
"knowledgeStore" : {
"storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
"projections": [
{
"tables": [ ],
"objects": [ ],
"files": [
{
"storageContainer": "myImages",
"source": "/document/normalized_images/*"
}
]
}
]
}
投影到多個類型
較複雜的案例可能會要求您在投影類型之間投影內容。 例如，將關鍵片語和實體投影到資料表，將文字的 OCR 結果儲存為物件，然後將影像投影為檔案。
多個投影類型的步驟：
- 建立每個文件的資料表和包含的資料列。
- 建立與文件資料表相關的資料表，其中將每個關鍵片語識別為此資料表中的資料列。
- 建立與文件資料表相關聯的資料表，其中將每個實體識別為此資料表中的資料列。
- 建立物件投影，其中包含每個影像的配置文字。
- 建立檔案投影以投影每個擷取的影像。
- 建立交互參考資料表，其中包含文件資料表參考、包含配置文字的物件投影和文件投影。
交叉投影的圖形資料
若要取得這些投影所需的圖形，請先新增新的塑形技能以建立名為 crossProjection 的塑形物件。
{
"@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
"name": "ShaperForCrossProjection",
"description": null,
"context": "/document",
"inputs": [
{
"name": "metadata_storage_name",
"source": "/document/metadata_storage_name",
"sourceContext": null,
"inputs": []
},
{
"name": "keyPhrases",
"source": null,
"sourceContext": "/document/merged_content/keyphrases/*",
"inputs": [
{
"name": "KeyPhrases",
"source": "/document/merged_content/keyphrases/*"
}
]
},
{
"name": "entities",
"source": null,
"sourceContext": "/document/merged_content/entities/*",
"inputs": [
{
"name": "Entities",
"source": "/document/merged_content/entities/*/name"
}
]
},
{
"name": "images",
"source": null,
"sourceContext": "/document/normalized_images/*",
"inputs": [
{
"name": "image",
"source": "/document/normalized_images/*"
},
{
"name": "layoutText",
"source": "/document/normalized_images/*/layoutText"
},
{
"name": "ocrText",
"source": "/document/normalized_images/*/text"
}
]
}
],
"outputs": [
{
"name": "output",
"targetName": "crossProjection"
}
]
}
定義資料表、物件和檔案投影
從合併的 crossProjection 物件中，將物件分割成都個資料表，將 OCR 輸出擷取為 Blob，然後將影像儲存為檔案 (Blob 儲存體)。
"knowledgeStore" : {
"storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
"projections": [
{
"tables": [
{
"tableName": "crossDocument",
"generatedKeyName": "Id",
"source": "/document/crossProjection"
},
{
"tableName": "crossEntities",
"generatedKeyName": "EntityId",
"source": "/document/crossProjection/entities/*"
},
{
"tableName": "crossKeyPhrases",
"generatedKeyName": "KeyPhraseId",
"source": "/document/crossProjection/keyPhrases/*"
},
{
"tableName": "crossReference",
"generatedKeyName": "CrossId",
"source": "/document/crossProjection/images/*"
}
],
"objects": [
{
"storageContainer": "crossobject",
"generatedKeyName": "crosslayout",
"source": null,
"sourceContext": "/document/crossProjection/images/*/layoutText",
"inputs": [
{
"name": "OcrLayoutText",
"source": "/document/crossProjection/images/*/layoutText"
}
]
}
],
"files": [
{
"storageContainer": "crossimages",
"generatedKeyName": "crossimages",
"source": "/document/crossProjection/images/*/image"
}
]
}
]
}
物件投影需要每個投影的容器名稱。 物件投影和檔案投影無法共用容器。
資料表、物件和檔案投影之間的關聯
此範例也強調投影的其他功能。 透過在相同投影物件內定義多種投影類型，在不同類型 (資料表、物件、檔案) 內和之間表示關聯性。 這可讓您從文件的資料表列開始，並在物件投影中尋找該文件內影像的所有 OCR 文字。
如果您不想要讓資料相關，請在不同投影群組中定義投影。 例如，下列程式碼片段會促使資料表相關，但資料表和物件 (OCR 文字) 投影之間並無關聯。
當您想要依照不同需求在不同圖形中投影相同資料時，投影群組會非常實用。 例如，投影群組用於 Power BI 儀表板，以及其他投影群組用於擷取資料，該資料用於定型使用自訂技能包裝的學習機器模型。
建置不同類型的投影時，會先產生檔案和物件投影，接著路徑會新增至資料表。
"knowledgeStore" : {
"storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
"projections": [
{
"tables": [
{
"tableName": "unrelatedDocument",
"generatedKeyName": "Documentid",
"source": "/document/projectionShape"
},
{
"tableName": "unrelatedKeyPhrases",
"generatedKeyName": "KeyPhraseid",
"source": "/document/projectionShape/keyPhrases"
}
],
"objects": [
],
"files": []
},
{
"tables": [],
"objects": [
{
"storageContainer": "unrelatedocrtext",
"source": null,
"sourceContext": "/document/normalized_images/*/text",
"inputs": [
{
"name": "ocrText",
"source": "/document/normalized_images/*/text"
}
]
},
{
"storageContainer": "unrelatedocrlayout",
"source": null,
"sourceContext": "/document/normalized_images/*/layoutText",
"inputs": [
{
"name": "ocrLayoutText",
"source": "/document/normalized_images/*/layoutText"
}
]
}
],
"files": []
}
]
}
下一步
本文中的範例示範如何建立投影的常見模式。 現在您充分了解概念，您已具備所需的知識以建置特定案例的投影。