Konfigurowanie śledzenia w usłudze Microsoft Foundry

Użyj śledzenia, aby debugować agentów sztucznej inteligencji i monitorować ich zachowanie w środowisku produkcyjnym. Śledzenie przechwytuje szczegółowe dane telemetryczne — w tym opóźnienia, wyjątki, zawartość monitu i operacje pobierania — dzięki czemu można szybciej identyfikować i rozwiązywać problemy.

Zalecanym punktem wyjścia jest śledzenie po stronie serwera. Funkcja Foundry włącza ją automatycznie po połączeniu zasobu usługi Application Insights z projektem. Nie są wymagane żadne zmiany kodu, a ślady są dostępne w ciągu kilku minut od jej włączenia. Śledzenie po stronie serwera działa dla dowolnego agenta hostowanego w narzędziu Foundry. Jeśli potrzebujesz wglądu w własny kod aplikacji — na przykład w celu śledzenia niestandardowej logiki otaczającej wywołanie agenta — możesz dodać instrumentację po stronie klienta jako drugi krok.

Microsoft Foundry Skill pomaga wybrać śledzenie po stronie serwera lub klienta oraz rozwiązywać problemy z brakującą telemetrią.

Wymagania wstępne

• Projekt Foundry.
• Zasób usługi Application Insights Azure Monitor do przechowywania śladów (utwórz nowy lub połącz istniejący).
• Dostęp do zasobu usługi Application Insights połączonego z projektem.
• Rola Log Analytics Reader w połączonym zasobie Application Insights (wymagana do wykonywania zapytań telemetrycznych). Jeśli bazowe tabele Log Analytics są chronione, przypisz również rolę Czytelnik uprzywilejowanych danych monitorowania.

Łączenie usługi Application Insights z projektem Foundry

Usługa Foundry przechowuje ślady w usłudze Application Insights przy użyciu konwencji semantycznych OpenTelemetry.

1. Zaloguj się do Microsoft Foundry. Upewnij się, że przełącznik New Foundry jest włączony. Te właśnie kroki odnoszą się do Foundry (new).

   

2. Otwórz projekt Foundry.

3. W obszarze nawigacji po lewej stronie wybierz pozycję Agenci.

4. W górnej części wybierz pozycję Ślady.

5. Po prawej stronie wybierz pozycję Połącz , aby utworzyć lub połączyć zasób usługi Application Insights.

   

• Aby połączyć istniejący zasób, wybierz zasób, a następnie wybierz pozycję Połącz.
• Aby utworzyć nowy zasób, wybierz pozycję Utwórz nowy, a następnie przejdź przez kreatora.

Po pomyślnym nawiązaniu połączenia zostanie wyświetlony komunikat potwierdzający.

Użyj ścieżki połączenia do szczegółów projektu

Jeśli nie widzisz paska komunikatów lub przycisku Połącz, użyj tego alternatywnego sposobu, aby włączyć usługę Azure Monitor Application Insights.

1. Wybierz pozycję Zarządzaj w prawym górnym rogu paska nawigacyjnego, a następnie wybierz pozycję Szczegóły projektu.
2. Wybierz kartę Połączone zasoby , a następnie wybierz pozycję Dodaj połączenie.
3. W obszarze Wybierz połączenie wybierz pozycję Application Insights.

Informacje na temat pozyskiwania śladów uwierzytelnianego za pomocą usługi Microsoft Entra zawiera artykuł Konfigurowanie uwierzytelniania Microsoft Entra na potrzeby pozyskiwania śladów agenta Foundry (wersja zapoznawcza).

Po nawiązaniu połączenia z zasobem projekt jest gotowy do użycia śledzenia.

Konfigurowanie agentów sztucznej inteligencji

Wybierz metodę, która odpowiada sposobowi, w jakim tworzysz i uruchamiasz swojego agenta.

Śledzenie po stronie serwera w Portalu Foundry

Zacznij od śladów po stronie serwera. Foundry rejestruje ślady dla typowych scenariuszy związanych z agentami i przepływem pracy bez konieczności zmiany kodu.

• Narzędzie Foundry automatycznie rejestruje ślady po stronie serwera dla agentów monitów, agentów hosta i przepływów pracy w portalu Foundry. Po włączeniu śledzenia w projekcie Foundry masz dostęp do wbudowanych śladów z ostatnich 90 dni.
• Platforma Foundry obsługuje również łatwą integrację z najlepszymi strukturami agentów.

Ślady po stronie klienta za pomocą zestawu SDK Microsoft Foundry

Zainstaluj bibliotekę OpenTelemetry i wtyczkę śledzenia Azure SDK, wykonując następujące kroki:

pip install azure-ai-projects azure-identity opentelemetry-sdk azure-core-tracing-opentelemetry

dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.Identity
dotnet add package Azure.Monitor.OpenTelemetry.Exporter
dotnet add package OpenTelemetry.Exporter.Console

using Azure.AI.Projects;
using Azure.Identity;

AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true);

var projectEndpoint = Environment.GetEnvironmentVariable(
   "FOUNDRY_PROJECT_ENDPOINT");
AIProjectClient projectClient = new(
   endpoint: new Uri(projectEndpoint!),
   tokenProvider: new DefaultAzureCredential());

Po uruchomieniu agenta można wyświetlać i analizować ślady w portalu Foundry.

Aby zapoznać się z kompleksowymi przykładami w językach Python i .NET, które eksportują ślady do usługi Azure Monitor lub do konsoli, zobacz Konfigurowanie śledzenia po stronie klienta.

Śledzenie lokalne przy użyciu rozszerzenia Microsoft Foundry Toolkit for Visual Studio Code

Rozszerzenie Microsoft Foundry Toolkit dla programu Visual Studio Code umożliwia lokalne śledzenie w programie Visual Studio Code przy użyciu lokalnego kolektora zgodnego z protokołem OTLP. Takie podejście jest idealne do programowania i debugowania.

Zestaw narzędzi obsługuje frameworki AI, takie jak Foundry Agent Service, OpenAI, Anthropic i LangChain, za pośrednictwem OpenTelemetry. Ślady są widoczne natychmiast w programie VS Code bez konieczności uzyskiwania dostępu do chmury.

Aby uzyskać szczegółowe instrukcje dotyczące konfiguracji i specyficzne dla SDK przykłady kodu, zobacz Śledzenie w Foundry Toolkit.

Wyświetlanie i analizowanie śladów

Przeglądaj ślady w portalu Foundry

W projekcie Foundry przejdź do karty Ślady w agentach lub przepływach pracy. Możesz wyszukiwać, filtrować lub sortować pozyskane ślady z ostatnich 90 dni.

Wybierz ślad, aby przejść przez poszczególne zakresy, zidentyfikować problemy i obserwować sposób reagowania aplikacji. Ten proces pomaga debugować i określać problemy w aplikacji.

Wyświetlanie śladów w Azure Monitor

Ślady są wysyłane do usługi Azure Monitor Application Insights, dzięki czemu można je tam wyświetlić.

Aby uzyskać więcej informacji na temat wysyłania śladów do Azure Monitor i tworzenia zasobu Azure Monitor, zobacz dokumentację OpenTelemetry dla Azure Monitor.

Wyświetlanie wyników konwersacji

Konwersacja to trwały kontekst kompleksowej historii dialogu między użytkownikiem a agentem. W portalu Foundry możesz wyświetlić wyniki Konwersacji dla działania agenta od razu po wyjęciu z pudełka wraz ze śladami na stronie Ślady.

Wyszukaj według identyfikatora odpowiedzi lub według identyfikatora śledzenia, który odpowiada tej rozmowie. Następnie wybierz identyfikator rozmowy, aby przejrzeć:

• Szczegóły historii konwersacji
• Informacje dotyczące odpowiedzi i tokeny w procesie
• Uporządkowane akcje, etapy uruchamiania i instrukcje dla narzędzi
• Dane wejściowe i wyjściowe między użytkownikiem a agentem

Sprawdzanie, czy śledzenie działa

1. Upewnij się, że projekt jest połączony z usługą Application Insights. W razie potrzeby wykonaj kroki opisane w temacie Łączenie usługi Application Insights z projektem foundry.

2. Uruchom agenta lub przepływ pracy co najmniej raz (na przykład przy użyciu portalu lub aplikacji).

3. W projekcie Foundry otwórz widok Ślady i upewnij się, że zostanie wyświetlony nowy ślad.

   Gdy śledzenie działa prawidłowo, zostanie wyświetlona lista ostatnich śladów ze znacznikami czasu, czasami trwania i wskaźnikami stanu. Wybierz ślad, aby wyświetlić szczegóły zakresu.

Jeśli nie widzisz nowych śladów, poczekaj kilka minut i odśwież, a następnie zobacz Rozwiązywanie problemów.

Bezpieczeństwo i prywatność

Śledzenie może przechwytywać poufne informacje, takie jak dane wejściowe użytkownika, dane wyjściowe modelu i argumenty narzędzi i wyniki. Skorzystaj z tych rozwiązań, aby zmniejszyć ryzyko:

• Nie przechowuj tajemnic, poświadczeń ani tokenów w wezwaniach, parametrach narzędzi lub atrybutach zakresu.
• Zredaguj lub ogranicz dane osobowe oraz inne poufne informacje przed ich pojawieniem się w telemetrii.
• Traktuj dane śledzenia jako dane telemetryczne produkcyjne i zastosuj te same zasady kontroli dostępu i przechowywania, które są używane dla dzienników i metryk.

Aby uzyskać więcej wskazówek, zobacz Zabezpieczenia i prywatność.

Przechowywanie i koszt danych

Narzędzie Foundry przechowuje ślady w zasobie usługi Application Insights połączonym z projektem. Przechowywanie i rozliczenia danych są zgodne z konfiguracją usługi Application Insights i Log Analytics.

Rozwiązywanie problemów

Powiązana zawartość

Teraz, po skonfigurowaniu śledzenia, zapoznaj się z tymi zasobami, aby pogłębić zrozumienie i rozszerzyć możliwości obserwacji:

• Omówienie śledzenia agentów
• Śledzenie integracji
• Monitorowanie agentów AI za pomocą pulpitu monitorowania agentów
• Obserwowalność w sztucznej inteligencji generatywnej