Anpassad webb-API-kompetens i en pipeline för Azure AI Search-berikande

Artikel
10/21/2024

Med den anpassade webb-API-färdigheten kan du utöka AI-berikandet genom att anropa en webb-API-slutpunkt som tillhandahåller anpassade åtgärder. På samma sätt som för inbyggda kunskaper har en anpassad webb-API-färdighet indata och utdata. Beroende på indata får webb-API:et en JSON-nyttolast när indexeraren körs och matar ut en JSON-nyttolast som ett svar, tillsammans med en statuskod för lyckad körning. Svaret förväntas ha de utdata som anges av din anpassade färdighet. Andra svar anses vara ett fel och inga berikningar utförs. Strukturen för JSON-nyttolasten beskrivs längre ned i det här dokumentet.

Den anpassade webb-API-färdigheten används också i implementeringen av Azure OpenAI On Your Data-funktionen . Om Azure OpenAI har konfigurerats för rollbaserad åtkomst och du får 403 Forbidden anrop när du skapar vektorindexet kontrollerar du att Azure AI Search har en systemtilldelad identitet och körs som en betrodd tjänst i Azure OpenAI.

Kommentar

Indexeraren försöker igen två gånger för vissa STANDARD HTTP-statuskoder som returneras från webb-API:et. Dessa HTTP-statuskoder är:

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Kompetensparametrar

Parametrar är skiftlägeskänsliga.

Parameternamn	beskrivning
`uri`	URI:n för webb-API:et som JSON-nyttolasten skickas till. Endast https-URI-schemat tillåts.
`authResourceId`	(Valfritt) En sträng som om den anges anger att den här färdigheten ska använda en systemhanterad identitet på anslutningen till den funktion eller app som är värd för koden. Den här egenskapen tar ett program-ID (klient)-ID eller appens registrering i Microsoft Entra-ID i något av följande format: `api://<appId>`, `<appId>/.default`, `api://<appId>/.default`. Det här värdet används för att begränsa den autentiseringstoken som hämtats av indexeraren och skickas tillsammans med den anpassade API-begäran om webbfärdighet till funktionen eller appen. Om du anger den här egenskapen måste din söktjänst konfigureras för hanterad identitet och att azure-funktionsappen har konfigurerats för en Microsoft Entra-inloggning. Om du vill använda den här parametern anropar du API:et med `api-version=2023-10-01-Preview`.
`authIdentity`	(Valfritt) En användarhanterad identitet som används av söktjänsten för att ansluta till funktionen eller appen som är värd för koden. Du kan använda antingen en system- eller användarhanterad identitet. Lämna tom om du vill använda en systemhanterad identitet `authIdentity` .
`httpMethod`	Den metod som ska användas när nyttolasten skickas. Tillåtna metoder är `PUT` eller `POST`
`httpHeaders`	En samling nyckel/värde-par där nycklarna representerar rubriknamn och värden representerar huvudvärden som skickas till webb-API:et tillsammans med nyttolasten. Följande rubriker får inte vara i den här samlingen: , , , , , `Content-Type`, `Cookie`, `Host`, `TE`, , `Upgrade`, . `ViaContent-LengthAccept-EncodingAccept-CharsetAccept`
`timeout`	(Valfritt) När det anges anger du tidsgränsen för http-klienten som gör API-anropet. Det måste formateras som ett XSD-värde "dayTimeDuration" (en begränsad delmängd av ett ISO 8601-varaktighetsvärde ). Till exempel `PT60S` i 60 sekunder. Om det inte anges väljs ett standardvärde på 30 sekunder. Tidsgränsen kan anges till högst 230 sekunder och minst 1 sekund.
`batchSize`	(Valfritt) Anger hur många "dataposter" (se JSON-nyttolaststrukturen nedan) som skickas per API-anrop. Om den inte har angetts väljs standardvärdet 1 000. Vi rekommenderar att du använder den här parametern för att uppnå en lämplig kompromiss mellan indexeringsdataflöde och belastning på ditt API.
`degreeOfParallelism`	(Valfritt) När detta anges anger det antal anrop som indexeraren gör parallellt med den slutpunkt som du anger. Du kan minska det här värdet om slutpunkten misslyckas under tryck eller höja det om slutpunkten kan hantera belastningen. Om det inte anges används standardvärdet 5. `degreeOfParallelism` Kan anges till högst 10 och minst 1.

Kunskapsindata

Det finns inga fördefinierade indata för den här färdigheten. Indata är ett befintligt fält eller en nod i berikande träd som du vill skicka till din anpassade kompetens.

Kunskapsutdata

Det finns inga fördefinierade utdata för den här färdigheten. Se till att definiera en mappning av utdatafält i indexeraren om kunskapens utdata ska skickas till ett fält i sökindexet.

Exempeldefinition

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

Exempel på JSON-struktur för indata

Den här JSON-strukturen representerar nyttolasten som skickas till webb-API:et. Den följer alltid dessa begränsningar:

Entiteten på den översta nivån anropas values och är en matris med objekt. Antalet sådana objekt är som mest batchSize.
Varje objekt i matrisen values har:
- En recordId egenskap som är en unik sträng som används för att identifiera posten.
- En data egenskap som är ett JSON-objekt. Fälten i data egenskapen motsvarar de "namn" som anges i inputs avsnittet i kunskapsdefinitionen. Värdena för dessa fält kommer från fälten source (som kan komma från ett fält i dokumentet eller eventuellt från en annan färdighet).

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

Exempel på JSON-struktur för utdata

"Utdata" motsvarar svaret som returneras från webb-API:et. Webb-API:et bör endast returnera en JSON-nyttolast (verifieras genom att titta på Content-Type svarshuvudet) och bör uppfylla följande begränsningar:

Det bör finnas en entitet på den översta nivån som heter values, som ska vara en matris med objekt.
Antalet objekt i matrisen ska vara detsamma som antalet objekt som skickas till webb-API:et.
Varje objekt ska ha:
- En recordId egenskap.
- En data egenskap, som är ett objekt där fälten är berikningar som matchar "namnen" i output och vars värde anses vara berikningen.
- En errors egenskap, en matris som visar eventuella fel som har lagts till i indexerarens körningshistorik. Den här egenskapen krävs, men kan ha ett null värde.
- En warnings egenskap, en matris som visar eventuella varningar som har lagts till i indexerarens körningshistorik. Den här egenskapen krävs, men kan ha ett null värde.
Ordningen på objekt i values i antingen begäran eller svaret är inte viktigt. recordId Men används för korrelation så att alla poster i svaret som innehåller en recordId, som inte ingick i den ursprungliga begäran till webb-API:et ignoreras.

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

Felfall

Förutom att webb-API:et inte är tillgängligt eller skickar ut statuskoder som inte lyckas betraktas följande som felaktiga fall:

Om webb-API:et returnerar en statuskod för lyckade försök, men svaret anger att det inte application/json är det, anses svaret vara ogiltigt och inga berikningar utförs.
Om det finns ogiltiga poster (till exempel recordId saknas eller dupliceras) i svarsmatrisen values utförs ingen berikning för de ogiltiga posterna. Det är viktigt att följa kunskapskontraktet för webb-API:et när du utvecklar anpassade kunskaper. Du kan se det här exemplet som finns på lagringsplatsen för Power Skill som följer det förväntade kontraktet.

Om webb-API:et inte är tillgängligt eller returnerar ett HTTP-fel läggs ett användarvänligt fel med tillgänglig information om HTTP-felet till i indexerarens körningshistorik.

Dela via