AML-vaardigheid in een Azure AI Search-verrijkingspijplijn

Artikel
12/18/2024

Belangrijk

Ondersteuning voor indexeerfunctiesverbindingen met de Azure AI Foundry-modelcatalogus bevindt zich in openbare preview onder aanvullende gebruiksvoorwaarden. Preview-REST API's ondersteunen deze vaardigheid.

Met de AML-vaardigheid kunt u AI-verrijking uitbreiden met een aangepast AML-model (Azure Machine Learning) of een geïmplementeerd basis insluitmodel in Azure AI Foundry. Zodra een AML-model is getraind en geïmplementeerd, integreert een AML-vaardigheid het in een vaardighedenset.

Gebruik van AML-vaardigheden

Net als bij andere ingebouwde vaardigheden heeft een aangepaste AML-vaardigheid invoer en uitvoer. De invoer wordt verzonden naar een geïmplementeerd online AML-eindpunt als een JSON-object. De uitvoer van het eindpunt moet een JSON-nettolading in het antwoord zijn, samen met een geslaagde statuscode. Uw gegevens worden verwerkt in de geografische locatie waar uw model wordt geïmplementeerd. Het antwoord zal naar verwachting de uitvoer leveren die is opgegeven door de definitie van uw AML-vaardigheid . Elk ander antwoord wordt beschouwd als een fout en er worden geen verrijkingen uitgevoerd.

Notitie

De indexeerfunctie probeert het opnieuw voor bepaalde standaard HTTP-statuscodes die worden geretourneerd door het online-eindpunt van AML. Deze HTTP-statuscodes zijn:

503 Service Unavailable
429 Too Many Requests

De AML-vaardigheid kan worden aangeroepen met de stabiele API-versie 2024-07-01 of een equivalente Azure SDK, of de API-versie 2024-05-01-preview voor verbindingen met de modelcatalogus in de Azure AI Foundry-portal.

AML-vaardigheid voor modellen in Azure AI Foundry

Vanaf 2024-05-01-preview REST API en in Azure Portal (die ook gericht is op de 2024-05-01-preview), biedt Azure AI Search de Azure AI Foundry-modelcatalogusvectorfunctie voor querytijdverbindingen met de modelcatalogus in Azure AI Foundry Portal. Als u deze vectorizer wilt gebruiken voor query's, is een AML-vaardigheid de indexerende tegenhanger voor het genereren van insluitingen met behulp van een model in de Azure AI Foundry-modelcatalogus.

Tijdens het indexeren kan de AML-vaardigheid verbinding maken met de modelcatalogus om vectoren voor de index te genereren. Tijdens query's kunnen query's een vectorizer gebruiken om verbinding te maken met hetzelfde model om tekenreeksen voor een vectorquery te vectoriseren. In deze werkstroom moeten de AML-vaardigheid en de vectorizer voor modelcatalogus samen worden gebruikt, zodat u hetzelfde insluitingsmodel gebruikt voor zowel indexering als query's. Zie Insluitmodellen gebruiken uit de azure AI Foundry-modelcatalogus voor meer informatie en voor een lijst met de ondersteunde insluitingsmodellen.

U wordt aangeraden de wizard Gegevens importeren en vectoriseren te gebruiken om een vaardighedenset te genereren die een AML-vaardigheid bevat voor geïmplementeerde insluitingsmodellen in Azure AI Foundry. De AML-vaardigheidsdefinitie voor invoer, uitvoer en toewijzingen wordt gegenereerd door de wizard, waarmee u een model eenvoudig kunt testen voordat u code schrijft.

Vereisten

Een AML-werkruimte voor een aangepast model dat u maakt of een project in Azure AI Foundry als een insluitmodel wordt geïmplementeerd vanuit de catalogus.
Een online-eindpunt (realtime) in deze werkruimte voor een aangepast model of het modeleindpunt voor het insluiten van modellen die zijn geïmplementeerd vanuit de catalogus.

@odata.type

Microsoft.Skills.Custom.AmlSkill

Vaardigheidsparameters

Parameters zijn hoofdlettergevoelig. Welke parameters u wilt gebruiken, is afhankelijk van de verificatie die uw online-eindpunt van AML vereist, indien van toepassing

Parameternaam	Beschrijving
`uri`	(Vereist voor sleutelverificatie) De score-URI van het online-AML-eindpunt waarnaar de JSON-nettolading wordt verzonden. Alleen het https-URI-schema is toegestaan. Voor het insluiten van modellen in de Azure AI Foundry-modelcatalogus is dit de doel-URI.
`key`	(Vereist voor sleutelverificatie) De sleutel voor het online AML-eindpunt of het
`resourceId`	(Vereist voor tokenverificatie). De resource-id van Azure Resource Manager van het online-eindpunt van AML. Gebruik hierbij de notatie `subscriptions/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name}`.
`region`	(Optioneel voor tokenverificatie). De regio waarin het online-eindpunt van AML is geïmplementeerd.
`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.
`degreeOfParallelism`	(Optioneel) Wanneer dit is opgegeven, geeft u het aantal aanroepen aan dat de indexeerfunctie parallel uitvoert met het eindpunt dat u hebt opgegeven. U kunt deze waarde verlagen als uw eindpunt onder te hoge belasting van een aanvraag mislukt. U kunt het verhogen als uw eindpunt meer aanvragen kan accepteren en u een toename van de prestaties van de indexeerfunctie wilt. Als dit niet is ingesteld, wordt een standaardwaarde van 5 gebruikt. Het degreeOfParallelism kan worden ingesteld op maximaal 10 en minimaal 1.

Verificatie

Online AML-eindpunten bieden twee verificatieopties:

Verificatie op basis van sleutels. Er wordt een statische sleutel verstrekt voor het verifiëren van scoreaanvragen van AML-vaardigheden. Stel de uri en key parameters voor deze verbinding in.
Verificatie op basis van tokens, waarbij het online-eindpunt van AML wordt geïmplementeerd met behulp van verificatie op basis van tokens. De beheerde identiteit van de Azure AI-Search-service moet zijn ingeschakeld en een roltoewijzing hebben voor de werkruimte. De AML-vaardigheid gebruikt vervolgens de beheerde identiteit van de service om te verifiëren bij het online-eindpunt van AML, zonder dat statische sleutels vereist zijn. De identiteit van de zoekservice moet een eigenaar of inzender zijn. Stel de resourceId parameter in en als de zoekservice zich in een andere regio bevindt dan de AML-werkruimte, stelt u de region parameter in.

Invoer van vaardigheden

Invoer van vaardigheden is een knooppunt van het verrijkte document dat wordt gemaakt tijdens het kraken van het document. Dit kan bijvoorbeeld het hoofddocument, een genormaliseerde afbeelding of de inhoud van een blob zijn. Er zijn geen vooraf gedefinieerde invoerwaarden voor deze vaardigheid. Voor invoer moet u een of meer knooppunten opgeven die zijn ingevuld op het moment dat de AML-vaardigheid wordt uitgevoerd.

Uitvoer van vaardigheden

Uitvoer van vaardigheden zijn nieuwe knooppunten van een verrijkt document dat door de vaardigheid is gemaakt. Er zijn geen vooraf gedefinieerde uitvoer voor deze vaardigheid. Voor uitvoer moet u knooppunten opgeven die kunnen worden ingevuld vanuit het JSON-antwoord van uw AML-vaardigheid.

Voorbeelddefinitie

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A custom model that detects the language in a document.",
    "uri": "https://language-model.models.contoso.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

JSON-voorbeeldinvoerstructuur

Deze JSON-structuur vertegenwoordigt de nettolading die naar uw online AML-eindpunt wordt verzonden. De velden op het hoogste niveau van de structuur 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)

{
  "text": "Este es un contrato en Inglés"
}

JSON-voorbeelduitvoerstructuur

De uitvoer komt overeen met het antwoord dat is geretourneerd door uw online-eindpunt van AML. Het online-eindpunt van AML mag alleen een JSON-nettolading retourneren (geverifieerd door naar de Content-Type antwoordheader te kijken) en moet een object zijn waarin de velden verrijkingen zijn die overeenkomen met de 'namen' in de output en waarvan de waarde wordt beschouwd als de verrijking.

{
    "detected_language_code": "es"
}

Definitie van inline-vormgevingsvoorbeeld

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://language-model.models.contoso.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "shapedText",
        "sourceContext": "/document",
        "inputs": [
            {
              "name": "content",
              "source": "/document/content"
            }
        ]
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

JSON-structuur voor inline-vormgeving

{
  "shapedText": { "content": "Este es un contrato en Inglés" }
}

JSON-structuur van voorbeelduitvoer inline vormgeven

{
    "detected_language_code": "es"
}

Foutcases

Naast dat uw AML niet beschikbaar is of niet-geslaagde statuscodes verzendt, worden het volgende beschouwd als onjuiste gevallen:

Het online AML-eindpunt retourneert een geslaagde statuscode, maar het antwoord geeft aan dat dit niet application/jsonhet is, het antwoord wordt als ongeldig beschouwd en er worden geen verrijkingen uitgevoerd.
Het online-eindpunt van AML retourneert ongeldige JSON.

Voor gevallen waarin het online-eindpunt van AML 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.

Delen via