Hinzufügen einer benutzerdefinierten Fähigkeit zu einer Azure KI-Suche Anreicherungspipeline

Eine KI-Anreicherungspipeline kann sowohl integrierte Fähigkeiten als auch benutzerdefinierte Fähigkeiten umfassen, die Sie erstellen und veröffentlichen. Ihr benutzerdefinierter Code wird außerhalb des Suchdiensts ausgeführt (z. B. als Azure-Funktion), akzeptiert jedoch Eingaben und sendet Ausgaben wie jede andere Fähigkeit an das Skillset. Ihre Daten werden in der geographie verarbeitet, in der Ihr Modell bereitgestellt wird.

Benutzerdefinierte Fähigkeiten klingen möglicherweise komplex, aber sie können einfach implementiert werden. Wenn Sie über vorhandene Pakete verfügen, die Musterabgleichs- oder Klassifizierungsmodelle bereitstellen, können Sie Inhalte aus Blobs zur Verarbeitung an diese Modelle übergeben. Da die KI-Anreicherung Azure basiert, sollten Sie ihr Modell auch auf Azure hosten. Allgemeine Hostingoptionen umfassen Azure Functions oder container.

Wenn Sie einen benutzerdefinierten Skill erstellen, wird in diesem Artikel die Schnittstelle beschrieben, mit der Sie den Skill in die Pipeline integrieren können. Die Hauptanforderung ist die Fähigkeit, Eingaben zu akzeptieren und Ausgaben so bereitzustellen, dass das Skillset sie als Ganzes verarbeiten kann. Daher liegt der Schwerpunkt dieses Artikels auf den Eingabe- und Ausgabeformaten, die die Anreicherungspipeline benötigt.

Vorteile von benutzerdefinierten Skills

Das Erstellen eines benutzerdefinierten Skills gibt Ihnen die Möglichkeit, Transformationen einzufügen, die für Ihren Inhalt eindeutig sind. Sie können beispielsweise benutzerdefinierte Klassifizierungsmodelle erstellen, um zwischen Geschäfts- und Finanzverträgen und -dokumenten zu unterscheiden, oder einen Skill für die Spracherkennung hinzufügen, um Audiodateien nach relevanten Inhalten zu durchsuchen. Ein Beispiel mit Schrittanleitung finden Sie unter Beispiel: Erstellen eines benutzerdefinierten Skills zur KI-Anreicherung.

Festlegen des Endpunkt- und Timeoutintervalls

Geben Sie die Schnittstelle für eine benutzerdefinierte Fähigkeit über die Benutzerdefinierte Web-API-Fähigkeit an.

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230-second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

Der URI ist der HTTPS-Endpunkt Ihrer Funktion oder App. Stellen Sie beim Festlegen des URI sicher, dass der URI sicher ist (HTTPS). Wenn Sie Ihren Code in einer Azure Funktions-App hosten, fügen Sie einen API-Schlüssel in den Header oder als URI-Parameter in den URI ein, um die Anforderung zu autorisieren.

Wenn Ihre Funktion oder App Azure verwaltete Identitäten und Azure Rollen für Authentifizierung und Autorisierung verwendet, kann die benutzerdefinierte Fähigkeit ein Authentifizierungstoken für die Anforderung enthalten. In den folgenden Punkten werden die Anforderungen für diesen Ansatz beschrieben:

• Der Suchdienst, der die Anforderung im Namen des Indexers sendet, muss so konfiguriert werden, dass eine verwaltete Identität verwendet wird (entweder system oder vom Benutzer zugewiesen), damit Microsoft Entra ID den Aufrufer authentifizieren kann.

• Sie müssen Ihre Funktion oder App für Microsoft Entra ID konfigurieren.

• Ihre benutzerdefinierte Qualifikationsdefinition muss eine authResourceId Eigenschaft enthalten. Diese Eigenschaft verwendet eine Anwendungs-ID (Client-ID) in einem unterstützten Format: api://<appId>.

Stellen Sie sicher, dass uri auf den Endpunkt der anwendung verweist, die von authResourceId. Falsch übereinstimmende Werte können dazu führen, dass Authentifizierungsfehler oder Anforderungen an einen unbeabsichtigten Endpunkt gesendet werden. Sicherheitsleitfaden, empfohlene Methoden und Schritte zur Überprüfung Ihrer Konfiguration finden Sie unter Sicherheitsüberlegungen für die verwaltete Identitätsauthentifizierung.

Die Verbindung mit dem Endpunkt wird standardmäßig unterbrochen, wenn nicht innerhalb eines Zeitfensters von 30 Sekunden eine Antwort zurückgegeben wird (PT30S). Die Indizierungspipeline ist synchron, und die Indizierung erzeugt einen Timeoutfehler, wenn eine Antwort in diesem Zeitrahmen nicht empfangen wird. Sie können das Intervall auf einen Wert von maximal 230 Sekunden erhöhen, indem Sie den Parameter timeout festlegen (PT230S).

Wenn ein durch IP-Zugriffsbeschränkungen geschützter Endpunkt nicht reagiert, wird timeout vorübergehend auf einen kurzen Wert festgelegt, z PT10S. B. auf eine schnellere Anzeige des Timeoutfehlers. Verwalten Sie für eine Azure-Funktions-App eingehende IP-Regeln unterEinschränkungen für > denNetzwerkzugriff>. Informationen zu den zuzulassenden IP-Adressen finden Sie unter Konfigurieren von IP-Firewallregeln, um Indexerverbindungen zuzulassen.

Formatieren von Web-API-Eingaben

Die Web-API muss ein Array von Zu verarbeitenden Datensätzen akzeptieren. Geben Sie innerhalb jedes Datensatzes einen Eigenschaftenbehälter als Eingabe für Ihre Web-API an.

Angenommen, Sie möchten einen einfachen Anreicherer erstellen, der das erste im Vertragstext erwähnte Datum identifiziert. In diesem Beispiel akzeptiert die benutzerdefinierte Fähigkeit eine einzelne Eingabe. contractText Der Skill hat auch eine einzige Ausgabe: das Datum des Vertrags. Um den Anreicherer interessanter zu machen, geben Sie contractDate in Form eines mehrteiligen komplexen Typs zurück.

Ihre Web-API sollte bereit sein, einen Batch von Eingabedatensätzen zu empfangen. Jedes Element des values Arrays stellt die Eingabe für einen bestimmten Datensatz dar. Jeder Datensatz muss die folgenden Elemente enthalten:

• Ein recordId Element, das der eindeutige Bezeichner für einen bestimmten Datensatz ist. Wenn Ihr Anreicherer Ergebnisse zurückgibt, muss er diesen recordId bereitstellen, damit der Aufrufer Ergebnisdatensätze den Eingaben zuordnen kann.

• Ein data-Element, das im Wesentlichen ein Behälter mit Eingabefeldern für jeden Datensatz ist.

Die resultierende Web-API-Anforderung könnte wie folgt aussehen:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issued on November 3, 2023 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

In der Praxis kann Ihr Code mit Hunderten oder Tausenden von Datensätzen aufgerufen werden, statt wie hier nur mit drei Datensätzen.

Formatieren von Web-API-Ausgaben

Das Format der Ausgabe ist eine Gruppe von Datensätzen, die recordId und einen Eigenschaftenbehälter beinhalten. Dieses spezielle Beispiel hat nur eine Ausgabe, Sie können jedoch auch mehr als eine Eigenschaft zurückgeben. Erwägen Sie als bewährte Methode die Ausgabe von Fehler- und Warnmeldungen, wenn ein Datensatz nicht verarbeitet werden konnte.

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2023 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

Hinzufügen eines benutzerdefinierten Skills zu einem Skillset

Wenn Sie eine Web-API-Anreicherung erstellen, können Sie HTTP-Header und Parameter als Teil der Anforderung definieren. Der folgende Codeschnipsel zeigt, wie Anforderungsparameter und optionale HTTP-Header in die Skillsetdefinition aufgenommen werden können. Das Festlegen eines HTTP-Headers ist nützlich, wenn Sie Konfigurationseinstellungen an Ihren Code übergeben müssen.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

Sehen Sie sich dieses Video an

Die folgende Demo bietet eine Videoeinführung und eine Demonstration.

Nächste Schritte

In diesem Artikel wurden die Schnittstellenanforderungen behandelt, die für die Integration einer benutzerdefinierten Qualifikation in ein Skillset erforderlich sind. Weitere Informationen zu benutzerdefinierten Skills und zur Zusammensetzung von Skillsets finden Sie in den folgenden Ressourcen:

• Power Skills: ein Repository von benutzerdefinierten Fähigkeiten
• Beispiel: Erstellen eines benutzerdefinierten Skills für die KI-Anreicherung
• Definieren eines Skillsets
• Erstellen eines Skillsets (REST)
• Wie man angereicherte Felder zuordnet