Udostępnij za pośrednictwem

Samouczek: naprawianie zestawu umiejętności przy użyciu sesji debugowania

  • Artykuł

W usłudze Azure AI Search zestaw umiejętności koordynuje działania umiejętności, które analizują, przekształcają lub tworzą zawartość z możliwością wyszukiwania. Często dane wyjściowe jednej umiejętności stają się danymi wejściowymi innego. Gdy dane wejściowe zależą od danych wyjściowych, błędy w definicjach zestawu umiejętności i skojarzeniach pól mogą spowodować nieodebrane operacje i dane.

Sesje debugowania to narzędzie witryny Azure Portal, które udostępnia całościową wizualizację zestawu umiejętności wykonywanego w usłudze Azure AI Search. Za pomocą tego narzędzia możesz przejść do szczegółów określonych kroków, aby łatwo sprawdzić, gdzie może spadać akcja.

W tym artykule użyj sesji debugowania, aby znaleźć i naprawić brakujące dane wejściowe i wyjściowe. Samouczek jest all-inclusive. Udostępnia przykładowe dane, plik REST, który tworzy obiekty i instrukcje dotyczące debugowania problemów w zestawie umiejętności.

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

Wymagania wstępne

  • Azure AI Search. Utwórz usługę lub znajdź istniejącą usługę w ramach bieżącej subskrypcji. W tym samouczku możesz skorzystać z bezpłatnej usługi. Warstwa Bezpłatna nie zapewnia obsługi tożsamości zarządzanej dla usługa wyszukiwania usługi Azure AI. Musisz użyć kluczy dla połączeń z usługą Azure Storage.

  • Konto usługi Azure Storage z usługą Blob Storage używane do hostowania przykładowych danych oraz utrwalanie buforowanych danych utworzonych podczas sesji debugowania. Jeśli używasz bezpłatnej usługi wyszukiwania, konto magazynu musi mieć włączone klucze dostępu współdzielonego i musi zezwalać na dostęp do sieci publicznej.

  • Program Visual Studio Code z klientem REST.

  • Przykładowe pliki PDF (badania kliniczne).

  • Przykładowy plik debug-sessions.rest używany do tworzenia potoku wzbogacania.

Uwaga

W tym samouczku używane są również usługi Azure AI do wykrywania języka, rozpoznawania jednostek i wyodrębniania kluczowych fraz. Ponieważ obciążenie jest tak małe, usługi azure AI są zakulisowe, aby bezpłatnie przetwarzać do 20 transakcji. Oznacza to, że możesz wykonać to ćwiczenie bez konieczności tworzenia rozliczanego zasobu usług Azure AI.

Konfigurowanie przykładowych danych

W tej sekcji tworzony jest przykładowy zestaw danych w usłudze Azure Blob Storage, dzięki czemu indeksator i zestaw umiejętności mają zawartość do pracy.

  1. Pobierz przykładowe dane (clinical-trials-pdf-19), składające się z 19 plików.

  2. Utwórz konto usługi Azure Storage lub znajdź istniejące konto.

    • Wybierz ten sam region co usługa Azure AI Search, aby uniknąć opłat za przepustowość.

    • Wybierz typ konta StorageV2 (ogólnego przeznaczenia w wersji 2).

  3. Przejdź do stron usług Azure Storage w portalu i utwórz kontener obiektów blob. Najlepszym rozwiązaniem jest określenie poziomu dostępu "prywatny". Nadaj kontenerowi clinicaltrialdatasetnazwę .

  4. W kontenerze wybierz pozycję Przekaż , aby przekazać pobrane i rozpakowane pliki przykładowe w pierwszym kroku.

  5. W portalu skopiuj parametry połączenia dla usługi Azure Storage. Możesz pobrać parametry połączenia z pozycji Ustawienia>Klucze dostępu w portalu.

Kopiowanie klucza i adresu URL

W tym samouczku używane są klucze interfejsu API do uwierzytelniania i autoryzacji. Potrzebujesz punktu końcowego usługi wyszukiwania i klucza interfejsu API, który można uzyskać z witryny Azure Portal.

  1. Zaloguj się do witryny Azure Portal, przejdź do strony Przegląd i skopiuj adres URL. Przykładowy punkt końcowy może wyglądać podobnie jak https://mydemo.search.windows.net.

  2. W obszarze Klucze ustawień>skopiuj klucz administratora. Klucze administracyjne służą do dodawania, modyfikowania i usuwania obiektów. Istnieją dwa zamienne klucze administratora. Skopiuj jedną z nich.

    Zrzut ekranu przedstawiający adres URL i klucze interfejsu API w witrynie Azure Portal.

Prawidłowy klucz interfejsu API ustanawia relację zaufania dla poszczególnych żądań między aplikacją wysyłającą żądanie a usługą wyszukiwania, która go obsługuje.

Tworzenie źródła danych, zestawu umiejętności, indeksu i indeksatora

W tej sekcji utwórz przepływ pracy "buggy", który można naprawić w tym samouczku.

  1. Uruchom program Visual Studio Code i otwórz debug-sessions.rest plik.

  2. Podaj następujące zmienne: adres URL usługi wyszukiwania, klucz interfejsu API administratora usług wyszukiwania, parametry połączenia magazynu i nazwę kontenera obiektów blob przechowując pliki PDF.

  3. Wyślij każde żądanie z kolei. Tworzenie indeksatora trwa kilka minut.

  4. Zamknij plik.

Sprawdzanie wyników w portalu

Przykładowy kod celowo tworzy indeks usterek w wyniku problemów, które wystąpiły podczas wykonywania zestawu umiejętności. Problem polega na tym, że w indeksie brakuje danych.

  1. W witrynie Azure Portal na stronie Przegląd usługi wyszukiwania wybierz kartę Indeksy.

  2. Wybierz badania kliniczne.

  3. Wprowadź ten ciąg zapytania JSON w widoku JSON eksploratora wyszukiwania. Zwraca pola dla określonych dokumentów (zidentyfikowanych przez unikatowe metadata_storage_path pole).

    "search": "*",
"select": "metadata_storage_path, organizations, locations",
"count": true

  4. Uruchamianie zapytania. Powinny zostać wyświetlone puste wartości dla organizations i locations.

    Te pola powinny zostać wypełnione za pomocą umiejętności rozpoznawania jednostek zestawu umiejętności, używanej do wykrywania organizacji i lokalizacji w dowolnym miejscu zawartości obiektu blob. W następnym ćwiczeniu z debugujesz zestaw umiejętności, aby określić, co poszło nie tak.

Innym sposobem zbadania błędów i ostrzeżeń jest witryna Azure Portal.

  1. Otwórz kartę Indeksatory i wybierz pozycję clinical-trials-idxr.

    Zwróć uwagę, że chociaż zadanie indeksatora zakończyło się pomyślnie, wystąpiły ostrzeżenia.

  2. Wybierz pozycję Powodzenie , aby wyświetlić ostrzeżenia (jeśli wystąpiły głównie błędy, link szczegółów będzie niepowodzeniem). Zobaczysz długą listę wszystkich ostrzeżeń emitowanych przez indeksator.

    Zrzut ekranu przedstawiający ostrzeżenia widoku.

Uruchamianie sesji debugowania

  1. W okienku nawigacji po lewej stronie usługi wyszukiwania w obszarze Zarządzanie wyszukiwaniem wybierz pozycję Sesje debugowania.

  2. Wybierz pozycję + Dodaj sesję debugowania.

  3. Nadaj sesji nazwę.

  4. W szablonie indeksatora podaj nazwę indeksatora. Indeksator zawiera odwołania do źródła danych, zestawu umiejętności i indeksu.

  5. Wybierz konto magazynu.

  6. Zapisz sesję.

    Zrzut ekranu przedstawiający stronę definicji sesji debugowania.

  7. Zostanie otwarta sesja debugowania na stronie ustawień. Możesz wprowadzić modyfikacje początkowej konfiguracji i zastąpić wszystkie ustawienia domyślne. Sesja debugowania działa tylko z jednym dokumentem. Ustawieniem domyślnym jest zaakceptowanie pierwszego dokumentu w kolekcji jako podstawy sesji debugowania. Możesz wybrać konkretny dokument do debugowania , podając jego identyfikator URI w usłudze Azure Storage.

  8. Po zakończeniu inicjowania sesji debugowania powinien zostać wyświetlony przepływ pracy umiejętności z mapowaniami i indeksem wyszukiwania. Wzbogacona struktura danych dokumentu jest wyświetlana w okienku szczegółów po stronie. Wykluczyliśmy go z poniższego zrzutu ekranu, aby zobaczyć więcej przepływu pracy.

    Zrzut ekranu przedstawiający edytor wizualizacji Sesja debugowania.

Znajdowanie problemów z zestawem umiejętności

Wszelkie problemy zgłaszane przez indeksator są wskazywane jako błędy i ostrzeżenia.

Zwróć uwagę, że liczba błędów i ostrzeżeń jest znacznie mniejsza niż wyświetlana wcześniej, ponieważ ta lista zawiera tylko szczegóły błędów dla pojedynczego dokumentu. Podobnie jak lista wyświetlana przez indeksator, możesz wybrać komunikat ostrzegawczy i wyświetlić szczegóły tego ostrzeżenia.

Wybierz pozycję Ostrzeżenia , aby przejrzeć powiadomienia. Powinny zostać wyświetlone cztery:

  • "Nie można wykonać umiejętności, ponieważ co najmniej jeden wkład umiejętności był nieprawidłowy. Brak wymaganych danych wejściowych umiejętności. Nazwa: "text", Źródło: '/document/content'".

  • "Nie można zamapować pola wyjściowego "locations" na indeks wyszukiwania. Sprawdź właściwość "outputFieldMappings" indeksatora. Brak wartości "/document/merged_content/locations".

  • "Nie można mapować pola wyjściowego "organizacje" na indeks wyszukiwania. Sprawdź właściwość "outputFieldMappings" indeksatora. Brak wartości "/document/merged_content/organizations".

  • "Wykonane umiejętności, ale mogą mieć nieoczekiwane wyniki, ponieważ co najmniej jeden wkład umiejętności był nieprawidłowy. Brak opcjonalnych danych wejściowych umiejętności. Nazwa: 'languageCode', Źródło: '/document/languageCode'. Problemy z analizowaniem języka wyrażeń: Brak wartości "/document/languageCode".

Wiele umiejętności ma parametr "languageCode". Sprawdzając operację, możesz zobaczyć, że brakuje danych wejściowych kodu języka z EntityRecognitionSkill.#1tabeli , która jest tą samą umiejętnością rozpoznawania jednostek, która ma problemy z danymi wyjściowymi "lokalizacji" i "organizacji".

Ponieważ wszystkie cztery powiadomienia dotyczą tej umiejętności, następnym krokiem jest debugowanie tej umiejętności. Jeśli to możliwe, najpierw rozwiąż problemy z danymi wejściowymi przed przejściem do problemów z danymi wyjściowymi.

Naprawianie brakujących wartości wejściowych umiejętności

  1. Na powierzchni pracy wybierz umiejętności, które zgłaszają ostrzeżenia. W tym samouczku jest to umiejętność rozpoznawania jednostek.

  2. Po prawej stronie zostanie otwarte okienko Szczegóły umiejętności z sekcjami iteracji oraz ich odpowiednimi danymi wejściowymi i wyjściowymi, ustawieniami umiejętności dla definicji umiejętności JSON oraz komunikatami dotyczącymi błędów i ostrzeżeń, które emitują ta umiejętność.

    Zrzut ekranu przedstawiający okienko szczegółów umiejętności.

  3. Umieść kursor na poszczególnych danych wejściowych (lub wybierz dane wejściowe), aby wyświetlić wartości w ewaluatorze wyrażeń. Zwróć uwagę, że wyświetlany wynik dla tych danych wejściowych nie wygląda jak wprowadzanie tekstu. Wygląda jak seria nowych znaków \n \n\n\n\n wiersza zamiast tekstu. Brak tekstu oznacza, że nie można zidentyfikować żadnych jednostek, więc ten dokument nie spełnia wymagań wstępnych umiejętności lub istnieje inne dane wejściowe, które powinny być używane.

    Zrzut ekranu przedstawiający dane wejściowe umiejętności z wartościami null.

  4. Wróć do wzbogaconej struktury danych i przejrzyj węzły wzbogacania dla tego dokumentu. Zwróć uwagę, że właściwość \n \n\n\n\n "content" nie ma źródła źródłowego, ale inna wartość "merged_content" ma dane wyjściowe OCR. Chociaż nie ma żadnych wskazówek, zawartość tego pliku PDF wydaje się być plikiem JPEG, co jest dowodem wyodrębnionego i przetworzonego tekstu w "merged_content".

    Zrzut ekranu przedstawiający wzbogaconą strukturę danych.

  5. Wróć do umiejętności i wybierz pozycję Ustawienia zestawu umiejętności, aby otworzyć definicję JSON.

  6. Zmień wyrażenie z /document/content na /document/merged_content, a następnie wybierz pozycję Zapisz. Zwróć uwagę, że ostrzeżenie nie jest już wyświetlane.

    Zrzut ekranu przedstawiający ewaluator wyrażeń dla stałych danych wejściowych merged_content.

  7. Wybierz pozycję Uruchom w menu okna sesji. Rozpoczyna to kolejne wykonanie zestawu umiejętności przy użyciu dokumentu.

  8. Po zakończeniu wykonywania sesji debugowania zwróć uwagę, że liczba ostrzeżeń zmniejszyła się o jedną. Ostrzeżenia pokazują, że błąd dla wprowadzania tekstu zniknął, ale pozostałe ostrzeżenia pozostają. Następnym krokiem jest rozwiązanie problemu z ostrzeżeniem dotyczącym brakującej lub pustej wartości /document/languageCode.

    Zrzut ekranu przedstawiający zaktualizowane błędy i ostrzeżenia.

  9. Wybierz umiejętności i umieść kursor nad elementem /document/languageCode. Wartość dla tych danych wejściowych ma wartość null, która nie jest prawidłowym wejściem.

  10. Podobnie jak w przypadku poprzedniego problemu, zacznij od przejrzenia struktury wzbogaconych danych pod kątem dowodów na jego węzły. Zwróć uwagę, że nie ma węzła "languageCode", ale istnieje jeden dla "language". W ustawieniach umiejętności jest więc literówka.

  11. Skopiuj wyrażenie /document/language.

  12. W okienku Szczegóły umiejętności wybierz pozycję Ustawienia umiejętności dla umiejętności #1 i wklej nową wartość /document/language.

  13. Wybierz pozycję Zapisz.

  14. Wybierz Uruchom.

  15. Po zakończeniu wykonywania sesji debugowania możesz sprawdzić wyniki w okienku Szczegóły umiejętności. Po umieszczeniu wskaźnika myszy /document/languagena obiekcie powinna być widoczna en wartość w ewaluatorze wyrażeń.

Zwróć uwagę, że ostrzeżenia wejściowe znikną. Istnieją teraz tylko dwa ostrzeżenia dotyczące pól wyjściowych dla organizacji i lokalizacji.

Naprawianie brakujących wartości wyjściowych umiejętności

Komunikaty mówią, aby sprawdzić właściwość "outputFieldMappings" indeksatora, więc zacznijmy tam.

  1. Wybierz pozycję Mapowania pól wyjściowych na powierzchni roboczej. Zwróć uwagę, że brakuje mapowań pól wyjściowych.

    Zrzut ekranu przedstawiający mapowania pól wyjściowych.

  2. W pierwszym kroku upewnij się, że indeks wyszukiwania ma oczekiwane pola. W tym przypadku indeks zawiera pola "lokalizacje" i "organizacje".

  3. Jeśli nie ma problemu z indeksem, następnym krokiem jest sprawdzenie danych wyjściowych umiejętności. Tak jak poprzednio, wybierz strukturę wzbogaconych danych i przewiń węzły, aby znaleźć "lokalizacje" i "organizacje". Zwróć uwagę, że element nadrzędny to "zawartość" zamiast "merged_content". Kontekst jest nieprawidłowy.

  4. Wróć do okienka Szczegóły umiejętności, aby uzyskać umiejętności rozpoznawania jednostek.

  5. W obszarze Ustawienia umiejętności zmień wartość context na document/merged_content. W tym momencie należy mieć trzy modyfikacje definicji umiejętności.

    Zrzut ekranu przedstawiający definicję umiejętności ze wszystkimi wskazanymi modyfikacjami.

  6. Wybierz pozycję Zapisz.

  7. Wybierz Uruchom.

Wszystkie błędy zostały rozwiązane.

Zatwierdzanie zmian w zestawie umiejętności

Po zainicjowaniu sesji debugowania usługa wyszukiwania utworzyła kopię zestawu umiejętności. Zostało to zrobione w celu ochrony oryginalnego zestawu umiejętności w usłudze wyszukiwania. Po zakończeniu debugowania zestawu umiejętności można przekazać poprawki (zastąpić oryginalny zestaw umiejętności).

Alternatywnie, jeśli nie jesteś gotowy do zatwierdzenia zmian, możesz zapisać sesję debugowania i ponownie otworzyć ją później.

  1. Wybierz pozycję Zatwierdź zmiany w głównym menu Sesje debugowania.

  2. Wybierz przycisk OK , aby potwierdzić, że chcesz zaktualizować zestaw umiejętności.

  3. Zamknij sesję debugowania i otwórz indeksatory w okienku nawigacji po lewej stronie.

  4. Wybierz pozycję "clinical-trials-idxr".

  5. Wybierz Resetuj.

  6. Wybierz Uruchom.

  7. Wybierz pozycję Odśwież , aby wyświetlić stan poleceń resetowania i uruchamiania.

Po zakończeniu działania indeksatora powinien istnieć zielony znacznik wyboru i słowo Powodzenie obok sygnatury czasowej dla najnowszego uruchomienia na karcie Historia wykonywania. Aby upewnić się, że zmiany zostały zastosowane:

  1. W okienku nawigacji po lewej stronie otwórz pozycję Indeksy.

  2. Wybierz indeks "badania kliniczne", a następnie na karcie Eksplorator wyszukiwania wprowadź ten ciąg zapytania: $select=metadata_storage_path, organizations, locations&$count=true aby zwrócić pola dla określonych dokumentów (zidentyfikowanych przez unikatowe metadata_storage_path pole).

  3. Wybierz Wyszukaj.

Wyniki powinny wskazywać, że organizacje i lokalizacje są teraz wypełniane oczekiwanymi wartościami.

Czyszczenie zasobów

Jeśli pracujesz w ramach własnej subskrypcji, dobrym pomysłem po zakończeniu projektu jest sprawdzenie, czy dalej potrzebujesz utworzonych zasobów. Uruchomione zasoby mogą generować koszty. Zasoby możesz usuwać pojedynczo lub jako grupę zasobów, usuwając cały zestaw zasobów.

Zasoby można znaleźć w portalu i zarządzać nimi, korzystając z linku Wszystkie zasoby lub Grupy zasobów w okienku nawigacji po lewej stronie.

Bezpłatna usługa jest ograniczona do trzech indeksów, indeksatorów i źródeł danych. Możesz usunąć poszczególne elementy w portalu, aby pozostać w limicie.

Następne kroki

Ten samouczek dotyczył różnych aspektów definicji i przetwarzania zestawu umiejętności. Aby dowiedzieć się więcej na temat pojęć i przepływów pracy, zapoznaj się z następującymi artykułami: