Příklad obrazců a projekcí v úložišti znalostí

Tento článek obsahuje podrobný příklad, který doplňuje základní koncepty a články založené na syntaxi tím, že vás provede kroky formování a projekce potřebné k úplnému vyjádření výstupu bohaté sady dovedností v úložišti znalostí ve službě Azure Storage.

Pokud požadavky vaší aplikace vyžadují více dovedností a projekcí, můžete v tomto příkladu lépe zjistit, jak obrazce a projekce interagují.

Nastavení ukázkových dat

Ukázkové dokumenty nejsou součástí kolekce Projekce, ale ukázkové datové soubory pro rozšiřování AI obsahují text a obrázky, které pracují s projekcemi popsanými v tomto příkladu. Pokud použijete tato ukázková data, můžete přeskočit krok, který připojí prostředek Microsoft Foundry , protože zůstanete pod denním limitem indexeru pro bezplatné rozšiřování.

Vytvořte v Azure Storage kontejner objektů blob a nahrajte všechny 14 položek.

V Azure Storage zkopírujte připojovací řetězec.

Soubor projections.rest můžete použít ke spuštění příkladů v tomto článku.

Příklad sady dovedností

Pokud chcete porozumět závislosti mezi obrazci a projekcemi, projděte si následující sadu dovedností, která vytváří obohacený obsah. Tato sada dovedností zpracovává nezpracované obrázky i text a vytváří výstupy, na které se budou odkazovat v obrazcích a projekcích.

Věnujte pozornost výstupům dovedností (targetNames). Výstupy psané do rozšířeného stromu dokumentů jsou odkazovány v projekcích a obrazcích (prostřednictvím Shaper skills).

{
    "name": "projections-demo-ss",
    "description": "Skillset that enriches blob data found in the merged_content field. 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 Foundry resource in the same region as Search.",
        "key": "{{cognitive-services-key}}"
    },
    "knowledgeStore": null
}

Příklad dovednosti shaperu

Schopnost Shaper je pomůcka pro práci s existujícím rozšířeným obsahem, místo vytváření nového rozšířeného obsahu. Přidáním Shaperu do sady dovedností můžete vytvořit vlastní obrazec, který můžete promítnout do úložiště tabulek nebo objektů blob. Bez vlastního obrazce jsou projekce omezené na odkazování na jeden uzel (jednu projekci na výstup), což není vhodné pro tabulky. Vytvoření vlastního obrazce agreguje různé prvky do nového logického celku, který lze promítnut jako jednu tabulku nebo rozdělit a distribuovat napříč kolekcí tabulek.

V tomto příkladu vlastní obrazec kombinuje metadata objektů blob a identifikované entity a klíčové fráze. Vlastní obrazec se nazývá projectionShape a je podřazena pod /document.

Jedním z účelů tvarování je zajistit, aby se všechny uzly rozšiřování vyjadřovaly ve formátu JSON ve správném formátu, který je nutný pro promítání do úložiště znalostí. To platí zejména v případě, že strom rozšiřování obsahuje uzly, které nejsou ve správném formátu JSON (například když je rozšiřování nadřazené primitivnímu typu řetězce).

Všimněte si posledních dvou uzlů KeyPhrases a Entities. Tyto objekty jsou zabalené do platného objektu JSON s objektem sourceContext. Je to nutné, protože keyphrases a entities jsou rozšíření primitiv a před jejich projekcí je třeba je převést na platný 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"
        }
    ]
}

Přidání "Shaperů" do sady dovedností

Ukázková sada dovedností představená na začátku tohoto článku neobsahuje dovednost Shaper, ale dovednosti Shaper patří do sady dovedností a často se umístí na konec.

V sadě dovedností může dovednost Shaper vypadat takto:

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

Promítání do tabulek

Na základě výše uvedených příkladů existuje známé množství rozšiřování a obrazců dat, na které lze odkazovat v projekcích tabulek. V projekci níže uvedených tabulek jsou tři tabulky definovány nastavením vlastností tableName, source a generatedKeyName.

Všechny tři z těchto tabulek budou souviset prostřednictvím vygenerovaných klíčů a sdíleným nadřazeným objektem /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": []
        }
    ]
}

Otestujte svou práci

Definice projekce můžete zkontrolovat pomocí následujících kroků:

1. Nastavte vlastnost úložiště znalostí storageConnectionString na platný připojovací řetězec k účtu úložiště pro obecné účely verze 2.

2. Aktualizujte sadu dovedností vydáním požadavku PUT.

3. Po aktualizaci sady dovedností spusťte indexer.

Teď máte funkční projekci se třemi tabulkami. Import těchto tabulek do Power BI by měl vést ke zjištění relací v Power BI.

Než přejdeme k dalšímu příkladu, pojďme se vrátit k aspektům projekce tabulky, abychom pochopili mechaniku řezů a souvisejících dat.

Rozdělení tabulky na několik podřízených tabulek

Řezy jsou technika, která rozděluje celý konsolidovaný tvar do složek. Výsledek se skládá z samostatných, ale souvisejících tabulek, se kterými můžete pracovat jednotlivě.

V tomto příkladu je projectionShape konsolidovaný tvar (nebo uzel obohacení). V definici projekce projectionShape je rozdělen do dalších tabulek, což vám umožňuje vytáhnout části obrazce keyPhrases a Entities. V Power BI je to užitečné, protože ke každému dokumentu je přidruženo více entit a klíčových frází a získáte další přehledy, pokud uvidíte entity a klíčové fráze jako data zařazená do kategorií.

Řezání implicitně generuje relaci mezi nadřazenými a podřízenými tabulkami použitím generatedKeyName v nadřazené tabulce pro vytvoření sloupce se stejným názvem v podřízené tabulce.

Vztahy pojmenování

Tyto vlastnosti generatedKeyName a referenceKeyName se používají pro propojení dat mezi tabulkami nebo dokonce napříč typy projekce. Každý řádek v podřízené tabulce má vlastnost, která odkazuje zpět na nadřazenou tabulku. Název sloupce nebo vlastnosti v podřízeném objektu je referenceKeyName z nadřazeného objektu. referenceKeyName Pokud není poskytnuto, služba se nastaví na generatedKeyName z rodičovské úrovně.

Power BI využívá tyto vygenerované klíče ke zjišťování relací v tabulkách. Pokud chcete, aby měl sloupec v podřízené tabulce jiný název, nastavte vlastnost referenceKeyName v nadřazené tabulce. Jedním z příkladů by bylo nastavit generatedKeyName jako ID v tabulce tblDocument a referenceKeyName jako DocumentID. Výsledkem by byl sloupec v tabulkách tblEntities a tblKeyPhrases obsahující ID dokumentu s názvem DocumentID.

Promítání dokumentů blob

Projekce objektů představují reprezentaci stromu rozšiřování JSON, který lze získat z libovolného uzlu. Ve srovnání s projekcemi tabulek jsou projekce objektů jednodušší definovat a používají se při promítání celých dokumentů. Projekce objektů jsou omezené na jednu projekci v kontejneru a nelze je rozdělit.

Chcete-li definovat projekci objektu, použijte objects pole ve vlastnosti projekce.

Zdrojem je cesta k uzlu v obohacovacím stromu, který je kořenem projekce. I když to není povinné, cesta k uzlu je obvykle výstupem dovednosti Shaper. Je to proto, že většina dovedností nevytváří platné objekty JSON samy o sobě, což znamená, že je nutné jejich formátování. V mnoha případech lze ke generování projekce objektu použít stejnou dovednost Shaper, která vytváří projekci tabulky. Případně je možné zdroj nastavit také na uzel s vloženým formátováním, které poskytuje strukturu.

Cíl je vždy blobový kontejner.

Následující příklad projektuje jednotlivé hotelové dokumenty, přičemž každý hotelový dokument se nachází v samostatném objektu blob, do kontejneru pojmenovaného hotels.

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

Zdrojem je výstup dovednosti Shaper s názvem "objectprojection". Každý objekt blob bude mít reprezentaci JSON každého vstupu pole.

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

Promítání souboru obrázku

Projekce souborů jsou vždy binární, normalizované obrázky, kde normalizace označuje potenciální změnu velikosti a otočení pro použití při provádění sady dovedností. Projekce souborů, podobně jako projekce objektů, se vytvářejí jako objekty blob ve službě Azure Storage a obsahují obrázek.

Chcete-li definovat projekci souboru, použijte files pole ve vlastnosti projekce.

Zdroj je vždy /document/normalized_images/*. Projekce souborů fungují pouze s kolekcí normalized_images . Indexery ani sada schopností neprojdou původním nenormalizovaným obrázkem.

Cílem je vždy kontejner typu blob s předponou složky zakódovanou ve formátu base64 z ID dokumentu. Projekce souborů nemůžou sdílet stejný kontejner jako projekce objektů a je potřeba je promítnout do jiného kontejneru.

Následující příklad projektuje všechny normalizované obrázky extrahované z uzlu dokumentu obohaceného dokumentu do kontejneru nazývaného myImages.

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
        {
            "tables": [ ],
            "objects": [ ],
            "files": [
                {
                    "storageContainer": "myImages",
                    "source": "/document/normalized_images/*"
                }
            ]
        }
    ]
}

Promítání na více typů

Složitější scénář může vyžadovat projektování obsahu napříč typy projekce. Například promítání klíčových frází a entit do tabulek, uložení výsledků OCR textu a rozložení textu jako objektů a následné promítání obrázků jako souborů.

Kroky pro více typů projekce:

1. Vytvořte tabulku s řádkem pro každý dokument.
2. Vytvořte tabulku související s tabulkou dokumentů s každou klíčovou frází označenou jako řádek v této tabulce.
3. Vytvořte tabulku související s tabulkou dokumentů s každou entitou identifikovanou jako řádek v této tabulce.
4. Vytvořte projekci objektu s textem rozložení pro každý obrázek.
5. Vytvořte projekci souboru, která promítá každý extrahovaný obrázek.
6. Vytvořte tabulku křížového odkazu, která obsahuje odkazy na tabulku dokumentu, projekci objektu s textem rozložení a projekcí souboru.

Formátování dat pro křížové projekce

Pokud chcete získat obrazce potřebné pro tyto projekce, začněte přidáním nové dovednosti Shaper, která vytvoří tvarovaný objekt s názvem 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"
        }
    ]
}

Definování projekce tabulek, objektů a souborů

Z konsolidovaného objektu crossProjection rozdělte objekt do více tabulek, zachyťte výstup OCR jako objekty blob a pak uložte obrázek jako soubory (také v úložišti objektů 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"
                }
            ]
        }
    ]
}

Projekce objektů vyžadují pro každou projekci název kontejneru. Projekce objektů a projekce souborů nemůžou sdílet kontejner.

Relace mezi tabulkami, objekty a projekcemi souborů

Tento příklad také zvýrazňuje další funkci projekcí. Definováním více typů projekcí v rámci stejného objektu projekce existuje relace vyjádřená v různých typech (tabulky, objekty, soubory). To vám umožní začít řádkem tabulky pro dokument a najít veškerý text OCR pro obrázky v tomto dokumentu v projekci objektu.

Pokud nechcete, aby data souvisela, definujte projekce v různých skupinách projekce. Například následující fragment kódu způsobí, že tabulky souvisejí, ale bez relací mezi tabulkami a projekcemi objektu (text OCR).

Skupiny projekce jsou užitečné, když chcete promítnout stejná data v různých obrazcích pro různé potřeby. Například projekční skupina pro řídicí panel Power BI a další projekční skupina pro zachytávání dat používaných k trénování modelu strojového učení zabaleného do vlastní dovednosti.

Při vytváření projekcí různých typů se nejprve vygenerují projekce souborů a objektů a cesty se přidají do tabulek.

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

Další kroky

Příklad v tomto článku ukazuje běžné vzory vytváření projekcí. Teď, když máte dobrou představu o konceptech, jste lépe vybaveni k vytváření projekcí pro váš konkrétní scénář.