Let's Build: Dokumentenanalyse-Pipeline mit Transloadit

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande · Bio anzeigen

Erstellen Sie aus einem PDF- oder DOCX-Dokument eine lokale JSON-Datei mit Titel, Zusammenfassung und optionalen Erkenntnissen. Dieses Beispiel kombiniert Dokumentkonvertierung mit schemageleiteter KI-Extraktion. Sie gleichen das gespeicherte Ergebnis mit dem Original ab, bevor Sie es anderweitig verwenden.

Die TypeScript-Anwendung zum Herunterladen läuft außerhalb dieses Repositorys. Sie nimmt ein lokales Dokument entgegen, sendet es an Transloadit und einen KI-Anbieter und speichert die Antwort in einer neuen Ausgabedatei. Verwenden Sie beim ersten Durchlauf ein synthetisches oder unbedenkliches Dokument, das Sie hochladen dürfen. Die Verarbeitung ist kostenpflichtig, auch wenn Sie explizit die von Transloadit bereitgestellten KI-Testzugangsdaten auswählen.

Was Dokumentenanalyse wirklich bedeutet

Ein Dokumentenworkflow kann Text parsen, Seiten aufteilen und strukturierte Felder extrahieren. Das sind getrennte Vorgänge: Die hier vorgestellte Anwendung sendet PDFs direkt an /ai/chat und konvertiert DOCX-Dateien zuvor in PDF. Sie führt weder OCR durch noch teilt sie Dokumente in Abschnitte auf.

Das Ergebnis dient als Ausgangspunkt für die Prüfung oder Indexierung, nicht als Nachweis dafür, dass jede Angabe korrekt extrahiert wurde. Sein Schema beschreibt Erkenntnisse zum Dokument, keine Rechnungssummen, Rechnungspositionen oder Konfidenzwerte.

Ihr TypeScript-Projekt einrichten

Befolgen Sie die Installations- und Zugangsanleitung der Anwendung in einem leeren, eigenständigen Verzeichnis außerhalb eines bestehenden Node.js-Projekts oder Yarn-Workspaces. Sie benötigen weder einen privaten Checkout noch heruntergeladene Fixtures; Sie stellen Ihre eigene PDF- oder DOCX-Datei bereit. Die Shell-Beispiele verwenden Bash.

Die getestete Kombination besteht aus Node.js 26.12.1⁠, Yarn 4.12.0 über Corepack, @transloadit/node 4.14.0, zod 3.25.76 und zod-to-json-schema 3.25.2. Diese Versionsbindungen dienen der Reproduzierbarkeit und besagen nicht, dass es sich um die neuesten Releases handelt. Node 26 ist eine gepflegte Release-Linie⁠; berücksichtigen Sie Sicherheitsupdates, wenn Sie das Beispiel anpassen. Corepack ist unter Node 26 eine separate Voraussetzung: Folgen Sie der Installationsanleitung⁠, wenn corepack nicht verfügbar ist. Für die Downloads benötigen Sie außerdem cURL.

Die README installiert die Pakete in den festgelegten Versionen und lädt sowohl document-intelligence-pipeline/run.ts als auch shared/runtime.ts herunter. Lassen Sie diese beiden Verzeichnisse nebeneinander, da das Programm ../shared/runtime.ts importiert. Der abschließende Befehl --help sollte funktionieren, bevor Sie Zugangsdaten angeben. Schlägt die Einrichtung fehl, prüfen Sie das teilweise angelegte Verzeichnis vor einem erneuten Versuch: Beim anfänglichen Anlegen von package.json wird das Überschreiben einer Datei verweigert. Wiederholen Sie diesen Vorgang nicht in einer bestehenden Anwendung.

Konfigurieren Sie TRANSLOADIT_AUTH_KEY und TRANSLOADIT_AUTH_SECRET wie in der README beschrieben in der Shell, in der die Anwendung läuft. Damit authentifizieren Sie Ihren Transloadit-Workspace. Halten Sie diese Werte aus der Versionsverwaltung und aus Browsercode heraus. Das Programm liest Umgebungsvariablen des Prozesses und lädt keine Umgebungsdatei.

Den KI-Zugang wählen Sie separat. Setzen Sie entweder TRANSLOADIT_AI_CREDENTIALS auf den Namen eines bestehenden Zugangsdaten-Eintrags für KI, der einen Anthropic-Schlüssel enthält, oder geben Sie explizit --test-credentials an, um kostenpflichtige Testschlüssel von Transloadit zu verwenden. Wählen Sie einen Modus. Das Programm erstellt oder ändert keine Zugangsdaten; Informationen zu Anbieterzugang und Abrechnung finden Sie in der /ai/chat-Dokumentation.

Schritt 1: Dokumente mit OCR parsen (optional)

Der Robot /document/ocr ist hilfreich, wenn Ihr separater Workflow erkannten Text oder Layoutinformationen aus einer PDF-Datei benötigt. Diese Anwendung nutzt stattdessen die Unterstützung für PDF-Eingaben von anthropic/claude-sonnet-4-6, die im Extraktions-Step explizit ausgewählt wird.

Bei DOCX-Eingaben erzeugt der Robot /document/convert die PDF-Datei, die an das Modell gesendet wird. Konvertierung und OCR dienen unterschiedlichen Zwecken. Wenn Sie einen OCR-Step hinzufügen, müssen Sie entscheiden, wie dessen Ausgabe in Ihren eigenen Extraktionsworkflow einfließt.

Schritt 2: Dokumente aufteilen

Der Robot /document/split kann Seiten für einen anderen Workflow auswählen. Das folgende Beispiel verarbeitet eine ganze Datei. Wenn Sie einen Vertrag in unabhängige Anfragen aufteilen, können Definitionen oder Bedingungen anderer Seiten verloren gehen. Gehen Sie daher nicht davon aus, dass kombinierte Antworten zu einzelnen Seiten die Bedeutung des gesamten Dokuments wiedergeben.

Schritt 3: Schemagesteuerte Datenextraktion mit KI

Die Anwendung exportiert example und documentInsightsSchema. Verwenden Sie diese beim Prüfen oder Anpassen der Anwendung wieder, statt eine zweite Kopie der Verarbeitungskonfiguration oder des Schemas zu pflegen. Der Extraktions-Step nutzt format: 'json', ein serialisiertes JSON-Schema und result: true, um die Antwortdatei bereitzustellen.

title und summary sind erforderliche Strings. Optionale Felder sind author, publication_date, document_type, key_topics und key_points. Der Dokumenttyp ist, sofern vorhanden, einer der folgenden Werte: whitepaper, report, contract, invoice, receipt, statement oder manual. Ein optionales Feld darf fehlen; ein erforderlicher String kann trotzdem leer oder sachlich falsch sein. Die Schemavalidierung prüft die Struktur, nicht den Wahrheitsgehalt.

Eine vollständige Pipeline erstellen

Legen Sie ein Dokument unter document.pdf in Ihrem Projektverzeichnis ab oder ändern Sie --input auf den tatsächlichen Pfad. Wählen Sie einen beschreibbaren Ausgabepfad, der noch nicht existiert. Wenn die Workspace-Authentifizierung bereits konfiguriert und TRANSLOADIT_AI_CREDENTIALS nicht gesetzt ist, autorisiert dieser Befehl die kostenpflichtige Verarbeitung mit Testschlüsseln:

node document-intelligence-pipeline/run.ts --input ./document.pdf --output ./result.json --test-credentials

Für einen bestehenden Zugangsdaten-Eintrag für Anthropic-KI setzen Sie TRANSLOADIT_AI_CREDENTIALS wie oben beschrieben und lassen --test-credentials weg. Das Ausführungsprogramm akzeptiert eine nicht leere Eingabedatei mit höchstens 20 MiB und lädt höchstens 20 MiB an Ausgabedaten herunter. Diese Grenzen gelten für das Tutorial. Es räumt der Assembly fünf Minuten und dem separaten Ergebnisdownload 30 Sekunden ein. Aufgrund von Anbietergrenzen kann eine Datei auch innerhalb der lokalen Größenbegrenzung abgelehnt werden.

Bei Erfolg gibt das Terminal Saved gefolgt vom Ausgabepfad aus. Die Eingabe bleibt unverändert, und result.json ist eine lokale Datei statt einer temporären Ergebnis-URL. Eine vorhandene Ausgabedatei wird abgelehnt, bevor eine Assembly übermittelt wird. Verwenden Sie für aufeinanderfolgende Durchläufe ein anderes Ziel; löschen Sie Ihr bisheriges Ergebnis nicht nur, um einen Befehl zu wiederholen.

Speichern Sie dieses Prüfskript als inspect.ts neben package.json. Es liest die gespeicherte Ausgabe mit demselben exportierten Schema, weist leeren Pflichttext zurück und gibt die zwei Felder aus, die Sie prüfen sollten:

import { readFile } from 'node:fs/promises'

import { documentInsightsSchema } from './document-intelligence-pipeline/run.ts'

const saved = JSON.parse(await readFile('./result.json', 'utf8'))
const insights = documentInsightsSchema.parse(saved)
if (!insights.title.trim() || !insights.summary.trim()) {
  throw new Error('The title or summary is blank. Review the source and Assembly before retrying.')
}
console.log(insights.title)
console.log(insights.summary)

node inspect.ts

Gleichen Sie Namen, Daten, Mengen und die Kernaussagen der Zusammenfassung mit Ihrer Quelle ab. Aus einem Bericht über die Reparatur von 12 Fahrrädern mit Ersatzteilen für 240 $ darf keine Zusammenfassung über den Verkauf von Fahrrädern oder Ausgaben von 24 $ werden. Das Prüfskript kann Ihnen diese sachliche Beurteilung nicht abnehmen. Prüfen Sie auch optionale Felder in der JSON-Datei und halten Sie sensible Ergebnisse privat.

Wenn ein Durchlauf nach der Ausgabe einer Assembly ID fehlschlägt, prüfen Sie diese Assembly in der Console, bevor Sie es erneut versuchen. Ein Timeout oder eine Unterbrechung belegt nicht, dass die Verarbeitung auf dem Server gestoppt wurde. Auch ein fehlgeschlagener Durchlauf kann berechnet werden. Das Ausführungsprogramm deaktiviert SDK-Retries und entfernt nach einem abgefangenen Fehler seine unvollständige lokale Ausgabe. Nach einem erzwungenen Abbruch kann es die Bereinigung nicht garantieren. Prüfen Sie eine eventuell verbliebene Datei, bevor Sie ein neues Ziel wählen.

Mehrere Dokumenttypen verarbeiten

Das Ausführungsprogramm akzeptiert Dateinamen mit .pdf und .docx, auch mit großgeschriebenen Dateiendungen. Der Robot /file/filter leitet Dateien mit PDF-MIME-Typ direkt zur Extraktion weiter; der andere Zweig konvertiert zunächst in PDF. Dadurch wird nicht jedes andere Format als Eingabe für diese CLI akzeptiert. Das Umbenennen einer beschädigten Datei repariert deren Inhalt nicht, und eine erfolgreiche Konvertierung belegt nicht die Richtigkeit der Zusammenfassung.

Über Ergänzungen zum lokalen Beispiel entscheiden

Verarbeiten Sie Dokumente nacheinander mit unterschiedlichen Ausgabedateinamen, während Sie Ergebnisse und Kosten bewerten. Diese CLI hat weder einen Batch-Scheduler noch eine Warteschlange zur Prüfung oder einen Export in Cloud-Speicher. Prüfen Sie vor der Verarbeitung einer Sammlung die aktuellen Preise und die Robot-Dokumentation.

Templates können einen angepassten Satz von Assembly Instructions wiederverwendbar machen. Für diesen lokalen Durchlauf sind sie nicht erforderlich. Das Speichern der Verarbeitungskonfiguration in einem Template oder das Hinzufügen von Speicher sorgt allein weder für eine menschliche Prüfung noch für Zugriffskontrollen Ihrer Anwendung oder eine verlässliche Extraktionsrichtlinie.

Wann sich dieser Ansatz eignet

Dieser Ansatz ist hilfreich, wenn Sie die Konvertierungs- und Extraktions-Steps in einem Dateiworkflow selbst steuern möchten und die Anwendung darum herum bereitstellen können. Vergleichen Sie ein spezialisiertes Produkt für KI-Dokumentenanalyse anhand Ihrer eigenen Dokumente, wenn Sie eine fertige Prüfumgebung oder gemessene Extraktionsqualität benötigen. Dieses kleine Beispiel belegt weder Funktionsgleichheit noch Produktionsreife.

Bereit zum Entwickeln?

Beginnen Sie mit der README der Anwendung und einem unbedenklichen Dokument, dessen Inhalt Sie kennen. Bewahren Sie die gespeicherte JSON-Datei und Ihre Quelle zur Prüfung zusammen auf. Planen Sie anschließend mithilfe der Dokumentation zu KI-Robots mögliche Änderungen am Extraktionsworkflow.