Erstellen Sie einen Multi-Turn-LLM-Chat mit Gesprächsverlauf in Jitterbit Studio

Einführung

Ein Multi-Turn-Gespräch erfordert mehr als nur das Senden einer einzelnen Benutzernachricht an ein LLM: das Modell benötigt den vollständigen Nachrichtenaustausch, um kohärent auf Anschlussfragen zu antworten und den Kontext über mehrere Turns hinweg zu bewahren. Dieses Handbuch behandelt das Low-Level-Muster zum Erstellen und Speichern eines Gesprächsverlauf-Arrays in Studio, wobei Cloud Datastore als Session-Speicher und SumCSV zum Akkumulieren von Nachrichten zwischen Ausführungen verwendet werden.

Dieses Handbuch unterscheidet sich von So erstellen Sie einen kontextuellen KI-Agenten, das die Gesamtarchitektur des Agenten behandelt. Der Fokus liegt hier auf den Script- und Transformationsmustern, die das messages-Array aufbauen: wie man jede Nachricht als CSV-Zeile formatiert, wie man den vollständigen Verlauf zwischen Operationsausführungen speichert und abruft, und wie man optionale Felder wie tool_call_id beim Kombinieren von Gesprächsverlauf mit Function Calling behandelt.

Dieses Handbuch baut auf folgendem auf:

Speichern und Abrufen von Sessionzustand mit Cloud Datastore für Cloud-Datastore-Setup und das Query-Insert-Update-Muster.
OpenAI zum Verarbeiten von Daten in einer Studio-Operation verwenden oder Eine REST-API mit dem HTTP v2-Connector aufrufen für die LLM-Endpunkt-Konfiguration.

Hinweis

Dieses Handbuch verwaltet den Gesprächsverlauf explizit, was notwendig ist, wenn Sie das LLM über den HTTP v2-Connector aufrufen. Wenn Sie stattdessen Eingabeaufforderungen über einen nativen LLM-Connector senden und dieser Connector eine Einstellung Chat-Kontext über Operationen hinweg speichern bietet, kann dieser den Chat-Kontext für Sie speichern: diese Einstellung speichert den Verlauf zwischen Operationen, die die gleiche chatId auf Cloud-Agentgruppen verwenden, und private Agenten speichern den Chat-Kontext automatisch im Speicher.

Entwurfsmuster

Das Gesprächsverlauf-Muster fügt zwei Schritte um einen Standard-LLM-Aufruf hinzu: einen Verlaufabrufer-Schritt vor der Anfrage und einen Verlaufaktualisierungs-Schritt nach der Antwort.

%%{init: {"themeVariables": {"lineColor": "#6b7280", "edgeLabelBackground": "#f5f5f5"}}}%% flowchart LR A["Cloud Datastore abfragen
Verlauf nach Sessionschlüssel abrufen"] --> B["Script
Messages-CSV erstellen"] --> C["Transformation
CSV zu JSON konvertieren
LLM aufrufen"] --> D["Script
Benutzer + Assistent anhängen
CDS aktualisieren"]

Jede Benutzernachricht und Assistentenantwort wird in Cloud Datastore als Zeile in einer CSV-Zeichenkette gespeichert, gekennzeichnet durch einen Session-Bezeichner (typischerweise eine Slack-Kanal-ID oder Benutzer-ID). Vor jedem LLM-Aufruf wird der vollständige Verlauf abgerufen und in das messages-Array eingebunden. Nach der LLM-Antwort werden die aktuelle Benutzernachricht und die Antwort des Assistenten an den Verlauf angehängt, und die aktualisierte Zeichenkette wird zurück zu Cloud Datastore geschrieben.

Teil 1: Cloud-Datastore-Speicher einrichten

Erstellen Sie einen Schlüsselspeicher mit einem ConversationHistory-Feld zum Speichern der CSV-Verlaufzeichenkette für jede Session. Befolgen Sie Speichern und Abrufen von Sessionzustand mit Cloud Datastore für die vollständigen Setupschritte. Um Felder hinzuzufügen, navigieren Sie im Harmony-Portal zu Harmony-Portalmenü > Management Console > Cloud Datastore, öffnen Sie den Schlüsselspeicher, und fügen Sie ein Feld namens ConversationHistory mit dem Typ Big Text hinzu. Die integrierten Felder Key, Alternative Key und Value sind immer vorhanden und müssen nicht hinzugefügt werden.

Hinweis

Big-Text-Felder unterstützen bis zu 25.000 Byte pro Element. Für lange Gespräche implementieren Sie eine Abschneidestrategie: speichern Sie nur die neuesten N Austausche, bevor Sie zurück zu Cloud Datastore schreiben, oder fassen Sie frühere Turns mit dem LLM selbst zusammen, bevor Sie speichern.

Teil 2: Verlauf abrufen und Messages-Array erstellen

Verlauf abrufen

Der erste Schritt des Vorgangs fragt Cloud Datastore nach dem Sitzungsdatensatz ab und verwendet die Sitzungskennung (z. B. eine Slack-Kanal-ID) als Schlüsselfilter. Nach der Aktivität „Query Items" liest man das Ergebnis in einem Skriptschritt:

<trans>
$historyMessages = "";
if(Source.json.pagination.totalItems > 0,
    $historyMessages = Source.json.items.item[0].ConversationHistory
);
</trans>

Dies setzt historyMessages auf die gespeicherte CSV-Zeichenkette oder auf eine leere Zeichenkette, wenn dies die erste Runde in der Sitzung ist.

Messages-Array erstellen

Im nächsten Skriptschritt stellt man das vollständige Messages-Array als CSV-Zeichenkette mit SumCSV zusammen. Jeder Aufruf von SumCSV erzeugt eine CSV-Zeile aus einem Array von Feldwerten:

<trans>
// System message (always first, not stored in history)
message = Array();
message[0] = "system";
message[1] = $systemPrompt;
$messages = SumCSV(message);

// Append stored conversation history (all prior user/assistant pairs)
if(length(trim($historyMessages)) > 0,
    $messages = $messages + "\n" + $historyMessages
);

// Append the current user message
message[0] = "user";
message[1] = $userInput;
$messages = $messages + "\n" + SumCSV(message);
</trans>

messages enthält jetzt eine CSV-Zeichenkette mit einer Zeile pro Nachricht. Die Systemnachricht steht immer an erster Stelle; der gespeicherte Verlauf folgt in der Reihenfolge seiner Erfassung; die aktuelle Benutzernachricht steht zuletzt.

Tipp

Speichern Sie den Sitzungsschlüssel vor diesem Vorgang in einer globalen Variable, damit die Cloud Datastore-Aktualisierung in Teil 4 denselben Schlüssel verwendet.

Teil 3: Messages-Array in JSON konvertieren und LLM aufrufen

Quellenschema der Transformation konfigurieren

Fügen Sie eine Transformation zum Vorgang hinzu und setzen Sie die Quelldaten auf die messages-Variable, geparst als CSV. Definieren Sie ein Quellenschema mit zwei CSV-Spalten:

role (Zeichenkette)
content (Zeichenkette)

Messages-Array in die LLM-Anforderung zuordnen

Ordnen Sie die CSV-Spalten dem OpenAI Chat Completions-Anforderungstext zu. Der Zielpfad für jeden Nachrichteneintrag ist json/messages/item:

json/messages/item/role → Quellspalte role
json/messages/item/content → Quellspalte content

Wenn der Vorgang auch Werkzeugaufrufergebnisse zum Verlauf hinzufügt (zur Verwendung mit dem Werkzeugaufrufen-Schleifenmuster), kann die CSV zusätzliche Spalten enthalten. Verwenden Sie Unmap im Zielfeld-Skript, um das Feld auszulassen, wenn die Spalte leer ist, anstatt einen Null- oder leeren Zeichenkettenwert zu senden:

// Im Zielskript für json/messages/item/tool_call_id
if(length(trim(tool_call_id)) == 0, Unmap(), tool_call_id)

Wenden Sie dasselbe Muster auf name an, wenn Sie eine tool_name-Spalte einbeziehen:

// Im Zielskript für json/messages/item/name
if(length(trim(tool_name)) == 0, Unmap(), tool_name)

Dies stellt sicher, dass das Feld aus dem serialisierten JSON-Objekt fehlt, wenn es leer ist. Die OpenAI-API erfordert, dass tool_call_id und name fehlen (nicht null oder leer) für Standard-user- und assistant-Nachrichten.

Mit dem LLM-Endpunkt verbinden

Platzieren Sie die HTTP v2 POST-Aktivität, die auf den OpenAI Chat Completions-Endpunkt abzielt, nach der Transformation. Informationen zur Verbindungs- und Authentifizierungseinrichtung finden Sie unter Verwenden von OpenAI zum Verarbeiten von Daten in einem Studio-Vorgang.

Teil 4: Antwort anhängen und Cloud Datastore aktualisieren

Nach dem LLM-Aufruf extrahiert ein Skriptschritt die Antwort des Assistenten, hängt sowohl die Benutzernachricht als auch die Assistentenantwort an den gespeicherten Verlauf an und schreibt die aktualisierte Zeichenkette zurück in Cloud Datastore.

Aktualisierte Verlaufszeichenkette erstellen

<trans>
// Extract the assistant response
$assistantReply = TrimChars(GetJSONString($jitterbit.response, "/choices/0/message/content"), "\"");

// Build the two new rows to append
userMessage = Array();
userMessage[0] = "user";
userMessage[1] = $userInput;

assistantMessage = Array();
assistantMessage[0] = "assistant";
assistantMessage[1] = $assistantReply;

newExchange = SumCSV(userMessage) + "\n" + SumCSV(assistantMessage);

// Combine prior history with the new exchange
$updatedHistory = trim($historyMessages);
if(length($updatedHistory) > 0,
    $updatedHistory = $updatedHistory + "\n"
);
$updatedHistory = $updatedHistory + newExchange;
</trans>

updatedHistory enthält alle früheren Austausche sowie die aktuelle Benutzernachricht und Assistentenantwort. Die Systemnachricht ist nicht enthalten: Sie wird dynamisch am Anfang jeder Runde in Teil 2 vorangestellt und muss nicht gespeichert werden.

Aktualisierte Verlauf in Cloud Datastore schreiben

Verwenden Sie das Abfrage-Einfügen-Aktualisieren-Muster aus Sitzungsstatus mithilfe von Cloud Datastore speichern und abrufen, um updatedHistory in das Feld ConversationHistory zu schreiben, das durch die in Teil 2 verwendete Sitzungskennung gekennzeichnet ist.

Hinweis

Die Aktivität Update Items ordnet den zu aktualisierenden Datensatz anhand des Feldes Key zu. Falls das Abfrageergebnis aus Teil 2 totalItems = 0 zurückgegeben hat, muss stattdessen die Insert-Operation ausgeführt werden. Strukturiere die Post-Update-Kette so, dass sie dem Muster im Cloud Datastore-Leitfaden entspricht.

Alternative Herangehensweise: GetInstance()

Die Funktion GetInstance bietet eine alternative Möglichkeit, Nachrichtenrollen zuzuweisen, wenn Nachrichten bereits als strukturiertes Array vorliegen (z. B. aus einem JSON-Array oder einer Datenbanktabelle mit einer Zeile pro Nachricht abgerufen). In einer Transformation, die Nachrichteninstanzen durchläuft, verwende TargetInstanceCount, um den aktuellen Zeilenindex abzurufen und Rollen basierend auf gerader/ungerader Position zuzuweisen:

<trans>
// Assign alternating user/assistant roles based on row position (1-based)
$role = if(TargetInstanceCount() % 2 == 1, "user", "assistant");
</trans>

Ordne role zu json/messages/item/role. Dieser Ansatz funktioniert, wenn alle Turns mit ihren Inhaltswerten in chronologischer Reihenfolge gespeichert sind und die Rollenzuweisung nur anhand der Position abgeleitet werden kann. Er unterstützt keine Systemnachricht als eindeutlichen ersten Eintrag oder Rollenmetadaten pro Nachricht.

Der SumCSV-Ansatz aus Teil 2 ist flexibler für das Conversational Agent-Muster: Er unterstützt eine explizite Systemnachricht, ermöglicht jede beliebige Rolle pro Zeile und speichert den vollständigen Verlauf als ein einzelnes Cloud Datastore-Feld, ohne ein separates Schema mit einer Zeile pro Nachricht zu erfordern.

Integration überprüfen

Stelle die Operation bereit und führe sie aus mit einem Sitzungsschlüssel, der noch nicht im Speicher vorhanden ist. Gib eine anfängliche Benutzernachricht an.
In den Operationsprotokollen bestätige, dass das Abfrageergebnis totalItems = 0 zeigt und dass die Insert-Operation ausgeführt wurde, um den Sitzungsdatensatz zu erstellen.
In Management Console > Cloud Datastore öffne den Speicher und bestätige, dass ein Datensatz mit dem erwarteten Schlüssel vorhanden ist und dass ConversationHistory eine Benutzerzeile und eine Assistentenzeile enthält.
Führe die Operation erneut mit demselben Sitzungsschlüssel und einer Anschlussfrage aus, die sich auf den ersten Austausch bezieht.
Bestätige, dass die LLM-Antwort den vorherigen Kontext widerspiegelt. Bestätige in Cloud Datastore, dass ConversationHistory nun zwei Benutzer-/Assistentenpaare enthält.
Falls die LLM-Antwort den vorherigen Kontext ignoriert, verwende WriteToOperationLog, um messages vor der Transformation zu protokollieren und zu bestätigen, dass frühere Turns in der CSV-Zeichenkette erscheinen.
Falls die Transformation einen Schemafehler auslöst, bestätige, dass die Spaltenanzahl des CSV-Quellschemas der Anzahl der Werte entspricht, die an jeden SumCSV-Aufruf übergeben werden. Alle Zeilen müssen die gleiche Anzahl von Spalten haben.