Azure portalında Azure AI Arama beceri kümesinde hata ayıklama

Makale
02/03/2024

Hataları belirlemek ve çözmek, değişiklikleri doğrulamak ve Azure AI Arama hizmeti yayımlanmış beceri kümesine değişiklikleri göndermek için portal tabanlı bir hata ayıklama oturumu başlatın.

Hata ayıklama oturumu, değişikliklerinizi 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 arka plan için bkz . Azure AI Search'te oturumlarda hata ayıklama. Örnek bir belgeyle hata ayıklama iş akışı alıştırması yapmak için bkz . Öğretici: Hata ayıklama oturumları.

Önkoşullar

Veri kaynağı, beceri kümesi, dizin oluşturucu ve dizin gibi mevcut bir zenginleştirme işlem hattı.
Arama hizmetinde Katkıda Bulunan rolü ataması.
Oturum durumunu kaydetmek için kullanılan bir Azure Depolama hesabı.
Sistem tarafından yönetilen kimlik kullanıyorsanız Azure'da Depolama Blob Veri Katkıda Bulunanı rol ataması Depolama. Aksi takdirde, Azure Depolama hata ayıklama oturumu bağlantısı için tam erişim bağlantı dizesi kullanmayı planlayın.
Azure Depolama hesabı bir güvenlik duvarının arkasındaysa, arama hizmeti erişimine izin verecek şekilde yapılandırın.

Sınırlamalar

Hata ayıklama oturumları genel olarak kullanılabilen tüm dizin oluşturucu veri kaynakları ve çoğu önizleme veri kaynağıyla çalışır. Aşağıdaki listede özel durumlar not alınır:

MongoDB için Azure Cosmos DB şu anda desteklenmemektedir.
NoSQL için Azure Cosmos DB için dizin sırasında bir satır başarısız olursa ve buna karşılık gelen meta veriler yoksa, hata ayıklama oturumu doğru satırı seçmeyebilir.
Azure Cosmos DB'nin SQL API'sinde bölümlenmiş bir koleksiyon daha önce bölümlenmemişse, hata ayıklama oturumu belgeyi bulamaz.
Özel beceriler için azure Depolama hata ayıklama oturumu bağlantısı için kullanıcı tarafından atanan yönetilen kimlik desteklenmez. Önkoşullarda belirtildiği gibi, sistem tarafından yönetilen kimlik kullanabilir veya anahtar içeren bir tam erişim bağlantı dizesi belirtebilirsiniz. Daha fazla bilgi için bkz. Yönetilen kimlik kullanarak arama hizmetini diğer Azure kaynaklarına Bağlan.

Portal müşteri tarafından yönetilen anahtar şifrelemesini (CMK) desteklemez. Bu, hata ayıklama oturumları gibi portal deneyimlerinde CMK ile şifrelenmiş bağlantı dizesi veya diğer şifrelenmiş meta veriler olmadığı anlamına gelir. Arama hizmetiniz CMK zorlaması için yapılandırılmışsa hata ayıklama oturumları çalışmaz.

Hata ayıklama oturumu oluşturma

Azure portalında oturum açın ve arama hizmetinizi bulun.
Sol gezinti sayfasında Oturumlarda hata ayıkla'yı seçin.
Üstteki eylem çubuğunda Hata ayıklama oturumu ekle'yi seçin.
Hata ayıklama oturumu adı bölümünde, hata ayıklama oturumunun hangi beceri kümesini, dizin oluşturucuyu ve veri kaynağını anımsamanıza yardımcı olacak bir ad sağlayın.
Depolama bağlantıda hata ayıklama oturumunu önbelleğe almak için genel amaçlı bir depolama hesabı bulun. Blob Depolama veya Azure Data Lake Storage 2. Nesil'da bir blob kapsayıcısı seçmeniz ve isteğe bağlı olarak oluşturmanız istenir. Oluşturduğunuz sonraki tüm hata ayıklama oturumları için aynı kapsayıcıyı yeniden kullanabilirsiniz. Yararlı bir kapsayıcı adı "cognitive-search-debug-sessions" olabilir.
Yönetilen kimlik kimlik doğrulaması bölümünde, Azure Depolama bağlantısı yönetilen kimlik kullanmıyorsa Yok'u seçin. Aksi takdirde, Depolama Blob Veri Katkıda Bulunanı izinleri vermiş olduğunuz yönetilen kimliği seçin.
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.
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.

Belirli belgeniz bir blobsa blob URI'sini sağlayın. URI'yi portaldaki blob özellik sayfasında bulabilirsiniz.
İsteğe bağlı olarak, Dizin Oluşturucu ayarlarında oturumu oluşturmak için kullanılan dizin oluşturucu yürütme ayarlarını belirtin. Ayarlar, gerçek dizin oluşturucu tarafından kullanılan ayarları taklit etmelidir. Bir hata ayıklama oturumunda belirttiğiniz dizin oluşturucu seçeneklerinin dizin oluşturucunun kendisini etkilemesi gerekmez.
Yapılandırmanız bu ekran görüntüsüne benzer görünmelidir. Başlamak için Oturumu kaydet'i seçin.

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

Hata ayıklama oturumu yürütülürken İptal düğmesi kullanılarak 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

Portaldaki dizin oluşturucu yürütme geçmişi, tüm belgeler için tam hata ve uyarı listesi sağlar. Hata ayıklama oturumunda hatalar ve uyarılar tek bir belgeyle sınırlandırılır. Bu listede çalışacak, değişikliklerinizi yapacak ve sorunların çözülmüş olup olmadığını doğrulamak için listeye geri döneceksiniz.

İletileri görüntülemek için AI Zenginleştirme Beceri Grafiği'nde bir beceri seçin ve ardından ayrıntılar bölmesinde Hatalar/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:

Değişikliklerinizi korumak için beceri ayrıntıları bölmesinde Kaydet'i seçin.
Değiştirilen tanımı kullanarak beceri kümesi yürütmesini çağırmak için oturum penceresinde Çalıştır'ı seçin.
Sayın azaltılıp azaltılamadığını görmek için Hatalar/Uyarılar'a dönün. Siz sekmeyi açana kadar liste yenilenmez.

Zenginleştirme düğümlerinin içeriğini görüntüleme

Yapay zeka zenginleştirme işlem hatları, kaynak belgelerden bilgi ve yapı ayıklar veya çıkarır ve işlemde zenginleştirilmiş bir belge oluşturur. Zenginleştirilmiş bir belge ilk olarak belgenin kırılması 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üğümlerle doldurulur. Beceri yürütme sırasında beceriler tarafından daha fazla düğüm oluşturulur ve burada her beceri çıkışı zenginleştirme ağacına yeni bir düğüm ekler.

Zenginleştirilmiş belgeler iç belgelerdir, ancak hata ayıklama oturumu beceri yürütme sırasında üretilen içeriğe erişmenizi sağlar. Her becerinin içeriğini veya çıkışını görüntülemek için şu adımları izleyin:

Varsayılan görünümlerle başlayın: AI zenginleştirme > Beceri Grafiği, grafik türü Bağımlılık Grafı olarak ayarlanmıştır.
Bir beceri seçin.
Sağdaki ayrıntılar bölmesinde Yürütmeler'i seçin, BIR OUTPUT seçin ve ardından ifadeyi ve sonucunu görüntülemek için İfade Değerlendiricisi'ni (</>) açın.
Alternatif olarak, düğüm listesini aşağı kaydırmak için yapay zeka zenginleştirme > Zenginleştirilmiş Veri Yapısı'nı açın. Liste, çıkış sütunu içeren olası ve gerçek düğümleri ve çıkışı üretmek için kullanılan yukarı akış nesnesini gösteren başka bir sütunu içerir.

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 ile ilgili yardım için bkz . Azure AI Arama beceri kümesinde başvuru zenginleştirmeleri. Tek tek iletilerle ilgili yardım için bkz . Yaygın dizin oluşturucu hatalarını ve uyarılarını giderme.

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

Yapay zeka zenginleştirme > Beceri Grafiği'nde bir beceri seçin. Beceri Ayrıntıları bölmesi sağ tarafta açılır.
Her iki yaklaşımdan birini kullanarak beceri tanımını düzenleyin:
- Görsel düzenleyici tercih ediyorsanız beceri Ayarlar
- JSON belgesini doğrudan düzenlemek için Beceri JSON Düzenleyicisi
Zenginleştirme ağacında düğümlere başvurmak için yol söz dizimini denetleyin. 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 çıkarılmış metinler için.

Alan 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.

Varsayılan görünümlerle başlayın: AI zenginleştirme > Beceri Grafiği, grafik türü Bağımlılık Grafı olarak ayarlanmıştır.
Üst kısımdaki Alan Eşlemeleri'ni seçin. En azından arama dizinindeki her arama belgesini benzersiz olarak tanımlayan ve veri kaynağındaki kaynak belgeyle ilişkilendiren belge anahtarını bulmanız gerekir.

Ham içeriği doğrudan veri kaynağından içeri aktarıyorsanız, zenginleştirmeyi atlayarak bu alanları Alan Eşlemeleri'nde bulmanız gerekir.
Grafiğin alt kısmındaki Çıkış Alanı Eşlemeleri'ni seçin. Burada, beceri çıkışlarından arama dizinindeki hedef alanlara eşlemeleri bulacaksınız. Verileri İçeri Aktarma sihirbazını kullanmadığınız sürece, çıktı alanı eşlemeleri el ile tanımlanır ve eksik veya yanlış yazılabilir.

Çıktı Alanı Eşlemeleri'ndeki alanların, belirtilen şekilde arama dizininde mevcut olduğunu doğrulayın ve yazım ve zenginleştirme düğümü yolu söz dizimini denetleyin.

Ö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'nizin becerisinde, hata ayıklama oturumunda, Visual Studio Code'da ve ngrok veya Tunnelmole'da yerel olarak nasıl hata ayıklanacağınız açıklanmaktadı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

Tunnelmole kullanma

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

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. NodeJS yüklü değilse, Windows için önceden derlenmiş .exe dosyasını indirin ve PATH içinde bir yere yerleştirin.
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 Azure işlevlerinin kullanıma sunulduğu varsayılan bağlantı noktası 7071 olan yerel makinenizdeki bağlantı noktasına iletir.

ngrok kullanma

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. Yerel hata ayıklamaya izin vermek üzere arama hizmetinizdeki bir zenginleştirme işlem hattından gelen istekleri makinenize iletmek için ngrok kullanın.

ngrok'u yükleyin.
Bir terminal açın ve ngrok yürütülebilir dosyasını içeren klasöre gidin.
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 işlevleri 7071'de kullanıma sunulur. Diğer araçlar ve yapılandırmalar için farklı bir bağlantı noktası sağlamanız gerekebilir.
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ında yapılandırma

Hata ayıklama oturumunda Özel Web API'si Beceri URI'nizi Tunnelmole veya ngrok iletme URL'sini çağıracak şekilde değiştirin. Beceri kümesi kodunu yürütmek için Azure İşlevi'ni kullanırken "/api/FunctionName" öğesini eklediğinizden emin olun.

Beceri tanımını portalda düzenleyebilirsiniz.

Kodunuza test etme

Bu noktada, hata ayıklama oturumunuzdan gelen yeni istekler artık yerel Azure İşlevinize gönderilmelidir. Visual Studio Code'unuzda kesme noktalarını kullanarak kodunuzun hatalarını ayıklayabilir veya adım adım çalıştırabilirsiniz.

Sonraki adımlar

Hata Ayıklama Oturumları görsel düzenleyicisinin düzenini ve özelliklerini anladığınıza göre, uygulamalı deneyim için öğreticiyi deneyin.

Öğretici: Hata ayıklama oturumlarını keşfetme

Aracılığıyla paylaş