Egyéni webes API-képesség az Azure AI Search bővítési folyamatában

Cikk
03/10/2024

Az Egyéni webes API-képesség lehetővé teszi az AI-bővítés kiterjesztését egy egyéni műveleteket biztosító webes API-végpontra való meghívással. A beépített képességekhez hasonlóan az egyéni webes API-képességek bemenetekkel és kimenetekkel is rendelkezik. A bemenettől függően a webes API JSON hasznos adatokat kap az indexelő futtatásakor, és válaszként JSON hasznos adatokat ad ki, valamint egy sikeres állapotkódot. A válasz várhatóan az egyéni képesség által megadott kimenetekkel rendelkezik. A rendszer minden más választ hibának tekint, és nem végez bővítést. A JSON hasznos adatainak struktúráját ebben a dokumentumban részletesebben ismertetjük.

Az Egyéni webes API-készség az Azure OpenAI On Your Data szolgáltatás implementációjában is használatos. Ha az Azure OpenAI szerepköralapú hozzáférésre van konfigurálva, és a vektorindex létrehozásakor hívásokat kap403 Forbidden, ellenőrizze, hogy az Azure AI Search rendelkezik-e rendszer által hozzárendelt identitással, és megbízható szolgáltatásként fut-e az Azure OpenAI-ban.

Feljegyzés

Az indexelő kétszer újrapróbálkozza a webes API-ból visszaadott szabványos HTTP-állapotkódokat. Ezek a HTTP-állapotkódok a következők:

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Képességparaméterek

A paraméterek megkülönböztetik a kis- és nagybetűket.

Paraméter neve	Leírás
`uri`	Annak a webes API-nak az URI-ja, amelyre a JSON hasznos adatokat küldi. Csak a https URI-séma engedélyezett.
`authResourceId`	(Nem kötelező) Egy sztring, amely ha be van állítva, azt jelzi, hogy ennek a képességnek felügyelt identitást kell használnia a kódot futtató függvényhez vagy alkalmazáshoz való kapcsolaton. Ez a tulajdonság az alkalmazás (ügyfél) azonosítóját vagy az alkalmazás Microsoft Entra-azonosítóban való regisztrációját használja támogatott formátumban: `api://<appId>`. Ez az érték az indexelő által lekért hitelesítési jogkivonat hatókörének hatókörére szolgál, és az egyéni webes képességi API-kéréssel együtt elküldi a függvénynek vagy alkalmazásnak. A tulajdonság beállításához a keresési szolgáltatásnak konfigurálnia kell a felügyelt identitást , az Azure-függvényalkalmazás pedig a Microsoft Entra-bejelentkezéshez van konfigurálva. A paraméter használatához hívja meg az API-t a következővel `api-version=2023-10-01-Preview`: .
`httpMethod`	A hasznos adatok küldése során használandó módszer. Az engedélyezett metódusok `PUTPOST`
`httpHeaders`	Kulcs-érték párok gyűjteménye, ahol a kulcsok fejlécneveket, az értékeket pedig a webes API-nak küldött fejlécértékeket és a hasznos adatokat jelölik. A következő fejlécek nem szerepelnek ebben a gyűjteményben: `Accept`, , `Accept-CharsetAccept-Encoding`, `Content-Length`, `Content-Type`, `Cookie`, `HostTEUpgradeVia`.
`timeout`	(Nem kötelező) Ha meg van adva, az API-hívást kezdeményező HTTP-ügyfél időtúllépését jelzi. XSD "dayTimeDuration" értékként kell formázni (az ISO 8601 időtartamérték korlátozott részhalmaza). Például `PT60S` 60 másodpercig. Ha nincs beállítva, a rendszer 30 másodperces alapértelmezett értéket választ. Az időtúllépés legfeljebb 230 másodpercre és legalább 1 másodpercre állítható be.
`batchSize`	(Nem kötelező) Azt jelzi, hogy az API-hívásonként hány "adatrekord" (lásd az alábbi JSON hasznos adatstruktúrát) küldi el. Ha nincs beállítva, a rendszer az 1000 alapértelmezett értéket választja. Javasoljuk, hogy használja ezt a paramétert, hogy megfelelő kompromisszumot érjen el az átviteli sebesség indexelése és az API terhelése között.
`degreeOfParallelism`	(Nem kötelező) Ha meg van adva, az indexelő által a megadott végpontokkal párhuzamosan indított hívások számát jelzi. Ezt az értéket csökkentheti, ha a végpont nyomás alatt meghibásodik, vagy megemelheti, ha a végpont képes kezelni a terhelést. Ha nincs beállítva, a rendszer az alapértelmezett 5 értéket használja. A `degreeOfParallelism` beállítás legfeljebb 10 lehet, de legalább 1 is lehet.

Készségbemenetek

Ehhez a képességhez nincsenek előre definiált bemenetek. A bemenetek bármely meglévő mező vagy a bővítési fa bármely csomópontja, amelyet át szeretne adni az egyéni képességnek.

Képességkimenetek

Ehhez a képességhez nincsenek előre definiált kimenetek. Mindenképpen adjon meg kimeneti mezőleképezést az indexelőben, ha a képesség kimenetét a keresési index egy mezőjébe kell küldeni.

Mintadefiníció

{
  "@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"
    }
  ]
}

Minta bemeneti JSON-struktúra

Ez a JSON-struktúra a webes API-nak küldött hasznos adatokat jelöli. Mindig az alábbi korlátozásokat követi:

A legfelső szintű entitás neve values objektumtömb. Az ilyen objektumok száma legfeljebb a batchSize.
A tömb minden objektuma a values következő:
- Egy recordId egyedi sztringet tartalmazó tulajdonság, amely a rekord azonosítására szolgál.
- JSON-objektumnak data számító tulajdonság. A tulajdonság mezői data a képességdefiníció szakaszában inputs megadott "neveknek" felelnek meg. Ezeknek a mezőknek az értékei ezekből a source mezőkből származnak (amelyek a dokumentum egy mezőjéből vagy esetleg egy másik képességből származhatnak).

{
    "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": []
           }
      }
    ]
}

Minta kimeneti JSON-struktúra

A "kimenet" a webes API-ból visszaadott válasznak felel meg. A webes API-nak csak JSON hasznos adatokat kell visszaadnia (a Content-Type válaszfejlécen ellenőrizve), és meg kell felelnie a következő korlátozásoknak:

Egy legfelső szintű entitásnak valueskell lennie, amelynek objektumtömbnek kell lennie.
A tömbben lévő objektumok számának meg kell egyeznie a webes API-nak küldött objektumok számával.
Minden objektumnak a következőnek kell lennie:
- Egy recordId tulajdonság.
- Egy data tulajdonság, amely egy olyan objektum, amelyben a mezők olyan gazdagítások, amelyek megfelelnek a output "neveknek", és amelynek értékét a gazdagításnak tekintik.
- Egy errors tulajdonság, egy tömb, amely felsorolja az indexelőzmények végrehajtási előzményeihez hozzáadott hibákat. Ez a tulajdonság kötelező, de lehet null értéke.
- Egy warnings tulajdonság, egy tömb, amely felsorolja az indexelőzmények végrehajtási előzményeihez hozzáadott figyelmeztetéseket. Ez a tulajdonság kötelező, de lehet null értéke.
Az objektumok sorrendje a kérelemben values vagy a válaszban nem fontos. A rendszer azonban a recordId korrelációhoz használja, így a válaszban recordIdszereplő olyan rekordokat, amelyek nem részei a Webes API-nak küldött eredeti kérésnek, elvetik.

{
    "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"
              }
            ]
        },
    ]
}

Hibaesetek

Amellett, hogy a webes API nem érhető el, vagy nem sikeres állapotkódokat küld ki, az alábbiak téves eseteknek minősülnek:

Ha a Webes API sikeres állapotkódot ad vissza, de a válasz azt jelzi, hogy nem application/json , akkor a válasz érvénytelennek minősül, és nem történik bővítés.
Ha érvénytelen rekordok (például recordId hiányzó vagy duplikált) vannak a választömbben values , a rendszer nem végez bővítést az érvénytelen rekordok esetében. Az egyéni készségek fejlesztésekor fontos betartani a webes API-készségszerződést. Ebben a példában a Power Skill-adattárban található, a várt szerződést követő példára hivatkozhat.

Ha a webes API nem érhető el, vagy HTTP-hibát ad vissza, a rendszer egy rövid hibaüzenetet ad hozzá a HTTP-hibával kapcsolatos bármely elérhető részlettel az indexelőzményekhez.