Aangepaste web-API-vaardigheid in een Azure AI Search-verrijkingspijplijn

Artikel
03/06/2024

Met de vaardigheid Aangepaste web-API kunt u AI-verrijking uitbreiden door aan te roepen naar een web-API-eindpunt dat aangepaste bewerkingen biedt. Net als bij ingebouwde vaardigheden heeft een aangepaste web-API-vaardigheid invoer en uitvoer. Afhankelijk van de invoer ontvangt uw web-API een JSON-nettolading wanneer de indexeerfunctie wordt uitgevoerd en wordt een JSON-nettolading uitgevoerd als een antwoord, samen met een geslaagde statuscode. Het antwoord heeft naar verwachting de uitvoer die is opgegeven door uw aangepaste vaardigheid. Elk ander antwoord wordt beschouwd als een fout en er worden geen verrijkingen uitgevoerd. De structuur van de JSON-nettolading wordt verderop in dit document beschreven.

De vaardigheid aangepaste web-API wordt ook gebruikt in de implementatie van de functie Azure OpenAI On Your Data . Als Azure OpenAI is geconfigureerd voor op rollen gebaseerde toegang en u aanroepen krijgt 403 Forbidden bij het maken van de vectorindex, controleert u of Azure AI Search een door het systeem toegewezen identiteit heeft en wordt uitgevoerd als een vertrouwde service in Azure OpenAI.

Notitie

De indexeerfunctie probeert twee keer opnieuw voor bepaalde standaard HTTP-statuscodes die zijn geretourneerd door de web-API. Deze HTTP-statuscodes zijn:

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Vaardigheidsparameters

Parameters zijn hoofdlettergevoelig.

Parameternaam	Beschrijving
`uri`	De URI van de web-API waarnaar de JSON-nettolading wordt verzonden. Alleen het https-URI-schema is toegestaan.
`authResourceId`	(Optioneel) Een tekenreeks die, indien ingesteld, aangeeft dat deze vaardigheid een beheerde identiteit moet gebruiken voor de verbinding met de functie of app die als host fungeert voor de code. Deze eigenschap gebruikt een toepassings-id (client) of app-registratie in Microsoft Entra ID, in een ondersteunde indeling: `api://<appId>` Deze waarde wordt gebruikt om het verificatietoken te bepalen dat is opgehaald door de indexeerfunctie en wordt samen met de aangepaste API-aanvraag voor webvaardigheden verzonden naar de functie of app. Als u deze eigenschap instelt, moet uw zoekservice zijn geconfigureerd voor beheerde identiteit en is uw Azure-functie-app geconfigureerd voor een Microsoft Entra-aanmelding. Als u deze parameter wilt gebruiken, roept u de API aan met `api-version=2023-10-01-Preview`.
`httpMethod`	De methode die moet worden gebruikt tijdens het verzenden van de nettolading. Toegestane methoden zijn `PUT` of `POST`
`httpHeaders`	Een verzameling sleutel-waardeparen waarbij de sleutels headernamen en -waarden vertegenwoordigen headerwaarden die samen met de nettolading naar uw web-API worden verzonden. De volgende headers mogen niet in deze verzameling voorkomen: `Accept`, , `Accept-Charset`, `Accept-Encoding`, `Content-Length`, `Content-TypeCookie`, , `Host`, , `TE`, , `Upgrade`, . `Via`
`timeout`	(Optioneel) Wanneer dit is opgegeven, geeft u de time-out aan voor de HTTP-client die de API-aanroep maakt. Deze moet worden opgemaakt als een XSD-waarde 'dayTimeDuration' (een beperkte subset van een ISO 8601-duurwaarde ). Bijvoorbeeld `PT60S` gedurende 60 seconden. Als dit niet is ingesteld, wordt een standaardwaarde van 30 seconden gekozen. De time-out kan worden ingesteld op maximaal 230 seconden en minimaal 1 seconde.
`batchSize`	(Optioneel) Geeft aan hoeveel 'gegevensrecords' (zie de onderstaande JSON-nettoladingstructuur) per API-aanroep wordt verzonden. Als dit niet is ingesteld, wordt een standaardwaarde van 1000 gekozen. U wordt aangeraden deze parameter te gebruiken om een geschikte afweging te maken tussen de indexeringsdoorvoer en de belasting van uw API.
`degreeOfParallelism`	(Optioneel) Wanneer dit is opgegeven, geeft u het aantal aanroepen aan dat de indexeerfunctie parallel uitvoert met het eindpunt dat u opgeeft. U kunt deze waarde verlagen als uw eindpunt onder druk mislukt of verhoogt als uw eindpunt de belasting kan verwerken. Als dit niet is ingesteld, wordt een standaardwaarde van 5 gebruikt. De `degreeOfParallelism` kan worden ingesteld op maximaal 10 en minimaal 1.

Invoer van vaardigheden

Er zijn geen vooraf gedefinieerde invoerwaarden voor deze vaardigheid. De invoer is een bestaand veld of een knooppunt in de verrijkingsstructuur die u wilt doorgeven aan uw aangepaste vaardigheid.

Uitvoer van vaardigheden

Er zijn geen vooraf gedefinieerde uitvoer voor deze vaardigheid. Zorg ervoor dat u een toewijzing van uitvoervelden in de indexeerfunctie definieert als de uitvoer van de vaardigheid moet worden verzonden naar een veld in de zoekindex.

Voorbeelddefinitie

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

JSON-voorbeeldinvoerstructuur

Deze JSON-structuur vertegenwoordigt de nettolading die naar uw web-API wordt verzonden. Het volgt altijd deze beperkingen:

De entiteit op het hoogste niveau wordt aangeroepen values en is een matrix met objecten. Het aantal van dergelijke objecten is ten hoogste het batchSizeaantal .
Elk object in de values matrix heeft:
- Een recordId eigenschap die een unieke tekenreeks is, die wordt gebruikt om die record te identificeren.
- Een data eigenschap die een JSON-object is. De velden van de data eigenschap komen overeen met de 'namen' die zijn opgegeven in de inputs sectie van de vaardigheidsdefinitie. De waarden van deze velden zijn afkomstig van de source velden (die afkomstig kunnen zijn van een veld in het document of mogelijk van een andere vaardigheid).

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

JSON-voorbeelduitvoerstructuur

De 'uitvoer' komt overeen met het antwoord dat wordt geretourneerd door uw web-API. De web-API mag alleen een JSON-nettolading retourneren (geverifieerd door de Content-Type antwoordheader te bekijken) en moet voldoen aan de volgende beperkingen:

Er moet een entiteit op het hoogste niveau zijn aangeroepen values. Dit moet een matrix van objecten zijn.
Het aantal objecten in de matrix moet hetzelfde zijn als het aantal objecten dat naar de web-API wordt verzonden.
Elk object moet het volgende hebben:
- Een recordId eigenschap.
- Een data eigenschap, een object waarbij de velden verrijkingen zijn die overeenkomen met de 'namen' in de output en waarvan de waarde wordt beschouwd als de verrijking.
- Een errors eigenschap, een matrix met eventuele fouten die zijn opgetreden in de uitvoeringsgeschiedenis van de indexeerfunctie. Deze eigenschap is vereist, maar kan een null waarde hebben.
- Een warnings eigenschap, een matrix met waarschuwingen die zijn aangetroffen in de uitvoeringsgeschiedenis van de indexeerfunctie. Deze eigenschap is vereist, maar kan een null waarde hebben.
De volgorde van objecten in de values aanvraag of het antwoord is niet belangrijk. Het recordId wordt echter gebruikt voor correlatie, zodat alle records in het antwoord met een recordId, die geen deel uitmaakten van de oorspronkelijke aanvraag voor de web-API, worden verwijderd.

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

Foutcases

Naast dat uw web-API niet beschikbaar is of niet-geslaagde statuscodes verzendt, worden de volgende foutieve gevallen beschouwd:

Als de web-API een geslaagde statuscode retourneert, maar het antwoord aangeeft dat het niet application/json is, wordt het antwoord als ongeldig beschouwd en worden er geen verrijkingen uitgevoerd.
Als er ongeldige records zijn (bijvoorbeeld recordId ontbreekt of gedupliceerd) in de antwoordmatrix values , wordt er geen verrijking uitgevoerd voor de ongeldige records. Het is belangrijk om te voldoen aan het web-API-vaardigheidscontract bij het ontwikkelen van aangepaste vaardigheden. U kunt dit voorbeeld raadplegen in de opslagplaats voor Power Skill die volgt op het verwachte contract.

Voor gevallen waarin de web-API niet beschikbaar is of een HTTP-fout retourneert, wordt een beschrijvende fout met alle beschikbare informatie over de HTTP-fout toegevoegd aan de uitvoeringsgeschiedenis van de indexeerfunctie.