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

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

Sesja debugowania jest buforowanym indeksatorem i wykonywaniem zestawu umiejętności w zakresie pojedynczego dokumentu, którego można użyć do interaktywnego edytowania i testowania zmian. 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

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

• Przypisanie roli Współautor w usłudze wyszukiwania.

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

• Przypisanie roli Współautor danych obiektu blob usługi Storage w usłudze Azure Storage, jeśli używasz tożsamości zarządzanej przez system. 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. Poniższa lista zawiera informacje o wyjątkach:

• Usługa Azure Cosmos DB dla bazy danych MongoDB nie jest obecnie obsługiwana.

• 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 Połączenie usługę wyszukiwania do innych zasobów platformy Azure przy użyciu tożsamości zarządzanej.

Portal nie obsługuje szyfrowania kluczy zarządzanych przez klienta (CMK), co oznacza, że środowiska portalu, takie jak sesje debugowania, nie mogą mieć zaszyfrowanych parametry połączenia cmK ani innych zaszyfrowanych metadanych. Jeśli usługa wyszukiwania jest skonfigurowana do wymuszania klucza zarządzanego przez klienta, sesje debugowania nie będą działać.

Tworzenie sesji debugowania

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

2. Na lewej stronie nawigacji wybierz pozycję 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 obszarze Połączenie magazynu znajdź konto magazynu ogólnego przeznaczenia do buforowania sesji debugowania. Zostanie wyświetlony monit o wybranie i opcjonalnie utworzenie kontenera obiektów blob w usłudze Blob Storage lub Azure Data Lake Storage Gen2. Możesz ponownie użyć tego samego kontenera dla wszystkich kolejnych utworzonych sesji debugowania. Przydatną nazwą kontenera może być "cognitive-search-debug-sessions".

6. W obszarze Uwierzytelnianie tożsamości zarządzanej wybierz pozycję Brak , jeśli połączenie z usługą Azure Storage nie używa tożsamości zarządzanej. W przeciwnym razie wybierz tożsamość zarządzaną, do której udzielono uprawnień Współautor danych obiektu blob usługi Storage.

7. 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.

8. W obszarze Dokument do debugowania wybierz pierwszy dokument w indeksie lub wybierz określony dokument. Jeśli wybierzesz określony dokument, w zależności od źródła danych, zostanie wyświetlony monit o identyfikator URI lub identyfikator wiersza.

   Jeśli określony dokument jest obiektem blob, podaj identyfikator URI obiektu blob. Identyfikator URI można znaleźć na stronie właściwości obiektu blob w portalu.

   

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

10. Konfiguracja powinna wyglądać podobnie do tego zrzutu ekranu. Wybierz pozycję Zapisz sesję , aby rozpocząć pracę.

    

Sesja debugowania rozpoczyna się od wykonania indeksatora i zestawu umiejętności w wybranym dokumencie. Zawartość i metadane utworzone w dokumencie będą 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 będą ograniczone do jednego dokumentu. Wykonasz pracę z tą listą, wprowadzisz zmiany, a następnie wrócisz do listy, aby sprawdzić, czy problemy zostały rozwiązane.

Aby wyświetlić komunikaty, wybierz umiejętności w grafie umiejętności wzbogacania sztucznej inteligencji>, a następnie wybierz pozycję Błędy/ostrzeżenia w okienku szczegółó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/ostrzeżeń , aby sprawdzić, czy liczba jest zmniejszona. Lista nie zostanie odświeżona, dopóki nie otworzysz karty.

Wyświetlanie zawartości węzłów wzbogacania

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.

Wzbogacone dokumenty są wewnętrzne, ale sesja debugowania zapewnia dostęp do zawartości utworzonej podczas wykonywania umiejętności. Aby wyświetlić zawartość lub dane wyjściowe każdej umiejętności, wykonaj następujące kroki:

1. Zacznij od widoków domyślnych: Wykres umiejętności wzbogacania sztucznej inteligencji > z typem grafu ustawionym na graf zależności.

2. Wybierz umiejętności.

3. W okienku szczegółów po prawej stronie wybierz pozycję Wykonania, wybierz pozycję DANE WYJŚCIOWE, a następnie otwórz ewaluator wyrażeń (</>), aby wyświetlić wyrażenie i jego wynik.

   

4. Alternatywnie otwórz wzbogacanie > sztucznej inteligencji Wzbogacona struktura danych, aby przewinąć listę węzłów w dół. Lista zawiera potencjalne i rzeczywiste węzły z kolumną danych wyjściowych oraz inną kolumną wskazującą obiekt nadrzędny używany do wygenerowania danych wyjściowych.

   

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. W obszarze Graf umiejętności wzbogacania sztucznej inteligencji > wybierz umiejętności. Po prawej stronie zostanie otwarte okienko Szczegóły umiejętności.

2. Edytuj definicję umiejętności przy użyciu dowolnego podejścia:

   • Umiejętność Ustawienia, jeśli wolisz edytor wizualizacji
   • Edytor umiejętności JSON do bezpośredniej edycji dokumentu JSON

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.

Sprawdzanie mapowań pól

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.

1. Zacznij od widoków domyślnych: Wykres umiejętności wzbogacania sztucznej inteligencji > z typem grafu ustawionym na graf zależności.

2. Wybierz pozycję Mapowania pól u góry . Należy znaleźć co najmniej klucz dokumentu, który jednoznacznie identyfikuje i kojarzy każdy dokument wyszukiwania w indeksie wyszukiwania z jego dokumentem źródłowym w źródle danych.

   Jeśli importujesz nieprzetworzone treści bezpośrednio ze źródła danych, pomijając wzbogacanie, należy je znaleźć w obszarze Mapowania pól.

3. Wybierz pozycję Mapowania pól wyjściowych w dolnej części grafu. W tym miejscu znajdziesz mapowania z danych wyjściowych umiejętności na pola docelowe w indeksie wyszukiwania. Jeśli nie użyto kreatora importu danych, mapowania pól wyjściowych są definiowane ręcznie i mogą być niekompletne lub błędnie wtypowane.

   Sprawdź, czy pola w mapowaniach pól wyjściowych istnieją w indeksie wyszukiwania, jak określono, sprawdzając składnię ścieżki węzła pisowni i wzbogacania.

   

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

Korzystanie z tunelu

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

W ramach sesji debugowania zmodyfikuj identyfikator URI umiejętności niestandardowego internetowego interfejsu API, aby wywołać adres URL przekazywania tunnelmole lub ngrok. Upewnij się, że dołączasz element "/api/FunctionName" podczas korzystania z funkcji platformy Azure do wykonywania kodu zestawu umiejętności.

Definicję umiejętności można edytować w portalu.

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