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

Özel Web API'si becerisi, özel işlemler sağlayan bir Web API uç noktasına çağrı yaparak yapay zeka zenginleştirmesini genişletmenize olanak tanır. Yerleşik becerilere benzer şekilde, Ö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 bir JSON yükünü yanıt olarak ve bir başarı durum koduyla birlikte verir. Yanıtın özel beceriniz tarafından belirtilen çıkışlara sahip olması beklenir. Diğer tüm yanıtlar hata olarak kabul edilir ve zenginleştirme yapılmaz. JSON yükünün yapısı bu belgede daha aşağıda açıklanmıştır.

Özel Web API'sinin becerisi, Verilerinizde Azure 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 çağrılar alırsanız403 Forbidden, Azure AI Search'te sistem tarafından atanan bir kimlik olduğunu ve Azure OpenAI'de güvenilir 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.

Beceri girişleri

Bu beceri için önceden tanımlanmış giriş yok. 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 beceri için ö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"
    }
  ]
}

Örnek giriş JSON yapısı

Bu JSON yapısı, Web API'nize gönderilen 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 tür nesnelerin sayısı en fazla şeklindedir batchSize.

• Dizideki her nesnenin values sahip olduğu:

  • Bu recordId 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 değerleridir source (belgedeki bir alandan veya başka bir beceriden olabilir).

{
    "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öndermenize ek olarak, aşağıdakiler hatalı durumlar olarak kabul edilir:

• Web API'sinin bir başarı durum kodu döndürmesine rağmen yanıt bunun application/json olmadığını gösteriyorsa yanıt geçersiz kabul edilir ve zenginleştirme yapılmaz.

• Yanıt values dizisinde geçersiz kayıtlar (örneğin, recordId eksik veya yinelenen) varsa, geçersiz kayıtlar için zenginleştirme yapılmaz. Özel beceriler geliştirirken Web API beceri sözleşmesine uymak önemlidir. 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şine HTTP hatasıyla ilgili kullanılabilir ayrıntıları içeren kolay bir hata eklenir.

Ayrıca bkz.

• 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