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

Einführung

Der Azure OpenAI-Connector ermöglicht es Studio-Operationen, Daten an ein in Azure gehostetes Sprachmodell zu senden und im Gegenzug KI-generierten Text zu erhalten. Dieser Leitfaden behandelt das gängige Muster zur Erstellung eines Prompts aus Quelldaten, das Senden an Azure OpenAI mithilfe der Prompt-Aktivität und das Weiterleiten der KI-Antwort an ein nachgelagertes Ziel wie eine Datenbank, eine Datei oder einen Benachrichtigungskanal.

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-Kontoinhaberschlüssels, und Modelle werden aus den Bereitstellungen in Ihrer Azure OpenAI-Ressource ausgewählt, anstatt aus einer festen Liste.

Entwurfsmuster

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 (zum Beispiel das Ergebnis einer Datenbankabfrage oder einen Salesforce-Datensatz). Die Transformation ordnet diese Daten den Feldern der Prompt-Anfrage zu. Die Prompt-Aktivität sendet die Anfrage an Azure OpenAI und speichert die Antwort.

Eine zweite Operation, die an den Erfolg der ersten angekettet ist, verwendet eine Transformation, um die KI-Antwort zu lesen und den generierten Text an die Zielaktivität weiterzuleiten (zum Beispiel, um ihn in ein Datenbankfeld zu schreiben oder in einen Slack-Kanal zu posten).

Teil 1: Konfigurieren der Azure OpenAI-Verbindung

1. Öffnen Sie in Studio Ihr Projekt und klicken Sie auf die Projektendpunkte und -connectoren-Registerkarte in der Design-Komponentenpalette.

2. Klicken Sie auf den Azure OpenAI-Connector, um die Verbindungs-Konfiguration zu öffnen.

3. Verbindungsname: Geben Sie einen Namen ein, der diese Verbindung identifiziert, zum Beispiel Azure OpenAI.

4. Endpunkt: Geben Sie die Endpunkt-URL für Ihre Azure OpenAI-Ressource ein. Sie finden dies im Azure-Portal unter Ressourcenverwaltung > Schlüssel und Endpunkt in der linken Seitenleiste.

5. API/Geheimschlüssel: Geben Sie den API-Schlüssel für Ihre Azure OpenAI-Ressource ein. Sie finden dies im Azure-Portal an derselben Stelle: Verwenden Sie den Wert aus dem Feld SCHLÜSSEL 1 oder SCHLÜSSEL 2.

   Tipp

   Speichern Sie den API-Schlüssel als Projektvariable mit verborgenem Wert und verweisen Sie dann hier auf die Variable, indem Sie das Variablen-Symbol verwenden oder [ eingeben, um sie auszuwählen. Dadurch bleibt der Schlüssel direkt aus der Verbindungs-Konfiguration heraus und kann einfach ohne Bearbeitung des Projekts rotiert werden.

6. Optionale Einstellungen: Klicken Sie, um zu erweitern. Zwei Einstellungen sind für gängige Anwendungsfälle relevant:

   • Chat-Kontext über Operationen hinweg speichern: (Nur Cloud-Agent-Gruppen.) Ermöglicht dem Connector, den Gesprächsverlauf zwischen Operationen in derselben Umgebung, die dasselbe chatId teilen, aufrechtzuerhalten. Verwenden Sie dies, wenn spätere Operationen auf frühere Wendungen in einem Gespräch verweisen müssen.
   • Datenquelle hinzufügen: Verbindet eine Azure AI Search- oder Azure Cosmos DB für MongoDB (vCore)-Instanz, sodass die Antworten von Azure OpenAI in Ihren eigenen Daten verankert sind.

7. Klicken Sie auf Test, um die Verbindung zu überprüfen, und klicken Sie dann auf Änderungen speichern.

Teil 2: Konfigurieren der Prompt-Aktivität

Die Prompt-Aktivität ist ein Ziel: Sie konsumiert Daten, die aus einer Transformation zugeordnet sind, und übermittelt sie an Azure OpenAI.

1. Erweitern Sie im Design-Komponenten-Palette den Azure OpenAI-Endpunkt, den Sie erstellt haben. Ziehen Sie den Aktivitätstyp Prompt auf die Design-Leinwand, um eine Aktivitätsinstanz zu erstellen.

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

Schritt 1: Geben Sie einen Namen ein und spezifizieren Sie die Einstellungen

1. Name: Geben Sie einen Namen für die Aktivität ein, zum Beispiel Analyze Sentiment.

2. Prompt-Text: Geben Sie den Basis-Prompt-Text ein. Wenn der Prompt dynamisch Quellendatenfelder einbeziehen muss (zum Beispiel den Text einer Kundenbewertung oder eine Beschreibung eines Supportfalls), geben Sie hier die statische Anweisung ein und konstruieren Sie den vollständigen Prompt in der Transformation (siehe Teil 3).

   Beispiel für einen statischen Prompt:

   Analysieren Sie das Sentiment der folgenden Kundenbewertung:
   

3. Modell-ID: Wählen Sie das Azure OpenAI-Modell aus, das verwendet werden soll. Die Liste zeigt nur Modelle, die in Ihrer Azure OpenAI-Ressource bereitgestellt wurden. Klicken Sie auf Aktualisieren, um die Liste zu aktualisieren, wenn Sie seit dem Öffnen dieser Konfiguration neue Modelle bereitgestellt haben. Informationen zur Bereitstellung von Modellen finden Sie in der Dokumentation von Microsoft.

4. Optionale Einstellungen: Klicken Sie, um zu erweitern:

   • Rolle: Steuert die Art des an Azure OpenAI gesendeten Prompts. Der Standardwert ist System, was für automatisierte, nicht-interaktive Prompts geeignet ist. Verwenden Sie User, um einen direkten Benutzerprompt zu simulieren. Für Anleitungen zu den Rollen Assistant und Tool siehe Azure OpenAI Prompt-Aktivität.
   • Temperatur: Steuert die Zufälligkeit der Antwort. Werte näher an 0 erzeugen deterministischere Ausgaben; Werte näher an 2 erzeugen variiertere Ausgaben. Es wird nicht empfohlen, diese Einstellung zusammen mit Top Probability zu verwenden.
   • Max Tokens: Begrenzung der Länge der Antwort. Der Standardwert ist 16. Setzen Sie dies, um unerwartet lange Antworten zu vermeiden.
   • Top Probability: Eine Alternative zu Temperatur zur Steuerung der Ausgabediversität. Es wird nicht empfohlen, diese Einstellung zusammen mit Temperatur zu verwenden.

5. Klicken Sie auf Weiter.

Schritt 2: Überprüfen der Datenschemas

Die Anfrage- und Antwortschemas werden angezeigt. Das Anfrage-Schema umfasst prompt, model, max_tokens, temperature und top_p. Das Antwort-Schema umfasst choices (ein Array, das den generierten Text, index und finish_reason enthält), usage (Token-Zählungen) und errors.

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

Teil 3: Quellendaten im Prompt in einer Transformation zuordnen

In der Transformation, die der Prompt-Aktivität vorausgeht, ordnen Sie die Quellfelder dem Anforderungsschema der Prompt-Aktivität zu.

Das wichtigste Feld, das zugeordnet werden muss, ist prompt. Verwenden Sie einen Skriptnode, um den vollständigen Prompt-String zu erstellen, indem Sie die statische Anweisung mit den 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 Antwortschema der Quellaktivität (zum Beispiel ein Feld, das von einer Datenbank-Abfrage-Aktivität zurückgegeben wird).

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

<trans>
$azure_openai_model
</trans>

Teil 4: Auf die AI-Antwort zugreifen

Das Antwortschema der Prompt-Aktivität ist in jeder Transformation innerhalb derselben Operation oder in einer nachgelagerten Operation verfügbar.

Eine nachgelagerte Operation verketten

Konfigurieren Sie die On Success-Aktion der Prompt-Operation so, dass eine zweite Operation ausgeführt wird, die die AI-Antwort verarbeitet:

1. Öffnen Sie die Einstellungen der Prompt-Operation.

2. Setzen Sie im Tab Aktionen die On Success-Aktion auf Operation ausführen und wählen Sie die nachgelagerte Operation aus.

Für weitere Informationen zum Verketten von Operationen siehe Fehlerbehandlung in Operationen konfigurieren.

Den generierten Text lesen

Der Azure OpenAI-Connector verwendet die Chat Completion API, die den AI-generierten Text in choices[0].message.content zurückgibt. In der Transformation der nachgelagerten Operation ordnen Sie dieses Feld dem Ziel zu:

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

Zum Beispiel, mappe choices[0].message.content auf ein Datenbankfeld, um das Ergebnis zu speichern, oder auf ein Slack-Nachrichtenfeld text, um die AI-Antwort in einen Kanal zu posten (siehe Sende eine Slack-Benachrichtigung aus einer Studio-Operation).

Überprüfen auf Fehler

Das Antwortschema enthält auch ein errors-Array. Wenn Azure OpenAI einen Fehler zurückgibt (zum Beispiel aufgrund eines ungültigen Modellbereitstellungsnamens oder eines überschrittenen Tokenlimits), erscheinen die Fehlerdetails in errors[0].message. Um diese im Betriebsprotokoll anzuzeigen, füge einen Skriptnode zur Transformation hinzu, die RaiseError aufruft, wenn errors befüllt ist:

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

Überprüfen der Integration

1. Stelle die Prompt-Operation manuell bereit und führe sie aus.

2. Bestätige in den Betriebsprotokollen, dass die Prompt-Aktivität erfolgreich abgeschlossen wurde und dass die nachgelagerte Operation ausgelöst wurde.

3. Überprüfe das Protokoll der nachgelagerten Operation, um zu verifizieren, dass choices[0].message.content eine gültige, von der AI generierte Antwort enthält.

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

Für fortgeschrittenere AI-Muster, die auf diesem Fundament basieren, siehe Verarbeite Dokumente mit AI und Leite LLM-Antworten an Studio-Operationen weiter, indem du Funktionsaufrufe verwendest.