Definiowanie projekcji w magazynie wiedzy

Artykuł
09/01/2024

Projekcje są składnikiem definicji magazynu wiedzy, która określa miejsce przechowywania wzbogaconej zawartości sztucznej inteligencji w usłudze Azure Storage. Projekcje określają typ, ilość i kompozycję struktur danych zawierających zawartość.

W tym artykule przedstawiono składnię dla każdego typu projekcji:

Projekcje tabeli
Projekcje obiektów
Projekcje plików

Przypomnij sobie, że projekcje są definiowane w ramach właściwości "knowledgeStore" zestawu umiejętności.

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

Jeśli potrzebujesz więcej tła przed rozpoczęciem pracy, zapoznaj się z tą listą kontrolną, aby zapoznać się z poradami i przepływem pracy.

Napiwek

Podczas opracowywania projekcji włącz buforowanie wzbogacania (wersja zapoznawcza), aby można było ponownie używać istniejących wzbogaceń podczas edytowania definicji projekcji. Buforowanie wzbogacania jest funkcją w wersji zapoznawczej, dlatego w żądaniu indeksatora należy używać interfejsu API REST w wersji zapoznawczej. Bez buforowania proste edycje projekcji spowodują pełne ponowne przetwarzanie wzbogaconej zawartości. Buforując wzbogacenia, można iterować projekcje bez ponoszenia opłat za przetwarzanie zestawu umiejętności.

Wymagania

Wszystkie projekcje mają właściwości źródłowe i docelowe. Źródło jest zawsze wewnętrzną zawartością z drzewa wzbogacania utworzonego podczas wykonywania zestawu umiejętności. Miejsce docelowe to nazwa i typ obiektu zewnętrznego, który został utworzony i wypełniony w usłudze Azure Storage.

Z wyjątkiem projekcji plików, które akceptują tylko obrazy binarne, źródło musi być następujące:

Prawidłowy kod JSON
Ścieżka do węzła w drzewie wzbogacania (na przykład "source": "/document/objectprojection")

Węzeł może być rozpoznawany jako pojedyncze pole, jednak bardziej typową reprezentacją jest odwołanie do złożonego kształtu. Złożone kształty są tworzone za pomocą metodologii kształtowania, umiejętności kształtowania lub wbudowanej definicji kształtowania, ale zwykle umiejętności kształtowania. Pola lub elementy kształtu określają pola w kontenerach i tabelach.

Umiejętności kształtowania są preferowane, ponieważ generuje kod JSON, w którym większość umiejętności nie generuje prawidłowych danych JSON samodzielnie. W wielu przypadkach ten sam kształt danych utworzony przez umiejętności kształtowania może być używany w równym stopniu przez projekcje tabel i obiektów.

Biorąc pod uwagę wymagania dotyczące danych wejściowych źródła, wiedza na temat kształtowania danych staje się praktycznym wymaganiem dla definicji projekcji, zwłaszcza jeśli pracujesz z tabelami.

Definiowanie projekcji tabeli

Projekcje tabel są zalecane w scenariuszach wymagających eksploracji danych, takich jak analiza za pomocą usługi Power BI lub obciążeń korzystających z ramek danych. Sekcja tabel tablicy projekcji to lista tabel, które chcesz projektować.

Aby zdefiniować projekcję tabeli, użyj tables tablicy we właściwości projekcji. Projekcja tabeli ma trzy wymagane właściwości:

Właściwości	opis
tableName	Określa nazwę nowej tabeli utworzonej w usłudze Azure Table Storage.
generatedKeyName	Nazwa kolumny klucza, który jednoznacznie identyfikuje każdy wiersz. Wartość jest generowana przez system. Jeśli pominiesz tę właściwość, kolumna zostanie utworzona automatycznie, która będzie używać nazwy tabeli i "klucza" jako konwencji nazewnictwa.
source	Ścieżka do węzła w drzewie wzbogacania. Węzeł powinien być odwołaniem do złożonego kształtu, który określa, które kolumny są tworzone w tabeli.

W projekcjach tabeli "źródło" to zwykle dane wyjściowe umiejętności kształtowania definiujące kształt tabeli. Tabele mają wiersze i kolumny, a kształtowanie jest mechanizmem, za pomocą którego określono wiersze i kolumny. Możesz użyć umiejętności kształtowania lub kształtów wbudowanych. Umiejętność kształtowania generuje prawidłowy kod JSON, ale źródło może być danymi wyjściowymi dowolnej umiejętności, jeśli jest prawidłowy kod JSON.

Uwaga

Projekcje tabel podlegają limitom magazynu narzuconym przez usługę Azure Storage. Rozmiar jednostki nie może przekraczać 1 MB, a pojedyncza właściwość nie może być większa niż 64 KB. Te ograniczenia sprawiają, że tabele są dobrym rozwiązaniem do przechowywania dużej liczby małych jednostek.

Przykład pojedynczej tabeli

Schemat tabeli jest określany częściowo przez projekcję (nazwę tabeli i klucz), a także przez źródło, które udostępnia kształt tabeli (kolumn). W tym przykładzie pokazano tylko jedną tabelę, aby można było skupić się na szczegółach definicji.

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

Kolumny pochodzą z "źródła". Następujący kształt danych zawierający wartości HotelId, HotelName, Category i Description spowoduje utworzenie tych kolumn w tabeli.

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

Przykład wielu tabel (fragmentowania)

Typowym wzorcem projekcji tabeli jest posiadanie wielu powiązanych tabel, w których tworzone są kolumny partitionKey i rowKey generowane przez system w celu obsługi relacji między tabelami dla wszystkich tabel w tej samej grupie projekcji.

Tworzenie wielu tabel może być przydatne, jeśli chcesz kontrolować sposób agregowania powiązanych danych. Jeśli wzbogacona zawartość ma niepowiązane lub niezależne składniki, na przykład słowa kluczowe wyodrębnione z dokumentu mogą nie być powiązane z jednostkami rozpoznanymi w tym samym dokumencie, możesz podzielić te pola na sąsiadujące tabele.

Podczas projekcji do wielu tabel pełny kształt jest rzutowany na każdą tabelę, chyba że węzeł podrzędny jest źródłem innej tabeli w tej samej grupie. Dodanie projekcji ze ścieżką źródłową będącą elementem podrzędnym istniejącego projekcji powoduje wycinkę węzła podrzędnego z węzła nadrzędnego i zaplanowaną na nową, ale powiązaną tabelę. Ta technika umożliwia zdefiniowanie jednego węzła w umiejętności kształtowania, które mogą być źródłem wszystkich projekcji.

Wzorzec dla wielu tabel składa się z następujących elementów:

Jedna tabela jako tabela nadrzędna lub główna
Dodatkowe tabele zawierające wycinki wzbogaconej zawartości

Załóżmy na przykład, że umiejętność kształtowania generuje element "Wzbogacony kształt", który zawiera informacje o hotelu oraz wzbogaconą zawartość, na przykład kluczowe frazy, lokalizacje i organizacje. Tabela główna zawiera pola opisujące hotel (identyfikator, nazwa, opis, adres, kategoria). Frazy kluczowe otrzymają kolumnę frazy kluczowej. Jednostki pobierają kolumny jednostek.

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

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.

Definiowanie projekcji obiektu

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. Projekcja obiektu ma trzy wymagane właściwości:

Właściwości	opis
storageContainer	Określa nazwę nowego kontenera utworzonego w usłudze Azure Storage.
generatedKeyName	Nazwa kolumny klucza, który jednoznacznie identyfikuje każdy wiersz. Wartość jest generowana przez system. Jeśli pominiesz tę właściwość, kolumna zostanie utworzona automatycznie, która będzie używać nazwy tabeli i "klucza" jako konwencji nazewnictwa.
source	Ścieżka do węzła w drzewie wzbogacania, który jest elementem głównym projekcji. Węzeł jest zwykle odwołaniem do złożonego kształtu danych, który określa strukturę 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"
        }
      ]
    }

Definiowanie projekcji pliku

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ą dane binarne (w przeciwieństwie do formatu JSON).

Aby zdefiniować projekcję pliku, użyj files tablicy we właściwości projekcji. Projekcja plików ma trzy wymagane właściwości:

Właściwości	opis
storageContainer	Określa nazwę nowego kontenera utworzonego w usłudze Azure Storage.
generatedKeyName	Nazwa kolumny klucza, który jednoznacznie identyfikuje każdy wiersz. Wartość jest generowana przez system. Jeśli pominiesz tę właściwość, kolumna zostanie utworzona automatycznie, która będzie używać nazwy tabeli i "klucza" jako konwencji nazewnictwa.
source	Ścieżka do węzła w drzewie wzbogacania, który jest elementem głównym projekcji. W przypadku plików obrazów źródło jest 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. Jeśli istnieje wiele obrazów, zostaną one umieszczone razem w tym samym folderze. 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.

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

Projekcje testowe

Projekcje można przetwarzać, wykonując następujące kroki:

Ustaw właściwość magazynu storageConnectionString wiedzy na prawidłowe konto magazynu ogólnego przeznaczenia w wersji 2 parametry połączenia.
Zaktualizuj zestaw umiejętności, wysyłając żądanie PUT przy użyciu definicji projekcji w treści zestawu umiejętności.
Uruchom indeksator , aby umieścić zestaw umiejętności w wykonaniu.
Monitoruj wykonywanie indeksatora, aby sprawdzić postęp i przechwycić wszelkie błędy.
Użyj witryny Azure Portal, aby zweryfikować tworzenie obiektów w usłudze Azure Storage.
Jeśli projektujesz tabele, zaimportuj je do usługi Power BI w celu manipulowania tabelami i wizualizacji. W większości przypadków usługa Power BI automatycznie odnajduje relacje między tabelami.

Typowe problemy

Pominięcie dowolnego z poniższych kroków może spowodować nieoczekiwane wyniki. Sprawdź następujące warunki, jeśli dane wyjściowe nie wyglądają prawidłowo.

Wzbogacanie ciągów nie jest kształtowane w prawidłowy kod JSON. Gdy ciągi są wzbogacone, na przykład merged_content wzbogacone frazami kluczowymi, wzbogacona właściwość jest reprezentowana jako element podrzędny merged_content w drzewie wzbogacania. Domyślna reprezentacja nie jest poprawnie sformułowanym plikiem JSON. W czasie projekcji pamiętaj, aby przekształcić wzbogacanie w prawidłowy obiekt JSON o nazwie i wartości. Korzystanie z umiejętności kształtowania lub definiowanie kształtów wbudowanych pomoże rozwiązać ten problem.
/* Pominięcie na końcu ścieżki źródłowej. Jeśli źródłem projekcji jest /document/projectionShape/keyPhrases, tablica fraz kluczowych jest przewidywana jako pojedynczy obiekt/wiersz. Zamiast tego ustaw ścieżkę źródłową tak, aby /document/projectionShape/keyPhrases/* zwracała pojedynczy wiersz lub obiekt dla każdego z kluczowych fraz.
Błędy składni ścieżki. Selektory ścieżek są wrażliwe na wielkość liter i mogą prowadzić do braku ostrzeżeń wejściowych, jeśli nie używasz dokładnego przypadku selektora.

Następne kroki

Następny krok przeprowadzi Cię przez kształtowanie i projekcję danych wyjściowych z bogatego zestawu umiejętności. Jeśli zestaw umiejętności jest złożony, poniższy artykuł zawiera przykłady zarówno kształtów, jak i projekcji.

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

Udostępnij za pośrednictwem