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

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

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

下載範例定義

此範例使用Postman Desktop 應用程式和搜尋 REST API

複製或下載GitHub上的azure-search-postman-samples,並匯入Projections 集合,以自行逐步執行此範例。

設定範例資料

範例檔未特別包含在投影集合中,但來自 azure-search-sample-data 存放庫AI 擴充示範資料檔案包含文字和影像,而且將使用此範例中所述的投影。

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

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

範例技能集

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

請密切注意 targetNames) (技能輸出。 寫入擴充檔樹狀結構的輸出會透過 Shaper 技能) 來參考投影和圖形 (。

{
    "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
}

範例 Shaper 技能

Shaper 技能是使用現有擴充內容的公用程式,而不是建立新的擴充內容。 將 Shaper 新增至技能集可讓您建立可投影到資料表或 Blob 儲存體的自訂圖形。 如果沒有自訂圖形,投影僅限於參考單一節點 (每個輸出) 一個投影,這不適用於資料表。 建立自訂圖形會將各種元素匯總成可投影為單一資料表的新邏輯整個,或交叉分析並分散到資料表集合中。

在此範例中,自訂圖形結合了 Blob 中繼資料和識別的實體和關鍵字組。 自訂圖形稱為 projectionShape ,且會在 下 /document 父代。

成形的其中一個目的是要確保所有擴充節點都是以格式正確的 JSON 來表示,這是投影到知識存放區的必要條件。 當擴充樹狀結構包含格式不正確之 JSON 的節點 (例如,當擴充父代為字串之類的基本類型) 時,這特別適用。

請注意最後兩個節點和 KeyPhrasesEntities 。 這些會包裝成具有 的有效 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 新增至技能集

本文開頭所介紹的範例技能集不包含 Shaper 技能,但 Shaper 技能屬於技能集,而且通常會放在結尾。

在技能集中,Shaper 技能看起來可能像這樣:

    "name": "projections-demo-ss",
    "skills": [
        {
            <Shaper skill goes here>
            }
        ],
    "cognitiveServices":  "A key goes here",
    "knowledgeStore": []
}  

投影至資料表

在上述範例上繪製,有一個已知數量的擴充和資料圖形可以在資料表投影中參考。 在下方的資料表投影中,設定 和 sourcegeneratedKeyName 屬性會定義 tableName 三個數據表。

這三個數據表都會透過產生的索引鍵和共用父 /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 屬性。 其中一個範例是將 tblDocument 資料表上的 設定 generatedKeyName 為識別碼,並將 referenceKeyName 設定為 DocumentID。 這會導致 tblEntities 和 tblKeyPhrases 資料表中的資料行包含名為 DocumentID 的檔識別碼。

投影 Blob 檔

物件投影是擴充樹狀結構的 JSON 標記法,可從任何節點進行來源。 相較于資料表投影,物件投影比較容易定義,而且會在投影整個檔時使用。 物件投影僅限於容器中的單一投影,而且無法進行配量。

若要定義物件投影,請使用 objects 投影屬性中的陣列。

來源是擴充樹狀結構節點的路徑,該節點是投影的根目錄。 雖然並非必要,但節點路徑通常是 Shaper 技能的輸出。 這是因為大部分的技能不會自行輸出有效的 JSON 物件,這表示需要某種形式的成形。 在許多情況下,建立資料表投影的相同 Shaper 技能可用來產生物件投影。 或者,來源也可以設定為具有 內嵌成形 的節點,以提供 結構。

目的地一律是 Blob 容器。

下列範例會將個別旅館檔每個 Blob 一份旅館檔投影到名為 的 hotels 容器中。

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

來源是名為 「objectprojection」 的 Shaper 技能輸出。 每個 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. 建立與檔資料表相關的資料表,並將每個關鍵字組識別為此表格中的資料列。
  3. 建立與檔資料表相關的資料表,並將每個實體識別為此表格中的資料列。
  4. 使用每個影像的配置文字建立物件投影。
  5. 建立檔案投影,投影每個擷取的影像。
  6. 建立交叉參照資料表,其中包含檔資料表的參考、具有版面配置文字的物件投影,以及檔案投影。

交叉投影的圖形資料

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

後續步驟

本文中的範例示範如何建立投影的常見模式。 既然您已充分瞭解概念,您就更適合針對特定案例建置投影。