Dateien mit OpenAI-Dateieingaben in Jitterbit Studio analysieren

Einführung

Die Chat Completions API von OpenAI unterstützt das direkte Senden von Dateiinhalten in einer Nachricht mithilfe von Dateieingaben: Die Datei wird base64-codiert und in die Nachricht als file-Inhaltselement mit einem Daten-URI (data:<media-type>;base64,<content>) eingebettet. Ein separates Hochladen zur Files API ist nicht erforderlich.

Bei reinen Textdateien wie CSV ist eine einfachere Alternative, den base64-Inhalt in eine lesbare Zeichenkette zu dekodieren und direkt in die Eingabeaufforderung einzubetten. In Kombination mit dem Code-Interpreter von OpenAI (verfügbar über die Responses API) kann das Modell den Dateiinhalt programmgesteuert analysieren und abfragen.

Beide Muster rufen die OpenAI API direkt mithilfe einer HTTP v2-Aktivität auf, die vollständige Kontrolle über die Anforderungstextstruktur bietet, die jeder Ansatz erfordert.

Diese Anleitung behandelt beide Muster, beginnend mit demselben Schritt: das Herunterladen einer Datei von einer externen API, deren Antworttext die Datei als base64-codierte Daten enthält.

Entwurfsmuster

Jeder Ansatz folgt dem Transformationsmuster:

Die GET-Aktivität lädt die Datei herunter, und die erste Transformation extrahiert ihren base64-codierten Inhalt in eine Variable. Ein Script dekodiert dann entweder den Inhalt (für Textdateien) oder bereitet ihn als Daten-URI vor (für Binärdateien). Die zweite Transformation erstellt den OpenAI-Anforderungstext, die POST-Aktivität sendet ihn, und die abschließende Transformation extrahiert die Antwort des Modells.

Teil 1: Datei herunterladen und base64-Inhalt extrahieren

Viele APIs geben Dateiinhalte als base64-codierte Zeichenkette im JSON-Antworttext zurück. Dieser Teil behandelt das Abrufen des Inhalts und das Speichern zur Verwendung in späteren Schritten.

HTTP v2-Verbindung und GET-Aktivität konfigurieren

Für die Einrichtung der HTTP v2-Verbindung und Authentifizierung siehe REST-API mithilfe des HTTP v2-Connectors aufrufen.

Konfigurieren Sie eine HTTP v2 GET-Aktivität, die die Datei von der Quell-API abruft. Legen Sie den URL-Pfad auf den Datei-Download-Endpunkt fest. Bei Bedarf kann eine Projektvariable verwendet werden, um die Datei-ID dynamisch zu übergeben.

base64-Inhalt extrahieren

Fügen Sie nach der GET-Aktivität eine Transformation hinzu. Ordnen Sie den JSON-Pfad, der die base64-Zeichenkette enthält, einem Script-Knoten zu, der sie in einer Variable speichert:

<trans>
$core.base64fileContent = json$response$responseItem$responseContent$;
</trans>

Ersetzen Sie den JSON-Pfad oben durch den aktuellen Pfad aus dem Antwortschema Ihrer API. Der Variablenname core.base64fileContent wird in den folgenden Schritten verwendet.

Teil 2: Textdatei durch Dekodieren und Einbetten ihres Inhalts analysieren

Für CSV und andere Textdateien dekodieren Sie den base64-Inhalt in eine lesbare Zeichenkette und betten sie in die Benutzernachricht ein. Das Modell sieht den Dateiinhalt als Teil der Eingabeaufforderung.

base64-Inhalt dekodieren

Fügen Sie nach der Extraktionstransformation einen Script-Schritt hinzu. Wenden Sie Base64Decode, BinaryToHex und HexToString nacheinander an, um die base64-Zeichenkette in lesbaren Text zu konvertieren:

$decodedFileContent = HexToString(BinaryToHex(Base64Decode($core.base64fileContent)));

Die drei-Funktions-Kette ist erforderlich, weil Base64Decode Binärdaten zurückgibt, BinaryToHex diese in einen Hex-String konvertiert und HexToString den Hex-String in lesbaren Text umwandelt. Wird BinaryToHex übersprungen, entsteht ein hex-kodierter String statt des ursprünglichen Textinhalts.

Prompt erstellen

Erstellen Sie den Prompt, indem Sie den dekodierten Inhalt inline einbetten. Für CSV-Parsing weisen Sie das Modell an, den Inhalt als RFC 4180 zu behandeln und genau anzugeben, was zurückgegeben werden soll:

$gpt_userPrompt = "Role: " + $newHire_jobTitle + ".\n"
    + "Below is CSV text. Use Python to parse it as RFC 4180.\n"
    + "Rules:\n"
    + "- First row contains headers.\n"
    + "- Return ONLY rows where the target column value is exactly 'Yes'.\n"
    + "- Return the matching values as a single comma-separated line.\n\n"
    + "CSV START\n"
    + $decodedFileContent + "\n"
    + "CSV END";

Passen Sie die Anweisungen an Ihre eigene Dateistruktur und Analyseziel an.

Anfragetransformation der Responses API konfigurieren

Verwenden Sie für strukturierte Datenparsing die Responses API (v1/responses) mit aktiviertem Code-Interpreter-Tool. Der Code-Interpreter bietet dem Modell eine Python-Ausführungsumgebung zum programmatischen Parsing von CSV-Dateien, statt sich auf Pattern Matching zu verlassen.

Fügen Sie eine Transformation hinzu, die den Request Body zuordnet. Das Anfrageschema der Responses API unterscheidet sich von Chat Completions: das Nachrichtenfeld heißt input, nicht messages.

Zum Aktivieren des Code-Interpreters fügen Sie [{"type":"code_interpreter"}] zum tools-Array im Request Body hinzu. Dies kann in einem Skript vor der Transformation erfolgen, indem Sie den vollständigen Request Body als JSON-String erstellen, oder durch Hinzufügen einer json/tools/item/type-Zuordnung mit dem Wert "code_interpreter".

Legen Sie im Skriptschritt vor dieser Transformation den URL-Pfad für den Responses-Endpunkt fest:

$openAi.url.path = "v1/responses";

Antwort lesen

Fügen Sie nach der POST-Aktivität eine Transformation hinzu, um die Antwort des Modells zu extrahieren. Bei der Responses API befindet sich der Ausgabetext in json$output$item.content$item.text$:

<trans>
$llm_response = json$output$item.content$item.text$;
</trans>

Teil 3: Binärdatei mit Inline-Dateidaten analysieren

Bei PDFs und anderen Binärdateien behalten Sie den Base64-Inhalt unverändert bei und betten ihn über einen Data-URI in das Message-Content-Array ein. Das Modell erhält die vollständige Datei zusammen mit dem Text-Prompt.

Prompt und Content-Variable vorbereiten

Fügen Sie einen Skriptschritt hinzu, um den Benutzer-Prompt zu setzen und den Base64-Inhalt der Variablen zuzuweisen, die die Request-Transformation verwendet:

$gpt_userPrompt_fileInputs = "Please analyze the attached document and provide a concise "
    + "summary of the candidate's professional background, key skills, and notable "
    + "achievements.";
$offerSigned_cv_base64 = $core.base64fileContent;

Dekodieren Sie den Base64-Inhalt nicht in diesem Schritt. Die Chat Completions API erwartet den Raw-Base64-String als Teil des Data-URIs.

Anfragetransformation von Chat Completions konfigurieren

Fügen Sie eine Transformation hinzu, die den Request Body zuordnet. Das content-Feld ist ein Array mit zwei Elementen: einem text-Element für den Prompt und einem file-Element für das Dokument.

Die item#1-Notation erstellt ein zweites Element im content-Array. Der file_data-Wert muss ein vollständiger Data-URI sein, nicht der Raw-Base64-String. Verwenden Sie application/pdf als MIME-Type für PDF-Dateien.

Legen Sie im Skriptschritt vor dieser Transformation den URL-Pfad zum Chat Completions-Endpunkt fest:

$openAi.url.path = "v1/chat/completions";

HTTP v2 POST-Aktivität zu OpenAI konfigurieren

Konfigurieren Sie eine HTTP v2 POST-Aktivität für die OpenAI API. Falls Sie bereits über eine OpenAI-Verbindung aus einem anderen Vorgang verfügen, verwenden Sie diese erneut. Andernfalls erstellen Sie eine neue Verbindung:

1. Setzen Sie Base URL auf https://api.openai.com oder referenzieren Sie eine Projektvariable.

2. Fügen Sie einen Bearer-Autorisierungsheader mit einer Projektvariable hinzu, die Ihren OpenAI-API-Schlüssel enthält (mit verstecktem Wert):

   Authorization: Bearer [openai_api_key]
   

3. Setzen Sie den Path der URL auf [openAi.url.path], damit der Vorgang zwischen Endpunkten mithilfe der Skriptvariable wechseln kann.

4. Setzen Sie Request Format und Response Format auf JSON.

Weitere Informationen zu Verbindungs- und Authentifizierungsschritten finden Sie unter Eine REST API mithilfe des HTTP v2-Connectors aufrufen.

Die Antwort auslesen

Fügen Sie eine Transformation nach der POST-Aktivität ein, um die Antwort des Modells zu extrahieren. Für die Chat Completions API befindet sich der generierte Text in json$choices$item.message$content$:

<trans>
$offerSigned_cvSummary = json$choices$item.message$content$;
</trans>

Die Integration verifizieren

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

2. Bestätigen Sie in den Vorgangslogs, dass die GET-Aktivität eine erfolgreiche Antwort zurückgegeben hat und die POST-Aktivität gegenüber OpenAI ebenfalls ohne Fehler abgeschlossen wurde.

3. Überprüfen Sie die Logausgabe, um zu bestätigen, dass die Antwortvariable (llm_response für den Textansatz, offerSigned_cvSummary für den Binäransatz) eine gültige KI-generierte Zusammenfassung enthält.

4. Wenn die POST-Aktivität mit einem 400 Bad Request fehlschlägt, überprüfen Sie, dass der Wert file_data mit data:application/pdf;base64, beginnt und dass die Base64-Zeichenfolge vollständig und nicht gekürzt ist.

5. Wenn der dekodierte Textinhalt verzerrt aussieht (für den Textansatz), bestätigen Sie, dass die vollständige Funktionskette mit drei Funktionen angewendet wird: HexToString(BinaryToHex(Base64Decode(...))). Wenn nur Base64Decode ohne die Konvertierungskette angewendet wird, werden Binärdaten zurückgegeben, kein lesbarer Text.