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

Verwenden Sie die Benutzerdefinierte Web-API-Fähigkeit , um die KI-Anreicherung durch Aufrufen eines Web-API-Endpunkts zu erweitern, der benutzerdefinierte Vorgänge bereitstellt. Wie integrierte Fähigkeiten verfügt eine benutzerdefinierte Web-API-Fähigkeit über Eingaben und Ausgaben. Abhängig von den Eingaben empfängt Ihre Web-API eine JSON-Nutzlast, wenn der Indexer ausgeführt wird, und gibt eine JSON-Nutzlast als Antwort zusammen mit einem Erfolgsstatuscode zurück. Die Antwort muss die Ausgaben enthalten, die von Ihrer benutzerdefinierten Fähigkeit angegeben werden. 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.

Die Benutzerdefinierte Web-API-Fähigkeit wird auch bei der Implementierung des features Azure OpenAI On Your Data verwendet. Wenn Azure OpenAI für den rollenbasierten Zugriff konfiguriert ist und Beim Erstellen des Vektorindex Fehler auftreten403 Forbidden, überprüfen Sie, ob Azure KI-Suche über eine Systemidentität verfügt und als vertrauenswürdiger Dienst auf Azure OpenAI ausgeführt wird.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Qualifikationsparameter

Bei Parametern wird die Groß-/Kleinschreibung beachtet.

Qualifikationseingaben

Diese Fähigkeit hat keine vordefinierten Eingaben. Die Eingaben sind jedes vorhandene Feld oder ein beliebiger Knoten in der Anreicherungsstruktur, die Sie an Ihren benutzerdefinierten Skill übergeben möchten.

Skill-Ergebnisse

Diese Fähigkeit hat keine vordefinierten Ausgaben. 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"
    }
  ]
}

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso.example.org/api?code=<redacted>",
  "httpMethod": "POST",
  "name": "myCustomSkill",
  "httpHeaders": {
    "Authorization": "<redacted>",
    "Ocp-Apim-Subscription-Key": "<redacted>"
  }
}

{
  "uri": "<unchanged>",
  "httpHeaders": {
    "Authorization": "<unchanged>",
    "Ocp-Apim-Subscription-Key": "<unchanged>"
  }
}

Beispiel für eine Eingabe-JSON-Struktur

Diese JSON-Struktur stellt die Nutzlast dar, die Sie an Ihre Web-API senden. 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 dieser Objekte ist höchstens der batchSize.

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

  • Eine recordId Eigenschaft, die eine eindeutige Zeichenfolge ist, die verwendet wird, um diesen Datensatz zu identifizieren.

  • Eine data Eigenschaft, die ein JSON-Objekt ist. Die Felder der Eigenschaft data entsprechen den Namen, die im Abschnitt inputs der Skilldefinition angegeben sind. Die Werte dieser Felder stammen aus den source Feldern (die aus einem Feld im Dokument oder potenziell aus einer anderen Fähigkeit stammen können).

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

Fehlerfälle

Berücksichtigen Sie nicht nur die folgenden Fälle als Fehler, wenn Ihre Web-API nicht verfügbar ist oder nicht erfolgreiche Statuscodes sendet:

• Wenn die Web-API einen Erfolgsstatuscode zurückgibt, aber die Antwort angibt, dass sie nicht application/jsonist, ist die Antwort ungültig, und es werden keine Anreicherungen ausgeführt.

• Wenn das Antwortarray values ungültige Datensätze enthält (z. B. fehlende oder dupliziert recordId), werden die ungültigen Datensätze nicht erweitert. Wenn Sie benutzerdefinierte Fähigkeiten entwickeln, halten Sie sich an den Web-API-Qualifikationsvertrag. Im Power Skill-Repository finden Sie ein Beispiel, das dem erwarteten Vertrag entspricht.

Wenn die Web-API nicht verfügbar ist oder einen HTTP-Fehler zurückgibt, enthält der Indexerausführungsverlauf einen freundlichen Fehler mit allen verfügbaren Details zum HTTP-Fehler.

Siehe auch

• Definieren einer Fähigkeitengruppe
• Hinzufügen einer benutzerdefinierten Qualifikation zu einer KI-Anreicherungspipeline
• Beispiel: Erstellen eines benutzerdefinierten Skills für die KI-Anreicherung
• Power Skill-Repository