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

Makale
03/06/2024

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

Not

Dizin oluşturucu, Web API'sinden döndürülen belirli standart HTTP durum kodları için iki kez yeniden denenir. Bu HTTP durum kodları şunlardır:

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Beceri parametreleri

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

Parametre adı	Açıklama
`uri`	JSON yükünün gönderildiği Web API'sinin URI'sini. Yalnızca https URI düzenine izin verilir.
`authResourceId`	(İsteğe bağlı) Ayarlanırsa, bu becerinin kodu barındıran işlev veya uygulama bağlantısında yönetilen kimlik kullanması gerektiğini belirten bir dize. Bu özellik, desteklenen biçimde bir uygulama (istemci) kimliği veya Microsoft Entra Id'de uygulamanın kaydını alır: `api://<appId>`. Bu değer, dizin oluşturucu tarafından alınan kimlik doğrulama belirtecinin kapsamını daraltmak için kullanılır ve işleve veya uygulamaya özel Web beceri API'si isteğiyle birlikte gönderilir. Bu özelliğin ayarlanması, arama hizmetinizin yönetilen kimlik için yapılandırılmasını ve Azure işlev uygulamanızın bir Microsoft Entra oturum açma işlemi için yapılandırılmasını gerektirir. Bu parametreyi kullanmak için API'yi ile `api-version=2023-10-01-Preview`çağırın.
`httpMethod`	Yükü gönderirken kullanılacak yöntem. İzin verilen yöntemler veya'dır `PUTPOST`
`httpHeaders`	Anahtarların üst bilgi adlarını, değerlerin de yüküyle birlikte Web API'nize gönderilen üst bilgi değerlerini temsil ettiği anahtar-değer çiftleri koleksiyonu. Aşağıdaki üst bilgilerin bu koleksiyonda olması yasaktır: , , , , , `Content-Type`, `Cookie`, `Host`, `TEUpgrade`, `Via`. `Content-LengthAccept-EncodingAccept-CharsetAccept`
`timeout`	(İsteğe bağlı) Belirtildiğinde, API çağrısı yapan http istemcisinin zaman aşımını gösterir. XSD "dayTimeDuration" değeri (ISO 8601 süre değerinin kısıtlanmış bir alt kümesi) olarak biçimlendirilmelidir. Örneğin, `PT60S` 60 saniye için. Ayarlanmamışsa, varsayılan değer olarak 30 saniye seçilir. Zaman aşımı en fazla 230 saniye ve en az 1 saniye olarak ayarlanabilir.
`batchSize`	(İsteğe bağlı) API çağrısı başına kaç "veri kaydı" gönderildiğini gösterir (aşağıdaki JSON yük yapısına bakın). Ayarlanmamışsa, varsayılan olarak 1000 seçilir. Dizin aktarım hızı ile API'nizdeki yük arasında uygun bir denge elde etmek için bu parametreyi kullanmanızı öneririz.
`degreeOfParallelism`	(İsteğe bağlı) Belirtildiğinde, dizin oluşturucunun sağladığınız uç noktaya paralel olarak yaptığı çağrı sayısını gösterir. Uç noktanız baskı altında başarısız oluyorsa bu değeri azaltabilir veya uç noktanız yükü işleyebilirse yükseltebilirsiniz. Ayarlanmazsa, varsayılan 5 değeri kullanılır. `degreeOfParallelism` en fazla 10 ve en az 1 olarak ayarlanabilir.

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.