Let's Build: KI-Rechnungsparser mit Transloadit

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande ·

Wandeln Sie eine PDF-Rechnung in eine lokale JSON-Datei mit Lieferant, Rechnungsnummer, Währung und Beträgen um. Dieses Beispiel lädt Ihr Dokument zu Transloadit und einem KI-Anbieter hoch, validiert die zurückgegebenen Feldtypen und speichert das Ergebnis zum Abgleich mit der Originalrechnung.

Was wir entwickeln

Das Beispielskript akzeptiert eine nicht leere PDF- oder DOCX-Datei mit bis zu 20 MiB. PDFs gehen direkt an 🤖 /ai/chat; DOCX-Dateien werden zunächst mit 🤖 /document/convert in PDFs umgewandelt. Andere Eingabedateiendungen lehnt dieses Beispiel ab.

Dieses Tutorial zeigt die Extraktion mit lokal gespeichertem Ergebnis. Eine abgeschlossene Assembly und schemakonformes JSON belegen nicht, dass ein Betrag korrekt gelesen wurde. Prüfen Sie die Ausgabe, bevor Sie sie für Buchhaltung oder Zahlungen verwenden; das Schema liefert keine Konfidenzwerte zurück.

Zuerst das Schema (zod)

Das herunterladbare Programm exportiert sein Zod-Schema. Wenn Sie die unten beschriebene Dateistruktur beim Download beibehalten, können Sie es in Ihren eigenen TypeScript-Code importieren, statt eine zweite Feldliste zu pflegen:

import { zodToJsonSchema } from 'zod-to-json-schema'

import { invoiceSchema } from './invoice-parser/run.ts'

const invoiceJsonSchema = zodToJsonSchema(invoiceSchema)

Die Felder umfassen Lieferantendaten, Rechnungs- und Fälligkeitsdatum, Währung, Zwischensumme, Steuer, Gesamtsumme, Rechnungspositionen, Zahlungsbedingungen und eine Bestellung. Sie sind optional, damit das Modell unbekannte Werte auslassen kann. Das Ausführungsprogramm lehnt fehlerhaftes JSON, ungültige Feldtypen und Objekte ohne erkannte Felder ab. Eine plausible, aber falsche Gesamtsumme kann diese Prüfungen dennoch bestehen.

Überblick über die Pipeline

PDF  → /ai/chat → JSON download → local validation → result.json
DOCX → /document/convert (PDF) → /ai/chat → JSON download → local validation → result.json

Das Programm wählt explizit anthropic/claude-sonnet-4-6, ein PDF-fähiges Modell, das von /ai/chat unterstützt wird. Es lädt die Antwort von der Ergebnis-URL herunter und speichert die validierten Daten lokal. So können Sie die Datei auch nach Ablauf dieser temporären URL prüfen.

Assembly-Ausschnitt

Die exportierte Konfiguration liefert die vollständigen Assembly Instructions. Dieser Ausschnitt erstellt die Anweisungen, ohne eine Anfrage zu senden:

import { example } from './invoice-parser/run.ts'

const instructions = {
  steps: example.steps({ test_credentials: true }),
}

Der Step zur Extraktion verwendet format: 'json', ein serialisiertes JSON-Schema und result: true. Die CLI übernimmt Upload, Abschlussprüfung, Ergebnisdownload und lokale Validierung. Die Auswahl von test_credentials: true verwendet kostenpflichtige KI-Zugangsdaten, die Transloadit bereitstellt; die Verarbeitung wird dadurch nicht kostenlos.

Beispielanwendung ausprobieren

Verwenden Sie ein leeres Verzeichnis außerhalb eines bestehenden Node-Projekts. Installieren Sie Node.js und cURL sowie Corepack separat. Die getestete Laufzeit ist Node.js 26.12.1; verwenden Sie eine weiterhin gepflegte Version von Node 26, wenn Sie das Beispiel anpassen. Die Einrichtungsanleitung verwendet Yarn 4.12.0, um @transloadit/node 4.14.0, Zod 3.25.76 und zod-to-json-schema 3.25.2 zu installieren. Diese festgelegten Versionen reproduzieren die Kombination aus SDK und Schemakonverter des herunterladbaren Beispiels. Sie sind weder als neueste Versionen ausgewiesen noch eine Aufforderung, eine bestehende Anwendung auf ältere Versionen umzustellen.

Folgen Sie zuerst den Installations- und Zugriffseinstellungen in dieser README und führen Sie die Befehle einzeln aus. Laden Sie sowohl invoice-parser/run.ts als auch shared/runtime.ts herunter und behalten Sie deren relative Dateistruktur bei. Führen Sie die dokumentierte Prüfung mit --help aus, bevor Sie etwas hochladen. Falls eine Installation oder ein Download fehlschlägt, halten Sie an und beheben Sie das Problem, bevor Sie den Parser ausführen.

Exportieren Sie den Auth Key und das Auth Secret für Ihren Workspace als TRANSLOADIT_AUTH_KEY und TRANSLOADIT_AUTH_SECRET in derselben Shell. Das Skript liest diese Umgebungsvariablen; es lädt keine Umgebungsdatei und erstellt keine Zugangsdaten. Halten Sie sensible Zugangsdaten aus der Versionsverwaltung und aus Browsercode heraus.

Lassen Sie TRANSLOADIT_AI_CREDENTIALS ungesetzt und legen Sie eine Rechnung, die Sie hochladen dürfen, unter invoice.pdf ab. Wählen Sie einen noch nicht vorhandenen Zielpfad und führen Sie dann Folgendes aus:

node invoice-parser/run.ts --input ./invoice.pdf --output ./result.json --test-credentials

Dieser Befehl autorisiert explizit die Verwendung kostenpflichtiger KI-Testzugangsdaten sowie die Verarbeitung durch Transloadit. Um stattdessen Ihren eigenen Anthropic-Schlüssel zu verwenden, konfigurieren Sie in der Console einen Zugangsdaten-Eintrag für KI, exportieren Sie dessen vorhandenen Namen als TRANSLOADIT_AI_CREDENTIALS und lassen Sie --test-credentials weg. Wählen Sie genau einen Modus für die Anbieterzugangsdaten. Prüfen Sie die Preise, bevor Sie mehrere Rechnungen verarbeiten.

Das Ausführungsprogramm lässt die Eingabe unverändert und lehnt eine bereits vorhandene Ausgabedatei ab, bevor es eine Assembly übermittelt. Verwenden Sie für einen weiteren Durchlauf einen neuen Dateinamen. Die Grenzen dieses Tutorials sind 20 MiB für Eingabe und heruntergeladene Ausgabe, fünf Minuten für die Verarbeitung und 30 Sekunden für den Ergebnisdownload. Dies sind keine Produktgrenzen. Falls die Ausführung nach Ausgabe einer Assembly ID fehlschlägt, prüfen Sie diese Assembly in der Console, bevor Sie es erneut versuchen: Eine Zeitüberschreitung oder Unterbrechung belegt nicht, dass die Verarbeitung auf dem Server gestoppt wurde, und auch eine fehlgeschlagene Ausführung kann berechnet werden. Das Ausführungsprogramm führt eine Assembly nicht automatisch erneut aus.

Beispieleingaben

Beginnen Sie mit einer synthetischen Rechnung, deren Felder Sie unabhängig überprüfen können. Eine Rechnung von Sample Workshop Ltd mit der Nummer INV-2026-0042, zwei Fahrradreparaturen zu jeweils 100 USD und 20 USD Steuer sollte beispielsweise mindestens diese Werte liefern:

{
  "vendor_name": "Sample Workshop Ltd",
  "invoice_number": "INV-2026-0042",
  "currency": "USD",
  "subtotal": 200,
  "tax": 20,
  "total": 220
}

Öffnen Sie nach einer erfolgreichen Ausführung result.json in einem Texteditor. Vergleichen Sie Lieferant, Rechnungsnummer, Währung, Rechnungspositionen und Beträge mit Ihrer tatsächlichen Eingabe; unterschiedliche Rechnungen sollten unterschiedliche Daten liefern. Ein fehlendes Feld muss geprüft werden, auch wenn die Datei erfolgreich gespeichert wurde. Halten Sie das Ergebnis vertraulich, wenn es geschäftliche oder personenbezogene Informationen enthält.

Nächste Schritte

Bevor Sie Ergebnisse in Ihrer Datenbank speichern, legen Sie fest, welche Felder Ihre Anwendung benötigt, und leiten Sie fehlende oder abweichende Werte zur menschlichen Prüfung weiter. Trennen Sie die Währungsumrechnung von der Extraktion: Die zurückgegebene Währung und die Beträge beschreiben die Originalrechnung, keine vereinheitlichten Buchungseinträge.