Benutzerdefinierter Web-API Skill in einer Anreicherungspipeline der Azure KI Search

  • Artikel

Mit der Qualifikation Benutzerdefinierte Web-API können Sie die KI-Anreicherung erweitern, indem Sie einen Web-API-Endpunkt aufrufen, der benutzerdefinierte Operationen bereitstellt. Ähnlich wie integrierte Qualifikationen hat die Qualifikation Benutzerdefinierte Web-API Eingaben und Ausgaben. Abhängig von den Eingaben erhält Ihre Web-API eine JSON-Nutzlast, wenn der Indexer ausgeführt wird, und gibt eine JSON-Nutzlast als Antwort sowie einen Statuscode für den Erfolg aus. Es wird erwartet, dass die Antwort die von Ihrer Qualifikation „Benutzerdefiniert“ spezifizierten Ergebnisse aufweist. Jede andere Antwort gilt als Fehler und es werden keine Anreicherung durchgeführt. Die Struktur der JSON-Nutzlast wird weiter unten in diesem Dokument beschrieben.

Der Skill Benutzerdefinierte Web-API wird auch in der Implementierung des Features Azure OpenAI für Ihre Daten verwendet. Wenn Azure OpenAI für rollenbasierten Zugriff konfiguriert ist und Sie beim Erstellen des Vektorindexes 403 Forbidden-Aufrufe erhalten, vergewissern Sie sich, dass die Azure KI-Suche über eine systemseitig zugewiesene Identität verfügt und als vertrauenswürdiger Dienst in Azure OpenAI ausgeführt wird.

Hinweis

Bei bestimmten Standard-HTTP-Statuscodes, die von der Web-API zurückgegeben werden, unternimmt der Indexer zwei Wiederholungsversuche. Diese HTTP-Statuscodes lauten:

  • 502 Bad Gateway
  • 503 Service Unavailable
  • 429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Skillparameter

Bei den Parametern wird zwischen Groß- und Kleinschreibung unterschieden.

Parametername Beschreibung
uri Der URI der Web-API, an die die JSON-Nutzdaten gesendet werden. Nur das HTTPS-URI-Schema ist zulässig.
authResourceId (Optional) Eine Zeichenfolge, die angibt, dass dieser Skill bei der Verbindung mit der Funktion oder App, die den Code hostet, eine verwaltete Identität verwenden soll. Diese Eigenschaft wird auf eine Anwendungs-ID (Client) oder auf die Registrierung einer App in Microsoft Entra ID festgelegt. Dabei wird ein unterstütztes Format verwendet: api://<appId>. Dieser Wert wird verwendet, um den Gültigkeitsbereich des vom Indexer abgerufenen Authentifizierungstokens festzulegen. Er wird zusammen mit der API-Anforderung für benutzerdefinierte Web-Skills an die Funktion oder App gesendet. Wenn diese Eigenschaft festgelegt wird, muss Ihr Suchdienst für die verwaltete Identität konfiguriert und Ihre Azure-Funktions-App für eine Microsoft Entra-Anmeldung konfiguriert sein. Rufen Sie die API mit api-version=2023-10-01-Preview auf, um diesen Parameter zu verwenden.
httpMethod Diese Methode wird zum Senden der Nutzlast verwendet: Zulässige Methoden sind PUT oder POST.
httpHeaders Eine Sammlung von Schlüssel-Wert-Paaren, bei denen die Schlüssel Headernamen und die Werte Headerwerte darstellen, die zusammen mit den Nutzdaten an Ihre Web-API gesendet werden. Die folgenden Header dürfen nicht in dieser Sammlung enthalten sein: Accept, Accept-Charset, Accept-Encoding, Content-Length, Content-Type, Cookie, Host, TE, Upgrade, Via.
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.
batchSize (Optional) Gibt an, wie viele Datensätze (siehe JSON-Nutzlaststruktur weiter unten) pro API-Aufruf gesendet werden. Wenn kein Wert festgelegt ist, wird der Standardwert 1000 ausgewählt. Wir empfehlen Ihnen, diesen Parameter zu verwenden, um einen angemessenen Kompromiss zwischen Indizierungsdurchsatz und Auslastung Ihrer API zu erreichen.
degreeOfParallelism (Optional) Bei Angabe dieses Parameters wird die Anzahl von Aufrufen angezeigt, die der Indexer parallel zum von Ihnen bereitgestellten Endpunkt vornimmt. Sie können diesen Wert verringern, wenn Ihr Endpunkt unter Druck ausfällt, oder ihn heraufsetzen, wenn Ihr Endpunkt die Last verarbeiten kann. Wenn kein Wert festgelegt ist, wird ein Standardwert von 5 verwendet. Der degreeOfParallelism kann auf maximal 10 und mindestens 1 festgelegt werden.

Skilleingaben

Es gibt keine vordefinierten Eingaben für diesen Skill. Die Eingaben sind jedes vorhandene Feld oder ein beliebiger Knoten in der Anreicherungsstruktur, die Sie an Ihren benutzerdefinierten Skill übergeben möchten.

Skillausgaben

Es gibt keine vordefinierten Ausgaben für diesen Skill. Achten Sie darauf, im Indexer eine Ausgabefeldzuordnung zu definieren, wenn die Skillausgabe an ein Feld im Suchindex gesendet werden soll.

Beispieldefinition

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

Beispiel für eine Eingabe-JSON-Struktur

Diese JSON-Struktur stellt die Nutzdaten dar, die an Ihre Web-API gesendet werden. Es gelten immer folgende Einschränkungen:

  • Die Entität der höchsten Ebene hat die Bezeichnung values und ist ein Array von Objekten. Die Anzahl derartiger Objekte entspricht maximal dem Wert von batchSize.

  • Jedes Objekt im values-Array verfügt über Folgendes:

    • Eine recordId-Eigenschaft. Dies ist eine eindeutige Zeichenfolge, die zum Bestimmen dieses Datensatzes verwendet wird.

    • Eine data-Eigenschaft, die ein JSON-Objekt ist. Die Felder der data-Eigenschaft entsprechen den Namen, die im Abschnitt inputs der Qualifikationsdefinition angegeben sind. Die Werte dieser Felder stammen aus der Quelle (source) dieser Felder (also aus einem Feld im Dokument oder möglicherweise aus einem anderen Skill).

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

Beispiel für eine Ausgabe-JSON-Struktur

Die „Ausgabe“ entspricht der Antwort, die von Ihrer Web-API zurückgegebenen wird. Die Web-API sollte nur eine JSON-Nutzlast zurückgeben (verifiziert durch Prüfung des Content-Type-Antwortheaders) und die folgenden Einschränkungen erfüllen:

  • Es muss eine Entität der höchsten Ebene mit der Bezeichnung values vorhanden sein, bei der es sich um ein Array von Objekten handelt.

  • Die Anzahl der Objekte im Array sollte gleich der Anzahl der an die Web-API gesendeten Objekte sein.

  • Jedes Objekt benötigt:

    • Eine recordId-Eigenschaft.

    • Eine data-Eigenschaft, die ein Objekt ist, bei dem die Felder Anreicherungen sind, die den „Namen“ in der output entsprechen und deren Wert als Anreicherung betrachtet wird.

    • Eine errors-Eigenschaft (ein Array, das alle aufgetretenen Fehler auflistet und dem Ausführungsverlauf des Indexers hinzugefügt wird). Diese Eigenschaft ist erforderlich, kann jedoch ein null-Wert sein.

    • Eine warnings-Eigenschaft (ein Array, das alle aufgetretenen Warnungen auflistet und dem Ausführungsverlauf des Indexers hinzugefügt wird). Diese Eigenschaft ist erforderlich, kann jedoch ein null-Wert sein.

  • Die Reihenfolge der Objekte in den values der Anforderung oder Antwort ist nicht wichtig. recordId wird jedoch für die Korrelation verwendet, sodass jeder Datensatz in der Antwort, der eine Datensatz-ID (recordId) enthält, die nicht Teil der ursprünglichen Anforderung an die Web-API war, verworfen wird.

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

Auftretende Fehler

Neben der Tatsache, dass Ihre Web-API nicht verfügbar ist oder nicht erfolgreiche Statuscodes versendet werden, gelten die folgenden Fälle als fehlerhafte Fälle:

  • Wenn die Web-API einen Statuscode für den Erfolg zurückgibt, die Antwort aber angibt, dass es sich nicht um application/json handelt, wird die Antwort als ungültig betrachtet, und es werden keine Anreicherungen durchgeführt.

  • Wenn im values-Array der Antwort ungültige Datensätze vorhanden sind (z. B., wenn recordId fehlt oder dupliziert ist), wird für die ungültigen Datensätze keine Anreicherung durchgeführt. Es ist wichtig, bei der Entwicklung benutzerdefinierter Skills die Anforderungen des Skill-Vertrags der Web-API zu erfüllen. Im Power Skill-Repository finden Sie ein Beispiel, das dem erwarteten Vertrag entspricht.

In Fällen, in denen die Web-API nicht verfügbar ist oder einen HTTP-Fehler zurückgibt, wird eine verständliche Fehlermeldung mit allen verfügbaren Details über den HTTP-Fehler in den Ausführungsverlauf des Indexers aufgenommen.

Weitere Informationen