Tworzenie zestawu umiejętności w usłudze Azure AI Search

  • Artykuł

indexer stages

Zestaw umiejętności definiuje operacje, które generują zawartość tekstową i strukturę z dokumentów zawierających obrazy lub tekst bez struktury. Przykłady to OCR dla obrazów, rozpoznawanie jednostek dla niezróżnionego tekstu i tłumaczenie tekstu. Zestaw umiejętności jest wykonywany po wyodrębnieniu tekstu i obrazów z zewnętrznego źródła danych, a po przetworzeniu mapowań pól.

W tym artykule wyjaśniono, jak utworzyć zestaw umiejętności przy użyciu interfejsów API REST, ale te same pojęcia i kroki dotyczą innych języków programowania.

Reguły definicji zestawu umiejętności obejmują:

  • Unikatowa nazwa w kolekcji zestawów umiejętności. Zestaw umiejętności to zasób najwyższego poziomu, który może być używany przez dowolny indeksator.
  • Co najmniej jedna umiejętność. Typowe są trzy do pięciu umiejętności. Maksymalna wartość to 30.
  • Zestaw umiejętności może powtarzać umiejętności tego samego typu (na przykład wiele umiejętności kształtowania).
  • Zestaw umiejętności obsługuje operacje łańcuchowe, pętle i rozgałęzianie.

Indeksatory napędzają wykonywanie zestawu umiejętności. Przed przetestowaniem zestawu umiejętności potrzebujesz indeksatora, źródła danych i indeksu.

Napiwek

Włącz buforowanie wzbogacania w celu ponownego użycia już przetworzonej zawartości i obniżyć koszt programowania.

Dodawanie definicji zestawu umiejętności

Zacznij od podstawowej struktury. W interfejsie API REST tworzenia zestawu umiejętności treść żądania jest tworzona w formacie JSON i zawiera następujące sekcje:

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[
       
   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"An Azure AI services resource in the same region as Azure AI Search",
      "key":"<Your-Cognitive-Services-Multiservice-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

Po nazwie i opisie zestaw umiejętności ma cztery główne właściwości:

  • skills tablica, nieurządkowana kolekcja umiejętności. Umiejętności mogą być narzędziowe (takie jak dzielenie tekstu), przekształcanie (oparte na sztucznej inteligencji z usług AI platformy Azure) lub niestandardowe umiejętności, które udostępniasz. Przykład tablicy umiejętności znajduje się w następnej sekcji.

  • cognitiveServices służy do naliczania opłat za umiejętności , które nazywają interfejsy API usług Azure AI. Usuń tę sekcję, jeśli nie używasz umiejętności rozliczanych lub wyszukiwania jednostek niestandardowych. Dołącz zasób , jeśli jesteś.

  • knowledgeStore (opcjonalnie) określa konto usługi Azure Storage i ustawienia dotyczące projekcji danych wyjściowych zestawu umiejętności w tabelach, obiektach blob i plikach w usłudze Azure Storage. Usuń tę sekcję, jeśli jej nie potrzebujesz, w przeciwnym razie określ magazyn wiedzy.

  • encryptionKey(opcjonalnie) określa usługę Azure Key Vault i klucze zarządzane przez klienta używane do szyfrowania poufnej zawartości (opisy, parametry połączenia, klucze) w definicji zestawu umiejętności. Usuń tę właściwość, jeśli nie używasz szyfrowania zarządzanego przez klienta.

Dodawanie umiejętności

Wewnątrz definicji zestawu umiejętności tablica umiejętności określa, które umiejętności należy wykonać. Wspólne są trzy do pięciu umiejętności, ale w razie potrzeby można dodać tyle umiejętności, które podlegają limitom usług.

Wynikiem końcowym potoku wzbogacania jest zawartość tekstowa w indeksie wyszukiwania lub magazynie wiedzy. Z tego powodu większość umiejętności tworzy tekst na podstawie obrazów (tekst OCR, podpis, tagi) lub przeanalizuj istniejący tekst w celu utworzenia nowych informacji (jednostek, kluczowych fraz, tonacji). Umiejętności, które działają niezależnie, są przetwarzane równolegle. Umiejętności, które zależą od siebie, określają dane wyjściowe jednej umiejętności (np. kluczowe frazy) jako dane wejściowe drugiej umiejętności (np. tłumaczenie tekstu). Usługa wyszukiwania określa kolejność wykonywania umiejętności i środowiska wykonywania.

Wszystkie umiejętności mają typ, kontekst, dane wejściowe i wyjściowe. Umiejętność może opcjonalnie mieć nazwę i opis. W poniższym przykładzie przedstawiono dwa niepowiązane wbudowane umiejętności , dzięki czemu można porównać podstawową strukturę.

"skills": [
    {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "name": "#1",
        "description": "This skill detects organizations in the source content",
        "context": "/document",
        "categories": [
            "Organization"
        ],
        "inputs": [
            {
                "name": "text",
                "source": "/document/content"
            }
        ],
        "outputs": [
            {
                "name": "organizations",
                "targetName": "orgs"
            }
        ]
    },
    {
        "name": "#2",
        "description": "This skill detects corporate logos in the source files",
        "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
        "context": "/document/normalized_images/*",
        "visualFeatures": [
            "brands"
        ],
        "inputs": [
            {
                "name": "image",
                "source": "/document/normalized_images/*"
            }
        ],
        "outputs": [
            {
                "name": "brands"
            }
        ]
    }
]

Każda umiejętność jest unikatowa pod względem wartości wejściowych i parametrów, które przyjmuje. Dokumentacja referencyjna umiejętności opisuje wszystkie parametry i właściwości danej umiejętności. Chociaż istnieją różnice, większość umiejętności ma wspólny zestaw i jest podobnie wzorzyste.

Uwaga

Możesz tworzyć złożone zestawy umiejętności za pomocą pętli i rozgałęziania przy użyciu umiejętności warunkowych w celu utworzenia wyrażeń. Składnia jest oparta na notacji ścieżki wskaźnika JSON z kilkoma modyfikacjami identyfikującymi węzły w drzewie wzbogacania. Element "/" przechodzi przez poziom niższy w drzewie i "*" działa jako operator for-each w kontekście. Wiele przykładów w tym artykule ilustruje składnię.

Ustawianie kontekstu umiejętności

Każda umiejętność ma właściwość kontekstu, która określa poziom, na którym odbywają się operacje. Jeśli właściwość "context" nie jest jawnie ustawiona, wartość domyślna to "/document", gdzie kontekst jest całym dokumentem (umiejętność jest wywoływana raz na dokument).

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

Kontekst jest zwykle ustawiony na jeden z następujących przykładów:

Przykład kontekstu opis
"context": "/document" (Ustawienie domyślne) Dane wejściowe i wyjściowe są na poziomie dokumentu.
"context": "/document/pages/*" Niektóre umiejętności, takie jak analiza tonacji, działają lepiej w przypadku mniejszych fragmentów tekstu. Jeśli dzielisz duże pole zawartości na strony lub zdania, kontekst powinien być nad każdą częścią składnika.
"context": "/document/normalized_images/*" W przypadku zawartości obrazu dane wejściowe i wyjściowe są jedno na obraz w dokumencie nadrzędnym.

Kontekst określa również, gdzie są generowane dane wyjściowe w drzewie wzbogacania. Na przykład umiejętność rozpoznawania jednostek zwraca właściwość o nazwie "organizations", przechwyconą jako orgs. Jeśli kontekst to "/document", węzeł "organizacje" zostanie dodany jako element podrzędny "/document". Jeśli chcesz odwołać się do tego węzła w umiejętności podrzędnych, ścieżka będzie następująca "/document/orgs": .

Definiowanie danych wejściowych

Umiejętności odczytywane z i zapisywane w wzbogaconym dokumencie. Dane wejściowe umiejętności określają pochodzenie danych przychodzących. Często jest to węzeł główny wzbogaconego dokumentu. W przypadku obiektów blob typowe dane wejściowe umiejętności to właściwość zawartości dokumentu.

Dokumentacja referencyjna umiejętności dla każdej umiejętności opisuje dane wejściowe, z których może korzystać. Każde dane wejściowe ma wartość "name", która identyfikuje określone dane wejściowe i "źródło", które określa lokalizację danych w wzbogaconym dokumencie. Poniższy przykład pochodzi z umiejętności rozpoznawania jednostek:

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]

  • Umiejętności mogą mieć wiele danych wejściowych. Wartość "name" jest konkretnymi danymi wejściowymi. W przypadku rozpoznawania jednostek określone dane wejściowe to "tekst" i "languageCode".

  • Właściwość "source" określa, które pole lub wiersz udostępnia zawartość do przetworzenia. W przypadku umiejętności opartych na tekście źródło jest polem w dokumencie lub wierszu zawierającym tekst. W przypadku umiejętności opartych na obrazach węzeł dostarczający dane wejściowe jest znormalizowanymi obrazami.

    Przykład źródła opis
    "source": "/document" W przypadku zestawu danych tabelarycznych dokument odpowiada wierszowi.
    "source": "/document/content" W przypadku obiektów blob źródło jest zwykle właściwością zawartości obiektu blob.
    "source": "/document/some-named-field" W przypadku umiejętności opartych na tekście, takich jak rozpoznawanie jednostek lub wyodrębnianie kluczowych fraz, źródło powinno być polem zawierającym wystarczającą ilość tekstu do przeanalizowania, na przykład "opis" lub "podsumowanie".
    "source": "/document/normalized_images/*" W przypadku zawartości obrazu źródłem jest obraz, który został znormalizowany podczas pękania dokumentu.

Jeśli umiejętność iteruje tablicę, zarówno kontekst, jak i źródło danych wejściowych powinny zawierać /* się w odpowiednich pozycjach.

Definiowanie danych wyjściowych

Każda umiejętność jest przeznaczona do emitowania określonych rodzajów danych wyjściowych, do których odwołuje się nazwa zestawu umiejętności. Dane wyjściowe umiejętności mają wartość "name" i opcjonalną wartość "targetName".

Dokumentacja referencyjna umiejętności dla każdej umiejętności opisuje dane wyjściowe, które może wygenerować. Poniższy przykład pochodzi z umiejętności rozpoznawania jednostek:

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]

  • Umiejętności mogą mieć wiele danych wyjściowych. Wartość "name" identyfikuje określone dane wyjściowe. Na przykład w przypadku rozpoznawania jednostek dane wyjściowe mogą być "osobami", "lokalizacjami", "organizacjami".

  • "targetName" określa nazwę, którą ten węzeł ma mieć w wzbogaconym dokumencie. Jest to przydatne, jeśli dane wyjściowe umiejętności mają taką samą nazwę. Jeśli masz wiele umiejętności, które zwracają te same dane wyjściowe, użyj "targetName" funkcji uściślania nazw w ścieżkach węzłów wzbogacania. Jeśli nazwa docelowa jest nieokreślona, właściwość name jest używana dla obu tych elementów.

Niektóre sytuacje wymagają odwoływania się do każdego elementu tablicy oddzielnie. Załóżmy na przykład, że chcesz przekazać każdy element "/document/orgs" oddzielnie do innej umiejętności. W tym celu dodaj gwiazdkę do ścieżki: "/document/orgs/*".

Dane wyjściowe umiejętności są zapisywane w wzbogaconym dokumencie jako nowy węzeł w drzewie wzbogacania. Może to być prosta wartość, taka jak wynik tonacji lub kod języka. Może to być również kolekcja, taka jak lista organizacji, osób lub lokalizacji. Dane wyjściowe umiejętności mogą być również złożoną strukturą, podobnie jak w przypadku umiejętności kształtowania. Dane wejściowe umiejętności określają kompozycję kształtu, ale dane wyjściowe są nazwanym obiektem, do którego można odwoływać się w indeksie wyszukiwania, projekcji magazynu wiedzy lub innej umiejętności według jego nazwy.

Dodawanie umiejętności niestandardowej

Ta sekcja zawiera przykład umiejętności niestandardowej. Identyfikator URI wskazuje funkcję platformy Azure, która z kolei wywołuje model lub transformację, którą podajesz. Aby uzyskać więcej informacji, zobacz Definiowanie interfejsu niestandardowego.

Mimo że niestandardowa umiejętność wykonuje kod, który jest zewnętrzny dla potoku, w tablicy umiejętności jest to tylko kolejna umiejętność. Podobnie jak w przypadku wbudowanych umiejętności, ma typ, kontekst, dane wejściowe i wyjściowe. Odczytuje również i zapisuje w drzewie wzbogacania, podobnie jak w przypadku wbudowanych umiejętności. Zwróć uwagę, że pole "kontekst" ma ustawioną "/document/orgs/*" gwiazdkę, co oznacza, że krok wzbogacania jest wywoływany dla każdej organizacji w obszarze "/document/orgs".

Dane wyjściowe, takie jak opis firmy w tym przykładzie, są generowane dla każdej zidentyfikowanej organizacji. W przypadku odwoływania się do węzła w kroku podrzędnym (na przykład w wyodrębnieniu kluczowych fraz) należy użyć ścieżki "/document/orgs/*/companyDescription" , aby to zrobić.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "This skill calls an Azure function, which in turn calls custom code",
  "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeCode?code=foo",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "foobar"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

Wysyłanie danych wyjściowych do miejsca docelowego

Mimo że dane wyjściowe umiejętności mogą być opcjonalnie buforowane na potrzeby ponownego użycia, zwykle jest to tymczasowe i istnieje tylko wtedy, gdy wykonywanie umiejętności jest w toku.

  • Aby wysłać dane wyjściowe do pola w indeksie wyszukiwania, utwórz mapowanie pól wyjściowych w indeksatorze.

  • Aby wysłać dane wyjściowe do magazynu wiedzy, utwórz projekcję.

  • Aby wysłać dane wyjściowe do umiejętności podrzędnej, odwołaj się do danych wyjściowych według jego nazwy węzła, takiej jak "/document/organization", we właściwości źródłowej danych wejściowych umiejętności podrzędnych. Zobacz Dokumentację adnotacji , aby zapoznać się z przykładami.

Wskazówki dla pierwszego zestawu umiejętności

  • Spróbuj użyć Kreatora importu danych.

    Kreator automatyzuje kilka kroków, które mogą być trudne po raz pierwszy. Definiuje zestaw umiejętności, indeks i indeksator, w tym mapowania pól pól i mapowania pól wyjściowych. Definiuje również projekcje w magazynie wiedzy, jeśli używasz go. W przypadku niektórych umiejętności, takich jak analiza OCR lub obraz, kreator dodaje umiejętności narzędziowe, które scalają obraz i zawartość tekstowa oddzieloną podczas pękania dokumentu.

    Po uruchomieniu kreatora można otworzyć każdy obiekt w witrynie Azure Portal, aby wyświetlić jego definicję JSON.

  • Wypróbuj sesje debugowania, aby wywołać wykonywanie zestawu umiejętności w dokumencie docelowym i sprawdzić wzbogacony dokument tworzony przez zestaw umiejętności. Ustawienia i wartości wejściowe i wyjściowe można wyświetlać i modyfikować. Ten samouczek jest dobrym miejscem do rozpoczęcia: Samouczek: debugowanie zestawu umiejętności przy użyciu sesji debugowania.

Następne kroki

Pola kontekstu i źródła danych wejściowych to ścieżki do węzłów w drzewie wzbogacania. W następnym kroku dowiesz się więcej o składni ścieżki dla węzłów w drzewie wzbogacania.

Odwoływanie się do adnotacji w zestawie umiejętności