Een aangepaste vaardigheid toevoegen aan een Azure AI Zoeken verrijkingspijplijn

Een AI-verrijkingspijplijn kan zowel ingebouwde vaardigheden als aangepaste vaardigheden bevatten die u maakt en publiceert. Uw aangepaste code wordt uitgevoerd buiten de zoekservice (bijvoorbeeld als een Azure functie), maar accepteert invoer en verzendt uitvoer naar de vaardighedenset, net zoals elke andere vaardigheid. Uw gegevens worden verwerkt in de geography waar uw model wordt geïmplementeerd.

Aangepaste vaardigheden kunnen complex klinken, maar ze kunnen eenvoudig te implementeren zijn. Als u bestaande pakketten hebt die patroonkoppelings- of classificatiemodellen bieden, kunt u inhoud die uit blobs is geëxtraheerd, doorgeven aan die modellen voor verwerking. Omdat AI-verrijking op Azure is gebaseerd, moet u uw model ook op Azure hosten. Algemene hostingopties zijn 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 de vaardighedenset als geheel kan gebruiken. 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 voor een stapsgewijs voorbeeld Voorbeeld: Een aangepaste vaardigheid voor AI-verrijking maken.

Het eindpunt en time-outinterval instellen

Specificeer de interface voor een aangepaste vaardigheid via de Aangepaste Web API-vaardigheid.

"@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 u uw code host in een Azure functie-app, neemt u een API-sleutel op in de header of als een URI-parameter in de URI om de aanvraag te autoriseren.

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

• De zoekservice, die de aanvraag namens de indexeerfunctie verzendt, moet worden geconfigureerd voor het gebruik van een beheerde identiteit (systeem of door de gebruiker toegewezen), zodat Microsoft Entra ID de aanroeper kan verifiëren.

• U moet uw functie of app configureren voor Microsoft Entra ID.

• Uw aangepaste vaardigheidsdefinitie moet een authResourceId eigenschap bevatten. Deze eigenschap gebruikt een toepassings-id (client) in een supported format: api://<appId>.

Zorg ervoor dat deze verwijst naar het eindpunt van de toepassing die uri is geïdentificeerd door authResourceId. Niet-overeenkomende waarden kunnen leiden tot verificatiefouten of aanvragen die naar een onbedoeld eindpunt worden verzonden. Zie Beveiligingsoverwegingen voor verificatie van beheerde identiteiten voor beveiligingsrichtlijnen, aanbevolen procedures en stappen om uw configuratie te controleren.

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 produceert een time-outfout als er in dat tijdsbestek geen antwoord wordt ontvangen. U kunt het interval verhogen naar een maximumwaarde van 230 seconden door de timeout parameter (PT230S) in te stellen.

Als een eindpunt dat wordt beveiligd door IP-toegangsbeperkingen niet reageert, tijdelijk ingesteld timeout op een korte waarde, zoals PT10S, om de time-outfout sneller weer te geven. Voor een Azure functie-app beheert u binnenkomende IP-regels onder Beperkingen>>. Zie IP-firewallregels configureren om indexeerverbindingen toe te staan voor de IP-adressen die moeten worden toegestaan.

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 contracttekst. In dit voorbeeld accepteert de aangepaste vaardigheid één invoer. contractText De vaardigheid heeft ook één uitvoer, de contractdatum. Maak de verrijker interessanter door contractDate te retourneren in de vorm van een samengesteld complex type.

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

• Een recordId member die de unieke identificatie voor een bepaald record vormt. Wanneer uw verrijker resultaten retourneert, moet dit recordId worden opgegeven, zodat de aanroeper de recordresultaten aan invoer kan koppelen.

• Een data onderdeel, een verzameling invoervelden voor elk record.

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

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issued 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 uitvoerindeling is een set records met een recordId en een eigenschappentas. Dit specifieke voorbeeld heeft slechts één uitvoer, maar u kunt meer dan één eigenschap retourneren. Als beste praktijk kunt u overwegen fout- en waarschuwingsberichten terug te geven wanneer 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 definiëren 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. Zie de volgende bronnen voor meer informatie over aangepaste vaardigheden en vaardighedensetsamenstelling:

• Power Skills: een opslagplaats met aangepaste vaardigheden
• Voorbeeld: Een aangepaste vaardigheid maken voor AI-verrijking
• Een vaardighedenset definiëren
• Skillset maken (REST)
• Hoe je verrijkte velden toewijst