Dodawaj adnotacje do śladów przy użyciu informacji zwrotnych od użytkowników (wersja zapoznawcza)

Ważna

Elementy oznaczone podglądem w tym artykule są obecnie w wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług, a Microsoft nie zaleca korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.

Dodaj do śladów w Microsoft Foundry adnotacje „kciuk w górę” i „kciuk w dół”, aby rejestrować sygnały jakości pochodzące od ludzi dla poszczególnych interakcji agenta. Adnotacje śledzenia umożliwiają określenie, czy odpowiedź agenta była pomocna, czy nieprzydatna, i pojawiała się w tekście na stronie szczegółów śledzenia, dzięki czemu można szybko identyfikować wzorce zachowania agenta.

Adnotacje śladów umożliwiają dwa przepływy pracy:

  • Adnotacje konstruktora: Konstruktorzy i eksperci z dziedziny dodają adnotacje do śladów z portalu Foundry podczas przeglądania interakcji z agentem. Te adnotacje są automatycznie oznaczane jako pochodzące ze źródła builder.
  • Opinie użytkowników końcowych: Rejestruj programowo adnotacje w swojej aplikacji, gdy użytkownicy końcowi udzielają pozytywnej lub negatywnej opinii. Adnotacje te mają źródło end_user i pojawiają się na stronie śladu obok adnotacji buildera. Aby uzyskać szczegółowe informacje na temat rejestrowania opinii użytkowników końcowych, zobacz Rejestrowanie opinii użytkowników końcowych.

Wszystkie adnotacje są dołączane do śladu — dodanie adnotacji twórcy nigdy nie nadpisuje ani nie zastępuje istniejących informacji zwrotnych od użytkowników końcowych, a odwrotnie. Każda adnotacja zawiera atrybut źródłowy, dzięki czemu sygnały pozostają niezależnie możliwe do wysyłania zapytań i filtrowania.

Prerequisites

Domyślny szablon oceniania

Każdy projekt Foundry zawiera domyślnie szablon ocen „kciuk w górę / kciuk w dół”, który jest od razu dostępny bez dodatkowej konfiguracji. Możesz rozpocząć dodawanie adnotacji do śladów pierwszego dnia. Domyślny szablon używa binarnej oceny: zaliczone/niezaliczone:

  • Kciuki w górę = wynik 1.0, etykieta pass
  • Kciuki w dół = wynik 0.0, etykieta fail

Każdy szablon oceniania wymaga, aby atrybut gen_ai.evaluation.name miał wartość task_completion, więc każda adnotacja jest przypisywana do określonego wymiaru oceny. task_completion obsługuje kciuki w górę i w dół.

Dodawanie adnotacji do śladów w portalu Foundry

Dodaj adnotacje bezpośrednio ze strony szczegółów śledzenia, aby zarejestrować ocenę odpowiedzi agenta.

  1. Otwórz projekt Foundry i przejdź do pozycji Śledzenie w obszarze nawigacji po lewej stronie.
  2. Wybierz ślad, aby otworzyć widok szczegółów śledzenia.
  3. Na stronie szczegółów śledzenia wybierz przycisk Dodaj adnotację w prawym górnym rogu.
  4. Wybierz Kciuki w górę lub Kciuki w dół, aby przesłać swoją ocenę. Opcjonalnie dodaj wyjaśnienie wolnego tekstu.
  5. Adnotacja zapisuje się natychmiast i pojawia się w śladzie.

Zrzut ekranu karty „Adnotacje” na stronie szczegółów śladu w portalu Foundry.

Note

Wyświetlanie śledzenia i zapisywanie adnotacji są oddzielnymi operacjami autoryzacji. Jeśli ślad jest widoczny, ale nie można zapisać adnotacji, sprawdź lokalizację docelową adnotacji, rzeczywistą tożsamość zapisu i ścieżkę uwierzytelniania. Inna rola trace-reader nie przyznaje dostępu do zapisu danych telemetrycznych.

Adnotacje dodawane z portalu są automatycznie oznaczane za pomocą następujących tagów:

  • microsoft.gen_ai.human_evaluation.source = "builder"
  • microsoft.gen_ai.evaluation.actor.type = "human"

Edytowanie wyników

Każdy użytkownik może dodawać adnotacje wiele razy:

  • Wielu użytkowników może mieć własną adnotację tego samego rodzaju w ramach tego samego śladu.
  • Wcześniejsze adnotacje nie są usuwane w usłudze Application Insights. Nowe adnotacje są dołączane, a portal wyświetla wszystkie adnotacje w sekcji Historia adnotacji w panelu adnotacji.

Rejestruj opinie użytkowników końcowych jako adnotacje śledzenia

Gdy użytkownicy końcowi przesyłają w aplikacji opinie typu „kciuk w górę” lub „kciuk w dół”, możesz rejestrować te opinie, aby były widoczne jako adnotacje w odpowiednim śladzie. To podejście wykorzystuje zdarzenie OpenTelemetry gen_ai.evaluation.result, a informacja zwrotna jest automatycznie powiązana z pierwotnym śladem.

Schemat atrybutu adnotacji

Użyj następujących atrybutów podczas dodawania adnotacji „kciuk w górę” lub „kciuk w dół”:

[No changes needed]) Value Description
gen_ai.evaluation.name task_completion Nazwa metryki oceny
gen_ai.evaluation.score.value 1.0 (kciuki w górę) lub 0.0 (kciuk w dół) Wynik liczbowy
gen_ai.evaluation.score.label "pass" lub "fail" Etykieta kategorii
gen_ai.evaluation.explanation Opcjonalny komentarz w dowolnej formie Wyjaśnienie recenzenta
gen_ai.response.id Na przykład "chatcmpl-123" Identyfikator odpowiedzi AI używany do powiązania adnotacji ze śledzoną odpowiedzią
microsoft.gen_ai.human_evaluation.source "end_user" lub "builder" Typ dostawcy opinii
microsoft.gen_ai.evaluation.actor.type "human" Wskazuje, że adnotacja została przesłana przez ludzkiego recenzenta, odróżniając ją od zautomatyzowanych ocen.
operation_Id trace_Id Łączy adnotację z oryginalnym żądaniem śledzenia w usłudze Application Insights
operation_ParentId span_Id Zawiera identyfikator konkretnego spanu w adnotowanym śledzeniu
gen_ai.agent.id Ciąg identyfikatora zasobu agenta Unikatowy identyfikator agenta, który wygenerował odpowiedź z adnotacjami
gen_ai.agent.name Ciąg znaków nazwy wyświetlanej agenta Wyświetlana nazwa agenta, który wygenerował odpowiedź będącą przedmiotem adnotacji
gen_ai.agent.version Ciąg wersji 1, 2 lub 3 Znajdująca się w elemencie internal_properties wersja agenta z momentu wygenerowania odpowiedzi z adnotacjami

Musisz wyemitować zdarzenie oceny w tym samym kontekście śledzenia (przy użyciu tego samego identyfikatora śledzenia i identyfikatora spanu) co interakcję agenta, którą ono adnotuje. Ta korelacja gwarantuje, że adnotacja jest wyświetlana na prawidłowym śladzie w portalu.

Aby zapoznać się z kompletnym przykładem gotowym do uruchomienia, zobacz sample_human_evaluations.py.

Wyświetlanie adnotacji na stronie śledzenia

Po dodaniu adnotacji (z portalu lub programowo) są one wyświetlane na stronie szczegółów śledzenia.

  1. Otwórz projekt Foundry i przejdź do pozycji Śledzenie.
  2. Wybierz ślad zawierający adnotacje.
  3. Na stronie szczegółów śladu obok fragmentów objętych adnotacjami pojawiają się ikony adnotacji. Ikona kciuka w górę wskazuje pozytywną opinię, a ikona kciuka w dół wskazuje negatywną opinię.
  4. Umieść kursor na adnotacji, aby wyświetlić metadane, w tym źródło (builder lub end_user), nazwę oceny i znacznik czasu.

W widoku listy śladów adnotacje są wyświetlane w formie kompaktowej: tylko najnowsza adnotacja jest pokazywana bezpośrednio w wierszu, a gdy dla śladu istnieje wiele adnotacji, wskaźnik „+X więcej” informuje o dostępności dodatkowych adnotacji. Wybierz ślad, aby wyświetlić wszystkie adnotacje.

Filtruj ślady według adnotacji

Listę śledzenia można filtrować, wykonując następujące czynności:

  • Typ oceny (gen_ai.evaluation.name): wartość to "task_completion".
  • Wartość oceny lub etykieta (gen_ai.evaluation.score.value, gen_ai.evaluation.score.label): na przykład pokaż tylko ślady z oceną „kciuk w dół”.
  • Źródło (microsoft.gen_ai.human_evaluation.source): pokaż tylko adnotacje konstruktora lub tylko opinie użytkowników końcowych.

Te wymiary filtru są wyświetlane obok istniejących filtrów śledzenia (zakres czasu, agent, stan, model).

Adnotacje zapytań w usłudze Application Insights

Wszystkie adnotacje są publikowane w Azure Monitor / Application Insights i dołączone do oryginalnego śladu. Możesz wykonywać zapytania dotyczące adnotacji za pomocą języka Kusto Query Language (KQL), aby analizować wzorce informacji zwrotnych, tworzyć pulpity nawigacyjne lub konfigurować alerty.

Podsumowanie opinii według źródła i dnia

customEvents
| where name == "gen_ai.evaluation.result"
| extend
    eval_name = tostring(customDimensions["task_completion"]),
    score = todouble(customDimensions["gen_ai.evaluation.score.value"]),
    label = tostring(customDimensions["gen_ai.evaluation.score.label"]),
    eval_source = tostring(customDimensions["microsoft.gen_ai.human_evaluation.source"]),
    trace_id = tostring(customDimensions["trace_id"])
| where eval_source in ("builder", "end_user")
| summarize
    thumbs_up = countif(score == 1.0),
    thumbs_down = countif(score == 0.0),
    total = count()
  by eval_source, bin(timestamp, 1d)
| order by timestamp desc

Znajdź ślady z negatywnymi opiniami

customEvents
| where name == "gen_ai.evaluation.result"
| extend
    eval_name = tostring(customDimensions["task_completion"]),
    score = todouble(customDimensions["gen_ai.evaluation.score.value"]),
    eval_source = tostring(customDimensions["microsoft.gen_ai.human_evaluation.source"]),
    explanation = tostring(customDimensions["gen_ai.evaluation.explanation"]),
    trace_id = tostring(customDimensions["trace_id"])
| where score == 0.0
| project timestamp, trace_id, eval_name, eval_source, explanation
| order by timestamp desc

Rozwiązywanie problemów z zapisem adnotacji

Objaw Sprawdź
Możesz wyświetlić ślad, ale zapisywanie adnotacji buildera kończy się niepowodzeniem z powodu błędu autoryzacji Traktuj zapisywanie jako oddzielną operację zapisu. Potwierdź połączony zasób usługi Application Insights, tożsamość używaną do zapisu i tryb uwierzytelniania połączenia. Nie dodawaj innej roli Czytelnik jako poprawki ogólnej.
Adnotacja programowa zwraca 401 lub 403 Upewnij się, że aplikacja wysyła dane telemetryczne do oczekiwanego zasobu usługi Application Insights. W przypadku pozyskiwania uwierzytelnianego przez Microsoft Entra przypisz Monitoring Metrics Publisher tożsamości emitującej telemetrię w tym zasobie.
Aplikacja zgłasza sukces, ale adnotacja nie jest wyświetlana Upewnij się, że zdarzenie oceny używa oryginalnego kontekstu śledzenia i spanu, że zostało wysłane do tego samego zasobu usługi Application Insights co ślad i że pozyskiwanie danych zostało ukończone.
Adnotacja pojawia się na nieprawidłowym śladzie Przed wyemitowaniem zdarzenia sprawdź operation_Id, operation_ParentId i gen_ai.response.id.

Treści powiązane

  • Ostatnia aktualizacja o