Szczegółowy przykład kształtów i projekcji w magazynie wiedzy

  • Artykuł

Ten artykuł zawiera szczegółowy przykład, który uzupełnia ogólne pojęcia i artykuły oparte na składni, przechodząc przez kroki kształtowania i projekcji wymagane do pełnego wyrażania danych wyjściowych bogatego zestawu umiejętności w magazynie wiedzy.

Jeśli wymagania aplikacji wymagają wielu umiejętności i projekcji, w tym przykładzie można lepiej zrozumieć, jak kształty i projekcje przecinają się.

Konfigurowanie przykładowych danych

Przykładowe dokumenty nie są dołączone do kolekcji Projekcje, ale pliki danych pokazu wzbogacania sztucznej inteligencji zawierają tekst i obrazy, które współpracują z projekcjami opisanymi w tym przykładzie.

Utwórz kontener obiektów blob w usłudze Azure Storage i przekaż wszystkie 14 elementów.

W usłudze Azure Storage skopiuj parametry połączenia.

Możesz użyć projections.rest tego pliku, aby uruchomić przykłady w tym artykule.

Przykładowy zestaw umiejętności

Aby zrozumieć zależność między kształtami i projekcjami, zapoznaj się z następującym zestawem umiejętności, który tworzy wzbogaconą zawartość. Ten zestaw umiejętności przetwarza zarówno nieprzetworzone obrazy, jak i tekst, generując dane wyjściowe, do których będą odwoływać się kształty i projekcje.

Zwróć szczególną uwagę na dane wyjściowe umiejętności (targetNames). Dane wyjściowe zapisywane w wzbogaconym drzewie dokumentów są przywoływane w projekcjach i kształtach (za pomocą umiejętności kształtowania).

{
    "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": "An Azure AI services resource in the same region as Search.",
        "key": "<Azure AI services All-in-ONE KEY>"
    },
    "knowledgeStore": null
}

Przykładowa umiejętność kształtowania

Umiejętność kształtowania to narzędzie do pracy z istniejącą wzbogaconą zawartością zamiast tworzenia nowej wzbogaconej zawartości. Dodanie kształtu do zestawu umiejętności umożliwia utworzenie niestandardowego kształtu, który można projektować w magazynie tabel lub obiektów blob. Bez kształtu niestandardowego projekcje są ograniczone do odwoływania się do jednego węzła (jednej projekcji na dane wyjściowe), która nie jest odpowiednia dla tabel. Tworzenie niestandardowego kształtu agreguje różne elementy w nową całość logiczną, którą można rzutować jako pojedynczą tabelę lub podzielić i rozłożyć w kolekcji tabel.

W tym przykładzie kształt niestandardowy łączy metadane obiektu blob oraz zidentyfikowane jednostki i kluczowe frazy. Kształt niestandardowy jest wywoływany projectionShape i jest nadrzędny w obszarze /document.

Jednym z celów kształtowania jest zapewnienie, że wszystkie węzły wzbogacania są wyrażane w dobrze sformułowanym formacie JSON, który jest wymagany do projekcji w magazynie wiedzy. Jest to szczególnie istotne, gdy drzewo wzbogacania zawiera węzły, które nie są poprawnie sformułowane w formacie JSON (na przykład gdy wzbogacanie jest nadrzędne do elementu pierwotnego, takiego jak ciąg).

Zwróć uwagę na dwa ostatnie węzły i KeyPhrasesEntities. Są one opakowane w prawidłowy obiekt JSON z .sourceContext Jest to wymagane jako keyphrases i entities są wzbogacania elementów pierwotnych i należy je przekonwertować na prawidłowy kod JSON, zanim będzie można je projektować.

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

Dodawanie kształtatorów do zestawu umiejętności

Przykładowy zestaw umiejętności wprowadzony na początku tego artykułu nie zawiera umiejętności kształtowania, ale umiejętności kształtatora należą do zestawu umiejętności i są często umieszczane na końcu.

W ramach zestawu umiejętności umiejętność kształtowania może wyglądać następująco:

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

Projekcja do tabel

Na podstawie powyższych przykładów istnieje znana ilość wzbogacenia i kształtów danych, do których można się odwoływać w projekcjach tabeli. W poniższych tabelach trzy tabele są definiowane przez ustawienie tableNamewłaściwości i generatedKeyNamesource .

Wszystkie trzy z tych tabel będą powiązane za pośrednictwem wygenerowanych kluczy i udostępnionego elementu nadrzędnego /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": []
        }
    ]
}

Testowanie pracy

Definicje projekcji można sprawdzić, wykonując następujące kroki:

  1. Ustaw właściwość magazynu storageConnectionString wiedzy na prawidłowe konto magazynu ogólnego przeznaczenia w wersji 2 parametry połączenia.

  2. Zaktualizuj zestaw umiejętności, wysyłając żądanie PUT.

  3. Po zaktualizowaniu zestawu umiejętności uruchom indeksator.

Masz teraz projekcję roboczą z trzema tabelami. Zaimportowanie tych tabel do usługi Power BI powinno spowodować odnalezienie relacji w usłudze Power BI .

Przed przejściem do następnego przykładu wróćmy do aspektów projekcji tabeli, aby zrozumieć mechanikę fragmentowania i powiązanych danych.

Dzielenie tabeli na wiele tabel podrzędnych

Fragmentowanie to technika, która dzieli cały skonsolidowany kształt na części składowe. Wynik składa się z oddzielnych, ale powiązanych tabel, z którymi można pracować indywidualnie.

W tym przykładzie projectionShape jest to skonsolidowany kształt (lub węzeł wzbogacania). W definicji projectionShape projekcji jest podzielona na dodatkowe tabele, co umożliwia wyciąganie części kształtu keyPhrases i Entities. W usłudze Power BI jest to przydatne, ponieważ z każdym dokumentem jest skojarzonych wiele jednostek i fraz keyPhrases. Uzyskasz więcej szczegółowych informacji, jeśli zobaczysz jednostki i frazy keyPhrases jako dane podzielone na kategorie.

Fragmentowanie niejawnie generuje relację między tabelami nadrzędnymi i podrzędnymi przy użyciu generatedKeyName tabeli nadrzędnej w celu utworzenia kolumny o tej samej nazwie w tabeli podrzędnej.

Relacje nazewnictwa

Właściwości generatedKeyName i referenceKeyName służą do powiązania danych między tabelami, a nawet między typami projekcji. Każdy wiersz w tabeli podrzędnej ma właściwość wskazującą element nadrzędny. Nazwa kolumny lub właściwości w elemecie podrzędnym to referenceKeyName nazwa elementu nadrzędnego. referenceKeyName Jeśli parametr nie zostanie podany, usługa domyślnie jest domyślnie ustawiona na generatedKeyName wartość z elementu nadrzędnego.

Usługa Power BI opiera się na tych wygenerowanych kluczach w celu odnajdywania relacji w tabelach. Jeśli potrzebujesz kolumny w tabeli podrzędnej o nazwie inaczej, ustaw referenceKeyName właściwość w tabeli nadrzędnej. Przykładem może być ustawienie identyfikatora generatedKeyName jako w tabeli tblDocument i identyfikatora referenceKeyName DocumentID. Spowoduje to wyświetlenie kolumny w tabelach tblEntities i tblKeyPhrases zawierających identyfikator dokumentu o nazwie DocumentID.

Projecting blob documents (Projektowanie dokumentów obiektów blob)

Projekcje obiektów to reprezentacje JSON drzewa wzbogacania, które mogą być pozyskiwane z dowolnego węzła. W porównaniu z projekcjami tabel projekcje obiektów są prostsze do zdefiniowania i są używane podczas projekcji całych dokumentów. Projekcje obiektów są ograniczone do pojedynczej projekcji w kontenerze i nie można ich podzielić.

Aby zdefiniować projekcję obiektu, użyj objects tablicy we właściwości projekcji.

Źródłem jest ścieżka do węzła drzewa wzbogacania, który jest elementem głównym projekcji. Chociaż nie jest to wymagane, ścieżka węzła jest zwykle danymi wyjściowymi umiejętności kształtowania. Wynika to z faktu, że większość umiejętności nie generuje prawidłowych obiektów JSON samodzielnie, co oznacza, że konieczna jest pewna forma kształtowania. W wielu przypadkach ta sama umiejętność kształtowania, która tworzy projekcję tabeli, może służyć do generowania projekcji obiektu. Alternatywnie można ustawić źródło na węzeł z wbudowanym kształtowaniem , aby zapewnić strukturę.

Miejsce docelowe jest zawsze kontenerem obiektów blob.

Poniższy przykład obejmuje projekty poszczególnych dokumentów hotelowych, jednego dokumentu hotelowego na obiekt blob, do kontenera o nazwie hotels.

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

Źródłem jest dane wyjściowe umiejętności kształtowania o nazwie "objectprojection". Każdy obiekt blob będzie miał reprezentację JSON każdego pola wejściowego.

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

Projekcja pliku obrazu

Projekcje plików są zawsze binarne, znormalizowane obrazy, gdzie normalizacja odnosi się do potencjalnej zmiany rozmiaru i rotacji do użycia w wykonywaniu zestawu umiejętności. Projekcje plików, podobne do projekcji obiektów, są tworzone jako obiekty blob w usłudze Azure Storage i zawierają obraz.

Aby zdefiniować projekcję pliku, użyj files tablicy we właściwości projekcji.

Źródło to zawsze /document/normalized_images/*. Projekcje plików działają tylko w kolekcji normalized_images . Ani indeksatory, ani zestaw umiejętności nie przejdą przez oryginalny, nienormalowany obraz.

Miejsce docelowe jest zawsze kontenerem obiektów blob z prefiksem folderu zakodowanej w formacie base64 identyfikatora dokumentu. Projekcje plików nie mogą współużytkować tego samego kontenera co projekcje obiektów i muszą być projektowane w innym kontenerze.

Poniższy przykład zawiera projekty wszystkich znormalizowanych obrazów wyodrębnionych z węzła dokumentu wzbogaconego dokumentu do kontenera o nazwie myImages.

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

Projekcja do wielu typów

Bardziej złożony scenariusz może wymagać projekcji zawartości między typami projekcji. Na przykład projekcja kluczowych fraz i jednostek w tabelach, zapisywanie wyników OCR tekstu i tekstu układu jako obiektów, a następnie projekcje obrazów jako plików.

Kroki dla wielu typów projekcji:

  1. Utwórz tabelę z wierszem dla każdego dokumentu.
  2. Utwórz tabelę powiązaną z tabelą dokumentów z każdą frazą kluczową zidentyfikowaną jako wiersz w tej tabeli.
  3. Utwórz tabelę powiązaną z tabelą dokumentów z każdą jednostką zidentyfikowaną jako wiersz w tej tabeli.
  4. Utwórz projekcję obiektu z tekstem układu dla każdego obrazu.
  5. Utwórz projekcję pliku, wyświetlając każdy wyodrębniony obraz.
  6. Utwórz tabelę krzyżową zawierającą odwołania do tabeli dokumentów, projekcję obiektów z tekstem układu i projekcją pliku.

Dane kształtu dla projekcji krzyżowej

Aby uzyskać kształty potrzebne do tych projekcji, zacznij od dodania nowej umiejętności kształtowania, która tworzy kształtowany obiekt o nazwie 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"
        }
    ]
}

Definiowanie projekcji tabel, obiektów i plików

Z skonsolidowanego obiektu crossProjection podzielić obiekt na wiele tabel, przechwycić dane wyjściowe OCR jako obiekty blob, a następnie zapisać obraz jako pliki (również w usłudze Blob Storage).

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

Projekcje obiektów wymagają nazwy kontenera dla każdej projekcji. Projekcje obiektów i projekcje plików nie mogą współużytkować kontenera.

Relacje między projekcjami tabel, obiektów i plików

W tym przykładzie wyróżniono również inną funkcję projekcji. Definiując wiele typów projekcji w tym samym obiekcie projekcji, istnieje relacja wyrażona w obrębie i w różnych typach (tabele, obiekty, pliki). Dzięki temu można rozpocząć od wiersza tabeli dla dokumentu i znaleźć cały tekst OCR dla obrazów w tym dokumencie w projekcji obiektu.

Jeśli nie chcesz, aby dane powiązane, zdefiniuj projekcje w różnych grupach projekcji. Na przykład poniższy fragment kodu spowoduje, że tabele będą powiązane, ale bez relacji między tabelami a projekcjami obiektu (tekst OCR).

Grupy projekcji są przydatne, gdy chcesz projektować te same dane w różnych kształtach w różnych potrzebach. Na przykład grupa projekcji dla pulpitu nawigacyjnego usługi Power BI i inna grupa projekcji służąca do przechwytywania danych używanych do trenowania modelu uczenia maszynowego opakowanego w umiejętności niestandardowe.

Podczas tworzenia projekcji różnych typów projekcje plików i obiektów są generowane jako pierwsze, a ścieżki są dodawane do tabel.

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

Następne kroki

W przykładzie w tym artykule przedstawiono typowe wzorce tworzenia projekcji. Teraz, gdy masz dobre zrozumienie pojęć, lepiej jesteś przygotowany do tworzenia projekcji dla konkretnego scenariusza.

Konfigurowanie buforowania na potrzeby wzbogacania przyrostowego