Debugowanie zestawu umiejętności Foundry IQ (Wyszukiwanie AI platformy Azure) w portalu Azure

Uwaga

Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.

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 IQ (Wyszukiwanie AI platformy Azure).

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 Sesje debugowania w usłudze Foundry IQ. Aby przećwiczyć przepływ pracy debugowania przy użyciu przykładowego dokumentu, zobacz Samouczek: sesje debugowania.

Wymagania wstępne

  • Usługa IQ platformy Foundry, dowolny region lub warstwa.

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

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

  • Azure Cosmos DB dla indeksatora bazy danych MongoDB.

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

  • W przypadku interfejsu API NoSQL usługi Azure Cosmos DB, jeśli kolekcja partycjonowana była wcześniej nie partycjonowana, 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 Azure Storage. Zgodnie z wymaganiami wstępnymi można użyć tożsamości zarządzanej przez system lub określić pełny ciąg połączenia dostępu, który zawiera klucz. Aby uzyskać więcej informacji, zobacz Connect a Foundry IQ service to other Azure resources using a managed identity (Łączenie usługi IQ rozwiązania Foundry z innymi zasobami Azure przy użyciu tożsamości zarządzanej).

Zabezpieczenia i uprawnienia

  • Aby zapisać sesję debugowania w celu Azure Storage, tożsamość usługi IQ usługi Foundry musi mieć uprawnienia Współautor danych obiektu blob usługi Storage w Azure Storage. W przeciwnym razie zaplanuj wybranie ciągu połączenia z pełnym dostępem dla sesji debugowania z Azure Storage.

  • Jeśli konto Azure Storage znajduje się za zaporą, skonfiguruj je tak, aby umożliwiało dostęp usłudze Foundry IQ.

  • Jeśli usługa Foundry IQ jest skonfigurowana do używania klucza szyfrowania zarządzanego przez klienta (CMK), poufne informacje w sesji debugowania są szyfrowane tym kluczem podczas zapisywania danych.

Tworzenie sesji debugowania

  1. Przejdź do usługi IQ usługi Foundry w portalu Azure.

  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.

    Zrzut ekranu przedstawiający polecenia sesji debugowania na stronie portalu Azure.

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

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

  6. W obszarze Dokument do debugowania wybierz pierwszy dokument w indeksie lub wybierz określony dokument. Jeśli wybierzesz konkretny dokument, w zależności od źródła danych, zostaniesz poproszony o podanie identyfikatora URI lub identyfikatora wiersza.

    Dla konkretnego dokumentu w Blob Storage: podaj URI obiektu blob. Identyfikator URI można znaleźć na stronie właściwości obiektu blob w portalu Azure.

    Zrzut ekranu przedstawiający właściwość identyfikatora URI w magazynie obiektów blob.

    W przypadku określonego dokumentu w usłudze Azure Cosmos DB for NoSQL: podaj klucz dokumentu w indeksie wyszukiwania dla wartości oraz identyfikator jednostki w usłudze Cosmos DB dla klucza partycji.

    Zrzut ekranu przedstawiający właściwości w usłudze Cosmos DB.

    Oto konfiguracja sesji debugowania dla przykładu usługi Cosmos DB.

    Zrzut ekranu przedstawiający właściwości usługi Cosmos DB w konfiguracji sesji debugowania.

  7. W koncie magazynowym wybierz konto ogólnego przeznaczenia do buforowania sesji debugowania.

  8. 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 Foundry IQ. Jeśli to pole nie zostanie zaznaczone, usługa IQ rozwiązania Foundry łączy się przy użyciu parametrów połączenia z pełnym dostępem.

  9. Wybierz pozycję Zapisz.

    • Usługa Foundry IQ tworzy kontener obiektów blob na 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.

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

Sesję debugowania można anulować podczas jej wykonywania. 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.

Rozpocznij od błędów i ostrzeżeń

Historia wykonywania indeksatora w portalu Azure 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.

Zrzut ekranu przedstawiający przyciski błędów i ostrzeżeń na górze strony.

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

Pipelines wzbogacania przez sztuczną inteligencję wyodrębniają lub wnioskują informacje i strukturę z dokumentów źródłowych, tworząc w ten sposób wzbogacony dokument. Na początku proces analizy dokumentu generuje wzbogacony dokument, który wypełniany jest węzłem głównym (/document) oraz węzłami dla dowolnej zawartości podnoszonej bezpośrednio ze źródła danych, takich jak metadane i klucz dokumentu. Więcej węzłów tworzą umiejętności podczas realizacji umiejętności, gdzie każdy wynik 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 detale to wzbogacona struktura danych dokumentu. Jeśli jednak wybierzesz umiejętność lub mapowanie, szczegóły dotyczą tego obiektu.

    Zrzut ekranu wskazujący niebieską strzałkę używaną do wyświetlania szczegółów kontekstowych.

  2. Wybierz umiejętności.

    Zrzut ekranu przedstawiający okienko szczegółów umiejętności z przechodzeniem do szczegółów, aby uzyskać więcej informacji.

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

    Zrzut ekranu przedstawiający okienko szczegółów umiejętności z ewaluatorem wyrażeń dla danych wyjściowych.

Sprawdzanie mapowań indeksów

Jeśli umiejętności tworzą wyniki, ale indeks wyszukiwania jest pusty, sprawdź odwzorowania pól. Mapowania pól określają sposób, w jaki zawartość jest przenoszona z potoku do indeksu wyszukiwania.

Zrzut ekranu przedstawiający obszar mapowań indeksu przepływu pracy.

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 Import data. Te mapowania określają relacje pól nadrzędno-podrzędnych (fragmentów) i to, czy tylko dla fragmentowanej zawartości tworzony jest indeks pomocniczy.

  • 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 składnia ścieżek węzłów wzbogacających.

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

Zrzut ekranu przedstawiający węzeł mapowań pól wyjściowych i szczegóły.

Edytowanie definicji umiejętności

Jeśli mapowania pól są poprawne, sprawdź poszczególne umiejętności pod kątem konfiguracji i zawartości. Jeśli umiejętności nie udaje się wygenerować danych wyjściowych, może to być spowodowane brakiem właściwości lub parametru, co można zidentyfikować 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 IQ rozwiązania Foundry. 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ść na obszarze roboczym. 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 do odwoływania 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. Węzeł ten jest uzupełniany na podstawie właściwości zawartości blobu.
    • /document/merged_content w przypadku fragmentów tekstu w zestawach umiejętności zawierających umiejętność scalania tekstu.
    • /document/normalized_images/* dla tekstu rozpoznawanego lub wnioskowanego z obrazów.

Debuguj lokalnie umiejętność niestandardową

Niestandardowe umiejętności mogą być trudniejsze do debugowania, ponieważ kod działa zewnętrznie, więc sesja debugowania nie może być wykorzystana do ich analizy. W tej sekcji opisano sposób lokalnego debugowania umiejętności niestandardowego internetowego interfejsu API, sesji debugowania, kodu Visual Studio i ngrok lub Tunnelmole. Ta technika działa z niestandardowymi funkcjonalnościami wykonywanymi w Azure Functions lub w dowolnym innym frameworku webowym działającym lokalnie (na przykład FastAPI).

Uzyskiwanie publicznego adresu URL

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

Korzystanie z rozwiązania Tunnelmole

Tunnelmole to narzędzie do tunelowania 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
    • Na komputerze 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. Lub jeśli nie masz zainstalowanego Node.js, 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 Azure.

Użyj ngrok

ngrok to popularna aplikacja wieloplatformowa o zamkniętym kodzie źródłowym, która może utworzyć adres URL tunelu lub przekierowania, dzięki czemu żądania internetowe docierają do Twojego komputera lokalnego. Użyj narzędzia ngrok, aby przekazać żądania z potoku wzbogacania w usłudze IQ usługi Foundry na Twój komputer, aby umożliwić lokalne debugowanie.

  1. Zainstaluj program ngrok.

  2. Otwórz terminal i przejdź do folderu z plikiem wykonywalnym ngrok.

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

    ngrok http 7071 
    

    Uwaga

    Domyślnie funkcje Azure są dostępne na porcie 7071. Inne narzędzia i konfiguracje mogą wymagać podania innego portu.

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

    Zrzut ekranu przedstawiający terminal ngrok.

Skonfiguruj w portalu Azure

Po utworzeniu publicznego adresu URL dla swojej niestandardowej umiejętności zmodyfikuj URI niestandardowej umiejętności Web API w ramach sesji debugowania, aby wywołać adres URL przekazywania Tunnelmole lub ngrok. Pamiętaj, aby dołączyć element "/api/FunctionName" podczas używania funkcji 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 Azure. Możesz użyć punktów przerwania w kodzie Visual Studio, aby debugować kod lub uruchamiać krok po kroku.

Następne kroki

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