Odwołanie do ścieżki do wzbogaconych węzłów przy użyciu kontekstu i właściwości źródłowych zestawu umiejętności usługi Azure AI Search

Artykuł
01/19/2024

Podczas wykonywania zestawu umiejętności aparat tworzy drzewo wzbogacania w pamięci, które przechwytuje każde wzbogacanie, takie jak rozpoznane jednostki lub przetłumaczony tekst. W tym artykule dowiesz się, jak odwoływać się do węzła wzbogacania w drzewie wzbogacania, aby umożliwić przekazywanie danych wyjściowych do umiejętności podrzędnych lub określanie mapowania pól wyjściowych dla pola indeksu wyszukiwania.

W tym artykule przedstawiono przykłady ilustrujące różne scenariusze. Aby uzyskać pełną składnię, zobacz Kontekst umiejętności i język adnotacji wejściowych.

Pojęcia dotyczące podstaw

Przed zapoznaniem się ze składnią zapoznajmy się z kilkoma ważnymi pojęciami, aby lepiej zrozumieć przykłady przedstawione w dalszej części tego artykułu.

Okres	opis
"wzbogacony dokument"	Wzbogacony dokument to struktura w pamięci, która zbiera dane wyjściowe umiejętności podczas jego tworzenia i przechowuje wszystkie wzbogacania związane z dokumentem. Pomyśl o wzbogaconym dokumencie jako drzewie. Ogólnie rzecz biorąc, drzewo zaczyna się od poziomu dokumentu głównego, a każde nowe wzbogacanie jest tworzone na podstawie poprzedniego elementu podrzędnego.
"węzeł"	W wzbogaconym dokumencie węzeł (czasami nazywany "adnotacją") jest tworzony i wypełniany przez umiejętności, takie jak "tekst" i "layoutText" w umiejętności OCR. Wzbogacony dokument jest wypełniany zarówno wzbogacaniami, jak i oryginalnymi wartościami pól źródłowych lub metadanymi skopiowanymi ze źródła.
"kontekst"	Zakres wzbogacania, który jest zarówno całym dokumentem, fragmentem dokumentu, jak i w przypadku pracy z obrazami, wyodrębnionych obrazów z dokumentu. Domyślnie kontekst wzbogacania jest na `"/document"` poziomie, ograniczony do poszczególnych dokumentów zawartych w źródle danych. Po uruchomieniu umiejętności dane wyjściowe tej umiejętności stają się właściwościami zdefiniowanego kontekstu.

Ścieżki dla różnych scenariuszy

Ścieżki są określane we właściwościach "context" i "source" zestawu umiejętności oraz w mapowaniach pól wyjściowych w indeksatorze.

Przykład na zrzucie ekranu przedstawia ścieżkę elementu w kolekcji usługi Azure Cosmos DB.

context ścieżka jest ze względu na to /document/HotelId , że kolekcja jest podzielona na dokumenty według /HotelId pola.
source ścieżka jest /document/Description taka, ponieważ umiejętność tłumaczenia jest umiejętnością tłumaczenia, a pole, które chcesz przetłumaczyć, to Description pole w każdym dokumencie.

Wszystkie ścieżki zaczynają się od /document. Wzbogacony dokument jest tworzony na etapie "pękania dokumentu" wykonywania indeksatora, gdy indeksator otwiera dokument lub odczytuje go w wierszu ze źródła danych. Początkowo jedynym węzłem w wzbogaconym dokumencie jest węzeł główny (/document) i jest to węzeł, z którego występują wszystkie inne wzbogacania.

Poniższa lista zawiera kilka typowych przykładów:

/document jest węzłem głównym i wskazuje cały obiekt blob w usłudze Azure Storage lub wiersz w tabeli SQL.
/document/{key} to składnia dokumentu lub elementu w kolekcji usługi Azure Cosmos DB, gdzie {key} jest rzeczywistym kluczem, takim jak /document/HotelId w poprzednim przykładzie.
/document/content określa właściwość "content" obiektu blob JSON.
/document/{field} to składnia operacji wykonywanej na określonym polu, takim jak tłumaczenie /document/Description pola, widoczne w poprzednim przykładzie.
/document/pages/* lub /document/sentences/* stać się kontekstem, jeśli dzielisz duży dokument na mniejsze fragmenty na potrzeby przetwarzania. Jeśli "kontekst" to /document/pages/*, umiejętności są wykonywane raz na każdej stronie w dokumencie. Ponieważ może istnieć więcej niż jedna strona lub zdanie, dołączysz /* je, aby przechwycić je wszystkie.
/document/normalized_images/* jest tworzony podczas pękania dokumentu, jeśli dokument zawiera obrazy. Wszystkie ścieżki do obrazów zaczynają się od normalized_images. Ponieważ w dokumencie jest często osadzonych wiele obrazów, dołącz element /*.

Przykłady w pozostałej części tego artykułu są oparte na polu "zawartość" generowanym automatycznie przez indeksatory obiektów blob platformy Azure w ramach fazy łamania dokumentu. W przypadku odwoływania się do dokumentów z kontenera obiektów blob użyj formatu takiego jak "/document/content", gdzie pole "zawartość" jest częścią "dokumentu".

Przykład 1. Odwołanie do prostego adnotacji

W usłudze Azure Blob Storage załóżmy, że masz wiele plików zawierających odwołania do nazw osób, które chcesz wyodrębnić przy użyciu rozpoznawania jednostek. W poniższej definicji "/document/content" umiejętności jest tekstową reprezentacją całego dokumentu, a "ludzie" to wyodrębnianie pełnych nazwisk jednostek zidentyfikowanych jako osoby.

Ponieważ domyślnym kontekstem jest "/document", lista osób może teraz być przywołynięta jako "/document/people". W tym konkretnym przypadku "/document/people" jest adnotacja, która może być teraz mapowana na pole w indeksie lub używana w innej umiejętności w tym samym zestawie umiejętności.

  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "categories": [ "Person"],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "persons",
        "targetName": "people"
      }
    ]
  }

Przykład 2. Odwołanie do tablicy w dokumencie

W tym przykładzie przedstawiono sposób wielokrotnego wywoływania kroku wzbogacania w tym samym dokumencie. Załóżmy, że w poprzednim przykładzie wygenerowano tablicę ciągów z 10 nazwami osób z jednego dokumentu. Rozsądnym następnym krokiem może być drugie wzbogacanie, które wyodrębnia nazwisko z pełnej nazwy. Ponieważ istnieje 10 nazw, ten krok ma być wywoływany 10 razy w tym dokumencie, raz dla każdej osoby.

Aby wywołać właściwą liczbę iteracji, ustaw kontekst jako "/document/people/*", gdzie gwiazdka ("*") reprezentuje wszystkie węzły w wzbogaconym dokumencie jako obiekty podrzędne "/document/people". Mimo że ta umiejętność jest definiowana tylko raz w tablicy umiejętności, jest wywoływana dla każdego elementu członkowskiego w dokumencie do momentu przetworzenia wszystkich członków.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the last name from a full name",
    "uri": "http://names.azurewebsites.net/api/GetLastName",
    "context" : "/document/people/*",
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "fullname",
        "source": "/document/people/*"
      }
    ],
    "outputs": [
      {
        "name": "lastname",
        "targetName": "last"
      }
    ]
  }

Gdy adnotacje są tablicami lub kolekcjami ciągów, możesz chcieć kierować do określonych elementów członkowskich, a nie do tablicy jako całości. Powyższy przykład generuje adnotację o nazwie "last" w każdym węźle reprezentowanym przez kontekst. Jeśli chcesz odwołać się do tej rodziny adnotacji, możesz użyć składni "/document/people/*/last". Jeśli chcesz odwołać się do konkretnej adnotacji, możesz użyć jawnego indeksu: "/document/people/1/last", aby odwołać się do nazwiska pierwszej osoby zidentyfikowanej w dokumencie. Zwróć uwagę, że w tej składni tablice są "indeksowane 0".

Przykład 3. Odwołania do elementów członkowskich w tablicy

Czasami należy zgrupować wszystkie adnotacje określonego typu, aby przekazać je do określonej umiejętności. Rozważmy hipotetyczną umiejętność niestandardową, która identyfikuje najbardziej typowe nazwisko ze wszystkich nazwisk wyodrębnionych w przykładzie 2. Aby podać tylko nazwiska do umiejętności niestandardowej, określ kontekst jako "/document" i dane wejściowe jako "/document/people/*/lastname".

Zwróć uwagę, że kardynalność obiektu "/document/people/*/lastname" jest większa niż w dokumencie. W tym dokumencie może istnieć 10 węzłów lastname, podczas gdy istnieje tylko jeden węzeł dokumentu. W takim przypadku system automatycznie utworzy tablicę "/document/people/*/lastname" zawierającą wszystkie elementy w dokumencie.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the most common string from an array of strings",
    "uri": "http://names.azurewebsites.net/api/MostCommonString",
    "context" : "/document",
    "inputs": [
      {
        "name": "strings",
        "source": "/document/people/*/lastname"
      }
    ],
    "outputs": [
      {
        "name": "mostcommon",
        "targetName": "common-lastname"
      }
    ]
  }

Wskazówki na potrzeby rozwiązywania problemów ze ścieżką adnotacji

Jeśli masz problemy z określeniem danych wejściowych umiejętności, te porady mogą pomóc Ci przejść do przodu:

Uruchom Kreatora importu danych na danych, aby przejrzeć definicje zestawu umiejętności i mapowania pól generowane przez kreatora.
Rozpocznij sesję debugowania na zestawie umiejętności, aby wyświetlić strukturę wzbogaconego dokumentu. Możesz edytować ścieżki i inne części definicji umiejętności, a następnie uruchomić umiejętności, aby zweryfikować zmiany.