Verwenden von Azure OpenAI in einer Studio-Operation in Jitterbit Studio

Einführung

Der Azure OpenAI Connector ermöglicht Studio-Operationen, Daten an ein in Azure gehostetes Sprachmodell zu senden und KI-generierte Texte zurückzuerhalten. Diese Anleitung behandelt das häufige Muster, einen Prompt aus Quelldaten zu erstellen, ihn mithilfe der Prompt-Aktivität an Azure OpenAI zu senden und die KI-Antwort dann an ein Downstream-Ziel wie eine Datenbank, eine Datei oder einen Benachrichtigungskanal weiterzuleiten.

Im Gegensatz zum OpenAI Connector authentifiziert sich der Azure OpenAI Connector mithilfe einer Azure-Ressourcen-Endpunkt-URL und eines API-Schlüssels anstelle eines OpenAI-Kontoschlüssels. Die Modelle werden aus den Deployments in deiner Azure OpenAI-Ressource ausgewählt und nicht aus einer festen Liste.

Design-Muster

Die Operation, die Daten an Azure OpenAI übermittelt, folgt dem Transformationsmuster:

Die Quellaktivität stellt die Daten bereit, die zum Erstellen des Prompts verwendet werden (beispielsweise das Ergebnis einer Datenbankabfrage oder ein Salesforce-Datensatz). Die Transformation ordnet diese Daten den Prompt-Anforderungsfeldern zu. Die Prompt-Aktivität sendet die Anfrage an Azure OpenAI und speichert die Antwort.

Eine zweite Operation, die nach dem Erfolg der ersten verkettet wird, verwendet eine Transformation, um die KI-Antwort zu lesen und den generierten Text an die Zielaktivität weiterzuleiten (beispielsweise das Schreiben in ein Datenbankfeld oder das Posten in einen Slack-Kanal).

Teil 1: Den Azure OpenAI-Connector konfigurieren

1. Öffne dein Projekt in Studio und klicke auf die Registerkarte Projektendpunkte und Connectors in der Design Component Palette.

2. Klicke auf den Azure OpenAI Connector, um die Verbindungskonfiguration zu öffnen.

3. Verbindungsname: Gib einen Namen ein, der diese Verbindung identifiziert, beispielsweise Azure OpenAI.

4. Endpunkt: Gib die Endpunkt-URL für deine Azure OpenAI-Ressource ein. Diese findest du im Azure Portal unter Resource Management > Keys and Endpoint in der linken Seitenleiste.

5. API/Secret Key: Gib den API-Schlüssel für deine Azure OpenAI-Ressource ein. Du findest diesen im Azure Portal am gleichen Ort: Verwende den Wert aus dem Feld KEY 1 oder KEY 2.

   Tipp

   Speichere den API-Schlüssel als Projektvariable mit ausgeblendetem Wert. Referenziere die Variable dann hier über das Variablensymbol oder durch Drücken von [, um sie auszuwählen. Dies hält den Schlüssel aus der Verbindungskonfiguration direkt heraus und ermöglicht es dir, ihn einfach auszutauschen, ohne das Projekt zu bearbeiten.

6. Optionale Einstellungen: Klicke zum Erweitern. Zwei Einstellungen sind für häufige Anwendungsfälle relevant:

   • Chat-Kontext über Operationen hinweg speichern: (Nur Cloud Agent Groups.) Ermöglicht dem Connector, den Gesprächsverlauf zwischen Operationen in der gleichen Umgebung beizubehalten, die die gleiche chatId nutzen. Verwende dies, wenn spätere Operationen auf frühere Gesprächsrunden verweisen müssen.
   • Eine Datenquelle hinzufügen: Verbindet eine Azure AI Search oder Azure Cosmos DB for MongoDB (vCore) Instanz, damit Azure OpenAI-Antworten auf deinen eigenen Daten basieren.

7. Klicke auf Test, um die Verbindung zu überprüfen, und klicke dann auf Änderungen speichern.

Teil 2: Die Prompt-Aktivität konfigurieren

Die Prompt-Aktivität ist ein Ziel: Sie verarbeitet aus einer Transformation zugeordnete Daten und übermittelt sie an Azure OpenAI.

1. Erweitere auf der Design Component Palette den Azure OpenAI Endpunkt, den du erstellt hast. Ziehe den Aktivitätstyp Prompt auf die Design Canvas, um eine Aktivitätsinstanz zu erstellen.

2. Doppelklicke auf die Aktivität, um ihre Konfiguration zu öffnen.

Schritt 1: Einen Namen eingeben und Einstellungen festlegen

1. Name: Gib einen Namen für die Aktivität ein, beispielsweise Sentimentanalyse.

2. Eingabeaufforderungstext: Geben Sie den Basistextet der Eingabeaufforderung ein. Wenn die Eingabeaufforderung Quelldatenfelder dynamisch integrieren muss (zum Beispiel den Text einer Kundenrezension oder einer Supportfall-Beschreibung einfügen), geben Sie hier die statische Anweisung ein und erstellen Sie die vollständige Eingabeaufforderung in der Transformation (siehe Teil 3).

   Beispiel einer statischen Eingabeaufforderung:

   Analyze the sentiment of the following customer review:
   

3. Modell-ID: Wählen Sie das zu verwendende Azure OpenAI-Modell aus. Die Liste zeigt nur Modelle an, die in Ihrer Azure OpenAI-Ressource bereitgestellt sind. Klicken Sie auf Aktualisieren, um die Liste zu aktualisieren, wenn Sie neue Modelle bereitgestellt haben, seit Sie diese Konfiguration geöffnet haben. Informationen zur Modellbereitstellung finden Sie in der Microsoft-Dokumentation.

4. Optionale Einstellungen: Klicken Sie zum Erweitern:

   • Rolle: Steuert den Typ der an Azure OpenAI gesendeten Eingabeaufforderung. Der Standard ist System, was sich für automatisierte, nicht interaktive Eingabeaufforderungen eignet. Verwenden Sie Benutzer, um eine direkte Benutzereingabeaufforderung zu simulieren. Hinweise zu den Rollen Assistant und Tool finden Sie unter Azure OpenAI-Eingabeaufforderungsaktivität.
   • Temperatur: Steuert die Zufälligkeit der Antwort. Werte näher bei 0 erzeugen deterministischere Ausgaben; Werte näher bei 2 erzeugen vielfältigere Ausgaben. Es wird nicht empfohlen, diese Einstellung zusammen mit Höchste Wahrscheinlichkeit zu verwenden.
   • Max. Token: Begrenzt die Länge der Antwort. Der Standard ist 16. Legen Sie dies fest, um unerwartet lange Vervollständigungen zu vermeiden.
   • Höchste Wahrscheinlichkeit: Eine Alternative zu Temperatur zum Steuern der Ausgabendiversität. Es wird nicht empfohlen, diese Einstellung zusammen mit Temperatur zu verwenden.

5. Klicken Sie auf Weiter.

Schritt 2: Überprüfung der Datenschemas

Die Request- und Response-Schemas werden angezeigt. Das Request-Schema enthält prompt, model, max_tokens, temperature und top_p. Das Response-Schema enthält choices (ein Array mit dem generierten Text, index und finish_reason), usage (Token-Zählungen) und errors.

Klicken Sie auf Abgeschlossen, um die Aktivitätskonfiguration zu speichern.

Teil 3: Quelldaten der Eingabeaufforderung in einer Transformation zuordnen

Ordnen Sie in der Transformation, die der Aktivität Eingabeaufforderung vorausgeht, die Quellfelder dem Request-Schema der Aktivität Eingabeaufforderung zu.

Das wichtigste Feld zum Zuordnen ist prompt. Verwenden Sie einen Script-Knoten, um die vollständige Eingabeaufforderungszeichenfolge zu erstellen, indem Sie die statische Anweisung mit Feldwerten aus der Quelle kombinieren:

<trans>
"Analyze the sentiment of the following customer review:\n\n" +
Source.ReviewText
</trans>

Dabei ist Source.ReviewText ein Feld aus dem Response-Schema der Quellaktivität (zum Beispiel ein Feld, das von einer Datenbankaktivität Abfrage zurückgegeben wird).

Um das in der Aktivitätskonfiguration festgelegte Modell zu überschreiben, ordnen Sie das Feld model einer Literalzeichenfolge oder einer Projektvariablen zu:

<trans>
$azure_openai_model
</trans>

Teil 4: Zugriff auf die KI-Antwort

Das Response-Schema der Aktivität Eingabeaufforderung ist in jeder Transformation innerhalb desselben Vorgangs oder in einem nachgelagerten Vorgang verfügbar.

Verkettung eines nachgelagerten Vorgangs

Konfigurieren Sie die Aktion Bei Erfolg des Eingabeaufforderungsvorgangs, um einen zweiten Vorgang auszuführen, der die KI-Antwort verarbeitet:

1. Öffnen Sie die Einstellungen des Eingabeaufforderungsvorgangs.

2. Legen Sie auf der Registerkarte Aktionen die Aktion Bei Erfolg auf Vorgang ausführen fest und wählen Sie den nachgelagerten Vorgang aus.

Weitere Informationen zur Verkettung von Vorgängen finden Sie unter Fehlerbehandlung in Vorgängen konfigurieren.

Generierte Text auslesen

Der Azure OpenAI-Connector verwendet die Chat Completion API, die den von der KI generierten Text in choices[0].message.content zurückgibt. Ordnen Sie in der Transformation des nachgelagerten Vorgangs dieses Feld dem Ziel zu:

<trans>
Source.choices[0].message.content
</trans>

Beispielsweise können Sie choices[0].message.content einem Datenbankfeld zuordnen, um das Ergebnis zu speichern, oder einem Slack-Nachrichtenfeld text, um die KI-Antwort in einem Kanal zu posten (siehe Slack-Benachrichtigung aus einem Studio-Vorgang senden).

Fehler prüfen

Das Antwortschema enthält auch ein Array errors. Wenn Azure OpenAI einen Fehler zurückgibt (beispielsweise wegen eines ungültigen Modellbereitstellungsnamens oder eines überschrittenen Token-Limits), erscheinen die Fehlerdetails in errors[0].message. Um diese im Vorgangsprotokoll anzuzeigen, fügen Sie der Transformation einen Skriptknoten hinzu, der RaiseError aufruft, wenn errors mit Daten gefüllt ist:

<trans>
if(Length(Source.errors) > 0,
  RaiseError(Source.errors[0].message)
);
</trans>

Integration überprüfen

1. Stellen Sie den Prompt-Vorgang bereit und führen Sie ihn manuell aus.

2. Bestätigen Sie im Vorgangsprotokoll, dass die Prompt-Aktivität erfolgreich abgeschlossen wurde und der nachgelagerte Vorgang ausgelöst wurde.

3. Überprüfen Sie das Protokoll des nachgelagerten Vorgangs, um zu bestätigen, dass choices[0].message.content eine gültige KI-generierte Antwort enthält.

4. Wenn die Prompt-Aktivität mit einem Authentifizierungsfehler fehlschlägt, überprüfen Sie die Endpunkt-URL und den API-Schlüssel in der Azure OpenAI-Verbindung und bestätigen Sie, dass der Schlüssel im Azure Portal nicht rotiert wurde.

Weitere fortgeschrittene KI-Muster, die auf dieser Grundlage aufbauen, finden Sie unter Dokumente mit KI verarbeiten und LLM-Antworten mit Funktionsaufrufen an Studio-Vorgänge weiterleiten.