İnsan geri bildirimiyle izlemelere not ekleme (önizleme)

Important

Bu makalede önizleme olarak işaretlenmiş öğeler şu anda önizleme aşamasındadır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve Microsoft üretim iş yükleri için bunu önermez. Bazı özellikler desteklenmeyebilir veya kısıtlı özelliklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.

Tek tek aracı etkileşimlerinde insan kalitesi sinyallerini yakalamak için Microsoft Foundry'deki izlemelere başparmak yukarı veya başparmak aşağı ek açıklamaları ekleyin. İz açıklamaları, bir ajan yanıtının yararlı mı yoksa yararsız mı olduğunu işaretlemenize olanak tanır ve ajan davranışındaki kalıpları hızlıca belirleyebilmeniz için iz ayrıntı sayfasında doğrudan görünür.

İzleme ek açıklamaları iki iş akışını destekler:

Oluşturucu ek açıklamaları: Oluşturucular ve etki alanı uzmanları, aracı etkileşimlerini gözden geçirirken Foundry portalından izlemelere ek açıklama ekler. Bu açıklamalar, kaynak olarak builder ile otomatik olarak etiketlenir.
Son kullanıcı geri bildirimi: Son kullanıcılar başparmak yukarı veya başparmak aşağı geri bildirimi verdiğinde, açıklamaları uygulamanızdan programlı olarak günlüğe kaydedin. Bu ek açıklamaların kaynağı end_user olarak belirtilir ve izleme sayfasında oluşturucu ek açıklamalarının yanında görünür. Son kullanıcı geri bildiriminin günlüğe kaydedilmesiyle ilgili ayrıntılar için bkz. Son kullanıcı geri bildirimini günlüğe kaydetme.

Tüm ek açıklamalar izleme kaydına eklenir; bir geliştirici ek açıklaması eklemek, mevcut son kullanıcı geri bildirimini hiçbir zaman üzerine yazmaz veya onun yerini almaz; tersi de aynı şekilde geçerlidir. Her ek açıklama bir kaynak özniteliği taşır, böylece sinyaller bağımsız olarak sorgulanabilir ve filtrelenebilir kalır.

Prerequisites

Application Insights kaynağının bağlı olduğu bir Foundry projesi. Bkz. İzlemeyi ayarlama.
Uygulamanızda yapılandırılmış OpenTelemetry enstrümantasyonu. Kurulum yönergeleri için bkz. Microsoft Foundry içinde izlemeyi ayarlama.
Programatik ek açıklamalar için: azure-ai-projects ve azure-monitor-opentelemetry paketlerinin yüklü olması.
```
pip install "azure-ai-projects>=2.0.0" azure-monitor-opentelemetry python-dotenv
```
Microsoft Entra kimliği doğrulanmış Application Insights alımını kullanan programlı ek açıklamalar için: Telemetriyi yayan kimlik, bağlı Application Insights kaynağında Monitoring Metrics Publisher rolüne sahiptir. Kurulum ve kimliğe özgü yönergeler için bkz. İzleme alımı için Microsoft Entra kimlik doğrulamasını yapılandırma.

Varsayılan puanlama şablonu

Her Foundry projesi, ek bir kurulum gerektirmeden hemen kullanıma hazır olan varsayılan bir başparmak yukarı/aşağı puanlama şablonuyla birlikte gelir. İzlemelere açıklama eklemeye ilk gün başlayabilirsiniz. Varsayılan şablon ikili geçiş/başarısız puanlama kullanır:

Başparmak yukarı = puan 1.0, etiket pass
Başparmak aşağı = puan 0.0, etiket fail

Her puanlama şablonu, gen_ai.evaluation.name özniteliğinin değerinin task_completion olmasını gerektirir; böylece her ek açıklama belirli bir değerlendirme boyutuna atfedilebilir. task_completion başparmakları yukarı ve aşağı destekler.

Foundry portalında izlere açıklama ekleyin

Temsilci yanıtlarına ilişkin değerlendirmenizi kayda geçirmek için ek açıklamaları doğrudan iz ayrıntıları sayfasından ekleyin.

Foundry projenizi açın ve sol gezinti bölmesinde İzleme'ye gidin.
İz ayrıntıları görünümünü açmak için bir iz seçin.
İzleme ayrıntıları sayfasında sağ üst köşedeki Not Ekle düğmesini seçin.
Puanınızı göndermek için Başparmak yukarı veya Başparmak aşağı seçeneğini belirleyin. İsteğe bağlı olarak serbest metin açıklaması ekleyin.
Not anında kaydedilir ve iz üzerinde görünür.

Note

İzlemeyi görüntüleme ve ek açıklama kaydetme ayrı yetkilendirme işlemleridir. İzleme görünür durumdaysa ancak ek açıklama kaydedilemiyorsa ek açıklama hedefini, gerçek yazma kimliğini ve kimlik doğrulama yolunu doğrulayın. Başka bir iz okuyucu rolü telemetri-yazma erişimi vermez.

Portaldan eklediğiniz ek açıklamalar otomatik olarak şu şekilde etiketlenir:

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

Puan düzenleme

Her kullanıcı birden çok kez açıklama ekleyebilir:

Birden çok kullanıcının her biri aynı izlemede aynı türde kendi ek açıklamalarına sahip olabilir.
Önceki ek açıklamalar Application Insights'ta silinmez. Yeni ek açıklamalar eklenir ve portal, ek açıklama panelinin Ek Açıklama geçmişi bölümünde tüm ek açıklamaları görüntüler.

Son kullanıcı geri bildirimlerini izleme notları olarak günlüğe kaydet

Son kullanıcılar uygulamanızda başparmak yukarı veya başparmak aşağı geri bildirimi verdiğinde, bu geri bildirimi ilgili izde ek açıklamalar olarak görünmesi için günlüğe kaydedebilirsiniz. Bu yaklaşımda OpenTelemetry olayı kullanılır gen_ai.evaluation.result ve geri bildirim, kaynak izlemeyle otomatik olarak ilişkilendirildi.

Not öznitelik şeması

Başparmak yukarı ya da başparmak aşağı notu oluşturduğunuzda aşağıdaki öznitelikleri kullanın:

Attribute	Değer	Description
`gen_ai.evaluation.name`	`task_completion`	Değerlendirme ölçüm adı
`gen_ai.evaluation.score.value`	`1.0` (başparmak yukarı) veya `0.0` (başparmak aşağı)	Sayısal puan
`gen_ai.evaluation.score.label`	`"pass"` veya `"fail"`	Kategorik etiket
`gen_ai.evaluation.explanation`	İsteğe bağlı serbest metin açıklaması	Gözden geçiren açıklaması
`gen_ai.response.id`	Örneğin, `"chatcmpl-123"`	Ek açıklamayı izlenen yanıtla ilişkilendirmek için kullanılan yapay zeka yanıt kimliği
`microsoft.gen_ai.human_evaluation.source`	`"end_user"` veya `"builder"`	Geri bildirim sağlayıcı türü
`microsoft.gen_ai.evaluation.actor.type`	`"human"`	Ek açıklamanın bir gözden geçiren tarafından gönderildiğini gösterir ve bunu otomatik değerlendirmelerden ayırır
`operation_Id`	`trace_Id`	Ek açıklamayı Application Insights'taki özgün izleme isteğine bağlar
`operation_ParentId`	`span_Id`	Açıklama yapılan iz içindeki belirli span’ın span kimliğini içerir
`gen_ai.agent.id`	Ajan kaynak tanımlayıcı dizesi	Ek açıklama yapılan yanıtı üreten ajanın benzersiz tanımlayıcısı
`gen_ai.agent.name`	Temsilci görünen ad dizesi	Ek açıklama yapılan yanıtı üreten ajanın görünen adı
`gen_ai.agent.version`	Sürüm dizesi `1`, `2`veya `3`	Ek açıklamalı yanıtın oluşturulduğu sırada `internal_properties` içinde bulunan aracının sürümü

Değerlendirme olayını, ek açıklama getirdiği ajan etkileşimiyle aynı iz bağlamı içinde (aynı iz kimliği ve span kimliğini kullanarak) göndermelisiniz. Bu ilişkilendirme, ek açıklamanın portalda doğru iz üzerinde görünmesini sağlar.

Tam bir çalıştırılabilir örnek için bkz. sample_human_evaluations.py.

İzleme sayfasında ek açıklamaları görüntüleme

Ek açıklamalar ekledikten sonra (portaldan veya program aracılığıyla), izleme ayrıntısı sayfasında görünürler.

Foundry projenizi açın ve İzleme'ye gidin.
Açıklamaları olan bir iz seçin.
İzleme ayrıntısı sayfasında, ek açıklama simgeleri ek açıklama eklenmiş aralıkların yanında görünür. Başparmak yukarı simgesi pozitif geri bildirimi, başparmak aşağı simgesi ise negatif geri bildirimi gösterir.
Kaynak (builder veya end_user), değerlendirme adı ve zaman damgası gibi meta verileri görmek için ek açıklamanın üzerine gelin.

İzleme listesi görünümünde, ek açıklamalar sıkıştırılmış bir işlemle görüntülenir: yalnızca en son ek açıklama satır içinde gösterilir ve bir izlemede birden çok ek açıklama bulunduğunda bir "+X daha fazla" göstergesi ek ek açıklamaların kullanılabilir olduğunu gösterir. Tüm açıklamaları görmek için izi seçin.

İzleri açıklamaya göre filtreleyin

İzleme listesini şu şekilde filtreleyebilirsiniz:

Değerlendirme türü (gen_ai.evaluation.name): değeridir "task_completion".
Puan değeri veya etiketi (gen_ai.evaluation.score.value, gen_ai.evaluation.score.label): örneğin, yalnızca olumsuz derecelendirmesi olan izleri göster.
Kaynak (microsoft.gen_ai.human_evaluation.source): Yalnızca oluşturucu ek açıklamalarını veya yalnızca son kullanıcı geri bildirimlerini gösterir.

Bu filtre boyutları mevcut izleme filtrelerinin (zaman aralığı, aracı, durum, model) yanında görünür.

Application Insights'ta sorgu ek açıklamaları

Tüm açıklamalar Azure İzleyici / Application Insights'ta yayımlanır ve orijinal izleme kaydına iliştirilir. Geri bildirim desenlerini analiz etmek, panolar oluşturmak veya uyarıları ayarlamak için Kusto Sorgu Dili'ni (KQL) kullanarak ek açıklamaları sorgulayabilirsiniz.

Kaynağa ve güne göre geri bildirimi özetleme

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

Olumsuz geri bildirim içeren izlemeleri bulun

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

Ek açıklama yazma sorunlarını giderme

Belirti	Kontrol
Bir izi görüntüleyebilirsiniz, ancak oluşturucu ek açıklamasını kaydetme işlemi yetkilendirme hatasıyla başarısız oluyor	Kaydetme işlemini ayrı bir yazma işlemi olarak değerlendirin. Bağlı Application Insights kaynağını, yazma için kullanılan kimliği ve bağlantı kimlik doğrulama modunu onaylayın. Genel bir düzeltme olarak başka bir Okuyucu rolü eklemeyin.
Programatik bir ek açıklama `401` veya `403` döndürür	Uygulamanın beklenen Application Insights kaynağına telemetri gönderdiğini onaylayın. Microsoft Entra kimliği doğrulanmış alım için, bu kaynakta telemetri yayan kimliğe Monitoring Metrics Publisher verin.
Uygulama başarı bildiriyor, ancak ek açıklama görüntülenmez	Değerlendirme olayının özgün izleme ve span bağlamını kullandığını, izlemeyle aynı Application Insights kaynağına gönderildiğini ve alımın tamamlandığını onaylayın.
Ek açıklama yanlış izde görüntüleniyor	Olayı tetiklemeden önce `operation_ParentId`, `gen_ai.response.id` ve `operation_Id` öğelerini doğrulayın.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-10-08