Copilot Aracısı Kit'te Aracı Debugger ile Aracı Hataları Temizleme Konuşmalarını Sorun Giderme

Aracı Debugger, kaydedilmiş bir konuşmayı yüklemenize ve bir aracının verdiği her kararı incelemenize yardımcı olan bir tanı aracıdır. Her konuşma turunda, yürütme yolunu, adım zamanlamasını, belirteç kullanımını, bilgi kaynaklarını, adım argümanlarını ve orkestratörün gerekçesini inceleyebilirsiniz.

Aracı Debugger iki veri kaynağını destekler:

  • Konuşma Transkripti (Dataverse): Copilot Studio'da bir konuşma çalıştığında, platform bir etkinlik kaydını Dataverse'de Konuşma Transkripti olarak kaydeder. Aracı Debugger bu kayıtları doğrudan sorgular, böylece transkript verisi olan yayımlanmış herhangi bir aracı hemen erişilebilir olur.
  • Copilot Studio anlık görüntüsü (ZIP): Copilot Studio test paneli, mevcut test konuşmasını ZIP dosyası olarak dışa aktaran İndir snapshot seçeneği içerir. Bu dosyayı Aracı Debugger'a yüklemek, Dataverse bağlantısı olmadan tam analiz görünümünü sunar. Bu yöntem, ön üretim konuşmalarını hata ayıklamak, çevrimdışı sorunları yeniden üretmek veya başarısız bir oturumu bir meslektaşınızla paylaşmak için faydalıdır.

Her iki veri kaynağı da aynı analiz arayüzünü besler. Paneller, adım detayları ve görselleştirmeler, veri nasıl yüklenirse yüklense de aynıdır.

Ön koşullar

Aracı Debugger'ı kullanmak için aşağıdaki ön koşulların yerine getirildiğinden emin olun:

  • Aracı, Aracı Envanteri'nde bulunuyor ve en az bir konuşma transkripti kaydediliyor. Bu durumu, Aracı Envanteri listesi görünümünü açarak, aracıyı seçerek ve ek alanları genişletmek için Daha fazlasını göster seçeneğini seçerek doğrulayabilirsiniz. Transkript Mevcut mu alanı Evet olarak ayarlanmalıdır. Aracı Envanteri senkronizasyonu, Dataverse'de aracı için en az bir konuşma transkripti varsa bu alanı otomatik olarak ayarlar.
  • Giriş yapan kullanıcı, kit ortamında CSK - Yönetici veya Sistem Yöneticisi güvenlik rolüne sahiptir.
  • Oturum açmış kullanıcının hedef ortamdaki conversationtranscripts, bot ve botcomponents tablolarında Okuma erişimi vardır.

Not

Hata ayıkladığınız aracı, kitin kurulduğu yerden farklı bir ortamdaysa, aynı okuma izinleriyle uzak ortamda Dataverse bağlantısını doğrulamanız gerekir.

Bir konuşma seçin

Aracı Debugger'ı açtığınızda, filtre çubuğu analiz edilecek bir konuşmayı bulmak için gereken kontrolleri sağlar.

Filtre Açıklama
Ortam Aracı Inventory'deki farklı ortam isimlerinden oluşmuştur. Bir ortam seçmek, Aracı açılır menüsünü o ortamda kayıtlı aracılara daraltıyor.
Aracı Seçilmiş ortamda Transcript Kullanılabilir alanı Evet olarak ayarlanmış aracıları gösterir. Bir aracı seçildiğinde, seçilen zaman aralığındaki en son 50 konuşmayı Konuşma Kimliği açılır menüsüne yükler.
Konuşma kimliği Seçilen aracı için ayarlanmış zaman aralığındaki en son 50 benzersiz konuşmayı gösterir. Kutuya girdiğinizde, o aracının tüm transkriptlerinde (100.000 kayıta kadar) tam bir arama başlatılır, böylece zaman aralığı ne olursa olsun eski veya spesifik konuşmaları bulabilirsiniz.
Zaman aralığı Konuşma Kimliği listesini belirli bir pencereye daraltır. Son 30 dakika, Son saat, Son 4 saat, Son 24 saat, Son 7 gün veya Özel aralık seçeneklerinden birini seçin. Özel aralık seçtiğinizde, tarih ve saat seçiciler başlangıç ve bitiş zaman damgası belirler.
Sadece hata konuşmaları Conversation ID açılır menüsünü en az bir başarısız adım veya sistem hatası içeren konuşmalara filtreler. Bu seçeneği olayları triajlarken veya bilinen güvenilirlik sorunları olan aracıları incelerken kullanın.

Bir Konuşma Kimliği seçtikten sonra Analiz Erişebilir hale gelir. Analiz görünümünü açmak için onu seçin.

Not

Doğrudan bir Konuşma Kimliği yazmak, aktif zaman aralığı ne olursa olsun tüm transkriptleri her zaman arar. Hata konuşmaları yalnızca istemci tarafındaki transkript içeriğini filtreler ve standart sorgudan daha uzun sürer. Özellikle hatalara göre filtrelemeniz gerekmediği sürece kapatın.

Copilot Studio'dan bir anlık görüntü yükleyin

Upload Snapshot sekmesi, Dataverse erişimi gerektirmeyen alternatif bir giriş noktası sunar. Açılır menülerden canlı bir konuşma seçmek yerine, Copilot Studio test panelinden indirilmiş bir snapshot ZIP dosyası yüklüyorsunuz.

Copilot Studio'dan bir anlık görüntü indirmek için:

  1. Aracınızı Copilot Studio'da açın ve Aracınızı test edin paneline gidin.
  2. Bir konuşmayı başlatın veya gözden geçirin.
  3. Test paneli araç çubuğunda Anlık görüntüyü indir seçeneğini seçin.

Copilot Studio şunları içeren bir .zip dosyası indiriyor:

  • dialog.json: Konuşma için tüm Bot Framework etkinlikleri (zorunlu).
  • botContent.yml: Aracının tam bileşen ve akış tanımları, adım isimlerini çözmek için kullanılır (isteğe bağlı; yoksa, ham şema adları gösterilir).

Aracı Debugger'a bir anlık görüntü yüklemek için:

  1. Aracı Debugger başlığındaki Upload Snapshot sekmesine geçin.
  2. .zip dosyasını sürükleyip bırakma alanına bırakın veya dosyayı tarayarak bulun.

Aracı Debugger ZIP'i doğrular, dosyaları çıkarır ve analiz görünümünü açar. Hiçbir ortam, aracı veya konuşma seçimi gerekmez. Tüm genel bilgi metrikleri yüklenen dosyadan türetilir.

Şularda Upload Snapshot modunu kullanın:

  • Aracı yayınlanmadan önce test panelinde gerçekleşen bir konuşmayı hata ayıklayın.
  • Doğrulama sağlayamayacağınız bir ortamdan bir konuşmayı analiz edin.
  • Sorunları çevrimdışı olarak yeniden üretebilir veya başarısız bir oturumu bir meslektaşınızla paylaşarak Dataverse'e erişim izni vermeyebilirsiniz.
  • Yerel bir geliştirme ortamında aracı davranışını doğrulamak.

Bir konuşmayı analiz edin

Analiz görünümü, Analiz Et'i seçtikten veya bir anlık görüntü yükledikten sonra açılır. Üstte Genel bilgiler özet satırı, dört panelden oluşan (Yürütme yolu, Performans zaman çizelgesi, Aracı ayrıntıları ve Öneriler) daraltılabilir bir analiz bölümü ve Konuşma önizlemesi ile Hata ayıklama bilgileri panelini gösteren iki panelli bir düzen içerir.

Genel bilgiler

Genel bilgi satırı, konuşma için özet metrik taşlarını gösterir.

Alan Açıklama
Oturumlar Konuşma oturumlarının sayısı. Birden fazla oturum, bir kullanıcı hareketsizlikten sonra aynı konuşmaya geri döndüğünde gerçekleşir.
Dönüşler Konuşmadaki kullanıcı mesaj sayısı.
Sonuç Platform tarafından bildirilen oturum sonuçları, örneğin Çözüldü, Yükseltildi, Terk edildi veya SystemError.
Süre İlk hareketten son harekete kadar toplam konuşma süresi.
Başlangıç Saati Konuşma başladığında (yerel saatle).
Kanal Webchat veya msteams'ler gibi iletişim kanalları kullanılır. Mevcut olduğunda gösterilir.
Model Bu konuşma için aracının düzenleyicinin kullandığı AI modeli.

Canlı bir aracı yüklendiğinde, genel bilgi başlığında bir Açık aracı bağlantısı görünür. Bağlantı, Copilot Studio'da aracının yapılandırma sayfasını açar.

Uygulama yolu

Yürütme yolu, tüm konuşma turlarında tam yürütme sırasını yönlendirilmiş bir akış diyagramı olarak gösterir. Adımlar uygulama sırasına göre soldan sağa akıyor. Kesik dikey çizgiler dönüş sınırlarını işaretler ve her kullanıcı mesajı yeni bir bölüm başlatır. Tur etiketleri her bölümün üstünde belirir. Bir tur etiketi seçtiğinizde, Konuşma önizlemesi o mesaja kaydırılıyor.

Her adım türü farklı bir renk kullanır ve diyagramın altındaki bir efsane, renkleri Konu, Bilgi, Araç, Bağlayıcı, Akış, Kod, MCP ve Bağlı Aracı gibi adım kategorilerine eşler. Her düğüm adım adını ve uygulama süresini gösterir. Başarısız adımlar kırmızı renkle vurgulanmıştır. Bağlantılı aracılar, yürütdükleri alt adımları gruplayan konteyner kutuları olarak görünür.

Performans zaman çizelgesi

Performans zaman çizelgesi, konuşma turuna göre gruplanmış bir şelale çizelgesini gösterir. Step barları, göreceli zamanlamayı görün kılmak için turun toplam süresine göre ölçeklendirilir. Renk kodlama, uygulama yolu efsanesiyle eşleşir ve başarısız adımlar kırmızı renkte görünür.

Panel aşağıdaki özellikleri içermektedir:

  • Genişlet/Kısaltma Tümü tuşları tüm tur bölümlerini aynı anda aç. Her dönüş bölümü ayrıca ayrı ayrı katlanabilir.
  • Tur başına yapılan istatistikler adım sayı, en yavaş adım adı ve süresi ile başarısızlık sayısını gösterir.
  • Üstteki küresel bir özet, toplam adımları, toplam geçen süreyi, tüm konuşma boyunca en yavaş adımı ve toplam başarısızlık sayısını gösterir.
  • 10 saniyeden yavaş adımlar uyarı göstergesiyle işaretlenir.

Aracı ayrıntıları

Aracı detayları paneli, konuşmanın analiz edildiği dönemdeki tüm yapılandırmasını gösterir. Bilgiler altı sekmeye ayrılmıştır.

Tab Açıklama
Genel bakış Konular, Araçlar, Bilgi, Çocuk Aracılar, Orkestrasyon modu, Dil, Doğrulama Modu, Model Bilgisi, Anlamsal Arama ve Son Modeller için KPI Karoları. Her karo, ayarı açıklayan bir araç ipucu içerir.
Yönergeler Aracının tam sistem isteği, Copilot Studio'da ayarlanmış şekilde.
Konular Tüm konular isim, açıklama, giriş/çıktı değişkenleri ve Etkin/Devre dışı duruma sahip.
Araçlar İsim, açıklama, tür rozeti (MCP, Akış, Bağlantı, İstem) ve Etkin/Devre dışı durumlu tüm araçlar.
Bilgi İsim, tür rozeti (SharePoint, Web, Dataverse, File), URL ve Etkin/Devre dışı durumlu tüm bilgi kaynakları.
Aracılar İsim, ilişki tipi ve Etkin/Devre dışı duruma sahip tüm bağlı çocuk aracılar.

Öneriler

Öneriler paneli, konuşmadaki sorunları otomatik olarak algılar ve bunları ciddiyet dereceleriyle uygulanabilir kartlar olarak ortaya çıkarır.

Önem Derecesi Açıklama
Yüksek Muhtemelen başarısız veya yanlış bir yanıta yol açtı. Hemen araştırın.
Orta Deneyim kaybı veya güvenilirlik riski. Yakında inceleme yapacağım.
Düşük Küçük verimsizlik veya bilgilendirici not.

Aşağıdaki sorun türleri tespit edilmiştir:

Sorun Önem Derecesi Açıklama
Başarısız adım veya hata Yüksek Bir adım hata veya istisna döndürür.
Sorumlu AI bloku Yüksek İçerik, Sorumlu AI sistemi tarafından filtrelendi.
Görüşme ilerletme Yüksek Konuşma bir insan aracıya devredildi.
Konuşmanın terk edilmesi Yüksek Kullanıcı çözüm olmadan ayrıldı.
Geri dönüş konusu tetiklendi Yüksek Aracı, kullanıcının mesajını bir konuya yönlendiremedi.
Yavaş adım (>10s) Medium Bir adımın uygulanması 10 saniyeden fazla sürdü.
Bilgi arama başarısızlığı Medium Bir bilgi kaynağı sorguladı ancak sonuç vermedi.
Belirteç sınırına yaklaşıldı Medium Belirteç kullanımı, modelin bağlam penceresi sınırına yaklaştı.
Kod adım hatası Yüksek Bir Python kod adımı bir istisna ortaya çıkardı.
MCP başlatma hatası Yüksek Bir MCP sunucusu konuşma sırasında başlatılamadı.

Her öneri kartı, önem derecesini gösteren simgeyi ve rengi, kategori rozetini, tespit edilen sorunun başlığını ve açıklamasını, sorunun nasıl araştırılacağına veya çözüleceğine dair bir öneriyi ve Konuşma önizlemesini ilgili kullanıcı mesajına kaydıran bir Sıraya Git düğmesini gösterir. Herhangi bir sorun tespit edilmediğinde, panel boş bir durum mesajı gösterir.

Konuşma önizlemesi

Konuşma önizleme paneli, kullanıcıya göründüğü şekilde tüm konuşma alışverişini gösteriyor; bot ve kullanıcı mesaj balonları, Uyarlamalı Kartların iç çizimleri, önerilen aksiyon çipleri ve geri bildirim önerileri dahil.

Bir kullanıcı mesajı balonu seçildiğinde, bu adımlar Debug bilgi paneline yüklenir. Seçilen mesaj vurgulanır, böylece hangi turun aktif olduğunu takip edebilirsiniz. Panel bağımsız olarak kaydırılabilir. Konuşma önizleme başlığında JSON'u Gör seçeneğini seçtiğinizde tam transkripsiyon JSON diyalogu açılır.

Hata ayıklama bilgileri

Hata ayıklama bilgi paneli, seçilen kullanıcı mesajı sırası için adım düzeyinde ayrıntıları gösterir. Panelde solda bir adım listesi ve bir adım seçtiğinizde açılan bir adım detay görünümü bulunur.

Adım listesi, seçilen tur için yürütülen her düzenleyici adımını, adım türünü belirten bir adım simgesi ve rengi, adım adını (mümkünse kullanıcı dostu bir görüntüleme adına dönüştürülmüş), yürütme süresini ve başarı veya başarısızlık göstergesini gösterir. Bağlı bir aracıya ait adımlar, aracının adını ve toplam yürütme süresini gösteren katlanabilir bir konteyner kartında gruplanır. Kapsayıcı üzerindeki Bağlı aracı ayrıntılarını yükle düğmesi, isteğe bağlı olarak alt aracının tam dökümünü yükler.

Aşağıdaki adım türleri desteklenmektedir:

Type Açıklama
Konu Aracının konu listesinde isimlendirilmiş bir konu.
Sistem Konusu Selam, Geri Dönüş veya Yükseltme gibi yerleşik bir platform konusu.
Bilgi Bilgi kaynağı arama adımı.
Araç / Eylem Power Automate akışı veya konnektör eylemi.
Kod Bir Python kod yürütme adımı.
Özel İstem Özel bir üretken yapay zeka istemi adımı.
Akıl Yürütücü Düzenleyici tarafından kullanılan bir iç akıl yürütme adımı.
MCP Server Model Bağlam Protokolü aracı çağrısı.
Bağlı Aracı Bağlantılı bir alt aracıya devret.

Bir adım seçildiğinde, veri transkriptte bulunduğunda gösterilen aşağıdaki bölümleri içeren bir detay paneli açılır:

  • Düşünce süreci: Düzenleyici tarafından adım çağrılmadan önce kaydedilen mantık metni. Modelin bu adımı nasıl adlandırdığını ve bundan ne beklediğini gösteriyor.
  • Adım türü: Adım için sınıflandırılmış etiket.
  • Argümanlar: Adıma aktarılan giriş parametrelerinin katlanabilir JSON ağacı görünümü. JSON'u destek biletleri için yakalamak için bir kopya seçeneği içerir.
  • Gözlem: Adımdan çıkan çıktı veya dönüş değeri. Ayrıca kopya desteğiyle katlanabilir bir JSON ağacı olarak da gösteriliyor.
  • Kod önizlemesi: Python kod adımlarında kaynak kodu sözdizimi vurgulanarak gösterilir.
  • Belirteç kullanımı: Adım için belirteç sayı, tamamlanma belirteç sayısı ve toplam ile birlikte kullanılan model adı ile birlikte belirtilir.
  • Bilgi kaynakları: Aranan kaynaklar, geri dönen sonuçlar (çıktı) ve nihai yanıtta gerçekten atıfta bulunan kaynaklar. Her giriş, kaynak adı, türü, varsa URL ve kaynağı açmak için bir bağlantı gösterir.
  • MCP sunucu bilgisi: MCP adımları için, sunucunun protokol sürümünü, ilan edilmiş yeteneklerini ve sunucunun başlatma sırasında sağladığı araçlar listesini gösterir.
  • Hata bilgisi: Bir adım başarısız olduğunda, hata kodu, hata mesajı ve (Sorumlu Yapay Zeka blokları için) filtreyi tetikleyen içerik güvenliği kategorisi gösterilir.
  • Uyarlamalı Kartlar: Adım Uyarlamalı Kart yanıtı oluşturduğunda, kart detay panelinde kullanıcının göreceği şekilde hat içinde render edilir.

Döküm JSON

Konuşma önizleme başlığında JSON'u Gör seçtiğinizde, sözdizimi vurgulama, JSON ağacında tam metin arama ve tüm yük için kopyalama panosuna kopyalama seçeneğiyle tam ham transkript aktivitelerini gösteren bir diyalog açılır.

Bu görünümü şu durumlarda kullanın:

  • Hata ayıklama bilgileri panelinde görüntülenmeyen bir olay türünü incelemeniz gerekiyor.
  • Destek bileti için belirli alanları kopyalamak istersiniz.
  • Seçilmiş görüşlerde beklenmedik davranışları araştırıyorsunuz.

Sorun giderme

Aşağıdaki bölümlerde sık karşılaşılan sorunlar ve bunların nasıl çözüleceği açıklanmaktadır.

Aracı, Ortam veya Aracı açılır menüsünde görünmez

Aracı, Aracı Envanteri ile senkronize değil ya da herhangi bir konuşma transkripti yok.

Bu sorunu çözmek için:

  1. Ortam için manuel bir Aracı Envanteri senkronizasyonu çalıştırın.
  2. Dataverse'teki Aracı Detayları tablosunda aracı kaydının var olduğunu doğrulayın.
  3. Kayıtta Transkript Mevcut mu sütununun Evet olarak ayarlandığını kontrol edin. Senkronizasyon bu alanı en az bir transkript varsa ayarlar.

Daha fazla bilgi için bkz. Copilot Aracısı Kit'te Aracı Envanterini kullanarak aracıları izleme.

Konuşma Kimliği açılır menüde bulunmuyor

Performans için, açılır menü aktif zaman aralığındaki en son 50 konuşmayı önceden yükler. Eski transkriptler hâlâ Dataverse'de mevcut ama varsayılan olarak görünmüyor. Alternatif olarak, konuşma yeni bittiyse tutanak henüz yazılmamış olabilir.

Bu sorunu çözmek için:

  1. Konuşma ID'sini doğrudan Konuşma Kimliği alanına yazın. Yazmak, o aracının tüm transkriptlerinde tam bir arama başlatır ve zaman aralığı göz ardı edilir.
  2. Zaman aralığı darsa (örneğin, Son 30 dakika), genişletin veya konuşma tarihini kapsayan özel bir aralık değiştirin.
  3. Konuşma yeni bittiyse, transkriptin Dataverse'e yazılmasını 35-40 dakika bekleyin, sonra yenileyin.

Yüklemeleri analiz edin ama Debug bilgi panelinde adım görünmüyor

Transkript mevcuttur ancak yalnızca mesaj tipi faaliyetler içerir ve tanısal iz olayı yoktur. Bu sorun genellikle konuşmanın iz verisi yaymayan bir kanaldan, örneğin belirli özel kanallar veya eski şema sürümlerinden geldiğinde ortaya çıkar.

Bu sorunu çözmek için:

  1. Konuşma önizleme başlığında JSON'u Gör seçeneğini seçerek faaliyetlerin var olduğunu doğrulayın.
  2. type: "trace" veya type: "event" girişlerini arayın. Eğer yoksa, kanal iz verisi yaymayabilir.

Erişim reddedildi veya yüklenirken boş sayfa

Roller veya izinler bir veya her iki ortamda eksiktir.

Bu sorunu çözmek için:

  1. Kit ortamında, kullanıcının CSK - Yönetici veya Sistem Yöneticisi rolüne sahip olduğundan emin olun.
  2. Hedef ortamda, oturum açmış kullanıcının conversationtranscripts, bot ve botcomponents tablolarına okuma erişimine sahip olduğundan emin olun.

Transkriptler eksik görünüyor (erken mesajlar eksik)

Uzun konuşmalar birden fazla Dataverse kaydı arasında bölünür (kayıt başına 1 MB sınırı). Tutma politikası bazı kayıtları temizlerse, birleştirilen transkriptte boşluklar vardır.

Bu sorunu çözmek için:

  1. Dataverse, varsayılan olarak 30 günden eski konuşma transkriptlerini temizler. Veri saklama sorunu varsa, Power Apps>Ayarlar>Gelişmiş ayarlar>Veri Yönetimi>Toplu Kayıt Silme bölümünde toplu silme işi zamanlamasını güncelleyin.
  2. Eğer sorun kayıt tutmadan kaynaklanmıyorsa, görüşmeye ait tüm transkript kayıtlarının Dataverse'deki conversationtranscripts tablosunda mevcut olduğunu doğrulayın.

Adımlar, okunabilir konu isimleri yerine ham şema isimlerini gösterir

botcomponents tablosunda arama başarısız oldu veya bileşen kaydı silindi.

Bu sorunu çözmek için:

  1. Oturum açmış kullanıcının hedef ortamdaki botcomponents tablosuna okuma erişimine sahip olduğunu doğrulayın.
  2. Eğer bileşen Copilot Studio'dan silindiyse, eşleşen bir kayıt bulunmaz ve Aracı Debugger, cr123_mytopic gibi ham şema adına geri döner. Bu davranış, silinmiş konular veya eylemler için beklenir.

Aracı detayları paneli veri göstermiyor

Aracı yapılandırma alma işlemi başarısız oldu veya oturum açmış kullanıcının bağlantısının hedef ortamdaki bot ve botcomponents tablolarına okuma erişimi yok.

Bu sorunu çözmek için:

  1. Uygulama tarafından kullanılan bağlantı referansı için bot ve botcomponents tablolarına okuma erişimini doğrulayın.
  2. Eğer görüşme kaydedildikten sonra aracı silinirse veya yayından kaldırılırsa, yapılandırma kayıtları artık mevcut olmayabilir. Bu durumda, Aracı detaylar paneli boş kalır, ancak transkript ve hata ayıklama panelleri hâlâ tamamen işlevseldir.

Öneriler panelinde hiçbir sorun yok ama konuşma başarısız oldu

Öneriler, transkript iz olaylarındaki desenlerden gelir. Eğer transkriptte iz veri yoksa veya hata konuşma dışında gerçekleşiyorsa (örneğin, transkriptin kaydetmediği sessiz bir ağ zaman aşımı gibi), sistem herhangi bir öneri üretmez.

Bu sorunu çözmek için:

  1. Transkript JSON'u açın, öneri olarak ortaya çıkmayan ham hata yüklerini arayın.
  2. Kırmızı renkle gösterilen adımlar için yürütme yoluna bakın. Bu adımlar, bilinen bir öneri modeline eşlenemeyen başarısızlıkları gösterir.
  • Last updated on