Egyéni webes API-képesség az Azure AI Search bővítési folyamatában
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 PUT POST |
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-Charset Accept-Encoding , Content-Length , Content-Type , Cookie , Host TE Upgrade Via . |
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 abatchSize
.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őidata
a képességdefiníció szakaszábaninputs
megadott "neveknek" felelnek meg. Ezeknek a mezőknek az értékei ezekből asource
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
values
kell 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 aoutput
"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 lehetnull
é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 lehetnull
értéke.
Az objektumok sorrendje a kérelemben
values
vagy a válaszban nem fontos. A rendszer azonban arecordId
korrelációhoz használja, így a válaszbanrecordId
szereplő 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ömbbenvalues
, 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.