Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
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
Przejdź do usługi IQ usługi Foundry w portalu Azure.
W menu po lewej stronie wybierz pozycję Zarządzanie wyszukiwaniem>Sesje debugowania.
Na pasku akcji u góry wybierz pozycję Dodaj sesję debugowania.
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.
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.
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.
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.
Oto konfiguracja sesji debugowania dla przykładu usługi Cosmos DB.
W koncie magazynowym wybierz konto ogólnego przeznaczenia do buforowania sesji debugowania.
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.
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.
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:
Wybierz pozycję Zapisz w okienku szczegółów umiejętności, aby zachować zmiany.
Wybierz pozycję Uruchom w oknie sesji, aby wywołać wykonywanie zestawu umiejętności przy użyciu zmodyfikowanej definicji.
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:
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.
Wybierz umiejętności.
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.
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.
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.
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.
Wybierz umiejętność na obszarze roboczym. Zostanie otwarte okienko Szczegóły umiejętności po prawej stronie.
Edytuj definicję umiejętności przy użyciu ustawień umiejętności. Możesz edytować kod JSON bezpośrednio.
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/contentw przypadku fragmentów tekstu. Węzeł ten jest uzupełniany na podstawie właściwości zawartości blobu. -
/document/merged_contentw 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.
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.
- Npm:
Uruchom to polecenie, aby utworzyć nowy tunel:
tmole 7071Powinna 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:7071W poprzednim przykładzie
https://m5hdpb-ip-49-183-170-144.tunnelmole.netprzekazuje do portu7071na 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.
Zainstaluj program ngrok.
Otwórz terminal i przejdź do folderu z plikiem wykonywalnym ngrok.
Uruchom polecenie ngrok za pomocą następującego polecenia, aby utworzyć nowy tunel:
ngrok http 7071Uwaga
Domyślnie funkcje Azure są dostępne na porcie 7071. Inne narzędzia i konfiguracje mogą wymagać podania innego portu.
Po uruchomieniu narzędzia ngrok skopiuj i zapisz publiczny adres URL dla następnego kroku. Adres URL przekazywania jest generowany losowo.
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.