Anotasi jejak dengan masukan manusia (pratinjau)

Important

Item yang ditandai sebagai pratinjau dalam artikel ini saat ini masih dalam pratinjau. Pratinjau ini disediakan tanpa perjanjian tingkat layanan, dan Microsoft tidak merekomendasikannya untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk informasi lebih lanjut, lihat Supplemental Terms of Use for Microsoft Azure Previews.

Tambahkan anotasi jempol naik atau jempol turun pada trace di Microsoft Foundry untuk mengumpulkan sinyal kualitas dari manusia pada setiap interaksi agen. Anotasi pelacakan memungkinkan Anda menandai apakah respons agen berguna atau tidak membantu, dan anotasi tersebut muncul sebaris di halaman detail pelacakan sehingga Anda dapat dengan cepat mengidentifikasi pola dalam perilaku agen.

Anotasi jejak mendukung dua alur kerja:

Anotasi pembangun: Pembangun dan pakar domain memberi anotasi pada jejak di portal Foundry saat meninjau interaksi agen. Anotasi ini secara otomatis ditandai dengan sumber builder.
Umpan balik pengguna akhir: Catat anotasi secara terprogram dari aplikasi Anda saat pengguna akhir memberikan umpan balik jempol ke atas atau jempol ke bawah. Anotasi ini memiliki sumber end_user dan ditampilkan di halaman trace bersama anotasi builder. Untuk detail tentang pengelogan umpan balik pengguna akhir, lihat Mencatat umpan balik pengguna akhir.

Semua anotasi ditambahkan ke pelacakan—menambahkan anotasi penyusun tidak pernah menimpa atau mengganti umpan balik pengguna akhir yang ada, dan sebaliknya. Setiap anotasi membawa atribut sumber sehingga sinyal tetap dapat dikueri dan dapat difilter secara independen.

Prerequisites

Proyek Foundry dengan sumber daya Application Insights yang terhubung. Lihat Menyiapkan pelacakan.
Instrumentasi OpenTelemetry dikonfigurasi dalam aplikasi Anda. Lihat Siapkan pelacakan di Microsoft Foundry untuk instruksi penyiapan.
Untuk anotasi terprogram: paket azure-ai-projects dan azure-monitor-opentelemetry telah terinstal.
```
pip install "azure-ai-projects>=2.0.0" azure-monitor-opentelemetry python-dotenv
```
Untuk anotasi terprogram yang menggunakan penyerapan Application Insights yang diautentikasi Microsoft Entra: identitas yang memancarkan telemetri memiliki peran Monitoring Metrics Publisher pada sumber daya Application Insights yang terhubung. Untuk penyiapan dan panduan khusus identitas, lihat Mengonfigurasi autentikasi Microsoft Entra untuk penyerapan jejak.

Templat penilaian default

Setiap proyek Foundry sudah dilengkapi dengan templat penilaian jempol naik/turun bawaan yang bisa langsung digunakan tanpa pengaturan tambahan. Anda dapat mulai menganotasi jejak pada hari pertama. Templat default menggunakan penilaian lulus/gagal biner:

Jempol ke atas = skor 1.0, label pass
Tidak suka = score 0.0, label fail

Setiap templat penilaian mengharuskan gen_ai.evaluation.name atribut memiliki nilai task_completion sehingga setiap anotasi dapat diatribusikan ke dimensi evaluasi tertentu. task_completion mendukung jempol ke atas dan ke bawah.

Membuat anotasi jejak di portal Foundry

Tambahkan anotasi langsung dari halaman detail pelacakan untuk merekam penilaian respons agen Anda.

Buka proyek Foundry Anda dan navigasi ke Pelacakan di navigasi kiri.
Pilih jejak untuk membuka tampilan detail jejak.
Pada halaman detail pelacakan, pilih tombol Anotasi di sudut kanan atas.
Pilih Jempol ke atas atau Jempol ke bawah untuk mengirimkan skor Anda. Secara opsional tambahkan penjelasan teks bebas.
Anotasi tersebut langsung tersimpan dan muncul pada rekaman penelusuran.

Note

Melihat jejak dan menyimpan anotasi adalah operasi otorisasi terpisah. Jika trace terlihat tetapi anotasi tidak dapat disimpan, verifikasi tujuan anotasi, identitas penulisan yang digunakan sebenarnya, dan jalur autentikasi. Peran trace-reader lain tidak memberikan akses telemetry-write.

Anotasi yang Anda tambahkan dari portal secara otomatis ditandai dengan:

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

Pengeditan skor

Setiap pengguna dapat membuat anotasi beberapa kali:

Beberapa pengguna masing-masing dapat memiliki anotasi mereka sendiri dengan jenis yang sama pada jejak yang sama.
Anotasi sebelumnya tidak dihapus di Application Insights. Anotasi baru ditambahkan, dan portal menampilkan semua anotasi di bagian Riwayat anotasi dari panel anotasi.

Mencatat umpan balik pengguna akhir sebagai anotasi pelacakan

Saat pengguna akhir memberikan umpan balik jempol ke atas atau jempol ke bawah di aplikasi Anda, Anda dapat mencatat umpan balik tersebut sehingga muncul sebagai anotasi pada jejak yang sesuai. Pendekatan ini menggunakan peristiwa gen_ai.evaluation.result OpenTelemetry, dengan umpan balik yang secara otomatis dikaitkan dengan jejak asalnya.

Skema atribut anotasi

Gunakan atribut berikut saat Anda memancarkan anotasi jempol ke atas atau jempol ke bawah:

Attribute	Nilai	Deskripsi
`gen_ai.evaluation.name`	`task_completion`	Nama metrik evaluasi
`gen_ai.evaluation.score.value`	`1.0` (jempol ke atas) atau `0.0` (jempol ke bawah)	Skor numerik
`gen_ai.evaluation.score.label`	`"pass"` atau `"fail"`	Label kategorikal
`gen_ai.evaluation.explanation`	Komentar teks bebas opsional	Penjelasan peninjau
`gen_ai.response.id`	Misalnya: `"chatcmpl-123"`	ID respons AI yang digunakan untuk menghubungkan anotasi dengan respons yang ditelusuri
`microsoft.gen_ai.human_evaluation.source`	`"end_user"` atau `"builder"`	Jenis penyedia umpan balik
`microsoft.gen_ai.evaluation.actor.type`	`"human"`	Menunjukkan anotasi dikirimkan oleh peninjau manusia, membedakannya dari evaluasi otomatis
`operation_Id`	`trace_Id`	Menautkan anotasi ke permintaan pelacakan asli di Application Insights
`operation_ParentId`	`span_Id`	Termasuk ID rentang rentang tertentu dalam jejak yang diannotasi
`gen_ai.agent.id`	String pengidentifikasi sumber daya agen	Pengidentifikasi unik agen yang menghasilkan respons yang dianotasi
`gen_ai.agent.name`	String nama tampilan agen	Nama tampilan agen yang menghasilkan respons yang sedang dianotasi
`gen_ai.agent.version`	Teks versi `1`, `2`, atau `3`	Di dalam `internal_properties`, versi agen pada saat respons yang dianotasi dihasilkan

Anda harus memancarkan peristiwa evaluasi dalam konteks pelacakan yang sama (menggunakan ID pelacakan dan ID rentang yang sama) seperti interaksi agen yang dianotasinya. Korelasi ini memastikan anotasi muncul pada jejak yang benar di portal.

Untuk contoh lengkap yang dapat dijalankan, lihat sample_human_evaluations.py.

Menampilkan anotasi pada halaman pelacakan

Setelah Anda menambahkan anotasi (dari portal atau secara terprogram), anotasi tersebut muncul di halaman detail pelacakan.

Buka proyek Foundry Anda dan buka Pelacakan.
Pilih jejak yang memiliki anotasi.
Pada halaman detail trace, ikon anotasi muncul di samping span yang dianotasi. Ikon jempol ke atas menunjukkan umpan balik positif dan ikon jempol ke bawah menunjukkan umpan balik negatif.
Arahkan mouse ke atas anotasi untuk melihat metadata, termasuk sumber (builder atau end_user), nama evaluasi, dan tanda waktu.

Dalam tampilan daftar jejak, anotasi ditampilkan dalam format ringkas: hanya anotasi terbaru yang ditampilkan sebaris, dan ketika ada beberapa anotasi pada sebuah jejak, indikator "+X more" menandakan bahwa ada anotasi tambahan yang tersedia. Pilih jejak untuk melihat semua anotasi.

Memfilter jejak menurut anotasi

Anda dapat memfilter daftar jejak dengan:

Jenis evaluasi (gen_ai.evaluation.name): nilainya adalah "task_completion".
Nilai atau label skor (gen_ai.evaluation.score.value, gen_ai.evaluation.score.label): misalnya, hanya tampilkan jejak dengan peringkat jempol ke bawah.
Sumber (microsoft.gen_ai.human_evaluation.source): hanya menampilkan anotasi penyusun atau hanya umpan balik pengguna akhir.

Dimensi filter ini muncul bersama filter pelacakan yang ada (rentang waktu, agen, status, model).

Anotasi kueri di Application Insights

Semua anotasi dipublikasikan ke Azure Monitor / Application Insights dan dilampirkan ke pelacakan asli. Anda dapat mengkueri anotasi dengan menggunakan Kusto Query Language (KQL) untuk menganalisis pola umpan balik, membangun dasbor, atau menyiapkan pemberitahuan.

Meringkas umpan balik menurut sumber dan hari

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

Menemukan jejak dengan umpan balik negatif

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

Mengatasi masalah penulisan anotasi

Gejala	Periksa
Anda dapat melihat trace, tetapi menyimpan builder annotation gagal dengan kesalahan otorisasi	Perlakukan penyimpanan sebagai operasi tulis terpisah. Konfirmasikan sumber daya Application Insights yang terhubung, identitas yang digunakan untuk operasi penulisan, dan mode autentikasi koneksi. Jangan tambahkan role Reader lain sebagai perbaikan umum.
Anotasi terprogram mengembalikan `401` atau `403`	Konfirmasikan bahwa aplikasi mengirim telemetri ke sumber daya Application Insights yang diharapkan. Untuk ingestion yang diautentikasi Microsoft Entra, berikan Monitoring Metrics Publisher ke identitas pemancar telemetri pada sumber daya tersebut.
Aplikasi melaporkan keberhasilan, tetapi anotasi tidak muncul	Konfirmasikan bahwa peristiwa evaluasi menggunakan konteks pelacakan dan span asli, bahwa peristiwa tersebut dikirim ke sumber daya Application Insights yang sama dengan jejak, dan ingestion tersebut telah selesai.
Anotasi muncul pada jejak yang salah	Verifikasi `operation_Id`, `operation_ParentId`, dan `gen_ai.response.id` sebelum memicu event.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-10-08