Azure Yapay Zeka Arama zenginleştirme işlem hattına özel beceri ekleme

Not

Azure Yapay Zeka Arama Azure portalı, REST API'leri ve Azure SDK’ları aracılığıyla kullanılabilir. Ayrıca kuruluş içeriğini Microsoft Foundry portalındaki aracılar için yeniden kullanılabilir, izin kullanan bilgi bankalarına dönüştüren yönetilen bilgi katmanı Foundry IQ'yu temel alır.

Yapay zeka zenginleştirme işlem hattı hem yerleşik becerileri hem de oluşturup yayımladığınız özel becerileri içerebilir. Özel kodunuz arama hizmetinin dışında çalışır (örneğin, bir Azure işlevi olarak), ancak girişleri kabul eder ve diğer beceriler gibi çıkışları beceri kümesine gönderir. Verileriniz, modelinizin dağıtıldığı bölge işlenir.

Özel beceriler karmaşık gelebilir, ancak uygulanması basit olabilir. Desen eşleştirme veya sınıflandırma modelleri sağlayan mevcut paketleriniz varsa, bloblardan ayıklanan içeriği işlenmek üzere bu modellere geçirebilirsiniz. Yapay zeka zenginleştirmesi Azure tabanlı olduğundan modelinizi Azure'da da barındırmanız gerekir. Yaygın barındırma seçenekleri arasında Azure İşlevleri veya containers bulunur.

Özel bir beceri oluşturuyorsanız, bu makalede beceriyi işlem hattıyla tümleştirmek için kullandığınız arabirim açıklanmaktadır. Birincil gereksinim, girişleri kabul etme ve çıkışları beceri kümesinin bir bütün olarak kullanabileceği şekilde yayma yeteneğidir. Bu nedenle, bu makalenin odak noktası zenginleştirme işlem hattının gerektirdiği giriş ve çıkış biçimleridir.

Özel becerilerin avantajları

Özel beceri oluşturmak, içeriğinize özgü dönüşümler eklemeniz için bir yol sunar. Örneğin, iş ve finansal sözleşmeleri ve belgeleri ayırt etmek için özel sınıflandırma modelleri oluşturabilir veya ilgili içerik bulmak amacıyla ses dosyalarını daha derinlemesine inceleyebilmeniz için bir konuşma tanıma becerisi ekleyebilirsiniz. Adım adım bir örnek için bkz . Örnek: Yapay zeka zenginleştirmesi için özel beceri oluşturma.

Uç noktayı ve zaman aşımı aralığını ayarlama

Özel Web API'si becerisi aracılığıyla özel becerinin arabirimini belirtin.

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230-second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

URI işlevinizin veya uygulamanızın HTTPS uç noktasıdır. URI'yi ayarlarken URI'nin güvenli (HTTPS) olduğundan emin olun. Kodunuzu bir Azure işlev uygulamasında barındıracaksanız, isteği yetkilendirmek için üst bilgide bir API anahtarı veya URI parametresi olarak ekleyin.

İşleviniz veya uygulamanız kimlik doğrulaması ve yetkilendirme için Azure yönetilen kimlikler ve Azure rolleri kullanıyorsa, özel beceri istekte bir kimlik doğrulama belirteci içerebilir. Aşağıdaki noktalar bu yaklaşımın gereksinimlerini açıklar:

tarafından uritanımlanan uygulamanın uç noktasına işaret olduğundan authResourceId emin olun. Eşleşmeyen değerler, kimlik doğrulama hatalarına veya isteklerin istenmeyen bir uç noktaya gönderilmesine neden olabilir. Güvenlik yönergeleri, önerilen uygulamalar ve yapılandırmanızı doğrulama adımları için bkz. Yönetilen kimlik kimlik doğrulaması için güvenlikle ilgili dikkat edilmesi gerekenler.

Varsayılan olarak, 30 saniyelik bir pencere (PT30S) içinde yanıt döndürülmezse uç noktaya bağlantı zaman aşımına uğradı. Dizin oluşturma işlem hattı eşzamanlıdır ve bu süre içinde yanıt alınmazsa bir zaman aşımı hatası üretir. parametresini (timeout) ayarlayarak aralığı en fazla 230 saniyeye PT230S çıkarabilirsiniz.

IP erişim kısıtlamalarıyla korunan bir uç nokta yanıt vermezse, zaman aşımı hatasını daha hızlı ortaya çıkarabilmek için geçici olarak gibi timeoutkısa bir değere ayarlayınPT10S. Azure işlev uygulaması için Ayarlar>Ağ>Erişimi kısıtlamaları altında gelen IP kurallarını yönetin. İzin verecek IP adresleri için bkz. Dizin oluşturucu bağlantılarına izin vermek için IP güvenlik duvarı kurallarını yapılandırma.

Web API girişlerini biçimlendirme

Web API'sinin işlenmek üzere bir kayıt dizisi kabul etmesi gerekir. Her kayıtta, web API'nize girdi olarak bir özellik torbası sağlayın.

Sözleşme metninde belirtilen ilk tarihi tanımlayan temel bir zenginleştirici oluşturmak istediğinizi varsayalım. Bu örnekte, özel beceri tek bir girişi kabul eder: contractText. Yetenek ayrıca tek bir çıktı üretir; bu da sözleşme tarihidir. Zenginleştiriciyi daha ilginç hale getirmek için contractDate öğesini çok parçalı bir karmaşık tür biçiminde döndürün.

Web API'niz bir toplu giriş kaydı almaya hazır olmalıdır. Dizinin her üyesi values belirli bir kaydın girişini temsil eder. Her kaydın aşağıdaki öğelere sahip olması gerekir:

  • recordId Belirli bir kaydın benzersiz tanımlayıcısı olan üye. Zenginleştiriciniz sonuç döndürdüğünde, çağıran tarafın kayıt sonuçlarını girdilerle eşleştirebilmesi için bu recordId öğesini sağlamalıdır.

  • Her kayıt için giriş alanları kümesi olan bir data üye.

Sonuçta elde edilen web API'si isteği aşağıdaki gibi görünebilir:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issued on November 3, 2023 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

Uygulamada kodunuz yalnızca burada gösterilen üç kayıt yerine yüzlerce veya binlerce kayıtla çağrılabilir.

Web API çıkışlarını biçimlendirme

Çıkış biçimi, recordId ve bir özellik çantası içeren bir kayıt kümesidir. Bu özel örnekte yalnızca bir çıkış vardır, ancak birden fazla özellik döndürebilirsiniz. En iyi uygulama olarak, bir kayıt işlenemediyse hata ve uyarı iletileri döndürmeyi göz önünde bulundurun.

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2023 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

Beceri kümesine özel beceri ekleme

Web API zenginleştiricisi oluşturduğunuzda, isteğin bir parçası olarak HTTP üst bilgilerini ve parametrelerini tanımlayabilirsiniz. Aşağıdaki kod parçacığı, istek parametrelerinin ve isteğe bağlı HTTP üst bilgilerinin beceri kümesi tanımına nasıl dahil edilebileceğini gösterir. Yapılandırma ayarlarını kodunuzla geçirmeniz gerekiyorsa HTTP üst bilgisi ayarlamak yararlı olur.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

Not

GET ile beceri kümesini aldığınızda hizmet, kimlik bilgilerinin açığa çıkmasını önlemek için tüm <redacted> değerleri için httpHeaders döndürür. Depolanan üst bilgi değerlerini değiştirmeden beceriyi güncelleştirmek için her bir değeri <unchanged> olarak ayarlayın. Ayrıntılar ve örnekler için bkz. Özel Web API'si becerisi — Beceri parametreleri.

Bu videoyu izleyin

Video tanıtımı ve demo için aşağıdaki tanıtımı izleyin.

Sonraki adımlar

Bu makalede, özel bir beceriyi beceri kümesiyle tümleştirmek için gereken arabirim gereksinimleri ele alınmıştır. Özel beceriler ve beceri kümesi oluşturma hakkında daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın:

  • Son güncelleştirme: