Azure portal'da Azure Yapay Zeka Arama beceri kümesinde hata ayıklama

Azure Yapay Zeka Arama service hataları tanımlayıp çözmek, değişiklikleri doğrulamak ve değişiklikleri mevcut beceri kümesine göndermek için portal tabanlı bir hata ayıklama oturumu başlatın.

Hata ayıklama oturumu, beceri kümesi değişikliklerini etkileşimli olarak düzenlemek ve test etmek için kullanabileceğiniz, kapsamı tek bir belge olarak belirlenmiş önbelleğe alınmış bir dizin oluşturucu ve beceri kümesi yürütmesidir. Hata ayıklamayı bitirdiğinizde, değişikliklerinizi beceri kümesine kaydedebilirsiniz.

Hata ayıklama oturumlarının nasıl çalıştığına ilişkin bilgiler için bkz. Azure Yapay Zeka Arama'te Hata Ayıklama Oturumları. Örnek bir belgeyle hata ayıklama iş akışı alıştırması yapmak için bkz . Öğretici: Hata ayıklama oturumları.

Önkoşullar

• Bir Azure AI Arama hizmeti, herhangi bir bölge veya katman.

• Oturum durumunu kaydetmek için kullanılan bir Azure Depolama hesabı.

• Var olan bir zenginleştirme işlem hattı, şunları içeren: veri kaynağı, beceri kümesi, dizin oluşturucu ve dizin.

Sınırlamalar

Hata ayıklama oturumları genel kullanıma açık tüm dizin oluşturucu veri kaynaklarıyla ve çoğu önizleme veri kaynağıyla çalışır ve aşağıdaki özel durumlar geçerlidir:

• SharePoint dizin oluşturucu.

• Azure Cosmos DB için MongoDB dizin oluşturucusu.

• Azure Cosmos DB for NoSQL için, indeksleme sırasında bir satır başarısız olursa ve karşılık gelen meta veriler yoksa, hata ayıklama oturumu doğru satırı seçmeyebilir.

• Azure Cosmos DB'nin NoSQL API'sinde bölümlenmiş bir koleksiyon daha önce bölümlenmemişse, hata ayıklama oturumu belgeyi bulamaz.

• Özel beceriler için kullanıcı tarafından atanan yönetilen kimlik, Azure Depolama hata ayıklama oturumu bağlantısı için desteklenmez. Önkoşullarda belirtildiği gibi, sistem tarafından yönetilen kimlik kullanabilir veya anahtar içeren tam bir access bağlantı dizesi belirtebilirsiniz. Daha fazla bilgi için bkz. Yönetilen bir kimlik kullanarak arama hizmetini diğer Azure kaynaklarına bağlama.

Güvenlik ve izinler

• Azure Depolama'a hata ayıklama oturumunu kaydetmek için search service kimliğinin Azure Depolama üzerinde Storage Blob Veri Katkıcısı izinlerine sahip olması gerekir. Aksi takdirde, Azure Depolama hata ayıklama oturumu bağlantısı için tam erişim bağlantı dizesini seçmeyi planlayın.

• Azure Depolama hesabı bir güvenlik duvarının arkasındaysa allow search service access olarak yapılandırın.

• Azure Yapay Zeka Arama müşteri tarafından yönetilen bir şifreleme anahtarı (CMK) kullanacak şekilde yapılandırılmışsa, veriler kalıcı hale geldiğinde hata ayıklama oturumundaki hassas bilgiler bu anahtarla şifrelenir.

Bir hata ayıklama oturumu oluştur.

1. Azure portalında arama hizmetinize gidin.

2. Soldaki menüde Arama yönetimi

3. Üstteki eylem çubuğunda Hata ayıklama oturumu ekle'yi seçin.

   

4. Hata ayıklama oturumu adı bölümünde, oturumun hangi beceri kümesini, dizin oluşturucuyu ve veri kaynağını kapsadığını hatırlamanıza yardımcı olacak bir ad sağlayın.

5. Dizin oluşturucu şablonunda, hata ayıklamak istediğiniz beceri kümesini yönlendiren dizin oluşturucuyu seçin. Oturumu başlatmak için hem dizin oluşturucunun hem de beceri kümesinin kopyaları kullanılır.

6. Hata ayıklamak için belge bölümünde dizindeki ilk belgeyi seçin veya belirli bir belgeyi seçin. Veri kaynağına bağlı olarak belirli bir belgeyi seçerseniz sizden URI veya satır kimliği istenir.

   Blob storage'daki belirli bir belge için: blob URI'sini sağlayın. URI'yi Azure portal blob özellik sayfasında bulabilirsiniz.

   

   NoSQL için Azure Cosmos DB'deki belirli bir belge için: değerin arama dizininde belge anahtarını ve bölüm anahtarı için Cosmos DB'deki varlığın kimliğini belirtin.

   

   Cosmos DB örneği için hata ayıklama oturumu yapılandırması aşağıda verilmiştir.

   

7. Storage account içinde hata ayıklama oturumunu önbelleğe almak için genel amaçlı bir storage hesabı seçin.

8. Yönetilen kimlik kullanarak kimlik doğrula seçeneğini, arama hizmeti sistem tarafından yönetilen kimliğe daha önce Storage Blob Veri Katkıda Bulunanı izinleri atadıysanız seçin. Bu kutuyu işaretlemezseniz, arama hizmeti tam erişim bağlantı dizesi kullanarak bağlanır.

9. Kaydet'i seçin.

   • Azure Yapay Zeka Arama, Azure Depolama üzerinde ms-az-cognitive-search-debugsession adlı bir blob kapsayıcısı oluşturur.
   • Bu kapsayıcının içinde, oturum adı için sağladığınız adı kullanarak bir klasör oluşturur.
   • Hata ayıklama oturumunuzu başlatır.

Hata ayıklama oturumu, seçilen belgede dizin oluşturucu ve beceri kümesini yürüterek başlar. Belgenin içeriği ve meta verileri oturumda görünür ve kullanılabilir.

Bir hata ayıklama oturumu yürütülürken iptal edilebilir. İptal düğmesine basarsanız kısmi sonuçları analiz edebilmeniz gerekir.

Hata ayıklama oturumunun yürütülmesi, ek işlemden geçtiğinden dizin oluşturucudan daha uzun sürmesi beklenir.

Hatalarla ve uyarılarla başlayın

Azure portal dizin oluşturucu yürütme geçmişi size tüm belgeler için tam hata ve uyarı listesi verir. Hata ayıklama oturumunda hatalar ve uyarılar tek bir belgeyle sınırlıdır. Bu listede çalışabilir, değişikliklerinizi yapabilir ve ardından sorunların çözülmüş olup olmadığını doğrulamak için listeye dönebilirsiniz.

Hata ayıklama oturumunun dizinin tamamından bir belgeyi temel alındığını unutmayın. Bir giriş veya çıkış yanlış görünüyorsa, sorun bu belgeye özgü olabilir. Hataların ve uyarıların sık veya tek bir belgeye özgü olup olmadığını onaylamak için farklı bir belge seçebilirsiniz.

Sorunların listesi için Hatalar veya Uyarılar'ı seçin.

En iyi yöntem olarak, çıkışlara geçmeden önce girişlerle ilgili sorunları çözün.

Bir değişikliğin bir hatayı giderip gidermediğini kanıtlamak için şu adımları izleyin:

1. Değişikliklerinizi korumak için beceri ayrıntıları bölmesinde Kaydet'i seçin.

2. Değiştirilen tanımı kullanarak beceri kümesi yürütmesini çağırmak için oturum penceresinde Çalıştır'ı seçin.

3. Hatalar veya Uyarılar'a dönüp sayının azaltılıp azaltılmadığını kontrol edin.

Zenginleştirilmiş veya oluşturulan içeriği görüntüleme

Yapay zeka zenginleştirme süreçleri, kaynak belgelerden bilgi ve yapı çıkarır veya çıkarsar, ve bu süreçte daha zengin bir belge oluşturur. Zenginleştirilmiş bir belge, ilk olarak belge çözümlemesi sırasında oluşturulur ve bir kök düğüm (/document) ile birlikte meta veriler ve belge anahtarı gibi doğrudan veri kaynağından kaldırılan tüm içerikler için düğümlerin eklenmesiyle zenginleştirilir. Beceriler yürütülürken daha fazla düğüm oluşturulur ve her beceri çıktısı zenginleştirme ağacına yeni bir düğüm ekler.

Beceri kümesi tarafından oluşturulan veya kullanılan tüm içerik İfade Değerlendiricisi'nde görünür. Zenginleştirilmiş belge ağacındaki her giriş veya çıkış değerini görüntülemek için bağlantıların üzerine gelebilirsiniz. Her becerinin girişini veya çıkışını görüntülemek için şu adımları izleyin:

1. Hata ayıklama oturumunda, bağlamsal ayrıntıları görüntülemek için mavi oku genişletin. Varsayılan olarak, ayrıntı zenginleştirilmiş belge veri yapısıdır. Ancak, bir beceri veya eşleme seçerseniz, ayrıntı bu nesneyle ilgili olur.

   

2. Bir beceri seçin.

   

3. Beceri işlemede daha fazla detaya gitmek için bağlantıları izleyin. Örneğin, aşağıdaki ekran görüntüsünde Metin Bölme becerisinin ilk yinelemesinin çıkışı gösterilmektedir.

   

Dizin eşlemelerini denetleme

Beceriler çıktı oluşturuyorsa ancak arama dizini boşsa alan eşlemelerini denetleyin. Alan eşlemeleri, içeriğin işlem hattından nasıl bir arama dizinine taşınacağını belirtir.

Eşleme seçeneklerinden birini seçin ve kaynak ve hedef tanımları gözden geçirmek için ayrıntılar görünümünü genişletin.

• Projeksiyon eşlemeleri , verileri içeri aktarma sihirbazı tarafından oluşturulan beceriler gibi tümleşik vektörleştirme sağlayan beceri kümelerinde bulunur. Bu eşlemeler üst-alt (öbek) alan eşlemelerini ve yalnızca öbeklenmiş içerik için ikincil dizin oluşturulup oluşturulmadığını belirler

• Çıktı alanı eşlemeleri dizin oluşturucularda bulunur ve beceri kümeleri yerleşik veya özel becerileri çağırdığında kullanılır. Bu eşlemeler, zenginleştirme ağacındaki bir düğümden arama dizinindeki bir alana veri yolunu ayarlamak için kullanılır. Yollar hakkında daha fazla bilgi için zenginleştirme düğümü yol söz dizimi konusuna bakın.

• Alan eşlemeleri dizin oluşturucu tanımlarında bulunur ve veri kaynağındaki ham içerikten ve dizindeki bir alandan veri yolunu oluşturur. Kodlama ve kod çözme adımları eklemek için alan eşlemelerini de kullanabilirsiniz.

Bu örnekte projeksiyon eşlemesinin ayrıntıları gösterilir. Tüm eşleme sorunlarını düzeltmek için JSON'ı düzenleyebilirsiniz.

Beceri tanımlarını düzenleme

Alan eşlemeleri doğruysa yapılandırma ve içerik için tek tek becerileri denetleyin. Bir beceri çıkış üretemezse, hata ve doğrulama iletileri aracılığıyla belirlenebilen bir özellik veya parametre eksik olabilir.

Geçersiz bağlam veya giriş ifadesi gibi diğer sorunları çözmek daha zor olabilir çünkü hata size neyin yanlış olduğunu söyler, ancak nasıl düzelteceğinizi söylemez. Bağlam ve giriş söz dizimi hakkında yardım almak için Azure Yapay Zeka Arama beceri setinde Başvuru zenginleştirmelerine bakın. Bireysel iletilerle ilgili yardım için, Yaygın dizin oluşturucu hatalarını ve uyarılarını giderme kısmına bakın.

Aşağıdaki adımlarda bir beceri hakkında nasıl bilgi alabileceğiniz gösterilmektedir.

1. Çalışma yüzeyinde bir beceri seçin. Beceri ayrıntıları bölmesi sağ tarafta açılır.

2. Beceri Ayarlarını kullanarak beceri tanımını düzenleyin. JSON'yi doğrudan düzenleyebilirsiniz.

3. Zenginleştirme ağacında düğümlere referans almak için yol söz dizimini kontrol edin. En yaygın giriş yollarından bazıları şunlardır:

   • /document/content metin öbekleri için. Bu düğüm blob'un içerik özelliğinden doldurulur.
   • /document/merged_content Metin Birleştirme becerisini içeren beceri kümelerindeki metin öbekleri için.
   • /document/normalized_images/* resimlerden tanınan veya türetilen metinler için.

Özel beceride yerel olarak hata ayıklama

Kod dışarıdan çalıştırıldığından özel becerilerin hata ayıklaması daha zor olabilir, bu nedenle hata ayıklama oturumu hata ayıklama için kullanılamaz. Bu bölümde, Özel Web API becerinizi, hata ayıklama oturumlarınızı, Visual Studio Code'u ve ngrok veya Tunnelmole'u yerel olarak nasıl hata ayıklayacağınız açıklanır. Bu teknik, Azure İşlevleri veya yerel olarak çalışan başka bir Web Framework'te (örneğin, FastAPI) yürütülen özel becerilerle çalışır.

Genel URL alma

Bu bölümde, özel becerinin genel URL'sini almaya yönelik iki yaklaşım açıklanmaktadır.

Tunnelmole kullanma

Tunnelmole, istekleri bir tünel aracılığıyla yerel makinenize ileten genel bir URL oluşturabilen bir açık kaynak tünel aracıdır.

1. Tunnelmole'u yükleme:

   • npm: npm install -g tunnelmole
   • Linux: curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
   • Mac: curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
   • Windows: npm kullanarak yükleyin. Node.js yüklü değilse , Windows için önceden derlenmiş .exe dosyasını indirin ve PATH'inizde bir yere yerleştirin.

2. Yeni bir tünel oluşturmak için şu komutu çalıştırın:

   tmole 7071
   

   Şuna benzer bir yanıt görmeniz gerekir:

   http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   

   Yukarıdaki örnekte, https://m5hdpb-ip-49-183-170-144.tunnelmole.net yerel makinenizde 7071 bağlantı noktasına iletilir. Bu, Azure functions kullanıma sunulduğu varsayılan bağlantı noktasıdır.

ngrok'u kullan

ngrok , internet isteklerinin yerel makinenize ulaşması için tünel oluşturma veya iletme URL'si oluşturabilen popüler, kapalı kaynak, platformlar arası bir uygulamadır. Local debugging'a izin vermek için, arama hizmetinizdeki bir zenginleştirme işlem hattından makinenize gelen istekleri iletmek amacıyla ngrok kullanın.

1. ngrok'u yükleyin.

2. Bir terminal açın ve ngrok yürütülebilir dosyasını içeren klasöre gidin.

3. Yeni bir tünel oluşturmak için ngrok'u aşağıdaki komutla çalıştırın:

   ngrok http 7071 
   

   Not

   Varsayılan olarak, Azure functions 7071'de kullanıma sunulur. Diğer araçlar ve yapılandırmalar için farklı bir bağlantı noktası sağlamanız gerekebilir.

4. ngrok başladığında, sonraki adım için genel iletme URL'sini kopyalayın ve kaydedin. İletme URL'si rastgele oluşturulur.

   

Azure portal'da yapılandırma

Özel beceriniz için genel bir URL'niz olduğunda, hata ayıklama oturumunuz sırasında Özel Web API'si Beceri URI'nizi Tunnelmole veya ngrok iletme URL'sini çağırmak için değiştirin. Beceri kümesi kodunu yürütmek için Azure İşlevini kullanırken "/api/FunctionName" eklemeyi unutmayın.

Beceri tanımını Beceri ayrıntıları bölmesinin Beceri ayarları bölümünde düzenleyebilirsiniz.

Kodunuzu test edin

Bu noktada, hata ayıklama oturumunuzdan gelen yeni istekler artık yerel Azure İşlevinize gönderilmelidir. kodunuzun hatalarını ayıklamak veya adım adım çalıştırmak için Visual Studio Kodunuzda kesme noktalarını kullanabilirsiniz.

Sonraki adımlar

Debug Oturumları görsel düzenleyicisinin düzenini ve özelliklerini anladığınıza göre, uygulamalı deneyim için eğitim kılavuzunu deneyin.