Eine benutzerdefinierte Fähigkeit zu einer Anreicherungspipeline in Foundry IQ (Azure KI-Suche) hinzufügen

Note

Foundry IQ (Azure KI-Suche) bietet direkte Indizierungs- und Abfrage-APIs zusammen mit Wissensquellen- und Knowledge Base-APIs auf höherer Ebene für den verwalteten Abruf. Verwenden Sie das Azure Portal, REST-APIs oder Azure SDKs, um diese Funktionen zu konfigurieren, oder verbinden Sie Agents mit Wissensdatenbanken im Microsoft Foundry-Portal.

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 Foundry IQ-Dienstes ausgeführt (z. B. als Azure Function), nimmt jedoch Eingaben entgegen und übermittelt Ausgaben an das Skillset, genau wie jede andere Fähigkeit. 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:

Stellen Sie sicher, dass uri auf den Endpunkt der Anwendung verweist, die durch authResourceId identifiziert wird. Nicht übereinstimmende Werte können zu Authentifizierungsfehlern führen oder dazu, dass Anfragen an einen nicht vorgesehenen 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, setzen Sie timeout vorübergehend auf einen niedrigen Wert, z. B. PT10S, damit der Timeoutfehler schneller angezeigt wird. Verwalten Sie bei einer Azure Function App eingehende IP-Regeln unter Einstellungen>Netzwerk>Zugriffsbeschränkungen. 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"
          }
        ]
      }
  ]
}

Note

Wenn Sie das Skillset mit GET abrufen, gibt der Dienst <redacted> für alle httpHeaders-Werte zurück, um die Offenlegung von Anmeldeinformationen zu verhindern. Um die Fähigkeit zu aktualisieren, ohne gespeicherte Headerwerte zu ändern, legen Sie jeden Wert auf <unchanged>. Ausführliche Informationen und Beispiele finden Sie unter "Benutzerdefinierte Web-API-Fähigkeit – Qualifikationsparameter".

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: