AML-Skill in einer Anreicherungspipeline von Azure AI Search

Artikel
05/21/2024

Wichtig

Dieser Skill befindet sich in der Public Preview-Phase und unterliegt den zusätzlichen Nutzungsbedingungen. Die Vorschau-REST-API unterstützt diesen Skill.

Mit dem AML-Skill können Sie die KI-Anreicherung durch ein benutzerdefiniertes AML-Modell (Azure Machine Learning) erweitern. Nachdem ein AML-Modell trainiert und bereitgestellt wurde, integriert ein AML-Skill dieses in die KI-Anreicherung.

Wie andere integrierte Skills weist ein AML-Skill Eingaben und Ausgaben auf. Die Eingaben werden als JSON-Objekt an den bereitgestellten AML-Online-Endpunkt gesendet, das eine JSON-Nutzlast als Antwort zusammen mit einem Erfolgsstatuscode ausgibt. Es wird erwartet, dass die Antwort die von Ihrem Skill AML angegebenen Ergebnisse aufweist. Jede andere Antwort gilt als Fehler und es werden keine Anreicherung durchgeführt.

Wenn Sie die Vektorisierung des Azure AI Studio-Modellkatalogs (Vorschau) für die integrierte Vektorisierung zur Abfragezeit verwenden, sollten Sie auch den AML-Skill zur integrierten Vektorisierung während der Indizierung verwenden. Anweisungen dazu finden Sie unter Implementieren der integrierten Vektorisierung mithilfe von Modellen aus Azure KI Studio. Dieses Szenario wird über die REST-API 2024-05-01-Vorschau und das Azure-Portal unterstützt.

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

Voraussetzungen

Ein AML-Arbeitsbereich
Ein Onlineendpunkt (Echtzeit) in diesem Arbeitsbereich.

@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.
`key`	(Erforderlich für Schlüsselauthentifizierung) Der Schlüssel für den AML-Online-Endpunkt.
`resourceId`	(Erforderlich für Tokenauthentifizierung). Die Azure Resource Manager-Ressourcen-ID des AML-Onlinenendpunkts. Er sollte im Format „subscriptions/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name}“ vorliegen.
`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.

Zu verwendende Skillparameter

Welche AML-Skillparameter erforderlich sind, hängt davon ab, welche Authentifizierung der AML-Onlineendpunkt ggf. erfordert. AML-Onlineendpunkte bieten zwei Authentifizierungsoptionen:

Schlüsselbasierte Authentifizierung. Ein statischer Schlüssel wird bereitgestellt, um Bewertungsanforderungen von AML-Skills zu authentifizieren.
- Verwenden Sie die Parameter uri und key.
Tokenbasierte Authentifizierung. Der AML-Onlineendpunkt wird mithilfe der tokenbasierten Authentifizierungbereitgestellt. Die verwaltete Identität des Azure KI Suchdienstes muss aktiviert sein. 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. Der Identität muss die Rolle „Besitzer“ oder „Mitwirkender“ zugewiesen werden.
- Verwenden Sie den resourceId-Parameter.
- Wenn sich der Suchdienst in einer anderen Region als der AML-Arbeitsbereich befindet, verwenden Sie den Parameter region, um die Region festzulegen, in der der AML-Onlineendpunkt bereitgestellt wurde

Skilleingaben

Es gibt keine „vordefinierten“ Eingaben für diese Qualifikation. Sie können mindestens ein Feld auswählen, das zum Zeitpunkt der Ausführung dieses Skills bereits verfügbar ist, da Eingaben und die an den AML-Onlineendpunkt gesendete JSON-Nutzlast unterschiedliche Felder aufweisen.

Skillausgaben

Es gibt keine „vordefinierten“ Ausgaben für diese Qualifikation. Abhängig von der Antwort, die Ihr AML-Onlineendpunkt zurückgibt, fügen Sie Ausgabefelder hinzu, damit sie von der JSON-Antwort übernommen werden können.

Beispieldefinition

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

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://contoso.count-things.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:

Wenn der AML-Onlineendpunkt einen Statuscode für den Erfolg zurückgibt, die Antwort aber anzeigt, dass er nicht application/json ist, dann wird die Antwort als ungültig betrachtet, und es werden keine Anreicherungen durchgeführt.
Wenn der AML-Onlineendpunkt ungültige JSON zurückgibt

In Fällen, in denen der AML-Onlineendpunkt nicht verfügbar ist oder einen HTTP-Fehler zurückgibt, wird eine Fehlermeldung mit allen verfügbaren Details zum HTTP-Fehler in den Ausführungsverlauf des Indexers aufgenommen.

Share via