AML-Skill in einer Anreicherungspipeline von Azure AI Search

Artikel
12/18/2024

Wichtig

Die Unterstützung für Indexerverbindungen mit dem Azure AI Foundry-Modellkatalog befindet sich in der öffentlichen Vorschau unter zusätzlichen Nutzungsbedingungen. Vorschau-REST-APIs unterstützen diese Fähigkeit.

Mit der AML-Fähigkeit können Sie die KI-Anreicherung mit einem benutzerdefinierten AmL-Modell (Azure Machine Learning) erweitern oder das Basiseinbettungsmodell auf Azure AI Foundry bereitstellen. Sobald ein AML-Modell trainiert und bereitgestellt wird, wird es durch eine AML-Fähigkeit in ein Skillset integriert.

AML-Qualifikationsnutzung

Wie andere integrierte Fähigkeiten verfügt eine benutzerdefinierte AML-Fähigkeit über Eingaben und Ausgaben. Die Eingaben werden als JSON-Objekt an einen bereitgestellten AML-Onlineendpunkt gesendet. Die Ausgabe des Endpunkts muss eine JSON-Nutzlast in der Antwort sein, zusammen mit einem Erfolgsstatuscode. Ihre Daten werden im geografischen Raum verarbeitet, in dem Ihr Modell bereitgestellt wird. Die Antwort wird erwartet, dass die ausgaben bereitgestellt werden, die durch Ihre AML-Qualifikationsdefinition angegeben sind. Jede andere Antwort gilt als Fehler und es werden keine Anreicherung durchgeführt.

Hinweis

Der Indexer versucht zwei Mal, bestimmte Standard-HTTP-Statuscodes, die vom AML-Onlineendpunkt zurückgegeben werden, erneut zu ermitteln. Diese HTTP-Statuscodes lauten:

503 Service Unavailable
429 Too Many Requests

Die AML-Fähigkeit kann mit der stabilen API-Version 2024-07-01 oder dem entsprechenden Azure SDK oder der 2024-05-01-Preview-API-Version für Verbindungen mit dem Modellkatalog im Azure AI Foundry-Portal aufgerufen werden.

AML-Fähigkeit für Modelle in Azure AI Foundry

Ab 2024-05-01-Preview-REST-API und in der Azure-Portal (die auch auf die Vorschau von 2024-05-01 ausgerichtet ist), stellt Azure AI Search den Azure AI Foundry-Modellkatalog-Katalogvektorizer für Abfragezeitverbindungen zum Modellkatalog im Azure AI Foundry-Portal bereit. Wenn Sie diesen Vektorizer für Abfragen verwenden möchten, ist eine AML-Fähigkeit das Indizierungs-Gegenstück zum Generieren von Einbettungen mithilfe eines Modells im Azure AI Foundry-Modellkatalog.

Während der Indizierung kann die AML-Fähigkeit eine Verbindung mit dem Modellkatalog herstellen, um Vektoren für den Index zu generieren. Abfragen können zur Abfragezeit einen Vektorizer verwenden, um eine Verbindung mit demselben Modell herzustellen, um Textzeichenfolgen für eine Vektorabfrage zu vektorisieren. In diesem Workflow sollten die AML-Kenntnisse und der Modellkatalogvektorizer zusammen verwendet werden, damit Sie dasselbe Einbettungsmodell sowohl für die Indizierung als auch für Abfragen verwenden. Ausführliche Informationen und eine Liste der unterstützten Einbettungsmodelle finden Sie unter Verwenden von Einbettungsmodellen aus dem Azure AI Foundry-Modellkatalog.

Wir empfehlen die Verwendung des Assistenten zum Importieren und Vektorisieren von Daten , um ein Skillset zu generieren, das eine AML-Fähigkeit für bereitgestellte Einbettungsmodelle in Azure AI Foundry enthält. Die AML-Qualifikationsdefinition für Eingaben, Ausgaben und Zuordnungen wird vom Assistenten generiert, wodurch Sie ein Modell einfach testen können, bevor Sie Code schreiben.

Voraussetzungen

Ein AML-Arbeitsbereich für ein benutzerdefiniertes Modell, das Sie erstellen, oder ein Projekt in Azure AI Foundry, wenn ein Einbettungsmodell aus dem Katalog bereitgestellt wird.
Ein Onlineendpunkt (Echtzeit) in diesem Arbeitsbereich für ein benutzerdefiniertes Modell oder der Modellendpunkt zum Einbetten von Modellen, die aus dem Katalog bereitgestellt werden.

@odata.type

Microsoft.Skills.Custom.AmlSkill

Skillparameter

Bei den Parametern wird zwischen Groß- und Kleinschreibung unterschieden. Welche Parameter Sie verwenden, hängt davon ab, welche Authentifizierung der AML-Onlineendpunkt ggf. erfordert

Parametername	Beschreibung
`uri`	(Erforderlich für die Schlüsselauthentifizierung) Der Bewertungs-URI des AML-Onlineendpunkts, an den die JSON-Nutzlast gesendet wird. Nur das HTTPS-URI-Schema ist zulässig. Für das Einbetten von Modellen im Azure AI Foundry-Modellkatalog ist dies der Ziel-URI.
`key`	(Erforderlich für die Schlüsselauthentifizierung) Der Schlüssel für den AML-Onlineendpunkt oder den
`resourceId`	(Erforderlich für Tokenauthentifizierung). Die Azure Resource Manager-Ressourcen-ID des AML-Onlinenendpunkts. Sie sollte folgendes Format aufweisen: `subscriptions/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name}`.
`region`	(Optional für Tokenauthentifizierung). Die Region, in der der AML-Onlineendpunkt bereitgestellt wird.
`timeout`	(Optional) Wenn angegeben, wird damit das Zeitlimit für den HTTP-Client angegeben, der den API-Aufruf durchführt. Es muss als XSD-Wert „dayTimeDuration“ formatiert sein (eine eingeschränkte Teilmenge eines ISO 8601-Zeitwerts). Zum Beispiel `PT60S` für 60 Sekunden. Wenn kein Wert festgelegt ist, wird ein Standardwert von 30 Sekunden ausgewählt. Das Zeitlimit kann auf maximal 230 Sekunden und mindestens 1 Sekunde festgelegt werden.
`degreeOfParallelism`	(Optional) Wenn angegeben, wird die Anzahl der Aufrufe angezeigt, die der Indexer parallel zum von Ihnen bereitgestellten Endpunkt vornimmt. Sie können diesen Wert verringern, wenn Ihr Endpunkt unter zu hoher Anforderungslast fehlschlägt. Sie können ihn auslösen, wenn Ihr Endpunkt mehr Anforderungen annehmen kann und Sie eine Erhöhung der Leistung des Indexers wünschen. Wenn kein Wert festgelegt ist, wird ein Standardwert von 5 verwendet. „degreeOfParallelism“ kann auf maximal 10 und mindestens 1 festgelegt werden.

Authentifizierung

AML-Onlineendpunkte bieten zwei Authentifizierungsoptionen:

Schlüsselbasierte Authentifizierung. Ein statischer Schlüssel wird bereitgestellt, um Bewertungsanforderungen von AML-Fähigkeiten zu authentifizieren. Legen Sie die uri Parameter für diese Verbindung fest key .
Tokenbasierte Authentifizierung, bei der der AML-Onlineendpunkt mithilfe der tokenbasierten Authentifizierung bereitgestellt wird. Die verwaltete Identität von Azure AI Suchdienst muss aktiviert sein und über eine Rollenzuweisung im Arbeitsbereich verfügen. Die AML-Fähigkeit verwendet dann die verwaltete Identität des Diensts, um sich beim AML-Onlineendpunkt zu authentifizieren, ohne dass statische Schlüssel erforderlich sind. Die Suchdienstidentität muss ein Besitzer oder Mitwirkender sein. Legen Sie den resourceId Parameter fest, und legen Sie den Parameter fest, region wenn sich der Suchdienst in einem anderen Bereich des AML-Arbeitsbereichs befindet.

Skilleingaben

Qualifikationseingaben sind ein Knoten des angereicherten Dokuments, das während des Dokumentrisses erstellt wird. Dies kann z. B. das Stammdokument, ein normalisiertes Bild oder der Inhalt eines Blobs sein. Es gibt keine vordefinierten Eingaben für diesen Skill. Für Eingaben sollten Sie einen oder mehrere Knoten angeben, die zum Zeitpunkt der Ausführung der AML-Fähigkeit aufgefüllt werden.

Skillausgaben

Qualifikationsausgaben sind neue Knoten eines bereicherten Dokuments, das von der Fähigkeit erstellt wurde. Es gibt keine vordefinierten Ausgaben für diesen Skill. Für Ausgaben sollten Sie Knoten bereitstellen, die aus der JSON-Antwort Ihrer AML-Fähigkeit aufgefüllt werden können.

Beispieldefinition

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

Beispiel für eine Eingabe-JSON-Struktur

Diese JSON-Struktur stellt die Nutzlast dar, die an Ihren AML-Onlineendpunkt gesendet wird. Die Felder der Struktur auf oberster Ebene entsprechen den im Abschnitt inputs der Skilldefinition angegebenen „Namen“. Der Wert dieser Felder ergibt sich aus der source dieser Felder (die aus einem Feld im Dokument oder möglicherweise aus einer anderen Qualifikation stammen kann)

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

Beispiel für eine Ausgabe-JSON-Struktur

Die „Ausgabe“ entspricht der Antwort, die von Ihrem AML-Onlineendpunkt zurückgegebenen wird. Der AML-Onlineendpunkt sollte nur eine JSON-Nutzlast zurückgeben (verifiziert durch Untersuchen des Content-Type-Antwortheaders) und sollte ein Objekt sein, bei dem die Felder Anreicherungen sind, die mit den „Namen“ in output übereinstimmen und deren Wert als die Anreicherung angesehen wird.

{
    "detected_language_code": "es"
}

Definition des Inlinestrukturierungsbeispiels

  {
    "@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-Eingabestruktur der Inlinestrukturierung

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

JSON-Ausgabestruktur des Inlinestrukturierungsbeispiels

{
    "detected_language_code": "es"
}

Auftretende Fehler

Neben der Tatsache, dass AML nicht verfügbar ist oder keine erfolgreichen Statuscodes gesendet werden, gelten die folgenden Fälle als Fehlerfälle:

Der AML-Onlineendpunkt gibt einen Erfolgsstatuscode zurück, aber die Antwort gibt an, dass sie nicht application/jsonist, und die Antwort wird als ungültig betrachtet, und es werden keine Anreicherungen ausgeführt.
Der AML-Onlineendpunkt gibt ungültigen JSON-Code zurück.

Wenn der AML-Onlineendpunkt nicht verfügbar ist oder einen HTTP-Fehler zurückgibt, wird dem Indexerausführungsverlauf ein freundlicher Fehler mit allen verfügbaren Details zum HTTP-Fehler hinzugefügt.

Freigeben über