Delen via

AML-vaardigheid in een Azure AI Search-verrijkingspijplijn

  • Artikel

Belangrijk

Deze vaardigheid is 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). Zodra een AML-model is getraind en geïmplementeerd, integreert een AML-vaardigheid het in AI-verrijking.

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

De AML-vaardigheid is een preview-functie, maar afhankelijk van het eindpunt kunt u deze aanroepen in een vaardighedenset die is gericht op een stabiele API-versie. Een vaardighedenset die is gemaakt met 2023-11-01 stabiele API kan bijvoorbeeld een AML-vaardigheid bevatten, ook al is het een preview-functie.

Vanaf 2024-05-01-preview REST API en in Azure Portal (die ook gericht is op de 2024-05-01-preview), heeft Azure AI Search de Vectorizer voor modelcatalogus van Azure AI Studio geïntroduceerd voor querytijdverbindingen met de modelcatalogus in Azure AI Studio. Als u deze vectorizer wilt gebruiken voor query's, is de AML-vaardigheid de indexerende tegenhanger voor het genereren van insluitingen met behulp van een model in de Azure AI Studio-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 Hoe u geïntegreerde vectorisatie implementeert met behulp van modellen uit Azure AI Studio voor meer informatie over deze werkstroom.

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

Vereisten

@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.
key (Vereist voor sleutelverificatie) De sleutel voor het online-eindpunt van AML.
resourceId (Vereist voor tokenverificatie). De resource-id van Azure Resource Manager van het online-eindpunt van AML. Dit moet de indeling van abonnementen/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name} hebben.
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.

Welke vaardigheidsparameters moeten worden gebruikt

Welke AML-vaardigheidsparameters vereist zijn, is afhankelijk van welke verificatie uw online-eindpunt van AML gebruikt, indien van toepassing. 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
    • De URI- en sleutelparameters gebruiken
  • Verificatie op basis van tokens. 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. 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. Aan de identiteit moet de rol eigenaar of inzender zijn toegewezen.
    • Gebruik de parameter resourceId .
    • Als de zoekservice zich in een andere regio bevindt dan de AML-werkruimte, gebruikt u de regioparameter om de regio in te stellen waarin het online-eindpunt van AML is geïmplementeerd

Invoer van vaardigheden

Er zijn geen vooraf gedefinieerde invoerwaarden voor deze vaardigheid. U kunt een of meer velden kiezen die al beschikbaar zijn op het moment van de uitvoering van deze vaardigheid als invoer en de JSON-nettolading die naar het online-eindpunt van AML wordt verzonden, verschillende velden heeft.

Uitvoer van vaardigheden

Er zijn geen 'vooraf gedefinieerde' uitvoer voor deze vaardigheid. Afhankelijk van het antwoord dat het online-eindpunt van AML retourneert, voegt u uitvoervelden toe, zodat deze kunnen worden opgehaald uit het JSON-antwoord .

Voorbeelddefinitie

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.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://contoso.count-things.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:

  • Als het online-eindpunt van AML een successtatuscode retourneert, maar het antwoord aangeeft dat dit niet application/jsonhet is, wordt het antwoord als ongeldig beschouwd en worden er geen verrijkingen uitgevoerd.
  • Als het online-eindpunt van AML ongeldige json retourneert

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

Zie ook