ナレッジストアへのプロジェクションのためのデータのシェイプ

注

Azure AI 検索は、Azure ポータル、REST API、およびAzure SDKから使用できます。また、Foundry IQ は、エンタープライズコンテンツを、Microsoft Foundry ポータルのエージェントの再利用可能なアクセス許可に対応したナレッジベースに変換するマネージドナレッジレイヤーです。

注

ナレッジストア は、Azure Storage に存在し、Azure AI 検索スキルセットの出力を含むセカンダリストレージです。これらは、エージェントの取得ワークフローで使用されるナレッジソースやナレッジベースとは別です。

Azure AI 検索の、「データのシェイプ」では、ナレッジストアワークフローのステップを説明します。このステップでは、Azure Storage のテーブル、オブジェクト、およびファイルに投影するコンテンツのデータ表現を作成します。

スキルを実行すると、出力はノードの階層内のエンリッチメントツリーに書き込まれます。エンリッチメントツリー全体を表示して使用することもできますが、翻訳されたテキストに関連するノードや抽出されたエンティティを特定のテーブルに配置するなど、さまざまなシナリオでノードのサブセットを作成する、より細かい粒度が必要になる可能性の方が高くなります。

エンリッチメントツリー自体には、ナレッジストアでのコンテンツの表現方法を通知するロジックは含まれません。データシェイプは、各テーブル、オブジェクト、およびファイルプロジェクションに含まれるデータのスキーマを提供することで、このギャップを埋めます。データシェイプは、エンリッチされたデータのカスタム定義またはビューと考えられます。必要な数のシェイプを作成してから、それらをナレッジストア定義のプロジェクションに割り当てることができます。

シェイプを作成するための方法

ナレッジストアに投影できるように、エンリッチされたコンテンツを整形するには、次の 2 つの方法があります。

Shaper スキルを使用し、明示的にプロジェクションに使用されるノードをエンリッチメントツリーに作成します。ほとんどのスキルでは、新しいコンテンツが作成されます。これに対し、Shaper スキルは既存のノードと連携し、通常は複数のノードを 1 つの複雑なオブジェクトに統合します。これは、複数のノードの出力をテーブル内の列として物理的に表現するテーブルに便利です。
プロジェクション定義自体の中では、インラインシェイプを使用します。

Shaper スキルを使用するとシェイプを外部化でき、複数のプロジェクションや他のスキルでも使用できます。また、エンリッチメントツリーのすべての変更がスキル内に格納され、出力が再利用できるオブジェクトとなります。一方でインライン整形では、必要な形状を作成できますが、匿名オブジェクトであり、定義されているプロジェクションでのみ使用できます。

これらの方法は、組み合わせて使用することも、個別に使用することもできます。この記事では、テーブルプロジェクションの Shaper スキルと、キーフレーズテーブルプロジェクションを使用したインラインシェイプの両方について説明します。

Shaper スキルを使用する

通常、Shaper スキルはスキルセットの最後に配置され、プロジェクションに渡すデータのビューを作成します。この例では、"reviews_text"、"reviews_title"、"AzureSearch_DocumentKey" の各ノードと、ページレビューのセンチメントスコアとキーフレーズを含む "tableprojection" という名前のシェイプを作成します。

{
    "@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 プロパティ

Shaper スキル内で、入力は sourceContext エレメントを持つことができます。この同じプロパティを、プロジェクションのインラインシェイプでも使用できます。

sourceContext は、エンリッチメントパイプラインで複数レベルの入れ子になったオブジェクトを構築するために使用されます。入力がスキルコンテキストとは別のコンテキストにある場合は、sourceContext を使用します。 sourceContext には、特定の要素がソースとして扱われる入れ子の入力を定義する必要があります。

前の例では、より効率的な分析のために、ページに分割されたテキストに対して感情分析とキーフレーズ抽出が実行されました。スコアとフレーズをテーブルに射影するには、スコアとフレーズを提供する入れ子になった入力にコンテキストを設定する必要があります。

シェイプを複数のテーブルに射影する

前のセクションのtableprojectionで定義した outputs ノードを使用すると、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/*"
            }
        ]
    }
]

テーブルプロジェクションのインラインシェイプ

インラインシェイプは、プロジェクション定義自体の中で新しいシェイプを形成する機能です。インラインシェイプには、次の特徴があります。

図形は、図形を含むプロジェクションでのみ使用されます。
図形は、Shaper スキルが生成する図形と同じにすることができます。

インラインシェイプは、sourceContext と inputs を使用して作成されます。

プロパティ	説明
sourceContext	プロジェクションのルートを設定します。
inputs	各入力はテーブル内の列です。 Name は列名です。 Source は、値を提供するエンリッチメントノードです。

前の例と同じデータを射影するためのインラインプロジェクションオプションは次のようになります。

"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/*"
                    }
                ]
            }
        ]
    }
]

両方の方法から観察されることの 1 つは、"sourceContext" を使用して "Keyphrases" の値が射影される方法です。文字列のコレクションが含まれる "Keyphrases" ノードは、それ自体がページテキストの子になります。ただし、プロジェクションには JSON オブジェクトが必要であり、ページはプリミティブ (文字列) であるため、"sourceContext" を使用して、キーフレーズが名前付きプロパティを持つオブジェクトにラップされます。この手法を使用すると、プリミティブであっても個別に射影できます。

オブジェクトプロジェクションのインラインシェイプ

Shaper スキルを使用して新しいシェイプを生成するか、またはオブジェクトプロジェクションのインライン整形を使用することができます。テーブルの例ではシェイプの作成とスライスの手法を示しましたが、この例ではインライン整形の使用を例示します。

インライン整形とは、プロジェクションへの入力の定義内で新しいシェイプを作成する機能です。インライン整形では、Shaper スキルによって生成されるもの (この場合は projectionShape) と同じ匿名のオブジェクトが作成されます。再利用する予定がないシェイプを定義する場合は、インライン整形が便利です。

projections プロパティは配列です。この例では、新しいプロジェクションインスタンスを配列に追加しています。そこでは、インラインプロジェクションが knowledgeStore の定義に含まれています。インラインプロジェクションを使用するときは、Shaper スキルを省略することができます。

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

次のステップ

この記事では、プロジェクションシェイプの概念と原則について説明します。次のステップとして、テーブル、オブジェクト、およびファイルプロジェクションのパターンでこれらがどのように適用されるのかについて説明します。

ナレッジストアでのプロジェクションを定義する

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-10-21