知識存放區中的圖形和投影的詳細範例

本文提供詳細的範例來補充 高階概念語法型文章 ,方法是逐步解說在 知識存放區中完整表達豐富技能集輸出所需的成形和投影步驟。

如果您的應用程式需求呼叫多個技能和投影,此範例可讓您更瞭解圖案和投影的交集。

下載範例定義

此範例會使用 Postman 桌面應用程式搜尋 REST api

複製或下載 GitHub 上的 azure-搜尋-postman-範例並匯入 投影集合,以逐步執行此範例。

設定範例資料

範例檔不會特別包含在投射集合中,但AI 擴充示範資料存放庫中的資料檔案會包含文字和影像,並會使用此範例中所述的預測。

在 Azure 儲存體中建立 blob 容器,並上傳所有14個專案。

在 Azure 儲存體中,複製連接字串,讓您可以在 Postman 集合中指定它。

範例技能集

若要瞭解圖案和投影之間的相依性,請參閱下列可建立豐富內容的技能集。 此技能集會處理原始影像和文字,以產生將在圖形和投影中參考的輸出。

請密切注意技能輸出 (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": "A Cognitive Services resource in the same region as Search.",
        "key": "<COGNITIVE SERVICES All-in-ONE KEY>"
    },
    "knowledgeStore": null
}

範例整形技巧

整形工具技能是使用現有擴充內容的公用程式,而不是建立新的豐富內容。 將塑造程式新增至技能集,可讓您建立可投影至資料表或 blob 儲存體的自訂圖形。 如果沒有自訂圖形,投影會限制為參考單一節點, (每個輸出) 一個投射,這不適用於資料表。 建立自訂圖形會將各種元素匯總成一個新的邏輯,以投射為單一資料表,或是在資料表集合中切割和散發。

在此範例中,自訂圖形結合了 blob 中繼資料和已識別的實體和關鍵字組。 呼叫自訂圖形 projectionShape ,並以父系為其父代 /document

成形的其中一個目的是確保所有擴充節點都以正確格式的 JSON 表示,這是投射到知識存放區時所需的。 當擴充樹狀結構包含的節點不是格式正確的 (JSON 時(例如,當擴充的父代像是字串) )時,更是如此。

請注意最後兩個節點, KeyPhrases 以及 Entities 。 這些會使用來包裝成有效的 JSON 物件 sourceContext 。 這是必要的 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"
        }
    ]
}

將 Shapers 新增至技能集

本文開頭所引進的範例技能集不包含整形程式技能,但整形者技能屬於技能集,通常會放在結尾。

在技能集中,「整形」技能可能如下所示:

    "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": []
        }
    ]
}

儲存您的工作

您可以依照下列步驟來檢查投射定義:

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

  2. 藉由發出 PUT 要求來更新技能集。

  3. 更新技能集之後,請執行索引子。

您現在有三個數據表的工作投射。 將這些資料表匯入 Power BI應該會導致 Power BI 自動探索關聯性。

繼續進行下一個範例之前,讓我們先回顧一下資料表投射的各個層面,以瞭解切割和關聯資料的機制。

將資料表切割成多個子資料工作表

配量是一種技術,可將整個合併圖形細分組成零件。 結果包含個別但相關的資料表,您可以個別使用這些資料表。

在此範例中, projectionShape 是合併圖形 (或擴充節點) 。 在投射定義中, projectionShape 會切割成其他資料表,讓您提取圖形的各部分, keyPhrases 以及 Entities 。 在 Power BI 中,這項功能很有用,因為有多個實體和 keyPhrases 與每個檔相關聯,而如果您可以將實體和 keyPhrases 視為分類的資料,您將會獲得更多的見解。

配量會以隱含方式產生父資料表與子資料工作表之間的關聯性,並使用 generatedKeyName 父資料表中的,在子資料工作表中建立具有相同名稱的資料行。

命名關聯性

generatedKeyNamereferenceKeyName 屬性是用來在資料表之間建立關聯,甚至是跨投影類型。 子資料工作表中的每個資料列都有一個指向父系的屬性。 子系中的資料行或屬性名稱是 referenceKeyName 來自父系的。 當 referenceKeyName 未提供時,服務會將其預設為 generatedKeyName 來自父系的。

Power BI 依賴這些產生的金鑰來探索資料表內的關聯性。 如果您需要以不同方式命名的子資料工作表中的資料行,請在 referenceKeyName 父資料表上設定屬性。 其中一個範例是在 generatedKeyName tblDocument 資料表上設定 AS 識別碼,並將設定為 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 結果和版面配置文字儲存為物件,然後將影像投射為檔案。

多個投影類型的步驟:

  1. 建立每個檔都有一個資料列的資料表。
  2. 建立與 document 資料表相關的資料表,其中每個主要片語都識別為此資料表中的一個資料列。
  3. 建立與 document 資料表相關的資料表,其中每個實體都識別為此資料表中的一個資料列。
  4. 使用每個影像的版面配置文字來建立物件投射。
  5. 建立檔案投射,並投射每個已解壓縮的影像。
  6. 建立包含檔資料表參考、具有版面配置文字的物件投影,以及檔案投射的交叉參考資料表。

針對交叉投射塑造資料

若要取得這些投影所需的圖形,請先加入新的成形技能,以建立稱為的成形物件 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": []
        }
    ]
}

下一步

本文中的範例將示範如何建立投影的一般模式。 現在您已充分瞭解這些概念,您可以更妥善地針對特定案例建立投影。