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

Makale
04/27/2024

Yapay zeka zenginleştirme işlem hattı , kişisel olarak oluşturup yayımladığınız yerleşik becerileri ve özel becerileri içerebilir. Özel kodunuz arama hizmetinden (örneğin, bir Azure işlevi olarak) harici olarak yürütülür, ancak girişleri kabul eder ve diğer beceriler gibi çıkışları beceri kümesine gönderir.

Özel beceriler karmaşık gelebilir, ancak uygulama açısından basit ve basit olabilir. Desen eşleştirme veya sınıflandırma modelleri sağlayan mevcut paketleriniz varsa, bloblardan ayıkladığınız içerik işlenmek üzere bu modellere geçirilebilir. Yapay zeka zenginleştirmesi Azure tabanlı olduğundan modeliniz de Azure'da olmalıdır. Bazı yaygın barındırma yöntemleri arasında Azure İşlevleri veya Kapsayıcılar kullanılır.

Ö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ümesi içinde bir bütün olarak kullanılabilir olacak ş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 beceri arabirimi, Özel Web API'sinin becerisi aracılığıyla belirtilir.

"@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. Kodunuz bir Azure işlev uygulamasında barındırılıyorsa, URI üst bilgide bir API anahtarı veya isteği yetkilendirmek için bir URI parametresi içermelidir.

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

Dizin oluşturucu adına istek gönderen arama hizmetinin, çağıranın Kimliğinin Microsoft Entra Id ile doğrulanabilmesi için yönetilen kimlik (sistem veya kullanıcı tarafından atanan) kullanacak şekilde yapılandırılması gerekir.
İşleviniz veya uygulamanız Microsoft Entra Id için yapılandırılmalıdır.
Özel beceri tanımınız bir authResourceId özellik içermelidir. Bu özellik desteklenen biçimde bir uygulama (istemci) kimliği alır: api://<appId>.

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ı zaman uyumludur ve bu zaman diliminde bir yanıt alınmazsa dizin oluşturma bir zaman aşımı hatası oluşturur. Zaman aşımı parametresini (PT230S ) ayarlayarak aralığı en fazla 230 saniyeye çıkarabilirsiniz.

Web API girişlerini biçimlendirme

Web API'sinin işlenecek bir kayıt dizisini kabul etmesi gerekir. Her kayıtta, Web API'nize giriş olarak bir özellik paketi 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, sözleşme metni olarak tek bir "contractText" girişini kabul eder. Beceri ayrıca sözleşmenin tarihi olan tek bir çıkışa sahiptir. Zenginleştiriciyi daha ilginç hale getirmek için bu "contractDate" değerini çok parçalı karmaşık bir tür şeklinde döndürebilirsiniz.

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

Belirli bir kaydın benzersiz tanımlayıcısı olan "recordId" üyesi. Zenginleştiriciniz sonuçları döndürdüğünde, çağıranın kayıt sonuçlarını girişleriyle eşleştirmesine izin vermek için bu "recordId" değerini sağlaması gerekir.
Her kayıt için giriş alanları paketi olan bir "veri" üyesi.

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 issues 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ışın biçimi, "recordId" ve özellik paketi içeren bir kayıt kümesidir. Bu özel örnekte yalnızca bir çıkış vardır, ancak birden fazla özellik çıkışı yapabilirsiniz. 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 açıklayabilirsiniz. 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"
          }
        ]
      }
  ]
}

Bu videoyu izleyin

Video tanıtımı ve tanıtımı 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 bu bağlantılarla devam edin.