將資料成形，以投影至知識存放區

發行項
05/13/2024

在 Azure AI 搜尋服務中，「資料成形」是知識存放區工作流程中的一個步驟，可建立您想要投影到 Azure 儲存體中資料表、物件和檔案之內容的資料表示法。

執行技能時，輸出會寫入節點階層中的擴充樹狀結構，您雖可能想要完整檢視及取用擴充樹狀結構，但可能希望更精細，針對不同的案例建立節點子集，例如將與翻譯文字或擷取實體相關的節點放在特定資料表中。

擴充樹狀結構本身包含的邏輯，不會透露其內容在知識存放區中呈現方式。資料圖形藉由提供每個資料表、物件和檔案投影的架構，來填滿此間距。您可以將資料圖形視為擴充資料的自訂定義或檢視。您可以視需要建立多個圖形，然後將它們指派給知識存放區定義中的投影。

建立圖形的方法

有兩種方式可塑造擴充內容，以便投影到知識存放區：

使用塑形器技能，在明確用於投影的擴充樹狀結構中建立節點。大部分的技能都會建立新的內容。相對的，塑形器技能只會使用現有的節點，通常可將多個節點合併成單一複雜物件。這可用於當您希望在資料表中，將多個節點的輸出實際表示為資料表中的資料行時。
在投影定義本身內使用內嵌圖形。

使用塑形器技能會將圖形外部化，以供多個投影或甚至其他技能使用。這也可確保擴充樹狀結構的所有變動都包含在技能內，而且輸出是可以重複使用的物件。相對的，內嵌成形則可讓您建立所需的圖形，但這會是匿名物件，只適用於所定義的投影。

這些方法可以一起使用或分開使用。本文說明以下兩種情況：資料表投影的塑形器技能，以及使用關鍵字組資料表投影進行內嵌成形。

使用塑形器技能

塑形器工具技能通常會放在技能集的結尾，建立您想要傳遞至投影的資料檢視。本範例會建立名為 "tableprojection" 的圖形，其中包含下列節點："reviews_text"、"reviews_title"、"AzureSearch_DocumentKey"，以及分頁評論中的情感分數和關鍵字組。

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "name": "#5",
    "description": null,
    "context": "/document",
    "inputs": [        
        {
            "name": "reviews_text",
            "source": "/document/reviews_text",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "reviews_title",
            "source": "/document/reviews_title",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "AzureSearch_DocumentKey",
            "source": "/document/AzureSearch_DocumentKey",
            "sourceContext": null,
            "inputs": []
        },  
        {
            "name": "pages",
            "source": null,
            "sourceContext": "/document/reviews_text/pages/*",
            "inputs": [
                {
                    "name": "Sentiment",
                    "source": "/document/reviews_text/pages/*/Sentiment",
                    "sourceContext": null,
                    "inputs": []
                },
                {
                    "name": "LanguageCode",
                    "source": "/document/Language",
                    "sourceContext": null,
                    "inputs": []
                },
                {
                    "name": "Page",
                    "source": "/document/reviews_text/pages/*",
                    "sourceContext": null,
                    "inputs": []
                },
                {
                    "name": "keyphrase",
                    "sourceContext": "/document/reviews_text/pages/*/Keyphrases/*",
                    "inputs": [
                        {
                            "source": "/document/reviews_text/pages/*/Keyphrases/*",
                            "name": "Keyphrases"
                        }
                    ]
                }
            ]
        }
    ],
    "outputs": [
        {
            "name": "output",
            "targetName": "tableprojection"
        }
    ]
}

SourceContext 屬性

在塑形器技能內，輸入可包含 sourceContext 元素。這個相同的屬性也可以在投影中的內嵌圖形使用。

sourceContext 用於建構擴充管線中的多層級巢狀物件。如果輸入與技能內容位於「不同的」內容，請使用 sourceContext。 sourceContext 會要求您以要處理的特定元素作為來源，定義巢狀輸入。

在上述範例中，情感分析和關鍵字組擷取是在分割成頁面的文本上執行，以便更有效率地進行分析。假設您想要將分數和字詞投影到資料表中，則必須將內容設定為提供分數和字詞的巢狀輸入。

將圖形投影到多個資料表

如使用定義於上述 outputs 區段的 tableprojection 節點，可將 tableprojection 節點的部分切片為個別相關的資料表：

"projections": [
    {
        "tables": [
            {
                "tableName": "hotelReviewsDocument",
                "generatedKeyName": "Documentid",
                "source": "/document/tableprojection"
            },
            {
                "tableName": "hotelReviewsPages",
                "generatedKeyName": "Pagesid",
                "source": "/document/tableprojection/pages/*"
            },
            {
                "tableName": "hotelReviewsKeyPhrases",
                "generatedKeyName": "KeyPhrasesid",
                "source": "/document/tableprojection/pages/*/keyphrase/*"
            }
        ]
    }
]

表格投影的內嵌圖形

內嵌成形是能夠在投影定義本身內，形成新圖形的能力。內嵌成形具有下列特性：

圖形只能由包含它的投影使用。
圖形可以與塑形器技能所產生的圖形相同。

使用 sourceContext 和 inputs 建立內嵌圖形。

屬性	說明
sourceContext	設定投影的根。
輸入	每個輸入都是資料表中的資料行。「名稱」是資料行名稱。「來源」是提供值的擴充節點。

若要投影與前一個範例相同的資料，內嵌投影選項會如下所示：

"projections": [
    {
        "tables": [
            {
                "tableName": "hotelReviewsInlineDocument",
                "generatedKeyName": "Documentid",
                "sourceContext": "/document",     
                "inputs": [
                    {
                        "name": "reviews_text",
                        "source": "/document/reviews_text"
                    },
                    {
                        "name": "reviews_title",
                        "source": "/document/reviews_title"
                    },
                    {
                        "name": "AzureSearch_DocumentKey",
                        "source": "/document/AzureSearch_DocumentKey"
                    }                             
                ]
            },
            {
                "tableName": "hotelReviewsInlinePages",
                "generatedKeyName": "Pagesid",
                "sourceContext": "/document/reviews_text/pages/*",
                "inputs": [
                        {
                    "name": "Sentiment",
                    "source": "/document/reviews_text/pages/*/Sentiment"
                    },
                    {
                        "name": "LanguageCode",
                        "source": "/document/Language"
                    },
                    {
                        "name": "Page",
                        "source": "/document/reviews_text/pages/*"
                    }
                ]
            },
            {
                "tableName": "hotelReviewsInlineKeyPhrases",
                "generatedKeyName": "KeyPhraseId",
                "sourceContext": "/document/reviews_text/pages/*/Keyphrases/*",
                "inputs": [
                    {
                        "name": "Keyphrases",
                        "source": "/document/reviews_text/pages/*/Keyphrases/*"
                    }
                ]
            }
        ]
    }
]

可留意這兩種方法各自如何使用 "sourceContext" 來投影 "Keyphrases" 的值。 "Keyphrases" 節點，包含字串集合，本身則為頁面文字的子系。不過，因為投影需要 JSON 物件，而頁面是一個基本類型 (字串)，所以會使用 "sourceContext" 將關鍵字詞包裝到具有命名屬性的物件中。這項技術可以獨立地投影均等基本類型。

物件投影的內嵌圖形

您可以使用塑形器技能產生新的圖形，或使用物件投影的內嵌成形。雖然資料表範例已說明如何建立圖形和切片，本範例仍會示範如何使用內嵌成形。

內嵌成形是在投影輸入的定義中建立新圖形的能力。內嵌成形會建立匿名物件，且會與塑形器既能產生的物件相同 (在此情況為 projectionShape)。如果您不打算重複使用正在定義的圖形，內嵌成形就是很實用的技巧。

投影屬性是陣列。本範例會將新的投影執行個體新增至陣列，其中 knowledgeStore 定義包含內嵌投影。使用內嵌投影時，您可以省略塑形器技能。

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
            {
            "tables": [ ],
            "objects": [
                {
                    "storageContainer": "sampleobject",
                    "source": null,
                    "generatedKeyName": "myobject",
                    "sourceContext": "/document",
                    "inputs": [
                        {
                            "name": "metadata_storage_name",
                            "source": "/document/metadata_storage_name"
                        },
                        {
                            "name": "metadata_storage_path",
                            "source": "/document/metadata_storage_path"
                        },
                        {
                            "name": "content",
                            "source": "/document/content"
                        },
                        {
                            "name": "keyPhrases",
                            "source": "/document/merged_content/keyphrases/*"
                        },
                        {
                            "name": "entities",
                            "source": "/document/merged_content/entities/*/name"
                        },
                        {
                            "name": "ocrText",
                            "source": "/document/normalized_images/*/text"
                        },
                        {
                            "name": "ocrLayoutText",
                            "source": "/document/normalized_images/*/layoutText"
                        }
                    ]

                }
            ],
            "files": []
        }
    ]
}

下一步

本文說明投影圖形的概念和原則。在下一個步驟中，請參閱如何在資料表、物件和檔案投影的模式中套用這些專案。

定義知識存放區中的投影

共用方式為