Debugowanie zestawu umiejętności usługi Azure AI Search w witrynie Azure Portal

Uruchom sesję debugowania opartą na portalu, aby zidentyfikować i usunąć błędy, zweryfikować zmiany i wypchnąć zmiany do istniejącego zestawu umiejętności w usłudze Azure AI usługa wyszukiwania.

Sesja debugowania to buforowany indeksator i wykonywanie zestawu umiejętności w zakresie pojedynczego dokumentu, którego można użyć do interaktywnego edytowania i testowania zmian zestawu umiejętności. Po zakończeniu debugowania możesz zapisać zmiany w zestawie umiejętności.

Aby uzyskać informacje na temat działania sesji debugowania, zobacz Debugowanie sesji w usłudze Azure AI Search. Aby przećwiczyć przepływ pracy debugowania przy użyciu przykładowego dokumentu, zobacz Samouczek: sesje debugowania.

Wymagania wstępne

• Usługa wyszukiwania sztucznej inteligencji platformy Azure. Zalecamy użycie przypisanej przez system tożsamości zarządzanej i przypisań ról, które umożliwiają usłudze Azure AI Search zapisywanie w usłudze Azure Storage i wywoływanie zasobów sztucznej inteligencji platformy Azure używanych w zestawie umiejętności.

• Konto usługi Azure Storage używane do zapisywania stanu sesji.

• Istniejący potok wzbogacania, w tym źródło danych, zestaw umiejętności, indeksator i indeks.

• W przypadku przypisań ról tożsamość usługi wyszukiwania musi mieć następujące elementy:

  • Uprawnienia użytkownika usług Cognitive Services na koncie wielousług usługi Azure AI używane przez zestaw umiejętności.

  • Uprawnienia współautora danych obiektu blob usługi Storage w usłudze Azure Storage. W przeciwnym razie zaplanuj użycie pełnego dostępu parametry połączenia dla połączenia sesji debugowania z usługą Azure Storage.

• Jeśli konto usługi Azure Storage znajduje się za zaporą, skonfiguruj je tak, aby zezwalało na dostęp do usługi wyszukiwania.

Ograniczenia

Sesje debugowania współpracują ze wszystkimi ogólnie dostępnymi źródłami danych indeksatora i większością źródeł danych w wersji zapoznawczej, z następującymi wyjątkami:

• Indeksator usługi SharePoint Online.

• Indeksator usługi Azure Cosmos DB dla bazy danych MongoDB.

• W przypadku usługi Azure Cosmos DB for NoSQL, jeśli wiersz nie powiedzie się podczas indeksu i nie ma odpowiednich metadanych, sesja debugowania może nie wybrać poprawnego wiersza.

• W przypadku interfejsu API SQL usługi Azure Cosmos DB, jeśli kolekcja partycjonowana wcześniej nie została podzielona na partycje, sesja debugowania nie znajdzie dokumentu.

• W przypadku niestandardowych umiejętności tożsamość zarządzana przypisana przez użytkownika nie jest obsługiwana w przypadku połączenia sesji debugowania z usługą Azure Storage. Zgodnie z wymaganiami wstępnymi można użyć tożsamości zarządzanej systemu lub określić pełny dostęp parametry połączenia, który zawiera klucz. Aby uzyskać więcej informacji, zobacz Łączenie usługi wyszukiwania z innymi zasobami platformy Azure przy użyciu tożsamości zarządzanej.

• Obecnie możliwość wybrania dokumentu do debugowania jest niedostępna. To ograniczenie nie jest trwałe i wkrótce zostanie zniesione. Obecnie sesje debugowania wybierają pierwszy dokument w źródłowym kontenerze danych lub folderze.

Tworzenie sesji debugowania

1. Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.

2. W menu po lewej stronie wybierz pozycję Zarządzanie wyszukiwaniem>Sesje debugowania.

3. Na pasku akcji u góry wybierz pozycję Dodaj sesję debugowania.

   

4. W polu Nazwa sesji debugowania podaj nazwę, która pomoże Zapamiętać, który zestaw umiejętności, indeksator i źródło danych dotyczy sesji debugowania.

5. W szablonie indeksatora wybierz indeksator, który kieruje zestawem umiejętności do debugowania. Kopie indeksatora i zestawu umiejętności są używane do inicjowania sesji.

6. Na koncie magazynu znajdź konto magazynu ogólnego przeznaczenia do buforowania sesji debugowania.

7. Wybierz pozycję Uwierzytelnianie przy użyciu tożsamości zarządzanej, jeśli wcześniej przypisano uprawnienia Współautor danych obiektu blob usługi Storage do tożsamości zarządzanej przez system usługi wyszukiwania.

8. Wybierz pozycję Zapisz.

   • Usługa Azure AI Search tworzy kontener obiektów blob w usłudze Azure Storage o nazwie ms-az-cognitive-search-debugsession.
   • W tym kontenerze tworzy folder przy użyciu podanej nazwy sesji.
   • Spowoduje to uruchomienie sesji debugowania.

9. Zostanie otwarta sesja debugowania na stronie ustawień. Możesz wprowadzić modyfikacje początkowej konfiguracji i zastąpić wszystkie ustawienia domyślne.

10. W parametry połączenia usługi Storage można określić parametry połączenia lub zmienić konto magazynu.

11. Opcjonalnie w obszarze Ustawienia indeksatora określ ustawienia wykonywania indeksatora używane do utworzenia sesji. Ustawienia powinny odzwierciedlać ustawienia używane przez rzeczywisty indeksator. Wszystkie opcje indeksatora określone w sesji debugowania nie mają wpływu na sam indeksator.

12. W przypadku wprowadzenia zmian wybierz pozycję Zapisz sesję, a następnie pozycję Uruchom.

Sesja debugowania rozpoczyna się od wykonania indeksatora i zestawu umiejętności w wybranym dokumencie. Zawartość i metadane dokumentu są widoczne i dostępne w sesji.

Podczas wykonywania sesji debugowania można anulować za pomocą przycisku Anuluj . Po naciśnięciu przycisku Anuluj powinno być możliwe analizowanie częściowych wyników.

Oczekuje się, że sesja debugowania trwa dłużej niż indeksator, ponieważ przechodzi przez dodatkowe przetwarzanie.

Rozpoczynanie pracy z błędami i ostrzeżeniami

Historia wykonywania indeksatora w portalu zawiera pełną listę błędów i ostrzeżeń dla wszystkich dokumentów. W sesji debugowania błędy i ostrzeżenia są ograniczone do jednego dokumentu. Możesz pracować z tą listą, wprowadzić zmiany, a następnie wrócić do listy, aby sprawdzić, czy problemy zostały rozwiązane.

Pamiętaj, że sesja debugowania jest oparta na jednym dokumencie z całego indeksu. Jeśli dane wejściowe lub wyjściowe wyglądają źle, problem może być specyficzny dla tego dokumentu. Możesz wybrać inny dokument, aby potwierdzić, czy błędy i ostrzeżenia są wszechobecne, czy specyficzne dla pojedynczego dokumentu.

Wybierz pozycję Błędy lub ostrzeżenia, aby wyświetlić listę problemów.

Najlepszym rozwiązaniem jest rozwiązywanie problemów z danymi wejściowymi przed przejściem do danych wyjściowych.

Aby udowodnić, czy modyfikacja rozwiązuje błąd, wykonaj następujące kroki:

1. Wybierz pozycję Zapisz w okienku szczegółów umiejętności, aby zachować zmiany.

2. Wybierz pozycję Uruchom w oknie sesji, aby wywołać wykonywanie zestawu umiejętności przy użyciu zmodyfikowanej definicji.

3. Wróć do błędów lub ostrzeżeń, aby sprawdzić, czy liczba jest zmniejszona.

Wyświetlanie wzbogaconej lub wygenerowanej zawartości

Potoki wzbogacania sztucznej inteligencji wyodrębniają lub wnioskowają informacje i strukturę z dokumentów źródłowych, tworząc wzbogacony dokument w procesie. Wzbogacony dokument jest tworzony po raz pierwszy podczas pękania dokumentu i wypełniany węzłem głównym () oraz/document węzłami dla dowolnej zawartości, która jest podnosina bezpośrednio ze źródła danych, takich jak metadane i klucz dokumentu. Więcej węzłów jest tworzonych przez umiejętności podczas wykonywania umiejętności, gdzie każde dane wyjściowe umiejętności dodaje nowy węzeł do drzewa wzbogacania.

Cała zawartość utworzona lub użyta przez zestaw umiejętności jest wyświetlana w ewaluatorze wyrażeń. Możesz umieścić kursor na linkach, aby wyświetlić każdą wartość wejściową lub wyjściową w wzbogaconym drzewie dokumentów. Aby wyświetlić dane wejściowe lub wyjściowe każdej umiejętności, wykonaj następujące kroki:

1. W sesji debugowania rozwiń niebieską strzałkę, aby wyświetlić szczegóły kontekstowe. Domyślnie szczegóły są wzbogaconą strukturą danych dokumentu. Jeśli jednak wybierzesz umiejętność lub mapowanie, szczegóły dotyczą tego obiektu.

   

2. Wybierz umiejętności.

   

3. Skorzystaj z linków, aby przejść dalej do przetwarzania umiejętności. Na przykład poniższy zrzut ekranu przedstawia dane wyjściowe pierwszej iteracji umiejętności dzielenia tekstu.

   

Sprawdzanie mapowań indeksów

Jeśli umiejętności generują dane wyjściowe, ale indeks wyszukiwania jest pusty, sprawdź mapowania pól. Mapowania pól określają sposób, w jaki zawartość jest przenosina z potoku i do indeksu wyszukiwania.

Wybierz jedną z opcji mapowania i rozwiń widok szczegółów, aby przejrzeć definicje źródłowe i docelowe.

• Mapowania projekcji znajdują się w zestawach umiejętności, które zapewniają zintegrowaną wektoryzację, takie jak umiejętności utworzone przez kreatora Importowanie i wektoryzowanie danych. Te mapowania określają mapowania pól nadrzędny-podrzędny (fragment) i określa, czy indeks pomocniczy jest tworzony dla tylko fragmentowanej zawartości

• Mapowania pól wyjściowych znajdują się w indeksatorach i są używane, gdy zestawy umiejętności wywołują wbudowane lub niestandardowe umiejętności. Te mapowania służą do ustawiania ścieżki danych z węzła w drzewie wzbogacania na pole w indeksie wyszukiwania. Aby uzyskać więcej informacji na temat ścieżek, zobacz wzbogacanie składni ścieżki węzła.

• Mapowania pól znajdują się w definicjach indeksatora i ustanawiają ścieżkę danych z nieprzetworzonej zawartości w źródle danych i polu w indeksie. Mapowania pól można również użyć do dodawania kroków kodowania i dekodowania.

W tym przykładzie przedstawiono szczegóły mapowania projekcji. Możesz edytować kod JSON, aby rozwiązać wszelkie problemy z mapowaniem.

Edytowanie definicji umiejętności

Jeśli mapowania pól są poprawne, sprawdź poszczególne umiejętności dotyczące konfiguracji i zawartości. Jeśli nie można wygenerować danych wyjściowych umiejętności, może brakować właściwości lub parametru, który można określić za pomocą komunikatów o błędach i walidacji.

Inne problemy, takie jak nieprawidłowy kontekst lub wyrażenie wejściowe, mogą być trudniejsze do rozwiązania, ponieważ błąd poinformuje Cię, co jest złe, ale nie sposób go naprawić. Aby uzyskać pomoc dotyczącą składni kontekstu i danych wejściowych, zobacz Temat Wzbogacanie odwołań w zestawie umiejętności usługi Azure AI Search. Aby uzyskać pomoc dotyczącą poszczególnych komunikatów, zobacz Rozwiązywanie typowych błędów i ostrzeżeń indeksatora.

Poniższe kroki pokazują, jak uzyskać informacje o umiejętności.

1. Wybierz umiejętności na powierzchni roboczej. Zostanie otwarte okienko Szczegóły umiejętności po prawej stronie.

2. Edytuj definicję umiejętności przy użyciu ustawień umiejętności. Możesz edytować kod JSON bezpośrednio.

3. Sprawdź składnię ścieżki, aby odwoływać się do węzłów w drzewie wzbogacania. Poniżej przedstawiono niektóre z najbardziej typowych ścieżek wejściowych:

   • /document/content w przypadku fragmentów tekstu. Ten węzeł jest wypełniany z właściwości zawartości obiektu blob.
   • /document/merged_content w przypadku fragmentów tekstu w umiejętnościach zawierających umiejętność scalania tekstu.
   • /document/normalized_images/* w przypadku tekstu rozpoznawanego lub wnioskowanego z obrazów.

Lokalne debugowanie umiejętności niestandardowych

Niestandardowe umiejętności mogą być trudniejsze do debugowania, ponieważ kod działa zewnętrznie, więc sesja debugowania nie może być używana do debugowania. W tej sekcji opisano sposób lokalnego debugowania niestandardowego internetowego interfejsu API, sesji debugowania, programu Visual Studio Code i narzędzia ngrok lub Tunnelmole. Ta technika działa z niestandardowymi umiejętnościami wykonywanymi w usłudze Azure Functions lub w dowolnej innej strukturze internetowej, która działa lokalnie (na przykład FastAPI).

Uzyskiwanie publicznego adresu URL

W tej sekcji opisano dwie metody uzyskiwania publicznego adresu URL do umiejętności niestandardowych.

Korzystanie z rozwiązania Tunnelmole

Tunnelmole to narzędzie tunelowania typu open source, które umożliwia utworzenie publicznego adresu URL, który przekazuje żądania do maszyny lokalnej za pośrednictwem tunelu.

1. Zainstaluj aplikację Tunnelmole:

   • npm: npm install -g tunnelmole
   • Linux: curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
   • Mac: curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
   • Windows: Zainstaluj przy użyciu narzędzia npm. Jeśli nie masz zainstalowanego środowiska NodeJS, pobierz wstępnie skompilowany plik .exe dla systemu Windows i umieść go gdzieś w ścieżce.

2. Uruchom to polecenie, aby utworzyć nowy tunel:

   tmole 7071
   

   Powinna zostać wyświetlona odpowiedź podobna do następującej:

   http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   

   W poprzednim przykładzie https://m5hdpb-ip-49-183-170-144.tunnelmole.net przekazuje do portu 7071 na komputerze lokalnym, który jest domyślnym portem, na którym są uwidocznione funkcje platformy Azure.

Korzystanie z narzędzia ngrok

ngrok to popularna, zamknięta aplikacja wieloplatformowa, która może utworzyć adres URL tunelowania lub przesyłania dalej, dzięki czemu żądania internetowe docierają do komputera lokalnego. Użyj narzędzia ngrok, aby przekazywać żądania z potoku wzbogacania w usłudze wyszukiwania do maszyny, aby umożliwić lokalne debugowanie.

1. Zainstaluj program ngrok.

2. Otwórz terminal i przejdź do folderu za pomocą pliku wykonywalnego ngrok.

3. Uruchom polecenie ngrok za pomocą następującego polecenia, aby utworzyć nowy tunel:

   ngrok http 7071 
   

   Uwaga

   Domyślnie funkcje platformy Azure są udostępniane w wersji 7071. Inne narzędzia i konfiguracje mogą wymagać podania innego portu.

4. Po uruchomieniu narzędzia ngrok skopiuj i zapisz publiczny adres URL przekazywania dla następnego kroku. Adres URL przekazywania jest generowany losowo.

   

Konfigurowanie w witrynie Azure Portal

Po utworzeniu publicznego adresu URL dla swojej umiejętności niestandardowej zmodyfikuj identyfikator URI umiejętności niestandardowego internetowego interfejsu API w ramach sesji debugowania, aby wywołać adres URL przekazywania tunnelmole lub ngrok. Pamiętaj, aby dołączyć element "/api/FunctionName" podczas korzystania z funkcji platformy Azure do wykonywania kodu zestawu umiejętności.

Definicję umiejętności można edytować w sekcji Ustawienia umiejętności w okienku Szczegóły umiejętności.

testowanie kodu

W tym momencie nowe żądania z sesji debugowania powinny być teraz wysyłane do lokalnej funkcji platformy Azure. Możesz użyć punktów przerwania w programie Visual Studio Code, aby debugować kod lub uruchamiać krok po kroku.

Następne kroki

Teraz, gdy znasz układ i możliwości edytora wizualizacji Sesje debugowania, wypróbuj samouczek, aby zapoznać się z praktycznym środowiskiem.

Samouczek: eksplorowanie sesji debugowania