Azure AI Arama zenginleştirme işlem hattında özel Web API'si becerisi

Özel işlemler sağlayan bir Web API uç noktasını çağırarak yapay zeka zenginleştirmesini genişletmek için Özel Web API'sini kullanın. Yerleşik beceriler gibi Özel Web API'sinde de girişler ve çıkışlar bulunur. Girişlere bağlı olarak, dizin oluşturucu çalıştırıldığında Web API'niz bir JSON yükü alır ve yanıt olarak bir JSON yükü ve bir başarı durum kodu döndürür. Yanıt, özel beceriniz tarafından belirtilen çıkışları içermelidir. Diğer tüm yanıtlar hata olarak kabul edilir ve zenginleştirme yapılmaz. JSON yükünün yapısı bu belgenin ilerleyen bölümlerinde açıklanmıştır.

Özel Web API'sinin becerisi, Azure Verilerinizde OpenAI özelliğinin uygulanmasında da kullanılır. Azure OpenAI rol tabanlı erişim için yapılandırılmışsa ve vektör dizinini oluştururken hata alırsanız403 Forbidden, Azure Yapay Zeka Arama sistem tarafından atanmış bir kimliğe sahip olduğunu ve Azure OpenAI üzerinde güvenilir bir hizmet olarak çalıştığını doğrulayın.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Beceri parametreleri

Parametreler büyük/küçük harfe duyarlıdır.

authResourceId Değeri anlama

Özel Web API'sinin becerisi yönetilen kimlik doğrulaması kullandığında, Azure Yapay Zeka Arama bir Microsoft Entra erişim belirteci alır ve özel beceri uç noktasına gönderir. authResourceId özelliği, belirtecin istendiği hedef kitle veya Uygulama Kimliği URI'si olarak da bilinen kaynak tanımlayıcısını belirtir. Değer, belirteç doğrulaması sırasında hedef uygulamanın beklediği değerle eşleşmelidir. Aksi takdirde, kimlik doğrulaması bir 401 Unauthorized yanıtla başarısız olur.

değeri, authResourceId özel becerinizi barındıran uygulamayı tanımlar. Arama hizmetinizin veya dizin oluşturucunuzun URL'si değildir.

Aşağıdaki tabloda yaygın biçimler gösterilmektedir:

özelliği, kapsam soneki olan ve olmayan .default biçimleri kabul eder. Uygulama Kimliği URI'sini doğrudan eşleştirmek için kullanın api://<appId> . gibi .defaultbir api://<appId>/.default sonek eklerseniz, erişim belirtecinin aud talebi sonek olmadan temel Uygulama Kimliği URI'sini içerir.

Azure İşlevi için Microsoft Entra kimlik doğrulamasını yapılandırma ve ayarlama authResourceIdadımları için bkz. Azure İşlev uygulamasına bağlanmak için arama hizmeti yönetilen kimliğini kullanma.

Örnek: Microsoft Entra ID tarafından korunan Azure İşlevi

Bu örnekte, Azure Yapay Zeka Arama tarafından authResourceId belirtilen hedef kitle için bir erişim belirteci alır ve özel beceri uç noktasını çağırırken belirteci içerir.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso-function.azurewebsites.net/api/enrich",
  "authResourceId": "api://contoso-customskill"
}

Beceri girişleri

Bu becerinin önceden tanımlanmış girişi yoktur. Girişler, var olan herhangi bir alan veya özel becerinize geçirmek istediğiniz zenginleştirme ağacındaki herhangi bir düğüm.

Beceri çıkışları

Bu becerinin önceden tanımlanmış çıkışı yok. Becerinin çıkışının arama dizinindeki bir alana gönderilmesi gerekiyorsa dizin oluşturucuda bir çıkış alanı eşlemesi tanımladığınızdan emin olun.

Örnek tanım

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso.example.org/api?code=<redacted>",
  "httpMethod": "POST",
  "name": "myCustomSkill",
  "httpHeaders": {
    "Authorization": "<redacted>",
    "Ocp-Apim-Subscription-Key": "<redacted>"
  }
}

{
  "uri": "<unchanged>",
  "httpHeaders": {
    "Authorization": "<unchanged>",
    "Ocp-Apim-Subscription-Key": "<unchanged>"
  }
}

Örnek giriş JSON yapısı

Bu JSON yapısı, Web API'nize gönderdiğiniz yükü temsil eder. Her zaman şu kısıtlamaları izler:

• Üst düzey varlık çağrılır values ve bir nesne dizisidir. Bu nesnelerin sayısı en çok olandır batchSize.

• Dizideki her nesnenin values sahip olduğu:

  • recordId Bu kaydı tanımlamak için kullanılan benzersiz bir dize olan özellik.

  • data JSON nesnesi olan bir özellik. özelliğinin data alanları, beceri tanımının bölümünde belirtilen inputs "adlara" karşılık gelir. Bu alanların değerleri bu alanların (belgedeki source bir alandan veya başka bir beceriden olabilir) kaynaklanabilir.

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

Örnek çıkış JSON yapısı

"Çıkış", Web API'nizden döndürülen yanıta karşılık gelir. Web API'sinin yalnızca bir JSON yükü döndürmesi (yanıt üst bilgisine Content-Type bakarak doğrulanmış) ve aşağıdaki kısıtlamaları karşılaması gerekir:

• adlı valuesbir üst düzey varlık olmalıdır ve bu bir nesne dizisi olmalıdır.

• Dizideki nesne sayısı, Web API'sine gönderilen nesne sayısıyla aynı olmalıdır.

• Her nesnenin sahip olması gerekenler:

  • Bir recordId özellik.

  • data Alanların içindeki "adlarla" output eşleşen zenginleştirmeler olduğu ve değerinin zenginleştirme olarak kabul edildiği bir nesne olan özellik.

  • Dizin errors oluşturucu yürütme geçmişine eklenen hataları listeleyen bir özellik. Bu özellik gereklidir, ancak bir null değere sahip olabilir.

  • warnings Dizin oluşturucu yürütme geçmişine eklenen uyarıları listeleyen bir dizi özelliği. Bu özellik gereklidir, ancak bir null değere sahip olabilir.

• içindeki nesnelerin values istekte veya yanıtta sıralanması önemli değildir. Ancak, web API'sine recordId yönelik özgün isteğin parçası olmayan bir recordIdiçeren yanıttaki tüm kayıtların atılması için bağıntı için kullanılır.

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

Hata durumları

Web API'nizin kullanılamaması veya başarılı olmayan durum kodları göndermesine ek olarak, aşağıdaki durumları hata olarak göz önünde bulundurun:

• Web API'sinin bir başarı durum kodu döndürmesine rağmen yanıt olmadığını application/jsongösteriyorsa, yanıt geçersizdir ve zenginleştirme yapılmaz.

• Yanıt values dizisi geçersiz kayıtlar içeriyorsa (örneğin, eksik veya çoğaltılmış recordId), geçersiz kayıtlar zenginleştirilir. Özel beceriler geliştirirken Web API beceri sözleşmesine bağlı kalın. Beklenen sözleşmeyi izleyen Power Skill deposunda sağlanan bu örneğe başvurabilirsiniz.

Web API'sinin kullanılamadığı veya HTTP hatası döndürdüğü durumlarda, dizin oluşturucu yürütme geçmişi HTTP hatasıyla ilgili kullanılabilir ayrıntıları içeren kolay bir hata içerir.

Yönetilen kimlik kimlik doğrulaması için güvenlikle ilgili dikkat edilmesi gerekenler

Özel Web API'siyle yönetilen kimlik doğrulamasını kullanırken Azure Yapay Zeka Arama tarafından authResourceId tanımlanan uygulama için bir Microsoft Entra erişim belirteci alır ve bu belirteci tarafından uribelirtilen uç noktaya gönderilen isteklere ekler. Tarafından uri başvuruda bulunan uç nokta genellikle Azure İşleviniz, Azure App Service, Azure API Management uç noktanız veya Microsoft Entra korumalı başka bir uygulamadır. Uç nokta ile tarafından authResourceIdtanımlanan uygulama arasındaki ilişkiyi yapılandırmak ve sürdürmek sizin sorumluluğundadır.

Kimlik doğrulama yöntemi ne olursa olsun, özel beceri girişleri müşteri tarafından sağlanan belgelerden veya bu belgelerden türetilen değerlerden değerler içerebilir. Tüm özel beceri girişlerine güvenilmeyen olarak davranın. Azure Yapay Zeka Arama, özel uygulamanız için içeriklerini yorumlamadan, doğrulamadan veya kısıtlamadan beceri kümesinde yapılandırılan girişleri uç noktanıza iletir.

Giden isteklerde veya diğer güvenlik duyarlı işlemlerde kullanmadan önce özel becerinizdeki belge türetilmiş değerleri doğrulayın ve kısıtlayın. Yalnızca becerinin gerektirdiği hedeflere ve bağlantı noktalarına izin veren giriş doğrulamasını, hedef izin listelerini, URL ve konak adı doğrulamasını, protokol kısıtlamalarını ve en az ayrıcalıklı ağ erişimini kullanın. Daha fazla bilgi için bkz . Ağ ve bağlantı için mimari stratejileri.

Önerilen güvenlik uygulamaları

Güvenli bir dağıtımın korunmasına yardımcı olmak için şu uygulamaları izleyin:

• uri özelliğini yalnızca Azure Yapay Zeka Arama istekleri alması amaçlanan güvenilen uç noktalara işaret eden şekilde yapılandırın.
• Erişim belirtecini alması ve doğrulaması beklenen Microsoft Entra uygulamasını tanımlamak için yapılandırınauthResourceId.
• İstekleri işlemeden önce uygulama alma isteklerinin hedef kitle (), veren (aud), kiracı (isstid) ve gerekli uygulama rolleri veya izinleri dahil olmak üzere standart belirteç taleplerini doğruladığından emin olun.
• Azure Yapay Zeka Arama yönetilen kimliğe izinler verirken en az ayrıcalık ilkesini uygulayın.
• Özel Web API'si beceri tanımlarını, Microsoft Entra uygulama kayıtlarını ve Azure Yapay Zeka Arama yönetilen kimliklere verilen uygulama rolü atamalarını ve izinlerini düzenli aralıklarla gözden geçirin. Yerleşik değişiklik yönetimi ve güvenlik gözden geçirme süreçlerinizle yapılandırma değişikliklerini gözden geçirin.
• Azure İşlevleri, App Services, API'ler ve API ağ geçitleri için uç nokta yapılandırmalarını düzenli aralıklarla gözden geçirin.
• Beklenmeyen veya yetkisiz etkinlikler için uygulama oturum açma günlüklerini, kimlik doğrulama olaylarını ve API erişim günlüklerini izleyin.
• Artık gerekli olmayan kullanılmayan uç noktaları, izinleri, uygulama kayıtlarını ve rol atamalarını kaldırın.

Beceri kümesi yapılandırmasına erişimi kısıtlama

Beceri kümelerini oluşturabilen, değiştirebilen veya çalıştırabilen kullanıcılar hem hedef uç noktayı hem de Özel Web API'sinin kullandığı kimlik doğrulama yapılandırmasını denetleyebilir. Bu izinleri güvenilen yöneticilerle kısıtlayın ve yönetilen kimlik özellikli özel becerileri yapılandırırken standart değişiklik yönetimi ve güvenlik gözden geçirme işlemlerinizi izleyin.

Ayrıca bakınız

• Beceri kümesi tanımlama
• Yapay zeka zenginleştirme işlem hattına özel beceri ekleme
• Örnek: Yapay zeka zenginleştirmesi için özel beceri oluşturma
• Power Skill deposu