Een aangepaste vaardigheid toevoegen aan een Azure AI Search-verrijkingspijplijn

  • Artikel

Een AI-verrijkingspijplijn kan zowel ingebouwde vaardigheden als aangepaste vaardigheden bevatten die u persoonlijk maakt en publiceert. Uw aangepaste code wordt extern uitgevoerd vanuit de zoekservice (bijvoorbeeld als een Azure-functie), maar accepteert invoer en verzendt uitvoer naar de vaardighedenset, net zoals elke andere vaardigheid.

Aangepaste vaardigheden kunnen complex klinken, maar kunnen eenvoudig en eenvoudig zijn in termen van implementatie. Als u bestaande pakketten hebt die patroonkoppelings- of classificatiemodellen bieden, kan de inhoud die u uit blobs extraheert, worden doorgegeven aan deze modellen voor verwerking. Omdat AI-verrijking is gebaseerd op Azure, moet uw model zich ook in Azure bevindt. Enkele algemene hostingmethoden zijn onder andere het gebruik van Azure Functions of Containers.

Als u een aangepaste vaardigheid bouwt, wordt in dit artikel de interface beschreven die u gebruikt om de vaardigheid in de pijplijn te integreren. De primaire vereiste is de mogelijkheid om invoer te accepteren en uitvoer te verzenden op manieren die in de vaardighedenset als geheel kunnen worden gebruikt. Daarom is de focus van dit artikel op de invoer- en uitvoerindelingen die nodig zijn voor de verrijkingspijplijn.

Voordelen van aangepaste vaardigheden

Door een aangepaste vaardigheid te bouwen, kunt u transformaties invoegen die uniek zijn voor uw inhoud. U kunt bijvoorbeeld aangepaste classificatiemodellen bouwen om zakelijke en financiële contracten en documenten te onderscheiden, of een vaardigheid voor spraakherkenning toevoegen om beter in audiobestanden naar relevante inhoud te kunnen zoeken. Zie voorbeeld: Een aangepaste vaardigheid voor AI-verrijking maken voor stapsgewijze voorbeelden.

Het eindpunt en time-outinterval instellen

De interface voor een aangepaste vaardigheid wordt opgegeven via de vaardigheid Aangepaste web-API.

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230 second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

De URI is het HTTPS-eindpunt van uw functie of app. Zorg er bij het instellen van de URI voor dat de URI veilig is (HTTPS). Als uw code wordt gehost in een Azure-functie-app, moet de URI een API-sleutel in de header of als een URI-parameter bevatten om de aanvraag te autoriseren.

Als uw functie of app in plaats daarvan gebruikmaakt van door Azure beheerde identiteiten en Azure-rollen voor verificatie en autorisatie, kan de aangepaste vaardigheid een verificatietoken op de aanvraag bevatten. In de volgende punten worden de vereisten voor deze aanpak beschreven:

Er treedt standaard een time-out op voor de verbinding met het eindpunt als een antwoord niet binnen een venster van 30 seconden (PT30S) wordt geretourneerd. De indexeringspijplijn is synchroon en indexering veroorzaakt een time-outfout als er in die periode geen antwoord wordt ontvangen. U kunt het interval verhogen naar een maximumwaarde van 230 seconden door de time-outparameter (PT230S) in te stellen.

Web-API-invoer opmaken

De web-API moet een matrix met records accepteren die moeten worden verwerkt. Geef binnen elke record een eigenschappentas op als invoer voor uw web-API.

Stel dat u een eenvoudige verrijker wilt maken die de eerste datum identificeert die wordt vermeld in de tekst van een contract. In dit voorbeeld accepteert de aangepaste vaardigheid één invoer 'contractText' als de contracttekst. De vaardigheid heeft ook één uitvoer, de datum van het contract. Als u de verrijker interessanter wilt maken, retourneert u deze "contractDate" in de vorm van een complex type met meerdere onderdelen.

Uw web-API moet gereed zijn om een batch invoerrecords te ontvangen. Elk lid van de matrix 'waarden' vertegenwoordigt de invoer voor een bepaalde record. Elke record is vereist om de volgende elementen te hebben:

  • Een recordId-lid dat de unieke id voor een bepaalde record is. Wanneer uw verrijker de resultaten retourneert, moet deze 'recordId' worden opgegeven om de aanroeper toe te staan de recordresultaten aan hun invoer te koppelen.

  • Een 'data'-lid, dat in feite een zak invoervelden is voor elke record.

De resulterende web-API-aanvraag kan er als volgt uitzien:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issues on November 3, 2023 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

In de praktijk kan uw code worden aangeroepen met honderden of duizenden records in plaats van alleen de drie die hier worden weergegeven.

Web-API-uitvoer opmaken

De indeling van de uitvoer is een set records die een 'recordId' en een eigenschapsverzameling bevatten. Dit specifieke voorbeeld heeft slechts één uitvoer, maar u kunt meer dan één eigenschap uitvoeren. U kunt het beste fouten en waarschuwingsberichten retourneren als een record niet kan worden verwerkt.

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2023 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

Een aangepaste vaardigheid toevoegen aan een vaardighedenset

Wanneer u een web-API-verrijker maakt, kunt u HTTP-headers en -parameters beschrijven als onderdeel van de aanvraag. In het volgende codefragment ziet u hoe aanvraagparameters en optionele HTTP-headers kunnen worden opgenomen in de definitie van de vaardighedenset. Het instellen van een HTTP-header is handig als u configuratie-instellingen aan uw code moet doorgeven.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

Bekijk deze video

Bekijk de volgende demo voor een video-inleiding en demo.

Volgende stappen

Dit artikel heeft betrekking op de interfacevereisten die nodig zijn voor het integreren van een aangepaste vaardigheid in een vaardighedenset. Ga verder met deze koppelingen voor meer informatie over aangepaste vaardigheden en samenstelling van vaardighedensets.