Definování projekcí v úložišti znalostí

Projekce jsou součástí definice úložiště znalostí, která určuje, kde je obsah obohacený o AI uložený ve službě Azure Storage. Projekce určují typ, množství a složení datových struktur obsahujících váš obsah.

V tomto článku se seznámíte se syntaxí pro každý typ projekce:

• Projekce tabulek
• Projekce objektů
• Projekce souborů

Vzpomeňte si, že projekce jsou definovány ve vlastnosti knowledgeStore sady dovedností.

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
      {
        "tables": [ ],
        "objects": [ ],
        "files": [ ]
      }
    ]
}

Pokud před zahájením práce potřebujete další pozadí, projděte si tento seznam tipů a pracovních postupů.

Tip

Při vývoji projekcí povolte ukládání do mezipaměti rozšiřování (Preview), abyste při úpravě definic projekce mohli znovu použít existující rozšiřování. Ukládání do mezipaměti do mezipaměti je funkce preview, proto pro požadavek indexeru nezapomeňte použít rozhraní REST API verze Preview (api-version=2020-06-30-preview nebo novější). Bez ukládání do mezipaměti budou jednoduché úpravy projekce vést k úplnému opětovnému zpracování rozšířeného obsahu. Díky ukládání do mezipaměti můžete iterovat před projekcemi, aniž byste museli účtovat poplatky za zpracování sady dovedností.

Požadavky

Všechny projekce mají vlastnosti zdroje a cíle. Zdroj je vždy interní obsah ze stromu rozšiřování vytvořeného během provádění sady dovedností. Cílem je název a typ externího objektu vytvořeného a naplněného ve službě Azure Storage.

S výjimkou projekcí souborů, které přijímají pouze binární obrázky, musí být zdrojem:

• Platný kód JSON
• Cesta k uzlu ve stromu rozšiřování (například "source": "/document/objectprojection")

I když se uzel může přeložit na jedno pole, častější reprezentace je odkaz na složitý obrazec. Složité obrazce se vytvářejí metodikou tvarování, buď dovednost Shaper, nebo definice vloženého tvarování, ale obvykle dovednost Shaper. Pole nebo prvky obrazce určují pole v kontejnerech a tabulkách.

Upřednostňují se dovednosti shaperu, protože výstupem je JSON, kde většina dovedností nevypíše platný json samostatně. V mnoha případech lze stejný datový obrazec vytvořený dovedností Shaper použít stejně jako projekce tabulek i objektů.

Vzhledem k požadavkům na vstup zdroje se znalost tvarování dat stává praktickým požadavkem pro definici projekce, zejména pokud pracujete s tabulkami.

Definování projekce tabulky

Projekce tabulek se doporučují pro scénáře, které volají pro zkoumání dat, jako je analýza pomocí Power BI nebo úloh, které využívají datové rámce. Oddíl tabulky pole projekcí je seznam tabulek, které chcete projektovat.

Chcete-li definovat projekci tabulky, použijte tables pole ve vlastnosti projekce. Projekce tabulky má tři požadované vlastnosti:

Vlastnost	Popis
tableName	Určuje název nové tabulky vytvořené v Azure Table Storage.
generatedKeyName	Název sloupce pro klíč, který jednoznačně identifikuje každý řádek. Hodnota je vygenerována systémem. Pokud tuto vlastnost vynecháte, vytvoří se sloupec automaticky, který jako konvenci pojmenování použije název tabulky a klíč.
zdroj	Cesta k uzlu ve stromu rozšiřování Uzel by měl být odkazem na složitý obrazec, který určuje sloupce vytvořené v tabulce.

V projekcích tabulky je "zdroj" obvykle výstupem dovednosti Shaper, která definuje tvar tabulky. Tabulky mají řádky a sloupce a tvarování je mechanismus, podle kterého jsou zadané řádky a sloupce. Můžete použít dovednost shaperu nebo vložené obrazce. Dovednost Shaper vytváří platný kód JSON, ale zdrojem může být výstup z jakékoli dovednosti, pokud je platný JSON.

Poznámka:

Projekce tabulek podléhají omezením úložiště uloženým službou Azure Storage. Velikost entity nesmí překročit 1 MB a jedna vlastnost nesmí být větší než 64 kB. Díky těmto omezením jsou tabulky vhodným řešením pro ukládání velkého počtu malých entit.

Příklad jedné tabulky

Schéma tabulky je částečně určeno projekcí (název tabulky a klíč) a také zdrojem, který poskytuje tvar tabulky (sloupců). Tento příklad ukazuje jenom jednu tabulku, abyste se mohli zaměřit na podrobnosti definice.

"projections" : [
  {
    "tables": [
      { "tableName": "Hotels", "generatedKeyName": "HotelId", "source": "/document/tableprojection" }
    ]
  }
]

Sloupce jsou odvozeny ze zdroje. Následující datový obrazec obsahující HotelId, HotelName, Category a Description způsobí vytvoření těchto sloupců v tabulce.

{
    "@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": "Description",
        "source": "/document/Description"
    },
    ],
    "outputs": [
    {
        "name": "output",
        "targetName": "tableprojection"
    }
    ]
}

Příklad více tabulek (řezů)

Běžným vzorem pro projekce tabulek je mít více souvisejících tabulek, kde jsou vytvořeny sloupce partitionKey a rowKey generované systémem, které podporují relace mezi tabulkami pro všechny tabulky ve stejné skupině projekcí.

Vytvoření více tabulek může být užitečné, pokud chcete mít kontrolu nad tím, jak se související data agregují. Pokud má obohacený obsah nesouvisející nebo nezávislé komponenty, například klíčová slova extrahovaná z dokumentu nemusí souviset s entitami rozpoznanými ve stejném dokumentu, můžete tato pole rozdělit do sousedních tabulek.

Při promítání do více tabulek se celý obrazec promítá do každé tabulky, pokud podřízený uzel není zdrojem jiné tabulky ve stejné skupině. Přidání projekce se zdrojovou cestou, která je podřízenou existující projekcí, vede k rozdělení podřízeného uzlu z nadřazeného uzlu a promítnutí do nové, ale související tabulky. Tato technika umožňuje definovat jeden uzel v dovednostech Shaper, které mohou být zdrojem pro všechny vaše projekce.

Vzor pro více tabulek se skládá z:

• Jedna tabulka jako nadřazená nebo hlavní tabulka
• Další tabulky obsahující řezy rozšířeného obsahu

Předpokládejme například, že dovednost Shaper vypíše "EnrichedShape", která obsahuje informace o hotelu a obohacený obsah, jako jsou klíčové fráze, místa a organizace. Hlavní tabulka by obsahovala pole, která popisují hotel (ID, jméno, popis, adresa, kategorie). Klíčové fráze by získaly sloupec klíčových frází. Entity by získaly sloupce entit.

"projections" : [
  {
    "tables": [
    { "tableName": "MainTable", "generatedKeyName": "HotelId", "source": "/document/EnrichedShape" },
    { "tableName": "KeyPhrases", "generatedKeyName": "KeyPhraseId", "source": "/document/EnrichedShape/*/KeyPhrases/*" },
    { "tableName": "Entities", "generatedKeyName": "EntityId", "source": "/document/EnrichedShape/*/Entities/*" }
    ]
  }
]

Vztahy pojmenování

Tyto generatedKeyName vlastnosti referenceKeyName se používají k relaci dat mezi tabulkami nebo dokonce napříč typy projekce. Každý řádek v podřízené tabulce má vlastnost odkazující zpět na nadřazenou položku. Název sloupce nebo vlastnosti v podřízené části je referenceKeyName z nadřazeného objektu. referenceKeyName Pokud není tato služba zadaná, nastaví ji jako generatedKeyName výchozí z nadřazeného objektu.

Power BI využívá tyto vygenerované klíče ke zjišťování relací v tabulkách. Pokud potřebujete sloupec v podřízené tabulce s názvem jinak, nastavte referenceKeyName vlastnost nadřazené tabulky. 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.

Definování projekce objektu

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. Projekce objektu má tři požadované vlastnosti:

Vlastnost	Popis
storageContainer	Určuje název nového kontejneru vytvořeného ve službě Azure Storage.
generatedKeyName	Název sloupce pro klíč, který jednoznačně identifikuje každý řádek. Hodnota je vygenerována systémem. Pokud tuto vlastnost vynecháte, vytvoří se sloupec automaticky, který jako konvenci pojmenování použije název tabulky a klíč.
zdroj	Cesta k uzlu ve stromu rozšiřování, který je kořenem projekce. Uzel je obvykle odkazem na složitý datový obrazec, který určuje strukturu objektů blob.

Následující příklad projekty jednotlivé hotelové dokumenty, jeden hotelový dokument na objekt blob, do kontejneru s názvem 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"
        }
      ]
    }

Definování projekce souboru

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í binární data (na rozdíl od JSON).

Chcete-li definovat projekci souboru, použijte files pole ve vlastnosti projekce. Projekce souborů má tři požadované vlastnosti:

Vlastnost	Popis
storageContainer	Určuje název nového kontejneru vytvořeného ve službě Azure Storage.
generatedKeyName	Název sloupce pro klíč, který jednoznačně identifikuje každý řádek. Hodnota je vygenerována systémem. Pokud tuto vlastnost vynecháte, vytvoří se sloupec automaticky, který jako konvenci pojmenování použije název tabulky a klíč.
zdroj	Cesta k uzlu ve stromu rozšiřování, který je kořenem projekce. Pro soubory obrázků je zdroj vždy /document/normalized_images/*. Projekce souborů fungují pouze s kolekcí normalized_images . Indexery ani sada dovedností neprojdou původní nenormalizovaným obrázkem.

Cílem je vždy kontejner objektů blob s předponou složky kódované hodnotou base64 ID dokumentu. Pokud existuje více obrázků, umístí se do stejné složky. 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 projekty všechny normalizované obrázky extrahované z uzlu dokumentu rozšířeného dokumentu do kontejneru nazývaného myImages.

"projections": [
    {
        "tables": [ ],
        "objects": [ ],
        "files": [
            {
                "storageContainer": "myImages",
                "source": "/document/normalized_images/*"
            }
        ]
    }
]

Testování projekcí

Projekce můžete zpracovat pomocí následujících kroků:

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

2. Aktualizujte sadu dovedností vydáním požadavku PUT definicí projekce v těle sady dovedností.

3. Spuštěním indexeru umístěte sadu dovedností do spuštění.

4. Monitorujte provádění indexeru, abyste zkontrolovali průběh a zachytili případné chyby.

5. Pomocí webu Azure Portal ověřte vytváření objektů ve službě Azure Storage.

6. Pokud promítáte tabulky, naimportujte je do Power BI pro manipulaci s tabulkami a vizualizaci. Power BI ve většině případů automaticky vyhledá relace mezi tabulkami.

Běžné problémy

Vynechání některého z následujících kroků může vést k neočekávaným výsledkům. Pokud výstup nevypadá správně, zkontrolujte následující podmínky.

• Rozšiřování řetězců není tvarováno do platného formátu JSON. Když jsou řetězce rozšířeny, například merged_content obohacené o klíčové fráze, rozšířená vlastnost je reprezentována jako podřízený prvek merged_content v rámci stromu rozšiřování. Výchozí reprezentace není ve správném formátu JSON. V době projekce nezapomeňte transformovat rozšiřování na platný objekt JSON s názvem a hodnotou. Tento problém vyřešíte použitím dovednosti Shaperu nebo definováním vložených obrazců.

• Vynechání /* na konci zdrojové cesty Pokud je /document/projectionShape/keyPhraseszdrojem projekce, pole klíčových frází se promítá jako jeden objekt nebo řádek. Místo toho nastavte zdrojovou cestu tak, aby /document/projectionShape/keyPhrases/* se pro každou z klíčových frází vytvořil jeden řádek nebo objekt.

• Chyby syntaxe cesty Selektory cest rozlišují malá a velká písmena a můžou vést k chybějícím upozorněním na vstup, pokud pro selektor nepoužíváte přesný případ.

Další kroky

Další krok vás provede formováním a projekcí výstupu z bohaté sady dovedností. Pokud je vaše sada dovedností složitá, následující článek obsahuje příklady obrazců i projekcí.

Podrobný příklad obrazců a projekcí