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

Az Egyéni webes API-képesség használatával bővítheti az AI-bővítést egy egyéni műveleteket biztosító webes API-végpont meghívásával. 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 egy JSON hasznos adatot ad vissza a sikerességi állapotkóddal együtt. A válasznak tartalmaznia kell az egyéni képesség által megadott kimeneteket. A rendszer minden más választ hibának tekint, és nem végez bővítést. A JSON hasznos adatok struktúráját a dokumentum későbbi részében ismertetjük.

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

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Képességparaméterek

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

Az authResourceId érték értelmezése

Ha egy egyéni webes API-képesség felügyelt identitáshitelesítést használ, Azure AI Keresés beszerez egy Microsoft Entra hozzáférési jogkivonatot, és elküldi azt az egyéni képességvégpontnak. A authResourceId tulajdonság megadja az erőforrás-azonosítót, más néven a célközönséget vagy az alkalmazásazonosító URI-t, amelyhez a jogkivonatot kérik. Az értéknek meg kell egyeznie azzal, amit a célalkalmazás elvár a jogkivonat érvényesítése során. Ellenkező esetben a hitelesítés válaszsal 401 Unauthorized meghiúsul.

Az authResourceId érték azonosítja az egyéni készséget üzemeltető alkalmazást. Nem a keresési szolgáltatás vagy az indexelő URL-címe.

Az alábbi táblázat a gyakori formátumokat mutatja be:

A tulajdonság a hatókör utótaggal és anélkül is elfogadja a .default formátumokat. Az alkalmazásazonosító URI-jának közvetlen egyeztetésére szolgál api://<appId> . Ha például .defaultutótagot api://<appId>/.default is tartalmaz, a hozzáférési jogkivonat jogcíme aud az alapalkalmazás-azonosító URI-t tartalmazza az utótag nélkül.

Az Azure függvény Microsoft Entra hitelesítésének konfigurálásához és beállításához authResourceIdlásd: A keresési szolgáltatás által felügyelt identitás használata Azure függvényalkalmazáshoz való csatlakozáshoz.

Példa: Azure Microsoft Entra ID által védett függvény

Ebben a példában Azure AI Keresés beszerez egy hozzáférési jogkivonatot a célközönség számára, amelyet authResourceId az egyéni képességvégpont meghívásakor a jogkivonat is tartalmaz.

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

Készségbemenetek

Ez a képesség nem rendelkezik előre definiált bemenetekkel. 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

Ez a képesség nem rendelkezik előre definiált kimenetekkel. 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"
    }
  ]
}

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

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. Ezeknek az objektumoknak a száma legfeljebb a batchSize.

• A tömb minden objektuma a values következő:

  • Egy recordIdegyedi sztringet tartalmazó tulajdonság, amely a rekord azonosítására szolgál.

  • JSON-objektumnak data minősülő 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 leírása

Amellett, hogy a webes API nem érhető el, vagy nem sikeres állapotkódokat küld, vegye figyelembe a következő eseteket:

• Ha a webes API sikeres állapotkódot ad vissza, de a válasz azt jelzi, hogy nem application/json, a válasz érvénytelen, és nem történik bővítés.

• Ha a választömb values érvénytelen rekordokat tartalmaz (például hiányzó vagy duplikált recordId), az érvénytelen rekordok nem lesznek gazdagítva. Egyéni készségek fejlesztésekor tartsa be 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, az indexelőzmények rövid hibát tartalmaznak a HTTP-hibával kapcsolatos esetleges részletekkel.

A felügyelt identitás hitelesítésének biztonsági szempontjai

Ha egyéni webes API-képességgel rendelkező felügyelt identitáshitelesítést használ, Azure AI Keresés lekér egy Microsoft Entra hozzáférési jogkivonatot az általa azonosított authResourceId alkalmazáshoz, és a jogkivonatot a megadott urivégpontra küldött kérelmekben is tartalmazza. A hivatkozott uri végpont általában a Azure függvény, Azure App Service, Azure API Management végpont vagy egy másik Microsoft Entra által védett alkalmazás. Ön felel a végpont és az általa azonosított alkalmazás közötti kapcsolat konfigurálásáért és fenntartásáért authResourceId.

A hitelesítési módszertől függetlenül az egyéni készségbemenetek tartalmazhatnak az ügyfél által megadott dokumentumokból vagy ezekből a dokumentumokból származó értékeket. Az összes egyéni készségbemenetet ne megbízhatóként kezelje. Azure AI Keresés továbbítja a képességkészletben konfigurált bemeneteket a végpontnak anélkül, hogy értelmezi, érvényesíti vagy korlátozza az egyéni megvalósításhoz szükséges tartalmakat.

Ellenőrizze és korlátozza a dokumentumból származtatott értékeket az egyéni képességében, mielőtt kimenő kérésekben vagy más biztonsági szempontból érzékeny műveletekben használva használnák őket. Használjon bemeneti érvényesítést, célengedélylistákat, URL-címet és állomásnév-ellenőrzést, protokollkorlátozásokat és minimális jogosultságú hálózati hozzáférést, amely csak azokat a célhelyeket és portokat teszi lehetővé, amelyekre a képességnek szüksége van. További információ: Architektúrastratégiák a hálózatkezeléshez és a kapcsolatokhoz.

Ajánlott biztonsági eljárások

A biztonságos üzembe helyezés fenntartásához kövesse az alábbi eljárásokat:

• Konfigurálja úgy a uri tulajdonságot, hogy csak olyan megbízható végpontokra mutasson, amelyek a Azure AI Keresés kéréseinek fogadására szolgálnak.
• Konfigurálja authResourceId annak a Microsoft Entra alkalmazásnak a azonosítására, amely várhatóan megkapja és érvényesíti a hozzáférési jogkivonatot.
• A kérések feldolgozása előtt győződjön meg arról, hogy a kéréseket fogadó alkalmazás érvényesíti a szabványos jogkivonat-jogcímeket, beleértve a célközönséget (aud), a kiállítót (iss), a bérlőt (tid), valamint a szükséges alkalmazásszerepköröket vagy engedélyeket.
• Alkalmazza a minimális jogosultság elvét, amikor engedélyeket ad a Azure AI Keresés felügyelt identitásnak.
• Rendszeresen tekintse át az egyéni webes API-képességdefiníciókat, Microsoft Entra alkalmazásregisztrációkat, valamint Azure AI Keresés felügyelt identitások számára biztosított alkalmazásszerepkör-hozzárendeléseket és engedélyeket. Tekintse át a konfigurációs módosításokat a már létrehozott változáskezelési és biztonsági felülvizsgálati folyamatokkal.
• Rendszeresen tekintse át Azure Functions, App Services, API-k és API-átjárók végpontkonfigurációit.
• Az alkalmazás bejelentkezési naplóinak, hitelesítési eseményeinek és API-hozzáférési naplóinak monitorozása váratlan vagy jogosulatlan tevékenységek esetén.
• Távolítsa el a már nem használt végpontokat, engedélyeket, alkalmazásregisztrációkat és szerepkör-hozzárendeléseket.

A képességkészlet-konfigurációhoz való hozzáférés korlátozása

Azok a felhasználók, akik képességkészleteket hozhatnak létre, módosíthatnak vagy futtathatnak, vezérelhetik a célvégpontot és az egyéni webes API-képesség által használt hitelesítési konfigurációt is. Korlátozza ezeket az engedélyeket megbízható rendszergazdákra, és kövesse a szabványos változáskezelési és biztonsági felülvizsgálati folyamatokat a felügyelt identitásbarát egyéni képességek konfigurálásakor.

Lásd még

• Képességkészlet definiálása
• Egyéni képesség hozzáadása AI-bővítési folyamathoz
• Példa: Egyéni képesség létrehozása a mi-bővítéshez
• Power Skill-adattár